基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
Catalog 数据手动同步
更新时间:2026-11-16 20:22:57
Catalog 数据手动同步通过 SYNC CATALOG 语句实现,用于在开启 Catalog 同步的前提下,将 OceanBase AI 数据库 Internal catalog 中的库表元数据手动同步到 HMS(Hive Metastore)侧,支持全量同步、按数据库同步和按表同步三种粒度。
说明
OceanBase AI 数据库从 V4.6.3 版本开始支持 SYNC CATALOG 语句。该语句为 OceanBase AI 数据库的扩展语法。
功能概述
在 Unified Catalog 体系下,Catalog 数据自动同步仅对开启同步后新发生的 DDL 生效,开启同步前已创建的存量表不会被自动同步到 HMS 侧;此外,自动同步还可能因网络抖动等原因执行失败。SYNC CATALOG 语句作为自动同步的补充手段,提供手动同步能力。
SYNC CATALOG 仅同步元数据,以及占位表(placeholder)的分区定义和分区值,不同步表中的实际数据。有关 Catalog 数据自动同步的详细介绍,请参见 Catalog 数据自动同步。
使用场景
- 同步补偿存量表:将开启同步前已创建的内部表手动同步到 HMS 侧,无需删表重建。
- 失败兜底重试:自动同步因网络抖动等原因失败后,手动执行同步作为兜底。
- 按需同步:支持同步全部库表、指定数据库下的所有表、或仅同步指定的表。
语法
SYNC CATALOG { *.* | db_name.* | db_name.table_name };
参数说明
| 参数 | 说明 |
|---|---|
*.* |
同步 Internal catalog 下所有支持同步的数据库和表。 |
db_name |
数据库名。db_name.* 表示同步指定数据库下所有支持同步的内部表。 |
table_name |
表名。db_name.table_name 表示仅同步指定的内部表。 |
同步对象范围
SYNC CATALOG 仅同步普通用户数据库和普通用户表,系统数据库、隐藏数据库、索引表、辅助表等对象不参与同步。不同对象在显式指定与批量同步两种方式下的行为如下:
| 对象 | 显式指定(db_name.table_name) |
批量同步(*.* 或 db_name.*) |
|---|---|---|
| 普通用户数据库 | 支持 | 同步 |
| 普通用户表 | 支持 | 同步 |
| 系统数据库 | 报不支持 | 跳过 |
| 隐藏数据库 | 报不支持 | 跳过 |
| 索引表 | 报不支持 | 跳过 |
| 辅助表 | 报不支持 | 跳过 |
| 视图及其他非普通表 | 报不支持 | 跳过 |
| 不存在的库或表 | 报对象不存在 | 不适用 |
远端处理规则
远端数据库处理
| 远端状态 | 处理行为 |
|---|---|
| 同名数据库不存在 | 自动创建 |
| 同名数据库已存在 | 复用现有数据库 |
| 数据库中存在其他远端表 | 保留,不删除 |
| 数据库无法访问 | 同步失败 |
| 数据库创建发生并发冲突 | 重新确认存在后继续 |
远端表冲突处理
| 远端同名表状态 | 处理行为 |
|---|---|
| 不存在 | 创建 OceanBase 占位表 |
| 是当前本地表对应的占位表 | 使用本地最新 Schema 更新 |
| 是普通 Hive/Spark 表 | 报同名对象冲突,不覆盖 |
| 是其他租户的占位表 | 报归属冲突,不覆盖 |
| 是本租户其他本地表的占位表 | 报归属冲突,不覆盖 |
| 占位表标记不完整 | 报非法占位表,不覆盖 |
| 无法确定归属 | 按冲突处理,不覆盖 |
占位表归属判断依据如下属性:
| 属性 | 校验要求 |
|---|---|
ob.type |
必须为 placeholder |
ob.tenant_id |
必须与当前租户一致 |
ob.table_id |
必须与当前本地表一致 |
说明
当前版本的占位表归属校验以 ob.type 校验为主,后续版本将进一步加强校验。
分区处理
仅在远端表确认属于当前本地分区表后,才会执行分区处理,处理规则如下:
| 分区场景 | 处理行为 |
|---|---|
| 本地存在、远端不存在 | 新增分区 |
| 本地和远端均存在且一致 | 不处理 |
| 本地和远端均存在但元数据不同 | 更新分区 |
| 远端存在非 OceanBase 管理的额外分区 | 保留 |
| 分区归属其他租户或其他表 | 报冲突,不修改 |
删除边界
SYNC CATALOG 不会删除远端的额外对象,具体边界如下:
| 同步范围 | 是否删除远端额外对象 |
|---|---|
SYNC CATALOG *.* |
不删除远端额外数据库和表 |
SYNC CATALOG db_name.* |
不删除远端额外表 |
SYNC CATALOG db_name.table_name |
不删除非本表管理的远端对象 |
| 占位表分区对账 | 删除本地已不存在且归属当前表的占位表分区 |
注意
SYNC CATALOG *.* 和 SYNC CATALOG db_name.* 为非原子的尽力执行操作,执行失败时可能已有部分对象同步成功,可在排除故障后重新执行。
失败与重试
| 失败类型 | 处理方式 |
|---|---|
| 网络连接失败 | 内部有限重试 |
| Thrift 通信异常 | 内部有限重试并切换 HMS URI |
| HMS 临时不可用 | 重试耗尽后返回失败 |
| 权限不足 | 不重试,直接失败 |
| 同名对象冲突 | 不重试,直接失败 |
| SQL 最终执行失败 | 排除问题后手动重试 |
使用限制及注意事项
- 仅支持从 Internal catalog 同步到 HMS Catalog。
- 执行前必须已配置
catalog_sync_target,且指向有效的 HMS Catalog。 - 同步过程中不支持修改数据库名或表名。
- 仅同步普通用户数据库和普通用户表,系统数据库、隐藏数据库、索引表、辅助表等不参与同步;显式指定不支持的对象时报错,批量同步时自动跳过。
SYNC CATALOG仅同步元数据,以及占位表的分区定义和分区值,不同步表中的实际数据。
前置条件
已通过
CREATE EXTERNAL CATALOG创建 HMS 类型的 External catalog,并将租户配置项catalog_sync_target指向该 Catalog,即已开启 Catalog 同步。详细操作请参见 Catalog 数据自动同步。catalog_sync_target指向的 HMS Catalog 有效且可访问。
注意
执行 SYNC CATALOG 时,目标 HMS Catalog 需与配置项 catalog_sync_target 指定的 Catalog 保持一致。
使用示例
创建同步目标 Catalog。
更多语法细节,请查阅CREATE EXTERNAL CATALOG。
CREATE EXTERNAL CATALOG hms_sync_catalog PROPERTIES ( TYPE = 'hms', URI = 'thrift://<hms-host>:<port>' );开启同步。
设置同步目标 Catalog,开启后 Internal catalog 的 DDL 将自动同步到 HMS。
ALTER SYSTEM SET catalog_sync_target = 'hms_sync_catalog';同步 Internal catalog 下所有支持同步的库表。
SYNC CATALOG *.*;同步指定数据库
db1下的所有内部表。SYNC CATALOG db1.*;同步指定表
db1数据库下的t1表。SYNC CATALOG db1.t1;
常见问题
Q:
SYNC CATALOG会同步表中的实际数据吗?不会。
SYNC CATALOG仅同步元数据,以及占位表的分区定义和分区值,不同步表中的实际数据。Q:
SYNC CATALOG *.*执行失败后重新执行,已同步成功的对象会被重复创建吗?不会。已同步成功的对象再次同步时按远端冲突处理规则处理:属于当前本地表对应的占位表会使用本地最新 Schema 更新,不会重复创建。
Q: 为什么显式指定某个表执行同步时报错?
可能原因包括:指定了系统数据库、隐藏数据库、索引表、辅助表、视图等不支持同步的对象;或指定的库或表不存在。可使用批量同步方式自动跳过不支持的对象。