---
title: "Catalog 与外部表 - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: Catalog 与外部表 功能简介 OceanBase 支持通过 Catalog（数据目录） 和 外部表（External Table） 访问外部数据。二者均为外部数据访问能力，但元数据管理方式与适用场景不同： Catalog ：连接外部元数据服务（如 Hive Metastore、MaxCompute 项目），自动…
---
切换语言

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

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

# Catalog 与外部表

更新时间：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/400.catalog-externaltable.md)  

## 功能简介

OceanBase 支持通过 **Catalog（数据目录）** 和 **外部表（External Table）** 访问外部数据。二者均为外部数据访问能力，但元数据管理方式与适用场景不同：

- **Catalog**：连接外部元数据服务（如 Hive Metastore、MaxCompute 项目），自动同步库表结构，适用于已有元数据中心的结构化数据源。
 - **外部表**：在 OceanBase 中手工定义表结构与访问路径，适用于文件路径、临时数据或单表映射等场景。

OceanBase 自 V4.3.5 BP2 起支持 ODPS Catalog，V4.4.1 起支持 HMS Catalog。通过 Catalog，可查询 HMS 管理的 Hive 表、Iceberg 表，以及 MaxCompute（ODPS）中的表；查询时可与 internal Catalog 中的内表进行联邦分析。

#### 说明

当前仅 OceanBase MySQL 模式支持 Catalog 能力。

## 部署与环境依赖

| 项目 | 说明 |
| --- | --- |
| 跨机房部署 | 若 HMS 与 OBServer 跨机房部署，元数据获取延迟可能达秒级，影响查询耗时。建议将 HMS 与 OBServer 部署在同一低延迟网络内。 |
| HDFS 存储 | 底层存储为 HDFS 时，需在 OBServer 节点部署 Java 运行环境（JDK 8/11）并启用 Java 支持（`ob_enable_java_env = true`）。详见 [部署 OceanBase JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005681933)。 |

## Catalog 与外部表的关系

OceanBase 访问外部数据时，涉及以下层次，请勿混淆：

| 层次 | 说明 |
| --- | --- |
| 外部存储 | 数据文件的物理位置，如 HDFS、OSS、S3 |
| 元数据 | 库、表、分区等结构信息，可由 HMS、ODPS 或 OceanBase 外表定义维护 |
| 访问入口 | Catalog 或外部表，将外部数据纳入 SQL 查询体系 |

OceanBase 提供两种外部数据访问模式：

| 模式 | 元数据来源 | 适用场景 | 典型用法 |
| --- | --- | --- | --- |
| **Catalog 模式** | 外部元数据服务自动同步 | Hive 数仓、ODPS 项目等已有元数据中心的结构化数据源 | `SET CATALOG my_hms;`   `SELECT * FROM db1.sales;` |
| **显式外部表** | 在 OceanBase 中手工定义 | 文件路径、临时探查、单表 API 映射等非 Catalog 场景 | `CREATE EXTERNAL TABLE t1 (...) LOCATION = 'oss://...';` |

**选型说明：**

- Catalog 适用于数据源已在 HMS 或 MaxCompute 中注册的场景；OceanBase 通过 Catalog 读取元数据，再访问底层存储或远端表。
 - 显式外部表适用于按路径访问 CSV / Parquet / ORC 文件，或通过 MaxCompute API 映射单张 ODPS 表等场景。
 - **Iceberg 表**通过 External Catalog 访问（如 HMS Catalog、REST Catalog），**不属于** `CREATE EXTERNAL TABLE` 的接入方式。详细说明参见 [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326202)。

#### 注意

- Catalog 是对底层数据的元数据抽象，不是存储位置本身。
 - HMS Catalog 仅支持对接 Hive Metastore，无法直接指向任意 HDFS 路径。若需访问未注册到 HMS 的文件，应使用 `CREATE EXTERNAL TABLE ... LOCATION` 方式。

## Catalog 类型

Catalog 是数据库对象的顶层命名空间，用于组织和隔离不同数据源的元数据。OceanBase 支持内部 Catalog 与外部 Catalog：

| Catalog 类型 | 数据源 | 支持表类型 | 典型场景 |
| --- | --- | --- | --- |
| 内部 Catalog（`internal`） | OceanBase 本地存储 | OceanBase 表 | 租户内核心业务数据 |
| ODPS Catalog | 阿里云 MaxCompute | ODPS 表 | 离线数仓分析 |
| HMS Catalog | Hive Metastore | Hive 表、Iceberg 表 | Hadoop 生态集成 |

### 内部 Catalog

每个租户有且仅有一个名为 `internal` 的内部 Catalog，包含该租户内通过 `CREATE DATABASE`、`CREATE TABLE` 等 DDL 创建的对象。internal Catalog 与外部 Catalog 逻辑隔离；不支持创建、删除或重命名 internal Catalog。

- 默认情况下可直接 `USE database;` 访问，无需显式指定 Catalog。
 - 支持完整 DDL/DML；数据存储在 OceanBase 分布式存储引擎中。

```sql
USE ap_db;
SELECT COUNT(*) FROM user_behavior;

-- 显式指定 internal Catalog（可选）
SELECT COUNT(*) FROM internal.ap_db.user_behavior;

```

#### 注意

内部 Catalog 名称为 `internal`，通常可省略。

### 外部 Catalog

外部 Catalog 通过 [`CREATE EXTERNAL CATALOG`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150) 创建。SQL 参考当前以 **ODPS Catalog** 为正式语法；**HMS Catalog**（V4.4.1+）及 Iceberg 相关的 REST / FILESYSTEM Catalog 参数见下列接入文档，使用前请对照当前集群版本与 SQL 参考是否已更新：

- [通过 Catalog 加载 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)
 - [ODPS Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682509)
 - [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326202)

## 创建与访问 Catalog

### 创建 External Catalog

internal Catalog 无需手动创建。创建外部 Catalog 的语法参见 [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150)；各类型参数说明参见上述接入文档。

### 查看 Catalog

```sql
SHOW CATALOGS;

```

### 切换 Catalog 与跨 Catalog 查询

引用表时遵循以下规则：

- 未切换会话上下文时，须使用三段式标识符：`catalog_name.database_name.table_name`
 - 已执行 `SET CATALOG` 和 `USE` 后，可使用简写表名

**方式一：三段式标识符（无需切换上下文）**

```sql
SELECT CURRENT_CATALOG();
SELECT DATABASE();

SELECT * FROM hive_catalog.hive_db.hive_table;

SELECT h.*, o.*
FROM hive_catalog.hive_db.hive_table h
JOIN internal.ap_db.ap_table o ON h.id = o.id;

```

**方式二：切换上下文后使用简写表名**

```sql
SET CATALOG hive_catalog;
USE hive_db;

SELECT h.*, o.*
FROM hive_table h
JOIN internal.ap_db.ap_table o ON h.id = o.id;

```

也可单独执行 `SET CATALOG catalog_name;`，或在查询中显式指定：

```sql
SELECT * FROM odps_catalog.database_name.table_name;

```

#### 说明

- 若未执行 `SET CATALOG` 和 `USE`，直接写 `SELECT * FROM hive_table;` 将在当前 Catalog（如 internal）中查找该表，可能报错。
 - 切换上下文仅影响后续语句，不影响连接或事务状态。

语法说明参见 [SET CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686082) 与 [查看 CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683170)。

## Catalog 支持范围

本节概述各外部 Catalog 的能力边界。创建、认证及 Location 配置等详细说明，参见对应接入文档。

### HMS Catalog

| 项目 | 说明 |
| --- | --- |
| 访问模式 | 只读；不支持 `INSERT`、`UPDATE`、`DROP TABLE` 等 DML/DDL |
| Hive 表 | 支持 ORC、Parquet、TextFile、CSV；复杂类型当前仅支持 Parquet 格式的 ARRAY 类型 |
| Iceberg 表 | 支持 V1 / V2（推荐 Parquet）；支持 Schema Evolution、Partition Transform 等 |
| Hive 版本 | 支持 Hive 1.2.x、2.3.x、3.1.x、4.x；Iceberg 表元数据注册在 HMS 中即可访问 |

ARRAY 类型说明参见 [数组元素类型概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005688102)。HMS 与 HDFS 认证机制参见 [通过 Catalog 加载 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)。

### ODPS Catalog

| 项目 | 说明 |
| --- | --- |
| 支持操作 | `SELECT`、`JOIN`、`GROUP BY` 等分析型查询 |
| 不支持操作 | `INSERT`、`UPDATE`、`DROP TABLE` 等写入或 DDL |
| 查询优化 | 支持分区裁剪与列裁剪条件下推 |

详细参数与 API 模式说明参见 [ODPS Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682509)。

## Catalog 权限管理

Catalog 权限分为两个层级：

| 层级 | 作用范围 |
| --- | --- |
| User Level（全局级） | 所有 Catalog（MySQL 模式中对应 `*.*`） |
| Catalog Level（对象级） | 指定 Catalog |

### MySQL 模式权限

| 权限 | 作用范围 | 用途 |
| --- | --- | --- |
| `CREATE CATALOG` | User Level | 执行 `CREATE` / `DROP EXTERNAL CATALOG` |
| `USE CATALOG` | User Level 或 Catalog Level | `SET CATALOG`、`SHOW CATALOGS`、查询 `catalog.db.table` |

**授予全局权限：**

```sql
GRANT CREATE CATALOG ON *.* TO 'user1';
GRANT USE CATALOG ON *.* TO 'user1' WITH GRANT OPTION;

```

**授予特定 Catalog 权限：**

```sql
GRANT SELECT, USE CATALOG ON CATALOG odps_prod TO 'user1' WITH GRANT OPTION;
REVOKE USE CATALOG ON CATALOG odps_prod FROM 'user1';

```

**补充说明：**

1. 执行 `CREATE EXTERNAL CATALOG` 成功后，创建者自动获得该 Catalog 的 `USE CATALOG` 和 `SELECT` 权限。
 2. Catalog 权限与数据访问权限相互独立。以 HMS 为例，Catalog 层连接 Hive Metastore 获取元数据，Location 层访问 HDFS 等存储上的数据文件，两层认证需分别配置。

**权限验证示例：**

```sql
GRANT SELECT, USE CATALOG ON CATALOG ca1 TO zhangsan WITH GRANT OPTION;
SHOW GRANTS FOR zhangsan;

```

**权限查询视图：**

- [`information_schema.USER_PRIVILEGES`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005684208)
 - [`oceanbase.DBA_OB_USERS`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005684079) / [`CDB_OB_USERS`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683994)

## 外部表

外部表（External Table）在 OceanBase 侧保存表定义与访问路径，数据仍位于外部存储（对象存储、HDFS、MaxCompute 等）。外部表通常为只读，不支持约束与索引。

与 Catalog 模式相比，显式外部表适用于以下场景：

- 按文件路径访问 CSV、Parquet、ORC 等数据，且数据未注册到 HMS
 - 临时探查外部文件，无需预建 Catalog
 - 通过 MaxCompute API 映射单张 ODPS 表（非整个项目）

OceanBase 支持以下外部表类型：

| 类型 | 说明 | 文档 |
| --- | --- | --- |
| 文件外部表 | 访问 OSS、S3、HDFS 等路径下的 CSV、Parquet、ORC 文件 | [文件外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682506) |
| URL 外部表 | 通过 `FILES()` 直接读取外部文件，无需预建外表 | [URL 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682054) |
| ODPS 外部表 | 通过 MaxCompute API 映射单张 ODPS 表 | [ODPS 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326203) |

Iceberg 表不通过 `CREATE EXTERNAL TABLE` 接入，应使用 External Catalog，参见 [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326202)。

## 相关文档

### 接入文档

- [通过 HMS Catalog 访问 Hive 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682510)
 - [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326202)
 - [ODPS Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682509)
 - [ODPS 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326203)
 - [文件外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682506)
 - [URL 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682054)
 - [数据湖概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326199)

### 参考文档

- [Catalog 概述（参考）](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683168)
 - [创建 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683169)
 - [查看 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683170)
 - [删除 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683167)
 - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150)
 - [SET CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686082)
 - [DROP CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686131)

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