ODPS Catalog

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。
• 分区裁剪/列裁剪：自动下推过滤条件，减少数据传输量。

限制说明

环境依赖的详细信息，参见 部署 OceanBase 数据库 JAVA SDK 环境。

使用前提

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 开放存储概述。

创建 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'
);

参数说明

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 开放存储概述。

  • 适用环境：

    • OceanBase 数据库与 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;

相关文档

• Catalog 与外部表
• Catalog 概述
• 部署 OceanBase 数据库 JAVA SDK 环境
• CREATE EXTERNAL CATALOG