1
1
---
2
- title : 在 Stage 中查询 NDJSON 文件
2
+ title : 查询暂存区中的 NDJSON 文件
3
3
sidebar_label : NDJSON
4
4
---
5
5
6
- ## 查询 Stage 中的 NDJSON 文件
6
+ 在 Databend 中,你可以直接查询存储在暂存区(Stage)中的 NDJSON 文件,而无需先将数据加载到表中。这种方法对于数据探索、ETL 处理和即席分析等场景特别有用。
7
+
8
+ ## 什么是 NDJSON?
9
+
10
+ NDJSON(Newline Delimited JSON,换行符分隔的 JSON)是一种基于 JSON 的文件格式,其中每一行都包含一个完整且有效的 JSON 对象。这种格式特别适合流式数据处理和大数据分析。
11
+
12
+ ** NDJSON 文件内容示例:**
13
+ ``` json
14
+ {"id" : 1 , "title" : " Database Fundamentals" , "author" : " John Doe" , "price" : 45.50 , "category" : " Technology" }
15
+ {"id" : 2 , "title" : " Machine Learning in Practice" , "author" : " Jane Smith" , "price" : 68.00 , "category" : " AI" }
16
+ {"id" : 3 , "title" : " Web Development Guide" , "author" : " Mike Johnson" , "price" : 52.30 , "category" : " Frontend" }
17
+ ```
18
+
19
+ ** NDJSON 的优势:**
20
+ - ** 流式友好** :可以逐行解析,无需将整个文件加载到内存中。
21
+ - ** 兼容大数据** :广泛用于日志文件、数据导出和 ETL Pipeline。
22
+ - ** 易于处理** :每一行都是一个独立的 JSON 对象,支持并行处理。
23
+
24
+ ## 查询暂存区中的 NDJSON 文件
7
25
8
26
语法:
9
27
``` sql
10
- SELECT [< 别名 > .]$1 :< 列名 > [, $1 :< 列名 > ...]
11
- FROM {@< stage名称 > [/ < 路径 > ] [< 表别名 > ] | ' <uri>' [< 表别名 > ]}
28
+ SELECT [< alias > .]$1 :< column > [, $1 :< column > ...]
29
+ FROM {@< stage_name > [/ < path > ] [< table_alias > ] | ' <uri>' [< table_alias > ]}
12
30
[(
13
- [< 连接参数 > ],
14
- [ PATTERN => ' <正则表达式 >' ],
15
- [ FILE_FORMAT => ' NDJSON| <自定义格式名称 >' ],
16
- [ FILES => ( ' <文件名 >' [ , ' <文件名 >' ] [ , ... ] ) ]
31
+ [< connection_parameters > ],
32
+ [ PATTERN => ' <regex_pattern >' ],
33
+ [ FILE_FORMAT => ' NDJSON| <custom_format_name >' ],
34
+ [ FILES => ( ' <file_name >' [ , ' <file_name >' ] [ , ... ] ) ]
17
35
)]
18
36
```
19
37
20
38
21
39
:::info 提示
22
40
** 查询返回内容说明:**
23
41
24
- * ** 返回格式** :每行作为单个 variant 对象(引用为 ` $1 ` )
25
- * ** 访问方式 ** :使用路径表达式 ` $1:列名 `
26
- * ** 示例** :` SELECT $1:title, $1:author FROM @stage名称 `
27
- * ** 关键特性 ** :
28
- * 必须使用路径表示法访问特定字段
29
- * 类型转换需显式声明 (例如 ` CAST($1:id AS INT) ` )
30
- * 每行 NDJSON 被解析为完整 JSON 对象
31
- * 整行数据表示为单个 variant 对象
42
+ * ** 返回格式** :每一行作为一个单独的 VARIANT 对象(通过 ` $1 ` 引用)。
43
+ * ** 访问方法 ** :使用路径表达式 ` $1:column_name ` 。
44
+ * ** 示例** :` SELECT $1:title, $1:author FROM @stage_name ` 。
45
+ * ** 主要特性 ** :
46
+ * 必须使用路径表示法来访问特定字段。
47
+ * 对于特定类型的操作,需要进行类型转换 (例如, ` CAST($1:id AS INT) ` )。
48
+ * 每一行 NDJSON 都被解析为一个完整的 JSON 对象。
49
+ * 整行数据表示为一个单独的 VARIANT 对象。
32
50
:::
33
51
34
52
## 教程
35
53
36
- ### 步骤 1. 创建外部 Stage
54
+ ### 步骤 1. 创建外部暂存区
37
55
38
- 在存储 NDJSON 文件的 S3 存储桶中创建外部 stage,需配置访问凭证 。
56
+ 使用你自己的 S3 存储桶和凭证创建一个外部暂存区,你的 NDJSON 文件存储在该位置 。
39
57
``` sql
40
58
CREATE STAGE ndjson_query_stage
41
59
URL = ' s3://load/ndjson/'
42
60
CONNECTION = (
43
- ACCESS_KEY_ID = ' <您的访问密钥ID >'
44
- SECRET_ACCESS_KEY = ' <您的秘密访问密钥 >'
61
+ ACCESS_KEY_ID = ' <your-access-key-id >'
62
+ SECRET_ACCESS_KEY = ' <your-secret-access-key >'
45
63
);
46
64
```
47
65
@@ -53,10 +71,12 @@ CREATE FILE FORMAT ndjson_query_format
53
71
COMPRESSION = AUTO;
54
72
```
55
73
56
- - 更多 NDJSON 文件格式选项参见 [ NDJSON 文件格式选项] ( /sql/sql-reference/file-format-options#ndjson-options )
74
+ - 更多 NDJSON 文件格式选项,请参考 [ NDJSON 文件格式选项] ( /sql/sql-reference/file-format-options#ndjson-options )
57
75
58
76
### 步骤 3. 查询 NDJSON 文件
59
77
78
+ 现在你可以直接从暂存区查询 NDJSON 文件。此示例从每个 JSON 对象中提取 ` title ` 和 ` author ` 字段:
79
+
60
80
``` sql
61
81
SELECT $1 :title, $1 :author
62
82
FROM @ndjson_query_stage
@@ -66,7 +86,15 @@ FROM @ndjson_query_stage
66
86
);
67
87
```
68
88
69
- 若 NDJSON 文件采用 gzip 压缩,可使用以下查询:
89
+ ** 说明:**
90
+ - ` $1:title ` 和 ` $1:author ` :从 JSON 对象中提取特定字段。` $1 ` 代表整个 JSON 对象(作为一个 VARIANT),` :字段名 ` 用于访问单个字段。
91
+ - ` @ndjson_query_stage ` :引用在步骤 1 中创建的外部暂存区。
92
+ - ` FILE_FORMAT => 'ndjson_query_format' ` :使用在步骤 2 中定义的自定义文件格式。
93
+ - ` PATTERN => '.*[.]ndjson' ` :匹配所有以 ` .ndjson ` 结尾的文件的正则表达式模式。
94
+
95
+ ### 查询压缩文件
96
+
97
+ 如果 NDJSON 文件使用 gzip 进行了压缩,请修改模式以匹配压缩文件:
70
98
71
99
``` sql
72
100
SELECT $1 :title, $1 :author
@@ -76,9 +104,11 @@ FROM @ndjson_query_stage
76
104
PATTERN => ' .*[.]ndjson[.]gz'
77
105
);
78
106
```
79
- ### 带元数据的查询
80
107
81
- 直接从 stage 查询 NDJSON 文件,包含 ` METADATA$FILENAME ` 和 ` METADATA$FILE_ROW_NUMBER ` 等元数据列:
108
+ ** 主要区别:** 模式 ` .*[.]ndjson[.]gz ` 匹配以 ` .ndjson.gz ` 结尾的文件。由于文件格式中设置了 ` COMPRESSION = AUTO ` ,Databend 会在查询执行期间自动解压 gzip 文件。
109
+ ### 带元数据查询
110
+
111
+ 你还可以在查询中包含文件元数据,这对于跟踪数据血缘和调试非常有用:
82
112
83
113
``` sql
84
114
SELECT
@@ -90,4 +120,20 @@ FROM @ndjson_query_stage
90
120
FILE_FORMAT => ' ndjson_query_format' ,
91
121
PATTERN => ' .*[.]ndjson'
92
122
);
93
- ```
123
+ ```
124
+
125
+ ** 元数据列说明:**
126
+ - ` METADATA$FILENAME ` :显示每行数据来自哪个文件——在查询多个文件时非常有用。
127
+ - ` METADATA$FILE_ROW_NUMBER ` :显示源文件中的行号——有助于跟踪特定记录。
128
+
129
+ ** 使用场景:**
130
+ - ** 数据血缘** :跟踪每条记录来自哪个源文件。
131
+ - ** 调试** :通过文件和行号识别有问题的记录。
132
+ - ** 增量处理** :只处理特定的文件或文件中的特定范围。
133
+
134
+ ## 相关文档
135
+
136
+ - [ 加载 NDJSON 文件] ( ../03-load-semistructured/03-load-ndjson.md ) - 如何将 NDJSON 数据加载到表中
137
+ - [ NDJSON 文件格式选项] ( /sql/sql-reference/file-format-options#ndjson-options ) - 完整的 NDJSON 格式配置
138
+ - [ CREATE STAGE] ( /sql/sql-commands/ddl/stage/ddl-create-stage ) - 管理外部和内部暂存区
139
+ - [ 查询元数据] ( ./04-querying-metadata.md ) - 关于元数据列的更多详细信息
0 commit comments