fdl-cli 0.18.2__tar.gz → 0.20.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.18.2 → fdl_cli-0.20.0}/CHANGELOG.md +30 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/PKG-INFO +1 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/concepts/repositories.md +1 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/mirrors.md +3 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/serving-over-http.md +2 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/concepts/repositories.md +1 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/mirrors.md +3 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/serving-over-http.md +2 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/reference/cli.md +18 -1
- fdl_cli-0.20.0/docs/ja/spec/data-files.md +68 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/http.md +2 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/index.md +4 -3
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/layout.md +4 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/versions.md +88 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/writing.md +5 -5
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/reference/cli.md +18 -1
- fdl_cli-0.20.0/docs/spec/data-files.md +68 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/http.md +2 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/index.md +4 -3
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/layout.md +4 -2
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/versions.md +88 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/writing.md +5 -5
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/pyproject.toml +1 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/cli.py +67 -3
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/dataset.py +8 -1
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/layout.py +6 -0
- fdl_cli-0.20.0/src/fdl/objects.py +227 -0
- fdl_cli-0.20.0/src/fdl/profiles.py +296 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/repo.py +145 -4
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/version.py +8 -0
- fdl_cli-0.20.0/tests/test_objects.py +177 -0
- fdl_cli-0.20.0/tests/test_profiles.py +131 -0
- fdl_cli-0.18.2/docs/ja/spec/data-files.md +0 -60
- fdl_cli-0.18.2/docs/spec/data-files.md +0 -60
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.github/workflows/docs.yml +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.github/workflows/publish.yml +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.github/workflows/release.yml +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.gitignore +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.node-version +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/.python-version +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/CLAUDE.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/CONTRIBUTING.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/LICENSE +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/README.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/blume.config.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/concepts/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/getting-started.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/building-a-host.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/public-and-private.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/guides/stores.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/index.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/internals/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/concepts/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/getting-started.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/building-a-host.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/public-and-private.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/guides/stores.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/index.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/internals/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/reference/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/reference/python.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/reading.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/ja/spec/refs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/reference/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/reference/python.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/meta.ts +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/reading.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/docs/spec/refs.md +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/package-lock.json +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/package.json +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/public/CNAME +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/__init__.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/catalog.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/py.typed +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/refs.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/store.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/src/fdl/stores.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/http_repo.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/test_cli.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/test_dataset.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/test_http.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/test_repo.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/tests/test_stores.py +0 -0
- {fdl_cli-0.18.2 → fdl_cli-0.20.0}/uv.lock +0 -0
|
@@ -1,6 +1,36 @@
|
|
|
1
1
|
# CHANGELOG
|
|
2
2
|
|
|
3
3
|
|
|
4
|
+
## v0.20.0 (2026-11-06)
|
|
5
|
+
|
|
6
|
+
### Documentation
|
|
7
|
+
|
|
8
|
+
- Drop the note that the draft spec changes as tools are built
|
|
9
|
+
([#36](https://github.com/queria-io/fdl/pull/36),
|
|
10
|
+
[`de531b8`](https://github.com/queria-io/fdl/commit/de531b806a3b1d65fe4e5347ce203d22573981d6))
|
|
11
|
+
|
|
12
|
+
### Features
|
|
13
|
+
|
|
14
|
+
- Write a profile of each table beside a version ([#39](https://github.com/queria-io/fdl/pull/39),
|
|
15
|
+
[`bdabd3f`](https://github.com/queria-io/fdl/commit/bdabd3fcd3f0b777609de78691b8ad64a1c40c26))
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## v0.19.0 (2026-11-06)
|
|
19
|
+
|
|
20
|
+
### Features
|
|
21
|
+
|
|
22
|
+
- Keep the files rows point at and a version's other files as assets, listed in tree.json
|
|
23
|
+
([#38](https://github.com/queria-io/fdl/pull/38),
|
|
24
|
+
[`8c49933`](https://github.com/queria-io/fdl/commit/8c49933158f31f8c40d267ee76a6ed8e331b548b))
|
|
25
|
+
|
|
26
|
+
A column marked asset holds the sha256 of a file stored at assets/<sha256>. A version's other files
|
|
27
|
+
(README.md and docs/) go in versions/<ID>/tree.json, path to sha256, as Git's tree does; they are
|
|
28
|
+
stored as written and links are resolved through the tree. fdl commit uploads both, --assets gives
|
|
29
|
+
the folder of the files rows point at, and fdl assets lists a folder as CSV.
|
|
30
|
+
|
|
31
|
+
Co-authored-by: Claude <noreply@anthropic.com>
|
|
32
|
+
|
|
33
|
+
|
|
4
34
|
## v0.18.2 (2026-11-03)
|
|
5
35
|
|
|
6
36
|
### Bug Fixes
|
|
@@ -29,7 +29,7 @@ Readers only read. A static HTTP server in front of the repository is enough for
|
|
|
29
29
|
refs/tags/<name> tags
|
|
30
30
|
versions/<ID>/ one folder per version
|
|
31
31
|
data/ Parquet files, shared by all versions
|
|
32
|
-
|
|
32
|
+
assets/<sha256> files a version points at, such as PDFs, images and its README
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
The repository holds no catalog outside a version folder, and never a working catalog. Either would hand readers a state that was never published.
|
|
@@ -9,13 +9,14 @@ A mirror is a copy of a repository on another host. Since versions and data file
|
|
|
9
9
|
|
|
10
10
|
Copy in the same order a push writes, so a reader of the mirror never follows a ref to a version that is not all there:
|
|
11
11
|
|
|
12
|
-
1. data files under `data/` that the mirror lacks
|
|
12
|
+
1. data files under `data/` and assets under `assets/` that the mirror lacks
|
|
13
13
|
2. version folders under `versions/` that the mirror lacks, `version.json` last in each
|
|
14
14
|
3. `fdl.json`, if it changed
|
|
15
15
|
4. `refs/`, `HEAD` and `refs.json`
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
18
|
aws s3 sync s3://origin/towns/data/ s3://mirror/towns/data/
|
|
19
|
+
aws s3 sync s3://origin/towns/assets/ s3://mirror/towns/assets/
|
|
19
20
|
aws s3 sync s3://origin/towns/versions/ s3://mirror/towns/versions/
|
|
20
21
|
aws s3 cp s3://origin/towns/fdl.json s3://mirror/towns/fdl.json
|
|
21
22
|
aws s3 sync s3://origin/towns/refs/ s3://mirror/towns/refs/ --delete
|
|
@@ -49,4 +50,4 @@ Anyone can write a `version.json`, so a checksum shows the copy matches the reco
|
|
|
49
50
|
|
|
50
51
|
When the origin takes a version out of retention, the mirror sees `expired.json` appear and the catalog disappear on the next copy. Copy `expired.json` and delete the catalogs the origin deleted. A mirror that keeps them serves versions its origin no longer does.
|
|
51
52
|
|
|
52
|
-
An `expired.json` with `"reason": "withdrawn"` means the origin removed data that must not be published. Delete the catalogs
|
|
53
|
+
An `expired.json` with `"reason": "withdrawn"` means the origin removed data that must not be published. Delete the catalogs, the data files and the assets the origin deleted, without waiting.
|
|
@@ -27,9 +27,10 @@ ATTACH 'ducklake:https://data.example.org/towns/versions/019a3c4e-…/ducklake.d
|
|
|
27
27
|
| `refs.json` | `no-store` | `application/json` |
|
|
28
28
|
| `versions/**` | `public, max-age=31536000, immutable` | as the file |
|
|
29
29
|
| `data/**` | `public, max-age=31536000, immutable` | `application/octet-stream` |
|
|
30
|
+
| `assets/**` | `public, max-age=31536000, immutable` | as uploaded |
|
|
30
31
|
| `fdl.json` | a short `max-age` | `application/json` |
|
|
31
32
|
|
|
32
|
-
A version folder and a data file never change once written, so they can be cached for as long as the CDN allows. Only `HEAD` and the refs change, and a cached ref sends readers to an old version without telling them. `expired.json` can appear in a version folder later, so a host that expires versions should purge `versions/<ID>/` from its CDN when it does.
|
|
33
|
+
A version folder and a data file never change once written, so they can be cached for as long as the CDN allows. Only `HEAD` and the refs change, and a cached ref sends readers to an old version without telling them. `expired.json` can appear in a version folder later, so a host that expires versions should purge `versions/<ID>/` from its CDN when it does. On withdrawal, it also purges the data files and `assets/<sha256>` it deleted.
|
|
33
34
|
|
|
34
35
|
The server must answer range requests (`Accept-Ranges: bytes`, `206 Partial Content`). DuckDB falls back to whole-file downloads without them, which is slow for large Parquet files.
|
|
35
36
|
|
|
@@ -29,7 +29,7 @@ description: リポジトリとは何か、置き場に何が求められるか
|
|
|
29
29
|
refs/tags/<name> タグ
|
|
30
30
|
versions/<ID>/ バージョンごとのフォルダ
|
|
31
31
|
data/ Parquet ファイル。全バージョンで共有
|
|
32
|
-
|
|
32
|
+
assets/<sha256> バージョンが指すファイル(PDF・画像・README など)
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
リポジトリには、バージョンのフォルダの外にカタログを置きません。作業カタログも置きません。どちらも、公開していない状態を読み手に渡してしまいます。
|
|
@@ -9,13 +9,14 @@ description: リポジトリを別のホストに写し、最新に保ち、写
|
|
|
9
9
|
|
|
10
10
|
push と同じ順に写します。そうすれば、ミラーの読み手が、まだ揃っていないバージョンを ref からたどることはありません。
|
|
11
11
|
|
|
12
|
-
1. ミラーに無い `data/`
|
|
12
|
+
1. ミラーに無い `data/` の下のデータファイルと `assets/` の下のアセット
|
|
13
13
|
2. ミラーに無い `versions/` の下のバージョンのフォルダ。各フォルダで `version.json` を最後に
|
|
14
14
|
3. 変わっていれば `fdl.json`
|
|
15
15
|
4. `refs/`、`HEAD`、`refs.json`
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
18
|
aws s3 sync s3://origin/towns/data/ s3://mirror/towns/data/
|
|
19
|
+
aws s3 sync s3://origin/towns/assets/ s3://mirror/towns/assets/
|
|
19
20
|
aws s3 sync s3://origin/towns/versions/ s3://mirror/towns/versions/
|
|
20
21
|
aws s3 cp s3://origin/towns/fdl.json s3://mirror/towns/fdl.json
|
|
21
22
|
aws s3 sync s3://origin/towns/refs/ s3://mirror/towns/refs/ --delete
|
|
@@ -49,4 +50,4 @@ ATTACH 'ducklake:https://mirror.example.org/towns/versions/019a3c4e-…/ducklake
|
|
|
49
50
|
|
|
50
51
|
元がバージョンの保持期間を終わらせると、ミラーは次に写すときに、`expired.json` が増え、カタログが消えたことに気づきます。`expired.json` を写し、元が消したカタログを消してください。残しておくと、元がもう出していないバージョンをミラーが出し続けます。
|
|
51
52
|
|
|
52
|
-
`"reason": "withdrawn"` の `expired.json`
|
|
53
|
+
`"reason": "withdrawn"` の `expired.json` は、公開してはいけないデータを元が取り下げたことを意味します。元が消したカタログ・データファイル・アセットを、待たずに消してください。
|
|
@@ -27,9 +27,10 @@ ATTACH 'ducklake:https://data.example.org/towns/versions/019a3c4e-…/ducklake.d
|
|
|
27
27
|
| `refs.json` | `no-store` | `application/json` |
|
|
28
28
|
| `versions/**` | `public, max-age=31536000, immutable` | ファイルに合わせる |
|
|
29
29
|
| `data/**` | `public, max-age=31536000, immutable` | `application/octet-stream` |
|
|
30
|
+
| `assets/**` | `public, max-age=31536000, immutable` | アップロードしたときの型 |
|
|
30
31
|
| `fdl.json` | 短い `max-age` | `application/json` |
|
|
31
32
|
|
|
32
|
-
バージョンのフォルダとデータファイルは一度書いたら変わらないので、CDN が許す限り長くキャッシュできます。変わるのは `HEAD` と ref だけです。ref をキャッシュすると、読み手は知らないうちに古いバージョンを読みます。`expired.json` はあとからバージョンのフォルダに増えることがあるので、保持期間を終わらせたホストは、そのとき `versions/<ID>/` を CDN から消してください。
|
|
33
|
+
バージョンのフォルダとデータファイルは一度書いたら変わらないので、CDN が許す限り長くキャッシュできます。変わるのは `HEAD` と ref だけです。ref をキャッシュすると、読み手は知らないうちに古いバージョンを読みます。`expired.json` はあとからバージョンのフォルダに増えることがあるので、保持期間を終わらせたホストは、そのとき `versions/<ID>/` を CDN から消してください。取り下げでは、消したデータファイルと `assets/<sha256>` も CDN から消してください。
|
|
33
34
|
|
|
34
35
|
サーバーは範囲リクエストに応える必要があります(`Accept-Ranges: bytes`、`206 Partial Content`)。応えないと DuckDB はファイル全体を取得し、大きな Parquet ファイルでは遅くなります。
|
|
35
36
|
|
|
@@ -44,13 +44,19 @@ HTTP のリポジトリでは、新しいデータファイルは `<working.sqli
|
|
|
44
44
|
## fdl commit
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty]
|
|
47
|
+
fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty] [--assets files/]
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
作業カタログを、チェックアウトしたバージョンを親とする新しいバージョンに固め、アップロードし、条件付きでブランチを動かします。ブランチ、新しいバージョン ID、`seq` を表示します。
|
|
51
51
|
|
|
52
52
|
バージョンはそれぞれ `dataset.json`([バージョン](/ja/spec/versions#datasetjson)を参照)で説明します。`--dataset` で指定したファイルか、なければいまのディレクトリの `dataset.json` か `dataset.yml` から読みます。そのフォルダより下にある `*.table.yml`(または `*.table.json`)のテーブルの説明も合わせて読みます。隠しフォルダの中は読みません。コマンドはそれをカタログと照らし合わせ、列の型、行数、カタログのコメントを書き足します。
|
|
53
53
|
|
|
54
|
+
コマンドは、説明の隣の `README.md` と、そこにある `docs/` より下のファイル(隠しファイルを除く)をバージョンの tree に入れます。そのフォルダからのパスで `tree.json` を書き、リポジトリに無いものを書いたままの中身で `assets/<sha256>` にアップロードします([tree.json](/ja/spec/versions#treejson))。
|
|
55
|
+
|
|
56
|
+
あわせてテーブルごとの profile を書きます([profiles/](/ja/spec/versions#profiles))。読むのは、データファイルか列が親から変わったテーブルだけです。読めなかったテーブルには profile を書かず、警告を出してコミットを続けます。
|
|
57
|
+
|
|
58
|
+
`asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、リポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
|
|
59
|
+
|
|
54
60
|
親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit` と表示し、ブランチを動かさずに終了コード 0 で終わります。同じ行を新しいファイルに書き直しただけの作り直しも、変更なしとみなします。`--allow-empty` を付けると、それでもバージョンを作ります。行を読めず判定できないときは、警告を出してバージョンを作ります。
|
|
55
61
|
|
|
56
62
|
次のときは断られます。
|
|
@@ -59,8 +65,17 @@ fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.
|
|
|
59
65
|
- チェックアウトのあとにブランチが動いたとき。チェックアウトし直して作業をやり直す
|
|
60
66
|
- 作業カタログが行をカタログの中に持っているとき
|
|
61
67
|
- カタログが参照するデータファイルがリポジトリに無いとき
|
|
68
|
+
- アセットの列が `varchar` でないとき、sha256 でない値を持つとき、リポジトリにも `--assets` にも無いファイルを指すとき
|
|
62
69
|
- データファイルが、データディレクトリの外を指す絶対パスで記録されているとき
|
|
63
70
|
|
|
71
|
+
## fdl assets
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
fdl assets <folder> > files.csv
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
フォルダより下のファイル(隠しファイルを除く)を、`path`・`sha256`・`bytes`・`media_type` の CSV で表示します。これを DuckDB の `read_csv` などでファイルを指すテーブルに読み込み、`sha256` の列に `asset: true` の印を付けて、`--assets <folder>` を付けてコミットします。ファイルの sha256 はここで 1 回だけ計算し、SQL でファイルを読む必要はありません。
|
|
78
|
+
|
|
64
79
|
## fdl log
|
|
65
80
|
|
|
66
81
|
```bash
|
|
@@ -95,6 +110,8 @@ fdl withdraw <remote> <version>... [--yes]
|
|
|
95
110
|
|
|
96
111
|
間違って公開した個人データなど、公開してはいけないデータを持つバージョンを取り下げます([取り下げ](/ja/spec/data-files#取り下げ))。先にそのデータを除いたバージョンをコミットし、該当するバージョンを指すブランチが無い状態にします。そのうえでこのコマンドが、該当するバージョンを指すタグ、そのカタログが参照し残すバージョンが読まないデータファイル、カタログを消し、`"reason": "withdrawn"` の `expired.json` を置きます。`version.json` は残します。
|
|
97
112
|
|
|
113
|
+
アセットは、まだ消しません。データを持つものは `assets/` から手で消してください。
|
|
114
|
+
|
|
98
115
|
`--yes` を付けないと、消すものを表示するだけです。残すバージョンが読んでいるファイルは残すものとして表示します。それがそのデータを持つなら、そのバージョンも取り下げます。ブランチかリクエストが該当するバージョンを指しているあいだは断られます。
|
|
99
116
|
|
|
100
117
|
## fdl expire
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: データファイル
|
|
3
|
+
description: 共有オブジェクト(データファイル・アセット)の決まり、共有オブジェクトを消してよいとき、保持期間を終わらせる手順と取り下げる手順。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## 共有オブジェクト
|
|
7
|
+
|
|
8
|
+
データファイルとアセットは共有オブジェクトです。一度だけ書き、上書きせず、いくつのバージョンから到達してもかまいません。Git の blob と同じです。バージョンからは次のように到達します。
|
|
9
|
+
|
|
10
|
+
| オブジェクト | パス | バージョンから到達するとき |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| データファイル | `<data_dir><schema>/<table>/ducklake-<uuid>.parquet` | カタログが参照している |
|
|
13
|
+
| アセット | `assets/<sha256>` | `dataset.json` で `asset` の印を付けた列がどれかの行でその sha256 を持っている、または `tree.json` が並べている |
|
|
14
|
+
|
|
15
|
+
- 書き手は、バージョンを作る前に共有オブジェクトを置いてよい。バージョンから到達するまで、読み手には見えない
|
|
16
|
+
- 書き手は、既にあるオブジェクトをアップロードし直さなくてよい。ただしバージョンを書く前に消されることがあるので、バージョンから到達するオブジェクトが無い push は断る([書く](/ja/spec/writing#push-が断られるとき))
|
|
17
|
+
|
|
18
|
+
### データファイル
|
|
19
|
+
|
|
20
|
+
- 名前は DuckLake の付け方のまま。削除ファイルも同じ場所に置く
|
|
21
|
+
- 小さなファイルをまとめること(`ducklake_merge_adjacent_files`)はいつでもしてよい。新しいファイルを書き、何も消さない
|
|
22
|
+
|
|
23
|
+
### アセット
|
|
24
|
+
|
|
25
|
+
- 中身の sha256 を小文字の 16 進で名前にするので、同じ中身は 1 回だけ置く([バージョン](/ja/spec/versions#アセット))
|
|
26
|
+
|
|
27
|
+
## 共有オブジェクトを消してよいとき
|
|
28
|
+
|
|
29
|
+
次の 2 つがどちらも成り立つときだけです。
|
|
30
|
+
|
|
31
|
+
1. 有効なバージョン(`expired.json` の無いもの)のどれからも到達しない
|
|
32
|
+
2. 置かれてから猶予期間が過ぎている。猶予期間は、書き手が置いたものの、まだバージョンにしていないオブジェクトを守る
|
|
33
|
+
|
|
34
|
+
DuckLake 自身の片付け(`ducklake_cleanup_old_files`、`ducklake_expire_snapshots`)は 1 つのカタログしか見ないので、リポジトリから消すのに使ってはいけません。消すのは、リポジトリ全体を見る処理の役目です。
|
|
35
|
+
|
|
36
|
+
## 保持期間を過ぎたとき
|
|
37
|
+
|
|
38
|
+
バージョンの保持期間は、次の順に終わらせます。
|
|
39
|
+
|
|
40
|
+
1. `versions/<ID>/expired.json` を置く
|
|
41
|
+
2. バージョンのカタログ(`ducklake.duckdb` と `catalogs/`)と `files.json`・`tree.json` を消す
|
|
42
|
+
3. 猶予期間のあと、上の条件に合う共有オブジェクトを消す
|
|
43
|
+
|
|
44
|
+
```json expired.json
|
|
45
|
+
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "retention" }
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- `version.json` は残す。履歴にはそのバージョンがあったことと中身が残り、親のつながりも切れない
|
|
49
|
+
- `expired.json` を見た読み手は、`reason` が何であれ、保持期間を過ぎたものとして扱い、カタログを開かない
|
|
50
|
+
- ref が指すバージョンの保持期間を終わらせてはいけない
|
|
51
|
+
|
|
52
|
+
## 取り下げ
|
|
53
|
+
|
|
54
|
+
取り下げは、間違って公開した個人情報のように、公開してはいけないデータを消すための手順です。保持期間と違い、そのデータを持つバージョンを、有効なものも含めてすべて対象にし、猶予期間を待ちません。
|
|
55
|
+
|
|
56
|
+
1. そのデータを除いた新しいバージョンを作り、該当するバージョンを指しているブランチをすべてそこへ動かす。新しいバージョンの親はいまのバージョンなので、前へ動かすことになる
|
|
57
|
+
2. 該当するバージョンを指すタグを消す
|
|
58
|
+
3. 個人情報を持つデータファイルや、それが写ったスクリーンショットなど、そのデータを持つ共有オブジェクトをすぐに消す。該当するバージョンから到達し、残すバージョンのどれからも到達しないものが対象。そのオブジェクトに到達するバージョンは、すべて該当するバージョンになる
|
|
59
|
+
4. 該当するバージョンそれぞれに `"reason": "withdrawn"` の `expired.json` を置き、カタログを消す
|
|
60
|
+
|
|
61
|
+
共有オブジェクトをカタログより先に消すのは、途中で止まった取り下げをやり直せるようにするためです。カタログが残っていれば、どのファイルがそのデータを持つかが分かります。
|
|
62
|
+
|
|
63
|
+
```json expired.json
|
|
64
|
+
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "withdrawn" }
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- `version.json` は、保持期間のときと同じく残す。記録そのもの(`message` や `inputs`)にそのデータがあれば記録も消し、履歴にはその位置で親が欠けて見える
|
|
68
|
+
- ミラーは自分の写しを持っている。`"reason": "withdrawn"` の `expired.json` を写したミラーは、元が消したカタログと共有オブジェクトを消す。元のホストはこれを強制できないので、知っているミラーに伝える
|
|
@@ -21,12 +21,12 @@ 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` が並べるファイルがすべてリポジトリにあることを確かめる。行が持つアセットも確かめてよい。断るときは 409 で、理由を本文に書く
|
|
25
25
|
- `DELETE` は無い。保持期間と削除はホストの仕事
|
|
26
26
|
|
|
27
27
|
## ストレージへ直接アップロードする
|
|
28
28
|
|
|
29
|
-
ホストはアップロード用の URL を渡し、ファイルをホストを通さずストレージへ直接送らせてよい。Git LFS の batch API
|
|
29
|
+
ホストはアップロード用の URL を渡し、ファイルをホストを通さずストレージへ直接送らせてよい。Git LFS の batch API と同じ形にする。この経路を使うのは、一度だけ書くファイル(データファイル、アセット、バージョンのファイル)だけ。ref は常にホストを通して書く。
|
|
30
30
|
|
|
31
31
|
書き手は、アップロードするファイルを `POST <root>/?batch` で送る。
|
|
32
32
|
|
|
@@ -5,7 +5,7 @@ sidebar:
|
|
|
5
5
|
description: FDL 0.1(草案)の規範となる説明。何を決め、何をホストに任せ、どんな用語を使うか。
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
FDL 0.1
|
|
8
|
+
FDL 0.1 の仕様の草案です。ツールはこの仕様に合わせて作り、ツールと仕様が食い違ったときは、先に仕様を直してからツールを合わせます。この日本語訳は参考で、英語版を正とします。
|
|
9
9
|
|
|
10
10
|
FDL は、[DuckLake](https://ducklake.select/) のカタログのバージョンを残すための、置き場のファイル配置です。Git がコミットを保存する形にならっています。どのファイルを置き場のどこに置き、読み手と書き手がそれをどう扱うかを決めます。サーバーは要りません。置き場に求めるのは、読む・書く・条件付きで書くの 3 つです。
|
|
11
11
|
|
|
@@ -16,7 +16,7 @@ FDL は、[DuckLake](https://ducklake.select/) のカタログのバージョン
|
|
|
16
16
|
- リポジトリの配置と、各ファイルの名前と中身([配置](/ja/spec/layout))
|
|
17
17
|
- バージョンの記録の項目と、固めたカタログ([バージョン](/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))
|
|
@@ -41,6 +41,7 @@ FDL は、[DuckLake](https://ducklake.select/) のカタログのバージョン
|
|
|
41
41
|
| 作業カタログ(working catalog) | 書き手自身の SQLite の DuckLake カタログ。リポジトリには置かない |
|
|
42
42
|
| データファイル(data file) | DuckLake が書く Parquet ファイル。バージョンの間で共有する |
|
|
43
43
|
| ホスト(host) | リポジトリを預かり、権限を管理するサービス |
|
|
44
|
-
|
|
|
44
|
+
| アセット(asset) | テーブルの行が sha256 で指すファイル。データとして集めた PDF や画像など |
|
|
45
|
+
| 猶予期間(grace period) | どのバージョンからも到達しない共有オブジェクトを、消すまで残しておく期間。ホストが決めなければ 7 日 |
|
|
45
46
|
|
|
46
47
|
DuckLake のスナップショットとバージョンの関係は、作業ブランチの小さなコミットと、それを squash して `main` に入れたコミットの関係と同じです。スナップショットは書き込みのたびにでき、カタログの中に残ります。人に見せる単位はバージョンです。
|
|
@@ -22,11 +22,13 @@ description: リポジトリのファイル、そのパス、fdl.json の中身
|
|
|
22
22
|
ducklake.duckdb 固めたカタログ
|
|
23
23
|
dataset.json バージョンの中身の説明
|
|
24
24
|
files.json カタログから作った、表ごとのデータファイルの索引(任意)
|
|
25
|
+
tree.json README など、バージョンのほかのファイルのパスの一覧(任意)
|
|
26
|
+
profiles/<schema>/<table>.json データから測ったテーブルごとの要約(任意)
|
|
25
27
|
catalogs/<format>.duckdb 別の DuckLake 形式のカタログ(任意)
|
|
26
28
|
expired.json 保持期間を過ぎた印(過ぎたときだけ)
|
|
27
|
-
<others>
|
|
29
|
+
<others> ホストが足すファイル
|
|
28
30
|
<data_dir><schema>/<table>/ducklake-<uuid>.parquet データファイル(共有、変えない)
|
|
29
|
-
|
|
31
|
+
assets/<sha256> テーブルの行やバージョンの tree.json が指すファイル(共有、変更しない)
|
|
30
32
|
```
|
|
31
33
|
|
|
32
34
|
`HEAD` と `refs/` の下のファイルには、Git と同じく拡張子を付けません。中身は UTF-8 のテキストです。
|
|
@@ -48,6 +48,11 @@ description: バージョン ID、version.json の項目、固めたカタログ
|
|
|
48
48
|
"bytes": 1536,
|
|
49
49
|
"sha256": "7a0e…"
|
|
50
50
|
},
|
|
51
|
+
"tree": {
|
|
52
|
+
"path": "tree.json",
|
|
53
|
+
"bytes": 214,
|
|
54
|
+
"sha256": "3c5d…"
|
|
55
|
+
},
|
|
51
56
|
"changes": [
|
|
52
57
|
{ "table": "main.population", "kind": "add_column", "column": "note", "breaking": false }
|
|
53
58
|
],
|
|
@@ -76,8 +81,9 @@ description: バージョン ID、version.json の項目、固めたカタログ
|
|
|
76
81
|
| `dataset` | must | カタログの隣の `dataset.json` のファイル名、大きさ、sha256。必須になる前に書かれたバージョンには無い |
|
|
77
82
|
| `ducklake` | must | DuckLake の形式、固めたスナップショット、親から足したスナップショットの範囲(最初と最後) |
|
|
78
83
|
| `files` | may | カタログの隣の `files.json` を書いたときの、そのファイル名、大きさ、sha256([files.json](#filesjson)) |
|
|
84
|
+
| `tree` | may | バージョンがほかのファイルを持つときの、カタログの隣の `tree.json` のファイル名、大きさ、sha256([tree.json](#treejson)) |
|
|
79
85
|
| `changes` | may | 親との列の違い。`breaking` は、親に向けて書いた SQL が失敗しうるか(列の削除・改名・作り直し) |
|
|
80
|
-
| `inputs` | may |
|
|
86
|
+
| `inputs` | may | 使った元のファイル。それぞれの取得元・取得日時・sha256 を書く。FDL はファイル自体を置かない。残したい書き手は、テーブルのアセットにする。`source_id` の付け方は書き手が決める |
|
|
81
87
|
| `annotations` | may | 形式が解釈しない情報。読む側(ホストやツール)の名前をキーにする |
|
|
82
88
|
|
|
83
89
|
読み手は、知らない項目を無視しなければなりません。
|
|
@@ -128,6 +134,71 @@ DuckLake を使わずに Parquet ファイルを読む読み手は、`deletes`
|
|
|
128
134
|
|
|
129
135
|
保持期間から外すとき、`files.json` はカタログと一緒に消します。
|
|
130
136
|
|
|
137
|
+
## tree.json
|
|
138
|
+
|
|
139
|
+
`tree.json` は、バージョンがテーブルのほかに持つファイル(README とそこに表示する画像など)をパスで並べた一覧です。Git の tree に当たります。パスごとにファイルの sha256 を持ち、ファイル自体はアセットとして `assets/<sha256>` に置きます。テーブルはここに入れません。テーブルの tree はカタログです。
|
|
140
|
+
|
|
141
|
+
```json tree.json
|
|
142
|
+
{
|
|
143
|
+
"entries": [
|
|
144
|
+
{ "path": "README.md", "sha256": "5e88…", "bytes": 3120 },
|
|
145
|
+
{ "path": "docs/images/towns.png", "sha256": "c9d2…", "bytes": 48211 }
|
|
146
|
+
]
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- `entries` に、ファイルのパス・sha256(小文字の 16 進)・大きさを、パスの順に並べる。パスは相対パスで `/` で区切り、空・`.`・`..` のセグメントを含まず、重複しない
|
|
151
|
+
- ファイルは書いたままの中身で置く。Markdown のファイルの中の相対リンクは、そのファイル自身のパスを基準に解決し、パーセントエンコーディングをデコードしてから `entries` で引く。GitHub が README のリンクをコミットの tree で解決するのと同じである。`entries` に無いパスへのリンクはリンク切れとして扱う
|
|
152
|
+
- 多くの読み手は `README.md` を最初に表示する。どのファイルをどこに表示するかは読み手が決める
|
|
153
|
+
- `dataset.json` の `description` は短いテキストのまま残す。tree を読まない読み手もこれを持ち、一覧にはこれを表示する
|
|
154
|
+
- 書き手は、ファイルを編集する場所(Git のリポジトリの中の YAML の隣など)に置き、書き手のツールが `tree.json` を書く。書き手が手で書くものではない
|
|
155
|
+
- `tree.json` はバージョンの一部で、そのバージョンの中では変わらない。保持期間から外すときはカタログと一緒に消す
|
|
156
|
+
|
|
157
|
+
## profiles/
|
|
158
|
+
|
|
159
|
+
profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約です。行数、列ごとの中身、先頭の行、図形の列を持つテーブルでは図形の範囲と見本を持ちます。読み手はこの小さなファイル 1 つで、カタログを開かずデータも読まずにテーブルを表示できます。ホストは検索の索引をこれから作れます。profile が持つのはデータから測った事実で、列が何を意味するかは書き手が `dataset.json` に書きます。`files.json` と同じくカタログとデータから作るもので、食い違うときはカタログとデータが正です。任意で、読み手は profile が無くても読めなければなりません。
|
|
160
|
+
|
|
161
|
+
テーブルごとの profile は `versions/<ID>/profiles/<schema>/<table>.json` に置きます。スキーマ名かテーブル名が空・`.`・`..` のとき、または `/` を含むときは置きません。ビューには置きません。
|
|
162
|
+
|
|
163
|
+
```json profiles/main/towns.json
|
|
164
|
+
{
|
|
165
|
+
"rows": 1741,
|
|
166
|
+
"columns": [
|
|
167
|
+
{ "name": "town_code", "type": "varchar", "null_count": 0, "distinct_count": 1741,
|
|
168
|
+
"values": [{ "value": "082201", "count": 1 }] },
|
|
169
|
+
{ "name": "prefecture", "type": "varchar", "null_count": 0, "distinct_count": 2,
|
|
170
|
+
"values": [{ "value": "茨城県", "count": 1200 }, { "value": "栃木県", "count": 541 }] },
|
|
171
|
+
{ "name": "population", "type": "int64", "null_count": 3, "distinct_count": 1650,
|
|
172
|
+
"min": 0, "max": 84211, "mean": 3120.5, "std": 4410.2, "q1": 420, "median": 1630, "q3": 3990,
|
|
173
|
+
"values": [{ "value": "0", "count": 12 }],
|
|
174
|
+
"histogram": [{ "start": 0, "end": 4210.55, "count": 1302 }] },
|
|
175
|
+
{ "name": "surveyed_on", "type": "date", "null_count": 0, "distinct_count": 1,
|
|
176
|
+
"min": "2025-10-01", "max": "2025-10-01", "span_days": 0,
|
|
177
|
+
"values": [{ "value": "2025-10-01", "count": 1741 }] },
|
|
178
|
+
{ "name": "coastal", "type": "boolean", "null_count": 0, "true_count": 210, "false_count": 1531 },
|
|
179
|
+
{ "name": "geom", "type": "geometry" }
|
|
180
|
+
],
|
|
181
|
+
"head": [{ "town_code": "082201", "prefecture": "茨城県", "population": 2210, "surveyed_on": "2025-10-01", "coastal": false }],
|
|
182
|
+
"geometry": {
|
|
183
|
+
"column": "geom",
|
|
184
|
+
"count": 1741,
|
|
185
|
+
"bbox": [139.69, 35.74, 140.85, 37.15],
|
|
186
|
+
"types": ["MULTIPOLYGON", "POLYGON"],
|
|
187
|
+
"sample": { "type": "FeatureCollection", "features": [] }
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
- `rows` はテーブルの行数。`columns` にはカタログの順にすべての列を並べ、`name` と `type`(DuckLake の型名)は `dataset.json` と同じにする
|
|
193
|
+
- 図形の列を除くすべての列が `null_count` を持つ。数値・テキスト・日付と時刻の列は `distinct_count` と `values` を持つ。大きなテーブルの `distinct_count` は推定値のことがある
|
|
194
|
+
- `values` は、値(テキスト)とその値を持つ行の数を、多い順、同数なら値の順に並べる。列が持つ異なる値が 1,000 以下なら全部を並べ、そのとき `distinct_count` は正確な数になる。読み手は、`values` の長さが `distinct_count` と等しいことで全部の一覧だと判定する。それより多い列は上位 10 件だけを並べる。ホストは全部の一覧を、地域コードや名前などの値で検索できる
|
|
195
|
+
- 数値の列は `min`・`max`・`mean`・`std`、四分位数の `q1`・`median`・`q3`、`min` から `max` までを等幅に区切った `histogram` を持つ。日付と時刻の列は `min` と `max` をテキストで持ち、日付とタイムスタンプは `span_days` も持つ。真偽値の列は `true_count` と `false_count` を持つ
|
|
196
|
+
- `head` は、テーブルが返す先頭の行を JSON のオブジェクトで持つ。図形の列と、値を JSON で表せない列は入れない
|
|
197
|
+
- `geometry` は、書き手が読めたときに、最初の図形の列を説明する。図形を持つ行の数、全体の `bbox`(列の座標で `[xmin, ymin, xmax, ymax]`)、含まれる図形の種類、地図を描くための、無作為に選んで簡略化した図形の GeoJSON `FeatureCollection` を持つ
|
|
198
|
+
- 書き手は計算できないキーを省いてよい。読み手は知らないキーを無視する
|
|
199
|
+
- 書き手は、データファイル(`files.json`)と列が親と同じテーブルには親の profile を使い回す。コミットで読むのは変わったテーブルだけになる
|
|
200
|
+
- profile はバージョンの一部で、そのバージョンの中では変わらない。保持期間から外すときはカタログと一緒に消す
|
|
201
|
+
|
|
131
202
|
## 固めたカタログ
|
|
132
203
|
|
|
133
204
|
`ducklake.duckdb` は、DuckDB のファイル形式の DuckLake カタログです。
|
|
@@ -189,6 +260,22 @@ DuckLake を使わずに Parquet ファイルを読む読み手は、`deletes`
|
|
|
189
260
|
- `annotations` という名前になる前のバージョンは、同じものを `extensions` に持つ。読み手は `extensions` を `annotations` として読む
|
|
190
261
|
- ライセンスや出典に書いたことは書き手の主張で、ホストは公開する前に確かめてよい
|
|
191
262
|
|
|
263
|
+
### アセット
|
|
264
|
+
|
|
265
|
+
テーブルは、報告書の PDF や施設の写真などのファイルを指せます。Git LFS が大きなファイルを指すのと同じ形で、行にはファイルの sha256 を持ち、ファイルはデータと同じリポジトリに置きます。
|
|
266
|
+
|
|
267
|
+
```json
|
|
268
|
+
{ "name": "sha256", "title": "PDF", "type": "varchar", "asset": true }
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
- `"asset": true` の列は、各行にファイルの sha256(小文字の 16 進)か null を持つ。型は `varchar`
|
|
272
|
+
- 各ファイルはルートの `assets/<sha256>` に置く([レイアウト](/ja/spec/layout#パス))。同じ中身は 1 回だけ置き、複数のバージョンで共有する
|
|
273
|
+
- ファイルの名前・大きさ・メディアタイプは、同じテーブルの列として持つ。列名は書き手が決める。読み手がファイルを取得する前に表示方法を判定できるよう、少なくともメディアタイプの列を持つのがよい
|
|
274
|
+
- ファイルを差し替えるときは、新しい中身を置き、その sha256 を行に入れる。古いバージョンは古い中身を指したまま残る
|
|
275
|
+
- 書き手は、ファイルのメディアタイプを `Content-Type` に付けてアップロードする。バージョンの行が持つアセットは、そのバージョンを書く前にすべてリポジトリに置く
|
|
276
|
+
- 読み手は、リポジトリを読んでいる場所の `<root>assets/<sha256>` でファイルを取得し、表示する前に sha256 を確認する。ファイルが無い行は、リンク切れとして表示する
|
|
277
|
+
- 提供元のサイトにあるファイルなど、リポジトリの外のファイルは、普通の列に URL で持つ。これはアセットではなく、FDL は管理しない
|
|
278
|
+
|
|
192
279
|
## ほかの形式のカタログ
|
|
193
280
|
|
|
194
281
|
1 つのバージョンが DuckLake の形式ごとにカタログを持ってよく、読み手は DuckDB を替えずに、開けるファイルを選べます。
|
|
@@ -17,7 +17,7 @@ description: チェックアウト、コミット、push。作業カタログ、
|
|
|
17
17
|
| --- | --- |
|
|
18
18
|
| チェックアウト | ブランチのバージョンのカタログから作業カタログを作り、そのバージョンを覚える。最初のバージョンの前は空のものを作る |
|
|
19
19
|
| コミット | 作業カタログの最後のスナップショットを新しいバージョンに固める。親は覚えておいたバージョン。中身を `dataset.json` で説明する |
|
|
20
|
-
| push | データファイルを確かめ、カタログ、`dataset.json
|
|
20
|
+
| push | データファイルを確かめ、カタログ、`dataset.json`・`files.json`・`tree.json`・profile、`version.json` の順にアップロードし、条件付きで ref を動かす |
|
|
21
21
|
|
|
22
22
|
チェックアウトでは、DuckLake の管理用の表を、固めたカタログから SQLite へそのまま写します。固めるときはその逆で、最後のスナップショットまでの行を残します。どちらもデータファイルは書き換えません。
|
|
23
23
|
|
|
@@ -32,15 +32,15 @@ description: チェックアウト、コミット、push。作業カタログ、
|
|
|
32
32
|
書き手は、親と同じ中身のバージョンを作らないようにするべきです。Git が親と同じ tree のコミットを作らないのと同じです。次のどちらかなら、親と同じ中身です。
|
|
33
33
|
|
|
34
34
|
- 最後のスナップショットが親のもの(`ducklake.snapshot_id`)と同じ
|
|
35
|
-
- 同じ表とビューがあり、どの表も列の名前と型が同じで、行が同じ(重複を数え、順番は問わない)。さらに `dataset.json` の sha256
|
|
35
|
+
- 同じ表とビューがあり、どの表も列の名前と型が同じで、行が同じ(重複を数え、順番は問わない)。さらに `dataset.json` と `tree.json` の sha256 が親と同じ(どちらのバージョンにも `tree.json` が無いときを含む)
|
|
36
36
|
|
|
37
37
|
同じ入力から作り直した表は新しいデータファイルに書かれるので、ファイルやカタログのバイトを比べても判定できません。書き手はまずファイルを比べ、ファイルが違う表だけ行を読みます。行を読めないときはバージョンを作ります。頼まれたときは、`git commit --allow-empty` と同じく、変更がなくても作ってかまいません。
|
|
38
38
|
|
|
39
39
|
## 書き込みの順番
|
|
40
40
|
|
|
41
|
-
1.
|
|
41
|
+
1. データファイル・アセット
|
|
42
42
|
2. `versions/<ID>/ducklake.duckdb`(と `catalogs/`)
|
|
43
|
-
3. `versions/<ID>/dataset.json
|
|
43
|
+
3. `versions/<ID>/dataset.json`・`versions/<ID>/files.json`・`versions/<ID>/tree.json`・`versions/<ID>/profiles/`
|
|
44
44
|
4. `versions/<ID>/version.json`
|
|
45
45
|
5. ref(条件付き)
|
|
46
46
|
|
|
@@ -53,6 +53,6 @@ description: チェックアウト、コミット、push。作業カタログ、
|
|
|
53
53
|
古い作業カタログからの push は、次の 2 つの確認で断られます。
|
|
54
54
|
|
|
55
55
|
1. いまブランチが指すバージョンが、新しいバージョンの `parents` に無い。ほかの人が先に push した
|
|
56
|
-
2.
|
|
56
|
+
2. カタログが参照するデータファイルか、`tree.json` が並べるファイルがリポジトリに無い。ホストは行が持つアセットも確認してよい。有効なバージョンから猶予期間より長く参照されなかったファイルは、書き手が見つけたあとでも消されていることがある
|
|
57
57
|
|
|
58
58
|
どちらの場合も、書き手はチェックアウトし直し、作業をやり直して、もう一度 push します。リポジトリを片付ける必要はありません。断られたバージョンはどの ref からも参照されていません。
|
|
@@ -44,13 +44,19 @@ Refused when the version is past retention.
|
|
|
44
44
|
## fdl commit
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty]
|
|
47
|
+
fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty] [--assets files/]
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
Freezes the working catalog into a new version whose parent is the version it was checked out at, uploads it, and moves the branch on condition. It prints the branch, the new version ID and its `seq`.
|
|
51
51
|
|
|
52
52
|
Every version is described by a `dataset.json` (see [Versions](/spec/versions#datasetjson)), read from `--dataset` or else from `dataset.json` or `dataset.yml` in the current directory. Tables described in `*.table.yml` (or `*.table.json`) files below that folder are added to it; hidden folders are skipped. The command checks it against the catalog and fills in the column types, row counts and catalog comments.
|
|
53
53
|
|
|
54
|
+
The command puts `README.md` beside the description and every file below `docs/` there (hidden ones left out) in the version's tree: it writes `tree.json` with their paths from that folder and uploads those the repository lacks to `assets/<sha256>`, as written (see [tree.json](/spec/versions#treejson)).
|
|
55
|
+
|
|
56
|
+
It also writes a profile of each table (see [profiles/](/spec/versions#profiles)), reading only the tables whose data files or columns changed since the parent. A table it cannot read gets none, and the commit goes on with a warning.
|
|
57
|
+
|
|
58
|
+
Columns marked `asset: true` hold the sha256 of files (see [Assets](/spec/versions#assets)). The command reads the values those columns hold and uploads the files the repository lacks from the `--assets` folder to `assets/<sha256>`, by their content: file names in the folder do not matter.
|
|
59
|
+
|
|
54
60
|
When the version would hold what its parent holds (see [When nothing changed](/spec/writing#when-nothing-changed)), it prints `Nothing to commit`, leaves the branch where it is and exits 0. A rebuild that writes the same rows to new files counts as unchanged. `--allow-empty` makes the version anyway. If the rows cannot be read to tell, it warns and makes the version.
|
|
55
61
|
|
|
56
62
|
Refused when:
|
|
@@ -59,8 +65,17 @@ Refused when:
|
|
|
59
65
|
- the branch has moved since the checkout. Check out again and redo the work
|
|
60
66
|
- the working catalog holds inlined rows
|
|
61
67
|
- a data file the catalog names is not in the repository
|
|
68
|
+
- an asset column is not `varchar`, holds a value that is not a sha256, or points at a file that is neither in the repository nor in `--assets`
|
|
62
69
|
- a data file is recorded with an absolute path outside the data directory
|
|
63
70
|
|
|
71
|
+
## fdl assets
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
fdl assets <folder> > files.csv
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Prints every file below the folder (hidden ones left out) as CSV, with `path`, `sha256`, `bytes` and `media_type`. Read it into the table that points at the files, for example with DuckDB's `read_csv`, mark its `sha256` column `asset: true`, and commit with `--assets <folder>`. The files are hashed once here; nothing reads them in SQL.
|
|
78
|
+
|
|
64
79
|
## fdl log
|
|
65
80
|
|
|
66
81
|
```bash
|
|
@@ -95,6 +110,8 @@ fdl withdraw <remote> <version>... [--yes]
|
|
|
95
110
|
|
|
96
111
|
Removes versions that hold data that must not be published, such as personal data published by mistake (see [Withdrawal](/spec/data-files#withdrawal)). First commit a version without the data, so that no branch points at an affected version. The command then deletes the tags that point at the versions, the data files their catalogs name that no kept version reads, and their catalogs, and puts `expired.json` with `"reason": "withdrawn"`. `version.json` stays.
|
|
97
112
|
|
|
113
|
+
Assets are not deleted yet: delete those that hold the data from `assets/` by hand.
|
|
114
|
+
|
|
98
115
|
Without `--yes` it only prints what it would delete. Files a kept version still reads are listed as kept; if they hold the data, withdraw that version too. Refused while a branch or a request points at one of the versions.
|
|
99
116
|
|
|
100
117
|
## fdl expire
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Data files
|
|
3
|
+
description: Rules for shared objects (data files and assets), when a shared object may be deleted, and how a version is taken out of retention.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Shared objects
|
|
7
|
+
|
|
8
|
+
Data files and assets are shared objects: written once, never overwritten, and reached by any number of versions, as blobs are in Git. A version reaches them this way:
|
|
9
|
+
|
|
10
|
+
| Object | Path | A version reaches it when |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| data file | `<data_dir><schema>/<table>/ducklake-<uuid>.parquet` | its catalog names it |
|
|
13
|
+
| asset | `assets/<sha256>` | a column its `dataset.json` marks as `asset` holds the sha256 in a row, or its `tree.json` lists it |
|
|
14
|
+
|
|
15
|
+
- A writer may place shared objects before making a version. Until a version reaches them, readers do not see them
|
|
16
|
+
- A writer that finds an object already there need not upload it again. It may still be deleted before the version is written, so a push whose version reaches a missing object is refused ([Writing](/spec/writing#when-a-push-is-refused))
|
|
17
|
+
|
|
18
|
+
### Data files
|
|
19
|
+
|
|
20
|
+
- Named as DuckLake names them. Delete files go in the same place
|
|
21
|
+
- Compacting small files (`ducklake_merge_adjacent_files`) is allowed at any time: it writes new files and deletes none
|
|
22
|
+
|
|
23
|
+
### Assets
|
|
24
|
+
|
|
25
|
+
- Named by the lower-case hex sha256 of the content, so the same content is stored once (see [Versions](/spec/versions#assets))
|
|
26
|
+
|
|
27
|
+
## When a shared object may be deleted
|
|
28
|
+
|
|
29
|
+
Only when both hold:
|
|
30
|
+
|
|
31
|
+
1. No live version reaches it. A live version is one without `expired.json`
|
|
32
|
+
2. It was placed longer ago than the grace period. The grace period protects objects a writer has placed but not yet made a version of
|
|
33
|
+
|
|
34
|
+
DuckLake's own cleanup (`ducklake_cleanup_old_files`, `ducklake_expire_snapshots`) sees only one catalog, so it must not be used to delete from a repository. Deleting is for a process that sees the whole repository.
|
|
35
|
+
|
|
36
|
+
## Past retention
|
|
37
|
+
|
|
38
|
+
A version is taken out of retention in this order:
|
|
39
|
+
|
|
40
|
+
1. Put `versions/<ID>/expired.json`
|
|
41
|
+
2. Delete the version's catalogs, `ducklake.duckdb` and `catalogs/`, and its `files.json` and `tree.json`
|
|
42
|
+
3. After the grace period, delete the shared objects that meet the conditions above
|
|
43
|
+
|
|
44
|
+
```json expired.json
|
|
45
|
+
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "retention" }
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- `version.json` stays, so the history still says the version was there and what it was, and the graph of parents stays whole
|
|
49
|
+
- A reader that sees `expired.json` treats the version as past retention and does not open its catalog, whatever the `reason`
|
|
50
|
+
- A version a ref points at must not be taken out
|
|
51
|
+
|
|
52
|
+
## Withdrawal
|
|
53
|
+
|
|
54
|
+
Withdrawal removes data that must not be published, such as personal data published by mistake. Unlike retention, it removes data from every version that holds it, live ones included, and does not wait for the grace period.
|
|
55
|
+
|
|
56
|
+
1. Make a new version without the data and move every branch that holds an affected version to it. This is a forward move: the new version's parent is the current one
|
|
57
|
+
2. Delete the tags that point at affected versions
|
|
58
|
+
3. Delete the shared objects that hold the data, at once, such as a data file with personal data or a screenshot showing it: those an affected version reaches and no version kept reaches. Every version that reaches such an object is an affected version
|
|
59
|
+
4. For every affected version, put `expired.json` with `"reason": "withdrawn"` and delete its catalogs
|
|
60
|
+
|
|
61
|
+
The shared objects go before the catalogs, so a withdrawal that stops half way can be run again: the catalogs still say which files hold the data.
|
|
62
|
+
|
|
63
|
+
```json expired.json
|
|
64
|
+
{ "expired_at": "2026-12-01T00:00:00Z", "reason": "withdrawn" }
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- `version.json` stays, as with retention. If the record itself holds the data (in `message` or `inputs`), it is deleted too, and the history shows a missing parent at that point
|
|
68
|
+
- Mirrors keep their own copies. A mirror that copies `expired.json` with `"reason": "withdrawn"` deletes the catalogs and the shared objects the origin deleted. The origin cannot force this; the host tells the mirrors it knows of
|