バージョン
バージョン ID、version.json の項目、固めたメタデータ、tag、ほかの DuckLake 形式のメタデータ。
バージョンは versions/<version ID>/ の下のファイルです。一度書いたら変えてはいけません。例外は次のとおりです。
- 保持期間を過ぎたとき、
expired.jsonを足し、メタデータを消す(データファイル) - 取り下げのとき、
"reason": "withdrawn"のexpired.jsonを足してメタデータを消し、version.jsonに取り下げるデータがあれば、それを除いて書き換える(データファイル) metadata/<format>.dbはあとから足してよい。既にあるファイルは変えないversion.json.sigは、バージョンを作ったあとに署名する書き手が足してよいprofiles/<schema>/<table>.jsonは、profile の無いテーブルについてあとから足してよい。既にある profile は変えない
バージョン ID
- 小文字・ハイフン区切りの UUIDv7。たとえば
019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c。作った順に並び、書き手どうしが調整しなくても重ならない - 中身のハッシュではない。同じメタデータでも別のバイト列で書かれることがあり、ハッシュは安定しない。中身は
metadata.sha256で確かめる - 人に見せる番号は
seq。ブランチをまたぐと重なるので ID にはしない - 読み手は、これ以外の形の ID を受け付けてはならない。ref・フォルダ名・
parentsのどこから来たものでも同じ。ID はパスの一部になるため
version.json
{
"fdl": "0.1",
"id": "019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c",
"seq": 12,
"parents": ["019a2f10-0c4d-7e88-a1b2-55c0d9e3f7aa"],
"created_at": "2026-10-30T09:00:00Z",
"author": { "name": "example" },
"message": "Add the final 2025 figures",
"metadata": {
"path": "metadata.db",
"storage": "duckdb-v1.5.0",
"bytes": 4194304,
"sha256": "9f2c…"
},
"ducklake": {
"format": "1.0",
"snapshot_id": 345,
"snapshots": [301, 345]
},
"tables": {
"path": "tables.json",
"bytes": 1536,
"sha256": "7a0e…"
},
"diff": {
"tables": { "added": [], "dropped": [] },
"rows": [{ "table": "main.population", "from": 1741, "to": 1802 }],
"columns": [
{ "table": "main.population", "kind": "add_column", "column": "note", "breaking": false }
],
"data": ["main.population"]
},
"annotations": {}
}
| 項目 | 必須 | 意味 |
|---|---|---|
fdl |
must | 書いたときの仕様のバージョン |
id |
must | ディレクトリと同じ ID。違っていたら読み手は読んではいけない |
seq |
must | 人に見せる番号。最初は 1、そのあとは最初の親の seq に 1 を足す |
parents |
must | 親のバージョン ID。最初のバージョンでは空、そのあとは 1 つ、マージでは 2 つ |
created_at |
must | UTC、ISO 8601 |
author |
must | 作った人。name は必須、email などは任意 |
message |
must | 何を変えたか |
metadata |
must | メタデータのファイル名(metadata.db)、大きさ、sha256、保存形式(storage) |
ducklake |
must | DuckLake の形式、固めたスナップショット、このバージョンのために作業メタデータが親の後に作ったスナップショットの範囲(最初と最後)。メタデータに入るのは固めたスナップショットだけ |
tables |
must | メタデータの隣の tables.json のファイル名、大きさ、sha256(tables.json)。保持期間を過ぎたバージョンの記録には無いことがある |
diff |
may | 最初の親からの変更。最初のバージョンでは、そのバージョンの内容(diff) |
annotations |
may | 形式が解釈しない情報。読む側(ホストやツール)の名前をキーにする。バージョンを作った元のファイルなど |
読み手は、知らない項目を無視しなければなりません。
metadata・tables の path は、バージョンのフォルダの中のファイル名です。/ や \ を含まず、. や .. でもありません。読み手は、それ以外の値を持つ記録を拒否しなければなりません。
バージョンの親は 1 つで、マージなら 2 つです。作ったブランチのバージョン、マージで取り込んだバージョンの順に並べます(マージ)。最初のバージョンには親がありません。読み手は、どんな長さのリストも受け付け、ブランチの履歴をたどるときは最初の要素を、あるバージョンが別のバージョンの子孫かを判定するときはすべての要素をたどらなければなりません。
固めたスナップショットの説明と SQL は、DuckLake の commit_message と commit_extra_info としてメタデータの中に残し、version.json には写しません。
diff
diff は、バージョンとその最初の親との違いです。読み手は version.json だけで履歴を表示できます。最初のバージョンでは、すべての表を追加として記録します。どのキーでも table は schema.table です。
| キー | 内容 |
|---|---|
tables |
added・dropped: 片方にしかない表 |
rows |
table・from・to: 両方にあり、行数が違う表 |
columns |
列の違い(下の表) |
data |
両方にあり、データファイルが違う表。行が同じでも記録します |
declarations |
両方にあり、宣言が違うテーブルとビュー |
dependencies |
dependencies の名前のうち、片方にしかないもの、または url か version が違うもの |
書き手は、固める前の作業メタデータで、親のスナップショットと最後のスナップショットを比べます。作業メタデータは親のメタデータからクローンするので、親のスナップショットを持っています。持っていないときは diff を書きません。diff のないバージョンや、最初の親以外のバージョンと比べるときは、読み手が 2 つのバージョンの tables.json を比べます。
columns の各項目は、両方にある表の、列 1 つの違いです。column は新しいバージョンでの列名です。
kind |
ほかに持つもの | breaking |
|---|---|---|
add_column |
false |
|
drop_column |
true |
|
rename_column |
from: 前の列名 |
true |
change_type |
from_type・to_type: DuckLake の型名 |
前の型の値がすべて新しい型に収まるとき(int32 から int64、float32 から float64)は false、それ以外は true |
読み手は、知らない kind を無視し、その breaking は読みます。diff の知らないキーも無視します。
形式番号
| 項目 | 指すもの | 変わるとき |
|---|---|---|
fdl |
この仕様 | この仕様が変わったとき |
ducklake.format |
DuckLake の管理用の表の形 | DuckLake の仕様が変わったとき |
metadata.storage |
メタデータファイルの保存形式 | DuckDB の保存形式が変わったとき |
読み手は、version.json だけで、そのバージョンを開けるか判断できます。
tables.json
tables.json は、ducklake.snapshot_id の時点のバージョンのテーブルとビューの一覧です。テーブルごとのデータファイルと列を持ち、FDL が読む宣言を持ちます。どのバージョンにもあります。読み手は、メタデータを開かずに、バージョンが何を持つかと、FDL が各テーブルをどう扱うかを知れます。
{
"tables": {
"main.population": {
"files": [
{
"path": "main/population/ducklake-019a3c4e-….parquet",
"rows": 1741,
"bytes": 52311,
"footer_bytes": 2048,
"deletes": { "path": "main/population/ducklake-019a3c4f-…-delete.parquet", "rows": 3, "bytes": 812 }
}
],
"columns": [
{ "id": 1, "name": "code", "type": "varchar", "nullable": false },
{ "id": 2, "name": "population", "type": "int64", "nullable": true, "default": "0" },
{
"id": 3, "name": "tags", "type": "list", "nullable": true,
"children": [{ "id": 4, "name": "element", "type": "varchar", "nullable": true }]
}
],
"primary_key": ["code"]
},
"main.reports": {
"files": [],
"columns": [
{ "id": 1, "name": "report_id", "type": "varchar", "nullable": false },
{ "id": 2, "name": "pdf_sha256", "type": "varchar", "nullable": true }
],
"primary_key": ["report_id"],
"assets": ["pdf_sha256"]
}
},
"views": {
"main.population_by_area": {
"sql": "SELECT c.area, sum(p.population) AS population FROM …",
"columns": [
{ "name": "area", "type": "VARCHAR" },
{ "name": "population", "type": "HUGEINT" }
]
}
},
"dependencies": {
"census": { "url": "https://example.org/census/", "version": "019a2f10-0c4d-7e88-a1b2-55c0d9e3f7aa" }
}
}
tablesには、そのスナップショットにあるすべてのテーブルをschema.tableをキーにして入れます。行の無いテーブルのfilesは空ですpathはデータセットのdata_dirからの相対パスです。ファイルはメタデータの順に並べますrowsとbytesは、メタデータが記録している行数と大きさです。footer_bytesは Parquet のフッターの大きさで、記録があるときだけ書きますdeletesは、そのデータファイルから行を消したときの削除ファイルですcolumnsは、そのスナップショットでのテーブルの列をメタデータの順に並べたものです。idは DuckLake の列 ID で、DuckLake はこれをどの Parquet データファイルにも列のfield_idとして書きます。列の名前を変えてもidは変わりません。typeは DuckLake の型名で、nullableはNOT NULLの列でfalseになります。defaultは、列を追加する前に書いたデータファイルの行がその列に持つ値を文字列にしたもので、NULL でないときだけ書きます。structはフィールドを、listはelementを、mapはkeyとvalueをchildrenに持ちますrenamed_columnsは、そのテーブルの列の名前を変えたことがあるときにtrueにします。名前を変える前に書いたデータファイルは、古い名前のままですviewsには、そのスナップショットにあるすべてのビューをschema.viewをキーにして入れます。sqlはメタデータが記録しているビューの SQL から、DuckLake の{DUCKLAKE_CATALOG}.を外したものです。DuckLake はこの置き換え文字を、SQL がビュー自身のカタログを指すところに書きます。同じデータセットのテーブルはmain.populationのように書き、読み手はそのバージョンのメタデータを既定のカタログにして SQL を実行します。ほかのカタログの名前(dependenciesが決めるもの)は書いたまま残します。columnsはそのクエリが返す列を順に並べたもので、nameとtype(DuckDB の型名)を持ちます。書き手は、dependenciesのそれぞれを ATTACH してクエリをバインドし、これを得ます- テーブルやビューの
primary_key・assets・profileと、dependenciesは宣言です。宣言の無いテーブルやビューはそのキーを書かず、ビューがほかのデータセットを読まないバージョンはdependenciesを書きません
書き手は、files・columns・renamed_columns・sql を固めるときにメタデータから作り、これらはメタデータと一致しなければなりません。宣言はここにだけあります。読み手は知らないキーを無視します。
DuckLake を使わずに Parquet ファイルを読む読み手は、deletes を持つファイルがあるテーブルや、renamed_columns が true のテーブルを読んではいけません。DuckLake と同じように削除と改名を当てはめる場合は読んでかまいません。当てはめずに読むと、消した行が返ったり、名前を変えた列が欠けたりします。columns の id を使い、データファイルの列を field_id で探す読み手は、名前を変えた列も DuckLake と同じように読めます。
保持期間から外すとき、tables.json はメタデータと一緒に消します。
profiles/
profile は、ducklake.snapshot_id の時点の 1 つのテーブルの要約です。行数、列ごとの中身、先頭の行、図形の列を持つテーブルでは図形の範囲と見本を持ちます。読み手はこの小さなファイル 1 つで、メタデータを開かずデータも読まずにテーブルを表示できます。ホストは検索の索引をこれから作れます。profile が持つのはデータから測った事実で、列が何を意味するかは持ちません。メタデータとデータから作るもので、食い違うときはメタデータとデータが正です。任意で、読み手は profile が無くても読めなければなりません。
テーブルごとの profile は versions/<ID>/profiles/<schema>/<table>.json に置きます。ビューにも置き、クエリが返す行から測ります。スキーマ名かテーブル名が空・.・.. のとき、または / を含むときは置きません。profile を作らなかった書き手や作るのに失敗した書き手のバージョンには、あとから profile を足せます。ほかの profile と同じく、そのバージョンのメタデータとデータから測ります。
{
"rows": 1741,
"columns": [
{ "name": "town_code", "type": "varchar", "null_count": 0, "distinct_count": 1741,
"values": [{ "value": "082201", "count": 1 }] },
{ "name": "prefecture", "type": "varchar", "null_count": 0, "distinct_count": 2,
"values": [{ "value": "茨城県", "count": 1200 }, { "value": "栃木県", "count": 541 }] },
{ "name": "population", "type": "int64", "null_count": 3, "distinct_count": 1650,
"min": 0, "max": 84211, "mean": 3120.5, "std": 4410.2, "q1": 420, "median": 1630, "q3": 3990,
"values": [{ "value": "0", "count": 12 }],
"histogram": [{ "start": 0, "end": 4210.55, "count": 1302 }] },
{ "name": "surveyed_on", "type": "date", "null_count": 0, "distinct_count": 1,
"min": "2025-10-01", "max": "2025-10-01", "span_days": 0,
"values": [{ "value": "2025-10-01", "count": 1741 }] },
{ "name": "coastal", "type": "boolean", "null_count": 0, "true_count": 210, "false_count": 1531 },
{ "name": "geom", "type": "geometry" }
],
"head": [{ "town_code": "082201", "prefecture": "茨城県", "population": 2210, "surveyed_on": "2025-10-01", "coastal": false }],
"geometry": {
"column": "geom",
"count": 1741,
"bbox": [139.69, 35.74, 140.85, 37.15],
"types": ["MULTIPOLYGON", "POLYGON"],
"sample": { "type": "FeatureCollection", "features": [] }
}
}
rowsはテーブルの行数。columnsにはメタデータの順にすべての列を並べ、nameとtype(DuckLake の型名)はtables.jsonと同じにする。メタデータに列の無いビューでは、クエリが返す列を DuckDB の型名で並べる- 図形の列を除くすべての列が
null_countを持つ。数値・テキスト・日付と時刻の列はdistinct_countとvaluesを持つ。大きなテーブルのdistinct_countは推定値のことがある valuesは、値(テキスト)とその値を持つ行の数を、多い順、同数なら値の順に並べる。列が持つ異なる値が 2,000 以下なら全部を並べ、そのときdistinct_countは正確な数になる。読み手は、valuesの長さがdistinct_countと等しいことで全部の一覧だと判定する。それより多い列は上位 10 件だけを並べる。ホストは全部の一覧を、地域コードや名前などの値で検索できる- 数値の列は
min・max・mean・std、四分位数のq1・median・q3、minからmaxまでを等幅に区切ったhistogramを持つ。日付と時刻の列はminとmaxをテキストで持ち、日付とタイムスタンプはspan_daysも持つ。真偽値の列はtrue_countとfalse_countを持つ headは、テーブルが返す先頭の行を JSON のオブジェクトで持つ。図形の列と、値を JSON で表せない列は入れないgeometryは、書き手が読めたときに、最初の図形の列を説明する。図形を持つ行の数、全体のbbox(列の座標で[xmin, ymin, xmax, ymax])、含まれる図形の種類、地図を描くための、無作為に選んで簡略化した図形の GeoJSONFeatureCollectionを持つ- 書き手は計算できないキーを省いてよい。読み手は知らないキーを無視する
- 書き手は、データファイル(
tables.json)と列が親と同じテーブルには親の profile を使い回す。profile を作るときに読むのは変わったテーブルだけになる。ビューは、そのビューのsqlが親と同じで、クエリが読むテーブルとビューがどれも変わっていないときに親の profile を使い回す。テーブルはデータファイルで、ビューは同じ規則で判定する。ほかのデータセットを読むビューは、dependenciesが親と同じで、そのビューが読む項目がどれもversionを持つときだけ親の profile を使い回す。クエリから読むテーブルを判定できないビュー(テーブル関数を読むものなど)は、すべてのビューのsqlが親と同じで、どのテーブルのデータファイルも変わっていないときだけ親の profile を使い回す。親の profile のvaluesが書き手と異なる上限で書かれているときは、profile を作り直す - 書き手は、
profileの宣言がfalseのテーブルとビューの profile を作らない。書き手のツールは、ビルドが作る中間のテーブルなど、利用者に読ませないテーブルにこれを宣言し、profile を作るときに読まないようにする。ホストも、自分が表示するものだけの profile を作ってよい - profile はバージョンの一部で、そのバージョンの中では変わらない。保持期間から外すときはメタデータと一緒に消す
固めたメタデータ
メタデータは、バージョンのフォルダーにある metadata.path のファイル(metadata.db)です。DuckDB のファイル形式の DuckLake メタデータです。
- スナップショットは
ducklake.snapshot_idの 1 つだけを持ち、管理用の行はそのスナップショットが読むものだけを持つ。前のスナップショット、それより前に終わった行、削除予定のファイルは入れない。dbt などのツールで作り直したテーブルはすべて新しいファイルに書かれるので、1 つのメタデータの中の前のスナップショットは最後のものとほとんど共有せず、ファイルを大きくするだけになる - 行をメタデータの中に持たない。データはすべてデータファイルにある
- 参照するデータファイルはすべて
data_dirの下にあり、メタデータのデータパスからの相対で記録されている。書き手はこれを確かめなければならず、ホストも確かめてよい data_pathは、書き手が公開したデータフォルダの絶対 URL(ルートとdata_dir)。読み手はこれを上書きする(読むを参照)- 読み手は、前のバージョンをそのバージョンのメタデータを開いて読む(読む)。別のバージョンのメタデータで
AT (VERSION => n)を使って読まない
宣言
FDL が DuckLake の記録のほかにテーブル・ビュー・データセットについて知る必要のある値は、tables.json で宣言します。
| 宣言 | 対象 | 値 | 使い道 |
|---|---|---|---|
primary_key |
テーブル | 行を識別する列の名前のリスト | 主キーでのセルのマージ |
assets |
テーブル | アセットを持つ列の名前のリスト | アセット |
profile |
テーブルまたはビュー | false: 書き手は profile を作らない。書かないときは true |
profiles/ |
dependencies |
バージョン | ビューの SQL が読むほかのデータセット。SQL が読むときの名前をキーにし、url にそのルートの URL、version に読むバージョンの ID を持つ。version が無いときは main が指すバージョンを読む |
ビューを読む |
- 書き手のツールは、クローンからコミットまでの間に宣言を設定する。コミットまでどう持つかはツールが決める
- コミットは親の宣言から始めるので、宣言はツールが変えるか消すまで残る。テーブルとビューは
schema.tableで対応を取るので、dbt のCREATE OR REPLACEのように同じ名前で作り直したテーブルは宣言を保つ。削除したテーブルやビューは宣言を失う - 宣言が列を示したあとに名前を変えた列は、親の宣言の中では古い名前のまま。書き手は列の
idをたどって新しい名前を書く。idをたどるのは、テーブルが DuckLake のテーブル ID を保っている間だけ。同じ名前で作り直したテーブルは新しい列 ID を持つので、宣言は列名で対応を取る - 宣言が示す列は、そのスナップショットのテーブルに 1 回ずつ無ければならない。
assetsの列はvarchar。ビューはprimary_keyとassetsを持たない。dependenciesの名前は[a-z_][a-z0-9_]*に合い、DuckDB が予約する名前(memory・system・temp)ではない。読み手は、バージョン自身のメタデータをそのどれでもない名前で ATTACH する。dependenciesのurlは/で終わる絶対 URL、versionはバージョン ID。満たさないとき、書き手は固めるのを断る - 宣言はテーブルの一部で、宣言が変わったテーブルやビューは変わったものとして扱う(変更がないとき、マージ)
データセット・テーブル・列が人にとって何を意味するか(タイトル、説明、ライセンス、出典、ガイドなど)を表す宣言を、FDL は定めません。書き手は、自分のスキーマなどに置いたメタデータの普通のテーブルの行として持ち、文書や画像の sha256 を持つ列を assets で宣言してかまいません。FDL はそのテーブルをほかのテーブルと同じに扱います。行が変わればバージョンができ、マージもほかのテーブルと同じです。ホストが自分の手段で持ち、それが無い push を断ってもかまいません(push が断られるとき)。
アセット
テーブルは、報告書の PDF や施設の写真などのファイルを指せます。Git LFS が大きなファイルを指すのと同じ形で、行にはファイルの sha256 を持ち、ファイルはデータと同じデータセットに置きます。
-- テーブル main.reports、宣言は "assets": ["pdf_sha256"]
SELECT title, pdf_sha256, pdf_media_type FROM lake.main.reports;
assetsが示す列は、各行にファイルの sha256(小文字の 16 進)か null を持つ。型はvarchar- 各ファイルはルートの
assets/<sha256>に置く(レイアウト)。同じ中身は 1 回だけ置き、複数のバージョンで共有する - ファイルの名前・大きさ・メディアタイプは、同じテーブルの列として持つ。列名は書き手が決める。読み手がファイルを取得する前に表示方法を判定できるよう、少なくともメディアタイプの列を持つのがよい
- ファイルを差し替えるときは、新しい中身を置き、その sha256 を行に入れる。古いバージョンは古い中身を指したまま残る
- 書き手は、ファイルのメディアタイプを
Content-Typeに付けてアップロードする。バージョンの行が持つアセットは、そのバージョンを書く前にすべてデータセットに置く - 読み手は、データセットを読んでいる場所の
<root>assets/<sha256>でファイルを取得し、表示する前に sha256 を確認する。ファイルが無い行は、リンク切れとして表示する - 提供元のサイトにあるファイルなど、データセットの外のファイルは、普通の列に URL で持つ。これはアセットではなく、FDL は管理しない
ほかの形式のメタデータ
1 つのバージョンが DuckLake の形式ごとにメタデータを持ってよく、読み手は DuckDB を替えずに、開けるファイルを選べます。
versions/<ID>/
metadata.db 作ったときのメタデータ(version.json が説明するもの)
metadata/1.0.db 形式 1.0 で書いたもの
metadata/1.1.db 形式 1.1 で書いたもの
metadata/<format>.dbはすべて、同じデータファイルを参照し、同じ行を返さなければならない- 読み手は、開ける形式を新しい順に試し、どれも無ければ
metadata.pathのメタデータを開く - 宣言した形式をあるバージョンで作れない書き手は、そのファイルを置かない。どのファイルも開けない読み手は、そのバージョンを読めない
- 古い形式で表せないものを使ったバージョンには、その形式のメタデータを置かない
fdl.jsonのuntilを過ぎた形式は、新しいバージョンでは書かない。過去のバージョンはそのまま残してよい- データファイルは、
fdl.jsonで宣言した一番古い形式が読めるように書かなければならない metadata.storageは、宣言した読み手が開ける一番古い DuckDB の保存形式にするのがよい
DuckDB 2.0 で古い形式を書く方法は DuckLake の形式にあります。