示例

将表写入 Parquet 文件的 Hive 分区数据集

COPY orders TO 'orders'
(FORMAT parquet, PARTITION_BY (year, month));

将表写入 CSV 文件的 Hive 分区数据集，允许覆盖

COPY orders TO 'orders'
(FORMAT csv, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE);

将表写入 GZIP 压缩的 CSV 文件的 Hive 分区数据集，设置明确的数据文件扩展名

COPY orders TO 'orders'
(FORMAT csv, PARTITION_BY (year, month), COMPRESSION gzip, FILE_EXTENSION 'csv.gz');

分区写入

当为 COPY 语句指定 PARTITION_BY 子句时，文件将以 Hive 分区的文件夹层次结构写入。目标是根目录的名称（在上述示例中为：orders）。文件按照文件层次结构中的顺序写入。目前，每个目录每个线程写入一个文件。

orders
├── year=2021
│    ├── month=1
│    │   ├── data_1.parquet
│    │   └── data_2.parquet
│    └── month=2
│        └── data_1.parquet
└── year=2022
     ├── month=11
     │   ├── data_1.parquet
     │   └── data_2.parquet
     └── month=12
         └── data_1.parquet

分区的值会自动从数据中提取。请注意，写入大量分区可能会非常昂贵，因为会创建许多文件。理想的分区数量取决于您的数据集大小。

要在使用 PARTITION_BY 写入时限制系统在刷新到磁盘前可以保持打开的最大文件数，请使用 partitioned_write_max_open_files 配置选项（默认值：100）。

SET partitioned_write_max_open_files = 10;

最佳实践 将数据写入许多小分区是昂贵的。通常建议每个分区至少包含 100 MB 的数据。

文件名模式

默认情况下，文件将命名为 data_0.parquet 或 data_0.csv。通过 FILENAME_PATTERN 标志，可以定义包含 {i} 或 {uuid} 的模式来创建特定的文件名。

• {i} 将被一个索引替换
• {uuid} 将被一个 128 位长的 UUID 替换

将表写入 Hive 分区的 .parquet 文件数据集，文件名中包含索引

COPY orders TO 'orders'
(FORMAT parquet, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE, FILENAME_PATTERN 'orders_{i}');

将表写入 Hive 分区的 .parquet 文件数据集，文件名唯一

COPY orders TO 'orders'
(FORMAT parquet, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE, FILENAME_PATTERN 'file_{uuid}');

覆盖

默认情况下，分区写入不允许覆盖现有目录。在本地文件系统上，OVERWRITE 和 OVERWRITE_OR_IGNORE 选项会删除现有目录。在远程文件系统上，不支持覆盖。

追加

要追加到现有的 Hive 分区目录结构中，请使用 APPEND 选项。

COPY orders TO 'orders'
(FORMAT parquet, PARTITION_BY (year, month), APPEND);

使用 APPEND 选项会产生与 OVERWRITE_OR_IGNORE, FILENAME_PATTERN '{uuid}' 选项类似的行为，但 DuckDB 会额外检查文件是否已存在，并在极少数情况下存在时重新生成 UUID（以避免冲突）。

处理列中的斜杠

要处理列名中的斜杠，请使用 url_encode 函数实现的百分比编码。