示例

将 CSV 文件读取到 lineitem 表中，使用自动检测的 CSV 选项

COPY lineitem FROM 'lineitem.csv';

将 CSV 文件读取到 lineitem 表中，使用手动指定的 CSV 选项

COPY lineitem FROM 'lineitem.csv' (DELIMITER '|');

将 Parquet 文件读取到 lineitem 表中

COPY lineitem FROM 'lineitem.pq' (FORMAT parquet);

将 JSON 文件读取到 lineitem 表中，使用自动检测选项

COPY lineitem FROM 'lineitem.json' (FORMAT json, AUTO_DETECT true);

将 CSV 文件读取到 lineitem 表中，使用双引号

COPY lineitem FROM "lineitem.csv";

将 CSV 文件读取到 lineitem 表中，省略引号

COPY lineitem FROM lineitem.csv;

将表写入 CSV 文件

COPY lineitem TO 'lineitem.csv' (FORMAT csv, DELIMITER '|', HEADER);

将表写入 CSV 文件，使用双引号

COPY lineitem TO "lineitem.csv";

将表写入 CSV 文件，省略引号

COPY lineitem TO lineitem.csv;

将查询结果写入 Parquet 文件

COPY (SELECT l_orderkey, l_partkey FROM lineitem) TO 'lineitem.parquet' (COMPRESSION zstd);

将数据库 db1 的全部内容复制到数据库 db2

COPY FROM DATABASE db1 TO db2;

仅复制模式（目录元素）但不复制任何数据

COPY FROM DATABASE db1 TO db2 (SCHEMA);

概览

COPY 在 DuckDB 和外部文件之间移动数据。COPY ... FROM 将数据从外部文件导入到 DuckDB。COPY ... TO 将数据从 DuckDB 写入外部文件。COPY 命令可用于 CSV、PARQUET 和 JSON 文件。

COPY ... FROM

COPY ... FROM 将数据从外部文件导入到现有表中。数据将追加到表中已有的数据。文件中的列数必须与表 table_name 中的列数匹配，并且列内容必须可转换为表的列类型。如果无法转换，将抛出错误。

如果指定了列列表，COPY 将仅复制文件中指定列的数据。如果表中有任何列未包含在列列表中，COPY ... FROM 将为这些列插入默认值。

将不带标题的逗号分隔文件 test.csv 的内容复制到表 test 中

COPY test FROM 'test.csv';

将带标题的逗号分隔文件的内容复制到 category 表中

COPY category FROM 'categories.csv' (HEADER);

将 lineitem.tbl 的内容复制到 lineitem 表中，其中内容由竖线字符 (|) 分隔

COPY lineitem FROM 'lineitem.tbl' (DELIMITER '|');

将 lineitem.tbl 的内容复制到 lineitem 表中，其中分隔符、引号字符和标题的存在都自动检测

COPY lineitem FROM 'lineitem.tbl' (AUTO_DETECT true);

将逗号分隔文件 names.csv 的内容读取到 category 表的 name 列中。该表的任何其他列都填充其默认值。

COPY category(name) FROM 'names.csv';

将 Parquet 文件 lineitem.parquet 的内容读取到 lineitem 表中

COPY lineitem FROM 'lineitem.parquet' (FORMAT parquet);

将以换行符分隔的 JSON 文件 lineitem.ndjson 的内容读取到 lineitem 表中

COPY lineitem FROM 'lineitem.ndjson' (FORMAT json);

将 JSON 文件 lineitem.json 的内容读取到 lineitem 表中

COPY lineitem FROM 'lineitem.json' (FORMAT json, ARRAY true);

语法

为确保与 PostgreSQL 兼容，DuckDB 接受不完全符合此处所示铁路图的 COPY ... FROM 语句。例如，以下是一个有效语句：

COPY tbl FROM 'tbl.csv' WITH DELIMITER '|' CSV HEADER;

COPY ... TO

COPY ... TO 将数据从 DuckDB 导出到外部 CSV 或 Parquet 文件。它与 COPY ... FROM 大致有相同的选项集，但在 COPY ... TO 的情况下，这些选项指定了文件应如何写入磁盘。通过使用类似选项集的 COPY ... FROM，任何由 COPY ... TO 创建的文件都可以被复制回数据库。

COPY ... TO 函数可以指定表名或查询来调用。当指定表名时，整个表的内容将被写入生成的文件。当指定查询时，查询将被执行，查询结果将写入生成的文件。

将 lineitem 表的内容复制到带有标题的 CSV 文件中

COPY lineitem TO 'lineitem.csv';

将 lineitem 表的内容复制到文件 lineitem.tbl 中，其中列由竖线字符 (|) 分隔，并包含标题行

COPY lineitem TO 'lineitem.tbl' (DELIMITER '|');

使用制表符分隔符创建不带标题的 TSV 文件

COPY lineitem TO 'lineitem.tsv' (DELIMITER '\t', HEADER false);

将 lineitem 表的 l_orderkey 列复制到文件 orderkey.tbl 中

COPY lineitem(l_orderkey) TO 'orderkey.tbl' (DELIMITER '|');

将查询结果复制到文件 query.csv 中，包括带有列名称的标题

COPY (SELECT 42 AS a, 'hello' AS b) TO 'query.csv' (DELIMITER ',');

将查询结果复制到 Parquet 文件 query.parquet 中

COPY (SELECT 42 AS a, 'hello' AS b) TO 'query.parquet' (FORMAT parquet);

将查询结果复制到以换行符分隔的 JSON 文件 query.ndjson 中

COPY (SELECT 42 AS a, 'hello' AS b) TO 'query.ndjson' (FORMAT json);

将查询结果复制到 JSON 文件 query.json 中

COPY (SELECT 42 AS a, 'hello' AS b) TO 'query.json' (FORMAT json, ARRAY true);

返回作为 COPY 语句一部分写入的文件及其列统计信息

COPY (SELECT l_orderkey, l_comment FROM lineitem) TO 'lineitem_part.parquet' (RETURN_STATS);

注意：对于嵌套列（例如，结构体），列统计信息为每个部分定义。例如，如果我们有一个列 name STRUCT(field1 INTEGER, field2 INTEGER)，则列统计信息将包含 name.field1 和 name.field2 的统计信息。

COPY ... TO 选项

可以作为复制操作的一部分提供零个或多个复制选项。WITH 指定符是可选的，但如果指定了任何选项，则括号是必需的。参数值可以带或不带单引号。

任何布尔选项都可以通过多种方式启用或禁用。您可以写入 true、ON 或 1 来启用选项，写入 false、OFF 或 0 来禁用选项。BOOLEAN 值也可以省略，例如，仅传递 (HEADER)，在这种情况下假定为 true。

除少数例外，以下选项适用于所有使用 COPY 写入的格式。

语法

为确保与 PostgreSQL 兼容，DuckDB 接受不完全符合此处所示铁路图的 COPY ... TO 语句。例如，以下是一个有效语句：

COPY (SELECT 42 AS x, 84 AS y) TO 'out.csv' WITH DELIMITER '|' CSV HEADER;

COPY FROM DATABASE ... TO

COPY FROM DATABASE ... TO 语句将一个已附加数据库的全部内容复制到另一个已附加数据库。这包括模式，例如约束、索引、序列、宏和数据本身。

ATTACH 'db1.db' AS db1;
CREATE TABLE db1.tbl AS SELECT 42 AS x, 3 AS y;
CREATE MACRO db1.two_x_plus_y(x, y) AS 2 * x + y;

ATTACH 'db2.db' AS db2;
COPY FROM DATABASE db1 TO db2;
SELECT db2.two_x_plus_y(x, y) AS z FROM db2.tbl;

仅复制 db1 的**模式**到 db2 但省略复制数据，请在语句中添加 SCHEMA。

COPY FROM DATABASE db1 TO db2 (SCHEMA);

语法

格式特定选项

CSV 选项

以下选项适用于写入 CSV 文件时。

Parquet 选项

以下选项适用于写入 Parquet 文件时。

FIELD_IDS 的一些示例如下。

自动分配 field_ids

COPY
    (SELECT 128 AS i)
    TO 'my.parquet'
    (FIELD_IDS 'auto');

将列 i 的 field_id 设置为 42

COPY
    (SELECT 128 AS i)
    TO 'my.parquet'
    (FIELD_IDS {i: 42});

将列 i 的 field_id 设置为 42，将列 j 的 field_id 设置为 43

COPY
    (SELECT 128 AS i, 256 AS j)
    TO 'my.parquet'
    (FIELD_IDS {i: 42, j: 43});

将列 my_struct 的 field_id 设置为 43，并将列 i（嵌套在 my_struct 中）的 field_id 设置为 43

COPY
    (SELECT {i: 128} AS my_struct)
    TO 'my.parquet'
    (FIELD_IDS {my_struct: {__duckdb_field_id: 42, i: 43}});

将列 my_list 的 field_id 设置为 42，并将列 element（列表子项的默认名称）的 field_id 设置为 43

COPY
    (SELECT [128, 256] AS my_list)
    TO 'my.parquet'
    (FIELD_IDS {my_list: {__duckdb_field_id: 42, element: 43}});

将列 my_map 的 field_id 设置为 42，并将列 key 和 value（映射子项的默认名称）的 field_id 分别设置为 43 和 44

COPY
    (SELECT MAP {'key1' : 128, 'key2': 256} my_map)
    TO 'my.parquet'
    (FIELD_IDS {my_map: {__duckdb_field_id: 42, key: 43, value: 44}});

JSON 选项

以下选项适用于写入 JSON 文件时。

限制

COPY 不支持表之间的数据复制。要在表之间复制，请使用 INSERT 语句。

INSERT INTO tbl2
    FROM tbl1;