# Migrace z Delty může vytvořit tagy a změnit historii časových značek

Iceberg 1.12.0 migroval dvě verze prázdné syntetické tabulky Delta do dvou snímků a vytvořil čtyři tagy z čísel zdrojových verzí a uložených časů v informacích o commitu. V cílové tabulce publikoval jeden záznam historie časových značek, a to pro poslední snímek. Při druhé migraci vedly dva shodné uložené časy commitů k chybě duplicitního tagu. Cílová tabulka zůstala v místním katalogu nepřítomná a pod její cestou ve skladu zůstaly dva připravené soubory Avro. [Testovací data](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) a [pozorování](https://sapien1.com/research/iceberg-delta-clock/observations.json) vycházejí z prázdných místních tabulek s Delta Standalone 3.3.3 a HadoopCatalog. [Migrační akce](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## Dva snímky a jeden publikovaný záznam historie

Test nastavuje časy souborů protokolu Delta s dvousekundovým odstupem. Starší mechanismus Delty pro výběr podle časové značky používá časy těchto souborů. Nezávisle uložené časy v informacích o commitu zdroje se v úspěšném případě liší o jednu milisekundu. Iceberg používá tyto uložené hodnoty k pojmenování tagů `delta-ts` a pro každou zdrojovou verzi také vytváří tag `delta-version`. [Časové údaje v historii Delty](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Přiřazování tagů v Icebergu](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| Dotaz | Zjištěný výsledek |
| --- | --- |
| Dotaz na časovou značku v Deltě při čase druhého zdrojového souboru protokolu | Zdrojová verze 1 |
| Tag Icebergu `delta-version-0` | Dřívější migrovaný snímek |
| Dotaz na časovou značku v Icebergu při čase druhého souboru protokolu Delta | Žádný odpovídající publikovaný záznam historie |
| Dotaz na časovou značku v Icebergu při čase vytvoření prvního cílového snímku | Žádný odpovídající publikovaný záznam historie |
| Dotaz na časovou značku v Icebergu při čase publikovaném v historii cílové tabulky | Poslední migrovaný snímek |

Migrace připraví obě opakovaná provedení v jedné transakci vytvoření. Nástroj Icebergu pro sestavení metadat odfiltruje z publikované historie mezilehlé záznamy snímků hlavní větve. Dřívější snímek a jeho tagy zůstávají dostupné. Vyhledávání podle časové značky prochází publikovanou historii. Naše první sada testovacích dat očekávala dva záznamy a skončila při ověření tohoto předpokladu. Opravená sada ověřila oba snímky s tagy a samostatně také historii obsahující pouze poslední snímek. [Filtrování mezilehlých záznamů protokolu](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [Vyhledávání v historii](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [Dřívější změna historie](https://github.com/apache/iceberg/pull/5568)

## Opakované uložené časy

Ve druhém případu má zdroj stále dva časově seřazené časy souborů protokolu, takže obě původní verze lze pomocí jejich časových hranic nadále načíst. Obě uložené časové značky v informacích o commitu jsou shodné. Druhé opakované provedení se pokusí vytvořit stejný tag `delta-ts-1577836800000` a narazí na kontrolu duplicitních referencí v Icebergu dříve, než je transakce vytvoření potvrzena. Katalog hlásí, že tabulka neexistuje. Samostatná kontrola souborů našla dva připravené soubory Avro o celkové velikosti 8 641 bajtů. Testovací data ověřují starší uloženou časovou značku, kterou akce používá. `inCommitTimestamp` v novější Deltě je samostatné pole protokolu. Navrhovaná implementace migrace pomocí Delta Kernel již obsahuje logiku pro přeskočení opakovaných časových tagů. [Kontrola duplicitních referencí](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Výpočet názvu tagu Delty](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Protokol Delty](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [Navrhované zpracování v Kernelu](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

U migrace, jejíž historická data používají další systémy, uložte zdrojovou verzi, časový údaj použitý pro výběr ve zdroji a referenci na cílový snímek společně. Samostatně vyzkoušejte čtení pomocí pojmenovaných referencí a časových značek. Po neúspěšném vytvoření je také třeba samostatně zkontrolovat katalog a soubory v cílovém umístění. Naše běhy měřily tyto postupy na prázdných syntetických tabulkách a v místním HadoopCatalogu. Spark SQL, shoda záznamů, chování při opakování a další katalogy zůstávají neověřené.

## Postup reprodukce

Stáhněte [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml) a [pozorování](https://sapien1.com/research/iceberg-delta-clock/observations.json) do jedné složky. V této složce použijte JDK 17 a Maven. Ověřený běh používal Liberica JDK Lite 17.0.21.0.3+5 a Maven 3.9.16. Maven stáhne pevně určené verze závislostí do dočasného adresáře. Spouštěč zdrojového kódu Java provede migraci nad dvěma nově zapsanými dvojicemi souborů protokolu. [Cíl Maven pro sestavení classpath](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Spouštěč zdrojového kódu 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 {} +
```

Kontrolní program vypíše tyto dva řádky s výsledky.

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

Načtená metadata zpřístupňují `snapshots`, `refs` a `snapshot-log`. Poslední příkaz před odstraněním dočasných souborů vypíše obsah cílového umístění po neúspěšném vytvoření. ID snímků, časy vytvoření a názvy připravených souborů se mohou mezi běhy lišit. Porovnejte zachované přiřazení tagů a výsledky ověření katalogu a dotazů na časové značky.
