ODPS Catalog 和外部表 - OceanBase Database AI V4.6.2

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 环境。

使用前提

权限要求
- 当前用户需具备 CREATE CATALOG、USE CATALOG 等 Catalog 相关权限（MySQL 模式）。Catalog 能力当前仅 MySQL 模式支持。
访问凭证
- 已获取 MaxCompute 的 AccessKey ID / Secret（或 STS Token）
- OceanBase 集群可访问 MaxCompute Endpoint 与 Tunnel Endpoint
授权配置
- MaxCompute 项目已对 OceanBase 使用的 RAM 用户授权（至少 Read 权限），参见 MaxCompute 开放存储概述。

创建 ODPS Catalog 语法

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 开放存储概述。
- 适用环境：
  - OceanBase Database AI 与 MaxCompute 同属一个 VPC 网络。
  - 已开通 MaxCompute Storage API。
  - 数据量极大或对实时性要求较高。

创建示例

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

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

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

查询 ODPS 表

-- 假如 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;

元数据操作

-- 查看表结构
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

DROP CATALOG IF EXISTS odps_prod;

ODPS 外部表

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

与文件外部表不同，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`	不支持

前提条件

Java 环境：MaxCompute SDK 基于 Java，需部署 Java SDK 环境，参见部署 OceanBase Database AI JAVA SDK 环境。
MaxCompute 凭证：
- RAM 用户的 AccessKey ID / AccessKey Secret（建议最小权限）
- MaxCompute 服务 Endpoint（含地域信息）
- 使用 Storage API 时，需在同一 VPC 内且已开通 Storage API 权限
表权限：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 等。

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"}
);

显式列映射（推荐）

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 表分区结构一致。

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，将被当作普通列处理，导致查询失败。

-- 错误写法
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。

查询 MaxCompute 数据

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

SELECT * FROM t1;

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

写入 MaxCompute 数据

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

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

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

非分区表写入示例

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_;

分区表写入示例

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

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

写入时要求列数与顺序与外表定义一致。更多语法说明，参见插入数据。

分区信息同步策略

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

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

启用即时刷新示例

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

手动刷新

ALTER EXTERNAL TABLE t2 REFRESH;

类型映射与限制

类型映射

OceanBase 与 MaxCompute 之间的数据类型映射，参见数据类型映射

时区处理

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

使用限制

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

注意事项

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