Iceberg REST 目录 – DuckDB

搜索快捷键 cmd + k | ctrl + k

文档 / 核心扩展 / Iceberg

Iceberg REST 目录

iceberg 扩展支持挂载 Iceberg REST 目录。在挂载 Iceberg REST 目录之前，您必须按照概述中的说明安装 iceberg 扩展。

如果您要挂载由亚马逊管理的 Iceberg REST 目录，请参阅挂载 Amazon S3 Tables 或 Amazon SageMaker Lakehouse 的说明。

对于所有其他 Iceberg REST 目录，您可以按照下方的说明进行操作。有关特定目录的问题，请参阅示例部分。

大多数 Iceberg REST 目录通过 OAuth2 进行身份验证。您可以使用现有的 DuckDB 密钥 (Secret) 工作流来存储 OAuth2 服务的登录凭据。

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
    OAUTH2_SERVER_URI 'http://iceberg_rest_catalog_url.com/v1/oauth/tokens'
);

如果您已经拥有 Bearer 令牌，则可以直接将其传递给 CREATE SECRET 语句

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    TOKEN 'bearer_token'
);

您可以使用以下 ATTACH 语句挂载 Iceberg 目录。

LOAD httpfs;
ATTACH 'warehouse' AS iceberg_catalog (
   TYPE iceberg,
   SECRET iceberg_secret, -- pass a specific secret name to prevent ambiguity
   ENDPOINT 'https://rest_endpoint.com'
);

要查看可用表，请运行

SHOW ALL TABLES;

`ATTACH` 选项

具有 OAuth2 授权的 REST 目录也可以仅通过 ATTACH 语句进行挂载。请参阅下方 REST 目录的 ATTACH 选项完整列表。

参数	类型	默认值	描述
`ENDPOINT_TYPE`	`VARCHAR`	`NULL`	用于挂载 S3Tables 或 Glue 目录。允许的值为 'GLUE' 和 'S3_TABLES'
`ENDPOINT`	`VARCHAR`	`NULL`	与 REST 目录通信的 URL 端点。不能与 `ENDPOINT_TYPE` 同时使用
`SECRET`	`VARCHAR`	`NULL`	用于与 REST 目录通信的密钥名称
`CLIENT_ID`	`VARCHAR`	`NULL`	用于密钥的 CLIENT_ID
`CLIENT_SECRET`	`VARCHAR`	`NULL`	密钥所需的 CLIENT_SECRET
`DEFAULT_REGION`	`VARCHAR`	`NULL`	与存储层通信时使用的默认区域
`OAUTH2_SERVER_URI`	`VARCHAR`	`NULL`	用于获取 Bearer 令牌的 OAuth2 服务器 URL
`AUTHORIZATION_TYPE`	`VARCHAR`	`OAUTH2`	对于需要 SigV4 授权的目录，请传递 `SigV4`；对于不需要授权的目录，请传递 `none`
`ACCESS_DELEGATION_MODE`	`VARCHAR`	`vended_credentials`	访问委派模式。允许的值为 `vended_credentials` 和 `none`
`SUPPORT_NESTED_NAMESPACES`	`BOOLEAN`	`true`	支持嵌套命名空间的目录的选项。
`SUPPORT_STAGE_CREATE`	`BOOLEAN`	`false`	不支持阶段创建（stage create）的目录的选项。

以下选项只能传递给 CREATE SECRET 语句，并且要求 AUTHORIZATION_TYPE 为 OAUTH2

参数	类型	默认值	描述
`OAUTH2_GRANT_TYPE`	`VARCHAR`	`NULL`	请求 OAuth 令牌时的授权类型 (Grant Type)
`OAUTH2_SCOPE`	`VARCHAR`	`NULL`	为返回的 OAuth 访问令牌请求的范围 (Scope)

支持的操作

DuckDB Iceberg 扩展在挂载 REST 目录时支持以下操作

CREATE/DROP SCHEMA
CREATE/DROP TABLE
INSERT INTO
UPDATE
DELETE
SELECT

由于支持这些操作，以下操作也同样有效

COPY FROM DATABASE duckdb_db TO iceberg_datalake;
-- Or
COPY FROM DATABASE iceberg_datalake to duckdb_db;

此功能支持 Iceberg 和 DuckDB 存储之间的深度拷贝。

UPDATE 和 DELETE 的限制

UPDATE 和 DELETE 操作具有以下限制

它们仅适用于未分区且未排序的表。尝试在分区或排序表上执行这些操作会导致错误。
DuckDB-Iceberg 仅执行位置删除 (positional deletes)。暂不支持写时复制 (Copy-on-write) 功能。
DuckDB-Iceberg 仅支持读时合并 (merge-on-read) 语义。如果表的 write.update.mode 或 write.delete.mode 属性设置为 merge-on-read 以外的值，操作将会失败。

元数据操作

iceberg_metadata 和 iceberg_snapshots 函数也可用于配合使用完全限定路径的 Iceberg REST 目录，例如

SELECT * FROM iceberg_metadata(my_datalake.default.t)

-- Or
SELECT * FROM iceberg_snapshots(my_datalake.default.t)

此功能支持用户进行时间旅行 (time traveling) 查询。

-- Using a snapshot id
SELECT * FROM my_datalake.default.t AT (VERSION => SNAPSHOT_ID)

-- Or using a timestamp
SELECT * FROM my_datalake.default.t AT (TIMESTAMP => TIMESTAMP '2025-09-22 12:32:43.217')

与 DuckLake 的互操作性

DuckDB Iceberg 扩展公开了一个函数，用于将 Iceberg 元数据仅以元数据副本的形式复制到 DuckLake，这使用户能够像查询 DuckLake 表一样查询 Iceberg 表。

-- Given that we have an Iceberg catalog attached aliased to iceberg_datalake
ATTACH 'ducklake:my_ducklake.ducklake' AS my_ducklake;

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake');

也可以通过 skip_tables 参数跳过一组表。

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake', skip_tables := ['table_to_skip']);

表属性函数

DuckDB 提供了查看和修改 Iceberg 表属性的函数

函数	描述
`iceberg_table_properties(table)`	返回指定表的所有属性。
`set_iceberg_table_properties(table, properties)`	设置指定表的属性。
`remove_iceberg_table_properties(table, property_list)`	从指定表中移除属性。

-- View table properties
SELECT *
FROM iceberg_table_properties(iceberg_catalog.default.my_table);

-- Set table properties
CALL set_iceberg_table_properties(
    iceberg_catalog.default.my_table,
    {'write.update.mode': 'merge-on-read', 'write.delete.mode': 'merge-on-read'}
);

-- Remove table properties
CALL remove_iceberg_table_properties(
    iceberg_catalog.default.my_table,
    ['some.property']
);

不支持的操作

DuckDB Iceberg 扩展不支持以下操作

MERGE INTO
ALTER TABLE

特定目录示例

Cloudflare R2 目录

要挂载到 R2 Cloudflare 管理的目录，请按照下方的挂载步骤操作。

CREATE SECRET r2_secret (
    TYPE iceberg,
    TOKEN 'r2_token'
);

您可以按照入门指南中的创建 API 令牌步骤创建一个令牌。然后，使用以下命令挂载目录。

ATTACH 'warehouse' AS my_r2_catalog (
    TYPE iceberg,
    ENDPOINT 'catalog-uri'
);

warehouse 和 catalog-uri 的变量可在 R2 对象存储目录的设置中找到（R2 Object Store, Catalog name, Settings）。

挂载到 R2 数据目录后，创建一个 schema。您可以使用 USE 命令将其设置为默认值

CREATE SCHEMA my_r2_catalog.my_schema;
USE my_r2_catalog.my_schema;

Polaris

要挂载到 Polaris 目录，请使用以下命令

CREATE SECRET polaris_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
);

ATTACH 'quickstart_catalog' AS polaris_catalog (
    TYPE iceberg,
    ENDPOINT 'polaris_rest_catalog_endpoint'
);

Lakekeeper

要挂载到 Lakekeeper 目录，以下命令将起作用。

CREATE SECRET lakekeeper_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
    OAUTH2_SCOPE 'scope',
    OAUTH2_SERVER_URI 'lakekeeper_oauth_url'
);

ATTACH 'warehouse' AS lakekeeper_catalog (
    TYPE iceberg,
    ENDPOINT 'lakekeeper_irc_url',
    SECRET 'lakekeeper_secret'
);

限制

暂不支持从非 S3 或 S3 Tables 的远程存储支持的 Iceberg REST 目录读取数据。

关于此页面

行为准则商标使用指南

关于此页面

本文中