データ接続と統合Iceberg テーブルインクリメンタルと CDC変更履歴 API の技術入門

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

変更履歴 API の技術入門

変更履歴は、Iceberg スナップショット ↗間で挿入、更新、または削除された行を記述します。Python トランスフォームでは、Foundry の source.changelog() API が次の2つのモードでこれらの変更を読み取ります。

呼び出し結果
source.changelog(["id"])識別子の変更履歴:各識別子の最新の変更(同順位の変更も含む)
source.changelog()正味の変更の履歴:重複行の件数を保持した、正味の挿入と削除

Foundry のリーダー source.changelog() とライター output.apply_changelog() は、このページで説明する検証を実行します。Iceberg ネイティブの create_changelog_view または MERGE INTO を直接呼び出しても、これらのチェックは実行されません。

変更履歴の読み取り範囲

トランスフォームは、前回のビルドで処理した入力スナップショットより後から、今回のビルドで選択された入力スナップショットまでの変更を読み取ります。たとえば、前回のビルドで V0 を処理し、今回のビルドで V3 まで読み取る場合、変更履歴には V1、V2、V3 が含まれます。処理済みの V0 は除かれます。入力がまだ V0 のままの場合、変更履歴は空になり、Foundry は識別子を検証しません。

コンパクションや、変更されていない行の書き換えでは、論理的な変更は生じません。

Iceberg の変更履歴スキャンは、現在、merge-on-read によって生成される削除ファイルをサポートしていません。ソーステーブルは copy-on-write のままにしてください。

識別子変更履歴(識別子列あり)

キーごとの最新の変更を読み取るには、識別子列を渡します。

Copied!
1 changelog_df = source.changelog(["id"])

各トップレベル識別子列の名前を使用します。名前にドットやバッククォートが含まれる場合は、それらも含めます。

ソースの識別子の一意性

デフォルトの enforce_primary_key=True では、変更履歴に含まれる各識別子について、開始スナップショット内およびそれ以降の各スナップショットの後で、ソース行が0行または1行であることを Foundry がチェックします。行数が重複または負になると、データフレームが返される前にエラーが発生します。Foundry は、同一スナップショット内の変更をまとめてカウントします。

識別子の検証では、開始スナップショットが存在する場合はその識別子列をスキャンし、要求された範囲全体の変更を処理してからデータフレームを返します。このため、変更された行が少なくても、読み取り時間が長くなる場合があります。

任意のパラメーター enforce_primary_key=False を指定すると、この追加のスナップショットスキャンと行数の検証をスキップします。Iceberg 自体のチェックや、output.apply_changelog() でのライターの検証は無効になりません。

検証を無効にする前に主キーの一意性を確保してください

外部で一意性が保証されていない状態で主キーの強制を無効にすると、誤った変更履歴が通知なく生成される可能性があります。一時的に重複が生じた後に削除が行われると、識別子を誤って削除する変更履歴が生成される可能性があります。その識別子を持つ行は、ソースにまだ残っています。読み取り範囲の開始時点と、その範囲内のすべてのスナップショットの後で、ソースがすでに一意性を保証している場合を除き、検証を有効にしてください。検証を無効にする前に、主キーの強制を参照してください。

同じキーを順次更新することは有効です。各スナップショットの境界で、行数が0行または1行である必要があります。

開始スナップショットがある場合、読み取りには、そのスナップショットと、終了スナップショットまでをつなぐ履歴が必要です。その履歴を利用できない場合、または開始スナップショットが終了スナップショットの祖先に含まれない場合、読み取りは失敗します。

開始スナップショットがない場合、カウントは0から始まり、履歴がテーブルの作成時点までさかのぼると仮定します。リーダーはこの仮定を検証しません。そのため、履歴の期限切れによって、不完全な変更履歴が生成される可能性があります。

次に Foundry は、各キーについて、そのキーが変更された最新のスナップショットの変更を保持します。そのスナップショット内でキーに対する変更が複数残っている場合、Foundry はそれらをすべて返し、ライターが曖昧な操作を拒否できるようにします。

主キーの強制が有効な場合、リーダーは次の結果を生成します。

ソースへの書き込み結果
id1 を val1 から val2 に更新し、その後のスナップショットで val3 に更新しますUPDATE_AFTER(id1, val3)
(id1, val1) を追加し、その後のスナップショットで (id1, val2) を追加しますエラー:ソースキーが重複しています
同じスナップショットで (id1, val1) と (id1, val2) を追加しますエラー:ソースキーが重複しています

最初の結果は、id1 の出力値を置き換えるか、存在しない場合は挿入します。2つの APPEND の例は、物理的な行の順序にかかわらず、最新の変更を選択する前に失敗します。

たとえば、ある行が V0 では1行、V1 では同一内容で2行、V2 では1行存在するとします。主キーの強制が有効な場合、V0 から V2 までの読み取りは、開始と終了の両方のスナップショットでキーが一意であっても、V1 に重複キーが含まれるため失敗します。

正味の変更履歴は、読み取り時に行数を保持しますが、ソースに重複が含まれる場合、それらの適用には異なる処理が必要です。

更新の表現方法

Foundry は、識別子列を指定して Iceberg の create_changelog_view ↗ プロシージャを使用します。Iceberg は、ファイルの書き換えによって生じた、内容が同一の削除と挿入のペアを削除し、残った削除と挿入をペアにして UPDATE_BEFORE 行と UPDATE_AFTER 行にします。Foundry は UPDATE_BEFORE を削除し、各キーの _change_ordinal が最大の変更を保持します。

スナップショット間の変更返される変更
行を更新するか、行を挿入してから更新します最後の UPDATE_AFTER
行を挿入または更新してから削除します最後の DELETE
キーを以前に使用されていない値に変更します古いキーの DELETE と新しいキーの INSERT

changelog() に渡す列によって、この読み取りのキーが定義されます。Iceberg のテーブルメタデータ内の識別子フィールド ↗は、一意性を強制しません。

正味の変更履歴(識別子列なし)

識別子を省略すると、正味の変更履歴が作成されます。このモードは、重複を含めて行数を保持します。

Copied!
1 changelog_df = source.changelog()

正味の変更履歴は、すべてのデータ列を使って行を照合し、スナップショット範囲全体で一致する挿入と削除を相殺します。値が val1 から val2 に、さらに val3 に変更された場合、結果は DELETE(val1) と INSERT(val3) になります。中間の val2 の変更は相殺されます。

このモードは、Iceberg の net_changes オプションを使用します。

正味の変更履歴は、apply_changelog に渡す識別子変更履歴の汎用的な代替にはなりません。通常の更新では、同じキーに対して DELETE と INSERT が生成され、ライターはこれを拒否します。これらの変更を、意図する出力操作に変換してください。両方の変更の序数が同じであるため、_change_ordinal だけで1行を選択すると、削除が選択される可能性があります。

また、ライターは重複行の数の変更を適用できません。同一内容の2行が1行になる場合、正味の変更履歴は1件の DELETE を返します。すべてのデータ列が出力の識別子であっても、この削除は出力の2行に一致するため、ライターは拒否します。重複行を複製するには、行数を別途処理するか、完全なスナップショットで置き換える必要があります。

変更履歴の列

どちらのモードでも、source.changelog() はソース列に加えて、次のメタデータ列を含むデータフレームを返します。

列データ型意味
_change_type文字列識別子の変更履歴:INSERT、UPDATE_AFTER、または DELETE
正味の変更の履歴:INSERT または DELETE
_change_ordinalint要求された範囲内でのスナップショットの0始まりの順序
_commit_snapshot_idLong変更が発生したスナップショット

複数の行が同じ序数を持つ場合があります。序数は範囲内のスナップショットを識別するものであり、個々の行や、そのスナップショット内の行の順序を識別するものではありません。序数は読み取りごとにリセットされるため、別々の読み取りから取得した変更を _change_ordinal だけで並べ替えないでください。

変更履歴の推移の例

以下の例では、連続するスナップショット V0 から V3 を使用し、_commit_snapshot_id は省略しています。

スナップショット間でのテーブルの推移の例

各スナップショットでは、次の変更が行われます。

スナップショット書き込み書き込み後のテーブル
V0(id1, val1) を挿入します(id1, val1)
V1id1 を val2 に更新します(id1, val2)
V2id1 を val3 に更新し、(id2, val2) を挿入します(id1, val3), (id2, val2)
V3既存の id1 の行は変更せずに、(id2, val2) を (id1, val3) に変更します(id1, val3) が2行

以下の例では、開始スナップショットはすでに処理されています。そのため、V0 から V3 までを読み取ると、V0 は除外され、V1、V2、V3 が含まれ、それぞれの序数は 0、1、2 になります。V1 から V2 までを読み取ると、V2 のみが含まれるため、その序数は 0 になります。

識別子変更履歴の推移の例

これらの例では、デフォルトの enforce_primary_key=True を使用します。V1 または V2 で終わる範囲では、id1 と id2 の最新の変更が保持されます。最後の例では、V3 で意図的に重複するソースキーを導入しているため、識別子による読み取りが失敗します。

識別子変更履歴の例:V0 から V1

idvalue_change_type_change_ordinal
id1val2UPDATE_AFTER0

識別子変更履歴の例:V1 から V2

idvalue_change_type_change_ordinal
id1val3UPDATE_AFTER0
id2val2INSERT0

識別子変更履歴の例:V0 から V2

idvalue_change_type_change_ordinal
id1val3UPDATE_AFTER1
id2val2INSERT1

識別子変更履歴の例:V0 から V3

V3 にはキーが id1 の行が2行含まれているため、リーダーはエラーを発生させます。識別子変更履歴は返されません。

正味の変更履歴の推移の例

正味の変更履歴では、開始スナップショットと終了スナップショットの間の行数の差が保持されます。

正味の変更履歴の例:V0 から V1

idvalue_change_type_change_ordinal
id1val1DELETE0
id1val2INSERT0

正味の変更履歴の例:V1 から V2

idvalue_change_type_change_ordinal
id1val2DELETE0
id1val3INSERT0
id2val2INSERT0

正味の変更履歴の例:V0 から V2

次のテーブルは、相殺前の変更を示しています。一致する (id1, val2) の挿入と削除は相殺されるため、取り消し線で表示されています。

idvalue_change_type_change_ordinal
id1val1DELETE0
id1val2INSERT0
id1val2DELETE1
id1val3INSERT1
id2val2INSERT1

返される正味の変更履歴は次のとおりです。

idvalue_change_type_change_ordinal
id1val1DELETE0
id1val3INSERT1
id2val2INSERT1

正味の変更履歴の例:V0 から V3

V2 の2行が同じファイルに含まれていると仮定します。V3 での書き換えでは、(id1, val3) を1回削除し、2回挿入します。正味の変更履歴では、この削除が V2 での先行する挿入と相殺され、V3 の2回の挿入が残ります。(id2, val2) の挿入と削除も相殺されます。

idvalue_change_type_change_ordinal
id1val1DELETE0
id1val2INSERT0
id1val2DELETE1
id1val3INSERT1
id2val2INSERT1
id1val3DELETE2
id2val2DELETE2
id1val3INSERT2
id1val3INSERT2

返される正味の変更履歴は次のとおりです。

idvalue_change_type_change_ordinal
id1val1DELETE0
id1val3INSERT2
id1val3INSERT2

どちらの挿入も序数は 2 です。これらの挿入は V3 にある2つのコピーを保持します。序数は、どちらのコピーが先だったかを示すものではありません。

変更を出力テーブルに適用する

source.changelog() に渡す識別子は、ソースの変更をグループ化します。output.apply_changelog() に渡す識別子は、それらの変更を出力行と照合します。出力識別子の列を1つ以上渡す必要があります。

Copied!
1 output.apply_changelog(changelog_df, ["id"])
_change_type出力操作
INSERT, UPDATE_AFTER, or UPDATE一致する行を更新し、存在しない場合は挿入します
DELETE一致する行を削除し、存在しない場合は出力を変更しません
UPDATE_BEFORE行を無視します

ライターは、これらの _change_type の値との完全一致のみを受け付けます。不明な値、小文字表記の値、null はエラーになります。

出力識別子の一意性

テーブルを作成するときも含め、出力キーごとに処理対象の行を最大1行だけ指定してください。結合やその他の変換によって導入された重複キーは、書き込む前に、意図する出力に従って解消してください。同順位の行から任意の行を選択しないでください。新しいテーブルには、挿入または更新された行のみが含まれます。

最初の完全なスナップショットの書き込み後も含め、出力のキーも一意である必要があります。処理対象の変更履歴行が既存の出力行の複数に一致する場合、ライターはマージ前にエラーを発生させます。対応する操作がない重複した出力キーは、ライターの検査対象になりません。null のキー値は、ほかの null のキー値と一致します。この検証により、書き込み前に出力キーのスキャンと結合が追加されます。

スキーマ要件

既存の出力では、変更履歴のデータ列に不足または余分な列があるとエラーになります。この比較では変更履歴のメタデータ列は除外されますが、すべての行が DELETE の場合でも、ライターには出力のペイロード列が必要です。変更を適用する前に、列を揃えるか、出力のスキーマを明示的に進化させるか、出力を置き換えてください。

識別子のデータ型は、出力のデータ型と一致するか、Iceberg の型昇格が可能である必要があります。許可されるのは、int から long、float から double、またはスケールを変えずに Decimal の精度を高める昇格です。それ以外の変換はエラーになります。意図的に変換する場合は、apply_changelog を呼び出す前に、変更履歴の識別子を出力のデータ型にキャストしてください。その後、ライターは変換後のキーに重複する操作がないかを検査します。

安定した出力識別子

識別子の変更を変換する場合、キー以外のソース値が変更されても、ソースキーから出力キーへのマッピングは一意かつ安定している必要があります。たとえば、id で読み取り、destination_id で書き込む場合、destination_id が A から B に変わると、古い出力行が残ります。リーダーは新しい行のみを返すため、ライターは A を削除せずに B をアップサートします。これは、列名が変わらなくても、その値が変更可能なフィールドから導出されている場合にも当てはまります。出力キーを変更するには、保持しておいた変更前イメージを使用して古いキーの削除を明示的に出力するか、現在のソーススナップショットから出力を置き換えてください。識別子リーダーは変更前イメージを返しません。

ワークフロー全体については、変更履歴を使用した変更データキャプチャ (CDC)と絞り込み済み出力の例を参照してください。