스냅샷 만료와 참조되지 않는 파일 제거

읽는 데 약 26분분 걸린다, 8절에 3개 예제이(가) 있음.

2026.11.10판 예제 통과 2026년 11월 20 39개 예제 중 39개 통과 변경 사항

AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식

영어판 2026.11.10판을 번역한 것이다. 원문 읽기

이 장을 읽고 나면 세 가지 형식 각각에서 오래된 스냅샷을 만료시키고, 그 스냅샷만 여전히 나열하던 데이터 파일을 제거하며, 만료된 스냅샷을 읽으면 실패함을 보일 수 있다.

압축도 같은 종류의 오래된 파일을 남긴다. 다시 쓰기 작업은 교체된 파일을 디스크에 그대로 두었는데, 이전 스냅샷이 여전히 그 파일을 나열하기 때문이다. 이 장에서는 wiki.pageviews_hourly의 오래된 스냅샷을 만료시킨 다음, 어떤 스냅샷도 더 이상 나열하지 않는 파일을 삭제한다. 이 장의 모든 예제는 정정 장의 02시 정정을 사용하되, 뒤쪽 절의 upsert 대신 해당 시간대를 덮어쓰는 방식으로 작성한다. 덮어쓰기는 형식마다 오래된 파일을 정확히 하나씩만 남기기 때문이다. 그 오래된 파일은 해당 스냅샷이 만료되고 파일이 제거될 때까지 남아 있다. 두 단계는 각 형식에서 모두 실행하며, 각 단계는 믿고 확인해야 하는 목록이 아니라 개수로 검증한다.

스냅샷은 파일을 살려 둔다

마지막으로 변경된 판: 2026.11.10판

모든 스냅샷은 해당 커밋 시점에 테이블을 구성하는 데이터 파일이 무엇인지 기록한다. 각 포맷이 그 목록을 어떻게 저장하는지는 스냅샷이 가리키는 것에서 다룬다. 이 장에서 중요한 점은, 행을 교체하는 커밋이 교체되는 파일을 삭제하지 않는다는 것이다. 커밋은 교체할 행을 담은 새 파일을 쓰고, 커밋 이전의 스냅샷은 여전히 옛 파일을 목록에 올려 두므로 타임 트래블이 계속 동작한다. 데이터 파일이 고아 파일이 되는 것은 보존 중인 어떤 스냅샷의 목록에도 오르지 않을 때뿐이다.

어느 포맷에서든 파일을 제거하는 데는 두 단계가 필요하다. 먼저 만료, 그다음 정리이다. Iceberg 유지 관리 문서도 같은 순서를 제시한다. 만료는 메타데이터에서 스냅샷을 제거하므로 타임 트래블이 그 스냅샷에 닿을 수 없게 되며, "데이터 파일은 타임 트래블이나 롤백에 쓰일 수 있는 스냅샷이 더 이상 참조하지 않을 때까지 삭제되지 않는다"(Apache Iceberg, maintenance). 만료 후에 정리 단계가 남은 어떤 스냅샷도 목록에 올리지 않은 파일을 삭제한다.

wiki.pageviews_hourly가 세 번의 시간별 추가(append)를 받고, 이어서 02시가 그 시간에 대한 덮어쓰기(overwrite)로 정정된다. 추가는 각각 파일 하나를 쓴다. 덮어쓰기는 정정된 02시 행을 담은 파일을 쓰고, 현재 스냅샷에서 옛 파일을 제거한다. 옛 파일을 추가했던 스냅샷은 여전히 그 파일을 목록에 올려 두고 있다. 그 스냅샷이 만료되기 전에는 해당 스냅샷으로의 타임 트래블을 깨뜨리지 않고서는 옛 파일을 삭제할 수 없다. 정정된 시간을 upsert하기는 같은 정정을 쓰는 다른 방법을 보여 주며, 이 방법 역시 같은 종류의 옛 파일을 남긴다.

포맷마다 고유한 만료 호출과 고유한 정리 호출이 있다. 아래 표에 이를 정리했으며, 이 장의 나머지는 각 포맷에 대해 같은 순서를 따른다.

포맷 만료 호출 만료가 파일을 삭제하는가? 정리 호출
Iceberg (pyiceberg) expire_snapshots().by_ids(...) 아니요 라이브러리에 없음: 파일을 직접 세어 제거한다
Delta Lake (deltalake) vacuum의 버전 보존 예, vacuum에 의해 vacuum
DuckLake ducklake_expire_snapshots 아니요 ducklake_cleanup_old_files, 이어서 ducklake_delete_orphaned_files

작업 규칙: 독자가 아직 필요로 할 수 있는 스냅샷이나 버전을 정하고, 파일을 제거하기 전에 나머지를 만료한다. 보존 중인 스냅샷이 여전히 목록에 올린 파일은 절대 제거하지 않으며, 삭제하기 전에 개수를 세어 이를 확인한다.

pyiceberg로 스냅샷 만료하기

마지막으로 변경된 판: 2026.11.7판

pyiceberg 0.12.0에서 table.maintenance.expire_snapshots()는 스냅샷 ID를 받는다. 목록에는 by_ids를, 하나에는 by_id를 사용하며, older_than 타임스탬프를 대신 줄 수도 있다. 마지막 N개의 스냅샷을 남기는 인자는 없다. 이 장에서는 사례에서와 마찬가지로 커밋 순서에서 ID를 고른다. 시간별 추가 세 번이 처음 세 스냅샷이다. ID 자체는 무작위 64비트 숫자이므로, 예제는 같은 순서로 "snapshot 1", "snapshot 2" 같은 레이블을 출력한다.

덮어쓰기는 스냅샷을 하나가 아니라 두 개 추가한다. pyiceberg는 이전 파일을 제거하는 삭제 스냅샷을 먼저 쓰고, 이어서 수정된 행을 추가하는 추가 스냅샷을 쓴다. 스냅샷 4는 삭제이고 스냅샷 5는 추가이다. 따라서 세 번의 추가를 만료시키면 덮어쓰기는 그대로 남으며, 예제가 확인하는 상태가 바로 이것이다.

만료 호출은 데이터 파일을 삭제하지 않으므로, 예제는 만료 전후에 파일 수를 직접 센다. 스냅샷이 나열하는 고유한 파일의 수와, 어떤 스냅샷도 나열하지 않으면서 디스크에 있는 파일의 수이다. 마지막 수를 살펴보라. 교체된 파일이 여기에 나타난다.

expire-iceberg-snapshots.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Expire the three append snapshots by ID, then count what the snapshots still reference. The point rests on theline that counts unreferenced data files on disk: expiry removes metadata, and the file the overwrite replaced stays."""from lib.lakehouse import (    ICEBERG_ID,    create_iceberg_table,    hour_corrections,    hour_filter,    new_warehouse,    orphan_data_files,    read_cut_hour,    scan_arrow,    snapshot_labels,)def referenced_files(table):    """Distinct data files that some retained snapshot lists. Count them; do not print them."""    # all_files() can list one file from several manifests, so the set counts each file once    return len(set(table.inspect.all_files()["file_path"].to_pylist()))with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in (0, 1, 2):        table.append(read_cut_hour(hour))    # hour_filter(2) matches only hour 02's rows, so the overwrite replaces that hour and leaves hours 00 and 01 alone    table.overwrite(hour_corrections(read_cut_hour(2)), overwrite_filter=hour_filter(2))    ids = [snapshot.snapshot_id for snapshot in table.metadata.snapshots]  # metadata lists snapshots in commit order    labels = snapshot_labels(ids)    print("snapshots before expiry:", len(ids))    print("data files referenced before expiry:", referenced_files(table))    print("data files in the current snapshot:", len(table.inspect.files()))  # files() reads the current snapshot only    expired = ids[:3]  # the three hourly appends, by commit order    table.maintenance.expire_snapshots().by_ids(expired).commit()    table = wh.catalog.load_table(ICEBERG_ID)    print("remaining snapshots:", ", ".join(labels[s.snapshot_id] for s in table.metadata.snapshots))    print("data files referenced after expiry:", referenced_files(table))    # files under the table location that no remaining snapshot lists; a file a writer has not committed counts too    print("unreferenced data files left on disk:", len(orphan_data_files(table)))    print("rows in the current snapshot:", scan_arrow(table).num_rows)    try:        scan_arrow(table, snapshot_id=expired[-1])    except ValueError as exc:        print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
출력python expire-iceberg-snapshots.py
snapshots before expiry: 5
data files referenced before expiry: 4
data files in the current snapshot: 3
remaining snapshots: snapshot 4, snapshot 5
data files referenced after expiry: 3
unreferenced data files left on disk: 1
rows in the current snapshot: 1499
read snapshot 3: ValueError

만료 전에 테이블에는 스냅샷이 5개 있고, 그중 하나 이상이 나열하는 데이터 파일은 4개이다. 현재 스냅샷이 나열하는 파일은 그중 3개뿐이다. 나머지 하나는 이전의 02시 파일이며, 스냅샷 3이 여전히 이 파일을 나열한다. 이렇게 수를 읽으면 덮어쓰기가 한 일을 알 수 있다. 현재 테이블은 완전하지만, 이력에는 덮어쓰기로 교체된 파일이 남아 있다.

그다음 예제는 세 번의 추가인 스냅샷 1부터 3까지를 만료시킨다. 남는 스냅샷은 snapshot 4, snapshot 5이며, 덮어쓰기의 삭제와 그 추가이다. 이후 나열되는 데이터 파일은 3개이고, 이전의 02시 파일은 어떤 스냅샷도 더 이상 나열하지 않는다. 그래도 파일은 여전히 디스크에 있다. 예제는 참조되지 않는 파일이 1개라고 보고한다. 현재 테이블은 여전히 1499개의 행을 반환하므로, 만료는 현재 테이블을 읽는 독자가 보는 데이터를 바꾸지 않았다.

마지막 읽기는 실패한다. 만료 후 스냅샷 3을 스캔하면 ValueError가 발생하며, 출력에는 "read snapshot 3: ValueError"로 나타난다. 만료 전에 스냅샷 3을 고정해 둔 독자는 이전 행이 아니라 오류를 받는다. 오류 Snapshot not found는 스냅샷의 ID를 알려 주지만, 만료로 스냅샷이 제거되었다고는 알려 주지 않는다. 어떤 만료가 실행되었고 보고서가 어느 스냅샷을 사용했는지는 직접 로그에 기록해야 한다.

작업 규칙: Iceberg 스냅샷은 커밋 순서에서 고른 ID로 만료시키고, 남은 각 스냅샷이 나열하는 파일을 만료 전후에 센다. 만료로 디스크 공간이 돌아오리라고 기대하지 마라. pyiceberg는 메타데이터만 제거하므로, 남겨 둔 파일은 직접 제거하기 전까지 디스크에 남는다.

만료 후 고아 파일 찾기

마지막으로 변경된 판: 2026.11.8판

어떤 스냅숏도 나열하지 않는 파일은 고아 파일이다. Spark와 Java는 deleteOrphanFiles 액션을 제공한다. 이 액션은 테이블 위치의 파일을 나열하고, 그 파일을 메타데이터와 비교한 뒤, 차이가 나는 파일을 삭제하며, 기본 경과 기간 기준은 3일이다(Apache Iceberg, maintenance). pyiceberg API 페이지에는 고아 파일을 처리하는 단계가 없고, 0.12.0 패키지에도 없다. 이 패키지의 유지 관리 메서드는 스냅숏을 만료시키는 것뿐이다(PyIceberg API).

이 책의 공유 모듈인 examples/lib/lakehouse.py에 있는 도우미 함수 orphan_data_files은 이 비교를 직접 수행한다. 이 함수는 테이블 위치 아래의 Parquet 파일을 나열하고, 남아 있는 스냅숏 중 어느 하나라도 나열하는 파일을 뺀 다음, 나머지를 반환한다. 파일 이름에 UUID가 들어 있으므로 출력에는 개수만 표시한다. 이 개수가 바로 만료된 파일이 여전히 디스크에 남아 있음을 보여 주는 줄이다.

파일 목록만으로는 고아 파일과, 작성자가 기록했지만 아직 커밋하지 않은 파일을 구별할 수 없다. 커밋이 파일을 테이블에 연결하며, 그 전까지 파일은 참조되지 않는 것처럼 보인다. 이것이 보존 기간 보호 장치가 중요한 이유다. DuckLake의 ducklake_delete_orphaned_files는 기본적으로 새로 생긴 파일을 남겨 두며, Spark 액션도 같은 이유로 보존 기간을 받는다. pyiceberg에는 이런 기간이 없으므로 확인은 사용자가 직접 해야 한다. 고아 파일을 삭제하는 일은 별도의 결정이며, 해당 파일을 커밋할 수 있는 작성자가 모두 중단된 뒤에 해야 한다.

작업 규칙: 고아 파일은 목록을 나열해 세고, 어떤 작성자도 그 파일을 더 이상 커밋할 수 없고 어떤 독자도 그 파일을 나열하는 스냅숏을 더 이상 사용하지 않음을 확인한 뒤에만 제거한다. pyiceberg에서는 라이브러리의 어떤 기능도 이 확인을 대신해 주지 않는다.

deltalake로 테이블 vacuum하기

마지막으로 변경된 판: 2026.11.10판

Delta Lake는 커밋이 파일을 교체할 때 그 파일을 삭제하지 않는다. 파일을 교체하는 Delta 커밋은 로그에 remove 액션을 추가한다. 이 액션은 해당 파일이 더 이상 테이블에 속하지 않는다는 것을 알리는 툼스톤이며, 파일 자체는 디스크에 남는다. 프로토콜은 이러한 파일을 "사용자가 지정한 보존 기간(기본값 7일)이 지난 뒤 vacuum 명령으로 지연 삭제할 수 있다"고 명시한다 (Delta transaction log protocol, v4.4.1). 이 절의 출력은 0부터 시작하는 Delta 자체의 버전 번호를 사용한다.

Vacuum은 툼스톤이 보존 기간보다 오래된 파일을 삭제한다. 그때까지는 모든 버전을 읽을 수 있다. 각 버전이 나열하는 파일이 모두 아직 존재하기 때문이다. Delta 유틸리티 문서는 그 대가를 다음과 같이 밝힌다. "보존 기간보다 오래된 버전으로 타임 트래블하는 기능은 vacuum을 실행한 뒤에는 사라진다" (Delta Lake, VACUUM).

이 사례에서는 세 번의 append로 버전 0부터 2까지가 만들어지고, 그 뒤에 02시 구간의 정정이 이어진다. 정정은 해당 시간대를 삭제하는 버전 3과, 정정된 행을 append하는 버전 4로 이루어진다. 버전 2는 여전히 이전 02시 파일을 나열하고, 버전 3은 나열하지 않는다. 아직 아무것도 제거되지 않았으며, 다음 절은 이 상태에서 시작한다.

deltalake의 기본 보존 기간은 168시간, 즉 7일이다. 테이블은 delta.deletedFileRetentionDuration 속성으로 자체 보존 기간을 지정할 수 있으며, vacuum는 retention_hours를 전달하지 않으면 그 속성을 사용한다. 운영 환경에서 쓰는 설정은 이 속성이다. 라이브러리는 enforce_retention_duration를 끄지 않는 한 속성 값보다 짧은 보존 기간을 거부한다. 더 긴 보존 기간에는 플래그가 필요 없다. 선택한 보존 기간은 이력이 얼마나 과거까지 이어지는지에 대한 약속이다. 이전 버전을 여는 모든 리더가 이 약속에 의존하며, 다음 절에서 이 거부 동작과, 이 장의 실습 실행에서 검사를 끄는 이유를 보여 준다.

작업 규칙: vacuum의 기본 보존 기간을 유지하거나 delta.deletedFileRetentionDuration에 더 긴 값을 지정하여, 리더가 요청할 수 있는 모든 버전이 최신 버전이 아니게 된 뒤에도 그 기간 동안 계속 읽히도록 한다. 더 짧게 설정하는 것은 시스템에서 가장 긴 읽기와 가장 긴 쓰기를 확인한 뒤에만 하고, 그 경우에도 enforce_retention_duration를 끄는 방식으로, 의도적이고 기록된 결정으로 해야 한다.

먼저 드라이런을 실행한다

마지막으로 변경된 판: 2026.11.7판

드라이런은 실제 vacuum이 삭제할 파일의 목록을 보여 주며, 그 파일을 하나도 삭제하지 않는다. 모든 vacuum에 앞서 드라이런을 실행하고, 그 결과의 개수를 테이블의 이력과 비교한다. 이 예제의 경우는 세 번의 append, 버전 3의 delete, 버전 4의 append로 이루어진다. 짧은 목록은 직접 확인할 수 있다. 여기서 목록에 있는 파일은 각각 delete가 제거한 파일이며, 중요한 것은 버전 3의 delete이다. 이 이력에 대해 드라이런을 두 번 실행하면, 두 가지 보존 기간에서 vacuum이 무엇을 삭제할지 확인할 수 있다.

vacuum-delta-dry-run.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Show that vacuum's default retention keeps a file that a delete has just removed, and that a read of an older versionfails once a teaching-only run removes that file. The point rests on the default-retention line and the read of version 2."""import pyarrow as pafrom deltalake import DeltaTable, write_deltalakefrom deltalake.exceptions import DeltaErrorfrom lib.lakehouse import new_warehouse, read_cut_hour, read_delta, hour_correctionswith new_warehouse() as wh:    path = str(wh.root / "delta" / "pageviews_hourly")    for hour in (0, 1, 2):        write_deltalake(path, read_cut_hour(hour), mode="append")    dt = DeltaTable(path)    dt.delete("hour_utc = '2024-06-03T02:00:00'")  # hour 02, matched by its exact timestamp    # hour_corrections halves the views of some page titles in hour 02, so this append holds the corrected rows    write_deltalake(path, hour_corrections(read_cut_hour(2)), mode="append")    dt = DeltaTable(path)    print("current version:", dt.version())    # the delete was seconds ago, so the default retention still keeps its file    print("default retention, dry run lists:", len(dt.vacuum(dry_run=True)))    try:        dt.vacuum(retention_hours=0, dry_run=True)  # a retention below the table's minimum: refused without the flag    except DeltaError as exc:        print("zero retention without the flag:", type(exc).__name__)    # Teaching run only: a zero-hour retention removes files at once. Production keeps the 168-hour default.    print("zero retention, dry run lists:", len(dt.vacuum(retention_hours=0, dry_run=True, enforce_retention_duration=False)))    print("zero retention, removed:", len(dt.vacuum(retention_hours=0, dry_run=False, enforce_retention_duration=False)))    print("rows in version 0:", read_delta(path, version=0).num_rows)  # version 0 reads files the vacuum left alone    try:        read_delta(path, version=2)  # version 2 still lists the hour-02 file that the vacuum removed    except pa.ArrowInvalid as exc:        print("read version 2:", type(exc).__name__)
출력python vacuum-delta-dry-run.py
current version: 4
default retention, dry run lists: 0
zero retention without the flag: DeltaError
zero retention, dry run lists: 1
zero retention, removed: 1
rows in version 0: 499
read version 2: ArrowInvalid

테이블은 버전 4에 있다. 기본 보존 기간에서 드라이런이 나열하는 파일은 0개이다. 버전 3이 제거한 파일은 목록에 오르기에는 너무 최근의 것이므로, vacuum은 그 파일을 남겨 둔다.

다음 호출은 보존 기간을 0으로 설정하며, deltalake는 DeltaError와 함께 이를 거부한다. 라이브러리가 직접 내는 메시지는 최소 보존 기간이 168시간이라고 알려 주므로, 이 검사는 기본값을 보호한다.

교육용 실행에서는 enforce_retention_duration=False로 이 검사를 끈다. 이 코드는 교육용 전용임을 나타내며, 운영 환경에서는 사용하지 않는다. 검사를 끈 상태에서 드라이런이 나열하는 파일은 1개이고, 실제 vacuum이 제거하는 파일은 1개로, 오래된 hour-02 파일이다. 보존 기간 0은 파일을 즉시 삭제하므로 시연에는 알맞은 설정이다. 그러나 운영 환경에서는 잘못된 설정이다. vacuum 이전에 시작한 리더나 이전 버전을 고정해 둔 리더는 쿼리 도중에 읽고 있던 파일을 잃는다. 또한 짧은 보존 기간은 쓰기를 마쳤으나 아직 커밋하지 않은 라이터의 파일까지 삭제한다. Delta 유틸리티 문서는 "tables can be corrupted when VACUUM deletes files that have not yet been committed"라고 경고한다(Delta Lake, VACUUM). 피해는 한 번의 읽기에 그치지 않고 테이블 자체에 미친다.

마지막의 읽기는 vacuum의 대가를 보여 준다. 버전 0은 목록에 있는 모든 파일이 아직 존재하므로 499개의 행으로 여전히 읽힌다. 버전 2는 ArrowInvalid로 실패하며, 출력에는 "read version 2: ArrowInvalid"로 나타난다. 이 클래스는 쿼리 엔진이 Parquet 읽기에 실패할 때 발생시키는 것이며, 메시지에는 없어진 객체의 이름이 나온다. 이 읽기는 클래스만 출력한다. 테이블이 손상되었다고 판단하기 전에 자신의 로그에서 메시지를 읽는다. 메시지는 어떤 객체가 없는지, 따라서 vacuum이 그것을 제거했는지를 알려 준다.

드라이런은 실제 실행에 대한 약속이 아니다. 두 호출 사이에 커밋하는 라이터가 있으면 테이블이 바뀌며, 실제 실행은 그때 발견한 테이블 상태를 기준으로 동작한다. 드라이런의 개수는 예상한 바에 대한 점검으로 취급하고, 실제 실행의 개수를 함께 확인한다.

작업 규칙: vacuum은 먼저 드라이런으로 실행하고 그 개수를 읽는다. 개수가 테이블의 이력에서 예상한 것과 일치할 때에만 실제 실행으로 파일을 제거하고, 시스템에서 가장 긴 읽기를 확인하기 전에는 기본 보존 기간을 유지한다.

DuckLake의 만료와 정리

마지막으로 변경된 판: 2026.11.7판

DuckLake는 스냅샷이 만료될 때까지 그 스냅샷의 물리 파일을 보관한다. DuckLake 문서는 이를 다음과 같이 설명한다. "데이터는 오래된 데이터를 참조하는 스냅샷을 만료시켜야만 DuckLake에서 물리적으로 제거할 수 있다"(DuckLake, expire snapshots). 같은 문서는 만료가 참조되지 않게 된 파일을 즉시 삭제하지는 않는다고 밝히며, 두 번째 호출은 정리 문서에서 다룬다(DuckLake, cleanup of files).

따라서 DuckLake 유지 관리는 두 단계로 이루어지며, 아래 예제는 두 단계를 모두 실행한다. ducklake_expire_snapshots는 versions에 스냅샷 번호 목록을 받거나 older_than 타임스탬프를 받으며, 둘을 함께 쓸 수는 없다. ducklake_cleanup_old_files는 만료가 삭제 대상으로 예약한 파일을 제거한다. older_than를 지정하면 주어진 시각 이전에 예약된 파일만 제거한다. cleanup_all => true를 지정하면 경과 시간을 확인하지 않고 예약된 모든 파일을 제거한다. 두 단계 모두 dry_run를 지원한다.

세 번째 호출인 ducklake_delete_orphaned_files는 어떤 스냅샷에도 나열되지 않고 정리 단계에서도 예약된 적 없는 파일을 처리한다. 쓰기 작업이 커밋에 실패한 뒤 남겨 둔 파일이 그 예이다. 기본 설정에서는 아직 생성된 지 얼마 되지 않은 파일을 유지하는데, 쓰기 작업이 곧 그 파일을 커밋할 수도 있기 때문이다. cleanup_all 옵션은 나이와 관계없이 이러한 파일을 제거한다. 두 번째 카탈로그가 데이터 폴더를 공유할 때 이 옵션이 어떻게 동작하는지는 카탈로그 장에서 보여 준다.

도우미를 통해 카탈로그를 연결하고 스키마와 테이블을 만들면 행이 들어가기 전에 스냅샷이 세 개 생긴다. 연결이 스냅샷 1을 만들고, 두 CREATE 문이 스냅샷 2와 3을 만든다. 번호는 2장과 같이 설정 단계를 포함하여 1부터 붙인다. 이어서 로딩 도우미가 00시부터 02시까지의 데이터를 삽입하고, 02시 데이터를 삭제한 뒤, 수정된 02시 데이터를 삽입한다. 그 결과 스냅샷은 8개가 되며, 예제는 이를 "snapshot 1"부터 마지막 스냅샷까지 번호로 표시한다. 마지막 스냅샷은 수정된 삽입이다. 그 앞은 삭제이며, 이 삭제가 예전 02시 파일을 스냅샷에서 제거한다. 그 앞의 삽입인 스냅샷 6이 그 파일을 나열하는 마지막 스냅샷이다.

ducklake-expire-cleanup.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Expire every snapshot before the correction, clean up what expiry released, and run the orphan check as a dry run. Thepoint rests on the cleanup lines and on the orphan line, which shows that the default age check spares the stray copy."""import shutilfrom pathlib import Pathimport duckdbfrom lib.lakehouse import (    DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table,    ducklake_file_count, ducklake_file_paths, load_ducklake_with_correction, new_warehouse,    version_labels,)LAKE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"def listed(con, call):    """Run a DuckLake procedure and return how many rows it lists."""    return con.sql(f"CALL {call}").to_arrow_table().num_rowswith new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_table(con, wh.root)    load_ducklake_with_correction(con)  # lib inserts hours 00 to 02, deletes hour 02, then inserts the corrected hour 02    # ORDER BY 1 sorts by snapshot_id, which grows with each commit, so the labels number the snapshots in commit order    ids = [r[0] for r in con.execute(f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}') ORDER BY 1").fetchall()]    labels = version_labels(ids, word="snapshot")    print("snapshots before expiry:", len(ids))    print("data files in the current snapshot:", ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE))    stray = Path(sorted(ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE))[0])  # sorted, so every run copies the same file    shutil.copy(stray, stray.with_name("stray.parquet"))  # written, but no snapshot lists it    expired = ids[:-1]  # all but the last snapshot, which is the corrected insert and stays    # versions takes DuckLake's snapshot numbers, not the labels    expire = f"ducklake_expire_snapshots('{DUCKLAKE_ALIAS}', versions => {expired}"    print("expiry dry run lists:", listed(con, f"{expire}, dry_run => true)"))    con.execute(f"CALL {expire})")    print("remaining snapshots:", labels[ids[-1]])    # no age check, so this is safe only because one catalog owns the folder and no reader is running    cleanup = f"ducklake_cleanup_old_files('{DUCKLAKE_ALIAS}', cleanup_all => true"    print("cleanup dry run lists:", listed(con, f"{cleanup}, dry_run => true)"))    print("cleanup removed:", listed(con, f"{cleanup})"))    # no cleanup_all, so the default age check spares the stray copy, which was written seconds ago    orphans = f"ducklake_delete_orphaned_files('{DUCKLAKE_ALIAS}', dry_run => true)"    print("orphans listed without cleanup_all:", listed(con, orphans))    print("rows in the current snapshot:", con.sql(f"SELECT count(*) FROM {LAKE}").fetchall()[0][0])    try:        # the newest expired snapshot, the delete; reading it now fails        con.sql(f"SELECT count(*) FROM {LAKE} AT (VERSION => {expired[-1]})").fetchall()    except duckdb.InvalidInputException as exc:        print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
출력python ducklake-expire-cleanup.py
snapshots before expiry: 8
data files in the current snapshot: 3
expiry dry run lists: 7
remaining snapshots: snapshot 8
cleanup dry run lists: 1
cleanup removed: 1
orphans listed without cleanup_all: 0
rows in the current snapshot: 1499
read snapshot 7: InvalidInputException

현재 스냅샷은 데이터 파일 3개를 나열하며, 그중 하나를 같은 폴더의 다른 이름으로 복사한다. 이는 고아 파일 찾기에서 설명하듯이 쓰기 작업이 기록했지만 커밋하지 않은 파일을 대신한다. 그런 다음 각 단계를 순서대로 실행한다.

만료 드라이 런은 스냅샷 7개를 나열하는데, 수정된 삽입을 제외한 모든 스냅샷이다. 그 삽입은 남으므로 테이블의 현재 상태는 그대로이다. 실제 만료를 수행하면 snapshot 8이(가) 남는다. 예전 02시 파일을 마지막으로 나열한 스냅샷 6이 만료되므로, 이 파일은 이 단계에서 해제된다.

정리 드라이 런은 파일 1개, 즉 예전 02시 파일을 나열한다. DELETE가 그 파일의 모든 행과 일치했고 함께 예약된 삭제 파일이 없으므로, 제거할 파일은 예전 파일뿐이다. 실제 정리는 파일 1개를 제거한다.

고아 파일 확인은 고아 파일 0개를 나열한다. 복사해 둔 파일은 폴더에 그대로 남아 있는데, 기본 나이 확인이 이를 유지했기 때문이다. 이 파일은 생성된 지 몇 초밖에 되지 않았다. 테이블은 여전히 1499개의 행을 반환한다.

마지막으로 삭제 시점인 스냅샷 7을 읽으면 "read snapshot 7: InvalidInputException"와 함께 실패한다. 이 오류 클래스는 DuckLake가 더 이상 가지고 있지 않은 버전에 대해 발생시키는 것과 같다.

여기에 cleanup_all => true가 나타나는 이유는 카탈로그가 하나이고 읽기 작업이 없기 때문이다. 운영 환경에서는 대신 older_than를 사용하며, 가장 긴 읽기 작업보다 긴 기간을 지정하여 충분히 오래 예약된 파일만 정리 단계에서 제거되도록 한다.

작업 규칙: DuckLake 스냅샷을 먼저 만료시키고, 각 정리 호출은 드라이 런을 먼저 실행한 다음 실제로 실행한다. 기본 고아 파일 확인을 유지한다. cleanup_all는 카탈로그 하나가 데이터 폴더를 소유하고 제거되는 파일을 사용하는 읽기 작업이 없을 때만 사용하며, 그렇지 않으면 older_than를 사용한다.

운영 환경에서 잘못되는 것들

마지막으로 변경된 판: 2026.11.7판

독자가 아직 사용 중인 파일을 제거하는 경우. 베큠(vacuum)이나 정리 작업 전에 시작된 쿼리가 이후에 사라진 파일을 읽으면, 읽기가 중간에 실패한다. 이 실패는 유지 보수 시간대에 실행된 작업에서, 없는 객체의 이름을 가리키는 읽기 오류로 나타난다. 유지 보수는 긴 읽기 작업을 피해서 예약하고, 보존 기간은 가장 긴 읽기 작업보다 길게 유지한다. 보존 기간이 짧으면 기록 작업이 쓰기만 하고 아직 커밋하지 않은 파일까지 삭제할 수 있다. 이 경우에는 읽기 하나가 실패하는 데서 끝나지 않고 테이블이 손상되므로, 보존 기간은 가장 오래 실행되는 쓰기보다도 길게 유지한다.

가장 긴 쿼리보다 짧은 보존 기간. Delta Lake의 기본값인 7일은 여유분일 뿐, 측정한 값이 아니다. 한 달 전 버전을 읽는 대시보드는 이 범위를 벗어난다. 리더(읽기 작업)가 더 오래된 버전을 봐야 한다면 보존 기간이 그 버전을 포함해야 하고, 그렇지 않으면 리더가 먼저 데이터를 복사해야 한다.

유지 보수 후 실패하는 타임 트래블. 만료된 스냅샷과 베큠으로 제거된 버전은 형식에 따라 ValueError, ArrowInvalid 또는 InvalidInputException(으)로 실패한다. Iceberg는 ValueError를 발생시키고, Delta는 ArrowInvalid를 발생시킨다. DuckLake는 InvalidInputException를 발생시킨다. 나중에 읽으려고 스냅샷 ID나 버전 번호를 기록해 둔 작업은 그 스냅샷이 만료되면 모두 같은 방식으로 실패한다. 각 보고서가 어느 스냅샷을 사용했는지 직접 기록해 두면, 재구축이 데이터에서 시작할 수 있고 오래된 스냅샷을 읽는 데 의존하지 않는다.

실제 실행과 다른 드라이 런. 두 호출 사이에 기록 작업이 커밋하면 두 결과가 달라질 수 있다. 드라이 런의 개수는 예상한 값일 뿐, 실제 실행이 제거할 값이 아니다. 실제 실행의 개수를 드라이 런의 개수와 나란히 확인하고, 설명할 수 있는 범위를 넘어 차이가 나면 중단한다.

더 오래된 스냅샷이 필요한 감사. 일부 보고서는 몇 달 전의 수치를 재현해야 한다. 만료는 그 능력을 영구히 없애므로, 만료하기 전에 감사 기간을 정하고 감사에 필요한 스냅샷이나 복사한 데이터를 보관한다. 만료는 복사본을 대신하지 못한다.

다른 카탈로그가 필요로 하는 파일을 삭제하는 정리. cleanup_all와 cleanup_all을 쓰는 고아 파일 검사는 경로를 기준으로 파일을 삭제한다. 두 번째 카탈로그가 같은 데이터 폴더를 가리키면, 그 카탈로그의 사용 중인 파일이 첫 번째 카탈로그에는 고아 파일처럼 보인다. 카탈로그 장은 이 실패를 임시 디렉터리에서 보여 준다.

작업 규칙: 스냅샷이나 버전을 만료하거나 정리하기 전에, 더 오래된 스냅샷이나 버전을 열 수 있는 독자, 보고서, 감사를 모두 나열하고, 보존 기간을 그중 가장 긴 것을 포함하도록 설정한다. 각 호출을 드라이 런으로 실행하고, 그 개수를 예상한 값과 비교하며, 둘이 일치할 때만 실제 호출을 실행한다.

이 장에서 내린 결정

마지막으로 변경된 판: 2026.11.7판
  • Iceberg 스냅샷은 커밋 순서에서 고른 ID로 만료한다. 이 장은 나이를 기준으로 만료하지 않으므로 결과가 컴퓨터의 시계에 좌우되지 않으며, pyiceberg 0.12.0에는 마지막 N개를 남기는 인자가 없다.
  • pyiceberg는 파일을 제거하지 않으므로 expire-iceberg-snapshots는 도달 가능한 파일과 도달할 수 없는 파일의 수를 세고, 제거는 독자에게 맡긴다.
  • vacuum-delta-dry-run의 보존 기간 0 실행은 학습용으로만 쓴다. 코드에 그렇게 표시해 두었으며, 운영 환경에서는 기본 보존 기간을 유지한다.
  • DuckLake의 만료와 정리는 별개의 호출이며, 각각 실제 호출에 앞서 시험 실행으로 먼저 수행한다.
  • cleanup_all는 카탈로그가 하나뿐인 예제에만 나온다. 이 호출이 사용 중인 파일을 제거하는 경우는 카탈로그 장에서 다룬다.
  • 각 예제는 개수, 고정된 레이블, 오류 클래스 이름만 출력하고 ID, 타임스탬프, 파일 이름, 경로는 출력하지 않는다. 그 이유는 1장에 있다. 본문의 모든 수치는 바인딩된 출력 줄이나 예제 자체의 구성에서 나온다.
  • 모든 예제는 앞선 장들에서 만든 테이블을 그대로 사용하므로, 각 개수를 독자가 이미 본 이력과 대조해 확인할 수 있다.
  • 각 예제는 자체 임시 웨어하우스를 만들므로, 어떤 출력도 앞선 예제나 실행하는 컴퓨터에 좌우되지 않는다.
  • ducklake-expire-cleanup의 불필요한 사본은 고아 파일 찾기에서 설명하듯이 기록자가 아직 커밋하지 않은 파일을 대신한다. 실행에 몇 초밖에 걸리지 않으므로, 파일이 오래되기를 기다리지 않고도 고아 파일 규칙을 보일 수 있다.

이 판의 이 장

2026.11.10판예제 통과 2026년 11월 20이 장에서 3개 예제개 중 3개가 통과한다

영어판 2026.11.10판을 번역한 것이다.

이 절 인용

형식

각 형식은 이 번역이 따르는 영문 원서를 출처로 표기한다.

모든 형식은 이 판을 명시한다. 링크는 현재 판을 열며, 여기서 절의 제목은 본문이 마지막으로 바뀐 시점을 알려 준다. 접근 날짜와 검색 날짜는 이 자료를 여는 날짜다.

이 페이지의 내용

10장 중 7장: 스냅샷 만료와 참조되지 않는 파일 제거

  1. 스냅샷은 파일을 살려 둔다
  2. pyiceberg로 스냅샷 만료하기
  3. 만료 후 고아 파일 찾기
  4. deltalake로 테이블 vacuum하기
  5. 먼저 드라이런을 실행한다
  6. DuckLake의 만료와 정리
  7. 운영 환경에서 잘못되는 것들
  8. 이 장에서 내린 결정

맨 위로 돌아가기전체 장