スナップショットの失効と未参照ファイルの削除
読了まで約38 分分、8 節 節の 3 例 例。
この章を終えると、3 つの形式のそれぞれで古いスナップショットを失効させ、それらのスナップショットだけが参照していたデータファイルを削除し、失効したスナップショットの読み取りが失敗することを示せるようになる。
コンパクションも同じ種類の古いファイルを残す。書き換えは、置き換えたファイルをディスク上に残した。古いスナップショットがまだそれらを参照しているためである。この章では、wiki.pageviews_hourly の古いスナップショットを失効させ、続いてどのスナップショットからも参照されなくなったファイルを削除する。この章のすべての例では、訂正の章で扱った 02 時の訂正を使う。ただし、後の節にあるアップサートとしてではなく、その時間帯の上書きとして書く。上書きであれば、形式ごとに古いファイルがちょうど 1 つ残るためである。これらの古いファイルは、そのスナップショットが失効し、ファイルが削除されるまで残る。どちらの手順も各形式で実行し、各手順は、信頼するしかない一覧ではなく、件数で確認する。
スナップショットはファイルを生かし続ける
すべてのスナップショットは、そのコミット時点でテーブルを構成するデータファイルを記録している。各フォーマットがこの一覧をどのように保持するかは、スナップショットが指すもので扱った。本章にとって重要なのは、行を置き換えるコミットが、置き換えられたファイルを削除しないという点である。コミットは置換後の行を収めたファイルを書き出すが、コミット以前のスナップショットは古いファイルを依然として一覧に含んでおり、そのためタイムトラベルは機能し続ける。データファイルが孤立ファイルになるのは、保持しているどのスナップショットにも一覧されなくなったときだけである。
どのフォーマットでも、ファイルの削除は2段階で行う。まず期限切れ処理、次にクリーンアップである。Iceberg のメンテナンスのページにも同じ順序が示されている。期限切れ処理はメタデータからスナップショットを取り除くので、タイムトラベルはそこに到達できなくなる。そして「データファイルは、タイムトラベルやロールバックに使われうるスナップショットから参照されなくなるまで削除されない」(Apache Iceberg, maintenance)。期限切れ処理の後、クリーンアップが、残っているどのスナップショットにも一覧されていないファイルを削除する。
wiki.pageviews_hourly が3回の1時間ごとの追記を受け、その後、02時の分がその時間帯の上書きで訂正されるとする。追記のたびに1つのファイルが書き出される。上書きは、訂正後の02時の行を収めたファイルを書き出し、古いファイルを現在のスナップショットから取り除く。古いファイルを追記したスナップショットは、そのファイルを今も一覧に含んでいる。そのスナップショットが期限切れになるまでは、タイムトラベルを壊さずに古いファイルを削除することはできない。訂正した時間帯のアップサートは、同じ訂正を書くもう1つの方法を示しているが、その方法でも同じ種類の古いファイルが残る。
各フォーマットには、固有の期限切れ処理の呼び出しと、固有のクリーンアップの呼び出しがある。表にそれらを示す。本章の残りでも、各フォーマットについて同じ順序で説明する。
| フォーマット | 期限切れ処理の呼び出し | 期限切れ処理はファイルを削除するか | クリーンアップの呼び出し |
|---|---|---|---|
| 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 によるスナップショットの失効
pyiceberg 0.12.0 では、table.maintenance.expire_snapshots() はスナップショット ID を受け取る。複数の ID はリストとして by_ids で、1 つの ID は by_id で渡す。あるいは older_than のタイムスタンプを指定する。直近の N 個のスナップショットを残す引数はない。この章では、この事例と同じく、コミット順から ID を選ぶ。1 時間ごとの 3 回の追記が最初の 3 つのスナップショットである。ID 自体はランダムな 64 ビットの数値であるため、例では代わりに、同じ順序で「snapshot 1」「snapshot 2」などのラベルを出力する。
上書きは、スナップショットを 1 つではなく 2 つ追加する。pyiceberg は、古いファイルを削除する delete スナップショットを書き込み、続いて、修正後の行を追加する append スナップショットを書き込む。スナップショット 4 が delete、スナップショット 5 が append である。したがって、3 つの追記を失効させても上書きはそのまま残る。例が確認するのは、この状態である。
失効の呼び出しはデータファイルを削除しない。そのため、例では失効の前後で自らファイルを数える。数えるのは、スナップショットが列挙する重複のないファイルと、どのスナップショットにも列挙されずにディスク上にあるファイルである。置き換えられたファイルが現れるのは最後の数なので、そこに注目してほしい。
1"""Expire the three append snapshots by ID, then count what the snapshots still reference. The point rests on the2line that counts unreferenced data files on disk: expiry removes metadata, and the file the overwrite replaced stays."""34from lib.lakehouse import (5 ICEBERG_ID,6 create_iceberg_table,7 hour_corrections,8 hour_filter,9 new_warehouse,10 orphan_data_files,11 read_cut_hour,12 scan_arrow,13 snapshot_labels,14)151617def referenced_files(table):18 """Distinct data files that some retained snapshot lists. Count them; do not print them."""19 # all_files() can list one file from several manifests, so the set counts each file once20 return len(set(table.inspect.all_files()["file_path"].to_pylist()))212223with new_warehouse() as wh:24 table = create_iceberg_table(wh)25 for hour in (0, 1, 2):26 table.append(read_cut_hour(hour))27 # hour_filter(2) matches only hour 02's rows, so the overwrite replaces that hour and leaves hours 00 and 01 alone28 table.overwrite(hour_corrections(read_cut_hour(2)), overwrite_filter=hour_filter(2))2930 ids = [snapshot.snapshot_id for snapshot in table.metadata.snapshots] # metadata lists snapshots in commit order31 labels = snapshot_labels(ids)32 print("snapshots before expiry:", len(ids))33 print("data files referenced before expiry:", referenced_files(table))34 print("data files in the current snapshot:", len(table.inspect.files())) # files() reads the current snapshot only3536 expired = ids[:3] # the three hourly appends, by commit order37 table.maintenance.expire_snapshots().by_ids(expired).commit()38 table = wh.catalog.load_table(ICEBERG_ID)3940 print("remaining snapshots:", ", ".join(labels[s.snapshot_id] for s in table.metadata.snapshots))41 print("data files referenced after expiry:", referenced_files(table))42 # files under the table location that no remaining snapshot lists; a file a writer has not committed counts too43 print("unreferenced data files left on disk:", len(orphan_data_files(table)))44 print("rows in the current snapshot:", scan_arrow(table).num_rows)45 try:46 scan_arrow(table, snapshot_id=expired[-1])47 except ValueError as exc:48 print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
python expire-iceberg-snapshots.pysnapshots 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 個のスナップショットがあり、少なくとも 1 つのスナップショットから列挙されているデータファイルは 4 個である。現在のスナップショットが列挙するのは、そのうち 3 個のみである。残る 1 つは古い hour-02 のファイルであり、スナップショット 3 がまだそれを列挙している。このように数を読むと、上書きの結果が分かる。現在のテーブルは完全であり、履歴には上書きで置き換えられたファイルが残っている。
次に、例はスナップショット 1 から 3、すなわち 3 つの追記を失効させる。残るスナップショットは snapshot 4, snapshot 5 であり、上書きの delete とその append である。失効後に列挙されるデータファイルは 3 個であり、古い hour-02 のファイルはどのスナップショットからも列挙されなくなる。しかし、このファイルはまだディスク上にある。例は、参照されないファイルが 1 個あると報告する。現在のテーブルは引き続き 1499 行を返すため、失効によって、現在のテーブルの読み手が見るデータは何も変わらない。
最後の読み取りは失敗する。失効後にスナップショット 3 をスキャンすると ValueError が送出され、出力では「read snapshot 3: ValueError」と表示される。失効の前にスナップショット 3 を固定していた読み手は、古い行ではなくエラーを受け取る。エラー Snapshot not found はスナップショットの ID を示すが、失効によってそのスナップショットが削除されたことは示さない。どの失効を実行したか、レポートがどのスナップショットを使ったかは、自分のログに記録しておく必要がある。
実践ルール: Iceberg のスナップショットは、コミット順から選んだ ID で失効させ、残る各スナップショットが列挙するファイルの数を失効の前後で数える。失効によってディスク容量が戻ることは期待しない。pyiceberg が削除するのはメタデータだけであり、残されたファイルは、自分で削除するまでディスク上に残る。
期限切れ処理後の孤立ファイルを見つける
どのスナップショットにも記載されていないファイルは孤立ファイルである。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 では、この確認をライブラリが代わりに行ってくれることはない。
この部分はまだ翻訳されていないため、英語で表示している。
Vacuum a table with deltalake
Delta Lake does not delete a file when a commit replaces it. A Delta commit that replaces a file adds a remove action to the log, a tombstone that says the file is no longer part of the table, and the file stays on disk. The protocol states that such files "can be lazily deleted by the vacuum command after a user-specified retention period (default 7 days)" (Delta transaction log protocol, v4.4.1). The output in this section uses Delta's own version numbers, which start at 0.
Vacuum deletes the files whose tombstones are older than the retention. Until then, every version can be read, because every file it lists still exists. The Delta utility page states the cost: "The ability to time travel back to a version older than the retention period is lost after running vacuum" (Delta Lake, VACUUM).
The case has three appends, which make versions 0 to 2, and then the hour-02 correction. The correction is a delete of that hour, which is version 3, followed by an append of the corrected rows, which is version 4. Version 2 still lists the old hour-02 file, and version 3 does not. Nothing has been removed yet, and that is the state the next section starts from.
The default retention in deltalake is 168 hours, seven days. A table can set its own in the delta.deletedFileRetentionDuration property, and vacuum uses that property when you pass no retention_hours. That property is the production setting. The library refuses a retention shorter than the property's value unless you turn off enforce_retention_duration. A longer retention needs no flag. The retention you choose is a promise about how far back history reaches. Every reader that opens an older version depends on it, and the next section shows the refusal and why this chapter's teaching run turns the check off.
Working rule: Keep vacuum's default retention, or set a longer one in delta.deletedFileRetentionDuration, so that every version a reader may request is still readable for that long after it stops being current. Go shorter only after you have checked the longest read and the longest write in your system, and only by turning enforce_retention_duration off as a deliberate, recorded decision.
まずドライランを行う
ドライランは、実際の vacuum が削除するファイルを一覧にするだけで、どのファイルも削除しない。vacuum を実行する前には必ずドライランを行い、その件数をテーブルの履歴と照らし合わせる。ここで扱うのは、3 回の追加、バージョン 3 での削除、バージョン 4 での追加という履歴である。短い一覧であれば手作業で確認できる。この例では、一覧に含まれる各ファイルは削除操作によって取り除かれたものであり、重要なのはバージョン 3 の削除である。この履歴に対して 2 回のドライランを行うと、2 通りの保持期間で vacuum が何を削除するかを問い合わせることになる。
1"""Show that vacuum's default retention keeps a file that a delete has just removed, and that a read of an older version2fails once a teaching-only run removes that file. The point rests on the default-retention line and the read of version 2."""34import pyarrow as pa5from deltalake import DeltaTable, write_deltalake6from deltalake.exceptions import DeltaError78from lib.lakehouse import new_warehouse, read_cut_hour, read_delta, hour_corrections910with new_warehouse() as wh:11 path = str(wh.root / "delta" / "pageviews_hourly")12 for hour in (0, 1, 2):13 write_deltalake(path, read_cut_hour(hour), mode="append")14 dt = DeltaTable(path)15 dt.delete("hour_utc = '2024-06-03T02:00:00'") # hour 02, matched by its exact timestamp16 # hour_corrections halves the views of some page titles in hour 02, so this append holds the corrected rows17 write_deltalake(path, hour_corrections(read_cut_hour(2)), mode="append")1819 dt = DeltaTable(path)20 print("current version:", dt.version())21 # the delete was seconds ago, so the default retention still keeps its file22 print("default retention, dry run lists:", len(dt.vacuum(dry_run=True)))23 try:24 dt.vacuum(retention_hours=0, dry_run=True) # a retention below the table's minimum: refused without the flag25 except DeltaError as exc:26 print("zero retention without the flag:", type(exc).__name__)27 # Teaching run only: a zero-hour retention removes files at once. Production keeps the 168-hour default.28 print("zero retention, dry run lists:", len(dt.vacuum(retention_hours=0, dry_run=True, enforce_retention_duration=False)))29 print("zero retention, removed:", len(dt.vacuum(retention_hours=0, dry_run=False, enforce_retention_duration=False)))30 print("rows in version 0:", read_delta(path, version=0).num_rows) # version 0 reads files the vacuum left alone31 try:32 read_delta(path, version=2) # version 2 still lists the hour-02 file that the vacuum removed33 except pa.ArrowInvalid as exc:34 print("read version 2:", type(exc).__name__)
python vacuum-delta-dry-run.pycurrent 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 はそれを残す。
次の呼び出しでは保持期間をゼロに設定する。deltalake はこれを DeltaError で拒否する。ライブラリ自身のメッセージには、最小の保持期間は 168 時間であると書かれている。つまりこの検査は既定値を守るためのものである。
学習用の実行では、この検査を enforce_retention_duration=False で無効にする。このコードは学習専用であることを示しており、本番では使わない。検査を無効にすると、ドライランは 1 個のファイルを一覧にし、実際の vacuum は 1 個のファイル、すなわち古い hour-02 のファイルを削除する。ゼロの保持期間はデモには適した設定である。ファイルがただちに削除されるからである。本番では誤った設定である。vacuum の実行前に開始した読み取り処理や、古いバージョンを固定している読み取り処理は、クエリの途中で読み込み対象のファイルを失う。短い保持期間は、書き込みを終えたもののまだコミットしていない書き込み側のファイルも削除してしまう。Delta のユーティリティのページは、「VACUUM がまだコミットされていないファイルを削除すると、テーブルが破損することがある」と警告している(Delta Lake, VACUUM)。被害は 1 回の読み取りにとどまらず、テーブルそのものに及ぶ。
最後の読み取りは、vacuum が何を失わせたかを示す。バージョン 0 は、一覧にあるファイルがすべて残っているため、499 行を読み取れる。バージョン 2 は ArrowInvalid で失敗し、「read version 2: ArrowInvalid」と表示される。このクラスは、Parquet の読み取りに失敗したときにクエリエンジンが送出するものであり、メッセージには欠けているオブジェクトの名前が含まれる。この読み取りが出力するのはクラス名だけである。テーブルが破損したと判断する前に、自分のログでメッセージを読むこと。どのオブジェクトが欠けているか、したがって vacuum が削除したのかどうかが分かる。
ドライランは、実際の実行についての約束ではない。2 回の呼び出しの間にコミットする書き込み側があれば、テーブルは変わり、実際の実行は、そのとき見つかったテーブルの状態に基づいて動く。ドライランの件数は、予想との照合に使うものとして扱い、その隣で実際の件数も読むこと。
実践ルール: vacuum はまずドライランで実行し、件数を読む。実際の実行でファイルを削除するのは、件数がテーブルの履歴から予想した数と一致する場合に限る。システム内で最も長い読み取りを確認した場合を除き、既定の保持期間を維持する。
DuckLake の期限切れ処理とクリーンアップ
DuckLake は、スナップショットの物理ファイルを、そのスナップショットが期限切れになるまで保持する。DuckLake のドキュメントは次のように述べている。「データを DuckLake から物理的に削除できるのは、古いデータを参照するスナップショットを期限切れにした場合に限られる」(DuckLake, expire snapshots)。同じページには、期限切れ処理は、参照されなくなったファイルを直ちには削除しないとも書かれており、2 つ目の呼び出しはクリーンアップのページに示されている(DuckLake, cleanup of files)。
したがって、DuckLake の保守は 2 段階であり、以下の例では両方を実行する。ducklake_expire_snapshots は、versions にスナップショット番号のリストを取るか、older_than のタイムスタンプを取る。ただし両方を同時には指定できない。ducklake_cleanup_old_files は、期限切れ処理が削除予定にしたファイルを削除する。older_than を付けると、指定した時刻より前に削除予定となったファイルだけを削除する。cleanup_all => true を付けると、経過時間を確認せずに、削除予定のファイルをすべて削除する。どちらの段階も dry_run に対応している。
3 つ目の呼び出しである ducklake_delete_orphaned_files は、どのスナップショットにも記載されておらず、クリーンアップでも削除予定にならなかったファイルを扱う。たとえば、書き込み側がコミットの失敗後に残したファイルがこれに当たる。既定では、まだ新しいファイルは保持される。書き込み側がこれからコミットする可能性があるためである。cleanup_all オプションを指定すると、そのようなファイルが経過時間にかかわらず削除される。2 つ目のカタログがデータフォルダを共有している場合にこのオプションが何をするかは、カタログの章で示している。
ヘルパーを通じてカタログをアタッチし、スキーマとテーブルを作成すると、行を追加する前に 3 つのスナップショットができる。アタッチがスナップショット 1 を作り、2 つの CREATE 文がスナップショット 2 と 3 を作る。番号は、第 2 章と同様に、セットアップを含めて 1 から数える。続いて、ロード用のヘルパーが 00 時から 02 時までを挿入し、02 時を削除して、修正済みの 02 時を挿入する。これにより 8 個のスナップショットができ、例ではそれらを「snapshot 1」から最後のものまでと呼ぶ。最後のものは修正済みデータの挿入である。その前は削除であり、古い 02 時のファイルを除外する。さらにその前の挿入であるスナップショット 6 が、そのファイルを記載する最後のスナップショットである。
1"""Expire every snapshot before the correction, clean up what expiry released, and run the orphan check as a dry run. The2point rests on the cleanup lines and on the orphan line, which shows that the default age check spares the stray copy."""34import shutil5from pathlib import Path67import duckdb89from lib.lakehouse import (10 DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table,11 ducklake_file_count, ducklake_file_paths, load_ducklake_with_correction, new_warehouse,12 version_labels,13)1415LAKE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"161718def listed(con, call):19 """Run a DuckLake procedure and return how many rows it lists."""20 return con.sql(f"CALL {call}").to_arrow_table().num_rows212223with new_warehouse() as wh:24 con = connect_ducklake(wh.con)25 create_ducklake_table(con, wh.root)26 load_ducklake_with_correction(con) # lib inserts hours 00 to 02, deletes hour 02, then inserts the corrected hour 022728 # ORDER BY 1 sorts by snapshot_id, which grows with each commit, so the labels number the snapshots in commit order29 ids = [r[0] for r in con.execute(f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}') ORDER BY 1").fetchall()]30 labels = version_labels(ids, word="snapshot")31 print("snapshots before expiry:", len(ids))32 print("data files in the current snapshot:", ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE))33 stray = Path(sorted(ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE))[0]) # sorted, so every run copies the same file34 shutil.copy(stray, stray.with_name("stray.parquet")) # written, but no snapshot lists it3536 expired = ids[:-1] # all but the last snapshot, which is the corrected insert and stays37 # versions takes DuckLake's snapshot numbers, not the labels38 expire = f"ducklake_expire_snapshots('{DUCKLAKE_ALIAS}', versions => {expired}"39 print("expiry dry run lists:", listed(con, f"{expire}, dry_run => true)"))40 con.execute(f"CALL {expire})")41 print("remaining snapshots:", labels[ids[-1]])42 # no age check, so this is safe only because one catalog owns the folder and no reader is running43 cleanup = f"ducklake_cleanup_old_files('{DUCKLAKE_ALIAS}', cleanup_all => true"44 print("cleanup dry run lists:", listed(con, f"{cleanup}, dry_run => true)"))45 print("cleanup removed:", listed(con, f"{cleanup})"))46 # no cleanup_all, so the default age check spares the stray copy, which was written seconds ago47 orphans = f"ducklake_delete_orphaned_files('{DUCKLAKE_ALIAS}', dry_run => true)"48 print("orphans listed without cleanup_all:", listed(con, orphans))49 print("rows in the current snapshot:", con.sql(f"SELECT count(*) FROM {LAKE}").fetchall()[0][0])50 try:51 # the newest expired snapshot, the delete; reading it now fails52 con.sql(f"SELECT count(*) FROM {LAKE} AT (VERSION => {expired[-1]})").fetchall()53 except duckdb.InvalidInputException as exc:54 print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
python ducklake-expire-cleanup.pysnapshots 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 個のデータファイルが記載されている。そのうち 1 つを同じフォルダ内の別名にコピーし、孤立ファイルを見つけるで説明するように、書き込み側が書き出したもののコミットされていないファイルの代わりとする。そのあと、各段階を順に実行する。
期限切れ処理のドライランは 7 個のスナップショットを列挙する。これは、修正済みの挿入を除くすべてである。その挿入は残るため、テーブルの現在の状態は変わらない。実際の期限切れ処理を行うと、snapshot 8 が残る。古い 02 時のファイルは、それを記載していた最後のスナップショットであるスナップショット 6 が期限切れになるため、この段階で解放される。
クリーンアップのドライランは 1 個のファイル、つまり古い 02 時のファイルを列挙する。DELETE はそのファイルのすべての行に一致し、削除ファイルは併せて予定されていないため、削除すべきものはその古いファイルだけである。実際のクリーンアップでは 1 個のファイルが削除される。
孤立ファイルの確認では、0 個の孤立ファイルが列挙される。コピーされた不要なファイルは、まだフォルダに残っている。既定の経過時間の確認によって保持されたためであり、そのファイルは作成から数秒しかたっていない。テーブルは引き続き 1499 行を返す。
最後に、最後に、削除であるスナップショット 7 の読み取りは、「read snapshot 7: InvalidInputException」で失敗する。このエラーのクラスは、DuckLake がすでに持たないバージョンに対して送出するものである。
ここで cleanup_all => true を使っているのは、カタログが 1 つだけで、読み取り側がいないからである。本番環境では代わりに older_than を使い、最も長い読み取りよりも長い経過時間を指定する。こうすると、クリーンアップは十分に長く削除予定となっていたファイルだけを削除する。
実践ルール: DuckLake のスナップショットを先に期限切れにし、各クリーンアップの呼び出しは、先にドライランを行ってから本番を実行する。この順序を守る。既定の孤立ファイルの確認は維持する。cleanup_all を使うのは、データフォルダを所有するカタログが 1 つだけで、削除対象のファイルをまだ使っている読み取り側がいない場合に限る。それ以外では older_than を使う。
本番環境で起こる問題
読み取り中のファイルを削除する。 vacuum やクリーンアップの前に開始されたクエリが、その後に消えたファイルを読み取ると、読み取りは途中で失敗する。これは、メンテナンス時間帯に実行されたジョブで、存在しないオブジェクトの名前を示す読み取りエラーとして現れる。メンテナンスは長時間の読み取りを避けて実行し、保持期間は最も長い読み取りより長く設定する。保持期間が短すぎると、書き込み側が書き出したもののまだコミットしていないファイルまで削除されることがある。この場合は1回の読み取りが失敗するだけでなく、テーブルが破損する。そのため、保持期間は最も長く実行される書き込みよりも長くする。
最長のクエリより短い保持期間。 Delta Lake の既定値である7日間は、測定で得た値ではなく余裕を見た値である。1か月前のバージョンを読み取るダッシュボードは、この範囲の外にある。読み取り側が古いバージョンを参照する必要があるなら、保持期間でそのバージョンを覆うか、読み取り側が先にデータをコピーしなければならない。
メンテナンス後に失敗するタイムトラベル。 期限切れになったスナップショットと vacuum で削除されたバージョンは、形式に応じて ValueError、ArrowInvalid、InvalidInputException で失敗する。Iceberg は ValueError を送出し、Delta は ArrowInvalid を送出する。DuckLake は InvalidInputException を送出する。後で読み取るためにスナップショット ID やバージョン番号を記録しているジョブは、そのスナップショットが期限切れになると、同じように失敗する。各レポートがどのスナップショットを使ったかは自分で記録しておく。そうすれば、再構築は古いスナップショットの読み取りに頼らず、データから始められる。
実際の実行と異なるドライラン。 2回の呼び出しの間に書き込み側がコミットすると、両者の結果は食い違うことがある。ドライランの件数は、自分が想定した件数を示すにすぎず、実際の実行で削除される件数とは限らない。実際の実行の件数をドライランの件数と並べて確認し、説明のつかない差があれば中止する。
古いスナップショットを必要とする監査。 レポートによっては、数か月前の数値を再現しなければならない。期限切れにすると、この再現能力は完全に失われる。そのため、期限切れにする前に監査の対象期間を決め、監査に必要なスナップショットまたはコピーしたデータを残す。期限切れの設定は、コピーの代わりにはならない。
別のカタログが必要とするファイルを削除するクリーンアップ。 cleanup_all と、cleanup_all による孤立ファイルの確認は、パスを指定してファイルを削除する。2つ目のカタログが同じデータフォルダを指している場合、そのカタログの有効なファイルは、1つ目のカタログから見ると孤立ファイルに見える。カタログの章では、この失敗を一時ディレクトリで示している。
実践ルール: 期限切れにする前、またはクリーンアップする前に、古いスナップショットやバージョンを開く可能性のある読み取り側、レポート、監査を一覧にし、そのうち最も長いものを覆うように保持期間を設定する。各呼び出しはドライランとして実行し、その件数を想定と比べ、両者が一致したときにだけ実際の呼び出しを実行する。
この章で行った決定
- Iceberg のスナップショットは、コミット順から選んだ ID を指定して期限切れにする。この章では経過時間による期限切れ処理を行わない。そのため、結果はマシンの時計に依存せず、pyiceberg 0.12.0 には直近 N 件を残す引数もない。
- pyiceberg はファイルを削除しない。そのため
expire-iceberg-snapshotsは、到達可能なファイルと到達不能なファイルの数を数えるだけで、削除は読者に委ねる。 vacuum-delta-dry-runの保持期間ゼロの実行は、学習専用である。コード中にその旨を明示しており、本番環境では既定の保持期間を維持する。- DuckLake の期限切れ処理とクリーンアップは別々の呼び出しであり、それぞれ本番の呼び出しの前にドライランとして実行する。
cleanup_allは、単一カタログの例にのみ現れる。それが有効なファイルを削除してしまう場合については、カタログの章で扱う。- 各例は、件数、安定したラベル、エラークラス名を出力し、ID、タイムスタンプ、ファイル名、パスは出力しない(理由は第 1 章を参照)。本文中の数値はすべて、バインドされた出力行か、その例自身の構成から得たものである。
- どの例も、前の章までに作成したテーブルをそのまま使う。そのため、読者がすでに見た履歴と照らして、各件数を確認できる。
- 各例は専用の一時ウェアハウスを作成するので、出力は前の例にも、実行するマシンにも依存しない。
ducklake-expire-cleanupの迷子のコピーは、孤立ファイルを見つけるで説明されているとおり、書き込み側がまだコミットしていないファイルの代わりである。実行は数秒で終わるため、ファイルが古くなるのを待たずに孤立ファイルの規則を示せる。
この版における本章
第2026.11.10版2026年11月20日時点で例が通過この章の3 例件のうち3件が合格
英語版の書籍(版2026.11.10)から翻訳した。