はじめかた
リポジトリを作り、DuckDB で最初のバージョンを書いて、読み返します。
このページでは、フォルダにリポジトリを作り、表を 1 つ書き込み、読み手と同じ方法で結果を読みます。同じコマンドは S3 や R2 でも動きます。フォルダの代わりに s3://bucket/prefix/ を渡してください。
インストール
pip install 'fdl-cli[s3]'
fdl コマンドと fdl Python パッケージが入ります。Python 3.10 以上が必要です。フォルダしか使わない場合は [s3] を外してください。
リポジトリを作る
fdl init ./towns/
init が書くのは次の 2 つのファイルだけです。
towns/
fdl.json {"fdl": "0.1", "id": "5f0c…", "data_dir": "data/"}
HEAD ref: refs/heads/main
HEAD は既定のブランチ main を指します。ブランチそのものはまだありません。指す先のバージョンがないためです。
fdl init は、サーバーで git init --bare を打つのと同じく、読み手が読む場所にリポジトリを作ります。手元で書く場所は、次に作る作業メタデータです。
作業メタデータをクローンする
リポジトリには直接書き込みません。自分のディスクにある SQLite ファイルの DuckLake メタデータ(作業メタデータ)に書き、書き終えたらそれをバージョンにします。
mkdir work && cd work
fdl clone ../towns/ lake.sqlite
最初のバージョンができる前は、clone は空のメタデータを作ります。その後は、main が指すバージョンのメタデータを写します。作業メタデータを ATTACH する文を表示します。
ATTACH 'ducklake:lake.sqlite' AS lake (
DATA_PATH '/abs/path/towns/data/', OVERRIDE_DATA_PATH true,
META_TYPE 'sqlite', DATA_INLINING_ROW_LIMIT 0,
META_JOURNAL_MODE 'WAL', BUSY_TIMEOUT 5000
);
作業メタデータの隣の lake.sqlite.fdl.json に、リポジトリ、ブランチ、クローン元のバージョンが記録されます。
書く
DuckDB のクライアントなら何でも使えます。Parquet ファイルはリポジトリの data/ フォルダに直接書かれます。
CREATE TABLE lake.main.towns AS
SELECT * FROM '../towns.csv';
DATA_INLINING_ROW_LIMIT 0 を付けると、DuckLake はすべての行を Parquet に書きます。既定のままだと小さな表をメタデータの中に持ちますが、バージョンは行を、読み手が取得できるデータファイルとして持つ必要があります。
宣言する
行を識別する列を FDL に伝えます。マージは主キーで行を照合し、読み手は主キーで行を引けます。
fdl declare primary-key lake.sqlite main.towns code
宣言はコミットまで作業メタデータと一緒に保存され、コミットがテーブルと照らし合わせて確認します(宣言)。宣言は省略できます。宣言の無いバージョンはテーブルだけを持ちます。
コミットして push する
fdl commit lake.sqlite -m "First towns" --author alice
fdl push lake.sqlite
commit は作業メタデータを固めて手元でバージョンにします。push はテーブルごとに、データを読まずに表示できる小さな要約(profile)を測り、バージョンと一緒にアップロードして main をそこへ動かし、refs/heads/main -> 019a3c4e-… (version 1) と表示します。リポジトリは次のようになります。
towns/
fdl.json
HEAD
refs/heads/main 019a3c4e-…
versions/019a3c4e-…/
metadata.db
tables.json
profiles/main/towns.json
version.json
tables/main/towns/ducklake-….parquet
fdl log ../towns/
1 019a3c4e-… 2026-11-01T09:00:00Z alice
First towns
読む
fdl url ../towns/
main が指すバージョンのメタデータを表示します。読み取り専用で ATTACH し、データファイルの場所を DuckDB に渡してください。
ATTACH 'ducklake:../towns/versions/019a3c4e-…/metadata.db' AS towns (
DATA_PATH '../towns/data/', OVERRIDE_DATA_PATH true, READ_ONLY
);
SELECT count(*) FROM towns.main.towns;
バージョンのメタデータは変わらないので、読み手はいつまでもキャッシュしてかまいません。変わるのは HEAD と refs/ の下のファイルだけです。
2 つめのバージョンを作る
fdl clone ../towns/ lake.sqlite
INSERT INTO lake.main.towns SELECT * FROM '../towns-2026.csv';
fdl commit lake.sqlite -m "Add 2026" --author alice
fdl push lake.sqlite
新しいバージョンは、最初のバージョンを親として記録します。最初の Parquet ファイルは両方のメタデータが参照し、新しいファイルは 2 つめのメタデータだけが参照します。
途中でほかの人が push していたら、この push は断られます。新しいバージョンが、いまの main の上に積まれていないためです。クローンし直して、変更をやり直してください。理由はバージョンと ref で説明しています。