注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
Iceberg を使用したインクリメンタル（差分処理）Python トランスフォーム
このページでは、Iceberg テーブルでインクリメンタル Python トランスフォームを使用するための構文を紹介します。Iceberg テーブルの差分だけを処理する際の概念的な概要については、Iceberg テーブルを使用したインクリメンタル処理を参照してください。
Iceberg テーブルを使用してインクリメンタルトランスフォームを作成する際には、次の3つの重要な点に留意してください。
- インクリメンタルデコレーターと読み取りモードを追加する
- インクリメンタルランタイムオブジェクトを使用する
- インクリメンタル計算ロジックを使用する
インクリメンタルデコレーターと読み取りモード
トランスフォーム定義の直前にインクリメンタルデコレーターを記述することで、トランスフォームがインクリメンタルに実行されるように設定できます。
Iceberg テーブルを使用する際には、次の標準的な @incremental 引数が関係します。
| 引数 | 説明 |
|---|---|
v2_semantics | True である必要があります。Iceberg テーブルの入力と出力は、v2 インクリメンタルセマンティクスでのみサポートされています。 |
require_incremental | デフォルトは False です。True の場合、インクリメンタルに処理できないときは、非インクリメンタルな全件読み取りに切り替えるのではなく、トランスフォームが失敗します。 |
semantic_version | 既存の出力が無効になるような形でトランスフォームのロジックを変更するたびに、この数値を増やしてください。この値を変更すると、次回の実行は強制的に非インクリメンタルになります。 |
snapshot_inputs | 参照テーブルなど、全体を書き換えても出力が無効にならない入力の名前です。これらの入力は常に全件読み取られます。 |
さらに、デコレーターに .with_table_incremental_options(table_read_mode="...") をチェーンすることで、トランスフォームがインクリメンタルに取り込める上流の変更の種類を制御できます。
table_read_mode | 動作 |
|---|---|
append_only （デフォルト） | トランスフォームは、読み取り範囲内の追加および置換（コンパクション）のスナップショットをインクリメンタルに処理します。読み取り範囲内に上書きまたは削除のスナップショットが存在する場合、トランスフォームはインクリメンタルに処理できず、require_incremental の設定に応じて、非インクリメンタルにビルドされるか、失敗します。 |
changelog | トランスフォームは、読み取り範囲内の追加、置換、上書き、および削除のスナップショットをインクリメンタルに処理します。.changelog() API を呼び出すには、変更履歴読み取りモードが必要です。変更履歴モードは Spark トランスフォームでのみ利用可能です。 |
with_table_incremental_options には、transforms-tables のバージョン 0.1390.0 以降が必要です。
インクリメンタルランタイムオブジェクト
Foundry は、トランスフォーム内で Iceberg テーブルをインクリメンタルに読み書きするために、次のランタイムオブジェクトを提供します。
- 単一ノード API:
IncrementalIcebergInput,IncrementalIcebergOutput - PySpark API:
IncrementalTableTransformInput,TableTransformOutput
インクリメンタル計算ロジック
インクリメンタル実行では、インクリメンタル入力ランタイムオブジェクトは、デフォルトで「追加された」行を提供します。それ以外を読み取るには、.changelog() などの別のメソッドを呼び出します。
Copied!1added_rows = source.polars()
Copied!1added_rows = source.arrow()
Copied!1added_rows = source.pandas()
Copied!1 2added_rows = source.dataframe() changelog = source.changelog(["id"])
これらのランタイムオブジェクトを使用して、追加された行の書き込み、変更履歴の適用、Iceberg のネイティブ操作を使用した upsert と削除など、必要に応じたインクリメンタル計算ロジックを記述できます。さまざまなインクリメンタルトランスフォームについては、インクリメンタルコード例を参照してください。