# Uma migração Delta pode criar tags e alterar o histórico de timestamps

O Iceberg 1.12.0 migrou duas versões de uma tabela Delta sintética vazia para dois snapshots e criou quatro tags a partir dos números de versão da origem e dos tempos de commit-info armazenados. O destino publicou uma entrada no histórico de timestamps, referente ao snapshot final. Em uma segunda migração, dois tempos de commit armazenados iguais produziram um erro de tag duplicada. O destino permaneceu ausente do catálogo local e dois arquivos Avro preparados permaneceram no caminho do seu warehouse. O [programa de teste](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) e as [observações](https://sapien1.com/research/iceberg-delta-clock/observations.json) usam tabelas locais vazias com Delta Standalone 3.3.3 e HadoopCatalog. [Ação de migração](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## Dois snapshots e uma entrada no histórico publicado

O teste define os horários dos arquivos de log Delta com dois segundos de intervalo. O seletor legado de timestamps do Delta usa esses horários dos arquivos. Os tempos de commit-info armazenados separadamente na origem têm um milissegundo de intervalo no caso bem-sucedido. O Iceberg usa esses valores armazenados para nomear as tags `delta-ts` e também cria uma tag `delta-version` para cada versão da origem. [Relógios do histórico Delta](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [Atribuição de tags no 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 timestamp no Delta no horário do segundo arquivo de log da origem | Versão 1 da origem |
| Tag `delta-version-0` do Iceberg | O snapshot migrado anterior |
| Consulta por timestamp no Iceberg no horário do segundo arquivo de log Delta | Nenhuma entrada correspondente no histórico publicado |
| Consulta por timestamp no Iceberg no horário de criação do primeiro snapshot de destino | Nenhuma entrada correspondente no histórico publicado |
| Consulta por timestamp no Iceberg no horário do histórico publicado do destino | O snapshot migrado final |

A migração prepara as duas reproduções em uma única transação de criação. O construtor de metadados do Iceberg filtra as entradas intermediárias do snapshot principal do histórico publicado. O snapshot anterior e suas tags permanecem disponíveis. O resolvedor de timestamps pesquisa o histórico publicado. Nosso primeiro fixture esperava duas entradas e parou nessa asserção. O fixture corrigido verificou separadamente os dois snapshots com tags e o histórico contendo apenas o snapshot final. [Filtro de entradas intermediárias do log](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [Resolvedor de histórico](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [Alteração anterior no histórico](https://github.com/apache/iceberg/pull/5568)

## Tempos armazenados repetidos

No caso correspondente, a origem ainda tem dois horários ordenados de arquivos de log, então os dois pontos de corte das versões originais continuam acessíveis. Seus dois timestamps de commit-info armazenados são iguais. A segunda reprodução tenta criar a mesma tag `delta-ts-1577836800000` e encontra a verificação de referências duplicadas do Iceberg antes que a transação de criação seja confirmada. O catálogo informa que a tabela está ausente. Uma inspeção separada dos arquivos encontrou dois arquivos Avro preparados, totalizando 8.641 bytes. O fixture exercita o timestamp legado armazenado usado pela ação. O `inCommitTimestamp` das versões mais recentes do Delta é um campo separado do protocolo. Uma implementação proposta de migração com Delta Kernel já inclui lógica para ignorar tags de tempo repetidas. [Verificação de referências duplicadas](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [Cálculo do nome da tag Delta](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [Protocolo Delta](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [Tratamento proposto no Kernel](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

Para uma migração que atende a consumidores de dados históricos, salve juntos a versão da origem, o relógio do seletor de origem e a referência ao snapshot de destino. Teste separadamente as leituras por referência nomeada e por timestamp. Uma criação malsucedida também exige verificações separadas do catálogo e dos arquivos de destino. Nossas execuções avaliaram esses caminhos em tabelas sintéticas vazias e um HadoopCatalog local. Spark SQL, igualdade de registros, comportamento de novas tentativas e outros catálogos ainda não foram avaliados.

## Reproduzir

Baixe [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml) e as [observações](https://sapien1.com/research/iceberg-delta-clock/observations.json) em uma mesma pasta. Nessa pasta, use JDK 17 e Maven. A execução verificada usou Liberica JDK Lite 17.0.21.0.3+5 e Maven 3.9.16. O Maven resolve as versões fixas das dependências no diretório temporário. O inicializador de código-fonte Java executa a migração em dois pares de arquivos de log recém-criados. [Objetivo de classpath do Maven](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [Inicializador de código-fonte 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 {} +
```

O verificador imprime estas duas linhas de resultado.

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

A leitura dos metadados expõe `snapshots`, `refs` e `snapshot-log`. O comando final lista os arquivos do destino da criação malsucedida antes da limpeza temporária. IDs de snapshots, horários de criação e nomes dos arquivos preparados podem variar entre execuções. Compare o mapeamento de tags preservado e os resultados do catálogo e das consultas por timestamp.
