---
title: "ODPS Catalog 和外部表 - OceanBase Database AI V4.6.2 | OceanBase 文档中心"
description: ODPS Catalog 和外部表 ODPS Catalog OceanBase Database AI 支持 ODPS Catalog 。通过 ODPS Catalog，用户可直接查询阿里云 MaxCompute（原 ODPS） 中的表数据，无需手动创建外部表映射，适用于离线数仓查询加速场景。 免 ETL 查询：直…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

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

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*inJjSpyNOjUAAAAAHtAAAAgAeiGDAQ/original) OceanBase Database AIV 4.6.2

# ODPS Catalog 和外部表

更新时间：2026-08-18 15:43:15

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.2/zh-CN/300.data-pipeline/200.data-delivery/300.data-lake/200.data-lake-integration/300.data-lake-odps.md)  

## ODPS Catalog

OceanBase Database AI 支持 **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 Database AI JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779068)。

### 使用前提

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`。 |
| SPLIT | 条件 | 使用 `storage_api` 时指定分片方式：`byte` 或 `row`。 |
| REGION | 是 | MaxCompute 开通地域 |

### API_MODE

支持 API_MODE 和 SPLIT 参数：

- tunnel_api（默认值）：

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

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

     - 网络依赖性：要求 OceanBase Database AI 与 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 Database AI 与 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;

```

## ODPS 外部表

OceanBase Database AI 支持通过 `CREATE EXTERNAL TABLE` 创建 ODPS 外部表，访问阿里云 MaxCompute（原 ODPS）中的表数据（默认使用 Tunnel API）。

与 [文件外部表](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779564) 不同，ODPS 外部表不通过 `LOCATION` 指向文件路径，而是通过 MaxCompute API 连接远端 ODPS 项目中的表。OceanBase 在本地保存外表定义与列映射，查询或写入时调用 ODPS Storage API 或 Tunnel API 与 MaxCompute 交互。

#### 说明

若需访问整个 MaxCompute 项目下的多张表且无需逐表建外表，可使用上文中的 ODPS Catalog。本文介绍单表级别的 ODPS 外部表。

### 功能简介

MaxCompute 提供两类与 OceanBase 集成的数据访问接口：

| API | 用途 | 主要特点 |
| --- | --- | --- |
| **Storage API** | 数据服务接口 | 支持分区过滤、谓词下推等细粒度访问 |
| **Tunnel API** | 数据上传/下载接口 | 面向批量全表导入导出，无服务端过滤能力 |

创建 ODPS 外部表时，通过 `PROPERTIES` 中的 `API_MODE` 指定使用的 API。两种 API 的对比如下：

| 维度 | Storage API | Tunnel API |
| --- | --- | --- |
| 数据过滤 | 支持通过 SQL 条件过滤，仅传输所需数据 | 不支持服务端过滤，需全量传输 |
| 分片策略 | 自动分片（按字节或行数） | 手动分片，配置相对复杂 |
| 网络要求 | 需与 MaxCompute 部署在同一 VPC，并开通 Storage API 权限 | 无特殊 VPC 要求 |
| 适用场景 | 分区表条件查询、需减少传输数据量的分析场景 | 未开通 Storage API 或兼容性场景 |

### 支持的操作

| 操作 | 支持情况 |
| --- | --- |
| `SELECT` 查询 | 支持 |
| `INSERT INTO` / `INSERT OVERWRITE` | 支持 |
| 非分区表与分区表 | 支持 |
| 动态分区识别 | 支持（需配置 `AUTO_REFRESH`） |
| `UPDATE` / `DELETE` | 不支持 |

### 前提条件

1. **Java 环境**：MaxCompute SDK 基于 Java，需部署 Java SDK 环境，参见 [部署 OceanBase Database AI JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779068)。
 2. **MaxCompute 凭证**：
      - RAM 用户的 AccessKey ID / AccessKey Secret（建议最小权限）
      - MaxCompute 服务 Endpoint（含地域信息）
      - 使用 Storage API 时，需在同一 VPC 内且已开通 Storage API 权限
 3. **表权限**：RAM 用户对目标 MaxCompute 项目及表具备相应读写权限。

### ODPS 外表访问模型

ODPS 外部表的访问链路如下：

| 组件 | 作用 |
| --- | --- |
| **OceanBase 外表定义** | 保存列映射、分区定义及 ODPS 连接参数 |
| **MaxCompute API** | Storage API 或 Tunnel API，负责与 MaxCompute 服务端通信 |
| **MaxCompute 表** | 远端实际存储数据的表（非文件路径外表） |

OceanBase 不缓存 MaxCompute 表的全量数据。查询时通过 API 拉取所需数据；写入时通过 API 将数据写入 MaxCompute 表。

### 创建 ODPS 外部表

#### 非分区表

**自动列映射**

未指定生成列时，OceanBase 按列定义顺序映射为 `external$tablecol1`、`external$tablecol2` 等。

```sql
CREATE EXTERNAL TABLE t1 (c1 INT, c2 INT)
PROPERTIES = (
    TYPE = 'ODPS',
    ACCESSID = '*****',
    ACCESSKEY = '*****',
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    PROJECT_NAME = 'odps_project',
    SCHEMA_NAME = '',
    TABLE_NAME = 't1',
    QUOTA_NAME = '',
    COMPRESSION_CODE = '',
    API_MODE = {"tunnel_api"}
);

```

**显式列映射（推荐）**

```sql
CREATE EXTERNAL TABLE t1 (
    c1 INT AS (external$tablecol1),
    c2 INT AS (external$tablecol2)
)
PROPERTIES = (
    TYPE = 'ODPS',
    ACCESSID = '*****',
    ACCESSKEY = '*****',
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    PROJECT_NAME = 'odps_project',
    SCHEMA_NAME = '',
    TABLE_NAME = 't1',
    QUOTA_NAME = '',
    COMPRESSION_CODE = 'lz4',
    API_MODE = {"tunnel_api"}
);

```

#### 说明

`AS (external$tablecolx)` 用于指定映射到 MaxCompute 表的第 x 列普通列（非分区列），序号从 1 开始。若未指定生成列，则按列定义顺序自动递增编号。

#### 分区表

分区列须使用 `metadata$partition_list_colX` 显式声明，且 `PARTITION BY` 子句须与 MaxCompute 表分区结构一致。

```sql
CREATE EXTERNAL TABLE t2 (
    c1 INT,
    c2 INT,
    c3 VARCHAR(20) AS (metadata$partition_list_col1),
    c4 VARCHAR(20) AS (metadata$partition_list_col2)
)
PROPERTIES = (
    TYPE = 'ODPS',
    ACCESSID = '*****',
    ACCESSKEY = '*****',
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    PROJECT_NAME = 'odps_project',
    SCHEMA_NAME = '',
    TABLE_NAME = 't2',
    QUOTA_NAME = '',
    COMPRESSION_CODE = '',
    API_MODE = {"tunnel_api"}
)
PARTITION BY (c3, c4);

```

#### 说明

- `metadata$partition_list_colx` 用于映射 MaxCompute 表的第 x 个分区列，序号从 1 开始，不可省略。
 - MaxCompute 表的分区列与 OceanBase 外表的分区列须一一对应，个数一致。

**错误示例**：分区列未使用 `metadata$partition_list_colX`，将被当作普通列处理，导致查询失败。

```sql
-- 错误写法
CREATE EXTERNAL TABLE t2 (
    c1 INT,
    c2 INT,
    c3 VARCHAR(20),   -- 缺少 AS (metadata$partition_list_col1)
    c4 VARCHAR(20)    -- 缺少 AS (metadata$partition_list_col2)
)
PROPERTIES ( ... )
PARTITION BY (c3, c4);

```

### 关键参数说明（PROPERTIES）

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| TYPE | 是 | 固定为 `'ODPS'` |
| ACCESSID / ACCESSKEY | 是 | RAM 用户 AccessKey（建议最小权限） |
| ENDPOINT | 是 | MaxCompute 服务地址（含地域） |
| PROJECT_NAME | 是 | MaxCompute 项目名 |
| TABLE_NAME | 是 | MaxCompute 表名 |
| SCHEMA_NAME | 否 | 表位于 Schema 下时需指定 |
| ACCESSTYPE | 否 | 账号类型：`aliyun`（默认）/ `sts` / `app` |
| STSTOKEN | 条件 | 仅 `ACCESSTYPE = 'sts'` 时必填 |
| QUOTA_NAME | 否 | 指定计算资源配额 |
| COMPRESSION_CODE | 否 | 压缩格式：`zlib` / `zstd` / `lz4` / `odps_lz4` |
| API_MODE | 是 | `{"tunnel_api"}` 或 `{"storage_api"}` |
| SPLIT | 条件 | 使用 `storage_api` 时指定分片方式：`byte` 或 `row` |

完整语法参见 [CREATE EXTERNAL TABLE](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006781455)。

### 查询 MaxCompute 数据

查询 ODPS 外部表与查询普通表语法相同。

```sql
SELECT * FROM t1;

-- 指定并行度
SELECT /*+ PARALLEL(N) */ * FROM t1;

```

### 写入 MaxCompute 数据

OceanBase 支持通过 `INSERT INTO` 或 `INSERT OVERWRITE` 向 ODPS 外部表写入数据。

```sql
-- 追加写入
INSERT INTO external_table_name
SELECT column_list FROM source_table [WHERE ...];

-- 覆盖写入
INSERT OVERWRITE external_table_name
SELECT column_list FROM source_table [WHERE ...];

```

#### 非分区表写入示例

```sql
INSERT INTO t1 SELECT * FROM t1_;

INSERT /*+ PARALLEL(N) */ INTO t1 SELECT * FROM t1_;

-- 覆盖写入
INSERT OVERWRITE t1 SELECT * FROM t1_;

-- 指定列写入
INSERT INTO t1 (c1) SELECT c1 FROM t1_;

```

#### 分区表写入示例

```sql
INSERT INTO t2 PARTITION (c3 = 'abc', c4 = 'def') SELECT * FROM t2_;

INSERT OVERWRITE t2 PARTITION (c3 = 'abc', c4 = 'def') SELECT * FROM t2_;

```

写入时要求列数与顺序与外表定义一致。更多语法说明，参见 [插入数据](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779354)。

### 分区信息同步策略

通过 `AUTO_REFRESH` 控制 MaxCompute 分区元数据的刷新方式：

| 策略 | 说明 | 适用场景 |
| --- | --- | --- |
| `IMMEDIATE` | 每次查询时自动刷新 | 分区频繁变化 |
| `OFF` | 仅手动刷新 | 静态分区表 |
| `INTERVAL` | 通过定时任务刷新 | 中等频率更新 |

**启用即时刷新示例**

```sql
CREATE EXTERNAL TABLE t2 ( ... )
AUTO_REFRESH = IMMEDIATE
PROPERTIES ( ... )
PARTITION BY (c3, c4);

```

**手动刷新**

```sql
ALTER EXTERNAL TABLE t2 REFRESH;

```

### 类型映射与限制

#### 类型映射

OceanBase 与 MaxCompute 之间的数据类型映射，参见[数据类型映射](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779592)

#### 时区处理

MaxCompute 时间类型（如 `DATETIME`）无显式时区信息。OceanBase 默认将其视为与自身会话时区一致。建议 OceanBase 与 MaxCompute 使用相同时区（如 `Asia/Shanghai`）。

#### 使用限制

| 限制项 | 说明 |
| --- | --- |
| 模式 | 仅支持 MySQL 模式 |
| 复杂类型 | 不支持 `ARRAY<MAP<STRING, BIGINT>>` 等嵌套复杂类型 |
| 写入列约束 | 写入时列数与顺序须与外表定义严格一致 |
| 性能 | 查询速度受 MaxCompute API 配额与网络带宽影响 |

### 注意事项

1. **ODPS 外表与文件外表的区别**：ODPS 外部表通过 MaxCompute API 访问远端表，不使用 `LOCATION` 文件路径；文件外部表用于访问 S3 及兼容 S3 协议的对象存储、HDFS 等路径下的 CSV/Parquet/ORC 文件。
 2. **ODPS 外表与 ODPS Catalog 的区别**：外表针对单表映射；Catalog 连接整个 MaxCompute 项目，自动同步元数据。参见 ODPS Catalog。
 3. **API 选择**：需减少传输数据量、支持条件过滤时优先使用 Storage API；未开通 Storage API 或网络不满足 VPC 要求时使用 Tunnel API。
 4. **凭证安全**：建议使用 RAM 子账号并遵循最小权限原则；避免在 SQL 中硬编码明文 AccessKey。

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