# Migrasi Delta dapat membuat tag dan mengubah riwayat cap waktu

Iceberg 1.12.0 memigrasikan dua versi tabel Delta sintetis kosong menjadi dua snapshot dan membuat empat tag dari nomor versi sumber serta waktu commit-info yang tersimpan. Tujuan memublikasikan satu entri riwayat cap waktu, untuk snapshot terakhir. Dalam migrasi kedua, dua waktu commit tersimpan yang sama menghasilkan error tag duplikat. Tabel tujuan tetap tidak ada di katalog lokal, dan dua file Avro yang disiapkan masih berada di bawah jalur warehouse-nya. [Fixture](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) dan [hasil pengamatan](https://sapien1.com/research/iceberg-delta-clock/observations.json) menggunakan tabel lokal kosong dengan Delta Standalone 3.3.3 dan HadoopCatalog. [Aksi migrasi](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## Dua snapshot dan satu entri riwayat yang dipublikasikan

Pengujian menetapkan waktu file log Delta dengan selisih dua detik. Pemilih cap waktu legacy Delta menggunakan waktu file tersebut. Waktu commit-info sumber yang disimpan secara terpisah memiliki selisih satu milidetik dalam kasus yang berhasil. Iceberg menggunakan nilai tersimpan tersebut untuk menamai tag `delta-ts` dan juga membuat tag `delta-version` untuk setiap versi sumber. [Jam riwayat Delta](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Penetapan tag Iceberg](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| Pencarian | Hasil pengamatan |
| --- | --- |
| Pencarian cap waktu Delta pada waktu file log sumber kedua | Versi sumber 1 |
| Tag Iceberg `delta-version-0` | Snapshot hasil migrasi yang lebih awal |
| Pencarian cap waktu Iceberg pada waktu file log Delta kedua | Tidak ada entri riwayat yang dipublikasikan yang cocok |
| Pencarian cap waktu Iceberg pada waktu pembuatan snapshot tujuan pertama | Tidak ada entri riwayat yang dipublikasikan yang cocok |
| Pencarian cap waktu Iceberg pada waktu riwayat tujuan yang dipublikasikan | Snapshot hasil migrasi terakhir |

Migrasi menyiapkan kedua replay dalam satu transaksi pembuatan. Pembuat metadata Iceberg menyaring entri snapshot utama perantara dari riwayat yang dipublikasikan. Snapshot yang lebih awal dan tag-nya tetap tersedia. Resolver cap waktu mencari di riwayat yang dipublikasikan. Fixture pertama kami mengharapkan dua entri dan berhenti pada asersi tersebut. Fixture yang sudah diperbaiki memeriksa kedua snapshot bertag dan riwayat yang hanya memuat snapshot terakhir secara terpisah. [Filter entri log perantara](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [Resolver riwayat](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [Perubahan riwayat sebelumnya](https://github.com/apache/iceberg/pull/5568)

## Waktu tersimpan yang berulang

Dalam kasus pembanding, sumber tetap memiliki dua waktu file log yang berurutan, sehingga kedua batas versi asli masih dapat dibaca. Kedua cap waktu commit-info yang tersimpan sama. Replay kedua mencoba membuat tag `delta-ts-1577836800000` yang sama dan terkena pemeriksaan referensi duplikat Iceberg sebelum transaksi pembuatan di-commit. Katalog melaporkan bahwa tabel tidak ada. Pemeriksaan file terpisah menemukan dua file Avro yang disiapkan dengan total 8.641 byte. Fixture ini menguji cap waktu tersimpan legacy yang digunakan oleh aksi tersebut. `inCommitTimestamp` pada Delta yang lebih baru adalah field protokol terpisah. Implementasi migrasi Delta Kernel yang diusulkan sudah mencakup logika untuk melewati tag waktu yang berulang. [Pemeriksaan referensi duplikat](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Perhitungan nama tag Delta](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Protokol Delta](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [Penanganan Kernel yang diusulkan](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

Untuk migrasi yang melayani konsumen data historis, simpan versi sumber, jam pemilih sumber, dan referensi snapshot tujuan secara bersama. Uji pembacaan referensi bernama dan cap waktu secara terpisah. Pembuatan yang gagal juga memerlukan pemeriksaan terpisah pada katalog dan file tujuan. Pengujian kami mengukur jalur ini pada tabel sintetis kosong dan HadoopCatalog lokal. Spark SQL, kesetaraan record, perilaku percobaan ulang, dan katalog lain belum diukur.

## Reproduksi

Unduh [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml), dan [hasil pengamatan](https://sapien1.com/research/iceberg-delta-clock/observations.json) ke dalam satu folder. Dari folder tersebut, gunakan JDK 17 dan Maven. Pengujian yang diverifikasi menggunakan Liberica JDK Lite 17.0.21.0.3+5 dan Maven 3.9.16. Maven menyelesaikan versi dependensi yang telah ditetapkan ke direktori sementara. Peluncur sumber Java menjalankan migrasi terhadap dua pasangan file log yang baru ditulis. [Goal classpath Maven](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Peluncur sumber 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 {} +
```

Pemeriksa mencetak dua baris hasil berikut.

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

Pembacaan ulang metadata menampilkan `snapshots`, `refs`, dan `snapshot-log`. Perintah terakhir mendata file pada tujuan yang gagal sebelum pembersihan sementara. ID snapshot, waktu pembuatan, dan nama file yang disiapkan dapat berbeda di setiap pengujian. Bandingkan pemetaan tag yang dipertahankan serta hasil katalog dan cap waktu.
