---
title: "Catalog 数据手动同步 - OceanBase AI 数据库 V4.6.3 | OceanBase 文档中心"
description: Catalog 数据手动同步 Catalog 数据手动同步通过 SYNC CATALOG 语句实现，用于在开启 Catalog 同步的前提下，将 OceanBase AI 数据库 Internal catalog 中的库表元数据手动同步到 HMS（Hive Metastore）侧，支持全量同步、按数据库同步和按表同步…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

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

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

# Catalog 数据手动同步

更新时间：2026-11-16 20:22:57

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

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 数据自动同步](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088335)。

## 使用场景

- 同步补偿存量表：将开启同步前已创建的内部表手动同步到 HMS 侧，无需删表重建。
 - 失败兜底重试：自动同步因网络抖动等原因失败后，手动执行同步作为兜底。
 - 按需同步：支持同步全部库表、指定数据库下的所有表、或仅同步指定的表。

## 语法

```sql
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 数据自动同步](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088335)。
 - `catalog_sync_target` 指向的 HMS Catalog 有效且可访问。

#### 注意

执行 `SYNC CATALOG` 时，目标 HMS Catalog 需与配置项 `catalog_sync_target` 指定的 Catalog 保持一致。

## 使用示例

1. 创建同步目标 Catalog。

   更多语法细节，请查阅[CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007091124)。

   ```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. 同步 Internal catalog 下所有支持同步的库表。

   ```sql
   SYNC CATALOG *.*;

   ```
 4. 同步指定数据库 `db1` 下的所有内部表。

   ```sql
   SYNC CATALOG db1.*;

   ```
 5. 同步指定表 `db1` 数据库下的 `t1` 表。

   ```sql
   SYNC CATALOG db1.t1;

   ```

## 常见问题

- Q: `SYNC CATALOG` 会同步表中的实际数据吗？

  不会。`SYNC CATALOG` 仅同步元数据，以及占位表的分区定义和分区值，不同步表中的实际数据。
 - Q: `SYNC CATALOG *.*` 执行失败后重新执行，已同步成功的对象会被重复创建吗？

  不会。已同步成功的对象再次同步时按远端冲突处理规则处理：属于当前本地表对应的占位表会使用本地最新 Schema 更新，不会重复创建。
 - Q: 为什么显式指定某个表执行同步时报错？

  可能原因包括：指定了系统数据库、隐藏数据库、索引表、辅助表、视图等不支持同步的对象；或指定的库或表不存在。可使用批量同步方式自动跳过不支持的对象。

## 相关文档

- [Catalog 数据自动同步](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088335)
 - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007091124)

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