# Delta 마이그레이션은 태그를 생성하고 타임스탬프 이력을 바꿀 수 있습니다

Iceberg 1.12.0은 비어 있는 합성 Delta 테이블의 두 버전을 두 스냅샷으로 마이그레이션하고, 원본 버전 번호와 저장된 커밋 정보 시간을 바탕으로 태그 4개를 생성했습니다. 대상에는 마지막 스냅샷에 대한 타임스탬프 이력 항목 하나가 게시됐습니다. 두 번째 마이그레이션에서는 저장된 커밋 시간 두 개가 같아 중복 태그 오류가 발생했습니다. 로컬 카탈로그에는 대상이 생성되지 않은 상태로 남았고, 대상의 웨어하우스 경로 아래에는 준비된 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 로그 파일 시간을 2초 간격으로 설정합니다. Delta의 레거시 타임스탬프 선택기는 이 파일 시간을 사용합니다. 성공 사례에서 원본에 별도로 저장된 커밋 정보 시간은 1밀리초 차이가 납니다. 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의 중복 참조 검사에 걸립니다. 카탈로그는 테이블이 없다고 보고합니다. 별도의 파일 검사에서는 합계 8,641바이트인 준비된 Avro 파일 두 개가 발견됐습니다. 이 픽스처는 액션이 사용하는 레거시 저장 타임스탬프를 검증합니다. 최신 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`를 확인할 수 있습니다. 마지막 명령은 임시 파일을 정리하기 전에 실패한 대상의 파일 목록을 확인합니다. 스냅샷 ID, 생성 시간, 준비된 파일 이름은 실행마다 달라질 수 있습니다. 유지된 태그 매핑과 카탈로그 및 타임스탬프 결과를 비교하세요.
