⌘+k ctrl+k
1.1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Iceberg Extension

iceberg 扩展是一个可加载的扩展,它实现了对 Apache Iceberg 格式的支持。

Installing and Loading

要安装并加载iceberg扩展,请运行:

INSTALL iceberg;
LOAD iceberg;

更新扩展

iceberg 扩展经常在 DuckDB 发布之间收到更新。为了确保您拥有最新版本,请运行:

UPDATE EXTENSIONS (iceberg);

Usage

要测试示例,请下载iceberg_data.zip文件并解压缩。

通用参数

参数 类型 默认值 描述
allow_moved_paths BOOLEAN false 允许扫描已移动的Iceberg表
metadata_compression_codec VARCHAR '' 当设置为'gzip'时,将元数据文件视为压缩文件
version VARCHAR '?' 提供明确的版本字符串、提示文件或猜测
version_name_format VARCHAR 'v%s%s.metadata.json,%s%s.metadata.json' 控制版本如何转换为元数据文件名

查询单个表

SELECT count(*)
FROM iceberg_scan('data/iceberg/lineitem_iceberg', allow_moved_paths = true);
count_star()
51793

Note

allow_moved_paths 选项确保执行某些路径解析,从而允许扫描已移动的 Iceberg 表。

您还可以在查询中直接指定当前清单,这可能会在查询之前从目录中解析,在此示例中,清单版本是一个UUID。

SELECT count(*)
FROM iceberg_scan('data/iceberg/lineitem_iceberg/metadata/02701-1e474dc7-4723-4f8d-a8b3-b5f0454eb7ce.metadata.json');

此扩展可以与httpfs 扩展配对使用,以访问S3等对象存储中的Iceberg表。

SELECT count(*)
FROM iceberg_scan(
    's3://bucketname/lineitem_iceberg/metadata/02701-1e474dc7-4723-4f8d-a8b3-b5f0454eb7ce.metadata.json',
    allow_moved_paths = true
);

访问 Iceberg 元数据

SELECT *
FROM iceberg_metadata('data/iceberg/lineitem_iceberg', allow_moved_paths = true);
清单路径 清单序列号 清单内容 状态 内容 文件路径 文件格式 记录数
lineitem_iceberg/metadata/10eaca8a-1e1c-421e-ad6d-b232e5ee23d3-m1.avro 2 数据 已添加 已存在 lineitem_iceberg/data/00041-414-f3c73457-bbd6-4b92-9c15-17b241171b16-00001.parquet PARQUET 51793
lineitem_iceberg/metadata/10eaca8a-1e1c-421e-ad6d-b232e5ee23d3-m0.avro 2 数据 已删除 现有 lineitem_iceberg/data/00000-411-0792dcfe-4e25-4ca3-8ada-175286069a47-00001.parquet PARQUET 60175

可视化快照

SELECT *
FROM iceberg_snapshots('data/iceberg/lineitem_iceberg');
序列号 快照ID 时间戳(毫秒) 清单列表
1 3776207205136740581 2023-02-15 15:07:54.504 lineitem_iceberg/metadata/snap-3776207205136740581-1-cf3d0be5-cf70-453d-ad8f-48fdc412e608.avro
2 7635660646343998149 2023-02-15 15:08:14.73 lineitem_iceberg/metadata/snap-7635660646343998149-1-10eaca8a-1e1c-421e-ad6d-b232e5ee23d3.avro

选择元数据版本

默认情况下,iceberg 扩展会查找 version-hint.text 文件以确定要使用的正确元数据版本。这可以通过显式提供版本号来覆盖,通过 version 参数传递给 iceberg 表函数。默认情况下,这将查找 v{version}.metadata.json{version}.metadata.json 文件,或者当指定 metadata_compression_codec = 'gzip' 时查找 v{version}.gz.metadata.json{version}.gz.metadata.json 文件。不支持其他压缩编解码器。

此外,如果任何.text.txt文件作为版本提供,它将被打开并视为版本提示文件。iceberg扩展将打开此文件并使用文件的全部内容作为提供的版本号。

Note

version-hint.txt 文件的全部内容将被视为字面版本名称,不进行编码、转义或修剪。这包括任何空白字符或不安全字符,这些字符将按照下面描述的逻辑显式传递并格式化为文件名。

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = '1',
    allow_moved_paths = true
);
count_star()
60175

使用替代元数据命名约定

iceberg 扩展可以通过 version_name_format 参数指定不同的元数据命名约定,这些约定以逗号分隔的格式字符串列表形式提供。每个格式字符串必须接受两个 %s 参数。第一个是元数据文件名中版本号的位置,第二个是 metadata_compression_codec 扩展的位置。上述行为由默认值 "v%s%s.metadata.gz,%s%smetadata.gz 提供。如果您有一个不同命名的元数据文件,例如 rev-2.metadata.json.gz,则可以通过以下语句读取表。

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/alternative_metadata_gz_naming',
    version = '2',
    version_name_format = 'rev-%s.metadata.json%s',
    metadata_compression_codec = 'gzip',
    allow_moved_paths = true
);
count_star()
60175

“猜测”元数据版本

默认情况下,iceberg 扩展读取表时,必须提供表版本号或 version-hint.text。这通常由外部数据目录提供。如果两者都不存在,iceberg 扩展可以通过传递 ? 作为表版本来尝试猜测最新版本。“最新”版本被假定为按文件名排序时字典序最大的文件名。不考虑排序规则。此行为默认未启用,因为它可能违反 ACID 约束。可以通过将 unsafe_enable_version_guessing 设置为 true 来启用。启用后,iceberg 函数将在失败前默认尝试猜测最新版本。

SET unsafe_enable_version_guessing=true;
SELECT count(*)
FROM iceberg_scan('data/iceberg/lineitem_iceberg_no_hint', allow_moved_paths = true);
-- Or explicitly as:
-- FROM iceberg_scan(
--         'data/iceberg/lineitem_iceberg_no_hint',
--         version = '?',
--         allow_moved_paths = true
-- );
count_star()
51793

Limitations

目前不支持写入(即导出到)Iceberg文件。