データファイル
データファイルと元のファイルの決まり、データファイルを消してよいとき、保持期間を終わらせる手順と取り下げる手順。
データファイル
- 名前は DuckLake の付け方のまま:
<data_dir><schema>/<table>/ducklake-<uuid>.parquet。削除ファイルも同じ場所に置く - 上書きしない。1 つのファイルを複数のバージョンが参照してよい
- 書き手は、バージョンを作る前にデータファイルを置いてよい。バージョンが参照するまで、読み手には見えない
- 小さなファイルをまとめること（
ducklake_merge_adjacent_files）はいつでもしてよい。新しいファイルを書き、何も消さない
データファイルを消してよいとき
次の 2 つがどちらも成り立つときだけです。
- 有効なバージョン（
expired.jsonの無いもの）のカタログが、どれも参照していない - 置かれてから猶予期間が過ぎている。猶予期間は、書き手が置いたものの、まだバージョンにしていないファイルを守る
DuckLake 自身の片付け（ducklake_cleanup_old_files、ducklake_expire_snapshots）は 1 つのカタログしか見ないので、リポジトリから消すのに使ってはいけません。消すのは、リポジトリ全体を見る処理の役目です。
保持期間を過ぎたとき
バージョンの保持期間は、次の順に終わらせます。
versions/<ID>/expired.jsonを置く- バージョンのカタログ（
ducklake.duckdbとcatalogs/）とfiles.jsonを消す - 猶予期間のあと、上の条件に合うデータファイルを消す
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "retention" }version.jsonは残す。履歴にはそのバージョンがあったことと中身が残り、親のつながりも切れないexpired.jsonを見た読み手は、reasonが何であれ、保持期間を過ぎたものとして扱い、カタログを開かない- ref が指すバージョンの保持期間を終わらせてはいけない
取り下げ
取り下げは、間違って公開した個人情報のように、公開してはいけないデータを消すための手順です。保持期間と違い、そのデータを持つバージョンを、有効なものも含めてすべて対象にし、猶予期間を待ちません。
- そのデータを除いた新しいバージョンを作り、該当するバージョンを指しているブランチをすべてそこへ動かす。新しいバージョンの親はいまのバージョンなので、前へ動かすことになる
- 該当するバージョンを指すタグを消す
- そのデータを持つデータファイルを、すぐに消す。該当するバージョンのカタログが参照し、残すバージョンがどれもその時点のスナップショットで読んでいないファイルが対象
- 該当するバージョンそれぞれに
"reason": "withdrawn"のexpired.jsonを置き、カタログを消す
データファイルをカタログより先に消すのは、途中で止まった取り下げをやり直せるようにするためです。カタログが残っていれば、どのファイルがそのデータを持つかが分かります。
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "withdrawn" }version.jsonは、保持期間のときと同じく残す。記録そのもの（messageやinputs）にそのデータがあれば記録も消し、履歴にはその位置で親が欠けて見える- ミラーは自分の写しを持っている。
"reason": "withdrawn"のexpired.jsonを写したミラーは、元が消したカタログとデータファイルを消す。元のホストはこれを強制できないので、知っているミラーに伝える
元のファイル
sources/<sha256>。中身の sha256 を小文字の 16 進で名前にする。同じ中身は 1 回だけ置く- バージョンの
inputsのsha256からたどる - 置くかどうか、誰が読めるかはホストが決める。ほかの人の著作物であることがある