# Deltaの移行ではタグが作成され、タイムスタンプ履歴が変わることがあります

Iceberg 1.12.0は、空の合成Deltaテーブルの2つのバージョンを2つのスナップショットに移行し、移行元のバージョン番号と保存されたコミット情報の時刻から4つのタグを作成しました。移行先に公開されたタイムスタンプ履歴は、最後のスナップショットに対する1件でした。2回目の移行では、保存された2つのコミット時刻が同じだったため、タグの重複エラーが発生しました。ローカルカタログに移行先テーブルは作成されず、2つのステージ済みAvroファイルがそのウェアハウスパスの下に残りました。[フィクスチャ](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java)と[観察結果](https://sapien1.com/research/iceberg-delta-clock/observations.json)では、Delta Standalone 3.3.3とHadoopCatalogを使い、空のローカルテーブルで検証しています。[移行アクション](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## 2つのスナップショットと公開された1件の履歴

テストでは、Deltaログファイルの時刻を2秒ずらして設定します。Deltaの従来のタイムスタンプセレクターは、このファイル時刻を使います。一方、移行元に保存されたコミット情報の時刻は独立しており、成功したケースでは1ミリ秒ずれています。Icebergは保存された値を`delta-ts`タグの名前に使い、移行元の各バージョンに対して`delta-version`タグも作成します。[Delta履歴の時刻](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Icebergのタグ割り当て](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| 検索 | 観察結果 |
| --- | --- |
| 移行元の2番目のログファイル時刻でDeltaのタイムスタンプを検索 | 移行元のバージョン1 |
| Icebergの`delta-version-0`タグ | 先に移行されたスナップショット |
| Deltaの2番目のログファイル時刻でIcebergのタイムスタンプを検索 | 一致する公開済み履歴なし |
| 移行先の最初のスナップショットの作成時刻でIcebergのタイムスタンプを検索 | 一致する公開済み履歴なし |
| 移行先の公開済み履歴の時刻でIcebergのタイムスタンプを検索 | 最後に移行されたスナップショット |

移行では、両方のリプレイを1つの作成トランザクション内でステージします。Icebergのメタデータビルダーは、中間のmainスナップショットのエントリを公開履歴から除外します。先のスナップショットとそのタグは引き続き利用できます。タイムスタンプの解決処理は公開履歴を検索します。最初のフィクスチャでは2件のエントリを想定していたため、そのアサーションで停止しました。修正後のフィクスチャでは、タグ付きの両スナップショットと、最後のスナップショットのみを含む履歴を別々に確認しました。[中間ログエントリのフィルター](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [履歴の解決処理](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [以前の履歴の変更](https://github.com/apache/iceberg/pull/5568)

## 保存時刻の重複

対になるケースでも、移行元には順序のある2つのログファイル時刻があり、元の両バージョンをそれぞれの時刻を境に読み取れます。一方、保存された2つのコミット情報のタイムスタンプは同じです。2回目のリプレイは同じ`delta-ts-1577836800000`タグを作成しようとし、作成トランザクションのコミット前にIcebergの参照重複チェックに引っかかります。カタログはテーブルが存在しないと報告します。別途ファイルを確認したところ、合計8,641バイトのステージ済みAvroファイルが2つ見つかりました。このフィクスチャは、アクションが使う従来の保存済みタイムスタンプを検証します。新しいDeltaの`inCommitTimestamp`は別のプロトコルフィールドです。提案中のDelta Kernel移行実装には、重複する時刻タグをスキップするロジックがすでに含まれています。[参照重複チェック](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Deltaタグ名の算出](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Deltaプロトコル](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [提案中のKernelでの処理](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

過去のデータを参照する利用者向けの移行では、移行元のバージョン、移行元セレクターが使う時刻、移行先のスナップショット参照をまとめて保存してください。名前付き参照とタイムスタンプによる読み取りは、それぞれ事前に試してください。作成に失敗した場合は、カタログと移行先のファイルも別々に確認する必要があります。今回の実行では、空の合成テーブルとローカルのHadoopCatalogでこれらの処理を測定しました。Spark SQL、レコードの一致、再試行時の動作、その他のカタログは測定していません。

## 再現する

[ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java)、[pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml)、[観察結果](https://sapien1.com/research/iceberg-delta-clock/observations.json)を1つのフォルダーにダウンロードします。そのフォルダーからJDK 17とMavenを使います。検証済みの実行では、Liberica JDK Lite 17.0.21.0.3+5とMaven 3.9.16を使用しました。Mavenは固定された依存関係のバージョンを解決し、一時ディレクトリに配置します。Javaソースランチャーは、新たに書き込まれた2組のログファイルに対して移行を実行します。[Mavenのclasspathゴール](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Javaソースランチャー](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html)

```
set -eu
sapien_delta_run=$(mktemp -d)
trap 'rm -rf -- "$sapien_delta_run"' EXIT
mkdir "$sapien_delta_run/fixture"
mvn -C -B -q -f pom.xml -Dmaven.repo.local="$sapien_delta_run/repository" \
  org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath \
  -DincludeScope=runtime -Dmdep.outputFile="$sapien_delta_run/classpath.txt"
java --class-path "$(cat "$sapien_delta_run/classpath.txt")" --source 17 ClockReplay.java \
  "$sapien_delta_run/fixture"
sapien_delta_warehouse="$sapien_delta_run/fixture/warehouse/fixture"
cat "$sapien_delta_warehouse/distinct_times/metadata/v1.metadata.json"
find "$sapien_delta_warehouse/repeated_time" -type f -exec wc -c {} +
```

チェッカーは次の2行の結果を出力します。

```
DISTINCT sourceCutoffVersion=1 migratedSnapshots=2 migrationTags=4 publishedHistoryEntries=1 targetCutoffSnapshot=null
REPEATED duplicateTimestampTagRejected=true catalogTableExists=false
```

メタデータの読み戻しでは、`snapshots`、`refs`、`snapshot-log`を確認できます。最後のコマンドは、一時ファイルを削除する前に、失敗した移行先のファイルを一覧表示します。スナップショットID、作成時刻、ステージ済みファイルの名前は実行ごとに変わることがあります。保持されたタグの対応関係と、カタログおよびタイムスタンプ検索の結果を比較してください。
