Hologres:DLF カタログを使用した Paimon データへのアクセス

外部データベースの使用（推奨）

外部データベースは、DLF カタログを Hologres 内にマッピングすることで、Paimon テーブルのクエリ、管理、ミラーリングを可能にします。以下の 2 つの認証モードをサポートしています。

外部サーバーの使用（レガシ）

外部サーバーアプローチでは、タイムトラベル、ブランチクエリ、データミラーリングはサポートされていません。これらの機能を使用するには、外部データベースを使用してください。

ステップ 1: 外部サーバーの作成

DLF V2.5 以降の場合:

CREATE SERVER IF NOT EXISTS <server_name> FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
  catalog_type 'paimon',
  metastore_type 'dlf-rest',
  dlf_catalog '<dlf_catalog_name>'
);

DLF V1.0 の場合:

CREATE SERVER IF NOT EXISTS <server_name> FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
  dlf_region '',
  dlf_endpoint 'dlf-share.<region>.aliyuncs.com',
  oss_endpoint 'oss-<region_id>-internal.aliyuncs.com',
  dlf_catalog '<dlf_catalog_name>'
);

外部サーバーのその他の操作については、「外部サーバーのその他の操作」をご参照ください。

ステップ 2: 外部テーブルの作成

IMPORT FOREIGN SCHEMA を使用して、DLF データベース内のすべてのテーブルをインポートします。

-- すべてのテーブルをインポート
IMPORT FOREIGN SCHEMA <dlf_db_name>
FROM SERVER <server_name>
INTO <holo_schema_name>
OPTIONS (if_table_exist 'update');

-- 特定のテーブルをインポート
IMPORT FOREIGN SCHEMA <dlf_db_name>
LIMIT TO (<table_name>[, ...])
FROM SERVER <server_name>
INTO <holo_schema_name>
OPTIONS (if_table_exist 'update');

または、CREATE FOREIGN TABLE を使用して単一の外部テーブルを作成します。

CREATE FOREIGN TABLE <foreign_table_name>
(
  <column_name> <data_type>
  [, ...]
)
SERVER <server_name>
OPTIONS
(
  schema_name '<dlf_db_name>',
  table_name '<dlf_table_name>'
);

構文の詳細については、「IMPORT FOREIGN SCHEMA」および「CREATE FOREIGN TABLE」をご参照ください。

クエリ最適化のための統計情報収集

ANALYZE または AUTO ANALYZE を実行してテーブルの統計情報を収集します。クエリ オプテマイザーは、これらの統計情報を使用して最適なクエリプランを構築します。

-- すべての列の統計情報を収集
ANALYZE <ext_database_name>.<ext_schema_name>.<ext_table_name>;

-- 特定の列の統計情報を収集（より正確。フィルター列に使用）
ANALYZE <ext_database_name>.<ext_schema_name>.<ext_table_name>(<col_name>[, <col_name>]);

-- 外部データベースで AUTO ANALYZE を有効化
ALTER EXTERNAL DATABASE <ext_database_name> WITH enable_auto_analyze 'true';

詳細については、「ANALYZE and AUTO ANALYZE」をご参照ください。

タイムトラベルによるクエリ

Hologres V3.2 以降では、タイムスタンプ、バージョン（スナップショット ID）、またはタグによって Paimon テーブルの履歴スナップショットをクエリできます。

利用可能なスナップショットの一覧表示:

SELECT * FROM hologres.hg_list_snapshots('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

スナップショットテーブルは以下のフィールドを返します。

hg_list_versions 関数を使用して、Paimon スナップショットシステムテーブルをクエリすることもできます。Paimon テーブルでは、バージョンはスナップショット ID に対応します。

SELECT * FROM hologres.hg_list_versions('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

利用可能なタグの一覧表示:

SELECT * FROM hologres.hg_list_tags('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

タイムスタンプによるクエリ:

SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>
FOR TIMESTAMP AS OF '<timestamp>';

バージョン（スナップショット ID）によるクエリ:

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR VERSION AS OF '<version>';

タグによるクエリ:

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR TAG AS OF '<tag>';

Hologres V3.2.6 および V4.0.6 以降では、期限切れの Paimon スナップショットに対応するタグからのデータ読み取りがサポートされています。

Paimon システムテーブルの詳細については、「Paimon システムテーブル」をご参照ください。

Paimon ブランチのクエリ

Hologres V3.2 以降では、特定の Paimon ブランチからのデータクエリや、ブランチ内の履歴スナップショットのクエリがサポートされています。

利用可能なブランチの一覧表示:

SELECT * FROM hologres.hg_list_branches('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

ブランチの現在のデータをクエリ:

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>';

Paimon テーブルに scan.fallback-branch が設定されている場合、Hologres は自動的にフォールバックブランチから不足しているパーティションを読み取ります。「ブランチの管理」をご参照ください。

ブランチ内の履歴スナップショットをクエリ:

-- タイムスタンプによる
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>' TIMESTAMP AS OF '<timestamp>';

-- タグによる
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>' TAG AS '<tag_name>';

レイクテーブルミラーリングによるクエリの高速化

Hologres V3.2 以降では、レイクテーブルミラーリングがサポートされています。この機能により、Paimon テーブルのメタデータおよびデータがニアリアルタイムまたはスケジュールされた間隔で Hologres に同期されます。ミラーリングされたデータは Hologres ストレージから提供されるため、クエリの待ち時間が大幅に短縮されます。フルテーブルミラーリングと、パーティションテーブルの部分ミラーリングの両方がサポートされています。

設定の詳細については、「レイクテーブルミラーリング」をご参照ください。

動的テーブルによる継続的更新の使用

動的テーブルは、1 つ以上の Paimon 外部テーブルから集計結果を自動的に処理・保存し、組み込みの更新戦略を提供します。V3.0 以降では、MaxCompute 外部テーブルおよび DLF 外部テーブルを動的テーブルのベーステーブルとして使用できます。

フル更新 — 各更新サイクルで全データを置き換えます。

CREATE DYNAMIC TABLE paimon_dt_table
WITH (
  auto_refresh_mode = 'full',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

増分更新 — 新規または変更されたデータのみを処理します。

CREATE DYNAMIC TABLE paimon_dt_table_incremental
WITH (
  auto_refresh_mode = 'incremental',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

自動更新 — データの変更に基づいて、フル更新または増分更新を自動的に選択します。

CREATE DYNAMIC TABLE paimon_dt_table_auto
WITH (
  auto_refresh_mode = 'auto',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

詳細については、「動的テーブルの概要」をご参照ください。

INSERT INTO

以下の例では、Paimon プライマリキーテーブルを作成し、行を挿入します。

-- Paimon プライマリキーテーブルの作成
CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name> (
  id         BIGINT,
  customer_id BIGINT,
  item       TEXT,
  amount     FLOAT,
  dt         TEXT,
  PRIMARY KEY (id)
)
WITH (
  "table_format"  = 'paimon',
  "file_format"   = 'orc',
  "merge-engine"  = 'deduplicate',  -- 必要に応じて調整
  "bucket"        = '4'             -- 必要に応じて調整
);

-- 行の挿入
INSERT INTO <ext_database_name>.<ext_schema_name>.<ext_table_name>
  (id, customer_id, item, amount, dt)
VALUES
  (1, 1001, 'apple',  3.50, '2025-09-10'),
  (2, 1002, 'banana', 2.00, '2025-09-10'),
  (3, 1003, 'orange', 4.20, '2025-09-11');

INSERT OVERWRITE

以下の例では、パーティション化された Paimon 追加専用テーブルを作成し、パーティションを上書きします。

-- パーティション化された Paimon 追加専用テーブルの作成
CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name> (
  id     BIGINT,
  name   TEXT,
  amount FLOAT8,
  dt     TEXT
)
LOGICAL PARTITION BY LIST(dt)
WITH (
  "table_format" = 'paimon',
  "file_format"  = 'parquet',
  "merge-engine" = 'deduplicate',
  "bucket-key"   = 'id',
  "bucket"       = '2'
);

-- データの上書き
INSERT OVERWRITE <ext_database_name>.<ext_schema_name>.<ext_table_name>
  (id, name, amount, dt)
VALUES
  (1, 'Alice', 100.50, '2025-09-01'),
  (2, 'Bob',   200.00, '2025-09-01'),
  (3, 'Carol', 150.75, '2025-09-02');

UPDATE

UPDATE は、マージエンジンが deduplicate または partial-update の Paimon プライマリキーテーブルでのみサポートされます。プライマリキー列の更新はサポートされていません。

UPDATE <ext_database_name>.<ext_schema_name>.<ext_table_name>
SET amount = 5
WHERE id = 1;

DELETE

DELETE は、マージエンジンが deduplicate または partial-update の Paimon プライマリキーテーブルでのみサポートされます。partial-update テーブルに対して DELETE を実行する前に、partial-update.remove-record-on-delete プロパティを有効にしてください。

DELETE FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>
WHERE id = 2;