---
title: "通过 Catalog 加载 Iceberg 表 - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: 通过 Catalog 加载 Iceberg 表 Apache Iceberg 是一种开源表格式（Lake Table Format），表的数据文件与元数据文件存放在外部存储（如 OSS、S3、HDFS）中，Catalog 负责管理表的命名空间与元数据指针。 OceanBase 通过 External Catalog（…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.6.0

# 通过 Catalog 加载 Iceberg 表

更新时间：2026-07-02 18:41:33

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.6.0/zh-CN/620.obap/400.data-lake/200.data-lake-integration/200.load-iceberg-via-catalog.md)  

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

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

#### 说明

HMS Catalog 与 REST Catalog 的区别在于**从哪套 Catalog 服务加载 Iceberg 表元数据**；Iceberg 表已支持的功能、列类型等在两种接入方式下一致。HMS Catalog 的创建与认证配置详见 [通过 Catalog 加载 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)。

#### 说明

当前仅 OceanBase MySQL 模式支持通过 External Catalog 访问 Iceberg 表。

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

| 概念 | 说明 |
| --- | --- |
| **存储** | 数据文件与元数据文件的物理存放位置（OSS、S3、HDFS 等） |
| **文件格式** | 数据文件的编码方式，Iceberg 表通常使用 Parquet。Iceberg 表的 V1 / V2 版本，推荐 Parquet 格式。 |
| **表格式（Iceberg）** | 表的版本、分区、Schema 及 snapshot 管理机制 |
| **Catalog** | 表名到 Iceberg 元数据位置的映射服务 |
| **External Catalog** | OceanBase 中连接外部 Catalog 的对象 |

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

## 支持能力

- 支持类型

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

  各 Catalog 类型的 `CREATE EXTERNAL CATALOG` 语法与参数，以 [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150) 及当前版本产品文档为准。
 - 高级特性

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

## 前提条件

1. **版本与模式**：MySQL 模式租户。经 HMS Catalog 访问 Iceberg 表时需 OceanBase **V4.4.1 及以上**（HMS Catalog 配置见 [通过 Catalog 加载 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)）。
 2. **Iceberg 表已就绪**：目标 Iceberg 表已在对应 Catalog 中注册，且元数据完整可用。
 3. **存储访问**：所有 OBServer 节点对 Iceberg 表 warehouse 路径具备读权限；使用 HDFS 时需部署 Java SDK，参见 [部署 OceanBase 数据库 JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005681933)。
 4. **Catalog 服务可达**：OceanBase 集群网络可访问 HMS Thrift 端点、REST Catalog 服务地址，或对象存储/文件系统路径。
 5. **权限**：当前用户需具备 `CREATE CATALOG`、`USE CATALOG` 等权限；存储层如需 Kerberos 或 AccessKey，需额外配置 Location 或 Catalog 凭据。

## 创建用于访问 Iceberg 表的 External Catalog

### 通过 HMS Catalog 加载

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

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

```

创建步骤、Kerberos 认证及 Location 配置参见 [通过 Catalog 加载 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)。

### 通过 REST Catalog 加载

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

```sql
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](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150) 文档。

## 查询 Iceberg 表

### 切换 Catalog

```sql
SET CATALOG iceberg_hms;
USE analytics_db;

```

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

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

```

### 查询示例

```sql
-- 聚合查询
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;

```

### 查看元数据

```sql
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 类型而异，以当前版本行为为准。

### 读取能力

| 特性 | 支持情况 |
| --- | --- |
| `SELECT` 查询 | 支持 |
| 分区裁剪 | 支持按分区列或分区转换表达式过滤 |
| 列裁剪 | 支持 |
| 时间旅行（Time Travel） | 部分版本支持按 snapshot 或 timestamp 查询；语法以当前版本文档为准 |
| Position Delete / Equality Delete / Deletion Vector | 读取含删除文件的表；具体支持范围以当前版本为准 |
| Schema Evolution（列增删） | 支持读取演进后的 Schema |
| Partition Transform（`year()`、`bucket()`、`truncate()` 等） | 支持 |

### 写入能力

| 操作 | 支持情况 |
| --- | --- |
| `INSERT INTO` | 部分场景支持；分区写入存在限制 |
| `INSERT OVERWRITE` | 不支持 |
| `UPDATE` / `DELETE` | 不支持 |

#### 注意

通过 HMS Catalog 访问的 Iceberg 表当前为只读。Iceberg 表的 `INSERT INTO` 能力是否可用，取决于 External Catalog 类型及当前版本说明，使用前请确认。

### 数据文件格式

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

## 注意事项

1. **区分 Catalog 与存储**：Catalog 提供元数据映射，数据文件仍在 OSS、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 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510) 中的 Iceberg 兼容性说明。
 4. **未注册到 Catalog 的文件**：对象存储上的裸 Parquet/ORC 文件不是 Iceberg 表，应使用 [文件外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682506) 访问。
 5. **能力边界**：REST、FILESYSTEM Catalog 的参数与行为以产品当前版本文档为准；本文未列出的 Iceberg 特性，默认视为当前版本不支持或需另行确认。

## 相关文档

- [数据湖概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326199)
 - [Catalog 与外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326201)
 - [通过 HMS Catalog 访问 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)
 - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150)

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线