iceberg 扩展实现了对 Apache Iceberg 开放表格式的支持。在本页中，我们将介绍该扩展的基本用法，而无需附加到 Iceberg 目录（Catalog）。如需全面支持（包括写入支持），请参阅如何附加 Iceberg REST 目录。

安装和加载

iceberg 扩展在首次使用时会自动安装并加载。如果您想手动安装和加载它，请运行

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

可视化快照

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

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

iceberg_snapshots 不接受 allow_moved_paths、snapshot_from_id 或 snapshot_from_timestamp 作为参数。

选择元数据版本

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

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

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

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

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

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

“猜测”元数据版本

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

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

“最新”版本被假定为对文件名进行排序时按字典顺序排列最大的那个。不考虑排序规则（Collation）。默认情况下不启用此行为，因为它可能违反 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
);

限制

• 插入 v3 Iceberg 规范表。
• 从具有 v2 数据类型的 v3 表中读取。
• 几何数据类型（Geometry data type）。

有关附加到 Iceberg 目录时不支持的操作集，请参阅不支持的操作。