# Delta 移轉可能建立標籤並改變時間戳記歷史紀錄

Iceberg 1.12.0 將空的合成 Delta 資料表的兩個版本移轉為兩個快照，並依來源版本編號與儲存的 commit-info 時間建立四個標籤。目標資料表發布了一筆時間戳記歷史紀錄，對應最後一個快照。第二次移轉中，兩個相同的已儲存提交時間導致標籤重複錯誤。目標資料表仍未出現在本機目錄中，且其倉儲路徑下留下兩個暫存的 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)

## 兩個快照，一筆已發布的歷史紀錄

測試將 Delta 日誌檔案時間設為相隔兩秒。Delta 的舊版時間戳記選取器使用這些檔案時間。成功案例中，來源另外儲存的 commit-info 時間相隔一毫秒。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)

| 查詢 | 觀察結果 |
| --- | --- |
| 以第二個來源日誌檔案時間查詢 Delta 時間戳記 | 來源版本 1 |
| Iceberg `delta-version-0` 標籤 | 較早移轉的快照 |
| 以第二個 Delta 日誌檔案時間查詢 Iceberg 時間戳記 | 沒有相符的已發布歷史紀錄 |
| 以第一個目標快照的建立時間查詢 Iceberg 時間戳記 | 沒有相符的已發布歷史紀錄 |
| 以目標資料表已發布的歷史紀錄時間查詢 Iceberg 時間戳記 | 最後移轉的快照 |

移轉作業在同一個建立交易中暫存兩次重播。Iceberg 的中繼資料建構器會從已發布的歷史紀錄中篩除中間的 main 快照項目。較早的快照及其標籤仍可使用。時間戳記解析器會搜尋已發布的歷史紀錄。我們的第一個測試案例預期有兩筆紀錄，並在該斷言處停止。修正後的測試案例分別檢查兩個附有標籤的快照，以及僅含最後一筆的歷史紀錄。[中間日誌項目篩選](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)

## 重複的已儲存時間

在配對案例中，來源仍有兩個依序排列的日誌檔案時間，因此原本兩個版本的時間截點都仍可讀取。其儲存的兩個 commit-info 時間戳記相同。第二次重播嘗試建立相同的 `delta-ts-1577836800000` 標籤，並在建立交易提交前觸發 Iceberg 的重複參照檢查。目錄回報資料表不存在。另行檢查檔案後，發現兩個暫存的 Avro 檔案，合計 8,641 位元組。此測試案例涵蓋該動作使用的舊版已儲存時間戳記。較新版 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)下載至同一個資料夾。在該資料夾中使用 JDK 17 和 Maven。經驗證的執行環境使用 Liberica JDK Lite 17.0.21.0.3+5 和 Maven 3.9.16。Maven 會將固定版本的相依套件解析至暫存目錄。Java 原始碼啟動器會針對新寫入的兩組日誌檔案執行移轉。[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 {} +
```

檢查程式會輸出以下兩行結果。

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

讀回的中繼資料包含 `snapshots`、`refs` 和 `snapshot-log`。最後一個命令會在清除暫存資料前，列出建立失敗的目標資料表中的檔案。快照 ID、建立時間與暫存檔名可能因執行次數而異。請比較保留的標籤對應關係，以及目錄和時間戳記查詢結果。
