输入与输出文件格式

TiDB Cloud Lake 支持多种文件格式，既可作为数据加载或卸载的源，也可作为目标。本文介绍支持的文件格式及其可用选项。

语法

要在语句中指定文件格式，请使用以下语法：

-- Specify a standard file format
... FILE_FORMAT = ( TYPE = { CSV | TSV | NDJSON | PARQUET | LANCE | ORC | AVRO } [ formatTypeOptions ] )

-- Specify a custom file format
... FILE_FORMAT = ( FORMAT_NAME = '<your-custom-format>' )

TiDB Cloud Lake 按以下优先级顺序确定 COPY 或 Select 语句使用的文件格式：

1. 首先，检查语句中是否显式指定了 FILE_FORMAT。
2. 如果操作中未指定 FILE_FORMAT，则使用创建 stage 时为该 stage 初始定义的文件格式。
3. 如果创建 stage 时未定义文件格式，TiDB Cloud Lake 默认使用 PARQUET 格式。

formatTypeOptions

formatTypeOptions 包含一个或多个选项，用于描述文件的其他格式细节。不同文件格式支持的选项不同。请参见下文各节，了解每种受支持文件格式的可用选项。

formatTypeOptions ::=
  RECORD_DELIMITER = '<character>'
  FIELD_DELIMITER = '<character>'
  SKIP_HEADER = <integer>
  QUOTE = '<character>'
  ESCAPE = '<character>'
  NAN_DISPLAY = '<string>'
  ROW_TAG = '<string>'
  COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | XZ | NONE

CSV 选项

TiDB Cloud Lake 的 CSV 实现符合 RFC 4180，并受以下条件约束：

• 如果一个字符串包含 QUOTE、ESCAPE、RECORD_DELIMITER 或 FIELD_DELIMITER 中定义的字符，则该字符串必须使用引号包裹。
• 在带引号的字符串中，除 QUOTE 外，不会对任何字符进行转义。
• FIELD_DELIMITER 与 QUOTE 之间不应保留空格。

RECORD_DELIMITER

用于分隔文件中记录的分隔字符。

可用值：

• \r\n
• 单字节的非字母数字字符，例如 # 和 |。
• 带转义字符的字符：\b、\f、\r、\n、\t、\0、\xHH

默认值：\n

FIELD_DELIMITER

用于分隔一条记录中各字段的分隔字符。

可用值：

• 单字节的非字母数字字符，例如 # 和 |。
• 带转义字符的字符：\b、\f、\r、\n、\t、\0、\xHH

默认值：,（逗号）

QUOTE (Load Only)

用于包裹值的字符。

在加载数据时，除非字符串中包含 QUOTE、ESCAPE、RECORD_DELIMITER 或 FIELD_DELIMITER 中定义的字符，否则不需要使用引号。

可用值：'\''、'"' 或 '`'（反引号）

默认值：'"'

ESCAPE

用于在带引号的值中对引号字符进行转义的字符，此外 QUOTE 本身也可用于转义。

在某些 CSV 变体中，引号是通过特殊的转义字符（如 \）进行转义的，而不是通过重复引号来转义。

可用值：'\\' 或 ''（空，表示仅使用双引号转义）

默认值：''

SKIP_HEADER (Load Only)

从文件开头跳过的行数。

默认值：0

TRIM_SPACE (Load Only)

在类型转换之前，去除每个字段值前后的 ASCII 空白字符。

可去除的字符集合固定为 ASCII 空白字符：空格、tab、LF、CR、VT、FF。

对于 CSV，trim 操作发生在 csv-core 提取字段之后，因此带引号字段中的内容也会被去除首尾空白。

默认值：false

OUTPUT_HEADER (Unload Only)

包含带列名的表头行。

默认值：false

QUOTE_STYLE (Unload Only)

控制输出时 CSV 值的加引号方式。

默认值：QUOTE_NOT_NULL

NAN_DISPLAY

表示 "NaN"（Not-a-Number）的字符串。

可用值：必须是字面量 'nan' 或 'null'（不区分大小写）

默认值：'NaN'

NULL_DISPLAY

表示 NULL 值的字符串。

加载数据时，未加引号且匹配的值始终会转换为 NULL；加引号且匹配的值仅在 ALLOW_QUOTED_NULLS=true 时才会转换为 NULL。

默认值：'\N'

ALLOW_QUOTED_NULLS (Load Only)

允许将带引号的字符串转换为 NULL 值。

只有当该标记为 true 时，与 NULL_DISPLAY 匹配的带引号字符串才会变为 NULL。未加引号且匹配的值无论此选项如何都会变为 NULL。

默认值：false

ERROR_ON_COLUMN_COUNT_MISMATCH (Load Only)

如果数据文件中的列数与目标表中的列数不匹配，则返回错误。

默认值：true

EMPTY_FIELD_AS (Load Only)

未加引号的空字段（即 ,,）会被转换为的值。

默认值：NULL

QUOTED_EMPTY_FIELD_AS (Load Only)

带引号的空字段（即 ,"",）会被转换为的值。

可用值：与 EMPTY_FIELD_AS 相同

默认值：STRING

BINARY_FORMAT

Binary 列的编码格式。

可用值：HEX 或 BASE64

默认值：HEX

GEOMETRY_FORMAT

Geometry 列的编码格式。

可用值：EWKT、WKB、WKB、EWKB、GEOJSON

默认值：EWKT

ENCODING (Load Only)

源文件的字符集编码。设置为非 UTF-8 编码时，会先将文件内容转码为 UTF-8，再进行字段解析。

接受 Encoding Standard 识别的任何标签（例如 UTF-8、GBK、SHIFT_JIS、EUC-KR、ISO-8859-1）。该标签会在创建文件格式 / stage 时进行校验。

默认值：UTF-8

ENCODING_ERROR_MODE (Load Only)

如何处理在声明编码下无效的字节（或者当编码为 UTF-8 时的无效 UTF-8 字节）。

默认值：STRICT

COMPRESSION

压缩算法。

默认值：NONE

TSV 选项

TiDB Cloud Lake TSV（在 v1.2.891-nightly 及之后版本中也称为 TEXT）在这两个名称下使用相同的格式和选项。为兼容旧版本服务器，本页仍以 TSV 作为主要术语。

TiDB Cloud Lake TSV 需满足以下条件：

• RECORD_DELIMITER、FIELD_DELIMITER 使用 \ 转义，以解决分隔符冲突
• 除分隔符外，这些字符也会被转义：\b、\f、\r、\n、\t、\0、\\、\'。
• QUOTE 不是该格式的一部分。
• NULL 表示为 \N。

RECORD_DELIMITER

用于分隔文件中记录的分隔字符。

可用值：

• \r\n
• 任意字符，例如 # 和 |。
• 带转义字符的字符：\b、\f、\r、\n、\t、\0、\xHH

默认值：\n

FIELD_DELIMITER

用于分隔记录中字段的分隔字符。

可用值：

• 非字母数字字符，例如 # 和 |。
• 带转义字符的字符：\b、\f、\r、\n、\t、\0、\xHH

默认值：\t（TAB）

SKIP_HEADER (Load Only)

与 CSV 的 SKIP_HEADER 选项相同。

TRIM_SPACE (Load Only)

与 CSV 的 TRIM_SPACE 选项相同。

OUTPUT_HEADER (Unload Only)

与 CSV 的 OUTPUT_HEADER 选项相同。

NAN_DISPLAY

与 CSV 的 NAN_DISPLAY 选项相同。

NULL_DISPLAY

与 CSV 的 NULL_DISPLAY 选项相同。

EMPTY_FIELD_AS (Load Only)

与 CSV 的 EMPTY_FIELD_AS 选项相同。

注意：TSV 的默认值为 FIELD_DEFAULT（不同于 CSV，后者默认值为 NULL）。

默认值：FIELD_DEFAULT

ERROR_ON_COLUMN_COUNT_MISMATCH (Load Only)

与 CSV 的 ERROR_ON_COLUMN_COUNT_MISMATCH 选项相同。

ENCODING (Load Only)

与 CSV 的 ENCODING 选项相同。

ENCODING_ERROR_MODE (Load Only)

与 CSV 的 ENCODING_ERROR_MODE 选项相同。

COMPRESSION

与 CSV 的 COMPRESSION 选项相同。

NDJSON 选项

NULL_FIELD_AS (Load Only)

null 被转换成的值。

MISSING_FIELD_AS (Load Only)

缺失字段被转换成的值。

NULL_IF (Load Only)

一个字符串列表。当源文件中的字段值等于这些字符串之一时，会将其加载为 NULL。匹配必须完全一致且大小写敏感。

语法：NULL_IF = ('value1', 'value2', ...)

默认值：空（无额外 NULL 标记）

COMPRESSION

与 CSV 的 COMPRESSION 选项相同。

PARQUET 选项

MISSING_FIELD_AS (Load Only)

缺失字段被转换成的值。

NULL_IF (Load Only)

与 NDJSON 的 NULL_IF 选项相同。

USE_LOGIC_TYPE (Load Only)

启用后，加载时会使用 Parquet logical types（例如 DATE、TIMESTAMP、DECIMAL 注解）来确定目标列类型。禁用后，则只考虑物理存储类型。

默认值：true

COMPRESSION (Unload Only)

parquet 文件内部块的压缩算法。

LANCE 选项

仅在使用 COPY INTO <location> 卸载时支持 LANCE。

与 CSV、TSV、NDJSON 和 Parquet 相比，Lance 导出不会生成一个或多个可由 TiDB Cloud Lake 直接读回的独立文件。相反，TiDB Cloud Lake 会写入一个数据集目录，其中包含 .lance 数据文件以及诸如 _versions/ 之类的数据集元信息。

因此，Lance 更适合下游机器学习、向量以及基于 Arrow 的工作流，这些工作流会使用 Lance 工具（例如 Python lance（pip install pylance））来消费该数据集。

格式特定选项

Lance 没有格式特定选项。请使用：

FILE_FORMAT = (TYPE = LANCE)

行为差异

ORC 选项

MISSING_FIELD_AS（仅加载）

缺失字段会被转换成的值。

AVRO 选项

MISSING_FIELD_AS（仅加载）

缺失字段会被转换成的值。

NULL_IF（仅加载）

与 NDJSON 的 NULL_IF 选项 相同。

USE_LOGIC_TYPE（仅加载）

启用后，Avro 逻辑类型（例如 date、timestamp-millis、decimal）将用于在加载期间确定目标列类型。禁用后，则只考虑底层 Avro 类型。

默认值：true