# Delta 迁移可能创建标签并改变时间戳历史

Iceberg 1.12.0 将一个空的合成 Delta 表的两个版本迁移为两个快照，并根据源版本号和存储的提交信息时间创建了四个标签。目标表发布了一条时间戳历史记录，对应最终快照。在第二次迁移中，两个相同的存储提交时间导致重复标签错误。目标表在本地目录中仍然不存在，其仓库路径下留下了两个暂存的 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 的旧版时间戳选择器使用这些文件时间。在成功的案例中，源表独立存储的提交信息时间相隔一毫秒。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` 标签 | 较早迁移的快照 |
| 按第二个 Delta 日志文件的时间查询 Iceberg 时间戳 | 没有匹配的已发布历史记录 |
| 按第一个目标快照的创建时间查询 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)

## 重复的存储时间

在配对案例中，源表仍有两个按顺序排列的日志文件时间，因此原有的两个版本时间截点都仍可读取。它存储的两个提交信息时间戳相同。第二次重放尝试创建相同的 `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 classpath 目标](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`。最后一条命令在清理临时文件之前列出创建失败的目标表文件。快照 ID、创建时间和暂存文件名可能因运行而异。请比较保留的标签映射，以及目录和时间戳查询结果。
