fdl-cli 0.32.0__tar.gz → 0.33.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/CHANGELOG.md +78 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/PKG-INFO +1 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/reference/cli.md +4 -4
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/data-files.md +7 -7
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/http.md +1 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/index.md +4 -2
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/layout.md +3 -3
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/versions.md +55 -97
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/writing.md +14 -18
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/stability.md +3 -2
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/reference/cli.md +4 -4
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/data-files.md +7 -7
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/http.md +1 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/index.md +4 -2
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/layout.md +3 -3
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/versions.md +54 -96
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/writing.md +14 -18
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/stability.md +3 -2
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/pyproject.toml +1 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/cli.py +2 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/dataset.py +18 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/diff.py +10 -3
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/merge.py +51 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/profiles.py +6 -2
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/repo.py +136 -20
- fdl_cli-0.33.0/src/fdl/tags.py +160 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_dataset.py +9 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_merge.py +64 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_profiles.py +63 -1
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_repo.py +86 -3
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.github/workflows/docs.yml +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.github/workflows/publish.yml +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.github/workflows/release.yml +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.github/workflows/test.yml +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.gitignore +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.node-version +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/.python-version +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/CLAUDE.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/CONTRIBUTING.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/LICENSE +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/README.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/SECURITY.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/blume.config.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/cases/collection.json +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/cases/data-dir.json +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/cases/retention.json +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/concepts/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/concepts/repositories.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/concepts/working-metadata.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/getting-started.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/building-a-host.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/mirrors.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/public-and-private.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/serving-over-http.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/guides/stores.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/index.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/internals/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/concepts/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/concepts/repositories.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/concepts/working-metadata.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/getting-started.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/building-a-host.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/mirrors.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/public-and-private.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/serving-over-http.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/guides/stores.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/index.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/internals/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/reference/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/reference/python.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/collection-cases.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/reading.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/refs.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/ja/spec/retention-cases.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/reference/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/reference/python.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/collection-cases.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/meta.ts +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/reading.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/refs.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/docs/spec/retention-cases.md +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/package-lock.json +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/package.json +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/public/CNAME +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/__init__.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/catalog.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/config.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/layout.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/objects.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/py.typed +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/refs.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/store.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/stores.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/src/fdl/version.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/http_repo.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_cli.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_collection_cases.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_data_dir_cases.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_http.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_objects.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_retention_cases.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/tests/test_stores.py +0 -0
- {fdl_cli-0.32.0 → fdl_cli-0.33.0}/uv.lock +0 -0
|
@@ -1,6 +1,84 @@
|
|
|
1
1
|
# CHANGELOG
|
|
2
2
|
|
|
3
3
|
|
|
4
|
+
## v0.33.0 (2026-11-21)
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
- Allow descriptions kept as table rows, and keep comments when merging
|
|
9
|
+
([#80](https://github.com/queria-io/fdl/pull/80),
|
|
10
|
+
[`0675306`](https://github.com/queria-io/fdl/commit/0675306b4f74ee5e5197f0788728ada352721c1e))
|
|
11
|
+
|
|
12
|
+
- Profile a view again only when a table or view it reads changed
|
|
13
|
+
([#81](https://github.com/queria-io/fdl/pull/81),
|
|
14
|
+
[`3a760ed`](https://github.com/queria-io/fdl/commit/3a760ed884b7206538fcbc994c12fa0ca8aead9c))
|
|
15
|
+
|
|
16
|
+
### Documentation
|
|
17
|
+
|
|
18
|
+
- **spec**: Keep primary keys, assets and catalogs as DuckLake tags and drop dataset.json and
|
|
19
|
+
tree.json ([#77](https://github.com/queria-io/fdl/pull/77),
|
|
20
|
+
[`945dab3`](https://github.com/queria-io/fdl/commit/945dab3a94ac579386c1572007972aa7be8fbef4))
|
|
21
|
+
|
|
22
|
+
* docs(spec)!: keep primary keys, assets and catalogs as DuckLake tags and drop dataset.json and
|
|
23
|
+
tree.json
|
|
24
|
+
|
|
25
|
+
A version no longer carries dataset.json, tree.json or files under objects/. What FDL reads about a
|
|
26
|
+
table or a view is kept in the metadata as tags: fdl.primary_key and fdl.assets on tables,
|
|
27
|
+
fdl.catalogs on views. Titles, descriptions, licenses, sources and guides are left to the host.
|
|
28
|
+
|
|
29
|
+
Earlier versions keep their files: readers may ignore dataset.json and tree.json, read primary keys,
|
|
30
|
+
assets and catalogs from dataset.json when a version has no tags, and files under objects/ stay
|
|
31
|
+
shared objects until the versions that list them are taken out of retention.
|
|
32
|
+
|
|
33
|
+
* docs(spec): compare fdl. tags only, follow renamed columns, and keep checks for earlier versions
|
|
34
|
+
|
|
35
|
+
Tags are written after the parent's snapshot so a change to tags alone shows in diff. Renamed
|
|
36
|
+
columns are followed by ID. An earlier version is one with dataset or tree, its dataset.json stops
|
|
37
|
+
deletion when unreadable, and a push still needs the files its tree.json lists. diff.tags covers
|
|
38
|
+
views. The stability page lists the fdl. tags.
|
|
39
|
+
|
|
40
|
+
### Features
|
|
41
|
+
|
|
42
|
+
- Skip the profile of a table or view tagged fdl.profile = false
|
|
43
|
+
([#82](https://github.com/queria-io/fdl/pull/82),
|
|
44
|
+
[`31a743c`](https://github.com/queria-io/fdl/commit/31a743c803b2b5f88818972477c26ed62e7491c8))
|
|
45
|
+
|
|
46
|
+
- Write primary keys, assets and catalogs as fdl. tags in the metadata
|
|
47
|
+
([#78](https://github.com/queria-io/fdl/pull/78),
|
|
48
|
+
[`eeab3e9`](https://github.com/queria-io/fdl/commit/eeab3e9e35546000428f98c769baeed1ac8ef9d5))
|
|
49
|
+
|
|
50
|
+
* docs(spec)!: keep primary keys, assets and catalogs as DuckLake tags and drop dataset.json and
|
|
51
|
+
tree.json
|
|
52
|
+
|
|
53
|
+
A version no longer carries dataset.json, tree.json or files under objects/. What FDL reads about a
|
|
54
|
+
table or a view is kept in the metadata as tags: fdl.primary_key and fdl.assets on tables,
|
|
55
|
+
fdl.catalogs on views. Titles, descriptions, licenses, sources and guides are left to the host.
|
|
56
|
+
|
|
57
|
+
Earlier versions keep their files: readers may ignore dataset.json and tree.json, read primary keys,
|
|
58
|
+
assets and catalogs from dataset.json when a version has no tags, and files under objects/ stay
|
|
59
|
+
shared objects until the versions that list them are taken out of retention.
|
|
60
|
+
|
|
61
|
+
* docs(spec): compare fdl. tags only, follow renamed columns, and keep checks for earlier versions
|
|
62
|
+
|
|
63
|
+
Tags are written after the parent's snapshot so a change to tags alone shows in diff. Renamed
|
|
64
|
+
columns are followed by ID. An earlier version is one with dataset or tree, its dataset.json stops
|
|
65
|
+
deletion when unreadable, and a push still needs the files its tree.json lists. diff.tags covers
|
|
66
|
+
views. The stability page lists the fdl. tags.
|
|
67
|
+
|
|
68
|
+
* feat: write primary keys, assets and catalogs as fdl. tags in the metadata
|
|
69
|
+
|
|
70
|
+
fdl commit writes fdl.primary_key and fdl.assets on tables and fdl.catalogs on views from
|
|
71
|
+
dataset.json, still writing dataset.json as before. files.json carries each table's primary_key
|
|
72
|
+
and assets, and diff lists the tables and views whose tags changed.
|
|
73
|
+
|
|
74
|
+
* fix: give a change of tags alone its own snapshot and check primary keys
|
|
75
|
+
|
|
76
|
+
Tags are written before the snapshot range is taken. When the last snapshot is the parent's and the
|
|
77
|
+
tags differ, a new snapshot holds them; unchanged tags are not rewritten. dataset.json's
|
|
78
|
+
primary_key must be a list of the table's columns, each once. A tag naming a missing table raises
|
|
79
|
+
CatalogError. The fdl diff reference lists the tags key.
|
|
80
|
+
|
|
81
|
+
|
|
4
82
|
## v0.32.0 (2026-11-16)
|
|
5
83
|
|
|
6
84
|
### Features
|
|
@@ -65,9 +65,9 @@ fdl commit <working.sqlite> -m "What changed" [--author alice] [--dataset datase
|
|
|
65
65
|
|
|
66
66
|
作業メタデータを、クローンした(または最後に push した)バージョンを親とする新しいバージョンに固め、`fdl push` で送るまで `<working.sqlite>.pending/` に置きます。リポジトリは何も変わりません。新しいバージョン ID と `seq` を表示します。push する前にもう一度コミットすると、まだ push していないバージョンを置き換えます。
|
|
67
67
|
|
|
68
|
-
バージョンはそれぞれ `dataset.json`([バージョン](/ja/spec/versions
|
|
68
|
+
バージョンはそれぞれ `dataset.json`([バージョン](/ja/spec/versions#以前のバージョンのファイル)を参照)で説明します。`--dataset` で指定したファイルか、なければいまのディレクトリの `dataset.json` を読みます。JSON だけを読みます。コマンドはそれをメタデータと照らし合わせ、列の型、NULL の可否、行数を書き足します。メタデータのコメント(`COMMENT ON`)は読まず、形式が決めていないキーは書かれたまま残します。テーブルごとの `primary_key` と `asset: true` の列、すべてのビューの `catalogs`、テーブルかビューの `"profile": false` は、メタデータの [tag](/ja/spec/versions#tag) にも書きます。
|
|
69
69
|
|
|
70
|
-
コマンドは、`dataset.json` のフォルダとその下にあるほかのファイルをすべてバージョンの tree に入れます。隠しファイルと隠しフォルダ、そのフォルダの中に `fdl clone` が作った作業メタデータ(コミットするもの以外も含め、`.fdl.json` で見つけます)と、`fdl` と SQLite がその隣に置くファイル(`<working.sqlite>.fdl.json`・`.pending/`・`.data/`・`-wal`)、そのフォルダの中にある `--assets` のフォルダは除きます。ほかのファイルが入らないよう、説明は専用のフォルダに置いてください。そのフォルダからのパスで `tree.json` を書き、push がリポジトリに無いものを書いたままの中身で `objects/<sha256>` にアップロードします([tree.json](/ja/spec/versions
|
|
70
|
+
コマンドは、`dataset.json` のフォルダとその下にあるほかのファイルをすべてバージョンの tree に入れます。隠しファイルと隠しフォルダ、そのフォルダの中に `fdl clone` が作った作業メタデータ(コミットするもの以外も含め、`.fdl.json` で見つけます)と、`fdl` と SQLite がその隣に置くファイル(`<working.sqlite>.fdl.json`・`.pending/`・`.data/`・`-wal`)、そのフォルダの中にある `--assets` のフォルダは除きます。ほかのファイルが入らないよう、説明は専用のフォルダに置いてください。そのフォルダからのパスで `tree.json` を書き、push がリポジトリに無いものを書いたままの中身で `objects/<sha256>` にアップロードします([tree.json](/ja/spec/versions#以前のバージョンのファイル))。
|
|
71
71
|
|
|
72
72
|
`asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、push がリポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
|
|
73
73
|
|
|
@@ -88,7 +88,7 @@ fdl push <working.sqlite> [--no-profile]
|
|
|
88
88
|
|
|
89
89
|
`fdl commit` が作ったバージョンをアップロードし、条件付きでブランチをそこへ動かします([書き込みの順番](/ja/spec/writing#書き込みの順番))。ブランチ、バージョン ID、`seq` を表示します。fast-forward の `fdl merge` のあとは、何もアップロードせず、ブランチをマージしたバージョンへ動かします。コミットしたものが無いときは `Nothing to push` と表示します。
|
|
90
90
|
|
|
91
|
-
アップロードの前に、テーブルとビューごとの profile([profiles/](/ja/spec/versions#profiles))を書き、`version.json` より前にアップロードします。ブランチが動く時点で profile がリポジトリにあります。読むのは、データファイルか列が親から変わったテーブルだけで、ほかのテーブルは親の profile
|
|
91
|
+
アップロードの前に、テーブルとビューごとの profile([profiles/](/ja/spec/versions#profiles))を書き、`version.json` より前にアップロードします。ブランチが動く時点で profile がリポジトリにあります。読むのは、データファイルか列が親から変わったテーブルだけで、ほかのテーブルは親の profile を引き継ぎます。ビューは、そのクエリか、クエリが読むテーブル・ビューが変わると、クエリを実行して測り直します。`fdl.profile` tag が `false` のテーブルとビューには profile を書きません。読めなかったテーブルには profile を書かず、警告を出します。コミットのあとに作業メタデータが変わっていたときは profile を書かずに警告します。`--no-profile` を付けると profile を書きません。`fdl profile` であとから足せます。
|
|
92
92
|
|
|
93
93
|
作業メタデータがリポジトリに書いたデータファイルは push の前からありますが、push するまでどのバージョンも参照しません。push しなかったファイルは猶予期間のあとに削除されます。
|
|
94
94
|
|
|
@@ -144,7 +144,7 @@ fdl diff <remote> [<version>] [--against <version>] [--json]
|
|
|
144
144
|
~ dataset.json
|
|
145
145
|
```
|
|
146
146
|
|
|
147
|
-
親と比べるときは、バージョンの `diff` から取ります([diff](/ja/spec/versions#diff))。それ以外のときや `diff` のないバージョンでは、行数を `dataset.json` から、データファイルを `files.json` から取り、列は名前で比べます。そのため列名の変更は見分けられません。`~ data` は、行が同じでもテーブルのデータファイルが変わったことを示します。`~ dataset.json` は、コミットがメタデータから書き足す値を除いて、書き手が `dataset.json` に書いた内容が親と変わったことを示します。`--json` を付けると、同じ内容を `tables`(`added`・`dropped`)・`rows`・`columns`・`data`・`dataset` を持つオブジェクトで表示します。fdl-cli 0.31 以前が書いたバージョンでは、代わりに `descriptions` から `~ description` の行を表示します。
|
|
147
|
+
親と比べるときは、バージョンの `diff` から取ります([diff](/ja/spec/versions#diff))。それ以外のときや `diff` のないバージョンでは、行数を `dataset.json` から、データファイルを `files.json` から取り、列は名前で比べます。そのため列名の変更は見分けられません。`~ data` は、行が同じでもテーブルのデータファイルが変わったことを示します。`~ tags` は、テーブルかビューの [tag](/ja/spec/versions#tag) が変わったことを示します。`~ dataset.json` は、コミットがメタデータから書き足す値を除いて、書き手が `dataset.json` に書いた内容が親と変わったことを示します。`--json` を付けると、同じ内容を `tables`(`added`・`dropped`)・`rows`・`columns`・`data`・`tags`・`dataset` を持つオブジェクトで表示します。fdl-cli 0.31 以前が書いたバージョンでは、代わりに `descriptions` から `~ description` の行を表示します。
|
|
148
148
|
|
|
149
149
|
## fdl show
|
|
150
150
|
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: データファイル
|
|
3
|
-
description:
|
|
3
|
+
description: 共有オブジェクト(データファイル・アセット・以前のバージョンの tree のファイル)の決まり、共有オブジェクトを消してよいとき、保持期間を終わらせる手順と取り下げる手順。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
## 共有オブジェクト
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
データファイル・アセット・以前のバージョンの tree のファイルは共有オブジェクトです。一度だけ書き、上書きせず、いくつのバージョンから到達してもかまいません。Git の blob と同じです。バージョンからは次のように到達します。
|
|
9
9
|
|
|
10
10
|
| オブジェクト | パス | バージョンから到達するとき |
|
|
11
11
|
| --- | --- | --- |
|
|
12
12
|
| データファイル | `<data_dir><schema>/<table>/ducklake-<uuid>.parquet` | メタデータが参照している |
|
|
13
|
-
| アセット | `assets/<sha256>` | `
|
|
14
|
-
| tree のファイル | `objects/<sha256>` | `tree.json`
|
|
13
|
+
| アセット | `assets/<sha256>` | `fdl.assets` の tag が示す列がどれかの行でその sha256 を持っている |
|
|
14
|
+
| tree のファイル | `objects/<sha256>` | `tree.json` が並べている。`tree.json` を持つのは[以前のバージョン](/ja/spec/versions#以前のバージョンのファイル)だけ |
|
|
15
15
|
|
|
16
16
|
- 書き手は、バージョンを作る前に共有オブジェクトを置いてよい。バージョンから到達するまで、読み手には見えない
|
|
17
17
|
- 書き手は、既にあるオブジェクトをアップロードし直さなくてよい。ただしバージョンを書く前に消されることがあるので、バージョンから到達するオブジェクトが無い push は断る([書く](/ja/spec/writing#push-が断られるとき))
|
|
@@ -23,7 +23,7 @@ description: 共有オブジェクト(データファイル・アセット・t
|
|
|
23
23
|
|
|
24
24
|
### アセットと tree のファイル
|
|
25
25
|
|
|
26
|
-
- 中身の sha256 を小文字の 16 進で名前にするので、同じ中身は 1 回だけ置く([アセット](/ja/spec/versions#アセット)・[
|
|
26
|
+
- 中身の sha256 を小文字の 16 進で名前にするので、同じ中身は 1 回だけ置く([アセット](/ja/spec/versions#アセット)・[以前のバージョンのファイル](/ja/spec/versions#以前のバージョンのファイル))
|
|
27
27
|
- 同じ中身がアセットでもあり tree のファイルでもあるときは、それぞれのフォルダに 1 つずつ置き、別々に到達する
|
|
28
28
|
|
|
29
29
|
## 共有オブジェクトを消してよいとき
|
|
@@ -47,7 +47,7 @@ DuckLake 自身の片付け(`ducklake_cleanup_old_files`、`ducklake_expire_sn
|
|
|
47
47
|
|
|
48
48
|
消した共有オブジェクトは戻せず、それに到達するバージョンはすべて読めなくなります。共有オブジェクトを消す処理は、次の規則に従います。
|
|
49
49
|
|
|
50
|
-
1. 判定できないときは消さない。有効なバージョンが何に到達するかを判定できないとき、つまり `version.json`・`files.json`・`tree.json` を読めないか解釈できないとき、または `files.json` に `named` が無くメタデータも開けないときは、その種類のオブジェクトを消しません。どのデータファイルに到達するか判定できなければデータファイルを、どのアセットに到達するか判定できなければアセットを、どの tree のファイルに到達するか判定できなければ tree のファイルを消しません。処理を止めて何も消さないのでもかまいません。残しすぎたオブジェクトは容量を使うだけですが、早く消しすぎたオブジェクトはバージョンを壊します
|
|
50
|
+
1. 判定できないときは消さない。有効なバージョンが何に到達するかを判定できないとき、つまり `version.json`・`files.json`、以前のバージョンの `dataset.json`・`tree.json` を読めないか解釈できないとき、または `files.json` に `named` が無くメタデータも開けないときは、その種類のオブジェクトを消しません。どのデータファイルに到達するか判定できなければデータファイルを、どのアセットに到達するか判定できなければアセットを、どの tree のファイルに到達するか判定できなければ tree のファイルを消しません。処理を止めて何も消さないのでもかまいません。残しすぎたオブジェクトは容量を使うだけですが、早く消しすぎたオブジェクトはバージョンを壊します
|
|
51
51
|
2. 消す直前にバージョンを読み直す。処理が判定している間に、書き手がバージョンを作ることがあります。判定のときに無かったバージョンが到達するオブジェクトは残します
|
|
52
52
|
3. 判定したオブジェクトを 1 つずつキーで消す。プレフィックスやディレクトリごとには消しません
|
|
53
53
|
4. このページの実装は、[収集のテストケース](/ja/spec/collection-cases) で同じ結果になる。そこにある各リポジトリについて、消すオブジェクトが一致します
|
|
@@ -59,7 +59,7 @@ DuckLake 自身の片付け(`ducklake_cleanup_old_files`、`ducklake_expire_sn
|
|
|
59
59
|
バージョンの保持期間は、次の順に終わらせます。
|
|
60
60
|
|
|
61
61
|
1. `versions/<ID>/expired.json` を置く
|
|
62
|
-
2. バージョンのメタデータ(`metadata.db` と `metadata/`)と `files.json`・`tree.json`
|
|
62
|
+
2. バージョンのメタデータ(`metadata.db` と `metadata/`)と `files.json` を消す。`dataset.json`・`tree.json` があればそれも消す
|
|
63
63
|
3. 猶予期間のあと、上の条件に合う共有オブジェクトを消す
|
|
64
64
|
|
|
65
65
|
```json expired.json
|
|
@@ -21,7 +21,7 @@ description: 書き手が置き場の鍵を持たずに push できるよう、
|
|
|
21
21
|
- 最後以外の部分は同じ大きさにする。1 回のリクエストで送れる大きさ(既定で 64 MB)を超えるファイルは分割して送る
|
|
22
22
|
- どのキーを受け付けるかはホストが決める。`HEAD`、`fdl.json`、配置の外のものへの書き込みは断ってよく(ただし HTTP の `HEAD` リクエストには答える。書き手が ref の ETag を読むのに使う)、`versions/` とデータファイルは `If-None-Match: *` 付きのときだけ受け付けてよい
|
|
23
23
|
- 確かめたあとに自分で ref を動かすホストは、`refs.json` も自分で書き直す。書き手からの `refs.json` の書き込みは 403 で断ってよく、書き手はそれを済んだものとして扱う
|
|
24
|
-
- ホストが push を確かめるのは ref を動かすとき。バージョンがあること、fast-forward であること、メタデータが `version.json`
|
|
24
|
+
- ホストが push を確かめるのは ref を動かすとき。バージョンがあること、fast-forward であること、メタデータが `version.json` と合うこと、参照するデータファイルと、`tree.json` があればそれが並べるファイルがすべてリポジトリにあることを確かめる。行が持つアセットや、ホスト自身の規則([push が断られるとき](/ja/spec/writing#push-が断られるとき))も確かめてよい。断るときは 409 で、理由を本文に書く
|
|
25
25
|
- `DELETE` は無い。保持期間と削除はホストの仕事
|
|
26
26
|
|
|
27
27
|
## ストレージへ直接アップロードする
|
|
@@ -14,9 +14,9 @@ FDL は、[DuckLake](https://ducklake.select/) のメタデータのバージョ
|
|
|
14
14
|
## 決めること
|
|
15
15
|
|
|
16
16
|
- リポジトリの配置と、各ファイルの名前と中身([配置](/ja/spec/layout))
|
|
17
|
-
-
|
|
17
|
+
- バージョンの記録の項目、固めたメタデータ、その中で FDL が読む tag([バージョン](/ja/spec/versions))
|
|
18
18
|
- ref の中身と、動かすときの決まり([ref](/ja/spec/refs))
|
|
19
|
-
-
|
|
19
|
+
- 共有オブジェクト(データファイル・アセット)を消してよいとき、バージョンの保持期間を終わらせる手順と取り下げる手順([データファイル](/ja/spec/data-files))
|
|
20
20
|
- 読み手がバージョンを見つけて開く手順と、誰が作ったかの確かめ方([読む](/ja/spec/reading))
|
|
21
21
|
- 書き込みの順番と、push が断られるとき([書く](/ja/spec/writing))
|
|
22
22
|
- HTTP で push を受け付けるホストが応えるリクエスト([HTTP での push](/ja/spec/http))
|
|
@@ -26,6 +26,7 @@ FDL は、[DuckLake](https://ducklake.select/) のメタデータのバージョ
|
|
|
26
26
|
- 誰がリポジトリを読めるか、誰が `main` を動かせるか。1 つのリポジトリの中身はすべて同じ人が読める
|
|
27
27
|
- 認証、URL の形、保持期間の既定値
|
|
28
28
|
- DuckLake のメタデータそのものの中身。これは DuckLake の仕様が決める
|
|
29
|
+
- データセット・テーブル・列が人にとって何を意味するかの記録方法。タイトル、説明、ライセンス、出典、ガイド。FDL はこれらの項目も tag も定めない
|
|
29
30
|
|
|
30
31
|
形式の中に、ホストやサービスの名前は出てきません。ホストが足す項目は、仕様が空けておいた場所に置きます。
|
|
31
32
|
|
|
@@ -43,6 +44,7 @@ FDL は、[DuckLake](https://ducklake.select/) のメタデータのバージョ
|
|
|
43
44
|
| データファイル(data file) | DuckLake が書く Parquet ファイル。バージョンの間で共有する |
|
|
44
45
|
| ホスト(host) | リポジトリを預かり、権限を管理するサービス |
|
|
45
46
|
| アセット(asset) | テーブルの行が sha256 で指すファイル。データとして集めた PDF や画像など |
|
|
47
|
+
| tag | DuckLake がメタデータの中にテーブルやビューごとに持つキーと値。FDL はキーが `fdl.` で始まるものを読む |
|
|
46
48
|
| 猶予期間(grace period) | どのバージョンからも到達しない共有オブジェクトを、消すまで残しておく期間。ホストが決めなければ 7 日 |
|
|
47
49
|
|
|
48
50
|
DuckLake のスナップショットとバージョンの関係は、作業ブランチの小さなコミットと、それを squash して `main` に入れたコミットの関係と同じです。スナップショットは作業メタデータへの書き込みのたびにできます。固めたメタデータは最後のスナップショットだけを持つので、読み手が戻れる単位はバージョンで、そのバージョンのメタデータを開いて読みます。
|
|
@@ -20,16 +20,14 @@ description: リポジトリのファイル、そのパス、fdl.json の中身
|
|
|
20
20
|
version.json バージョンの記録。最後に書く
|
|
21
21
|
version.json.sig 記録の署名(任意)
|
|
22
22
|
metadata.db 固めたメタデータ
|
|
23
|
-
dataset.json バージョンの中身の説明
|
|
24
23
|
files.json メタデータから作った、表ごとのデータファイルの索引(任意)
|
|
25
|
-
tree.json README など、バージョンのほかのファイルのパスの一覧(任意)
|
|
26
24
|
profiles/<schema>/<table>.json データから測ったテーブルごとの要約(任意)
|
|
27
25
|
metadata/<format>.db 別の DuckLake 形式のメタデータ(任意)
|
|
28
26
|
expired.json 保持期間を過ぎた印(過ぎたときだけ)
|
|
29
27
|
<others> ホストが足すファイル
|
|
30
28
|
<data_dir><schema>/<table>/ducklake-<uuid>.parquet データファイル(共有、変えない)
|
|
31
29
|
assets/<sha256> テーブルの行が指すファイル(共有、変更しない)
|
|
32
|
-
objects/<sha256>
|
|
30
|
+
objects/<sha256> 以前のバージョンの tree.json が並べるファイル(共有、変更しない)
|
|
33
31
|
```
|
|
34
32
|
|
|
35
33
|
`HEAD` と `refs/` の下のファイルには、Git と同じく拡張子を付けません。中身は UTF-8 のテキストです。
|
|
@@ -38,6 +36,8 @@ description: リポジトリのファイル、そのパス、fdl.json の中身
|
|
|
38
36
|
|
|
39
37
|
ルートにほかの名前のファイルがあってもかまいません。読み手はそれを無視しなければなりません。
|
|
40
38
|
|
|
39
|
+
FDL が必要とする値を [tag](/ja/spec/versions#tag) に置く前に書かれたバージョンには、`dataset.json` と `tree.json` もあり、`objects/` の下のファイルはそのバージョンのものです([以前のバージョンのファイル](/ja/spec/versions#以前のバージョンのファイル))。新しいバージョンにはどちらも無く、いま始めるリポジトリには `objects/` がありません。
|
|
40
|
+
|
|
41
41
|
リポジトリのルートを、別のリポジトリのルートの下に置いてはいけません。外側のリポジトリで共有オブジェクトを削除するとき、内側のファイルをどのバージョンからも参照されていないオブジェクトとみなして削除してしまいます。
|
|
42
42
|
|
|
43
43
|
## fdl.json
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: バージョン
|
|
3
|
-
description: バージョン ID、version.json の項目、固めたメタデータ、
|
|
3
|
+
description: バージョン ID、version.json の項目、固めたメタデータ、tag、ほかの DuckLake 形式のメタデータ。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
バージョンは `versions/<version ID>/` の下のファイルです。一度書いたら変えてはいけません。例外は次のとおりです。
|
|
@@ -35,11 +35,6 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
35
35
|
"bytes": 4194304,
|
|
36
36
|
"sha256": "9f2c…"
|
|
37
37
|
},
|
|
38
|
-
"dataset": {
|
|
39
|
-
"path": "dataset.json",
|
|
40
|
-
"bytes": 2048,
|
|
41
|
-
"sha256": "4c1d…"
|
|
42
|
-
},
|
|
43
38
|
"ducklake": {
|
|
44
39
|
"format": "1.0",
|
|
45
40
|
"snapshot_id": 345,
|
|
@@ -50,19 +45,13 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
50
45
|
"bytes": 1536,
|
|
51
46
|
"sha256": "7a0e…"
|
|
52
47
|
},
|
|
53
|
-
"tree": {
|
|
54
|
-
"path": "tree.json",
|
|
55
|
-
"bytes": 214,
|
|
56
|
-
"sha256": "3c5d…"
|
|
57
|
-
},
|
|
58
48
|
"diff": {
|
|
59
49
|
"tables": { "added": [], "dropped": [] },
|
|
60
50
|
"rows": [{ "table": "main.population", "from": 1741, "to": 1802 }],
|
|
61
51
|
"columns": [
|
|
62
52
|
{ "table": "main.population", "kind": "add_column", "column": "note", "breaking": false }
|
|
63
53
|
],
|
|
64
|
-
"data": ["main.population"]
|
|
65
|
-
"dataset": true
|
|
54
|
+
"data": ["main.population"]
|
|
66
55
|
},
|
|
67
56
|
"annotations": {}
|
|
68
57
|
}
|
|
@@ -78,16 +67,14 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
78
67
|
| `author` | must | 作った人。`name` は必須、`email` などは任意 |
|
|
79
68
|
| `message` | must | 何を変えたか |
|
|
80
69
|
| `metadata` | must | メタデータのファイル名(`metadata.db`)、大きさ、sha256、保存形式(`storage`) |
|
|
81
|
-
| `dataset` | must | メタデータの隣の `dataset.json` のファイル名、大きさ、sha256。必須になる前に書かれたバージョンには無い |
|
|
82
70
|
| `ducklake` | must | DuckLake の形式、固めたスナップショット、このバージョンのために作業メタデータが親の後に作ったスナップショットの範囲(最初と最後)。メタデータに入るのは固めたスナップショットだけ |
|
|
83
71
|
| `files` | may | メタデータの隣の `files.json` を書いたときの、そのファイル名、大きさ、sha256([files.json](#filesjson)) |
|
|
84
|
-
| `tree` | may | バージョンがほかのファイルを持つときの、メタデータの隣の `tree.json` のファイル名、大きさ、sha256([tree.json](#treejson)) |
|
|
85
72
|
| `diff` | may | 最初の親からの変更。最初のバージョンでは、そのバージョンの内容([diff](#diff)) |
|
|
86
73
|
| `annotations` | may | 形式が解釈しない情報。読む側(ホストやツール)の名前をキーにする。バージョンを作った元のファイルなど |
|
|
87
74
|
|
|
88
|
-
読み手は、知らない項目を無視しなければなりません。fdl-cli 0.31 以前が書いたバージョンは、使った元のファイルを `inputs`
|
|
75
|
+
読み手は、知らない項目を無視しなければなりません。fdl-cli 0.31 以前が書いたバージョンは、使った元のファイルを `inputs` に持ちます。読み手は表示してもよく、表示しなくてもかまいません。以前のバージョンは `dataset` と `tree` を持ちます([以前のバージョンのファイル](#以前のバージョンのファイル))。
|
|
89
76
|
|
|
90
|
-
`metadata`・`dataset`・`
|
|
77
|
+
`metadata`・`files`、および以前のバージョンの `dataset`・`tree` の `path` は、バージョンのフォルダの中のファイル名です。`/` や `\` を含まず、`.` や `..` でもありません。読み手は、それ以外の値を持つ記録を拒否しなければなりません。
|
|
91
78
|
|
|
92
79
|
バージョンの親は 1 つで、マージなら 2 つです。作ったブランチのバージョン、マージで取り込んだバージョンの順に並べます([マージ](/ja/spec/writing#マージ))。最初のバージョンには親がありません。読み手は、どんな長さのリストも受け付け、ブランチの履歴をたどるときは最初の要素を、あるバージョンが別のバージョンの子孫かを判定するときはすべての要素をたどらなければなりません。
|
|
93
80
|
|
|
@@ -103,9 +90,9 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
103
90
|
| `rows` | `table`・`from`・`to`: 両方にあり、行数が違う表 |
|
|
104
91
|
| `columns` | 列の違い(下の表) |
|
|
105
92
|
| `data` | 両方にあり、データファイルが違う表。行が同じでも記録します |
|
|
106
|
-
| `
|
|
93
|
+
| `tags` | 両方にあり、[tag](#tag) が違う表とビュー |
|
|
107
94
|
|
|
108
|
-
書き手は、固める前の作業メタデータで、親のスナップショットと最後のスナップショットを比べます。作業メタデータは親のメタデータからクローンするので、親のスナップショットを持っています。持っていないときは `diff`
|
|
95
|
+
書き手は、固める前の作業メタデータで、親のスナップショットと最後のスナップショットを比べます。作業メタデータは親のメタデータからクローンするので、親のスナップショットを持っています。持っていないときは `diff` を書きません。以前のバージョンは `diff` に `dataset` か `descriptions` を持ち、`dataset.json` が変わったかを表します。読み手はこれを無視します。`diff` のないバージョンや、最初の親以外のバージョンと比べるときは、読み手が 2 つのバージョンの `files.json` を比べます。
|
|
109
96
|
|
|
110
97
|
`columns` の各項目は、両方にある表の、列 1 つの違いです。`column` は新しいバージョンでの列名です。
|
|
111
98
|
|
|
@@ -152,7 +139,8 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
152
139
|
"id": 3, "name": "tags", "type": "list", "nullable": true,
|
|
153
140
|
"children": [{ "id": 4, "name": "element", "type": "varchar", "nullable": true }]
|
|
154
141
|
}
|
|
155
|
-
]
|
|
142
|
+
],
|
|
143
|
+
"primary_key": ["code"]
|
|
156
144
|
}
|
|
157
145
|
},
|
|
158
146
|
"named": [
|
|
@@ -168,6 +156,7 @@ description: バージョン ID、version.json の項目、固めたメタデー
|
|
|
168
156
|
- `rows` と `bytes` は、メタデータが記録している行数と大きさです。`footer_bytes` は Parquet のフッターの大きさで、記録があるときだけ書きます
|
|
169
157
|
- `deletes` は、そのデータファイルから行を消したときの削除ファイルです
|
|
170
158
|
- `columns` は、そのスナップショットでの表の列をメタデータの順に並べたものです。`id` は DuckLake の列 ID で、DuckLake はこれをどの Parquet データファイルにも列の `field_id` として書きます。列の名前を変えても `id` は変わりません。`type` は DuckLake の型名で、`nullable` は `NOT NULL` の列で `false` になります。`default` は、列を追加する前に書いたデータファイルの行がその列に持つ値を文字列にしたもので、NULL でないときだけ書きます。`struct` はフィールドを、`list` は `element` を、`map` は `key` と `value` を `children` に持ちます。fdl-cli 0.24 より前の書き手は `columns` を書きません
|
|
159
|
+
- `primary_key` と `assets` は、その表の [tag](#tag) の `fdl.primary_key` と `fdl.assets`。tag があるときだけ書く
|
|
171
160
|
- `renamed_columns` は、その表の列の名前を変えたことがあるときに `true` にします。名前を変える前に書いたデータファイルは、古い名前のままです
|
|
172
161
|
- `named` には、メタデータがどのスナップショットででも名指しするデータファイルと削除ファイルを、`data_dir` からの相対パスですべて入れます。これがそのバージョンから到達するデータファイルです([データファイル](/ja/spec/data-files))。メタデータが古いスナップショットを残しているときは、`tables` より多くなります
|
|
173
162
|
|
|
@@ -175,32 +164,9 @@ DuckLake を使わずに Parquet ファイルを読む読み手は、`deletes`
|
|
|
175
164
|
|
|
176
165
|
保持期間から外すとき、`files.json` はメタデータと一緒に消します。
|
|
177
166
|
|
|
178
|
-
## tree.json
|
|
179
|
-
|
|
180
|
-
`tree.json` は、バージョンがテーブルのほかに持つファイル(README とそこに表示する画像など)をパスで並べた一覧です。Git の tree に当たります。パスごとにファイルの sha256 を持ち、ファイル自体は `objects/<sha256>` に置きます。テーブルはここに入れません。テーブルの tree はメタデータです。
|
|
181
|
-
|
|
182
|
-
```json tree.json
|
|
183
|
-
{
|
|
184
|
-
"entries": [
|
|
185
|
-
{ "path": "README.md", "sha256": "5e88…", "bytes": 3120 },
|
|
186
|
-
{ "path": "docs/images/towns.png", "sha256": "c9d2…", "bytes": 48211 }
|
|
187
|
-
]
|
|
188
|
-
}
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
- `entries` に、ファイルのパス・sha256(小文字の 16 進)・大きさを、パスの順に並べる。パスは相対パスで `/` で区切り、空・`.`・`..` のセグメントを含まず、重複しない
|
|
192
|
-
- 各ファイルはルートの `objects/<sha256>` に置き、行が指すアセットとは分ける。読み手は `<root>objects/<sha256>` でファイルを取得し、表示する前に sha256 を確認する。`tree.json` が並べるファイルは、バージョンを書く前にすべてリポジトリになければならない
|
|
193
|
-
- fdl-cli 0.31 以前はこれらのファイルを `assets/<sha256>` に置いていた。そのバージョンを持つリポジトリは、`tree.json` が並べる各ファイルを `objects/<sha256>` に写す。読み手は `assets/` の下を探さない
|
|
194
|
-
- ファイルは書いたままの中身で置く。Markdown のファイルの中の相対リンクは、そのファイル自身のパスを基準に解決し、パーセントエンコーディングをデコードしてから `entries` で引く。GitHub が README のリンクをコミットの tree で解決するのと同じである。`entries` に無いパスへのリンクはリンク切れとして扱う
|
|
195
|
-
- 多くの読み手は `README.md` を最初に表示する。どのファイルをどこに表示するかは読み手が決める
|
|
196
|
-
- `dataset.json` の `description` は短いテキストのまま残す。tree を読まない読み手もこれを持ち、一覧にはこれを表示する
|
|
197
|
-
- 書き手は、ファイルを編集する場所(Git のリポジトリの中など)に置き、書き手のツールが `tree.json` を書く。書き手が手で書くものではない
|
|
198
|
-
- バージョンにどのファイルを入れるかは書き手が決める
|
|
199
|
-
- `tree.json` はバージョンの一部で、そのバージョンの中では変わらない。保持期間から外すときはメタデータと一緒に消す
|
|
200
|
-
|
|
201
167
|
## profiles/
|
|
202
168
|
|
|
203
|
-
profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約です。行数、列ごとの中身、先頭の行、図形の列を持つテーブルでは図形の範囲と見本を持ちます。読み手はこの小さなファイル 1 つで、メタデータを開かずデータも読まずにテーブルを表示できます。ホストは検索の索引をこれから作れます。profile
|
|
169
|
+
profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約です。行数、列ごとの中身、先頭の行、図形の列を持つテーブルでは図形の範囲と見本を持ちます。読み手はこの小さなファイル 1 つで、メタデータを開かずデータも読まずにテーブルを表示できます。ホストは検索の索引をこれから作れます。profile が持つのはデータから測った事実で、列が何を意味するかは持ちません。`files.json` と同じくメタデータとデータから作るもので、食い違うときはメタデータとデータが正です。任意で、読み手は profile が無くても読めなければなりません。
|
|
204
170
|
|
|
205
171
|
テーブルごとの profile は `versions/<ID>/profiles/<schema>/<table>.json` に置きます。ビューにも置き、クエリが返す行から測ります。スキーマ名かテーブル名が空・`.`・`..` のとき、または `/` を含むときは置きません。profile を作らなかった書き手や作るのに失敗した書き手のバージョンには、あとから profile を足せます。ほかの profile と同じく、そのバージョンのメタデータとデータから測ります。
|
|
206
172
|
|
|
@@ -233,14 +199,15 @@ profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約
|
|
|
233
199
|
}
|
|
234
200
|
```
|
|
235
201
|
|
|
236
|
-
- `rows` はテーブルの行数。`columns` にはメタデータの順にすべての列を並べ、`name` と `type`(DuckLake の型名)は `
|
|
202
|
+
- `rows` はテーブルの行数。`columns` にはメタデータの順にすべての列を並べ、`name` と `type`(DuckLake の型名)は `files.json` と同じにする。メタデータに列の無いビューでは、クエリが返す列を DuckDB の型名で並べる
|
|
237
203
|
- 図形の列を除くすべての列が `null_count` を持つ。数値・テキスト・日付と時刻の列は `distinct_count` と `values` を持つ。大きなテーブルの `distinct_count` は推定値のことがある
|
|
238
204
|
- `values` は、値(テキスト)とその値を持つ行の数を、多い順、同数なら値の順に並べる。列が持つ異なる値が 2,000 以下なら全部を並べ、そのとき `distinct_count` は正確な数になる。読み手は、`values` の長さが `distinct_count` と等しいことで全部の一覧だと判定する。それより多い列は上位 10 件だけを並べる。ホストは全部の一覧を、地域コードや名前などの値で検索できる
|
|
239
205
|
- 数値の列は `min`・`max`・`mean`・`std`、四分位数の `q1`・`median`・`q3`、`min` から `max` までを等幅に区切った `histogram` を持つ。日付と時刻の列は `min` と `max` をテキストで持ち、日付とタイムスタンプは `span_days` も持つ。真偽値の列は `true_count` と `false_count` を持つ
|
|
240
206
|
- `head` は、テーブルが返す先頭の行を JSON のオブジェクトで持つ。図形の列と、値を JSON で表せない列は入れない
|
|
241
207
|
- `geometry` は、書き手が読めたときに、最初の図形の列を説明する。図形を持つ行の数、全体の `bbox`(列の座標で `[xmin, ymin, xmax, ymax]`)、含まれる図形の種類、地図を描くための、無作為に選んで簡略化した図形の GeoJSON `FeatureCollection` を持つ
|
|
242
208
|
- 書き手は計算できないキーを省いてよい。読み手は知らないキーを無視する
|
|
243
|
-
- 書き手は、データファイル(`files.json`)と列が親と同じテーブルには親の profile を使い回す。profile
|
|
209
|
+
- 書き手は、データファイル(`files.json`)と列が親と同じテーブルには親の profile を使い回す。profile を作るときに読むのは変わったテーブルだけになる。ビューは、そのビューの `sql` が親と同じで、クエリが読むテーブルとビューがどれも変わっていないときに親の profile を使い回す。テーブルはデータファイルで、ビューは同じ規則で判定する。クエリから読むテーブルを判定できないビュー(テーブル関数を読むものなど)は、すべてのビューの `sql` が親と同じで、どのテーブルのデータファイルも変わっていないときだけ親の profile を使い回す。親の profile の `values` が書き手と異なる上限で書かれているときは、profile を作り直す
|
|
210
|
+
- 書き手は、`fdl.profile` tag が `false` のテーブルとビューの profile を作らない。書き手のツールは、ビルドが作る中間のテーブルなど、利用者に読ませないテーブルにこの tag を付け、profile を作るときに読まないようにする。ホストも、自分が表示するものだけの profile を作ってよい
|
|
244
211
|
- profile はバージョンの一部で、そのバージョンの中では変わらない。保持期間から外すときはメタデータと一緒に消す
|
|
245
212
|
|
|
246
213
|
## 固めたメタデータ
|
|
@@ -255,69 +222,42 @@ profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約
|
|
|
255
222
|
- `data_path` は、書き手が公開したデータフォルダの絶対 URL(ルートと `data_dir`)。読み手はこれを上書きする([読む](/ja/spec/reading)を参照)
|
|
256
223
|
- 読み手は、前のバージョンをそのバージョンのメタデータを開いて読む([読む](/ja/spec/reading#前のバージョン))。別のバージョンのメタデータで `AT (VERSION => n)` を使って読まない
|
|
257
224
|
|
|
258
|
-
##
|
|
225
|
+
## tag
|
|
259
226
|
|
|
260
|
-
|
|
227
|
+
FDL が列のほかにテーブルやビューについて知る必要のある値は、メタデータの中に、テーブルやビューの DuckLake の tag として持ちます。1 つの値が DuckLake の `ducklake_tag` の 1 行で、`object_id` はテーブルかビューの ID、有効期間は書いたスナップショットからです。キーは `fdl.` で始まり、値は JSON のテキストです。
|
|
261
228
|
|
|
262
|
-
|
|
229
|
+
| キー | 付ける先 | 値 | 使い道 |
|
|
230
|
+
| --- | --- | --- | --- |
|
|
231
|
+
| `fdl.primary_key` | テーブル | 行を識別する列の名前の JSON 配列 | [主キーでの行のマージ](/ja/spec/writing#主キーでの行のマージ) |
|
|
232
|
+
| `fdl.assets` | テーブル | アセットを持つ列の名前の JSON 配列 | [アセット](#アセット) |
|
|
233
|
+
| `fdl.catalogs` | ビュー | ビューの SQL が読むほかのデータセットについて、ATTACH する名前とそのリポジトリの URL の対応の JSON オブジェクト(`{"census": "https://example.org/census/"}`) | ビューを読む。読み手は先にそれぞれのリポジトリをその名前で ATTACH する |
|
|
234
|
+
| `fdl.profile` | テーブルまたはビュー | `false`: 書き手はプロファイルを作らない | [profiles/](#profiles) |
|
|
263
235
|
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
"
|
|
267
|
-
"title": "Population by town",
|
|
268
|
-
"description": "Census population of each town, by age and sex",
|
|
269
|
-
"keywords": ["population", "census"],
|
|
270
|
-
"language": "en",
|
|
271
|
-
"homepage": "https://example.org/population",
|
|
272
|
-
"issued": "2026-10-30",
|
|
273
|
-
"update_frequency": "yearly",
|
|
274
|
-
"licenses": [{ "id": "CC-BY-4.0", "spdx": "CC-BY-4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }],
|
|
275
|
-
"sources": [{ "title": "2025 census", "path": "https://example.org/census-2025" }],
|
|
276
|
-
"contributors": [{ "title": "Example City", "roles": ["publisher"] }],
|
|
277
|
-
"temporal_coverage": { "start": "2025", "end": "2025" },
|
|
278
|
-
"spatial_coverage": ["JP"],
|
|
279
|
-
"schemas": [{ "name": "main", "title": "Tables" }],
|
|
280
|
-
"catalogs": { "census": "https://example.org/census/" },
|
|
281
|
-
"tables": [
|
|
282
|
-
{
|
|
283
|
-
"schema": "main",
|
|
284
|
-
"name": "population",
|
|
285
|
-
"title": "Population",
|
|
286
|
-
"description": "One row per town, age group and sex",
|
|
287
|
-
"primary_key": ["town_code", "age_group", "sex"],
|
|
288
|
-
"depends_on": ["https://example.org/census/#main.towns"],
|
|
289
|
-
"sql": "SELECT …",
|
|
290
|
-
"rows": 120000,
|
|
291
|
-
"fields": [
|
|
292
|
-
{ "name": "town_code", "title": "Town code", "description": "…", "type": "varchar", "nullable": false }
|
|
293
|
-
]
|
|
294
|
-
}
|
|
295
|
-
],
|
|
296
|
-
"annotations": {}
|
|
297
|
-
}
|
|
236
|
+
```sql
|
|
237
|
+
SELECT schema_name, table_name, tags FROM duckdb_tables() WHERE database_name = 'lake';
|
|
238
|
+
-- main population {fdl.primary_key=["town_code","age_group","sex"]}
|
|
298
239
|
```
|
|
299
240
|
|
|
300
|
-
-
|
|
301
|
-
-
|
|
302
|
-
- `
|
|
303
|
-
- `
|
|
304
|
-
- `
|
|
305
|
-
- `
|
|
306
|
-
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
- `annotations` という名前になる前のバージョンは、同じものを `extensions` に持つ。読み手は `extensions` を `annotations` として読む
|
|
310
|
-
- ライセンスや出典に書いたことは書き手の主張で、ホストは公開する前に確かめてよい
|
|
241
|
+
- 書き手のツールは、固める前の作業メタデータに、親より後のスナップショットから有効な行としてこれを書く。最後のスナップショットが親のものなら、そのために新しいスナップショットを作る。親のスナップショットから有効な行は、`diff` にも[変更がないとき](/ja/spec/writing#変更がないとき)の判定にも現れない。DuckDB が SQL で書ける tag は `comment`(`COMMENT ON`)だけ
|
|
242
|
+
- tag はテーブルに付け、列には付けない(`ducklake_column_tag`)。DuckDB は `comment` 以外の列の tag を持つテーブルを開けない
|
|
243
|
+
- `CREATE OR REPLACE`(dbt が使う)などで同じ名前のテーブルを作り直すと、ID が変わって tag が消える。書き手のツールは固める前に書き直す
|
|
244
|
+
- tag が示す列は、そのスナップショットのテーブルに 1 回ずつ無ければならない。tag を書いたあとに名前を変えた列は、tag の中では古い名前のままなので、書き手のツールは列の ID をたどって新しい名前を書いてから確認する。`fdl.assets` の列は `varchar`。満たさないとき、書き手は固めるのを断る
|
|
245
|
+
- 読み手はメタデータの `duckdb_tables()`・`duckdb_views()` の `tags` か、`ducklake_tag` の行から読む。メタデータを開かない読み手は、テーブルの tag を `files.json` で読む
|
|
246
|
+
- 読み手は、知らない `fdl.` のキーを無視する。それ以外のキーは FDL のものではなく、書き手はそのまま残し、FDL は読まない。DuckLake の `comment` もその 1 つ
|
|
247
|
+
- FDL の tag はテーブルの一部で、`fdl.` の tag が変わったテーブルやビューは変わったものとして扱う([変更がないとき](/ja/spec/writing#変更がないとき)、[マージ](/ja/spec/writing#テーブル))。この仕様で tag を比べるときは `fdl.` のキーだけを比べるので、`COMMENT ON` だけでは何も変わらない
|
|
248
|
+
|
|
249
|
+
データセット・テーブル・列が人にとって何を意味するか(タイトル、説明、ライセンス、出典、ガイドなど)を表す tag を、FDL は定めません。書き手は、自分のスキーマなどに置いたメタデータの普通のテーブルの行として持ってかまいません。FDL はそのテーブルをほかのテーブルと同じに扱います。行が変わればバージョンができ、マージもほかのテーブルと同じです。ホストが自分の手段で持ち、それが無い push を断ってもかまいません([push が断られるとき](/ja/spec/writing#push-が断られるとき))。
|
|
311
250
|
|
|
312
251
|
### アセット
|
|
313
252
|
|
|
314
253
|
テーブルは、報告書の PDF や施設の写真などのファイルを指せます。Git LFS が大きなファイルを指すのと同じ形で、行にはファイルの sha256 を持ち、ファイルはデータと同じリポジトリに置きます。
|
|
315
254
|
|
|
316
|
-
```
|
|
317
|
-
|
|
255
|
+
```sql
|
|
256
|
+
-- テーブル main.reports、tag は fdl.assets = ["pdf_sha256"]
|
|
257
|
+
SELECT title, pdf_sha256, pdf_media_type FROM lake.main.reports;
|
|
318
258
|
```
|
|
319
259
|
|
|
320
|
-
- `
|
|
260
|
+
- `fdl.assets` が示す列は、各行にファイルの sha256(小文字の 16 進)か null を持つ。型は `varchar`
|
|
321
261
|
- 各ファイルはルートの `assets/<sha256>` に置く([レイアウト](/ja/spec/layout#パス))。同じ中身は 1 回だけ置き、複数のバージョンで共有する
|
|
322
262
|
- ファイルの名前・大きさ・メディアタイプは、同じテーブルの列として持つ。列名は書き手が決める。読み手がファイルを取得する前に表示方法を判定できるよう、少なくともメディアタイプの列を持つのがよい
|
|
323
263
|
- ファイルを差し替えるときは、新しい中身を置き、その sha256 を行に入れる。古いバージョンは古い中身を指したまま残る
|
|
@@ -345,3 +285,21 @@ versions/<ID>/
|
|
|
345
285
|
- `metadata.storage` は、宣言した読み手が開ける一番古い DuckDB の保存形式にするのがよい
|
|
346
286
|
|
|
347
287
|
DuckDB 2.0 で古い形式を書く方法は [DuckLake の形式](/ja/internals/ducklake-formats)にあります。
|
|
288
|
+
|
|
289
|
+
## 以前のバージョンのファイル
|
|
290
|
+
|
|
291
|
+
FDL が必要とする値を tag に置く前に書かれたバージョンは、メタデータの隣にファイルを 2 つ多く持ちます。`version.json` に `dataset` か `tree` があるバージョンがそれです。
|
|
292
|
+
|
|
293
|
+
```
|
|
294
|
+
versions/<バージョン ID>/
|
|
295
|
+
dataset.json 書き手が書いた、バージョンの中身の説明
|
|
296
|
+
tree.json README など、バージョンのほかのファイルのパスの一覧(任意)
|
|
297
|
+
objects/<sha256> tree.json が並べるファイル(共有、変更しない)
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
- `version.json` の `dataset` と `tree` は、`files` と同じく、これらのファイルの名前・大きさ・sha256 を持つ
|
|
301
|
+
- 読み手は `dataset.json`・`tree.json`・`objects/` を無視してよい。表示する読み手が表示するのは、書き手が当時書いたもので、いまの意味ではない
|
|
302
|
+
- このバージョンには FDL の tag が無い。読み手と書き手は、主キーとアセットを `dataset.json` から読む。`tables` の要素(`schema` と `name` で対応を取る)の `primary_key` が `fdl.primary_key`、その `fields` のうち `"asset": true` の要素の `name` が `fdl.assets` に入る。`dataset.json` の最上位の `catalogs` は、すべてのビューの `fdl.catalogs`。このバージョンを基点にしたマージと、どのバージョンからも到達しないアセットの削除は、これに頼る
|
|
303
|
+
- `tree.json` の `entries` には、`path`、ファイルの `sha256` と `bytes` を並べる。各ファイルは `objects/<sha256>` にあり、そのバージョンが到達する共有オブジェクト([データファイル](/ja/spec/data-files#共有オブジェクト))。fdl-cli 0.31 以前はこれらのファイルを `assets/<sha256>` に置いていた。そのバージョンを持つリポジトリは、それを `objects/<sha256>` に写す
|
|
304
|
+
- `dataset.json` と `tree.json` は、バージョンを保持期間から外すときにメタデータと一緒に消す。`tree.json` を持つ有効なバージョンが無くなれば、`objects/` の下のファイルはどのバージョンからも到達せず、猶予期間のあとに消える
|
|
305
|
+
- 書き手は、新しいバージョンにこれらのファイルを書かない。このバージョンからコミット・元に戻す・マージで新しいバージョンを作る書き手は、読んだ主キー・アセット・`catalogs` を tag として書く。`diff` と[変更がないとき](/ja/spec/writing#変更がないとき)の判定では、親の `dataset.json` から読んだ値と比べるので、主キーとアセットが同じテーブルは変わったことにならない
|