FDL
DuckLake のメタデータのバージョンを、Git がコミットを残すのと同じ形でオブジェクトストレージに残します。
FDL は、DuckLake のメタデータの履歴をバケットやフォルダに残します。バージョンはそれぞれ、メタデータを固めた写しと、親・作者・メッセージの記録でできています。読み手がどのバージョンを読むかは、refs/heads/main のような ref が決めます。Parquet ファイルはバージョンの間で共有し、書き換えません。
s3://my-bucket/towns/
fdl.json
HEAD ref: refs/heads/main
refs/heads/main 019a3c4e-…
versions/019a3c4e-…/
version.json 親・作者・メッセージ・sha256
metadata.db 固めたメタデータ
tables/main/towns/ducklake-….parquet
読み手に要るのは DuckDB だけです。refs/heads/main を読み、そのバージョンのメタデータを HTTP か S3 で読み取り専用に ATTACH します。書き手に要るのは、読む・書く・条件付きで書くの 3 つができる置き場です。サーバーは要りません。
FDL を使う場面
DuckLake は、変更をすべてスナップショットとして残します。スナップショットは書き込みのたびにできるので、データベースの単位としては合っていますが、人が扱う単位としては細かすぎます。FDL は、データを公開するときに人が使う単位を足します。「これは 2025 年のリリースで、Alice が作り、2024 年のリリースの上に積んだもの」という単位です。この単位に、変わらない ID と、履歴の中の位置と、読み手がたどれる名前を付けます。
FDL は、公開して多くの人が読み、少ない人が書くデータに向いています。
- バージョンごとにリリースするオープンデータや統計
- チームで整備し、読み手に見せる前に変更を確認するデータセット
- 同じデータセットを複数のホストに置く写し(ミラー)
FDL はトランザクションのためのデータベースではありません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られます。後の書き手は新しいバージョンの上に作り直すか、自分のブランチで作業してマージします。マージではテーブルの主キーで行を照合します。
FDL と Git
FDL は、Git がプロジェクトのコミットを残すのと同じ形で、メタデータのバージョンを残します。Git を知っていれば、FDL のほとんどは次のように対応します。
| Git | FDL |
|---|---|
| サーバー上の bare リポジトリ | リポジトリ(バケットのプレフィックス、またはフォルダ) |
| コミット | バージョン(versions/<ID>/version.json) |
| ツリー | 固めたメタデータ(metadata.db) |
| ブロブ | データファイル(Parquet)、アセット |
ブランチ・タグ・HEAD |
refs/heads/・refs/tags/・HEAD |
| 作業ツリー | 作業メタデータ(手元の SQLite) |
git init --bare |
fdl init |
git commit、git push |
fdl commit、fdl push |
git log・git tag |
fdl log・fdl tag |
git branch・git merge |
fdl branch・fdl merge |
バージョンの親は 1 つです。別のブランチをマージしたバージョンは親を 2 つ持ちます。書いてから読まれるまでで、コミットのときにファイルがどう動くかを順に追えます。
ドキュメントの構成
- はじめかた: リポジトリを作り、最初のバージョンを書いて読み返します
- 概念: リポジトリ、バージョン、ref、作業メタデータを説明します
- 仕組み: コミットを何回かしたときに、リポジトリのファイルがどう増えるかを追います
- ガイド: 置き場、HTTP での配信、ミラー、ホストの作り方を扱います
- 仕様: 形式の規範となる説明です。ツールは仕様に合わせて作ります
- リファレンス: コマンドと Python API の一覧です
fdl コマンドと fdl Python パッケージが参照実装です。PyPI に fdl-cli として MIT ライセンスで公開しています。
pip install 'fdl-cli[s3]'