---
title: 配置
description: データセットのファイル、そのパス、fdl.json の中身。
---

## パス

パスはルートからの相対パスで、小文字、区切りは `/` です。ルートはサーバー上の Git の bare リポジトリにあたり、たとえば `s3://bucket/lake/` です。

```
<root>/
  fdl.json                         データセットの設定
  HEAD                             既定の ref: "ref: refs/heads/main"
  refs.json                        すべての ref と指すバージョン。一覧を取れない読み手のため
  refs/
    heads/<name>                   ブランチ。動く。読み手が既定で見るのは main
    tags/<name>                    タグ。一度作ったら動かさない
    requests/<number>              ホストが使う（承認待ちなど、任意）
  versions/<version ID>/
    version.json                   バージョンの記録。最後に書く
    version.json.sig               記録の署名（任意）
    metadata.db                    固めたメタデータ
    tables.json                    テーブルとビュー、そのデータファイルと列、FDL の宣言
    profiles/<schema>/<table>.json データから測ったテーブルごとの要約（任意）
    metadata/<format>.db           別の DuckLake 形式のメタデータ（任意）
    expired.json                   保持期間を過ぎた印（過ぎたときだけ）
    <others>                       ホストが足すファイル
  <data_dir><schema>/<table>/ducklake-<uuid>.parquet   データファイル（共有、変えない）
  assets/<sha256>                  テーブルの行が指すファイル（共有、変更しない）
```

`HEAD` と `refs/` の下のファイルには、Git と同じく拡張子を付けません。中身は UTF-8 のテキストです。

ルートには、`versions/` の外に DuckLake のメタデータを置いてはいけません。作業メタデータも決して置いてはいけません。どちらも、公開していない状態を読み手に渡してしまいます。

ルートにほかの名前のファイルがあってもかまいません。読み手はそれを無視しなければなりません。

データセットのルートを、別のデータセットのルートの下に置いてはいけません。外側のデータセットで共有オブジェクトを削除するとき、内側のファイルをどのバージョンからも参照されていないオブジェクトとみなして削除してしまいます。

## fdl.json

```json
{
  "fdl": "0.1",
  "id": "5f0c8a52-6d3e-4f8e-9b1a-2c7d4e9f0a13",
  "data_dir": "tables/",
  "signers": ["alice@example.org ssh-ed25519 AAAAC3…"],
  "metadata_formats": [
    { "ducklake": "1.1" },
    { "ducklake": "1.0", "until": "2027-03-31" }
  ]
}
```

| 項目 | 必須 | 意味 |
| --- | --- | --- |
| `fdl` | must | この仕様のバージョン。読み手は知らないメジャーバージョンを読んではいけない |
| `id` | should | データセットを作ったときに書き、変えない UUID |
| `data_dir` | may | データファイルの場所。ルートからの相対で `/` で終わる。既定は `tables/` |
| `metadata_formats` | may | 新しいバージョンで出す DuckLake 形式と、いつまで出すか |
| `signers` | may | バージョンに署名する公開鍵。SSH の `allowed_signers` ファイルの行の形 |

`fdl.json` は `If-None-Match: *` で作るので、データセットを 2 回作っても最初の設定が残ります。

### id

`id` があれば、データセットの写しが同じデータセットだと分かります。ミラーはそのまま持ちます。ホストは、データセットを作るときに、自分の ID をここに書いてもかまいません。`id` の無いデータセットも読めます。

### data_dir

既定は `tables/` です。データファイルが既に別のプレフィックスにあるデータセットは、ファイルを動かさずに、そのプレフィックスをここに書きます。メタデータが参照するデータファイルは、すべて `data_dir` の下になければなりません。

`data_dir` はルートの下のフォルダで、1 つ以上の段を、それぞれ `/` で終えて書きます。

- 各段は、小文字の ASCII 英字、数字、`_`、`-`、`.` からなり、`.` だけの段は使えません
- 最初の段は `versions`、`refs`、`assets`、`objects` のどれでもありません

読み手と書き手は、書かれた値をそのまま使います。`data_dir` がこの規則に合わないか、文字列でないデータセットは断ります。足りない `/` を補うといった補正はしません。実装ごとに補正の仕方が違うと、読み書きするファイルが食い違うためです。ホストは、自分のファイルのためにほかのトップレベルのフォルダを予約し、その下を指す `data_dir` を断ってもかまいません。[`cases/data-dir.json`](https://github.com/queria-io/fdl/blob/main/cases/data-dir.json) に、値とそれぞれの読み方を並べています。`fdl.json` を読む実装は、すべてのケースを実行します。

#### data_dir を変える

ホストは、既にバージョンのあるデータセットのデータファイルを移してもかまいません。メタデータはデータファイルを `data_dir` からの相対で参照するので、バージョンは書き換えません。ホストは次の順に進めます。

1. 有効なバージョンが到達するデータファイルを、すべて新しい `data_dir` の下の同じパスに写す
2. それらがすべてあることを確認する
3. `fdl.json` の `data_dir` を新しい値にする

3 の前は、読み手は前の場所を読み、そこですべてのファイルを見つけます。3 の後は新しい場所を読み、そこにはすべてのファイルが既にあります。ホストは、変更の前に読んだ `data_dir` を使い続けている読み手がいなくなるまで、前の場所を残します。少なくとも猶予期間のあいだ残し、それより長く使う読み手がいればその分も残します。その後、ホストが前の場所を消します（[データファイル](/ja/spec/data-files#data_dir-の外のファイル)）。

3 の前にクローンした作業メタデータは、新しいデータファイルを前の場所に書き、どのバージョンもそれを読みません。書き手はクローンしたときの `data_dir` を覚えておき、`fdl.json` が別の `data_dir` を示していれば commit も push も断ります。ビルドはクローンし直します。ホストがそのような push を断ってもかまいません。

### signers

データセットの書き手が署名に使う鍵です（[読む](/ja/spec/reading#署名)を参照）。読み手は、ここに書いてあるという理由で鍵を信用してはいけません。ミラーは `fdl.json` も書き換えられるからです。この一覧は、どの鍵が来るはずかを示すだけで、信用する鍵は、読み手が元のホストから別の手段で受け取ります。

バージョンを残す期間はここに書きません。ホストが決めます。

### metadata_formats

各項目に DuckLake の形式と、任意で新しいバージョンに書く最後の日（`until`、ISO 8601 の日付）を書きます。この項目が無ければ、バージョンが持つのは `metadata.db` だけです。[バージョン](/ja/spec/versions#ほかの形式のメタデータ)を参照してください。
