CREATE ICEBERG CATALOG

CREATE ICEBERG CATALOG 以名称和连接选项注册 Apache Iceberg REST 目录。访问和修改还需要完成下述配置与策略设置。

描述

CREATE ICEBERG CATALOG 在 MatrixOne 中注册一个 Apache Iceberg REST 目录。仅注册目录并不会授予访问权限。目录注册完成并配置所需访问策略后，可以创建引用该目录的外部表。写入和行级 MERGE INTO 还需要额外的写入与 DML 开关。

目录需要一个指向 Iceberg REST 目录端点的 uri 选项。省略 type 选项时默认值为 rest。认证通过 auth_mode（或其别名 auth）以及可选的 token_secret_ref（别名 token_secret）配置基于令牌的凭据。

要修改现有目录，请使用 ALTER ICEBERG CATALOG ... SET (...)。要删除目录，请使用 DROP ICEBERG CATALOG。

前置条件

注册目录元数据时不会访问远端服务，即使 Iceberg 访问功能关闭也可以完成注册。查询 Iceberg 外部表前需要：

  1. 在 MatrixOne 配置中启用 Iceberg 集成。

  2. 为访问用户配置 principal mapping。

  3. 为外部数据配置 residency policy。

  4. 如果需要修改目录数据，启用写入、DML 和删除操作。

只读访问仅需要读取配置；MERGE INTO 还需要写入、DML 和删除能力。需要在每个可能执行 Iceberg 查询的 CN 上启用：

[cn.frontend.iceberg]
enable = true

如需写入，还要设置 enable-write = true。MERGE INTO、UPDATE 和 DELETE 还要求同时设置 enable-dml = true 和 enable-delete = true，并且外表必须使用兼容的非 read_only write_mode。

查询目录前，管理员必须注册 principal mapping 和 residency policy。iceberg_register_access 会同时创建这两类记录，但指定的目录必须已经存在。请先创建目录，再按下方示例调用该过程，形成一个有序流程。请把 endpoint、region、bucket 和 external principal 替换为部署实际允许的精确值。

如果 principal mapping 或 residency policy 任一缺失，MatrixOne 会直接拒绝访问，而不会连接远端目录或对象存储。

语法

CREATE ICEBERG CATALOG [IF NOT EXISTS] catalog_name WITH (option = value [, option = value] ...)

参数

选项

说明

uri

必填。Iceberg REST 目录端点 URL，例如 https://catalog.example.com/rest。

type

可选。目录类型，默认为 rest。

warehouse

可选。warehouse 位置，例如 s3://warehouse。

auth_mode

可选。认证模式，别名 auth，默认为 none。

token_secret_ref

可选。对已存储令牌密钥的引用，用于需要认证的目录，别名 token_secret。

capabilities_json

可选。描述目录能力的 JSON 文档。

示例

CREATE ICEBERG CATALOG dist_iceberg_cat WITH (
    'uri' = 'https://catalog.example.com/rest',
    'type' = 'rest',
    'warehouse' = 's3://warehouse',
    'auth_mode' = 'none'
);

CALL iceberg_register_access(
    'dist_iceberg_cat',
    'scope=cluster,account_id=0,external_principal=local,endpoint=catalog.example.com,region=*,bucket=*'
);

相关参考