---
title: "Catalog 数据同步 - OceanBase AI 数据库 V4.6.2 | OceanBase 文档中心"
description: Catalog 数据同步 Catalog 同步功能可以将 OceanBase internal catalog 中的库表元数据自动同步到 Hive Metastore（HMS），使计算引擎（如 Spark/Daft）、DataStudio 能够通过 HMS 发现并查询 OceanBase 中的表。 概述 在 Unif…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

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

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*w3cwQYKZAJwAAAAAHhAAAAgAeiGDAQ/original) OceanBase AI 数据库V 4.6.2

# Catalog 数据同步

更新时间：2026-09-02 16:58:40

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.2/zh-CN/300.data-pipeline/300.data-sharing/100.synchronize-catalog-data.md)  

Catalog 同步功能可以将 OceanBase internal catalog 中的库表元数据自动同步到 Hive Metastore（HMS），使计算引擎（如 Spark/Daft）、DataStudio 能够通过 HMS 发现并查询 OceanBase 中的表。

## 概述

在 Unified Catalog 体系下，元数据需要统一维护和管理，以便第三方引擎直接从 HMS 获取所需的元数据信息。因此，OceanBase 需要主动将表注册到 HMS，使这些引擎能够发现并访问 OceanBase 中的数据。Catalog 数据同步提供了这一自动同步能力，无需用户手动在 HMS 侧逐一注册。

开启同步后，Internal catalog 呈现为**联邦合并视图**：本地表和远端表（如 Iceberg 等）合并展示，用户无需感知来源区别。本地新建的表会自动注册到远端 HMS（以占位表形式）。

总体而言，数据写入统一在 OceanBase 侧完成，Lakebase 内计算引擎可直接消费元数据。

**适用范围**

- 仅支持 Internal catalog 到外部 HMS 的**单向同步**
 - 仅对开启同步**后新发生的 DDL** 生效，存量对象不自动处理

## 核心概念

- 占位表（Placeholder Table）：OceanBase 本地表在 HMS 中注册的 `EXTERNAL_TABLE`，供第三方引擎发现。占位表在 `parameters` 中携带 OceanBase 溯源信息（`ob.type`、`ob.tenant_id`、`ob.table_id`、`ob.schema_version` 等），HMS 侧加保护标记防止被外部工具误删。
 - 联邦合并视图：开启同步后，Internal catalog 下合并展示本地表与远端表，用户无需关心表实际位于哪一侧。
 - 同步目标 Catalog：通过租户配置项 `catalog_sync_target` 指定的 HMS 类型 External catalog，作为同步的接收端。

## 使用场景

- 数据平台统一消费：OceanBase 写入的业务表，需要被计算引擎（如 Spark/Daft）、DataStudio 通过 HMS 读取
 - 湖仓一体查询：在 OceanBase 内同时查询本地表和远端表（如 Iceberg 等），无需手动切换 Catalog
 - 元数据统一治理：通过 HMS 统一查看 OceanBase 的表结构，避免多套元数据源不一致

## 前置条件

1. 通过 `CREATE EXTERNAL CATALOG` 创建 HMS 类型的 External catalog
 2. OceanBase AI 数据库集群能够访问 HMS 的 Thrift 地址
 3. `catalog_sync_target` 是租户级配置项，修改该配置需要租户级管理权限

## 配置方法

1. 创建同步目标 Catalog，更多语法细节，请查阅[CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006781534)。

   ```sql
   CREATE EXTERNAL CATALOG hms_sync_catalog PROPERTIES (
   TYPE = 'hms',
   URI  = 'thrift://<hms-host>:<port>'
   );

   ```
 2. 开启同步

   设置同步目标 Catalog，开启后 Internal catalog 的 DDL 将自动同步到 HMS。

   ```sql
   ALTER SYSTEM SET catalog_sync_target = 'hms_sync_catalog';

   ```
 3. 关闭同步

   ```sql
   -- 置空即断开同步
   ALTER SYSTEM SET catalog_sync_target = '';

   ```

   关闭后的行为：

      - 远端表**立刻不可见**（查询不再回退到已同步的 external catalog）
      - 本地表**不受影响**
      - HMS 中已注册的占位表**不会被自动清理**，如需移除须手动在 HMS 侧删除
 4. 重新开启同步

   重新开启同步时，需注意以下行为：

      - 若重新指向原先 Catalog，需再次执行配置方法第 2 步的开启同步语句
      - 若指向其他 Catalog，同步目标将变更为新 Catalog 对应的 HMS
      - 断开期间，OceanBase 侧新建的表不会同步到 HMS
      - 恢复同步后，断开期间产生的 DDL **不支持追溯同步**

## 支持的 DDL 操作

以下联动**仅在同步开启后的 Internal catalog 下生效**。切到 External catalog 直接操作走独立路径，不触发同步。有关切换 Catalog 的详细语法，请参阅 [SET CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006781465)。

1. CREATE TABLE

   在 Internal catalog 下执行 `CREATE TABLE` 时，系统**先在 HMS 注册占位表，再创建本地表**。该顺序确保 HMS 作为表名唯一性的前置校验点，且本地建表失败时能够补偿回滚。

   | 场景 | 处理 |
   | --- | --- |
   | HMS 中已有同名表（占位表或 Iceberg 表） | 报错：表已存在 |
   | HMS 注册成功，本地建表失败 | 自动补偿回滚，删除刚注册的 HMS 占位表 |
   | 两端均成功 | 表在 HMS 和 OceanBase 同时可见 |
 2. DROP TABLE

   在 Internal catalog 下执行 `DROP TABLE` 时，系统**先删除本地表，再注销 HMS 占位表**。该顺序以本地删除作为并发控制点（并发 DROP 仅允许一个成功）。

   | 场景 | 处理 |
   | --- | --- |
   | 本地表不存在 | 报错 |
   | HMS 注销失败 | 报错（不会静默忽略） |
 3. CREATE DATABASE

   先在 HMS 创建占位 Database，再建本地 Database。

   | 场景 | 处理 |
   | --- | --- |
   | HMS 已有同名 Database | 认领，跳过 HMS 只建本地 |
   | HMS 创建因非"已存在"原因失败 | 报错，不建本地 |
 4. DROP DATABASE

   分别删除 HMS 和本地 database。

   注意该 Database 下仍存在远端表时，严格禁止删除并报错，避免连带影响仍在被引用的远端表。
 5. ALTER TABLE

   当前支持 `ALTER TABLE` 的列变更（`ADD COLUMN`、`MODIFY COLUMN`）同步到 HMS。
 6. 不支持的 DDL 操作

   | 操作 | 说明 |
   | --- | --- |
   | `RENAME TABLE` | 同步开启时直接拦截报错 |
   | `CTAS`（`CREATE TABLE AS SELECT`） | 同步开启时直接拦截报错 |

## 查询语义

1. 联邦合并视图

   开启同步后，在 Internal Catalog 中查询表时，系统按以下规则处理：优先查询本地表。若本地不存在同名表，自动回退至已同步的 External Catalog 查询。远端表通过 External Table 路径访问，该过程对用户透明。

   用户无需感知表的实际存储位置，可通过统一的 SELECT 语句直接查询。

   **同名冲突处理**：建立同步关系时，系统不执行全量冲突检查。若运行时出现本地表与远端表同名的情况（属于异常状态），系统优先访问本地表，需用户手动清理冲突的表。
 2. SHOW TABLES

   合并展示本地表和远端表，自动去重。同名冲突（异常态）下以本地为准。
 3. SHOW DATABASES

   受系统变量 `_enable_catalog_fusion` 控制（默认 `true`）：

   ```sql
   -- 开启后，SHOW DATABASES 合并展示 internal 和同步的 external 并去重
   SET _enable_catalog_fusion = true;
   SHOW DATABASES;

   ```

   `SHOW DATABASES FROM <catalog>` 保持原语义不受影响。
 4. 占位表展示控制

   `_show_sync_placeholder_table`（GLOBAL/SESSION，默认 `false`）：在内部 Catalog 执行 `SHOW TABLES` 且开启 Catalog 融合（`_enable_catalog_fusion`）时，通过此变量控制已同步到远端 HMS 表的展示方式：

      - `false`（默认）：去重模式——如果本地已存在同名表，则不再重复展示对应的同步占位表。
      - `true`：完整模式——展示所有同步占位表，不做去重。

   ```sql
   SET _show_sync_placeholder_table = true;
   SHOW TABLES FROM hms_sync_catalog.<db>;

   ```

## 类型映射

OceanBase 与 Hive 的类型集合不完全重合。同步时按以下规则处理：

| OceanBase 类型 | HMS 侧处理 |
| --- | --- |
| `INT` / `BIGINT` / `VARCHAR` / `DECIMAL` / `TIMESTAMP` / `CHAR` 等 Hive 可识别的类型 | 直接映射为对应 Hive 类型 |
| `unsigned` / `enum` / `set` / `bit` / `datetime(6)` / `timestamp_ntz` / `year` / `time` / `json` 等 Hive 不识别的类型 | 降级为 `STRING`，同时在表属性 `parameters` 中记录原始 OceanBase 类型（如 `ob.col.<col>.original_type=geometry`） |

## 限制与约束

| 限制项 | 说明 |
| --- | --- |
| 同步方向 | 仅支持 Internal 到 外部 HMS 的**单向同步** |
| 作用范围 | 仅对开启同步 **后新发生的 DDL** 生效，存量对象不自动处理 |
| `RENAME TABLE` | 开启同步时**不支持**，入口直接拦截报错 |
| `CTAS`（`CREATE TABLE AS SELECT`） | 开启同步时**不支持**，入口直接拦截报错 |
| 远端表写操作 | 远端表只读，写操作需切换到 External catalog，有关切换 Catalog 的详细语法，请参阅 [SET CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006781465) |
| `DROP DATABASE` 保护 | Database 下存在远端表时禁止删除 |
| 同名冲突 | 建立同步时不做全量冲突检查；运行时本地优先，异常同名需用户手动清理 |
| 权限控制 | 当前版本暂不涉及远端表的权限管理 |

## 常见操作示例

1. 完整流程

   ```sql
   -- 1. 创建 HMS External catalog
   CREATE EXTERNAL CATALOG hms_sync_catalog PROPERTIES (
   TYPE = 'hms',
   URI  = 'thrift://hms-host:9083'
   );

   -- 2. 开启同步
   SET CATALOG internal;
   ALTER SYSTEM SET catalog_sync_target = 'hms_sync_catalog';

   -- 3. 建库建表（自动同步到 HMS）
   CREATE DATABASE sync_demo_db;
   USE sync_demo_db;
   CREATE TABLE orders (id INT, amount DECIMAL(10,2), created TIMESTAMP);

   -- 4. 在 Internal 下查看（合并视图）
   SHOW TABLES;

   -- 5. 在 External catalog 下查看同步结果
   SHOW TABLES FROM hms_sync_catalog.sync_demo_db;

   -- 6. 查询远端表
   SELECT * FROM hms_sync_catalog.sync_demo_db.orders;

   -- 7. 关闭同步
   ALTER SYSTEM SET catalog_sync_target = '';

   ```
 2. 清理环境

   ```sql
   SET CATALOG internal;
   ALTER SYSTEM SET catalog_sync_target = '';
   DROP TABLE IF EXISTS sync_demo_db.orders;
   DROP DATABASE IF EXISTS sync_demo_db;
   DROP CATALOG IF EXISTS hms_sync_catalog;

   ```

## 配置项与系统变量速查

| 名称 | 级别 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `catalog_sync_target` | 租户 | 空 | 同步目标 Catalog 名称。值为空时即关闭同步 |
| `_enable_catalog_fusion` | GLOBAL / SESSION | `true` | 控制 `SHOW DATABASES` 是否合并展示已同步的 External catalog 的 Database |

## 常见问题

**Q: 开启同步后，已有的存量表会同步到 HMS 吗？**

不会。同步仅对开启后新发生的 DDL 生效。存量表需要手动在 HMS 侧注册，或者删表重建。

**Q: 关闭同步后，HMS 中的占位表会自动删除吗？**

不会。占位表保留在 HMS 中，但 OceanBase 查询不再回退到远端。如需清理，须手动在 HMS 侧删除。

**Q: 建表时 HMS 注册成功但本地建表失败怎么办？**

系统会自动补偿回滚，删除刚注册的 HMS 占位表。如果补偿也失败（极端情况），用普通 `DROP TABLE` 重试清理即可。

**Q: 远端表能直接 INSERT / UPDATE 吗？**

不能。远端表只读。需要写操作时，通过 `SET CATALOG <external_catalog>` 切换到对应的 External catalog 直接操作。

**Q: 开启同步后能 RENAME TABLE 吗？**

不能。同步模式下 `RENAME TABLE` 被明确禁止。需要改名时，先关闭同步，改名后再重新开启。

**Q: 开启同步后能执行 CTAS 吗？**

不能。`CREATE TABLE AS SELECT` 在同步模式下被禁止。需要此类操作时，先关闭同步再执行。

**Q: 怎么确认同步是否生效？**

在 Internal catalog 建表后，到 External catalog 下查看：

```sql
SHOW TABLES FROM hms_sync_catalog.<db>;

```

能看到对应的表即表示同步成功。

 上一篇 下一篇 ![有帮助](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) 咨询热线