ODPS外部テーブル

OceanBaseデータベースは、V4.3.5 BP1 以降（MySQLモード）で CREATE EXTERNAL TABLE を使用してODPS外部テーブルを作成し、Alibaba Cloud MaxCompute（旧ODPS）のテーブルデータにアクセスすることをサポートしています（デフォルトではTunnel APIを使用）。

ファイル外部テーブルとは異なり、ODPS外部テーブルは LOCATION でファイルパスを指定するのではなく、MaxCompute APIを通じてリモートのODPSプロジェクト内のテーブルに接続します。OceanBaseはローカルに外部テーブルの定義と列マッピングを保存し、クエリや書き込み時にODPS Storage APIまたはTunnel APIを呼び出してMaxComputeとやり取りします。

機能の概要

MaxComputeは、OceanBaseと連携した2種類のデータアクセスインターフェースを提供します。

ODPS外部テーブルを作成する際に、PROPERTIES の API_MODE を使用して使用するAPIを指定します。2つのAPIの比較は以下の通りです：

サポートされる操作

前提条件

1. バージョンとモード：OceanBase V4.3.5 BP1以降（MySQLモードのテナント）。API_MODE = 'storage_api' または SPLIT を使用する場合は V4.3.5 BP3 以上が必要です。
2. Java環境：MaxCompute SDKはJavaベースであるため、Java SDK環境をデプロイする必要があります。OceanBaseデータベースJAVA SDK環境のデプロイを参照してください。
3. MaxCompute資格証明：
   • RAMユーザーのAccessKey ID / AccessKey Secret（最小権限を推奨）
   • MaxComputeサービスのEndpoint（リージョン情報を含む）
   • Storage APIを使用する場合は、同一VPC内であり、Storage API権限が有効である必要があります
4. テーブル権限：RAMユーザーが対象のMaxComputeプロジェクトおよびテーブルに対して適切な読み書き権限を持っていること。

ODPS外部テーブルアクセスモデル

ODPS外部テーブルへのアクセスパスは以下の通りです：

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

パーティションテーブル

パーティション列は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を使用しない場合、通常の列として処理され、クエリが失敗します。

-- 誤った書き方
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）

完全な構文については、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のパーティションメタデータのリフレッシュ方式を制御します。

即時リフレッシュを有効にする例

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）を使用することを推奨します。

使用上の制限

注意点

1. ODPS外部テーブルとファイル外部テーブルの違い：ODPS外部テーブルはMaxCompute APIを介してリモートテーブルにアクセスし、LOCATION ファイルパスは使用しません。ファイル外部テーブルは、OSS、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をハードコーディングすることは避けてください。

関連ドキュメント

• ODPS Catalog
• Catalogと外部テーブル
• CREATE EXTERNAL TABLE
• データ型マッピング