iceberg 扩展实现了对 Apache Iceberg 开放表格式的支持，并可以连接到 Iceberg REST Catalogs。有关如何连接到 Iceberg REST Catalog 的信息，请参阅Iceberg REST Catalogs 页面。

安装和加载

要安装 iceberg 扩展，请运行

INSTALL iceberg;

请注意，iceberg 扩展不可自动加载。因此，在使用它之前需要手动加载。

LOAD iceberg;

更新扩展

iceberg 扩展在 DuckDB 版本之间经常收到更新。为确保您拥有最新版本，请更新您的扩展

UPDATE EXTENSIONS;

用法

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

常见参数

查询单个表

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

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

您也可以在查询中直接指定当前的清单（manifest），这可以在查询之前从目录中解析，在此示例中，清单版本是 UUID。为此，请导航到 data/iceberg 目录并运行

SELECT count(*)
FROM iceberg_scan('lineitem_iceberg/metadata/v1.metadata.json');

iceberg 扩展与 httpfs 扩展或 azure 扩展协同工作，以访问 S3 或 Azure Blob Storage 等对象存储中的 Iceberg 表。

SELECT count(*)
FROM iceberg_scan('s3://bucketname/lineitem_iceberg/metadata/v1.metadata.json');

访问 Iceberg 元数据

要访问 Iceberg 元数据，可以使用 iceberg_metadata 函数

SELECT *
FROM iceberg_metadata('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

您也可以在通过 REST Catalog 附加的 Iceberg 表上运行 iceberg_metadata 函数

SELECT *
FROM iceberg_metadata(iceberg_table);

可视化快照

要可视化 Iceberg 表中的快照，请使用 iceberg_snapshots 函数

SELECT *
FROM iceberg_snapshots('data/iceberg/lineitem_iceberg');

您也可以在通过 REST Catalog 附加的 Iceberg 表上运行 iceberg_snapshots 函数

SELECT *
FROM iceberg_snapshots(iceberg_table);

选择元数据版本

默认情况下，iceberg 扩展将查找 version-hint.text 文件以识别要使用的正确元数据版本。这可以通过向 iceberg 扩展的函数显式提供 version 参数来覆盖。

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

默认情况下，当指定 metadata_compression_codec = 'gzip' 时，iceberg 函数将同时查找 v{version}.metadata.json 和 {version}.metadata.json 文件，或 v{version}.gz.metadata.json 和 {version}.gz.metadata.json 文件。不支持其他压缩编解码器。

如果通过 version 参数提供了任何文本文件，它将被打开并视为版本提示文件

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = 'version-hint.txt',
    allow_moved_paths = true
);

iceberg 扩展将打开此文件，并将其全部内容用作提供的版本号。请注意，version-hint.txt 文件的全部内容将被视为文字版本名称，不进行编码、转义或修剪。这包括任何空白字符或不安全字符，这些字符将按照下述逻辑明确格式化到文件名中。

使用备选元数据命名约定

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
);

“猜测”元数据版本

默认情况下，iceberg 扩展读取表必须提供表版本号或 version-hint.text 文件。这通常由外部数据目录提供。如果两者都不存在，iceberg 扩展可以通过将 ? 作为 version 参数来尝试猜测最新版本

SELECT count(*)
FROM iceberg_scan(
    'data/iceberg/lineitem_iceberg_no_hint',
    version = '?',
    allow_moved_paths = true
);

在对文件名进行排序时，假定“最新”版本是字典序最大的文件名。不考虑排序规则。此行为默认未启用，因为它可能违反 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
);

限制

目前不支持写入（即导出到）Iceberg 文件。