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
    ducklake.duckdb                 固めたカタログ
  data/main/towns/ducklake-….parquet

読み手に要るのは DuckDB だけです。refs/heads/main を読み、そのバージョンのカタログを HTTP か S3 で読み取り専用に ATTACH します。書き手に要るのは、読む・書く・条件付きで書くの 3 つができる置き場です。サーバーは要りません。

FDL を使う場面

DuckLake は、変更をすべてスナップショットとして残します。スナップショットは書き込みのたびにできるので、データベースの単位としては合っていますが、人が扱う単位としては細かすぎます。FDL は、データを公開するときに人が使う単位を足します。「これは 2025 年のリリースで、Alice が作り、2024 年のリリースの上に積んだもの」という単位です。この単位に、変わらない ID と、履歴の中の位置と、読み手がたどれる名前を付けます。

FDL は、公開して多くの人が読み、少ない人が書くデータに向いています。

バージョンごとにリリースするオープンデータや統計
チームで整備し、読み手に見せる前に変更を確認するデータセット
同じデータセットを複数のホストに置く写し（ミラー）

FDL はトランザクションのためのデータベースではありません。書き手どうしで行をマージしません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られて、新しいバージョンの上に作り直します。

ドキュメントの構成

はじめかた: リポジトリを作り、最初のバージョンを書いて読み返します
概念: リポジトリ、バージョン、ref、作業カタログを説明します
仕組み: コミットを何回かしたときに、リポジトリのファイルがどう増えるかを追います
ガイド: 置き場、HTTP での配信、ミラー、ホストの作り方を扱います
仕様: 形式の規範となる説明です。ツールは仕様に合わせて作ります
リファレンス: コマンドと Python API の一覧です

fdl コマンドと fdl Python パッケージが参照実装です。PyPI に fdl-cli として MIT ライセンスで公開しています。

pip install 'fdl-cli[s3]'