注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
Iceberg の変更履歴を使用して、PySpark トランスフォームで変更データキャプチャ(CDC)パイプラインを構築します。変更履歴を使用すると、ビルドのたびに入力全体を再処理することなく、入力テーブルの挿入、更新、削除を出力テーブルに適用できます。
CDC パイプラインを構築するには、次の手順を実行します。
changelog に設定してインクリメンタルトランスフォームを構築します。実行可能なコードを直接確認するには、クイックスタートを参照してください。
changelog に設定してインクリメンタル(差分処理)トランスフォームを構築する通常どおりにインクリメンタルトランスフォームを構築し、テーブルの読み取りモードを必ず changelog に指定します。
Copied!1@incremental(v2_semantics=True).with_table_incremental_options(table_read_mode="changelog")
テーブルの読み取りモード changelog は、可能な場合にトランスフォームをインクリメンタルに処理する必要があり、挿入、更新、削除をインクリメンタルに処理できることを示します。
入力テーブルから変更履歴を生成して、前回読み取った入力データのバージョンと現在のバージョンの間に発生した挿入、更新、削除を含む DataFrame を作成します。
変更履歴は、Foundry の source.changelog() API またはオープンソースの create_changelog_view Spark プロシージャ ↗を使用して生成できます。
Foundry の .changelog() API はオープンソースのプロシージャをラップし、次の2つの便利な機能を提供します。
UPDATE_BEFORE 行を削除し、一意の識別子ごとに最新の変更を選択します。オープンソースのプロシージャでは、スナップショット間の中間的な変更も含まれます。使いやすさを重視する場合は、Foundry API の使用を検討してください。Foundry API で公開されていないオプションを使用する場合は、オープンソースのプロシージャを使用します。識別子の検証がパフォーマンスに与える影響については、主キーの制約適用を参照してください。
Foundry API とオープンソースのプロシージャは、いずれも識別子ベースの変更履歴と正味の変更をサポートします。
| メソッド | 識別子ベースの変更履歴 | 正味の変更の変更履歴 |
|---|---|---|
Foundry .changelog API | 識別子を渡します。例:source.changelog(["primary_key"])。一意の識別子ごとに最新の変更を返し、UPDATE_BEFORE 行を削除します。 | 識別子を省略します:source.changelog()。スナップショットの範囲全体での正味の挿入と削除を返します。 |
オープンソースの create_changelog_view プロシージャ ↗ | identifier_columns => array('primary_key') を渡します。UPDATE_BEFORE 行と UPDATE_AFTER 行を含め、指定したスナップショット全体のすべての変更を返します。 | 識別子を省略し、net_changes => true を設定します。スナップショットの範囲全体での正味の挿入と削除を返します。 |
識別子ベースの変更履歴は、識別子として指定した列名に基づいて変更をグループ化します。正味の変更履歴は、すべてのデータ列を使用して行を照合し、スナップショット範囲全体で一致する挿入と削除を相殺し、重複行の数を保持します。Foundry の識別子ベースの変更履歴 API では、一意の識別子が必要です。主キーの制約適用が有効な場合、変更履歴に含まれる識別子に重複行があると、変更履歴の作成は失敗します。キーの信頼性を保証できない場合は、正味の変更履歴を使用します。両方のモードの例については、変更履歴 API の技術入門を参照してください。
識別子ベースの変更履歴を生成する際、source.changelog() では任意のパラメーター enforce_primary_key を使用できます。デフォルトは True です。
enforce_primary_key が True の場合、リーダーは変更履歴に含まれる識別子の一意性を検証します。読み取り範囲の開始時と各スナップショットの後に、各識別子に対応するソース行は0行または1行でなければなりません。これにより、キーの重複によるエラーを防ぎます。検証では開始スナップショットを読み取り、変更全体にわたって行数を計算するため、計算負荷が高くなる場合があります。
enforce_primary_key が False の場合、この検証は実行されません。
外部で一意性が保証されていない状態で主キーの制約適用を無効にすると、誤った変更履歴が警告なく生成される可能性があります。たとえば、一時的な重複の後に削除が発生すると、識別子を誤って削除する変更履歴が生成される可能性があります。その識別子を持つ行は、ソースに依然として残っています。すべての入力について、読み取り範囲の開始時とその範囲内のすべてのスナップショットの後に一意性がすでに保証されている場合を除き、検証を有効のままにしてください。
ソースですでにこの一意性が保証されている場合は、enforce_primary_key=False を設定して、リーダーによる追加のスナップショットスキャンと行数の検証をスキップします。
Copied!1changelog_df = source.changelog(["primary_key"], enforce_primary_key=False)
正味の変更を読み取るために識別子列を省略した場合、このオプションは効果を持ちません。Iceberg 自体の変更履歴の検証は引き続き適用されます。
変更履歴を生成したら、Foundry の .apply_changelog() API またはオープンソースの Spark SQL の MERGE INTO ↗ 文を使用して、出力に適用します。
| メソッド | 機能 | 使用場面 |
|---|---|---|
Foundry .apply_changelog | 指定した識別子で照合し、INSERT 行と UPDATE_AFTER 行をアップサートし、DELETE 行を削除します。出力キーごとの操作は最大1個である必要があります。 | 標準的な識別子ベースのアップサートと削除。 |
オープンソースの Spark SQL の MERGE INTO 文 ↗ | 記述した照合条件と、更新、挿入、削除の句を適用します。 | マージでのカスタムの照合、条件、またはビジネスロジック。 |
Foundry の API では、変更履歴の DataFrame と、それを出力と照合するために使用する列名を渡します。
Copied!1output.apply_changelog(changelog_df, ["primary_key"])
オープンソースの Spark SQL では、これらの操作を明示的に記述します。たとえば、キーごとに1つの操作を持つ latest_changes ビューをあらかじめ用意した場合は、次のようになります。
Copied!1 2 3 4 5 6MERGE INTO output_table AS tgt USING latest_changes AS src ON src.primary_key = tgt.primary_key WHEN MATCHED AND src._change_type = 'DELETE' THEN DELETE WHEN MATCHED AND src._change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET * WHEN NOT MATCHED AND src._change_type IN ('INSERT', 'UPDATE_AFTER') THEN INSERT *
データの加工で行を絞り込む場合は、フィルターに一致しなくなった行が出力から削除されるようにしてください。それらの行の変更履歴を削除すると、以前の出力行は変更されずに残ります。
Foundry の .apply_changelog() では、フィルターに一致しなくなった行の変更を DELETE に変換してから適用します。オープンソースの Spark SQL では、代わりに MERGE INTO 句で絞り込みロジックを記述できます。出力を絞り込む例を参照してください。
初回のビルド時、またはトランスフォームをインクリメンタルに解決できない場合は、出力を入力全体で置き換えます。ctx.is_incremental を使用して、この場合とインクリメンタルビルドを区別します。
非インクリメンタルビルドでは、入力履歴全体にわたる変更履歴を生成して適用することは避けてください。広範囲のスナップショットにわたって行の変更を対応付ける処理は、現在の入力を1回読み取る処理よりも効率が悪くなる場合があります。
以下のクイックスタートの2つの例では、いずれも非インクリメンタルビルドに output.write_dataframe(source.dataframe()) を使用しています。トランスフォームにビジネスロジックが含まれる場合は、書き込む前に入力全体に適用します。
この例では、ソーステーブルの変更を対象テーブルに複製する単純な恒等トランスフォームを示します。ソースにはキーごとに1行があることを前提としています。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14from transforms.api import IncrementalTransformContext, incremental, transform from transforms.tables import TableInput, TableOutput @incremental(v2_semantics=True).with_table_incremental_options(table_read_mode="changelog") @transform.spark.using( source=TableInput("/path/input"), output=TableOutput("/path/output"), ) def cdc_transform(ctx: IncrementalTransformContext, source, output): if ctx.is_incremental: changelog_df = source.changelog(["primary_key"]) output.apply_changelog(changelog_df, ["primary_key"]) else: output.write_dataframe(source.dataframe())
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84from transforms.api import ( IncrementalTableTransformInput, IncrementalTransformContext, incremental, transform, ) from transforms.tables import TableInput, TableOutput, TableTransformOutput _WATERMARK_PROP = "watermark.source-snapshot-id" @incremental(v2_semantics=True).with_table_incremental_options(table_read_mode="changelog") @transform.spark.using( source=TableInput("/path/input"), output=TableOutput("/path/output"), ) def cdc_transform( ctx: IncrementalTransformContext, source: IncrementalTableTransformInput, output: TableTransformOutput, ): spark = ctx.spark_session source_tbl = source.identifier output_tbl = output.identifier # このビルドでの処理範囲の終点となるソースのスナップショットを読み取ります。 snapshots = spark.sql(f""" SELECT snapshot_id FROM {source_tbl}.snapshots ORDER BY committed_at DESC LIMIT 1 """).collect() end = snapshots[0]["snapshot_id"] if snapshots else None # 非インクリメンタルビルドでは、ソース全体をコピーしてウォーターマークを初期化します。 if not ctx.is_incremental: output.write_dataframe(source.dataframe()) spark.sql(f""" ALTER TABLE {output_tbl} SET TBLPROPERTIES ('{_WATERMARK_PROP}' = '{end}') """) return # 前回のビルドで処理された最後のソースのスナップショットを読み取ります。 start = spark.sql(f""" SHOW TBLPROPERTIES {output_tbl} ('{_WATERMARK_PROP}') """).collect()[0]["value"] if start == str(end): return # 変更履歴を作成します。開始スナップショットは除き、終了スナップショットは含めます。 spark.sql(f""" CALL {source.catalog}.system.create_changelog_view( table => '{source_tbl}', changelog_view => 'source_changelog', identifier_columns => array('primary_key'), options => map('start-snapshot-id', '{start}', 'end-snapshot-id', '{end}') ) """) # 更新前のイメージを除き、キーごとに最新の操作を保持します。 spark.sql(f""" MERGE INTO {output_tbl} AS tgt USING ( SELECT * FROM ( SELECT *, ROW_NUMBER() OVER ( PARTITION BY primary_key ORDER BY _change_ordinal DESC ) AS _rn FROM source_changelog WHERE _change_type != 'UPDATE_BEFORE' ) WHERE _rn = 1 ) AS src ON src.primary_key = tgt.primary_key WHEN MATCHED AND src._change_type = 'DELETE' THEN DELETE WHEN MATCHED AND src._change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET * WHEN NOT MATCHED AND src._change_type IN ('INSERT', 'UPDATE_AFTER') THEN INSERT * """) # 変更を適用した後、ウォーターマークを進めます。 spark.sql(f""" ALTER TABLE {output_tbl} SET TBLPROPERTIES ('{_WATERMARK_PROP}' = '{end}') """)
詳細と例については、次を参照してください。