diff --git a/docs/cn/guides/40-load-data/00-stage/00-what-is-stage.md b/docs/cn/guides/40-load-data/00-stage/00-what-is-stage.md index bca50b2289..d679935681 100644 --- a/docs/cn/guides/40-load-data/00-stage/00-what-is-stage.md +++ b/docs/cn/guides/40-load-data/00-stage/00-what-is-stage.md @@ -80,6 +80,10 @@ LIST @~; 读取、列出、删除或检查 Stage 文件的命令和函数可以使用 `PATTERN` 按正则表达式过滤文件。对于 Stage 路径，`PATTERN` 匹配的是 `@[/]` 之后的文件路径部分，而不是完整的 Stage URI。 +:::note +Glob 模式（如 `ontime_200{6,7,8}.csv` 或 `ontime_200[6-8].csv`）仅支持基于 HTTP 的外部位置的文件路径。S3 等对象存储不支持文件路径中的 glob 展开——请改用 `PATTERN` 配合正则表达式。 +::: + 例如，对于 `@sales_stage/raw/`，Stage 文件 `@sales_stage/raw/year=2025/month=01/sales_20250101.parquet` 会作为 `year=2025/month=01/sales_20250101.parquet` 进行匹配： ```sql diff --git a/docs/cn/guides/40-load-data/01-load/00-stage.md b/docs/cn/guides/40-load-data/01-load/00-stage.md index 869bd94924..4300b1dea4 100644 --- a/docs/cn/guides/40-load-data/01-load/00-stage.md +++ b/docs/cn/guides/40-load-data/01-load/00-stage.md @@ -87,9 +87,14 @@ CREATE STAGE my_internal_stage; ```sql SHOW STAGES; -name |stage_type|number_of_files|creator |comment| ------------------+----------+---------------+----------+-------+ -my_internal_stage|Internal | 0|'root'@'%'| | +╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +│ String │ String │ Nullable(String) │ Nullable(String) │ Nullable(String) │ Boolean │ Boolean │ Nullable(Variant) │ Variant │ Nullable(String) │ Timestamp │ String │ Nullable(String) │ +├───────────────────┼────────────┼──────────────────┼──────────────────┼──────────────────┼─────────────────┼───────────────────────┼───────────────────┼──────────────────────┼──────────────────┼─────────────┼─────────┼──────────────────┤ +│ my_internal_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":"Zst… │ 'root'@'%' │ 2026-06-16 │ │ account_admin │ +│ │ │ │ │ │ │ │ │ │ │ 22:21:19… │ │ │ +╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ + ``` ### 步骤 2：上传示例文件 @@ -166,9 +171,9 @@ CREATE STAGE my_external_stage ```sql SHOW STAGES; -name |stage_type|number_of_files|creator |comment| ------------------+----------+---------------+------------------+-------+ -my_external_stage|External | |'root'@'%'| | +name |stage_type|creator |comment| +-----------------+----------+------------------+-------+ +my_external_stage|External |'root'@'%'| | ``` ### 步骤 2：上传示例文件 diff --git a/docs/cn/sql-reference/00-sql-reference/50-file-format-options.md b/docs/cn/sql-reference/00-sql-reference/50-file-format-options.md index a9bab4f604..7dbc119a42 100644 --- a/docs/cn/sql-reference/00-sql-reference/50-file-format-options.md +++ b/docs/cn/sql-reference/00-sql-reference/50-file-format-options.md @@ -20,15 +20,21 @@ Databend 支持多种文件格式用于数据导入与导出。本页介绍支 ``` :::note -- 从 Databend `v1.2.890-nightly` 开始，`TEXT` 可作为 `TSV` 的别名使用。 +- 从 Databend `v1.2.891-nightly` 开始，`TEXT` 可作为 `TSV` 的别名使用。 - 较旧版本的 Server 可能不支持 `TYPE = TEXT`，因此本页在语法和示例中仍以 `TSV` 为主，以兼容不同版本。 -- 如果你的环境只面向 Databend `v1.2.890-nightly` 及之后版本，新的配置更推荐使用 `TYPE = TEXT`。 +- 如果你的环境只面向 Databend `v1.2.891-nightly` 及之后版本，新的配置更推荐使用 `TYPE = TEXT`。 ::: +Databend 按如下优先级确定 COPY 或 Select 语句使用的文件格式： +1. 首先，检查语句中是否显式指定了 FILE_FORMAT。 +2. 如果语句中未指定 FILE_FORMAT，则使用创建 Stage 时为其定义的文件格式。 +3. 如果创建 Stage 时也未定义文件格式，Databend 默认使用 PARQUET 格式。 + +:::note - Databend 目前仅支持 ORC 和 AVRO 作为数据源。尚不支持将数据导出到 ORC 或 AVRO 文件中。 - Databend 目前仅支持将 LANCE 用作导出目标。`COPY INTO ` 写出的不是单个文件，而是一个 Lance 数据集目录，因此更适合由 Lance 工具链消费，而不是在 Databend 中直接作为 Stage 文件查询或通过 `COPY INTO ` 重新加载。 -- 如果在执行 COPY INTO 或 SELECT 操作时未指定 FILE_FORMAT，Databend 将使用您在最初创建 Stage 时为该 Stage 定义的文件格式。如果您在创建 Stage 期间未显式指定文件格式，Databend 默认使用 PARQUET 格式。如果您指定的 FILE_FORMAT 与创建 Stage 时定义的 FILE_FORMAT 不同，Databend 将优先使用操作期间指定的 FILE_FORMAT。 - 有关在 Databend 中管理自定义文件格式的信息，请参阅 [文件格式](../10-sql-commands/00-ddl/13-file-format/index.md)。 +::: ### formatTypeOptions @@ -45,20 +51,17 @@ formatTypeOptions ::= ROW_TAG = '' COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | XZ | NONE ``` - ## CSV 选项 -Databend 支持符合 [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) 标准的 CSV 文件，并遵循以下规则： +Databend CSV 符合 [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) 标准，并遵循以下规则： -- 如果字符串包含 [QUOTE](#quote)、[ESCAPE](#escape)、[RECORD_DELIMITER](#record_delimiter) 或 [FIELD_DELIMITER](#field_delimiter) 的字符，则必须引用该字符串。 -- 除了 [QUOTE](#quote) 之外，在带引号的字符串中不会转义任何字符。 +- 如果字符串包含 [QUOTE](#quote)、[ESCAPE](#escape)、[RECORD_DELIMITER](#record_delimiter) 或 [FIELD_DELIMITER](#field_delimiter) 的字符，则必须加引号。 +- 在带引号的字符串中，除了 [QUOTE](#quote) 之外不会转义任何字符。 - [FIELD_DELIMITER](#field_delimiter) 和 [QUOTE](#quote) 之间不应留有空格。 -- 如果字符串来自序列化的 Array 或 Struct 字段，则将在 CSV 中引用该字符串。 -- 如果您开发了一个程序并从中生成 CSV 文件，Databend 建议使用该编程语言中的 CSV 库。 ### RECORD_DELIMITER -分隔输入文件中的记录。 +分隔文件中记录的分隔字符。 **可用值**: @@ -70,82 +73,160 @@ Databend 支持符合 [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) 标准 ### FIELD_DELIMITER -分隔记录中的字段。 +分隔记录中字段的分隔字符。 **可用值**: - 一个字节的非字母数字字符，例如 `#` 和 `|`。 - 带有转义字符的字符：`\b`、`\f`、`\r`、`\n`、`\t`、`\0`、`\xHH` -**默认值**: `,` (逗号) +**默认值**: `,`（逗号） + +### QUOTE（仅导入） -### QUOTE (仅导入) +用于引用值的字符。 -引用 CSV 文件中的字符串。对于数据导入，除非字符串包含 [QUOTE](#quote)、[ESCAPE](#escape)、[RECORD_DELIMITER](#record_delimiter) 或 [FIELD_DELIMITER](#field_delimiter) 的字符，否则不需要引号。 +对于数据导入，除非字符串包含 [QUOTE](#quote仅导入)、[ESCAPE](#escape)、[RECORD_DELIMITER](#record_delimiter) 或 [FIELD_DELIMITER](#field_delimiter) 的字符，否则不需要引号。 -**可用值**: `'`、`"` 或 `(反引号) +**可用值**: `'\''`、`'"'` 或 ``'`'``（反引号） -**默认值**: `"` +**默认值**: `'"'` ### ESCAPE -转义带引号的字符串中的引号。 +用于在带引号的值中转义引号字符的字符，除了 [QUOTE](#quote仅导入) 自身（双引号转义）之外的额外转义方式。 -**可用值**: `'\\'` 或 `''` +在某些 CSV 变体中，引号使用特殊转义字符（如 `\`）来转义，而不是通过重复引号。 + +**可用值**: `'\\'` 或 `''`（空，表示仅使用双引号转义） **默认值**: `''` -### SKIP_HEADER (仅导入) +### SKIP_HEADER（仅导入） -指定从文件开头跳过的行数。 +从文件开头跳过的行数。 **默认值**: `0` -### NAN_DISPLAY (仅导入) +### TRIM_SPACE（仅导入） + +在类型转换之前，去除每个字段值的前导和尾随 ASCII 空白字符。 + +去除的字符集固定为 ASCII 空白：空格、制表符、LF、CR、VT、FF。 + +对于 CSV，去除发生在 csv-core 提取字段之后，因此带引号字段的内容也会被去除。 + +**默认值**: `false` -指定如何在查询结果中显示 "NaN"（非数字）值。 +### OUTPUT_HEADER（仅导出） + +在导出数据时包含列名标题行。 + +**默认值**: `false` + +### QUOTE_STYLE（仅导出） + +控制 CSV 输出时字段的引号策略。 + +| 可用值 | 描述 | +|---------------------------|--------------------------------------------------------------| +| `QUOTE_NOT_NULL`（默认） | 对每个非 NULL 字段加引号。 | +| `QUOTE_MINIMAL` | 仅在 CSV 格式需要时才对字段加引号。 | + +**默认值**: `QUOTE_NOT_NULL` + +### NAN_DISPLAY + +表示 "NaN"（非数字）的字符串。 **可用值**: 必须是文字 `'nan'` 或 `'null'`（不区分大小写） **默认值**: `'NaN'` -### NULL_DISPLAY (仅导入) +### NULL_DISPLAY -指定如何在查询结果中显示 NULL 值。 +表示 NULL 值的字符串。 + +导入数据时，未加引号的匹配值始终转为 NULL；加引号的匹配值仅在 `ALLOW_QUOTED_NULLS=true` 时转为 NULL。 **默认值**: `'\N'` -### ERROR_ON_COLUMN_COUNT_MISMATCH (仅导入) +### ALLOW_QUOTED_NULLS（仅导入） + +允许将带引号的字符串转换为 NULL 值。 -ERROR_ON_COLUMN_COUNT_MISMATCH 是一个布尔选项，当设置为 true 时，指定如果数据文件中的列数与目标表中的列数不匹配，则应引发错误。将其设置为 true 有助于确保加载过程中的数据完整性和一致性。 +仅当此选项为 true 时，匹配 `NULL_DISPLAY` 的带引号字符串才会被转为 NULL。未加引号的匹配值无论此选项如何都会转为 NULL。 + +**默认值**: `false` + +### ERROR_ON_COLUMN_COUNT_MISMATCH（仅导入） + +如果数据文件中的列数与目标表的列数不匹配，则返回错误。 **默认值**: `true` -### EMPTY_FIELD_AS (仅导入) +### EMPTY_FIELD_AS（仅导入） + +未加引号的空字段（即 `,,`）被转换为的值。 + +| 可用值 | 转换为 | +|------------------|-----------------------------------------------------------------------| +| `NULL` | `NULL`。如果列不可为空则报错。 | +| `STRING` | 对于 String 列：`''`。
对于其他列：`NULL`。如果不可为空则报错。 | +| `FIELD_DEFAULT` | 列的默认值。 | + +**默认值**: `NULL` -指定在 CSV 数据导入到表中时，遇到空字段（包括 `,,` 和 `,"",`）时应使用的值。 +### QUOTED_EMPTY_FIELD_AS（仅导入） -| 可用值 | 描述 | -|------------------|-----------------------------------------------------------------------------------| -| `null` (默认) | 将空字段解释为 NULL 值。仅适用于可为空的列。 | -| `string` | 将空字段解释为空字符串 ('')。仅适用于 String 列。 | -| `field_default` | 对空字段使用列的默认值。 | +带引号的空字段（即 `,"",`）被转换为的值。 -### OUTPUT_HEADER (仅导出) +**可用值**: 与 [EMPTY_FIELD_AS](#empty_field_as仅导入) 相同 -指定在使用 `COPY INTO ` 命令导出数据时，是否在 CSV 文件中包含标题行。默认为 `false`。 +**默认值**: `STRING` ### BINARY_FORMAT -控制数据导出和导入操作期间的二进制编码格式，可用值为 `HEX`（默认）和 `BASE64`。 +`Binary` 列的编码格式。 + +**可用值**: `HEX` 或 `BASE64` + +**默认值**: `HEX` + +### GEOMETRY_FORMAT + +`Geometry` 列的编码格式。 + +**可用值**: `EWKT`、`WKB`、`WKB`、`EWKB`、`GEOJSON` + +**默认值**: `EWKT` + +### ENCODING（仅导入） + +源文件的字符集编码。设置为非 UTF-8 编码时，文件内容会在字段解析之前先转码为 UTF-8。 + +支持 [Encoding Standard](https://encoding.spec.whatwg.org/) 识别的任何标签（如 `UTF-8`、`GBK`、`SHIFT_JIS`、`EUC-KR`、`ISO-8859-1`）。标签在创建文件格式 / Stage 时即进行验证。 + +**默认值**: `UTF-8` + +### ENCODING_ERROR_MODE（仅导入） + +遇到声明编码中的无效字节（或 encoding 为 `UTF-8` 时的无效 UTF-8 字节）时的处理方式。 + +| 可用值 | 描述 | +|--------------------|------------------------------------------------------------------| +| `STRICT`（默认） | 遇到第一个格式错误的字节序列时中止并报错。 | +| `REPLACE` | 将每个格式错误的字节序列替换为 U+FFFD 并继续处理。 | + +**默认值**: `STRICT` ### COMPRESSION -指定压缩算法。 +压缩算法。 | 可用值 | 描述 | |------------------|-----------------------------------------------------------------------| -| `NONE` (默认) | 表示文件未压缩。 | +| `NONE` | 表示文件未压缩。 | | `AUTO` | 通过文件扩展名自动检测压缩 | | `GZIP` | | | `BZ2` | | @@ -155,29 +236,33 @@ ERROR_ON_COLUMN_COUNT_MISMATCH 是一个布尔选项，当设置为 true 时， | `RAW_DEFLATE` | Deflate 压缩文件（没有任何标头，RFC1951）。 | | `XZ` | | +**默认值**: `NONE` + ## TSV 选项 -Databend 中的 TSV（在 `v1.2.890-nightly` 及之后版本中称为 `TEXT`）在两种名称下使用相同的格式和选项。为了兼容旧版本 Server，本页仍以 `TSV` 作为主要术语。 +Databend TSV（在 `v1.2.891-nightly` 及之后版本中也称为 `TEXT`）在两种名称下使用相同的格式和选项。为了兼容旧版本 Server，本页仍以 `TSV` 作为主要术语。 -Databend 处理 TSV 文件时遵循以下规则： +Databend TSV 遵循以下规则： -- TSV 文件中的这些字符将被转义：`\b`、`\f`、`\r`、`\n`、`\t`、`\0`、`\\`、`\'`、[RECORD_DELIMITER](#record_delimiter-1)、[FIELD_DELIMITER](#field_delimiter-1)。 -- 目前不支持引用或封闭。 -- 如果字符串来自序列化的 Array 或 Struct 字段，则将在 CSV 中引用该字符串。 -- Null 被序列化为 `\N`。 +- [RECORD_DELIMITER](#record_delimiter-1)、[FIELD_DELIMITER](#field_delimiter-1) 通过 `\` 进行转义以解决[分隔符冲突](https://en.wikipedia.org/wiki/Delimiter#Delimiter_collision) +- 除了分隔符之外，以下字符也会被转义：`\b`、`\f`、`\r`、`\n`、`\t`、`\0`、`\\`、`\'`。 +- [QUOTE](#quote仅导入) 不属于此格式。 +- NULL 表示为 `\N`。 :::note -1. 在 Databend 中，TSV 和 CSV 之间的主要区别是不使用制表符代替逗号作为字段分隔符（可以通过选项更改），而是使用转义而不是引用来解决[分隔符冲突](https://en.wikipedia.org/wiki/Delimiter#Delimiter_collision) +1. 在 Databend 中，TSV 和 CSV 之间的主要区别不是使用制表符代替逗号作为字段分隔符（可以通过选项更改），而是使用转义而不是引用来解决[分隔符冲突](https://en.wikipedia.org/wiki/Delimiter#Delimiter_collision) 2. 我们建议使用 CSV 作为存储格式，因为它具有正式标准。 -3. TSV 可用于加载以下文件生成的文件 - 1. Clickhouse TSV 文件格式。 - 2. MySQL `mysqldump` 命令，带有选项 `--tab`，但不带 `--fields-enclosed-by` 或 `--fields-optinally-enclosed-by`，如果指定了后两个选项，请改用 CSV。 - 3. Snowflake CSV，不带 `ESCAPE_UNENCLOSED_FIELD`。如果指定了 `ESCAPE_UNENCLOSED_FIELD`，请改用 CSV。 +3. TSV 可用于加载以下工具生成的文件 + 1. [Postgresql TEXT](https://www.postgresql.org/docs/current/sql-copy.html)。 + 2. [Clickhouse TSV](https://clickhouse.com/docs/integrations/data-formats/csv-tsv#tsv-tab-separated-files) + 3. [MySQL TabSeperated](https://dev.mysql.com/doc/refman/8.4/en/mysqldump.html) MySQL `mysqldump --tab`。如果使用了 `--fields-enclosed-by` 或 `--fields-optinally-enclosed-by`，请改用 CSV。 + 4. [Snowflake CSV](https://docs.snowflake.com/en/sql-reference/sql/create-file-format#type-csv) 默认选项。如果指定了 `ESCAPE_UNENCLOSED_FIELD`，请改用 CSV。 + 5. Hive Textfile。 ::: ### RECORD_DELIMITER -分隔输入文件中的记录。 +分隔文件中记录的分隔字符。 **可用值**: @@ -189,14 +274,54 @@ Databend 处理 TSV 文件时遵循以下规则： ### FIELD_DELIMITER -分隔记录中的字段。 +分隔记录中字段的分隔字符。 **可用值**: - 非字母数字字符，例如 `#` 和 `|`。 - 带有转义字符的字符：`\b`、`\f`、`\r`、`\n`、`\t`、`\0`、`\xHH` -**默认值**: `\t` (TAB) +**默认值**: `\t`（TAB） + +### SKIP_HEADER（仅导入） + +与 [CSV 的 SKIP_HEADER 选项](#skip_header仅导入) 相同。 + +### TRIM_SPACE（仅导入） + +与 [CSV 的 TRIM_SPACE 选项](#trim_space仅导入) 相同。 + +### OUTPUT_HEADER（仅导出） + +与 [CSV 的 OUTPUT_HEADER 选项](#output_header仅导出) 相同。 + +### NAN_DISPLAY + +与 [CSV 的 NAN_DISPLAY 选项](#nan_display) 相同。 + +### NULL_DISPLAY + +与 [CSV 的 NULL_DISPLAY 选项](#null_display) 相同。 + +### EMPTY_FIELD_AS（仅导入） + +与 [CSV 的 EMPTY_FIELD_AS 选项](#empty_field_as仅导入) 相同。 + +注意：TSV 的默认值为 `FIELD_DEFAULT`（与 CSV 默认的 `NULL` 不同）。 + +**默认值**: `FIELD_DEFAULT` + +### ERROR_ON_COLUMN_COUNT_MISMATCH（仅导入） + +与 [CSV 的 ERROR_ON_COLUMN_COUNT_MISMATCH 选项](#error_on_column_count_mismatch仅导入) 相同。 + +### ENCODING（仅导入） + +与 [CSV 的 ENCODING 选项](#encoding仅导入) 相同。 + +### ENCODING_ERROR_MODE（仅导入） + +与 [CSV 的 ENCODING_ERROR_MODE 选项](#encoding_error_mode仅导入) 相同。 ### COMPRESSION @@ -204,24 +329,32 @@ Databend 处理 TSV 文件时遵循以下规则： ## NDJSON 选项 -### NULL_FIELD_AS (仅导入) +### NULL_FIELD_AS（仅导入） + +`null` 值被转换为的目标值。 + +| 可用值 | 转换为 | +|-------------------------|----------------------------------------------------------| +| `NULL`（默认） | 可为空字段转为 NULL。不可为空字段则报错。 | +| `FIELD_DEFAULT` | 字段的默认值。 | + +### MISSING_FIELD_AS（仅导入） -指定在数据导入期间如何处理 null 值。有关可能的配置，请参阅下表中的选项。 +缺失字段被转换为的目标值。 -| 可用值 | 描述 | -|-----------------------|---------------------------------------------------------------------------------------------------| -| `NULL` (默认) | 将 null 值解释为可为空字段的 NULL。将为不可为空字段生成错误。 | -| `FIELD_DEFAULT` | 对 null 值使用字段的默认值。 | +| 可用值 | 转换为 | +|------------------|----------------------------------------------------------| +| `ERROR`（默认） | 报错。 | +| `NULL` | 可为空字段转为 NULL。不可为空字段则报错。 | +| `FIELD_DEFAULT` | 字段的默认值。 | -### MISSING_FIELD_AS (仅导入) +### NULL_IF（仅导入） -确定在数据导入期间遇到缺失字段时的行为。有关可能的配置，请参阅下表中的选项。 +一组字符串。当源文件中的字段值与列表中的某个字符串完全匹配时，该值被加载为 NULL。匹配为精确匹配且区分大小写。 -| 可用值 | 描述 | -|-----------------|-------------------------------------------------------------------------------------------| -| `ERROR` (默认) | 如果遇到缺失字段，则生成错误。 | -| `NULL` | 将缺失字段解释为 NULL 值。将为不可为空字段生成错误。 | -| `FIELD_DEFAULT` | 对缺失字段使用字段的默认值。 | +**语法**: `NULL_IF = ('value1', 'value2', ...)` + +**默认值**: 空（无额外 NULL 标记） ### COMPRESSION @@ -229,23 +362,33 @@ Databend 处理 TSV 文件时遵循以下规则： ## PARQUET 选项 -### MISSING_FIELD_AS (仅导入) +### MISSING_FIELD_AS（仅导入） + +缺失字段被转换为的目标值。 + +| 可用值 | 转换为 | +|------------------|----------------------------------------------------------| +| `ERROR`（默认） | 报错。 | +| `FIELD_DEFAULT` | 字段的默认值。 | + +### NULL_IF（仅导入） + +与 [NDJSON 的 NULL_IF 选项](#null_if仅导入) 相同。 -确定在数据导入期间遇到缺失字段时的行为。有关可能的配置，请参阅下表中的选项。 +### USE_LOGIC_TYPE（仅导入） -| 可用值 | 描述 | -|-----------------|-------------------------------------------------------------------------------------------| -| `ERROR` (默认) | 如果遇到缺失字段，则生成错误。 | -| `FIELD_DEFAULT` | 对缺失字段使用字段的默认值。 | +启用时，使用 Parquet 逻辑类型（如 DATE、TIMESTAMP、DECIMAL 注解）来确定导入时的目标列类型。禁用时，仅考虑物理存储类型。 -### COMPRESSION ### OUTPUT_HEADER (仅导出) +**默认值**: `true` + +### COMPRESSION（仅导出） -指定压缩算法，该算法用于压缩文件的内部块，而不是整个文件，因此输出仍为 Parquet 格式。 +Parquet 文件内部块的压缩算法。 | 可用值 | 描述 | |------------------|-----------------------------------------------------------------------| -| `ZSTD` (默认) | 支持 Zstandard v0.8（及更高版本）。 | -| `SNAPPY` | Snappy 是一种流行的快速压缩算法，通常与 Parquet 一起使用。 | +| `ZSTD`（默认） | 支持 Zstandard v0.8（及更高版本）。 | +| `SNAPPY` | Snappy 是一种常与 Parquet 配合使用的快速压缩算法。 | ## LANCE 选项 @@ -274,24 +417,36 @@ FILE_FORMAT = (TYPE = LANCE) | `SINGLE` Copy 选项 | 不支持 | | `PARTITION BY` | 不支持 | + ## ORC 选项 -### MISSING_FIELD_AS (仅导入) +### MISSING_FIELD_AS（仅导入） -确定在数据导入期间遇到缺失字段时的行为。有关可能的配置，请参阅下表中的选项。 +缺失字段被转换为的目标值。 + +| 可用值 | 转换为 | +|------------------|----------------------------------------------------------| +| `ERROR`（默认） | 报错。 | +| `FIELD_DEFAULT` | 字段的默认值。 | -| 可选值 | 描述 | -|------------------|----------------------------------------------------------------------------------------------------| -| `ERROR` (默认) | 如果遇到缺失字段，则会生成错误。 | -| `FIELD_DEFAULT` | 对于缺失的字段，使用该字段的默认值。 | ## AVRO 选项 -### MISSING_FIELD_AS (仅导入) +### MISSING_FIELD_AS（仅导入） + +缺失字段被转换为的目标值。 -确定在数据导入期间遇到缺失字段时的行为。请参考下表中的选项以获取可能的配置。 +| 可用值 | 转换为 | +|------------------|----------------------------------------------------------| +| `ERROR`（默认） | 报错。 | +| `FIELD_DEFAULT` | 字段的默认值。 | -| 可选值 | 描述 | -|------------------|----------------------------------------------------------------------------------------------------| -| `ERROR` (默认) | 如果遇到缺失字段，则会生成错误。 | -| `FIELD_DEFAULT` | 对于缺失的字段，使用该字段的默认值。 | +### NULL_IF（仅导入） + +与 [NDJSON 的 NULL_IF 选项](#null_if仅导入) 相同。 + +### USE_LOGIC_TYPE（仅导入） + +启用时，使用 Avro 逻辑类型（如 date、timestamp-millis、decimal）来确定导入时的目标列类型。禁用时，仅考虑底层 Avro 类型。 + +**默认值**: `true` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md index 06ef1d5b0a..3483c4b46b 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md @@ -16,9 +16,8 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; CREATE [ OR REPLACE ] STAGE [ IF NOT EXISTS ] [ FILE_FORMAT = ( FORMAT_NAME = '' - | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC } [ formatTypeOptions ] + | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC | AVRO | LANCE } [ formatTypeOptions ] ) ] - [ COPY_OPTIONS = ( copyOptions ) ] [ COMMENT = '' ] -- 外部 Stage @@ -26,9 +25,8 @@ CREATE STAGE [ IF NOT EXISTS ] externalStageParams [ FILE_FORMAT = ( FORMAT_NAME = '' - | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC } [ formatTypeOptions ] + | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC | AVRO | LANCE } [ formatTypeOptions ] ) ] - [ COPY_OPTIONS = ( copyOptions ) ] [ COMMENT = '' ] ``` @@ -58,19 +56,6 @@ externalStageParams ::= 详情请参见 [Input & Output File Formats](../../../00-sql-reference/50-file-format-options.md)。 -### copyOptions - -```sql -copyOptions ::= - [ SIZE_LIMIT = ] - [ PURGE = ] -``` - -| 参数 | 描述 | 是否必须 | -| :------------------- | :---------------------------------------------------------------------------- | :------- | -| `SIZE_LIMIT = ` | 大于 0 的数字，指定单个 COPY 语句最多加载的数据行数。默认为 `0`。 | 可选 | -| `PURGE = ` | 设为 true 表示文件成功加载到表后，命令会清理 Stage 中的文件。默认为 `false`。 | 可选 | - ## 访问控制要求 | 权限 | 对象类型 | 描述 | @@ -90,10 +75,11 @@ CREATE STAGE my_internal_stage; DESC STAGE my_internal_stage; -name |stage_type|stage_params |copy_options |file_format_options |number_of_files|creator |comment| ------------------+----------+--------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------+---------------+------------------+-------+ -my_internal_stage|Internal |StageParams { storage: Fs(StorageFsConfig { root: "_data" }) }|CopyOptions { on_error: AbortNum(1), size_limit: 0, max_files: 0, split_size: 0, purge: false, single: false, max_file_size: 0, disable_variant_check: false }|Parquet(ParquetFileFormatParams)| 0|'root'@'127.0.0.1'| | - +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├───────────────────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼──────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_internal_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### 示例 2：使用 Connection 创建外部 Stage @@ -113,11 +99,12 @@ CREATE STAGE my_s3_stage CONNECTION = (CONNECTION_NAME = 'my_s3_connection'); DESC STAGE my_s3_stage; -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| name | stage_type | stage_params | copy_options | file_format_options | comment | -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| my_s3_stage | External | StageParams { storage: S3(StageS3Storage { bucket: "load", path: "/files/", credentials_aws_key_id: "", credentials_aws_secret_key: "", encryption_master_key: "" }) } | CopyOptions { on_error: None, size_limit: 0 } | FileFormatOptions { format: Csv, skip_header: 0, field_delimiter: ",", record_delimiter: "\n", compression: None } | | -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ + +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├─────────────┼────────────┼──────────────┼──────────────────┼──────────┼─────────────────┼────────────────────┼───────────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_s3_stage │ External │ s3 │ s3://load/files/ │ NULL │ true │ false │ {"bucket":"load",...} │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### 示例 3：使用 AWS IAM 用户创建外部 Stage diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md index 249c462a5d..f6193ddc1f 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md @@ -19,9 +19,10 @@ CREATE STAGE my_int_stage; ```sql DESC STAGE my_int_stage; -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| name | stage_type | stage_params | copy_options | file_format_options | comment | -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| my_int_stage | Internal | StageParams { storage: S3(StageS3Storage { bucket: "", path: "", credentials_aws_key_id: "", credentials_aws_secret_key: "", encryption_master_key: "" }) } | CopyOptions { on_error: None, size_limit: 0 } | FileFormatOptions { format: Parquet, skip_header: 0, field_delimiter: ",", record_delimiter: "\n", compression: None } | | -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -``` \ No newline at end of file + +┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├──────────────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_int_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md index f45ba3b02c..943b638edb 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md @@ -16,8 +16,9 @@ SHOW STAGES; ```sql SHOW STAGES; ---- -name|stage_type|number_of_files|creator |comment| -----+----------+---------------+----------+-------+ -eric|Internal | 0|'root'@'%'| | -``` \ No newline at end of file +┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├──────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ eric │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md b/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md index 2dfacecebb..7444632687 100644 --- a/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md +++ b/docs/cn/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md @@ -145,27 +145,37 @@ formatTypeOptions ::= [ ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE ] [ EMPTY_FIELD_AS = null | string | field_default ] [ BINARY_FORMAT = HEX | BASE64 ] + [ TRIM_SPACE = TRUE | FALSE ] + [ ENCODING = '' ] + [ ENCODING_ERROR_MODE = STRICT | REPLACE ] /* TSV 专用选项 */ [ RECORD_DELIMITER = '' ] [ FIELD_DELIMITER = '' ] + [ TRIM_SPACE = TRUE | FALSE ] + [ ENCODING = '' ] + [ ENCODING_ERROR_MODE = STRICT | REPLACE ] /* NDJSON 专用选项 */ [ NULL_FIELD_AS = NULL | FIELD_DEFAULT ] [ MISSING_FIELD_AS = ERROR | NULL | FIELD_DEFAULT ] + [ NULL_IF = ('value1', 'value2', ...) ] [ ALLOW_DUPLICATE_KEYS = TRUE | FALSE ] /* PARQUET 专用选项 */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] + [ NULL_IF = ('value1', 'value2', ...) ] + [ USE_LOGIC_TYPE = TRUE | FALSE ] /* ORC 专用选项 */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] /* AVRO 专用选项 */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] + [ NULL_IF = ('value1', 'value2', ...) ] + [ USE_LOGIC_TYPE = TRUE | FALSE ] copyOptions ::= - [ SIZE_LIMIT = ] [ PURGE = ] [ FORCE = ] [ DISABLE_VARIANT_CHECK = ] @@ -181,12 +191,6 @@ copyOptions ::= ``` -:::note -对于远程文件，你可以使用 glob 模式指定多个文件。例如： -- `ontime_200{6,7,8}.csv` 表示 `ontime_2006.csv`、`ontime_2007.csv`、`ontime_2008.csv` -- `ontime_200[6-8].csv` 表示相同的文件 -::: - ## 关键参数 - **FILES**：指定一个或多个待加载文件名（以逗号分隔）。 @@ -195,7 +199,7 @@ copyOptions ::= ## 格式类型选项 -`FILE_FORMAT` 参数支持多种文件类型，每种类型都有专属的格式选项。下表列出各支持格式的可用选项： +`FILE_FORMAT` 参数支持多种文件类型，每种类型都有专属的格式选项。下表列出各支持格式的可用选项。完整说明请参见 [文件格式选项](../../00-sql-reference/50-file-format-options.md)。 @@ -222,6 +226,9 @@ copyOptions ::= | ERROR_ON_COLUMN_COUNT_MISMATCH | 列数不匹配时报错 | TRUE | | EMPTY_FIELD_AS | 空字段的处理方式 | null | | BINARY_FORMAT | 二进制数据的编码格式（HEX 或 BASE64） | HEX | +| TRIM_SPACE | 去除字段前后 ASCII 空白字符 | FALSE | +| ENCODING | 源文件字符集编码 | UTF-8 | +| ENCODING_ERROR_MODE | 无效字节的处理方式：STRICT 或 REPLACE | STRICT | @@ -231,6 +238,14 @@ copyOptions ::= |--------|-------------|--------| | RECORD_DELIMITER | 分隔记录的字符 | 换行符 | | FIELD_DELIMITER | 分隔字段的字符 | 制表符 (\t) | +| SKIP_HEADER | 跳过的标题行数 | 0 | +| TRIM_SPACE | 去除字段前后 ASCII 空白字符 | FALSE | +| NAN_DISPLAY | 表示 NaN 值的字符串 | NaN | +| NULL_DISPLAY | 表示 NULL 值的字符串 | \N | +| EMPTY_FIELD_AS | 空字段的处理方式 | FIELD_DEFAULT | +| ERROR_ON_COLUMN_COUNT_MISMATCH | 列数不匹配时报错 | TRUE | +| ENCODING | 源文件字符集编码 | UTF-8 | +| ENCODING_ERROR_MODE | 无效字节的处理方式：STRICT 或 REPLACE | STRICT | @@ -240,6 +255,7 @@ copyOptions ::= |--------|-------------|--------| | NULL_FIELD_AS | 空字段的处理方式 | NULL | | MISSING_FIELD_AS | 缺失字段的处理方式 | ERROR | +| NULL_IF | 视为 NULL 的字符串列表 | 空 | | ALLOW_DUPLICATE_KEYS | 是否允许对象键重复 | FALSE | @@ -249,6 +265,8 @@ copyOptions ::= | 选项 | 描述 | 默认值 | |--------|-------------|--------| | MISSING_FIELD_AS | 缺失字段的处理方式 | ERROR | +| NULL_IF | 视为 NULL 的字符串列表 | 空 | +| USE_LOGIC_TYPE | 使用 Parquet 逻辑类型推断列类型 | TRUE | @@ -265,6 +283,8 @@ copyOptions ::= | 选项 | 描述 | 默认值 | |--------|-------------|--------| | MISSING_FIELD_AS | 缺失字段的处理方式 | ERROR | +| NULL_IF | 视为 NULL 的字符串列表 | 空 | +| USE_LOGIC_TYPE | 使用 Avro 逻辑类型推断列类型 | TRUE | @@ -273,7 +293,6 @@ copyOptions ::= | 参数 | 描述 | 默认值 | |-----------|-------------|----------| -| SIZE_LIMIT | 最大加载行数 | `0`（无限制） | | PURGE | 成功加载后删除文件 | `false` | | FORCE | 允许重新加载重复文件 | `false`（跳过重复） | | DISABLE_VARIANT_CHECK | 将无效 JSON 替换为 null | `false`（无效 JSON 时报错） | @@ -383,8 +402,7 @@ COPY INTO mytable FIELD_DELIMITER = ',', RECORD_DELIMITER = '\n', SKIP_HEADER = 1 - ) - SIZE_LIMIT = 10; + ); ``` **使用 IAM 角色（生产环境推荐）** diff --git a/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md b/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md index 35920fc4c8..d2bd08f451 100644 --- a/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md +++ b/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md @@ -30,7 +30,7 @@ EXPLAIN SYNTAX select a, sum(b) as sum from t1 where a in (1, 2) and b > 0 and b ``` ```sql -EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = CSV field_delimiter = ',' record_delimiter = '\n' skip_header = 1) size_limit=10; +EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = CSV field_delimiter = ',' record_delimiter = '\n' skip_header = 1); ---- COPY @@ -42,5 +42,4 @@ EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = skip_header = "1", type = "CSV" ) - SIZE_LIMIT = 10 ``` \ No newline at end of file diff --git a/docs/en/guides/40-load-data/00-stage/00-what-is-stage.md b/docs/en/guides/40-load-data/00-stage/00-what-is-stage.md index c2f4d20050..885f469575 100644 --- a/docs/en/guides/40-load-data/00-stage/00-what-is-stage.md +++ b/docs/en/guides/40-load-data/00-stage/00-what-is-stage.md @@ -77,6 +77,10 @@ LIST @~; Commands and functions that read, list, remove, or inspect staged files can use `PATTERN` to filter files by regular expression. For staged locations, `PATTERN` matches the file path portion after `@[/]`, not the full stage URI. +:::note +Glob patterns (e.g., `ontime_200{6,7,8}.csv` or `ontime_200[6-8].csv`) in file paths are only supported for HTTP-based external locations. S3 and other object-storage locations do not support glob expansion in file paths — use `PATTERN` with a regular expression instead. +::: + For example, with `@sales_stage/raw/`, the staged file `@sales_stage/raw/year=2025/month=01/sales_20250101.parquet` is matched as `year=2025/month=01/sales_20250101.parquet`: ```sql diff --git a/docs/en/guides/40-load-data/01-load/00-stage.md b/docs/en/guides/40-load-data/01-load/00-stage.md index 3e662e7d38..3e6303de57 100644 --- a/docs/en/guides/40-load-data/01-load/00-stage.md +++ b/docs/en/guides/40-load-data/01-load/00-stage.md @@ -97,9 +97,13 @@ CREATE STAGE my_internal_stage; ```sql SHOW STAGES; -name |stage_type|number_of_files|creator |comment| ------------------+----------+---------------+----------+-------+ -my_internal_stage|Internal | 0|'root'@'%'| | +╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +│ String │ String │ Nullable(String) │ Nullable(String) │ Nullable(String) │ Boolean │ Boolean │ Nullable(Variant) │ Variant │ Nullable(String) │ Timestamp │ String │ Nullable(String) │ +├───────────────────┼────────────┼──────────────────┼──────────────────┼──────────────────┼─────────────────┼───────────────────────┼───────────────────┼──────────────────────┼──────────────────┼─────────────┼─────────┼──────────────────┤ +│ my_internal_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":"Zst… │ 'root'@'%' │ 2026-06-16 │ │ account_admin │ +│ │ │ │ │ │ │ │ │ │ │ 22:21:19… │ │ │ +╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` ### Step 2: Upload Sample File @@ -176,9 +180,9 @@ CREATE STAGE my_external_stage ```sql SHOW STAGES; -name |stage_type|number_of_files|creator |comment| ------------------+----------+---------------+------------------+-------+ -my_external_stage|External | |'root'@'%'| | +name |stage_type|creator |comment| +-----------------+----------+------------------+-------+ +my_external_stage|External |'root'@'%'| | ``` ### Step 2: Upload Sample File diff --git a/docs/en/sql-reference/00-sql-reference/50-file-format-options.md b/docs/en/sql-reference/00-sql-reference/50-file-format-options.md index 3619b426bd..9b5f70165b 100644 --- a/docs/en/sql-reference/00-sql-reference/50-file-format-options.md +++ b/docs/en/sql-reference/00-sql-reference/50-file-format-options.md @@ -109,12 +109,33 @@ Number of lines to be skipped from the beginning of the file. **Default**: `0` +### TRIM_SPACE (Load Only) + +Trim leading and trailing ASCII whitespace from each field value before type conversion. + +The trim set is fixed to ASCII whitespace: space, tab, LF, CR, VT, FF. + +For CSV, trimming happens after csv-core extracts fields, so quoted field contents are also trimmed. + +**Default**: `false` + ### OUTPUT_HEADER (Unload Only) Include a header row with column names. **Default**: `false` +### QUOTE_STYLE (Unload Only) + +Controls how CSV values are quoted during output. + +| Available Values | Description | +|---------------------------|--------------------------------------------------------------| +| `QUOTE_NOT_NULL` (Default)| Quote every non-NULL field in the CSV output. | +| `QUOTE_MINIMAL` | Quote a field only when required by the CSV output format. | + +**Default**: `QUOTE_NOT_NULL` + ### NAN_DISPLAY String that represent a "NaN" (Not-a-Number). @@ -181,6 +202,25 @@ Encoding format for `Geometry` column. **Default**: `EWKT` +### ENCODING (Load Only) + +Character set encoding of the source file. When set to a non-UTF-8 encoding, the file content is transcoded to UTF-8 before field parsing. + +Any label recognized by the [Encoding Standard](https://encoding.spec.whatwg.org/) is accepted (e.g., `UTF-8`, `GBK`, `SHIFT_JIS`, `EUC-KR`, `ISO-8859-1`). The label is validated at file format / stage creation time. + +**Default**: `UTF-8` + +### ENCODING_ERROR_MODE (Load Only) + +How to handle bytes that are invalid in the declared encoding (or invalid UTF-8 when encoding is `UTF-8`). + +| Available Values | Description | +|--------------------|----------------------------------------------------------------------| +| `STRICT` (Default) | Abort with an error on the first malformed byte sequence. | +| `REPLACE` | Replace each malformed byte sequence with U+FFFD and continue. | + +**Default**: `STRICT` + ### COMPRESSION The compression algorithm. @@ -245,6 +285,46 @@ Delimiter character to separates fields in a record. **Default**: `\t` (TAB) +### SKIP_HEADER (Load Only) + +Same as [the SKIP_HEADER option for CSV](#skip_header-load-only). + +### TRIM_SPACE (Load Only) + +Same as [the TRIM_SPACE option for CSV](#trim_space-load-only). + +### OUTPUT_HEADER (Unload Only) + +Same as [the OUTPUT_HEADER option for CSV](#output_header-unload-only). + +### NAN_DISPLAY + +Same as [the NAN_DISPLAY option for CSV](#nan_display). + +### NULL_DISPLAY + +Same as [the NULL_DISPLAY option for CSV](#null_display). + +### EMPTY_FIELD_AS (Load Only) + +Same as [the EMPTY_FIELD_AS option for CSV](#empty_field_as-load-only). + +Note: the default for TSV is `FIELD_DEFAULT` (different from CSV which defaults to `NULL`). + +**Default**: `FIELD_DEFAULT` + +### ERROR_ON_COLUMN_COUNT_MISMATCH (Load Only) + +Same as [the ERROR_ON_COLUMN_COUNT_MISMATCH option for CSV](#error_on_column_count_mismatch-load-only). + +### ENCODING (Load Only) + +Same as [the ENCODING option for CSV](#encoding-load-only). + +### ENCODING_ERROR_MODE (Load Only) + +Same as [the ENCODING_ERROR_MODE option for CSV](#encoding_error_mode-load-only). + ### COMPRESSION Same as [the COMPRESSION option for CSV](#compression). @@ -270,6 +350,14 @@ The value that missing field is converted to. | `NULL` | NULL for nullable fields. Error for non-nullable fields. | | `FIELD_DEFAULT` | The default value of the field. | +### NULL_IF (Load Only) + +A list of strings. When a field value in the source file equals one of these strings, it is loaded as NULL. Matching is exact and case-sensitive. + +**Syntax**: `NULL_IF = ('value1', 'value2', ...)` + +**Default**: empty (no extra NULL markers) + ### COMPRESSION Same as [the COMPRESSION option for CSV](#compression). @@ -285,6 +373,16 @@ The value that missing field is converted to. | `ERROR` (Default)| Error. | | `FIELD_DEFAULT` | The default value of the field. | +### NULL_IF (Load Only) + +Same as [the NULL_IF option for NDJSON](#null_if-load-only). + +### USE_LOGIC_TYPE (Load Only) + +When enabled, Parquet logical types (e.g., DATE, TIMESTAMP, DECIMAL annotations) are used to determine the target column type during loading. When disabled, only the physical storage type is considered. + +**Default**: `true` + ### COMPRESSION (Unload Only) Compression algorithm for internal blocks of parquet file. @@ -345,3 +443,13 @@ The value that missing field is converted to. |------------------|----------------------------------------------------------| | `ERROR` (Default)| Error. | | `FIELD_DEFAULT` | The default value of the field. | + +### NULL_IF (Load Only) + +Same as [the NULL_IF option for NDJSON](#null_if-load-only). + +### USE_LOGIC_TYPE (Load Only) + +When enabled, Avro logical types (e.g., date, timestamp-millis, decimal) are used to determine the target column type during loading. When disabled, only the underlying Avro type is considered. + +**Default**: `true` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md index db91c7f89e..637eb88e10 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/01-ddl-create-stage.md @@ -16,9 +16,8 @@ Creates an internal or external stage. CREATE [ OR REPLACE ] STAGE [ IF NOT EXISTS ] [ FILE_FORMAT = ( FORMAT_NAME = '' - | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC } [ formatTypeOptions ] + | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC | AVRO | LANCE } [ formatTypeOptions ] ) ] - [ COPY_OPTIONS = ( copyOptions ) ] [ COMMENT = '' ] -- External stage @@ -26,9 +25,8 @@ CREATE STAGE [ IF NOT EXISTS ] externalStageParams [ FILE_FORMAT = ( FORMAT_NAME = '' - | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC } [ formatTypeOptions ] + | TYPE = { CSV | TSV | NDJSON | PARQUET | ORC | AVRO | LANCE } [ formatTypeOptions ] ) ] - [ COPY_OPTIONS = ( copyOptions ) ] [ COMMENT = '' ] ``` @@ -58,19 +56,6 @@ For more information on `CONNECTION_NAME`, see [CREATE CONNECTION](../13-connect See [Input & Output File Formats](../../../00-sql-reference/50-file-format-options.md) for details. -### copyOptions - -```sql -copyOptions ::= - [ SIZE_LIMIT = ] - [ PURGE = ] -``` - -| Parameters | Description | Required | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -| `SIZE_LIMIT = ` | Number (> 0) that specifies the maximum rows of data to be loaded for a given COPY statement. Default `0` | Optional | -| `PURGE = ` | True specifies that the command will purge the files in the stage if they are loaded successfully into table. Default `false` | Optional | - ## Access control requirements | Privilege | Object Type | Description | @@ -90,10 +75,11 @@ CREATE STAGE my_internal_stage; DESC STAGE my_internal_stage; -name |stage_type|stage_params |copy_options |file_format_options |number_of_files|creator |comment| ------------------+----------+--------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------+---------------+------------------+-------+ -my_internal_stage|Internal |StageParams { storage: Fs(StorageFsConfig { root: "_data" }) }|CopyOptions { on_error: AbortNum(1), size_limit: 0, max_files: 0, split_size: 0, purge: false, single: false, max_file_size: 0, disable_variant_check: false }|Parquet(ParquetFileFormatParams)| 0|'root'@'127.0.0.1'| | - +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├───────────────────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼──────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_internal_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### Example 2: Create External Stage with Connection @@ -113,11 +99,12 @@ CREATE STAGE my_s3_stage CONNECTION = (CONNECTION_NAME = 'my_s3_connection'); DESC STAGE my_s3_stage; -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| name | stage_type | stage_params | copy_options | file_format_options | comment | -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| my_s3_stage | External | StageParams { storage: S3(StageS3Storage { bucket: "load", path: "/files/", credentials_aws_key_id: "", credentials_aws_secret_key: "", encryption_master_key: "" }) } | CopyOptions { on_error: None, size_limit: 0 } | FileFormatOptions { format: Csv, skip_header: 0, field_delimiter: ",", record_delimiter: "\n", compression: None } | | -+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ + +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├─────────────┼────────────┼──────────────┼──────────────────┼──────────┼─────────────────┼────────────────────┼───────────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_s3_stage │ External │ s3 │ s3://load/files/ │ NULL │ true │ false │ {"bucket":"load",...} │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### Example 3: Create External Stage with AWS IAM User diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md index 572c39dd24..a51c7d15a1 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/03-ddl-desc-stage.md @@ -19,9 +19,11 @@ CREATE STAGE my_int_stage; ```sql DESC STAGE my_int_stage; -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| name | stage_type | stage_params | copy_options | file_format_options | comment | -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -| my_int_stage | Internal | StageParams { storage: S3(StageS3Storage { bucket: "", path: "", credentials_aws_key_id: "", credentials_aws_secret_key: "", encryption_master_key: "" }) } | CopyOptions { on_error: None, size_limit: 0 } | FileFormatOptions { format: Parquet, skip_header: 0, field_delimiter: ",", record_delimiter: "\n", compression: None } | | -+--------------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------+---------+ -``` \ No newline at end of file + +┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├──────────────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ my_int_stage │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +``` + diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md index 4eb1b5627a..bd7e562e2f 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/03-stage/06-ddl-show-stages.md @@ -16,8 +16,9 @@ SHOW STAGES; ```sql SHOW STAGES; ---- -name|stage_type|number_of_files|creator |comment| -----+----------+---------------+----------+-------+ -eric|Internal | 0|'root'@'%'| | -``` \ No newline at end of file +┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ name │ stage_type │ storage_type │ url │ endpoint │ has_credentials │ has_encryption_key │ storage_params │ file_format_options │ creator │ created_on │ comment │ owner │ +├──────┼────────────┼──────────────┼──────┼──────────┼─────────────────┼────────────────────┼────────────────┼─────────────────────┼─────────┼────────────────────────────┼─────────┼───────────────┤ +│ eric │ Internal │ NULL │ NULL │ NULL │ false │ false │ NULL │ {"compression":...} │ root@% │ 2026-06-16 22:21:19.000000 │ │ account_admin │ +└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md b/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md index 9e246f94f6..fee741c617 100644 --- a/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md +++ b/docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-table.md @@ -145,27 +145,36 @@ formatTypeOptions ::= [ ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE ] [ EMPTY_FIELD_AS = null | string | field_default ] [ BINARY_FORMAT = HEX | BASE64 ] + [ TRIM_SPACE = TRUE | FALSE ] + [ ENCODING = '' ] + [ ENCODING_ERROR_MODE = STRICT | REPLACE ] /* TSV specific options */ [ RECORD_DELIMITER = '' ] [ FIELD_DELIMITER = '' ] + [ TRIM_SPACE = TRUE | FALSE ] + [ ENCODING = '' ] + [ ENCODING_ERROR_MODE = STRICT | REPLACE ] /* NDJSON specific options */ [ NULL_FIELD_AS = NULL | FIELD_DEFAULT ] [ MISSING_FIELD_AS = ERROR | NULL | FIELD_DEFAULT ] - [ ALLOW_DUPLICATE_KEYS = TRUE | FALSE ] + [ NULL_IF = ('value1', 'value2', ...) ] /* PARQUET specific options */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] + [ NULL_IF = ('value1', 'value2', ...) ] + [ USE_LOGIC_TYPE = TRUE | FALSE ] /* ORC specific options */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] /* AVRO specific options */ [ MISSING_FIELD_AS = ERROR | FIELD_DEFAULT ] + [ NULL_IF = ('value1', 'value2', ...) ] + [ USE_LOGIC_TYPE = TRUE | FALSE ] copyOptions ::= - [ SIZE_LIMIT = ] [ PURGE = ] [ FORCE = ] [ DISABLE_VARIANT_CHECK = ] @@ -181,12 +190,6 @@ copyOptions ::= ``` -:::note -For remote files, you can use glob patterns to specify multiple files. For example: -- `ontime_200{6,7,8}.csv` represents `ontime_2006.csv`, `ontime_2007.csv`, `ontime_2008.csv` -- `ontime_200[6-8].csv` represents the same files -::: - ## Key Parameters - **FILES**: Specifies one or more file names (separated by commas) to be loaded. @@ -195,7 +198,7 @@ For remote files, you can use glob patterns to specify multiple files. For examp ## Format Type Options -The `FILE_FORMAT` parameter supports different file types, each with specific formatting options. Below are the available options for each supported file format: +The `FILE_FORMAT` parameter supports different file types, each with specific formatting options. Below are the available options for each supported file format. For full details on all options, see [Input & Output File Formats](../../00-sql-reference/50-file-format-options.md). @@ -222,6 +225,9 @@ These options are available for all file formats: | ERROR_ON_COLUMN_COUNT_MISMATCH | Error if column count doesn't match | TRUE | | EMPTY_FIELD_AS | How to handle empty fields | null | | BINARY_FORMAT | Encoding format(HEX or BASE64) for binary data | HEX | +| TRIM_SPACE | Trim leading/trailing ASCII whitespace from fields | FALSE | +| ENCODING | Character set encoding of source file | UTF-8 | +| ENCODING_ERROR_MODE | How to handle invalid bytes: STRICT or REPLACE | STRICT | @@ -231,6 +237,14 @@ These options are available for all file formats: |--------|-------------|--------| | RECORD_DELIMITER | Character(s) separating records | newline | | FIELD_DELIMITER | Character(s) separating fields | tab (\t) | +| SKIP_HEADER | Number of header lines to skip | 0 | +| TRIM_SPACE | Trim leading/trailing ASCII whitespace from fields | FALSE | +| NAN_DISPLAY | String representing NaN values | NaN | +| NULL_DISPLAY | String representing NULL values | \N | +| EMPTY_FIELD_AS | How to handle empty fields | FIELD_DEFAULT | +| ERROR_ON_COLUMN_COUNT_MISMATCH | Error if column count doesn't match | TRUE | +| ENCODING | Character set encoding of source file | UTF-8 | +| ENCODING_ERROR_MODE | How to handle invalid bytes: STRICT or REPLACE | STRICT | @@ -240,7 +254,7 @@ These options are available for all file formats: |--------|-------------|--------| | NULL_FIELD_AS | How to handle null fields | NULL | | MISSING_FIELD_AS | How to handle missing fields | ERROR | -| ALLOW_DUPLICATE_KEYS | Allow duplicate object keys | FALSE | +| NULL_IF | List of strings treated as NULL | empty | @@ -249,6 +263,8 @@ These options are available for all file formats: | Option | Description | Default | |--------|-------------|--------| | MISSING_FIELD_AS | How to handle missing fields | ERROR | +| NULL_IF | List of strings treated as NULL | empty | +| USE_LOGIC_TYPE | Use Parquet logical types for column type inference | TRUE | @@ -265,6 +281,8 @@ These options are available for all file formats: | Option | Description | Default | |--------|-------------|--------| | MISSING_FIELD_AS | How to handle missing fields | ERROR | +| NULL_IF | List of strings treated as NULL | empty | +| USE_LOGIC_TYPE | Use Avro logical types for column type inference | TRUE | @@ -273,7 +291,6 @@ These options are available for all file formats: | Parameter | Description | Default | |-----------|-------------|----------| -| SIZE_LIMIT | Maximum rows of data to load | `0` (no limit) | | PURGE | Purges files after successful load | `false` | | FORCE | Allows reloading of duplicate files | `false` (skips duplicates) | | DISABLE_VARIANT_CHECK | Replaces invalid JSON with null | `false` (fails on invalid JSON) | @@ -383,8 +400,7 @@ COPY INTO mytable FIELD_DELIMITER = ',', RECORD_DELIMITER = '\n', SKIP_HEADER = 1 - ) - SIZE_LIMIT = 10; + ); ``` **Using IAM Role (Recommended for Production)** diff --git a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md index c8890cffb8..0245437db0 100644 --- a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md +++ b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-syntax.md @@ -30,7 +30,7 @@ EXPLAIN SYNTAX select a, sum(b) as sum from t1 where a in (1, 2) and b > 0 and b ``` ```sql -EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = CSV field_delimiter = ',' record_delimiter = '\n' skip_header = 1) size_limit=10; +EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = CSV field_delimiter = ',' record_delimiter = '\n' skip_header = 1); ---- COPY @@ -42,5 +42,4 @@ EXPLAIN SYNTAX copy into 's3://mybucket/data.csv' from t1 file_format = ( type = skip_header = "1", type = "CSV" ) - SIZE_LIMIT = 10 ``` \ No newline at end of file