通过 Catalog 加载 Iceberg 表

Apache Iceberg 是一种开源表格式（Lake Table Format），表的数据文件与元数据文件存放在外部存储（如 S3 及兼容 S3 协议的对象存储、HDFS）中，Catalog 负责管理表的命名空间与元数据指针。

OceanBase 通过 External Catalog（外部目录） 连接外部 Catalog 服务（如 HMS Catalog、REST Catalog），从对应 Catalog 加载 Iceberg 表元数据后读取底层数据文件。Iceberg 表不能通过简单的文件路径外表直接访问——需由 Catalog 提供 metadata.json、snapshot、manifest 等元数据信息。

在 Iceberg 体系中，各概念分工如下：

OceanBase 不直接解析对象存储目录结构来"发现"Iceberg 表，而是通过 External Catalog 从外部 Catalog 服务获取表定义，再按元数据定位并读取数据文件。

支持能力

• 支持类型

  Iceberg 是新一代开放表格式规范，HMS Catalog 通过扩展支持以 Hive 元数据管理 Iceberg 表，实现统一元数据入口。

  各 Catalog 类型的 CREATE EXTERNAL CATALOG 语法与参数，以 CREATE EXTERNAL CATALOG 及当前版本产品文档为准。

• 高级特性

  • Iceberg Schema Evolution（列增删）
  • Iceberg Partition Transform（如 bucket()、year() 分区表达式）

前提条件

1. Iceberg 表已就绪：目标 Iceberg 表已在对应 Catalog 中注册，且元数据完整可用。
2. 存储访问：所有 OBServer 节点对 Iceberg 表 warehouse 路径具备读权限；使用 HDFS 时需部署 Java SDK，参见 部署 OceanBase AI 数据库JAVA SDK 环境。
3. Catalog 服务可达：OceanBase AI 数据库集群网络可访问 HMS Thrift 端点、REST Catalog 服务地址，或对象存储/文件系统路径。
4. 权限：当前用户需具备 CREATE CATALOG、USE CATALOG 等权限；存储层如需 Kerberos 或 AccessKey，需额外配置 Location 或 Catalog 凭据。

创建用于访问 Iceberg 表的 External Catalog

通过 HMS Catalog 加载

当 Iceberg 表元数据在 Hive Metastore 中时，创建 TYPE = 'HMS' 的 External Catalog：

CREATE EXTERNAL CATALOG iceberg_hms
PROPERTIES (
    TYPE = 'HMS',
    URI = 'thrift://hms.example.com:9083'
);

创建步骤、Kerberos 认证及 Location 配置参见 通过 Catalog 加载 Hive 表。

通过 REST Catalog 加载

REST Catalog 通过 HTTP API 提供 Iceberg 元数据。创建 External Catalog 时需指定 Catalog 类型为 REST，并配置 REST 服务地址、warehouse 及认证信息等参数。

CREATE EXTERNAL CATALOG iceberg_rest
PROPERTIES (
    TYPE = 'REST',
    URI = '<rest_catalog_api_endpoint>',
    WAREHOUSE = '<warehouse_name_or_path>'
    -- 其他参数以 CREATE EXTERNAL CATALOG 语法文档为准
);

REST Catalog 的完整参数列表（如 OAuth2 认证、WAREHOUSE 格式等）因 REST 服务实现而异，具体信息参见 CREATE EXTERNAL CATALOG 文档。

查询 Iceberg 表

切换 Catalog

SET CATALOG iceberg_hms;
USE analytics_db;

或使用三段式标识符，无需切换上下文：

SELECT * FROM iceberg_hms.analytics_db.events
WHERE event_date = '2025-04-01'
LIMIT 100;

查询示例

-- 聚合查询
SELECT product_id, SUM(sales_amount)
FROM iceberg_hms.analytics_db.sales
WHERE event_time >= '2025-04-01'
GROUP BY product_id;

-- 与内表联邦查询
SELECT o.order_id, e.event_type
FROM internal.trade_db.orders o
JOIN iceberg_hms.analytics_db.events e ON o.user_id = e.user_id;

查看元数据

SHOW CATALOGS;

DESC iceberg_hms.analytics_db.sales;

SHOW CREATE TABLE iceberg_hms.analytics_db.sales;

Iceberg 表能力说明

以下能力适用于通过 External Catalog 访问的 Iceberg 表。经 HMS Catalog 或 REST Catalog 加载时，Iceberg 表已支持的功能与列类型一致；差异主要在元数据从哪套 Catalog 服务获取。写入能力等若因版本或 Catalog 类型而异，以当前版本行为为准。

读取能力

写入能力

数据文件格式

Iceberg 表底层数据文件格式以 Parquet 为主；元数据文件包括 metadata.json、manifest、manifest-list 等，由 OceanBase 在查询时解析。

注意事项

1. 区分 Catalog 与存储：Catalog 提供元数据映射，数据文件仍在 S3 及兼容 S3 协议的对象存储、HDFS 等外部存储中；存储凭据需单独配置。
2. 区分表格式与文件格式：Iceberg 是表格式；Parquet 是其底层常用的文件格式。二者不可混用表述。
3. HMS 中的 Iceberg 表：Hive 1.2.x / 2.3.x / 3.1.x 本身不原生管理 Iceberg，但若 Spark/Flink 等引擎已将 Iceberg 元数据注册到 HMS，OceanBase 可通过 HMS Catalog 访问。参见 通过 Catalog 加载 Hive 表 中的 Iceberg 兼容性说明。
4. 未注册到 Catalog 的文件：对象存储上的裸 Parquet/ORC 文件不是 Iceberg 表，应使用 文件外部表 访问。
5. 能力边界：REST、FILESYSTEM Catalog 的参数与行为以产品当前版本文档为准；本文未列出的 Iceberg 特性，默认视为当前版本不支持或需另行确认。