Note
allow_moved_paths
选项确保执行某些路径解析,从而允许扫描已移动的 Iceberg 表。
iceberg
扩展是一个可加载的扩展,它实现了对 Apache Iceberg 格式的支持。
要安装并加载iceberg
扩展,请运行:
INSTALL iceberg;
LOAD iceberg;
iceberg
扩展经常在 DuckDB 发布之间收到更新。为了确保您拥有最新版本,请运行:
UPDATE EXTENSIONS (iceberg);
要测试示例,请下载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
);
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 |
目前不支持写入(即导出到)Iceberg文件。