データファイル
共有オブジェクト(データファイル・アセット)の決まり、共有オブジェクトを消してよいとき、保持期間を終わらせる手順と取り下げる手順。
共有オブジェクト
データファイルとアセットは共有オブジェクトです。一度だけ書き、上書きせず、いくつのバージョンから到達してもかまいません。Git の blob と同じです。バージョンからは次のように到達します。
| オブジェクト | パス | バージョンから到達するとき |
|---|---|---|
| データファイル | <data_dir><schema>/<table>/ducklake-<uuid>.parquet |
メタデータが参照している |
| アセット | assets/<sha256> |
テーブルが assets で宣言した列がどれかの行でその sha256 を持っている |
- 書き手は、バージョンを作る前に共有オブジェクトを置いてよい。バージョンから到達するまで、読み手には見えない
- 書き手は、既にあるオブジェクトをアップロードし直さなくてよい。ただしバージョンを書く前に消されることがあるので、バージョンから到達するオブジェクトが無い push は断る(書く)
データファイル
- 名前は DuckLake の付け方のまま。削除ファイルも同じ場所に置く
- 小さなファイルをまとめること(
ducklake_merge_adjacent_files)はいつでもしてよい。新しいファイルを書き、何も消さない
アセット
- 中身の sha256 を小文字の 16 進で名前にするので、同じ中身は 1 回だけ置く(アセット)
共有オブジェクトを消してよいとき
次の 2 つがどちらも成り立つときだけです。
- 有効なバージョン(
expired.jsonの無いもの)のどれからも到達しない - 置かれてから猶予期間が過ぎている。猶予期間は、書き手が置いたものの、まだバージョンにしていないオブジェクトを守る
共有オブジェクトは、パスが上の表の形をしたファイルだけです。データディレクトリの下の ducklake-<名前>.parquet か、assets/ に続く小文字 16 進 64 桁です。共有オブジェクトを消す処理は、それ以外のファイルを消してはいけません。
バージョンのメタデータはスナップショットを 1 つだけ持つので、tables.json の tables にあるデータファイルと削除ファイルが、そのバージョンが到達するもののすべてです。
DuckLake 自身の片付け(ducklake_cleanup_old_files、ducklake_expire_snapshots)は 1 つのメタデータしか見ないので、データセットから消すのに使ってはいけません。消すのは、データセット全体を見る処理の役目です。
data_dir の外のファイル
バージョンが到達するデータファイルは、fdl.json がいま示す data_dir の下にあるものだけです。その外のファイルは、名前によらず、どのバージョンからも到達しません。data_dir を変えた後に前の場所に残ったファイルがこれに当たります。共有オブジェクトを消す処理は data_dir と assets/ の下だけを見るので、このファイルを消しません。消すのはホストの作業です。ホストは、前の場所を読む読み手がいなくなってから、fdl.json が新しい data_dir を示していることを確認し直し、前の場所を一覧して 1 キーずつ消します。
安全に消す
消した共有オブジェクトは戻せず、それに到達するバージョンはすべて読めなくなります。共有オブジェクトを消す処理は、次の規則に従います。
- 判定できないときは消さない。有効なバージョンが何に到達するかを判定できないとき、つまり
version.json・tables.jsonが無いか読めないか解釈できないとき、またはアセットを持つメタデータを開けないときは、その種類のオブジェクトを消しません。どのデータファイルに到達するか判定できなければデータファイルを、どのアセットに到達するか判定できなければアセットを消しません。処理を止めて何も消さないのでもかまいません。残しすぎたオブジェクトは容量を使うだけですが、早く消しすぎたオブジェクトはバージョンを壊します - 消す直前にバージョンを読み直す。処理が判定している間に、書き手がバージョンを作ることがあります。判定のときに無かったバージョンが到達するオブジェクトは残します
- 判定したオブジェクトを 1 つずつキーで消す。プレフィックスやディレクトリごとには消しません
- このページの実装は、GC のテストケース で同じ結果になる。そこにある各データセットについて、消すオブジェクトが一致します
処理は、オブジェクトを読み手が読まない場所(別のバケットなど)へ移し、決めた時間が過ぎてからそこで消してもかまいません。そうすると、間違えたときに戻せます。書き手は、そこにあるオブジェクトをあるものとして数えません。
保持期間を過ぎたとき
バージョンの保持期間は、次の順に終わらせます。
versions/<ID>/expired.jsonを置く- バージョンのメタデータ(
metadata.dbとmetadata/)とtables.jsonを消す - 猶予期間のあと、上の条件に合う共有オブジェクトを消す
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "retention", "by": "nightly retention", "message": "Keep the newest 7 versions" }
byには、保持期間を終わらせた人や仕組み(定期実行のジョブなど)を書いてよい。これで履歴には、バージョンを作った人と同じく、そのデータを消した人も残る。値は自由な文字列で、FDL は意味を持たせない。書くツールやホストが値を決めるmessageには、その理由を自由な文で書いてよい。version.jsonのmessageが変更の内容を書くのと同じ。読み手が動作を決めるのはreasonで、messageは人が読むためのものversion.jsonは残す。履歴にはそのバージョンがあったことと中身が残り、親のつながりも切れないexpired.jsonを見た読み手は、reasonが何であれ、保持期間を過ぎたものとして扱い、メタデータを開かない- ref が指すバージョンの保持期間を終わらせてはいけない
保持期間を終わらせるバージョンの選び方
バージョンをどれだけ残すかはホストが決めます。各ブランチの新しい keep 個、since 以降に作ったもの、またはその両方です。この決め方で保持期間を終わらせる処理は、有効なバージョン全部をまとめて判定し、次のどれかに当たるバージョンを残します。
- ref が指している
- ref と
refs/heads/mainの共通祖先(書き込み)である。ref を main へ、または main を ref へマージするときに読む - ブランチ(
refs/heads/<名前>)の first-parent の並びで、ブランチが指すバージョンから数えて新しいkeep個に入る since以降に作った- 猶予期間のうちに作った。書き手はバージョンを置いてから ref を動かす
それ以外の保持期間を終わらせます。refs/heads/main の無いデータセットでは何も終わらせません。どのブランチの first-parent の並びにも無いバージョン(マージが取り込んだ最初の親以外の親、消したブランチのバージョン、ホストが閉じて消した変更リクエストの head)も、上のどれにも当たらなくなれば保持期間を終わらせます。作った時刻には created_at を使います。
この決め方の実装は、expire のテストケースで同じ結果になります。
取り下げ
取り下げは、間違って公開した個人情報のように、公開してはいけないデータを消すための手順です。保持期間と違い、そのデータを持つバージョンを、有効なものも含めてすべて対象にし、猶予期間を待ちません。
- そのデータを除いた新しいバージョンを作り、該当するバージョンを指しているブランチをすべてそこへ動かす。新しいバージョンの親はいまのバージョンなので、前へ動かすことになる。新しいバージョンのメタデータは自分のスナップショットだけを持つので(固めたメタデータ)、そのデータには到達しない
- 該当するバージョンを指すタグを消す
- 個人情報を持つデータファイルや、それが写ったスクリーンショットなど、そのデータを持つ共有オブジェクトをすぐに消す。該当するバージョンから到達し、残すバージョンのどれからも到達しないものが対象。そのオブジェクトに到達するバージョンは、すべて該当するバージョンになる。該当するバージョンに保持期間を過ぎたものがあると、メタデータが無いので、それがどのオブジェクトに到達していたかが分からない。その場合は、有効なバージョンのどれからも到達しない共有オブジェクトもすべてすぐに消す
- 該当するバージョンそれぞれに
"reason": "withdrawn"とdeletedを持つexpired.jsonを置き、メタデータを消す
共有オブジェクトをメタデータより先に消すのは、途中で止まった取り下げをやり直せるようにするためです。メタデータが残っていれば、どのファイルがそのデータを持つかが分かります。
{
"expired_at": "2026-12-01T00:00:00Z",
"reason": "withdrawn",
"deleted": {
"data": ["main/towns/ducklake-019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c.parquet"],
"assets": ["9f2c…"]
}
}
-
deletedは手順 3 で消した共有オブジェクトの名前です。データファイルはdata_dirからのパス、アセットは sha256 で書きます。名前だけなので、データそのものは含みません。1 回の取り下げで該当するバージョンは、どれも同じ一覧を持ちます。途中で止まった取り下げをやり直すときは、すでに書かれた名前を残します。1 回目に消したオブジェクトは、やり直しでは見つからないことがあるためです -
ホストは、どれかのバージョンの
deletedにあるオブジェクトを置く push を断ります。データセットの間でバージョンを写す処理も、それらを写しません。そうしないと、手元の clone などの古い写しからデータが戻ります -
ミラーなどデータセットの写しは、
deletedの名前で取り下げを適用します。写しの中でそれらを参照する有効なバージョンは、写しで作ったものも含めて、すべて該当するバージョンです。名前のあるオブジェクトは、どのバージョンも参照していなくても消します -
version.jsonは、保持期間のときと同じく残す。これで、どのデータセットも最初のバージョンまでの履歴を持つ。記録そのもの(author・message・annotations)にそのデータがあれば、expired.jsonを置く前に記録を書き換えてデータを除く。authorやmessageの該当する値はwithdrawnに置き換え、annotationsは該当する要素を除く。id・seq・parentsなどほかの項目はそのまま残す -
expired.jsonのbyとmessageは取り下げのあとも読めるので、そこにもそのデータを書いてはいけない。理由は「誤って公開した個人データ」のように一般的な言葉で書く -
ミラーは自分の写しを持っている。
"reason": "withdrawn"のexpired.jsonを写したミラーは、メタデータとdeletedにある共有オブジェクトを消す。元のホストはこれを強制できないので、知っているミラーに伝える