# Una migración de Delta puede crear etiquetas y cambiar el historial de marcas de tiempo

Iceberg 1.12.0 migró dos versiones de una tabla sintética de Delta vacía a dos instantáneas y creó cuatro etiquetas a partir de los números de versión de origen y las horas almacenadas en la información de confirmación. El destino publicó una entrada en el historial de marcas de tiempo, correspondiente a la instantánea final. En una segunda migración, dos horas de confirmación almacenadas iguales produjeron un error de etiqueta duplicada. La tabla de destino siguió ausente del catálogo local y quedaron dos archivos Avro preparados bajo su ruta en el almacén. El [caso de prueba](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) y las [observaciones](https://sapien1.com/research/iceberg-delta-clock/observations.json) utilizan tablas locales vacías con Delta Standalone 3.3.3 y HadoopCatalog. [Acción de migración](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## Dos instantáneas y una entrada de historial publicada

La prueba establece las horas de los archivos de registro de Delta con dos segundos de diferencia. El selector de marcas de tiempo heredado de Delta utiliza esas horas de archivo. Las horas de la información de confirmación almacenadas por separado en el origen difieren en un milisegundo en el caso satisfactorio. Iceberg utiliza esos valores almacenados para nombrar las etiquetas `delta-ts` y también crea una etiqueta `delta-version` para cada versión de origen. [Relojes del historial de Delta](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Asignación de etiquetas de Iceberg](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| Consulta | Resultado observado |
| --- | --- |
| Consulta por marca de tiempo de Delta a la hora del segundo archivo de registro de origen | Versión 1 de origen |
| Etiqueta `delta-version-0` de Iceberg | La instantánea migrada anterior |
| Consulta por marca de tiempo de Iceberg a la hora del segundo archivo de registro de Delta | Ninguna entrada publicada del historial coincide |
| Consulta por marca de tiempo de Iceberg a la hora de creación de la primera instantánea de destino | Ninguna entrada publicada del historial coincide |
| Consulta por marca de tiempo de Iceberg a la hora del historial publicado del destino | La instantánea migrada final |

La migración prepara ambas reproducciones en una sola transacción de creación. El constructor de metadatos de Iceberg filtra las entradas intermedias de la instantánea principal del historial publicado. La instantánea anterior y sus etiquetas siguen disponibles. El resolvedor de marcas de tiempo busca en el historial publicado. Nuestro primer caso de prueba esperaba dos entradas y se detuvo en esa aserción. El caso corregido comprobó por separado las dos instantáneas etiquetadas y el historial con solo la entrada final. [Filtro de entradas intermedias del registro](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [Resolvedor del historial](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [Cambio anterior en el historial](https://github.com/apache/iceberg/pull/5568)

## Horas almacenadas repetidas

En el caso emparejado, el origen sigue teniendo dos horas de archivo de registro ordenadas, por lo que ambos puntos de corte de versión originales siguen siendo legibles. Sus dos marcas de tiempo almacenadas en la información de confirmación son iguales. La segunda reproducción intenta crear la misma etiqueta `delta-ts-1577836800000` y encuentra la comprobación de referencias duplicadas de Iceberg antes de que se confirme la transacción de creación. El catálogo indica que la tabla está ausente. Una inspección independiente de archivos encontró dos archivos Avro preparados con un total de 8.641 bytes. El caso de prueba ejercita la marca de tiempo heredada almacenada que utiliza la acción. El `inCommitTimestamp` de las versiones más recientes de Delta es un campo de protocolo independiente. Una implementación propuesta de migración con Delta Kernel ya incluye lógica para omitir las etiquetas de tiempo repetidas. [Comprobación de referencias duplicadas](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Cálculo del nombre de la etiqueta de Delta](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Protocolo de Delta](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [Tratamiento propuesto en Kernel](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

Para una migración que atienda a consumidores de datos históricos, guarda juntas la versión de origen, el reloj del selector de origen y la referencia de la instantánea de destino. Prueba por separado las lecturas por referencia con nombre y por marca de tiempo. Si falla una creación, comprueba también por separado el catálogo y los archivos de destino. Nuestras ejecuciones midieron estas rutas en tablas sintéticas vacías y un HadoopCatalog local. Spark SQL, la igualdad de registros, el comportamiento de los reintentos y otros catálogos siguen sin medirse.

## Reproducir

Descarga [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml) y las [observaciones](https://sapien1.com/research/iceberg-delta-clock/observations.json) en una misma carpeta. Desde esa carpeta, utiliza JDK 17 y Maven. La ejecución verificada utilizó Liberica JDK Lite 17.0.21.0.3+5 y Maven 3.9.16. Maven resuelve las versiones fijas de las dependencias en el directorio temporal. El lanzador de código fuente de Java ejecuta la migración sobre dos pares de archivos de registro recién escritos. [Objetivo de classpath de Maven](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Lanzador de código fuente de 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 {} +
```

El verificador muestra estas dos líneas de resultado.

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

La lectura de los metadatos expone `snapshots`, `refs` y `snapshot-log`. El último comando inventaría el destino de la creación fallida antes de la limpieza temporal. Los ID de las instantáneas, las horas de creación y los nombres de los archivos preparados pueden variar entre ejecuciones. Compara la asignación de etiquetas conservada y los resultados del catálogo y de las consultas por marca de tiempo.
