すべてのプロダクト
Search
ドキュメントセンター

Realtime Compute for Apache Flink:Paimon SQL コネクタ

最終更新日:Oct 28, 2026

このトピックでは、SQL ジョブで Paimon コネクタを使用する方法について説明します。最良の結果を得るには、コネクタを Paimon カタログと組み合わせて使用します。

背景情報

Apache Paimon は、ストリーミングとバッチの両方に対応した統合データレイクストレージフォーマットであり、高スループットの書き込みと低レイテンシーのクエリをサポートします。Paimon は、Alibaba Cloud E-MapReduce で利用可能な Flink、Spark、Hive、Trino などの一般的なコンピュートエンジンと緊密に統合されています。Apache Paimon を使用すると、HDFS または OSS 上にデータレイクを迅速に構築し、これらのコンピュートエンジンに接続してデータレイク分析を行うことができます。詳細については、Apache Paimon をご参照ください。

カテゴリ

説明

サポートされるタイプ

ソーステーブル、ディメンションテーブル、結果テーブル、およびデータインジェストのターゲット

実行モード

ストリーミングモードとバッチモード

データフォーマット

サポートされていません

監視メトリック

なし

API タイプ

データインジェスト用の SQL と YAML

結果テーブルの更新と削除

はい

主な特徴

Apache Paimon は、以下の主要な機能を提供します:

  • HDFS またはオブジェクトストレージ上に、軽量で低コストのデータレイクを構築します。

  • ストリーミングモードとバッチモードの両方で、大規模なデータセットの読み取りと書き込みを行います。

  • 数分から数秒のデータ鮮度で、バッチクエリと OLAP クエリを実行します。

  • 増分データをインジェストおよび生成し、従来のオフラインデータウェアハウスと最新のストリーミングデータウェアハウスの両方のストレージレイヤーとして機能します。

  • データを事前集計して、ストレージコストと下流の計算負荷を削減します。

  • データの履歴バージョンにアクセスします。

  • データを効率的にフィルターします。

  • スキーマ進化を可能にします。

制限事項と推奨事項

  • Paimon コネクタには、Flink コンピュートエンジン VVR 6.0.6 以降が必要です。

  • 次の表に、Paimon と VVR のバージョン互換性を示します。

    Apache Paimon バージョン

    VVR

    2.0.0

    11.9

    1.3.1

    11.5、11.6、11.7、11.8

    1.3

    11.4

    1.2

    11.2、11.3

    1.1

    11.1

    1.0

    8.0.11

  • 同時書き込みに関するストレージの推奨事項

    複数のジョブが同じ Paimon テーブルに同時に書き込みを行う場合、標準の OSS ストレージ (oss://) を使用すると、アトミックなファイル操作の制限により、コミットの競合やジョブの失敗が時折発生する可能性があります。

    安定した一貫性のある書き込みを行うには、強力なアトミック性を保証するメタデータまたはストレージサービスを使用してください。推奨されるオプションは Data Lake Formation (DLF) で、Paimon のメタデータとストレージの統合管理を提供します。または、OSS-HDFS または HDFS を使用することもできます。

  • 設定変更の反映方法

    Paimon テーブルの設定パラメーターへの変更は、関連するジョブを再起動した後にのみ有効になります。実行中のジョブは、これらの変更を動的にロードしません。

  • 削除されたパーティションの物理的な再利用の遅延

    DROP PARTITION 操作を実行しても、システムは基になる物理データファイルを直ちに削除しません。
    この操作は論理削除を実行します。Paimon は、最新のスナップショットからのみターゲットパーティションのメタデータを削除します。Paimon はタイムトラベル機能をサポートしているため、履歴スナップショットはまだそのパーティションのデータファイルを参照しています。物理データファイルは、パーティションを参照するすべての履歴スナップショットが保持期間の上限に達し、スナップショットの有効期限切れメカニズムによってクリーンアップされた後にのみ、完全に削除されます。

SQL

SQL ジョブで Paimon コネクタをソーステーブルまたは結果テーブルとして使用します。

構文

  • Paimon カタログで Paimon テーブルを作成する場合、connector パラメーターを指定する必要はありません。構文は次のとおりです:

    CREATE TABLE `<YOUR-PAIMON-CATALOG>`.`<YOUR-DB>`.paimon_table (
      id BIGINT,
      data STRING,
      PRIMARY KEY (id) NOT ENFORCED
    ) WITH (
      ...
    );
    説明

    Paimon カタログに Paimon テーブルをすでに作成している場合は、直接使用できます。

  • 別のカタログで Paimon 一時テーブルを作成する場合は、'connector' と 'path' パラメーターを指定する必要があります。構文は次のとおりです:

    CREATE TEMPORARY TABLE paimon_table (
      id BIGINT,
      data STRING,
      PRIMARY KEY (id) NOT ENFORCED
    ) WITH (
      'connector' = 'paimon',
      'path' = '<path-to-paimon-table-files>',
      'auto-create' = 'true', -- 指定されたパスに Paimon テーブルのデータファイルが存在しない場合、自動的に作成されます。
      ...
    );
    説明
    • パスの例: 'path' = 'oss://<bucket>/test/order.db/orders'。.db サフィックスを省略しないでください。Paimon はこのサフィックスに依存してデータベースを識別します。

    • 同じテーブルに書き込む複数のジョブは、同じパス設定を共有する必要があります。

    • 2 つのパス設定が異なる場合、Paimon はそれらを同じテーブルとして認識しません。物理パスが同じであっても、カタログ設定が一致しないと、同時書き込みの競合、コンパクション操作の失敗、データ損失につながる可能性があります。たとえば、Paimon は oss://b/test と oss://b/test/ を、物理的な場所が同じであっても、末尾のスラッシュのために異なるテーブルと見なします。

WITH パラメーター

パラメーター

説明

データ型

必須

デフォルト

備考

connector

テーブルのコネクタを指定します。

String

いいえ

なし

  • Paimon カタログで Paimon テーブルを作成する場合、このパラメーターは必須ではありません。

  • 別のカタログで Paimon 一時テーブルを作成する場合、このパラメーターを paimon に設定する必要があります。

path

テーブルのストレージパス。

String

いいえ

なし

  • Paimon カタログで Paimon テーブルを作成する場合、このパラメーターは必須ではありません。

  • 別のカタログで Paimon 一時テーブルを作成する場合、このパラメーターは HDFS または OSS 内のテーブルのストレージディレクトリを指定します。

auto-create

指定されたパスにテーブルファイルが存在しない場合に、自動的に作成するかどうかを指定します。

ブール値

いいえ

false

有効な値:

  • false (デフォルト): 指定されたパスに Paimon テーブルファイルが存在しない場合、ジョブは失敗します。

  • true: 指定されたパスが存在しない場合、Flink は自動的に Paimon テーブルファイルを作成します。

file.format

データファイルのフォーマット。

String

いいえ

parquet

有効な値:

  • orc

  • parquet

  • avro

  • lance (Realtime Compute for Apache Flink 11.6 以降でサポート)

  • mosaic (Realtime Compute for Apache Flink 11.9 以降でサポート)

bucket

パーティションごとのバケット数。

Integer

いいえ

1

Paimon は bucket-key に基づいてデータをバケットに分散します。

説明

各バケットのデータサイズは 5 GB 未満にすることを推奨します。

bucket-key

バケットキーとして使用される列。

String

いいえ

なし

データをバケットに分散するために使用される列を指定します。

複数の列名はカンマ (,) で区切ります。例: 'bucket-key' = 'order_id,cust_id' は、order_id と cust_id 列に基づいてデータを分散します。

説明
  • このパラメーターが指定されていない場合、Paimon はプライマリキーに基づいてデータを分散します。

  • テーブルにプライマリキーがない場合、Paimon はすべての列の値に基づいてデータを分散します。

changelog-producer

changelog の生成メカニズム。

String

いいえ

none

Paimon は任意の入力ストリームに対して完全な changelog を生成できます。これは、すべての update_after レコードに対応する update_before レコードがあることを意味します。これにより、下流での消費が簡素化されます。有効な値:

  • none (デフォルト): 追加の changelog は生成されません。下流のコンシューマーは引き続きストリーミングモードで Paimon テーブルを読み取ることができますが、changelog は不完全です (対応する update_before レコードなしで update_after レコードのみが含まれます)。

  • input: 入力ストリームを changelog ファイルに書き込み、これが完全な changelog として機能します。

  • full-compaction: 各完全なコンパクション中に完全な changelog を生成します。

  • lookup: 各スナップショットがコミットされる前に完全な changelog を生成します。

changelog プロデューサーの選択方法の詳細については、「Changelog の生成」をご参照ください。

full-compaction.delta-commits

2 つの連続する完全なコンパクション間の最大コミット数。

Integer

いいえ

なし

完全なコンパクションをトリガーする前に許可されるスナップショットコミットの最大数を指定します。

lookup.cache-max-memory-size

Paimon ディメンションテーブルのメモリキャッシュサイズ。

String

いいえ

256 MB

このパラメーターは、ディメンションテーブルのルックアップと lookup changelog プロデューサーの両方のキャッシュサイズを制御します。

merge-engine

同じプライマリキーを持つレコードをマージするメカニズム。

String

いいえ

deduplicate

有効な値:

  • deduplicate: 最新のレコードのみを保持します。

  • partial-update: 既存のレコードを最新のレコードの null でない値で更新します。他の列は変更されません。

  • aggregation: 指定された集計関数を使用して事前集計を実行します。

マージエンジンの詳細な分析については、「マージエンジン」をご参照ください。

partial-update.ignore-delete

削除 (-D) メッセージを無視するかどうかを指定します。

ブール値

いいえ

false

有効な値:

  • true: 削除メッセージを無視します。

  • false: 削除メッセージを処理します。潜在的な IllegalStateException または IllegalArgumentException エラーを防ぐために、sequence.field などのパラメーターを使用して削除を処理する戦略を設定する必要があります。

説明
  • Realtime Compute for Apache Flink 8.0.6 以前では、このパラメーターは merge-engine = 'partial-update' の部分更新シナリオでのみ有効です。

  • Realtime Compute for Apache Flink 8.0.7 以降では、このパラメーターは部分更新以外のシナリオとも互換性があり、ignore-delete パラメーターと同じ機能を持ちます。ignore-delete を代わりに使用することを推奨します。

  • このパラメーターを有効にするかどうかは、ビジネス要件と削除メッセージが期待されるものかどうかに基づいて決定してください。削除メッセージがジョブの意図したセマンティクスと一致しない場合、早期に失敗させることが多くの場合、より良い選択です。

ignore-delete

削除 (-D) メッセージを無視するかどうかを指定します。

ブール値

いいえ

false

有効な値は partial-update.ignore-delete のものと同じです。

説明
  • このパラメーターは、Realtime Compute for Apache Flink 8.0.7 以降でのみサポートされています。

  • このパラメーターは partial-update.ignore-delete と同じ機能を持ちます。ignore-delete を使用し、両方のパラメーターを同時に設定しないことを推奨します。

partition.default-name

デフォルトのパーティション名。

String

いいえ

__DEFAULT_PARTITION__

パーティション列の値が null または空の文字列の場合に使用するパーティション名。

partition.expiration-check-interval

システムが期限切れのパーティションをチェックする頻度。

String

いいえ

1h

詳細については、「自動パーティション有効期限切れの設定方法」をご参照ください。

partition.expiration-time

パーティションが期限切れになるまでの期間。

String

いいえ

なし

パーティションの経過時間がこの値を超えると、パーティションは期限切れになります。デフォルトでは、パーティションは期限切れになりません。

システムのパーティションの経過時間は、そのパーティション値から計算されます。詳細については、「自動パーティション有効期限切れの設定方法」をご参照ください。

partition.timestamp-formatter

時間文字列をタイムスタンプに変換するためのフォーマット文字列。

String

いいえ

なし

パーティション値からパーティションの経過時間を抽出するためのフォーマットを指定します。詳細については、「自動パーティション有効期限切れの設定方法」をご参照ください。

partition.timestamp-pattern

パーティション値を時間文字列に変換するためのフォーマット文字列。

String

いいえ

なし

パーティション値から時間文字列を抽出するためのパターンを指定します。詳細については、「自動パーティション有効期限切れの設定方法」をご参照ください。

scan.bounded.watermark

スキャンの終了を通知する Watermark 値。ソーステーブルは、その Watermark がこの値を超えるとデータの生成を停止します。

Long

いいえ

なし

N/A

scan.mode

Paimon ソーステーブルの消費位置を指定します。

String

いいえ

default

詳細については、「Paimon ソーステーブルの消費位置の設定方法」をご参照ください。

scan.snapshot-id

Paimon ソーステーブルが消費を開始するスナップショットを指定します。

Integer

いいえ

なし

詳細については、「Paimon ソーステーブルの消費位置の設定方法」をご参照ください。

scan.timestamp-millis

Paimon ソーステーブルが消費を開始する時点を指定します。

Integer

いいえ

なし

詳細については、「Paimon ソーステーブルの消費位置の設定方法」をご参照ください。

snapshot.num-retained.max

保持する最近のスナップショットの最大数。

Integer

いいえ

2147483647

この条件または snapshot.time-retained 条件のいずれかが満たされ、かつ snapshot.num-retained.min 条件も満たされた場合に、スナップショットの有効期限切れがトリガーされます。

snapshot.num-retained.min

保持する最近のスナップショットの最小数。

Integer

いいえ

10

N/A

snapshot.time-retained

スナップショットの保持期間。

String

いいえ

1h

この条件または snapshot.num-retained.max 条件のいずれかが満たされ、かつ snapshot.num-retained.min 条件も満たされた場合に、スナップショットの有効期限切れがトリガーされます。

write-mode

Paimon テーブルの書き込みモード。

String

いいえ

change-log

有効な値:

  • change-log: Paimon テーブルは、プライマリキーに基づいて挿入、削除、更新操作をサポートします。

  • append-only: Paimon テーブルは挿入操作のみを受け付け、プライマリキーをサポートしません。このモードは change-log モードよりも効率的です。

書き込みモードの詳細については、「書き込みモード」をご参照ください。

scan.infer-parallelism

Paimon ソーステーブルの並列度を自動的に推論するかどうかを指定します。

ブール値

いいえ

true

有効な値:

  • true: バケット数に基づいて Paimon ソーステーブルの並列度を自動的に推論します。

  • false: Realtime Compute for Apache Flink で設定されたデフォルトの並列度を使用します。エキスパートモードが有効な場合、ジョブは設定された並列度を使用します。

scan.parallelism

Paimon ソーステーブルの並列度。

Integer

いいえ

なし

説明

ジョブの [構成] > [リソース] タブで [リソースモード] が [モード] に設定されている場合、このパラメーターは無視されます。

sink.parallelism

Paimon sink テーブルの並列度。

Integer

いいえ

なし

説明

ジョブの [構成] > [リソース] タブで [リソースモード] が [モード] に設定されている場合、このパラメーターは無視されます。

sink.clustering.by-columns

Paimon sink テーブルへの書き込みのためのクラスタリング列を指定します。

String

いいえ

なし

Paimon append-only テーブル (プライマリキーのないテーブル) の場合、このパラメーターはバッチジョブでのクラスタ化書き込みを有効にします。このプロセスは、指定された列でデータをグループ化することにより、クエリのパフォーマンスを向上させます。

複数の列名はカンマ (,) で区切ります。例: 'col1,col2'。

クラスタリングの詳細については、Apache Paimon 公式ドキュメントをご参照ください。

sink.delete-strategy

システムがリトラクションメッセージ (-D/-U) を正しく処理することを保証するための検証戦略を指定します。

​​

Enum

いいえ

NONE

有効な値と、リトラクションメッセージを処理する際の sink 演算子の期待される動作:

  • NONE (デフォルト): 検証を実行しません。

  • IGNORE_DELETE: sink 演算子は -U および -D メッセージを無視する必要があります。リトラクションは発生しません。

  • NON_PK_FIELD_TO_NULL: sink 演算子は -U メッセージを無視する必要があります。-D メッセージについては、プライマリキーを保持し、他のすべての非プライマリキーフィールドを null に設定します。

    これは主に、複数の sink が同じテーブルに書き込む際の部分更新に使用されます。

  • DELETE_ROW_ON_PK: sink 演算子は -U メッセージを無視する必要がありますが、-D メッセージについてはプライマリキーに対応する行を削除します。

  • CHANGELOG_STANDARD: sink 演算子は -U と -D の両方のメッセージについて、プライマリキーに対応する行を削除する必要があります。

説明
  • このパラメーターは、Realtime Compute for Apache Flink 8.0.8 以降でのみサポートされています。

  • リトラクションに対する実際の sink の動作は、ignore-delete や merge-engine などの他のパラメーターによって決定されます。このパラメーターは、実際の動作が選択された戦略と一致するかどうかを検証するだけです。不一致がある場合、ジョブは修正を提案するエラーメッセージで失敗します。

blob-as-descriptor

Blob 列を読み取るときに Blob 記述子のバイトを出力するかどうかを指定します。

ブール値

いいえ

false

このパラメーターを true に設定すると、クエリは実際の Blob コンテンツの代わりに BlobDescriptor のシリアル化されたバイトを返します。このパラメーターは Blob 署名付き URL 機能と一緒に使用します。テーブル作成時にこのパラメーターを設定する必要はありません。SQL ヒントを使用して読み取り時に動的に設定できます。このパラメーターは VVR 11.9-preview1 以降でサポートされています。

説明

VVR 11.9-preview1 以降でのみサポートされています。

ベクトルテーブルのパラメーター

説明

以下のパラメーターは VVR 11.8 以降でのみサポートされています。

パラメーター

説明

データ型

必須

デフォルト値

備考

ivf.nprobe

検索中にプローブする IVF クラスターの数。

Integer

いいえ

16

値が大きいほど、一般的に再現率は向上しますが、レイテンシーは増加します。

ivf.refine_factor

top_k × refine_factor の IVF 候補を取得し、Paimon テーブルに保存されている元のベクトルを使用して再ランク付けします。

Float

いいえ

無効

すべての IVF バリアントでデフォルトで無効になっています。レイテンシーよりも再現率が優先されるシナリオで、圧縮インデックス (ivf-pq や ivf-hnsw-sq など) に最適です。

hnsw.ef_search

検索中の HNSW 検索幅。

Integer

いいえ

0

値が大きいほど、一般的に再現率は向上しますが、レイテンシーは増加します。0 はネイティブライブラリのデフォルトが使用されることを示します。

diskann.search.list_size

Lumina DiskANN の検索リストサイズ。

Integer

いいえ

max(1.5 × top_k, 16)

値が大きいほど、一般的に再現率は向上しますが、レイテンシーは増加します。

diskann.search.beam_width

Lumina DiskANN の検索ビーム幅。

Integer

いいえ

4

—

search.parallel_number

並列 Lumina 検索の数。

Integer

いいえ

5

—

説明

設定オプションの詳細については、Apache Paimon 公式ドキュメントをご参照ください。

機能詳細

データの鮮度と一貫性

Paimon sink テーブルは、各 Flink ジョブのチェックポイント中にデータをコミットするために二相コミットプロトコルを使用します。したがって、データの鮮度は Flink ジョブのチェックポイント間隔によって決まります。各コミットは最大 2 つのスナップショットを生成します。

2 つの Flink ジョブが同じ Paimon テーブルに同時に書き込む場合、ジョブが異なるバケットに書き込む場合はシリアライズ可能な一貫性を実現します。ジョブが同じバケットに書き込む場合は、スナップショット分離のみを実現します。これは、テーブルのデータが両方のジョブの結果の混合になる可能性があることを意味しますが、データ損失は発生しません。

マージエンジン

Paimon sink テーブルが同じプライマリキーを持つ複数のレコードを受信した場合、一意性を維持するためにそれらを単一のレコードにマージします。この動作は merge-engine パラメーターを設定することで制御できます。次の表に、利用可能なマージエンジンを説明します。

マージエンジン

説明

Deduplicate

重複排除エンジンがデフォルトです。同じプライマリキーを持つ複数のレコードについて、Paimon sink テーブルは最新のレコードのみを保持し、その他は破棄します。

説明

最新のレコードが削除メッセージの場合、そのプライマリキーを持つすべてのレコードが破棄されます。

Partial Update

部分更新エンジンを使用すると、複数のメッセージで段階的に更新することで完全なレコードを構築できます。同じプライマリキーを持つ新しいレコードが到着すると、その null でない値が既存のレコードの対応するフィールドを上書きします。エンジンは、新しいレコードで null のフィールドを無視し、既存の値を保持します。

たとえば、Paimon sink テーブルが次の 3 つのレコードを順に受信するとします:

  • <1, 23.0, 10, NULL>

  • <1, NULL, NULL, 'This is a book'>

  • <1, 25.2, NULL, NULL>

最初の列がプライマリキーである場合、最終的にマージされたレコードは <1, 25.2, 10, 'This is a book'> になります。

説明
  • 部分更新の結果をストリームで読み取るには、changelog-producer パラメーターを lookup または full-compaction に設定する必要があります。

  • 部分更新エンジンは削除メッセージを処理できません。partial-update.ignore-delete パラメーターを true に設定して、削除メッセージを無視できます。

Aggregation

一部のユースケースでは、レコードの集計値のみが必要な場合があります。集約エンジンは、指定した集計関数を使用して、同じプライマリキーを持つレコードを結合します。プライマリキー以外の各列について、fields.<field-name>.aggregate-function オプションを使用して集計関数を指定する必要があります。そうしないと、列はデフォルトで last_non_null_value 集計関数を使用します。たとえば、次の Paimon テーブル定義を考えます。

CREATE TABLE MyTable (
  product_id BIGINT,
  price DOUBLE,
  sales BIGINT,
  PRIMARY KEY (product_id) NOT ENFORCED
) WITH (
  'merge-engine' = 'aggregation',
  'fields.price.aggregate-function' = 'max',
  'fields.sales.aggregate-function' = 'sum'
);

price 列は max 関数で集計され、sales 列は sum 関数で集計されます。2 つの入力レコード <1, 23.0, 15> と <1, 30.2, 20> が与えられた場合、最終結果は <1, 30.2, 35> になります。サポートされている集計関数とそれに対応するデータ型は次のとおりです:

  • sum: DECIMAL、TINYINT、SMALLINT、INTEGER、BIGINT、FLOAT、DOUBLE をサポートします。

  • min および max: DECIMAL、TINYINT、SMALLINT、INTEGER、BIGINT、FLOAT、DOUBLE、DATE、TIME、TIMESTAMP、TIMESTAMP_LTZ をサポートします。

  • last_value および last_non_null_value: すべてのデータ型をサポートします。

  • listagg: STRING をサポートします。

  • bool_and および bool_or: BOOLEAN をサポートします。

説明
  • sum 関数のみがリトラクションと削除をサポートし、他の集計関数はサポートしません。特定の列でリトラクションと削除メッセージを無視する必要がある場合は、'fields.${field_name}.ignore-retract'='true' を設定できます。

  • 集約の結果をストリームで読み取るには、changelog-producer パラメーターを lookup または full-compaction に設定する必要があります。

Changelog プロデューサー

changelog-producer パラメーターを設定して、Paimon が任意の入力ストリームに対して完全な changelog (すべての update_after レコードに対応する update_before レコードがある) を生成するように設定します。次の表に、利用可能な changelog プロデューサーを説明します。詳細については、Apache Paimon 公式ドキュメントをご参照ください。

プロデューサー

説明

None

changelog-producer を none (デフォルト) に設定すると、下流の Paimon ソーステーブルは、特定のプライマリキーのデータの最新の状態のみを参照します。この不完全な changelog は、コンシューマーがデータの以前の状態を判断できず、削除されたか、最新の状態が何かしかわからないため、正しい計算を行うのが困難になります。

たとえば、下流のコンシューマーが列の合計を計算する必要があり、最新の値が 5 であることしかわからない場合、合計をどのように更新すればよいかを判断できません。以前の値が 4 であれば、合計は 1 増加し、以前の値が 6 であれば、合計は 1 減少します。update_before レコードに敏感なコンシューマーは none プロデューサーを使用すべきではありませんが、他の changelog プロデューサーはパフォーマンスのオーバーヘッドを伴います。

説明

データベースなどの下流のコンシューマーが update_before データに敏感でない場合は、none プロデューサーを使用できます。特定の要件に基づいて changelog プロデューサーを設定してください。

Input

changelog-producer を input に設定すると、sink テーブルは入力ストリームを changelog ファイルに二重書き込みします。

このプロデューサーは、入力ストリーム自体がすでに完全な changelog である場合 (Change Data Capture (CDC) からのデータなど) にのみ使用してください。

Lookup

changelog-producer を lookup に設定すると、sink テーブルはディメンションテーブルのルックアップに似たポイントクエリメカニズムを使用して、現在のスナップショットがコミットされる前に完全な changelog を生成します。このプロデューサーは、任意の入力ストリームから完全な changelog を生成します。

full-compaction プロデューサーと比較して、lookup プロデューサーは changelog の適時性が優れていますが、全体的なリソース消費は多くなります。

このオプションは、高いデータ鮮度 (例:分単位) が要求されるユースケースに使用します。

Full Compaction

changelog-producer を full-compaction に設定すると、sink テーブルは各完全なコンパクション中に完全な changelog を生成します。このプロデューサーは、任意の入力ストリームから完全な changelog を生成します。完全なコンパクションの間隔は full-compaction.delta-commits パラメーターで指定されます。

lookup プロデューサーと比較して、full-compaction プロデューサーはレイテンシーが高くなりますが、既存の完全なコンパクションプロセスを活用するため、追加の計算は発生しません。これにより、全体的なリソース消費が低くなります。

このオプションは、データ鮮度の要件が低い (例:時間単位) ユースケースに使用します。

書き込みモード

Paimon テーブルは、以下の書き込みモードをサポートしています。

モード

説明

Change-log

change-log 書き込みモードは、Paimon テーブルのデフォルトです。このモードは、プライマリキーに基づいて挿入、削除、更新操作をサポートします。また、このモードではマージエンジンと changelog プロデューサーも使用できます。

Append-only

append-only 書き込みモードは、データの挿入のみをサポートし、プライマリキーを使用しません。このモードは change-log モードよりも効率的で、データ鮮度の要件が中程度 (例:分単位の鮮度) のシナリオでメッセージキューの代替として使用できます。

append-only 書き込みモードの詳細については、Apache Paimon 公式ドキュメントをご参照ください。このモードを使用する際は、次の点にご注意ください:

  • 要件に応じて bucket-key パラメーターを設定してください。そうしないと、Paimon テーブルはすべての列の値に基づいてデータをバケット化するため、計算効率が悪くなります。

  • append-only 書き込みモードは、ある程度データの出力順序を保証できます。具体的な出力順序は次のとおりです:

    1. 異なるパーティションからのレコードの場合: scan.plan-sort-partition パラメーターが設定されている場合、値の小さいパーティションのレコードが先に出力されます。そうでない場合は、先に作成されたパーティションのレコードが先に出力されます。

    2. 同じパーティションとバケットからのレコードの場合、先に書き込まれたレコードが先に出力されます。

    3. 同じパーティションでも異なるバケットからのレコードの場合、異なるバケットは異なる並列タスクによって処理されるため、出力順序は保証されません。

Flink CDC データインジェストのターゲット

Paimon テーブルは、単一テーブルまたはデータベース全体のデータのリアルタイム同期をサポートしています。上流のスキーマ変更は、リアルタイムで Paimon テーブルに同期されます。詳細については、「Paimon YAML コネクタ」セクションをご参照ください。

Variant 読み取りプルーニング

クエリによって参照される Variant フィールドのみを読み取ることで、I/O とメモリのオーバーヘッドを削減します。

有効化する方法

パラメーター

デフォルト値

説明

variant.read.pushdown.enabled

false

true に設定して Variant 読み取りプルーニングを有効にします。

前提条件

  • Variant データは VVR 11.6 以降でのみ書き込み可能です。以前のバージョンや他のエンジンで書き込まれた Variant データは、読み取りプルーニングをサポートしていません。

  • 上流のデータが有効になるには、variant.inferShreddingSchema オプションを有効にして自動 Variant シュレッディング推論を有効にするか、variant.shreddingSchema および関連オプションを明示的に設定して、どの Variant メンバーがシュレッディングに適しているかを指定する必要があります。詳細については、Coreoptions をご参照ください。

サポートされるシナリオ

読み取りプルーニングは、SQL が文字列キーで Variant フィールドにアクセスする場合に有効になります。例:

SELECT v['a']            FROM t;   -- 単一レベル
SELECT v['a']['b']       FROM t;   -- ネスト
SELECT v['a'], v['b']    FROM t;   -- 複数フィールド
SELECT id, v['a']        FROM t;   -- 通常の列との混合
SELECT v['a'] + 1        FROM t;   -- 式での参照

サポートされないシナリオ

  • SELECT v FROM t のように、Variant 全体を直接参照する場合。

  • SELECT v, v['a'] FROM t のように、直接参照とフィールドアクセスを組み合わせる場合。

  • v[0] のような配列インデックスアクセス。

  • テーブルスキーマにネストされた Row フィールドが含まれている場合。この場合、読み取りプルーニングはテーブル内のどの Variant フィールドにも適用されません。

Blob 署名付き URL

Paimon は、OSS に保存されている Blob 列データに対して、短期間有効なパブリック HTTPS GET 署名付き URL を生成できます。マルチモーダルモデルサービスなどの外部サービスは、Flink ジョブ内でファイルバイトを転送することなく、URL を使用してファイルコンテンツを直接取得できます。

使用制限

  • この機能は Flink コンピュートエンジン VVR 11.9-preview1 以降でのみサポートされています。

  • OSS に保存されている Paimon テーブルのみがサポートされています。メタストアのタイプは問いません。Filesystem、DLF、その他のメタストアタイプはすべてサポートされています。

  • 生成される URL はパブリック HTTPS URL であり、パブリックネットワークアクセスを持つ外部サービスによって消費される必要があります。カタログが内部エンドポイントを使用している場合、外部サービスが生成された URL にアクセスできるように、パブリック HTTPS エンドポイントに変更することを推奨します。

  • 通常の Blob 列を読み取るには、まず blob-as-descriptor オプションを使用して BlobDescriptor バイトを取得し、そのバイトを関数に渡す必要があります。

構文

descriptor_to_presigned_url(source_table, descriptor, validity)
try_descriptor_to_presigned_url(source_table, descriptor, validity)

パラメーター

パラメーター

タイプ

説明

source_table

STRING リテラル

Blob 列を含む Paimon テーブル。database.table の形式です。テーブルのカタログが関数が属するカタログと同じ場合、catalog.database.table も使用できます。値は空でないリテラルでなければなりません。テーブルフィールド、動的カラム、CASE 式はサポートされていません。

descriptor

BYTES

BlobDescriptor バイト。blob-as-descriptor = 'true' が有効になった後に Blob 列を読み取った結果です。

validity

INTERVAL

URL の有効期間。値は正の秒数でなければなりません。例: INTERVAL '5' MINUTE。

戻り値

タイプ

説明

STRING

短期間有効なパブリック HTTPS GET 署名付き URL。

例

-- SQL ヒントを使用して Blob 列を記述子として読み取り、署名付き URL を生成する
SELECT sys.descriptor_to_presigned_url(
    'default.image_table',
    image,
    INTERVAL '5' MINUTE)
FROM image_table /*+ OPTIONS('blob-as-descriptor'='true') */;

-- フォールトトレラントモード:行レベルのエラーで NULL を返し、他の動作は変更されない
SELECT sys.try_descriptor_to_presigned_url(
    'default.image_table',
    image,
    INTERVAL '5' MINUTE)
FROM image_table /*+ OPTIONS('blob-as-descriptor'='true') */;
説明
  • descriptor_to_presigned_url は行レベルのエラーで例外をスローします。try_descriptor_to_presigned_url は行レベルのエラーで NULL を返します。

  • 生成された URL にはファイル拡張子が含まれず、URL が指すバイトは Blob データと同一です。下流のサービスは、URL のサフィックスではなく、返されたバイトに基づいてファイル形式を識別する必要があります。

  • 署名付き URL は一時的なアクセス認証情報と同等です。署名付き URL が生成されたら、すぐに下流のサービスに送信してください。ログや結果テーブルに書き込んだり、永続化したりしないでください。

チェインテーブル

チェインテーブルは、スナップショットブランチとそれに続くデルタブランチの変更から完全なデータセットを再構築します。定期的な完全データを snapshot ブランチに書き込み、2 つの完全ロード間の変更を delta ブランチに書き込みます。読み取りは最新のスナップショットパーティションをアンカーとして使用し、後のデルタパーティションをマージして完全なデータを再構築するため、テーブル全体を再書き込みする必要がなくなります。これは、ODS binlog ダンプのように、実行間で変更される行がごく一部である場合に便利です。詳細については、Apache Paimon ドキュメントの Chain Table をご参照ください。チェインテーブルは VVR 11.9 以降でのみサポートされています。

チェインテーブルの有効化

テーブルを作成する際に chain-table.enabled を true に設定し、snapshot と delta ブランチを作成し、その後、プライマリテーブルと両方のブランチテーブルでブランチフォールバックオプションを設定します。

CREATE TABLE `default`.`t` (
  `t1` STRING,
  `t2` STRING,
  `t3` STRING,
  `date` STRING,
  PRIMARY KEY (`date`, `t1`) NOT ENFORCED
) PARTITIONED BY (`date`) WITH (
  'chain-table.enabled' = 'true',
  'sequence.field' = 't2',
  'bucket-key' = 't1',
  'bucket' = '2',
  'partition.timestamp-pattern' = '$date',
  'partition.timestamp-formatter' = 'yyyyMMdd'
);

-- mycat は Paimon カタログの名前です。
CALL `mycat`.sys.create_branch('default.t', 'snapshot');
CALL `mycat`.sys.create_branch('default.t', 'delta');

ALTER TABLE `default`.`t` SET (
  'scan.fallback-snapshot-branch' = 'snapshot',
  'scan.fallback-delta-branch' = 'delta');

ALTER TABLE `default`.`t$branch_snapshot` SET (
  'scan.fallback-snapshot-branch' = 'snapshot',
  'scan.fallback-delta-branch' = 'delta');

ALTER TABLE `default`.`t$branch_delta` SET (
  'scan.fallback-snapshot-branch' = 'snapshot',
  'scan.fallback-delta-branch' = 'delta');

データの書き込み

完全データを t$branch_snapshot に書き込みます。このブランチの各パーティションは、ある時点での完全なビューです。増分データを t$branch_delta に書き込みます。このブランチの各パーティションには、その期間の変更のみが含まれます。

-- 完全書き込み
INSERT OVERWRITE `default`.`t$branch_snapshot` PARTITION (date = '20250810') VALUES ('1', '1', '1');

-- 増分書き込み
INSERT INTO `default`.`t$branch_delta` PARTITION (date = '20250811') VALUES ('2', '1', '1');

データの読み取り

読み取りパス

操作

結果

完全クエリ

プライマリテーブルのパーティションをクエリします。

パーティションの完全なデータ。スナップショットブランチにパーティションが含まれている場合は直接読み取られます。そうでない場合は、アンカースナップショットと後のデルタパーティションから再構築されます。

増分クエリ

t$branch_delta のパーティションをクエリします。

選択されたデルタパーティションに保存されている変更のみ。完全な状態は再構築されません。

ハイブリッドクエリ

完全クエリと増分クエリを UNION ALL で結合します。

完全な結果と増分結果の組み合わせ。同じ行が 2 回表示される場合があります。

ストリーミング読み取り

プライマリテーブルをストリーミングモードで読み取ります。

初期ロードフェーズの結果が最初に出力され、その後、デルタブランチの新しいコミットが継続的に消費されます。

ルックアップ結合

チェインテーブルをディメンションテーブルとして使用します。

各グループの最新のスナップショットパーティションと後のデルタパーティションのマージされた状態。continuous.discovery-interval に基づいて増分的にリフレッシュされます。

-- 完全クエリ
SELECT t1, t2, t3 FROM `default`.`t` WHERE date = '20250811';

-- 増分クエリ
SELECT t1, t2, t3 FROM `default`.`t$branch_delta` WHERE date = '20250811';

-- ハイブリッドクエリ
SELECT t1, t2, t3 FROM `default`.`t` WHERE date = '20250811'
UNION ALL
SELECT t1, t2, t3 FROM `default`.`t$branch_delta` WHERE date = '20250811';

ストリーミング読み取り

ストリーミング読み取りジョブは 2 つのフェーズで実行されます:

  • 初期ロードフェーズ: デフォルトでは、ジョブは各グループの最新のスナップショットパーティションと、その後のデルタパーティションを読み取ります。古いスナップショットパーティションは除外されます。このフェーズでアンカーによってスナップショットとデルタデータをマージし、クロスブランチの DELETE レコードを解決するには、chain-table.streaming.merge-snapshot を true に設定します。トレードオフとして、ジョブの起動時にスキャンが重くなります。

  • 増分フェーズ: ジョブは delta ブランチから新しいコミットを継続的に読み取ります。

SET 'execution.runtime-mode' = 'streaming';

INSERT INTO downstream_sink SELECT * FROM `default`.`t`;
説明

増分フェーズは delta ブランチのみを監視します。スナップショットブランチへの書き込みは、ジョブが再起動されるまで検出されません。定期的に compact_chain_table プロシージャを実行して、パーティションの増分データをスナップショットブランチにマージします。コンパクション後、初期ロードフェーズでマージする必要があるのは、コンパクション後に到着したデルタの変更のみです。

複数のパーティションキー

テーブルに複数のパーティションキーがある場合、chain-table.chain-partition-keys を使用して、チェインディメンションをグループディメンションから分離します。値はパーティションキーの連続したサフィックスでなければなりません。サフィックスフィールドは時間順のチェインを形成し、その前のパーティションフィールドはグループディメンションになります。グループパーティション値の各グループは、独自のチェインとアンカーを維持します。このオプションが設定されていない場合、すべてのパーティションは単一の暗黙的なグループに属します。

CREATE TABLE `default`.`t` (
  `t1` STRING,
  `t2` STRING,
  `t3` STRING,
  `region` STRING,
  `date` STRING,
  PRIMARY KEY (`region`, `date`, `t1`) NOT ENFORCED
) PARTITIONED BY (`region`, `date`) WITH (
  'chain-table.enabled' = 'true',
  'sequence.field' = 't2',
  'bucket-key' = 't1',
  'bucket' = '2',
  'partition.timestamp-pattern' = '$date',
  'partition.timestamp-formatter' = 'yyyyMMdd',
  -- date のみがチェインを形成します。各 region は独自のチェインを持ちます。
  'chain-table.chain-partition-keys' = 'date'
);

制限事項

  • チェインテーブルはプライマリキーテーブルでのみサポートされています。bucket と bucket-key を指定する必要があります。

  • 各ブランチのスキーマは一貫している必要があります。

  • チェインテーブルには sequence.field が必要です。first-row および aggregation マージエンジンはサポートされていません。

  • ストリーミング読み取りとルックアップ結合では、delta ブランチが deduplicate マージエンジン (デフォルト値) を使用する必要があります。バッチ読み取りは影響を受けません。

  • 削除ベクトルは、deduplicate マージエンジンを使用するチェインテーブルでのみサポートされています。

  • changelog-producer には none (デフォルト値) と input のみがサポートされています。lookup および full-compaction モードはサポートされていません。値が none の場合、レコードはチェインパーティションを含む完全なプライマリキーによって正規化され、元のレコードが別のパーティションにある -D および -U レコードはドロップされます。下流のコンシューマーがクロスパーティションの changelog レコードを受信する必要がある場合は、値を input に設定します。

  • ストリーミング読み取りとルックアップ結合は、デフォルトの起動モード (latest-full) のみをサポートします。scan.snapshot-id、scan.timestamp-millis、scan.mode を latest に設定、または consumer-id などの開始位置を指定するとエラーがスローされます。チェインテーブルロジックなしで標準のストリーミング読み取りを実行するには、t$branch_delta などの特定のブランチテーブルを読み取ります。

  • パーティションフィルターは、チェインテーブルのストリーミング読み取りとルックアップ結合ではサポートされていません。これには、WHERE 句のパーティション列と scan.partitions オプションが含まれます。これは、フィルターがクロスブランチのマージロジックに干渉するためです。特定のパーティションを読み取るには、バッチモードを使用します。

  • ルックアップ結合の結合キーにパーティションキーを含めることはできません。そうしないと、エラーが返されます。

  • partition.timestamp-formatter は、完全な日付 (年-月-日または年-通日) を指定し、往復可能な日付と時刻のフィールド (y/u、M/L、d、D、H、k、m、および s) のみを使用し、最小ステップが少なくとも 1 秒である必要があります。

Mosaic ファイル形式

Mosaic は、数千から数万の列を含むワイドテーブルに最適化されたカラムナ-バケットハイブリッド形式です。列は名前でソートされ、範囲によってバケットに分散され、各バケット内で列指向形式で保存され、ZSTD を使用して独立して圧縮されます。プロジェクションプッシュダウンはバケット粒度で機能するため、クエリは要求された列を含むバケットのみを読み取ります。類似した名前のプレフィックスを持つ列は同じバケットに配置され、圧縮率とプロジェクションの局所性の両方が向上します。詳細については、Mosaic をご参照ください。Mosaic 形式は VVR 11.9 以降でのみサポートされています。

形式の有効化

テーブルを作成する際に file.format を mosaic に設定します。データインジェストジョブでは、対応するオプションは table.properties.file.format です。

CREATE TABLE `default`.`wide_table` (
  `id` BIGINT,
  `col_a` STRING,
  `col_b` DOUBLE
) WITH (
  'file.format' = 'mosaic'
);

フォーマットオプション

オプション

デフォルト値

説明

mosaic.num-buckets

auto

並列 I/O のための列バケットの数。値が 0 またはオプションが指定されていない場合、バケットの数は自動的に決定されます。

mosaic.stats-columns

(空)

述語プッシュダウンのために最小/最大統計が収集される列の名前。カンマ (,) で区切ります。値が空の場合、統計は収集されません。

mosaic.read.prefetch-row-groups

8

リーダーが消費中の行グループより先に開く行グループの数。プリフェッチは、範囲読み取りのレイテンシーをデコードと重複させます。各プリフェッチされた行グループは、デコードされたバッチをメモリに保持し、別の入力ストリームを使用します。値 0 はプリフェッチを無効にします。

mosaic.read.prefetch-max-bytes

64 mb

プリフェッチされた行グループの推定デコードサイズの上限。行数と射影された列の型から計算されます。広い射影または大きな行グループは、mosaic.read.prefetch-row-groups の有効値を低下させます。

制限事項

Mosaic は複合型をサポートしていません: ARRAY、MAP、MULTISET、ROW、VARIANT、BLOB、および VECTOR。

Paimon をディメンションテーブルとして使用

Paimon テーブルはディメンションテーブルとして使用できます。JOIN 構文については、「ディメンションテーブルの JOIN 文」をご参照ください。

デフォルトでは、ルックアップは各並列インスタンスですべてのデータをロードします。このアプローチは、小さなディメンションテーブルにのみ適しています。大きなディメンションテーブルの場合は、以下で説明するシャッフルルックアップソリューションを使用してください。

パーティション化されたディメンションテーブル

ディメンションテーブルがパーティション化されており、最新の 1 つまたは 2 つのパーティションのデータのみが必要な場合は、動的パーティションロード機能を使用できます:

SELECT * FROM T
JOIN DIM /*+ OPTIONS('lookup.dynamic-partition'='max_pt()', 'lookup.dynamic-partition.refresh-interval'='1 h') */
FOR SYSTEM_TIME AS OF T.proc_time AS D
ON T.col = D.col;

パラメーター

データ型

デフォルト値

説明

lookup.dynamic-partition

String

N/A

max_pt(): 最新のパーティションのみをロードします。max_two_pt(): 最新の 2 つのパーティションのみをロードします。

lookup.dynamic-partition.refresh-interval

Duration

1 h

システムがディメンションテーブルのパーティション更新をチェックする間隔。

大きなディメンションテーブル:固定バケットテーブル

VVR 8.0.8 以降でのみサポートされています。固定バケットテーブル (bucket > 0) の場合、シャッフルルックアップを使用して、バケットキーによってデータを並列インスタンス間で分散させることができます。これにより、各インスタンスは割り当てられたバケットのデータのみをロードします:

SELECT /*+ LOOKUP('table'='D', 'shuffle'='true') */ T.col1, D.col2
FROM T
JOIN DIM FOR SYSTEM_TIME AS OF T.proc_time AS D
ON T.col1 = D.col1;
説明
  • 結合キーはバケットキーでなければなりません。バケットキーはデフォルトでプライマリキーになります。

  • 固定バケットテーブル (bucket > 0) のみがこの機能をサポートします。

大きなディメンションテーブル:非固定バケットテーブル

VVR 8.0.10 以降でのみサポートされています。動的バケットテーブルまたは追加テーブルの場合、SHUFFLE_HASH または REPLICATED_SHUFFLE_HASH を使用して、各並列インスタンスがすべてのデータを読み取り、必要な部分のみを保持するようにできます:

-- シャッフルハッシュ
SELECT /*+ SHUFFLE_HASH(D) */ T.col1, D.col2
FROM T
JOIN DIM FOR SYSTEM_TIME AS OF T.proc_time AS D
ON T.col1 = D.col1;

-- レプリケートシャッフルハッシュ
SELECT /*+ REPLICATED_SHUFFLE_HASH(D) */ T.col1, D.col2
FROM T
JOIN DIM FOR SYSTEM_TIME AS OF T.proc_time AS D
ON T.col1 = D.col1;

SHUFFLE_HASH と REPLICATED_SHUFFLE_HASH の詳細については、「ディメンションテーブルの JOIN 文」をご参照ください。

よくある質問