仕様
FDL 0.1(草案)の規範となる説明。何を決め、何をホストに任せ、どんな用語を使うか。
FDL 0.1 の仕様の草案です。ツールはこの仕様に合わせて作り、ツールと仕様が食い違ったときは、先に仕様を直してからツールを合わせます。この日本語訳は参考で、英語版を正とします。
FDL は、DuckLake のメタデータのバージョンを残すための、置き場のファイル配置です。Git がコミットを保存する形にならっています。どのファイルを置き場のどこに置き、読み手と書き手がそれをどう扱うかを決めます。サーバーは要りません。置き場に求めるのは、読む・書く・条件付きで書くの 3 つです。
「must(しなければならない)」は必須、「may(してよい)」は任意、「should(するのがよい)」は推奨です。should と違うことをするツールには、それなりの理由があります。
決めること
- データセットの配置と、各ファイルの名前と中身(配置)
- バージョンの記録の項目、固めたメタデータ、その隣で FDL が読む宣言(バージョン)
- ref の中身と、動かすときの決まり(ref)
- 共有オブジェクト(データファイル・アセット)を消してよいとき、バージョンの保持期間を終わらせる手順と取り下げる手順(データファイル)
- 読み手がバージョンを見つけて開く手順と、誰が作ったかの確かめ方(読む)
- 書き込みの順番と、push が断られるとき(書く)
- HTTP で push を受け付けるホストが応えるリクエスト(HTTP での push)
ホストに任せること
- 誰がデータセットを読めるか、誰が
mainを動かせるか。1 つのデータセットの中身はすべて同じ人が読める - 認証、URL の形、保持期間の既定値
- DuckLake のメタデータそのものの中身。これは DuckLake の仕様が決める
- データセット・テーブル・列が人にとって何を意味するかの記録方法。タイトル、説明、ライセンス、出典、ガイド。FDL はこれらの項目も宣言も定めない
形式の中に、ホストやサービスの名前は出てきません。ホストが足す項目は、仕様が空けておいた場所に置きます。
用語
| 用語 | 意味 |
|---|---|
| 置き場(store) | データセットを置く場所。バケットかフォルダ |
| データセット(dataset) | 置き場の 1 つのプレフィックス(ルート)の下にあるもの全部。Git のリポジトリに当たる |
| ルート(root) | そのプレフィックス。/ で終わる。この仕様のパスはルートからの相対パス |
| メタデータ(metadata) | DuckLake がテーブル・スナップショット・データファイルを記録するデータベース(DuckLake はカタログデータベースと呼ぶ) |
| バージョン(version) | 固めたメタデータ 1 つとその記録。一度書いたら変えない |
| ref | バージョン ID を書いたファイル。ブランチ、タグ、リクエストは ref |
| 作業メタデータ(working metadata) | 書き手自身の SQLite の DuckLake メタデータ。データセットには置かない |
| データファイル(data file) | DuckLake が書く Parquet ファイル。バージョンの間で共有する |
| ホスト(host) | データセットを預かり、権限を管理するサービス |
| アセット(asset) | テーブルの行が sha256 で指すファイル。データとして集めた PDF や画像など |
| 宣言 | FDL が DuckLake の記録のほかにテーブル・ビュー・データセットについて知る必要のある値。主キー、アセットを持つ列、profile を作るか、ビューが読むほかのデータセット。バージョンの tables.json に持つ |
| 猶予期間(grace period) | どのバージョンからも到達しない共有オブジェクトを、消すまで残しておく期間。ホストが決めなければ 7 日 |
DuckLake のスナップショットとバージョンの関係は、作業ブランチの小さなコミットと、それを squash して main に入れたコミットの関係と同じです。スナップショットは作業メタデータへの書き込みのたびにできます。固めたメタデータは最後のスナップショットだけを持つので、読み手が戻れる単位はバージョンで、そのバージョンのメタデータを開いて読みます。