Reading and Writing Parquet Files

Search Shortcut cmd + k | ctrl + k

Documentation / Data Import / Parquet Files

Examples

读取单个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']);

读取所有匹配通配符模式的文件：

SELECT *
FROM 'test/*.parquet';

读取所有匹配通配符模式的文件，并包含一个filename列：

指定每行来自哪个文件：

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

使用一组通配符来读取两个特定文件夹中的所有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 Files

Parquet文件是压缩的列式文件，加载和处理效率高。DuckDB提供了高效读取和写入Parquet文件的支持，以及将过滤器和投影推入Parquet文件扫描的支持。

Parquet 数据集根据文件数量、单个文件的大小、使用的压缩算法、行组大小等有所不同。这些因素对性能有显著影响。详情请参阅性能指南。

`read_parquet` 函数

函数	描述	示例
`read_parquet(path_or_list_of_paths)`	读取Parquet文件	`SELECT * FROM read_parquet('test.parquet');`
`parquet_scan(path_or_list_of_paths)`	`read_parquet` 的别名	`SELECT * FROM parquet_scan('test.parquet');`

如果你的文件以.parquet结尾，函数语法是可选的。系统会自动推断你正在读取一个Parquet文件：

SELECT * FROM 'test.parquet';

Multiple files can be read at once by providing a glob or a list of files. Refer to the multiple files section for more information.

Parameters

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

Name	Description	Type	Default
`binary_as_string`	由旧版写入器生成的Parquet文件未正确设置字符串的`UTF8`标志，导致字符串列被加载为`BLOB`。将此设置为true以将二进制列加载为字符串。	`BOOL`	`false`
`encryption_config`	用于Parquet加密的配置。	`STRUCT`	-
`filename`	Whether or not an extra `filename` column should be included in the result.	`BOOL`	`false`
`file_row_number`	是否包含`file_row_number`列。	`BOOL`	`false`
`hive_partitioning`	是否将路径解释为Hive分区路径。	`BOOL`	`true`
`union_by_name`	是否应该通过名称而不是位置来统一多个模式的列。	`BOOL`	`false`

Partial Reading

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', CODEC 'zstd');

将 tbl 写入一个使用最低压缩级别的 zstd 压缩的 Parquet 文件，以获得最快的压缩速度：

COPY tbl
    TO 'result-zstd.parquet'
    (FORMAT 'parquet', CODEC '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', CODEC 'uncompressed');

编写一个查询到使用zstd压缩的Parquet文件（与CODEC相同）并设置行组大小：

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

LZ4 压缩目前仅在 nightly 和源代码构建中可用：

将CSV文件写入LZ4_RAW压缩的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);

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

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

EXPORT DATABASE 'target_directory' (FORMAT PARQUET);

加密

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

安装和加载Parquet扩展

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

INSTALL parquet;