Catalog 与外部表

功能简介

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 中的内表进行联邦分析。

部署与环境依赖

Catalog 与外部表的关系

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

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

选型说明：

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

Catalog 类型

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

内部 Catalog

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

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

USE ap_db;
SELECT COUNT(*) FROM user_behavior;

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

外部 Catalog

外部 Catalog 通过 CREATE EXTERNAL CATALOG 创建。SQL 参考当前以 ODPS Catalog 为正式语法；HMS Catalog（V4.4.1+）及 Iceberg 相关的 REST / FILESYSTEM Catalog 参数见下列接入文档，使用前请对照当前集群版本与 SQL 参考是否已更新：

• 通过 Catalog 加载 Hive 表
• ODPS Catalog
• 通过 Catalog 加载 Iceberg 表

创建与访问 Catalog

创建 External Catalog

internal Catalog 无需手动创建。创建外部 Catalog 的语法参见 CREATE EXTERNAL CATALOG；各类型参数说明参见上述接入文档。

查看 Catalog

SHOW CATALOGS;

切换 Catalog 与跨 Catalog 查询

引用表时遵循以下规则：

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

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

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;

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

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;，或在查询中显式指定：

SELECT * FROM odps_catalog.database_name.table_name;

语法说明参见 SET CATALOG 与 查看 CATALOG。

Catalog 支持范围

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

HMS Catalog

ARRAY 类型说明参见 数组元素类型概述。HMS 与 HDFS 认证机制参见 通过 Catalog 加载 Hive 表。

ODPS Catalog

详细参数与 API 模式说明参见 ODPS Catalog。

Catalog 权限管理

Catalog 权限分为两个层级：

MySQL 模式权限

授予全局权限：

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

授予特定 Catalog 权限：

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 等存储上的数据文件，两层认证需分别配置。

权限验证示例：

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

权限查询视图：

• information_schema.USER_PRIVILEGES
• oceanbase.DBA_OB_USERS / CDB_OB_USERS

外部表

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

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

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

OceanBase 支持以下外部表类型：

Iceberg 表不通过 CREATE EXTERNAL TABLE 接入，应使用 External Catalog，参见 通过 Catalog 加载 Iceberg 表。

相关文档

接入文档

• 通过 HMS Catalog 访问 Hive 表
• 通过 Catalog 加载 Iceberg 表
• ODPS Catalog
• ODPS 外部表
• 文件外部表
• URL 外部表
• 数据湖概述

参考文档

• Catalog 概述（参考）
• 创建 Catalog
• 查看 Catalog
• 删除 Catalog
• CREATE EXTERNAL CATALOG
• SET CATALOG
• DROP CATALOG