格式选项

DataFusion 支持在执行 COPY、INSERT INTO 或 CREATE EXTERNAL TABLE 语句时，自定义数据从磁盘读取或写入磁盘的方式。选项分为几类：一些特殊选项、与文件格式（例如 CSV 或 Parquet）相关的特定选项，以及 Parquet 列级选项。在某些情况下，选项可以通过多种方式指定，并遵循一定的优先级顺序。

指定选项与优先级顺序

与格式相关的选项可以通过三种方式指定，按优先级从高到低依次为：

• CREATE EXTERNAL TABLE 语法
• COPY 选项元组
• 会话级配置默认值

有关支持的会话级配置默认值列表，请参阅配置设置。这些默认值适用于所有操作，但优先级最低。

如果要创建外部表，可以在建表时使用 OPTIONS 子句指定该表特有的格式选项：

CREATE EXTERNAL TABLE
  my_table(a bigint, b bigint)
  STORED AS csv
  LOCATION '/tmp/my_csv_table/'
  OPTIONS(
    NULL_VALUE 'NAN',
    'has_header' 'true',
    'format.delimiter' ';'
  );

执行 INSERT INTO my_table ... 时，会遵循 CREATE TABLE 中的选项（例如 gzip 压缩、特殊分隔符以及包含表头行）。请注意，压缩、表头和分隔符设置也可以在 OPTIONS 元组列表中指定。SQL 语句中的专用语法始终优先于任意选项元组，因此如果两者都已指定，OPTIONS 中的设置将被忽略。

例如，针对上面定义的表，执行以下命令：

INSERT INTO my_table VALUES(1,2);

使用指定的选项生成一个新的 CSV 文件：

$ cat /tmp/my_csv_table/bmC8zWFvLMtWX68R_0.csv
a;b
1;2

最后，在执行 COPY 命令时也可以传入选项。

COPY source_table
  TO 'test/table_with_options'
  PARTITIONED BY (column3, column4)
  OPTIONS (
    format parquet,
    compression snappy,
    'compression::column1' 'zstd(5)',
  )

在本示例中，我们将整个 source_table 写入一个 Parquet 文件目录。查询的每个分区都会并行地向该目录写入一个 Parquet 文件。接下来的选项 compression 设置为 snappy，表示除非另有说明，所有列都应使用 snappy 压缩编码。选项 compression::col1 设置了一个覆盖值，使 Parquet 文件中的 col1 列使用压缩级别为 5 的 ZSTD 压缩编码。通常，支持针对特定列进行设置的 Parquet 选项可以使用语法 OPTION::COLUMN.NESTED.PATH 来指定。

可用选项

JSON 格式选项

读取或写入 JSON 文件时，可以使用以下选项。注意：如果指定了任何不受支持的选项，将会抛出错误并导致查询失败。

示例：

CREATE EXTERNAL TABLE t(a int)
STORED AS JSON
LOCATION '/tmp/foo/'
OPTIONS('COMPRESSION' 'gzip');

CSV 格式选项

在读取或写入 CSV 文件时，可以使用以下选项。注意：如果指定了任何不支持的选项，系统将抛出错误，查询也会失败。

示例：

CREATE EXTERNAL TABLE t (col1 varchar, col2 int, col3 boolean)
STORED AS CSV
LOCATION '/tmp/foo/'
OPTIONS('DELIMITER' '|', 'HAS_HEADER' 'true', 'NEWLINES_IN_VALUES' 'true');

Parquet 格式选项

读取或写入 Parquet 文件时可以使用以下选项。如果指定了任何不支持的选项，系统将抛出错误并导致查询失败。如果针对不存在的列指定了特定列的选项，该选项将被忽略，不会报错。

示例：

CREATE EXTERNAL TABLE t (id bigint, value double, category varchar)
STORED AS PARQUET
LOCATION '/tmp/parquet_data/'
OPTIONS(
  'COMPRESSION::user_id' 'snappy',
  'ENCODING::col_a' 'delta_binary_packed',
  'MAX_ROW_GROUP_SIZE' '1000000',
  'BLOOM_FILTER_ENABLED::id' 'true'
);