# Миграция 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` | Более ранний перенесённый снимок |
| Поиск Iceberg по времени второго файла журнала Delta | Подходящей записи в опубликованной истории нет |
| Поиск Iceberg по времени создания первого целевого снимка | Подходящей записи в опубликованной истории нет |
| Поиск Iceberg по опубликованному времени истории целевой таблицы | Последний перенесённый снимок |

Миграция подготавливает оба воспроизведения в одной транзакции создания. Механизм построения метаданных Iceberg исключает промежуточные записи основного снимка из публикуемой истории. Более ранний снимок и его теги остаются доступны. Механизм разрешения временных меток ищет по опубликованной истории. Наш первый тестовый набор ожидал две записи и остановился на этой проверке. В исправленном наборе оба снимка с тегами и история, содержащая только последний снимок, проверялись отдельно. [Фильтр промежуточных записей журнала](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 для пути к классам](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`. Последняя команда составляет список файлов в целевом расположении после неудачного создания, прежде чем временные файлы будут удалены. Идентификаторы снимков, время создания и имена промежуточных файлов могут отличаться при разных запусках. Сравните сохранённое соответствие тегов, а также результаты проверок каталога и поиска по временной метке.
