Skip to content

Commit 739971c

Browse files
committed
docs: add examples for streaming load column mapping
1 parent 59c46be commit 739971c

File tree

2 files changed

+44
-0
lines changed

2 files changed

+44
-0
lines changed

docs/cn/guides/20-self-hosted/04-references/http-streaming-load.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,34 @@ X-Databend-SQL: insert into demo.people(name,age,city) values (?, ?, 'BJ') from
5656
### 列映射规则
5757

5858
- **不写列清单,也不写 `VALUES`**:按表的列定义顺序写入(文件字段依次对应表列)。
59+
- CSV 表头:`id,name,age`
60+
- SQL:
61+
```text
62+
X-Databend-SQL: insert into demo.people from @_databend_load file_format=(type=csv skip_header=1)
63+
```
5964
- **写了列清单,但不写 `VALUES`**:按列清单的顺序写入(文件字段依次对应列清单)。
65+
- CSV 表头:`id,name`
66+
- SQL:
67+
```text
68+
X-Databend-SQL: insert into demo.people(id,name) from @_databend_load file_format=(type=csv skip_header=1)
69+
```
6070
- **写了列清单且写 `VALUES`**:
6171
- 每个目标列对应 `VALUES` 中的一个表达式。
6272
- `VALUES` 里的每个 `?` 会依次消费上传文件里的一个字段。
73+
- CSV 表头:`name,age`
74+
- SQL:
75+
```text
76+
X-Databend-SQL: insert into demo.people(name,age,city) values (?, ?, 'BJ') from @_databend_load file_format=(type=csv skip_header=1)
77+
```
6378
- **未提供的列**:
6479
- 如果该列有 `DEFAULT`,则使用默认值;
6580
- 否则写入 `NULL`(若列是 `NOT NULL` 则会失败)。
81+
- **只读取 CSV 的部分字段(忽略多余字段)**:
82+
- 默认情况下,如果文件字段数多于目标列清单,会直接报错。
83+
- 如需忽略多余字段,设置 `error_on_column_count_mismatch=false`:
84+
```text
85+
X-Databend-SQL: insert into demo.people(id,name) from @_databend_load file_format=(type=csv skip_header=1 error_on_column_count_mismatch=false)
86+
```
6687
6788
**cURL 模板:**
6889
@@ -96,6 +117,7 @@ CSV 的解析规则通过 `FILE_FORMAT=(...)` 指定,语法与 Databend 的文
96117
- `field_delimiter=','`:字段分隔符(默认 `,`)。
97118
- `quote='\"'`:引用符号。
98119
- `record_delimiter='\n'`:行分隔符。
120+
- `error_on_column_count_mismatch=false`:允许列数不匹配并忽略多余字段。
99121

100122
示例:
101123

docs/en/guides/20-self-hosted/04-references/http-streaming-load.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,34 @@ X-Databend-SQL: insert into demo.people(name,age,city) values (?, ?, 'BJ') from
5656
### Column mapping rules
5757

5858
- **No column list, no `VALUES`**: file fields map to table columns by table definition order.
59+
- CSV header: `id,name,age`
60+
- SQL:
61+
```text
62+
X-Databend-SQL: insert into demo.people from @_databend_load file_format=(type=csv skip_header=1)
63+
```
5964
- **With column list, no `VALUES`**: file fields map to the listed columns in order.
65+
- CSV header: `id,name`
66+
- SQL:
67+
```text
68+
X-Databend-SQL: insert into demo.people(id,name) from @_databend_load file_format=(type=csv skip_header=1)
69+
```
6070
- **With column list and `VALUES`**:
6171
- Each target column gets the corresponding expression in `VALUES`.
6272
- Each `?` consumes one field from the uploaded file, in order.
73+
- CSV header: `name,age`
74+
- SQL:
75+
```text
76+
X-Databend-SQL: insert into demo.people(name,age,city) values (?, ?, 'BJ') from @_databend_load file_format=(type=csv skip_header=1)
77+
```
6378
- **Columns not provided**:
6479
- Use column `DEFAULT` value if defined.
6580
- Otherwise insert `NULL` (and fail if the column is `NOT NULL`).
81+
- **Read only part of a CSV (ignore extra fields)**:
82+
- By default, Databend errors if the file has more fields than the target column list.
83+
- To ignore extra fields, set `error_on_column_count_mismatch=false`:
84+
```text
85+
X-Databend-SQL: insert into demo.people(id,name) from @_databend_load file_format=(type=csv skip_header=1 error_on_column_count_mismatch=false)
86+
```
6687
6788
**cURL template:**
6889
@@ -102,6 +123,7 @@ Common CSV options:
102123
- `field_delimiter=','`: Use a custom delimiter (default is `,`).
103124
- `quote='\"'`: Quote character.
104125
- `record_delimiter='\n'`: Line delimiter.
126+
- `error_on_column_count_mismatch=false`: Allow column count mismatch and ignore extra fields.
105127

106128
Examples:
107129

0 commit comments

Comments
 (0)