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

バージョン

バージョン 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])、含まれる図形の種類、地図を描くための、無作為に選んで簡略化した図形の GeoJSON FeatureCollection を持つ
  • 書き手は計算できないキーを省いてよい。読み手は知らないキーを無視する
  • 書き手は、データファイル(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 の形式にあります。

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