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

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

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

# Catalog 与外部表

更新时间：2026-06-24 17:02:52

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.5/zh-CN/620.obap/400.data-lake/200.data-lake-integration/150.catalog-externaltable.md)  

## 功能简介

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

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

OceanBase 自 V4.3.5 BP2 起支持 ODPS Catalog。通过 Catalog，可查询 MaxCompute（ODPS）中的表；查询时可与 internal Catalog 中的内表进行联邦分析。

#### 说明

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

## 部署与环境依赖

| 项目 | 说明 |
| --- | --- |
| 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-1000000003503270)。 |

## Catalog 与外部表的关系

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

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

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

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

**选型说明：**

- Catalog 适用于数据源已在 MaxCompute 中注册的场景；OceanBase 通过 Catalog 读取元数据，再访问远端表。
 - 显式外部表适用于按路径访问 CSV / Parquet / ORC 文件，或通过 MaxCompute API 映射单张 ODPS 表等场景。

#### 注意

Catalog 是对底层数据的元数据抽象，不是存储位置本身。若需按路径直接访问未注册到 Catalog 的文件，应使用 `CREATE EXTERNAL TABLE ... LOCATION` 方式。

## Catalog 类型

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

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

### 内部 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-1000000002977502) 创建。SQL 参考当前以 **ODPS Catalog** 为正式语法；参数说明参见：

- [ODPS Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005066782)

## 创建与访问 Catalog

### 创建 External Catalog

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

### 查看 Catalog

```sql
SHOW CATALOGS;

```

### 切换 Catalog 与跨 Catalog 查询

引用表时遵循以下规则：

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

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

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

SELECT * FROM odps_catalog.odps_db.odps_table;

SELECT o.*, i.*
FROM odps_catalog.odps_db.odps_table o
JOIN internal.ap_db.ap_table i ON o.id = i.id;

```

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

```sql
SET CATALOG odps_catalog;
USE odps_db;

SELECT o.*, i.*
FROM odps_table o
JOIN internal.ap_db.ap_table i ON o.id = i.id;

```

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

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

```

#### 说明

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

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

## Catalog 支持范围

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

### ODPS Catalog

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

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

## 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 权限与数据访问权限相互独立。Catalog 层负责获取远端元数据，数据访问层负责访问 MaxCompute 等远端存储，两层认证需分别配置。

**权限验证示例：**

```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-1000000002014595)
 - [`oceanbase.DBA_OB_USERS`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002014826) / [`CDB_OB_USERS`](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002014801)

## 外部表

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

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

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

OceanBase 支持以下外部表类型：

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

## 相关文档

### 接入文档

- [ODPS Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005066782)
 - [ODPS 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006319716)
 - [文件外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005066785)
 - [URL 外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005066787)
 - [数据湖概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006319714)

### 参考文档

- [Catalog 概述（参考）](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004840206)
 - [创建 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004840207)
 - [查看 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004840208)
 - [删除 Catalog](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004840209)
 - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002977502)
 - [SET CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002977504)
 - [DROP CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002977503)

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