面向 Iceberg REST Catalog 的配置方法

Apache Iceberg 是一种面向数据湖的表格式，同时提供了与之配套的 Catalog 接口。Iceberg 定义了数据湖表的存储结构和管理机制，用于支持大规模、复杂数据操作。它为分区、数据更新、时间旅行、快照等提供了优化方案。Iceberg 的 Catalog 负责管理多个表的元数据，提供表发现和管理操作的入口。不同的 Catalog 实现（如 Hive Metastore、REST、Glue 等）可以用来存储和检索表的元数据，支持跨环境及引擎一致管理表。

ProtonBase 可以通过外部表方式与 Iceberg REST Catalog 元数据对接，实现查询加速和数据导入和导出。

安装扩展

安装 extension，仅需要安装一次，如果已经安装过，可以忽略。

注意：安装扩展（extension）通常需要超级用户权限。只有超级用户可以执行 CREATE EXTENSION，除非扩展被标记为 trusted，此时拥有数据库 CREATE 权限的用户也可安装。创建外部表时如依赖扩展提供的数据类型或函数，需确保已正确安装相关扩展且具备相应权限。

CREATE EXTENSION iceberg_fdw;

创建 Iceberg REST Catalog 外部服务器

CREATE SERVER <server_name> FOREIGN DATA WRAPPER iceberg_fdw
OPTIONS (
 endpoint '<endpoint_url>',
 catalog '<catalog_name>'
);

endpoint Iceberg Catalog 对外服务的 API
catalog 数据表格文件的根目录

-- 示例
CREATE SERVER iceberg_server FOREIGN DATA WRAPPER iceberg_fdw
OPTIONS (
 endpoint 'http://localhost:8181/api/catalog',
 catalog 'manual_spark'
);

创建用户映射

为本地用户账号授予对应的对象存储的访问权限。

CREATE USER MAPPING FOR public SERVER iceberg_server
OPTIONS (
 token 'principal:root;realm:default-realm'
);

创建外表

导入 Iceberg REST Catalog 中的 delta 表的元数据。

IMPORT FOREIGN SCHEMA remote_schema_name
    { LIMIT TO (table_name [, ...])
    | EXCEPT (table_name [, ...]) }
    FROM SERVER server_name
    INTO local_schema_name
    [ OPTIONS (option 'value' [, ...]) ];

其中 remote_schema_name 对应 Iceberg REST Catalog 中的 namespace，table_name 对应 Iceberg REST Catalog 中的 table，server_name 对应上述定义的 foreign server

-- 将 iceberg_namespace 下的 t1 表创建为外表，元数据保存在 public schema 下。
IMPORT FOREIGN SCHEMA iceberg_namespace
	LIMIT TO (t1) FROM SERVER iceberg_server INTO public;
 
-- 查询 Iceberg 表
SELECT COUNT(1) FROM t1;
 
-- 写入到 Iceberg 表
INSERT INTO t1 SELECT ...;