---
title: "ODPS Catalog - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: ODPS Catalog OceanBase 从 V4.3.5 BP2 起（MySQL 模式）支持 ODPS Catalog 。 通过 ODPS Catalog，用户可直接查询阿里云 MaxCompute（原 ODPS） 中的表数据，无需手动创建外部表映射，适用于离线数仓查询加速场景。 免 ETL 查询：直接访问 M…
---
切换语言

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

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

# ODPS 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/300.odps/100.odps-catalog.md)  

OceanBase 从 **V4.3.5 BP2** 起（MySQL 模式）支持 **ODPS Catalog**。

通过 ODPS Catalog，用户可直接查询阿里云 MaxCompute（原 ODPS） 中的表数据，无需手动创建外部表映射，适用于离线数仓查询加速场景。

- 免 ETL 查询：直接访问 MaxCompute 表，省去建外表的繁琐操作。
 - 统一元数据：自动同步 ODPS 项目中的数据库与表结构。
 - 跨源 JOIN：支持与 OceanBase 内部表联合查询。

## 支持能力

- **只读查询**：支持 `SELECT`、`JOIN`、`GROUP BY` 等分析操作。
 - **不支持写入**：禁止 `INSERT`、`UPDATE`、`DROP TABLE` 等 DML/DDL。
 - **分区裁剪/列裁剪**：自动下推过滤条件，减少数据传输量。

## 限制说明

| 限制项 | 说明 |
| --- | --- |
| 复杂数据类型 | 不支持 `ARRAY<MAP<STRING, BIGINT>>` 等嵌套复杂类型 |
| 性能依赖 | 查询速度受 MaxCompute Tunnel 配额与网络带宽影响 |
| 环境依赖 | 需部署 Java SDK（因 MaxCompute SDK 基于 Java） |

环境依赖的详细信息，参见 [部署 OceanBase 数据库 JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005681933)。

## 使用前提

1. **权限要求**

      - 当前用户需具备 `CREATE CATALOG`、`USE CATALOG` 等 Catalog 相关权限（**MySQL 模式**）。Catalog 能力当前仅 MySQL 模式支持。
 2. **访问凭证**

      - 已获取 MaxCompute 的 AccessKey ID / Secret（或 STS Token）
      - OceanBase 集群可访问 MaxCompute Endpoint 与 Tunnel Endpoint
 3. **授权配置**

      - MaxCompute 项目已对 OceanBase 使用的 RAM 用户授权（至少 `Read` 权限），参见 [MaxCompute 开放存储概述](https://help.aliyun.com/zh/maxcompute/user-guide/overview-1#cabfa502c288o)。

## 创建 ODPS Catalog 语法

```sql
CREATE EXTERNAL CATALOG [IF NOT EXISTS] catalog_name
PROPERTIES (
    TYPE = 'ODPS',
    [ACCESSTYPE = 'aliyun' | 'sts' | 'app'],
    ACCESSID = 'your-access-id',
    ACCESSKEY = 'your-access-key',
    [STSTOKEN = 'your-sts-token'],  -- 仅 ACCESSTYPE='sts' 时需要
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    TUNNEL_ENDPOINT = 'http://dt.cn-hangzhou.maxcompute.aliyun.com',
    PROJECT_NAME = 'your_odps_project',
    [QUOTA_NAME = 'your_quota'],
    [COMPRESSION = 'zlib' | 'zstd' | 'lz4' | 'odps_lz4'],
    API_MODE = {"tunnel_api" | "storage_api"},
    SPLIT = {"byte" | "row"},
    REGION = 'region_name'
);

```

## 参数说明

| 参数 | 是否必填 | 说明 |
| --- | --- | --- |
| TYPE | 是 | 固定为 `'ODPS'` |
| ACCESSTYPE | 否 | 账号类型，默认 `aliyun`；支持 `aliyun` / `sts` / `app` |
| ACCESSID / ACCESSKEY | 是 | RAM 用户的 AccessKey（非主账号 AK） |
| STSTOKEN | 条件 | 仅 `ACCESSTYPE = 'sts'` 时必填 |
| ENDPOINT | 是 | MaxCompute 服务入口（含地域） |
| TUNNEL_ENDPOINT | 是 | Tunnel 服务地址，用于高效拉取数据 |
| PROJECT_NAME | 是 | MaxCompute 项目名（相当于 Database） |
| QUOTA_NAME | 否 | 指定计算资源配额（如有） |
| COMPRESSION | 否 | 数据压缩格式（需与 ODPS 表一致），不设置表示不开启压缩 |
| API_MODE | 否 | 调用 API 模式：`tunnel_api`（默认）或 `storage_api`。V4.3.5 BP3 及以上支持。详见下文。 |
| SPLIT | 条件 | 使用 `storage_api` 时指定分片方式：`byte` 或 `row`。V4.3.5 BP3 及以上支持。 |
| REGION | 是 | MaxCompute 开通地域 |

### API_MODE

对于 OceanBase 数据库 V4.3.5 版本，从 V4.3.5 BP3 版本开始支持 API_MODE 和 SPLIT 参数：

- tunnel_api（默认值）：

     - 无需特殊网络配置：适用于所有部署场景，无需 OceanBase 数据库与 MaxCompute 位于同一 VPC（虚拟私有云）内。
     - 无需 MaxCompute 额外权限：仅需提供 AccessID 和 AccessKey 即可完成认证，无需开通 MaxCompute Storage API 权限。
     - 适用环境：

           - OceanBase 数据库与 MaxCompute 未部署在同一 VPC 中。
           - 未开通 MaxCompute Storage API。
           - 数据传输对延迟要求较低。
 - storage_api：

     - 网络依赖性：要求 OceanBase 数据库与 MaxCompute 必须部署在同一 VPC 内，以实现低延迟、高吞吐量的数据传输。
     - 权限依赖性：需在 MaxCompute 中开通 Storage API 权限，并确保访问密钥（AccessKey）具备相应权限。
     - 配额要求：当使用 storage_api 模式时，需将 QUOTA 参数设置为 pay-as-you-go（按量付费配额），以确保 Storage API 调用正常计费与执行。详情请参考：[MaxCompute Storage 开放存储概述](https://help.aliyun.com/zh/maxcompute/user-guide/overview-1)。
     - 适用环境：

           - OceanBase 数据库与 MaxCompute 同属一个 VPC 网络。
           - 已开通 MaxCompute Storage API。
           - 数据量极大或对实时性要求较高。

## 创建示例

```sql
CREATE EXTERNAL CATALOG odps_prod
PROPERTIES (
    TYPE = 'ODPS',
    ACCESSID = 'LTAI5tXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    TUNNEL_ENDPOINT = 'http://dt.cn-hangzhou.maxcompute.aliyun.com',
    PROJECT_NAME = 'sales_analytics',
    REGION = 'cn-hangzhou'
);

```

**安全建议**：

- 使用 RAM 子账号 并遵循最小权限原则
 - 避免在 SQL 中硬编码明文 AK，可通过变量或密钥管理服务注入

## 使用方式

### 切换 Catalog

```sql
-- 方式 1：仅切换 Catalog
SET CATALOG odps_prod;

-- 方式 2：同时切换 Catalog 和 Database
USE odps_prod.sales_db;

```

### 查询 ODPS 表

```sql
-- 假如 Catalog 已经切换到 odps_prod，直接查询
SELECT * FROM user_log
WHERE dt = '20250401'
LIMIT 10;

-- 联邦查询（与内部表 JOIN）
SELECT o.order_id, u.city
FROM internal.test_db.orders o
JOIN users u ON o.user_id = u.id;

```

### 元数据操作

```sql
-- 查看表结构
DESC odps_prod.sales_db.user_log;

-- 查看建表语句
SHOW CREATE TABLE odps_prod.sales_db.user_log;

-- 列出当前租户所有 Catalog
SHOW CATALOGS;

-- 查看 Catalog 创建语句
SHOW CREATE CATALOG odps_prod;

```

### 删除 Catalog

```sql
DROP CATALOG IF EXISTS odps_prod;

```

## 相关文档

- [Catalog 与外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326201)
 - [Catalog 概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005683168)
 - [部署 OceanBase 数据库 JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005681933)
 - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686150)

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