# Een Delta-migratie kan tags aanmaken en de tijdstempelgeschiedenis wijzigen

Iceberg 1.12.0 migreerde twee versies van een lege synthetische Delta-tabel naar twee snapshots en maakte vier tags aan op basis van de versienummers en opgeslagen commit-info-tijden van de bron. De bestemming publiceerde één vermelding in de tijdstempelgeschiedenis, voor de laatste snapshot. Bij een tweede migratie leidden twee gelijke opgeslagen commit-tijden tot een fout door een dubbele tag. De bestemming bleef afwezig in de lokale catalogus en onder het warehousepad bleven twee tijdelijke Avro-bestanden achter. De [testopstelling](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) en [waarnemingen](https://sapien1.com/research/iceberg-delta-clock/observations.json) gebruiken lege lokale tabellen met Delta Standalone 3.3.3 en HadoopCatalog. [Migratieactie](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## Twee snapshots en één gepubliceerde geschiedenisvermelding

De test stelt de tijden van de Delta-logbestanden twee seconden uit elkaar in. Delta’s oude tijdstempelselector gebruikt die bestandstijden. De apart opgeslagen commit-info-tijden van de bron liggen in het geslaagde geval één milliseconde uit elkaar. Iceberg gebruikt die opgeslagen waarden om de `delta-ts`-tags een naam te geven en maakt voor elke bronversie ook een `delta-version`-tag aan. [Klokken in de Delta-geschiedenis](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Toewijzing van Iceberg-tags](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| Zoekopdracht | Waargenomen resultaat |
| --- | --- |
| Delta-zoekopdracht op tijdstempel bij de tijd van het tweede bronlogbestand | Bronversie 1 |
| Iceberg-tag `delta-version-0` | De eerder gemigreerde snapshot |
| Iceberg-zoekopdracht op tijdstempel bij de tijd van het tweede Delta-logbestand | Geen overeenkomende vermelding in de gepubliceerde geschiedenis |
| Iceberg-zoekopdracht op tijdstempel bij de aanmaaktijd van de eerste doelsnapshot | Geen overeenkomende vermelding in de gepubliceerde geschiedenis |
| Iceberg-zoekopdracht op tijdstempel bij de gepubliceerde geschiedenistijd van de bestemming | De laatst gemigreerde snapshot |

De migratie bereidt beide replays voor binnen één aanmaaktransactie. De metadatabuilder van Iceberg filtert vermeldingen van tussenliggende hoofdsnapshots uit de gepubliceerde geschiedenis. De eerdere snapshot en de bijbehorende tags blijven beschikbaar. De tijdstempelresolver doorzoekt de gepubliceerde geschiedenis. Onze eerste testopstelling verwachtte twee vermeldingen en stopte bij die controle. De gecorrigeerde testopstelling controleerde beide getagde snapshots en de geschiedenis met alleen de laatste snapshot afzonderlijk. [Filter voor tussenliggende logvermeldingen](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [Geschiedenisresolver](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [Eerdere wijziging in de geschiedenis](https://github.com/apache/iceberg/pull/5568)

## Herhaalde opgeslagen tijden

In het bijbehorende testgeval heeft de bron nog steeds twee chronologisch geordende logbestandstijden, zodat beide oorspronkelijke versiegrenzen leesbaar blijven. De twee opgeslagen commit-info-tijdstempels zijn gelijk. De tweede replay probeert dezelfde tag `delta-ts-1577836800000` aan te maken en stuit op Icebergs controle op dubbele referenties voordat de aanmaaktransactie wordt vastgelegd. De catalogus meldt dat de tabel afwezig is. Bij een afzonderlijke bestandsinspectie zijn twee tijdelijke Avro-bestanden gevonden met een gezamenlijke grootte van 8.641 bytes. De testopstelling gebruikt de oude opgeslagen tijdstempel die de actie gebruikt. `inCommitTimestamp` in nieuwere versies van Delta is een afzonderlijk protocolveld. Een voorgestelde migratie-implementatie met Delta Kernel bevat al logica om herhaalde tijdtags over te slaan. [Controle op dubbele referenties](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Berekening van de Delta-tagnaam](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Delta-protocol](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [Voorgestelde verwerking in Kernel](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

Sla bij een migratie voor gebruikers van historische gegevens de bronversie, de klok van de bronselector en de referentie naar de doelsnapshot samen op. Test leesopdrachten met benoemde referenties en met tijdstempels afzonderlijk. Controleer na een mislukte aanmaak ook de catalogus en de doelbestanden afzonderlijk. Onze tests hebben deze paden gemeten op lege synthetische tabellen en een lokale HadoopCatalog. Spark SQL, gelijkheid van records, gedrag bij opnieuw proberen en andere catalogi zijn niet gemeten.

## Reproduceren

Download [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml) en de [waarnemingen](https://sapien1.com/research/iceberg-delta-clock/observations.json) naar één map. Gebruik vanuit die map JDK 17 en Maven. De geverifieerde test gebruikte Liberica JDK Lite 17.0.21.0.3+5 en Maven 3.9.16. Maven haalt de vastgelegde afhankelijkheidsversies op in de tijdelijke map. Java voert het bronbestand voor de migratie rechtstreeks uit op twee nieuw geschreven paren logbestanden. [Maven-classpathdoel](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Een bronbestand rechtstreeks uitvoeren met 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 {} +
```

De controle geeft deze twee resultaatregels weer.

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

Bij het teruglezen van de metadata zijn `snapshots`, `refs` en `snapshot-log` beschikbaar. De laatste opdracht inventariseert de mislukte bestemming voordat de tijdelijke bestanden worden opgeruimd. Snapshot-ID’s, aanmaaktijden en namen van tijdelijke bestanden kunnen per uitvoering verschillen. Vergelijk de behouden koppeling van tags en de resultaten voor de catalogus en tijdstempels.
