コンテンツにスキップ
FDL
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

はじめかた

リポジトリを作り、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 で説明しています。

このページは役に立ちましたか?