Catalog 数据同步

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。

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

2. 开启同步

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

   ALTER SYSTEM SET catalog_sync_target = 'hms_sync_catalog';
   

3. 关闭同步

   -- 置空即断开同步
   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。

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）：

   -- 开启后，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：完整模式——展示所有同步占位表，不做去重。

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

类型映射

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

限制与约束

常见操作示例

1. 完整流程

   -- 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. 清理环境

   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;
   

配置项与系统变量速查

常见问题

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 下查看：

SHOW TABLES FROM hms_sync_catalog.<db>;

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