⌘+k ctrl+k
1.3 (稳定版)
搜索快捷键 cmd + k | ctrl + k
读取和写入 Parquet 文件

示例

读取单个 Parquet 文件

SELECT * FROM 'test.parquet';

确定 Parquet 文件中的列/类型

DESCRIBE SELECT * FROM 'test.parquet';

从 Parquet 文件创建表

CREATE TABLE test AS
    SELECT * FROM 'test.parquet';

如果文件没有以 .parquet 结尾，请使用 read_parquet 函数

SELECT *
FROM read_parquet('test.parq');

使用列表参数读取三个 Parquet 文件并将它们视为单个表

SELECT *
FROM read_parquet(['file1.parquet', 'file2.parquet', 'file3.parquet']);

读取所有匹配 glob 模式的文件

SELECT *
FROM 'test/*.parquet';

读取所有匹配 glob 模式的文件，并包含指定每行来自哪个文件的 filename 虚拟列（此列自 DuckDB v1.3.0 起默认可用，无需配置选项）

SELECT *, filename
FROM read_parquet('test/*.parquet');

使用 glob 列表读取两个特定文件夹中的所有 Parquet 文件

SELECT *
FROM read_parquet(['folder1/*.parquet', 'folder2/*.parquet']);

通过 HTTPS 读取

SELECT *
FROM read_parquet('https://some.url/some_file.parquet');

查询 Parquet 文件的元数据

SELECT *
FROM parquet_metadata('test.parquet');

查询 Parquet 文件的文件元数据

SELECT *
FROM parquet_file_metadata('test.parquet');

查询 Parquet 文件的键值元数据

SELECT *
FROM parquet_kv_metadata('test.parquet');

查询 Parquet 文件的模式

SELECT *
FROM parquet_schema('test.parquet');

使用默认压缩（Snappy）将查询结果写入 Parquet 文件

COPY
    (SELECT * FROM tbl)
    TO 'result-snappy.parquet'
    (FORMAT parquet);

将查询结果写入具有特定压缩和行组大小的 Parquet 文件

COPY
    (FROM generate_series(100_000))
    TO 'test.parquet'
    (FORMAT parquet, COMPRESSION zstd, ROW_GROUP_SIZE 100_000);

将整个数据库的表内容导出为 Parquet

EXPORT DATABASE 'target_directory' (FORMAT parquet);

Parquet 文件

Parquet 文件是压缩的列式文件，加载和处理效率很高。DuckDB 支持高效地读取和写入 Parquet 文件，并支持将过滤器和投影下推到 Parquet 文件扫描中。

Parquet 数据集因文件数量、单个文件大小、使用的压缩算法、行组大小等而异。这些因素对性能有显著影响。有关详细信息，请查阅 性能指南。

read_parquet 函数

函数 描述 示例
read_parquet(路径或路径列表) 读取 Parquet 文件 SELECT * FROM read_parquet('test.parquet');
parquet_scan(路径或路径列表) read_parquet 的别名 SELECT * FROM parquet_scan('test.parquet');

如果您的文件以 .parquet 结尾，则函数语法是可选的。系统将自动推断您正在读取 Parquet 文件

SELECT * FROM 'test.parquet';

可以通过提供 glob 或文件列表一次读取多个文件。有关更多信息，请参阅多文件部分。

参数

有许多可用的选项可以传递给 read_parquet 函数或 COPY 语句。

名称 描述 类型 默认值
binary_as_string 传统写入器生成的 Parquet 文件未正确设置字符串的 UTF8 标志，导致字符串列被加载为 BLOB。将其设置为 true 可将二进制列作为字符串加载。 BOOL false
encryption_config 用于 Parquet 加密 的配置。 STRUCT -
文件名 结果中是否应包含一个额外的 filename 列。自 DuckDB v1.3.0 起，filename 列已作为虚拟列自动添加，此选项仅为兼容性原因而保留。 BOOL false
file_row_number 是否包含 file_row_number 列。 BOOL false
hive_partitioning 是否将路径解释为 Hive 分区路径。 BOOL (自动检测)
union_by_name 多个模式的列是否应按 名称而不是按位置进行合并。 BOOL false

部分读取

DuckDB 支持将投影下推到 Parquet 文件本身。也就是说，在查询 Parquet 文件时，只读取查询所需的列。这使您能够只读取 Parquet 文件中您感兴趣的部分。这将由 DuckDB 自动完成。

DuckDB 还支持将过滤器下推到 Parquet 读取器中。当您对从 Parquet 文件扫描的列应用过滤器时，过滤器将被下推到扫描中，甚至可以使用内置的区域图跳过文件的部分内容。请注意，这取决于您的 Parquet 文件是否包含区域图。

过滤器和投影下推提供了显著的性能优势。有关更多信息，请参阅 我们的博客文章“使用 DuckDB 精确查询 Parquet”。

插入和视图

您还可以将数据插入到表中，或直接从 Parquet 文件创建表。这将从 Parquet 文件加载数据并将其插入到数据库中

将 Parquet 文件中的数据插入到表中

INSERT INTO people
    SELECT * FROM read_parquet('test.parquet');

直接从 Parquet 文件创建表

CREATE TABLE people AS
    SELECT * FROM read_parquet('test.parquet');

如果您希望将数据存储在 Parquet 文件中，但又想直接查询 Parquet 文件，则可以在 read_parquet 函数上创建视图。然后，您可以像查询内置表一样查询 Parquet 文件

创建 Parquet 文件的视图

CREATE VIEW people AS
    SELECT * FROM read_parquet('test.parquet');

查询 Parquet 文件

SELECT * FROM people;

写入 Parquet 文件

DuckDB 还支持使用 COPY 语句语法写入 Parquet 文件。有关详细信息，包括 COPY 语句的所有可能参数，请参阅 COPY 语句页面。

将查询写入 Snappy 压缩的 Parquet 文件

COPY
    (SELECT * FROM tbl)
    TO 'result-snappy.parquet'
    (FORMAT parquet);

将 tbl 写入 zstd 压缩的 Parquet 文件

COPY tbl
    TO 'result-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd);

将 tbl 写入具有最低压缩级别（提供最快压缩）的 zstd 压缩 Parquet 文件

COPY tbl
    TO 'result-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd, COMPRESSION_LEVEL 1);

写入带有 键值元数据 的 Parquet 文件

COPY (
    SELECT
        42 AS number,
        true AS is_even
) TO 'kv_metadata.parquet' (
    FORMAT parquet,
    KV_METADATA {
        number: 'Answer to life, universe, and everything',
        is_even: 'not ''odd''' -- single quotes in values must be escaped
    }
);

将 CSV 文件写入未压缩的 Parquet 文件

COPY
    'test.csv'
    TO 'result-uncompressed.parquet'
    (FORMAT parquet, COMPRESSION uncompressed);

将查询写入具有 zstd 压缩和行组大小的 Parquet 文件

COPY
    (FROM generate_series(100_000))
    TO 'row-groups-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd, ROW_GROUP_SIZE 100_000);

将数据写入 LZ4 压缩的 Parquet 文件

COPY
    (FROM generate_series(100_000))
    TO 'result-lz4.parquet'
    (FORMAT parquet, COMPRESSION lz4);

或者，等效地

COPY
    (FROM generate_series(100_000))
    TO 'result-lz4.parquet'
    (FORMAT parquet, COMPRESSION lz4_raw);

将数据写入 Brotli 压缩的 Parquet 文件

COPY
    (FROM generate_series(100_000))
    TO 'result-brotli.parquet'
    (FORMAT parquet, COMPRESSION brotli);

要配置 Parquet 文件字典页的页面大小，请使用 STRING_DICTIONARY_PAGE_SIZE_LIMIT 选项（默认值：1 MB）

COPY
    lineitem
    TO 'lineitem-with-custom-dictionary-size.parquet'
    (FORMAT parquet, STRING_DICTIONARY_PAGE_SIZE_LIMIT 100_000);

DuckDB 的 EXPORT 命令可用于将整个数据库导出为一系列 Parquet 文件。有关更多详细信息，请参阅 “EXPORT 语句”页面

将整个数据库的表内容导出为 Parquet

EXPORT DATABASE 'target_directory' (FORMAT parquet);

加密

DuckDB 支持读取和写入加密的 Parquet 文件。

支持的特性

支持的 Parquet 特性列表可在 Parquet 文档的“实现状态”页面中找到。

安装和加载 Parquet 扩展

对 Parquet 文件的支持是通过扩展启用的。parquet 扩展几乎与所有客户端捆绑在一起。但是，如果您的客户端未捆绑 parquet 扩展，则必须单独安装该扩展。

INSTALL parquet;

本节页面

关于此页面