github-fill

OceanBase 查询与读写 MaxCompute（ODPS）数据实战教程

更新时间：2026-06-30 19:47:42

方案	适用场景
ODPS Catalog	快速探查、免建表、元数据自动同步
ODPS 外部表 + Tunnel API	公网访问、兼容性优先
ODPS 外部表 + Storage API	VPC 内高性能分析、HTAP 混合负载

假设前提

本教程假设 MaxCompute（ODPS）中已存在一张标准 TPC-H lineitem 表，其结构与样例数据如下：

+------------+-----------+-----------+--------------+------------+------------------+------------+-------+--------------+--------------+------------+------------+-------------+--------------------+------------+----------------------------------+
| l_orderkey | l_partkey | l_suppkey | l_linenumber | l_quantity | l_extendedprice  | l_discount | l_tax | l_returnflag | l_linestatus | l_shipdate | l_commitdate | l_receiptdate | l_shipinstruct     | l_shipmode | l_comment                        |
+------------+-----------+-----------+--------------+------------+------------------+------------+-------+--------------+--------------+------------+------------+-------------+--------------------+------------+----------------------------------+
|          1 |   1551894 |     76910 |            1 |      17.00 |         33078.94 |       0.04 |  0.02 | N            | O            | 1996-03-13 | 1996-02-12 | 1996-03-22  | DELIVER IN PERSON  | TRUCK      | egular courts above the          |
|          1 |    673091 |     73092 |            2 |      36.00 |         38306.16 |       0.09 |  0.06 | N            | O            | 1996-04-12 | 1996-02-28 | 1996-04-20  | TAKE BACK RETURN   | MAIL       | ly final dependencies: slyly bold|
|          1 |    636998 |     36999 |            3 |       8.00 |         15479.68 |       0.10 |  0.02 | N            | O            | 1996-01-29 | 1996-03-05 | 1996-01-31  | TAKE BACK RETURN   | REG AIR    | riously. regular, express dep    |
|          1 |     21315 |     46316 |            4 |      28.00 |         34616.68 |       0.09 |  0.06 | N            | O            | 1996-04-21 | 1996-03-30 | 1996-05-16  | NONE               | AIR        | lites. fluffily even de          |
|          1 |    240267 |     15274 |            5 |      24.00 |         28974.00 |       0.10 |  0.04 | N            | O            | 1996-03-30 | 1996-03-14 | 1996-04-01  | NONE               | FOB        |  pending foxes. slyly re         |
+------------+-----------+-----------+--------------+------------+------------------+------------+-------+--------------+--------------+------------+------------+-------------+--------------------+------------+----------------------------------+

环境准备

在开始前，请确保满足以下前提条件：

OceanBase 版本 ≥ V4.3.5 BP2（支持 ODPS Catalog）
已部署 JDK 8 或 11，并启用 Java 支持（ob_enable_java_env = true）
已完成 OceanBase JAVA SDK 环境部署，具体部署步骤请参见 OceanBase 数据库 JAVA SDK 环境部署。

方式一：使用 ODPS Catalog 快速探查数据（推荐）

OceanBase 自 V4.3.5 BP2 起支持 ODPS Catalog，可直接访问 MaxCompute 表，无需手动创建外部表。

创建 ODPS Catalog

CREATE EXTERNAL CATALOG odps_lineitem_test
PROPERTIES (
    TYPE = 'ODPS',
    ACCESSID = 'XXXXXXXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'https://service.cn-hangzhou.maxcompute.aliyun.com/api',
    TUNNEL_ENDPOINT = '',
    PROJECT_NAME = 'bigdata_public_dataset'
);

参数说明：

TUNNEL_ENDPOINT 可留空，系统将自动推导。
此方式默认使用 Tunnel API，适用于公网环境，或 OBServer 与 ODPS 位于不同 VPC 的场景。
bigdata_public_dataset：详细数据集地址参见公开数据集概述。

查询数据验证

SET CATALOG odps_lineitem_test;

USE odps_lineitem_test.test_db;

SELECT * FROM lineitem LIMIT 5;

预期结果：返回与源表完全一致的 5 行数据。

优势：

自动同步表结构与分区信息。
无需定义列类型，避免人工映射错误。
适合快速数据探查与元数据验证。

方式二：创建 ODPS 外部表（精细控制场景）

当需要显式控制列映射、启用 Storage API 或兼容旧版本时，可创建 ODPS 外部表。

切换到 OceanBase 的数据库

如果您先尝试了 方式一，那么此时需要先切换回到 OceanBase 的数据库。

USE internal.test;

创建外部表

CREATE EXTERNAL TABLE external_lineitem (
    l_orderkey      BIGINT,
    l_partkey       BIGINT,
    l_suppkey       BIGINT,
    l_linenumber    BIGINT,
    l_quantity      DECIMAL(15,2),
    l_extendedprice DECIMAL(15,2),
    l_discount      DECIMAL(15,2),
    l_tax           DECIMAL(15,2),
    l_returnflag    CHAR(1),
    l_linestatus    CHAR(1),
    l_shipdate      DATE,
    l_commitdate    DATE,
    l_receiptdate   DATE,
    l_shipinstruct  CHAR(25),
    l_shipmode      CHAR(10),
    l_comment       VARCHAR(44)
)
PROPERTIES (
    TYPE = 'ODPS',
    ACCESSID = 'XXXXXXXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'https://service.cn-hangzhou.maxcompute.aliyun.com/api',
    TUNNEL_ENDPOINT = '',
    PROJECT_NAME = 'bigdata_public_dataset',
    SCHEMA_NAME = 'tpch_10g',
    TABLE_NAME = 'lineitem',
    QUOTA_NAME = '',
    COMPRESSION_CODE = 'zstd'
);

关键配置说明：

COMPRESSION_CODE = 'zstd'：启用压缩以提升网络传输效率。
默认使用 Tunnel API，适用于通用网络环境。
列定义需与 MaxCompute 表一致。
bigdata_public_dataset：详细数据集地址参见公开数据集概述。

验证与进阶操作

验证外部表读取

SELECT * FROM external_lineitem LIMIT 5;

预期输出：返回与源表完全一致的 5 行数据。

（可选）导入内部表加速分析

若需高频查询或复杂聚合，可将数据导入 OceanBase 内部表：

-- 创建内部表
CREATE TABLE ob_lineitem LIKE external_lineitem;

-- 批量导入
INSERT INTO ob_lineitem SELECT * FROM external_lineitem;

-- 验证
SELECT COUNT(*) FROM ob_lineitem;

（可选）导出数据回 MaxCompute

使用 INSERT OVERWRITE 语句将 OceanBase 数据写回 MaxCompute：

-- 假设已创建目标外部表 lineitem_target
INSERT OVERWRITE lineitem_target
SELECT * FROM ob_lineitem
WHERE l_shipdate >= '1996-01-01';

使用限制：

目标表与源表的列数、顺序、类型必须完全一致。
仅支持 INSERT INTO / OVERWRITE ... SELECT 语法。

补充：API 模式选择指南

OceanBase 支持两种 MaxCompute 访问模式，应根据部署环境选择：

场景一：VPC 内高性能访问（推荐）

适用条件：OceanBase 部署在阿里云 ECS，且与 MaxCompute 同地域 VPC。

CREATE EXTERNAL TABLE lineitem1 ( /* 字段同上 */ )
PROPERTIES (
    TYPE = 'ODPS',
    ACCESSID = 'XXXXXXXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'https://service.cn-hangzhou-vpc.maxcompute.aliyun-inc.com/api',
    PROJECT_NAME = 'test_obqa',
    TABLE_NAME = 'lineitem1',
    QUOTA_NAME = 'pay-as-you-go',  -- 必须为按量付费
    API_MODE = 'storage_api',      -- 启用 Storage API
    SPLIT = 'byte',                -- 按字节分片（行大小不均时推荐）
    COMPRESSION_CODE = 'zstd'
);

优势：

支持谓词下推与列裁剪。
低延迟、高吞吐。
自动并行分片。

场景二：公网或通用环境（兼容优先）

CREATE EXTERNAL TABLE lineitem ( /* 字段同上 */ )
PROPERTIES (
    TYPE = 'ODPS',
    ACCESSID = 'XXXXXXXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'https://service.cn-hangzhou.maxcompute.aliyun.com/api',
    PROJECT_NAME = 'bigdata_public_dataset',
    SCHEMA_NAME = 'tpch_10g',
    TABLE_NAME = 'lineitem',
    COMPRESSION_CODE = 'zstd'
    -- 默认使用 Tunnel API
);

优势：

无需 VPC 网络配置。
兼容所有部署环境。
配置简单，快速上手。

更多信息，参考 ODPS 外部表。