fdl-cli 0.21.0__tar.gz → 0.22.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.
Files changed (105) hide show
  1. fdl_cli-0.22.0/.github/workflows/test.yml +41 -0
  2. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CHANGELOG.md +29 -0
  3. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CLAUDE.md +1 -1
  4. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CONTRIBUTING.md +12 -4
  5. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/PKG-INFO +21 -6
  6. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/README.md +17 -2
  7. fdl_cli-0.22.0/SECURITY.md +7 -0
  8. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/blume.config.ts +1 -1
  9. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/getting-started.md +2 -0
  10. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/index.md +22 -1
  11. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/getting-started.md +2 -0
  12. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/index.md +21 -0
  13. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/cli.md +47 -7
  14. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/python.md +13 -2
  15. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/http.md +2 -0
  16. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/layout.md +2 -0
  17. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/reading.md +11 -0
  18. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/versions.md +40 -6
  19. fdl_cli-0.22.0/docs/ja/stability.md +40 -0
  20. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/cli.md +47 -7
  21. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/python.md +13 -2
  22. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/http.md +2 -0
  23. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/layout.md +2 -0
  24. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/reading.md +11 -0
  25. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/versions.md +40 -6
  26. fdl_cli-0.22.0/docs/stability.md +40 -0
  27. fdl_cli-0.22.0/public/CNAME +1 -0
  28. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/pyproject.toml +4 -4
  29. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/catalog.py +198 -6
  30. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/cli.py +217 -18
  31. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/dataset.py +23 -6
  32. fdl_cli-0.22.0/src/fdl/diff.py +293 -0
  33. fdl_cli-0.22.0/src/fdl/lineage.py +127 -0
  34. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/repo.py +59 -5
  35. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/stores.py +58 -2
  36. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/version.py +9 -3
  37. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_cli.py +56 -0
  38. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_dataset.py +81 -3
  39. fdl_cli-0.22.0/tests/test_http.py +354 -0
  40. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_repo.py +110 -3
  41. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/uv.lock +2 -2
  42. fdl_cli-0.21.0/public/CNAME +0 -1
  43. fdl_cli-0.21.0/tests/test_http.py +0 -183
  44. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/docs.yml +0 -0
  45. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/publish.yml +0 -0
  46. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/release.yml +0 -0
  47. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.gitignore +0 -0
  48. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.node-version +0 -0
  49. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.python-version +0 -0
  50. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/LICENSE +0 -0
  51. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/meta.ts +0 -0
  52. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/repositories.md +0 -0
  53. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/versions-and-refs.md +0 -0
  54. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/working-catalogs.md +0 -0
  55. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/building-a-host.md +0 -0
  56. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/meta.ts +0 -0
  57. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/mirrors.md +0 -0
  58. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/public-and-private.md +0 -0
  59. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/reading-without-duckdb.md +0 -0
  60. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/serving-over-http.md +0 -0
  61. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/stores.md +0 -0
  62. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/ducklake-formats.md +0 -0
  63. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/from-write-to-read.md +0 -0
  64. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/inside-a-repository.md +0 -0
  65. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/meta.ts +0 -0
  66. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/meta.ts +0 -0
  67. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/repositories.md +0 -0
  68. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/versions-and-refs.md +0 -0
  69. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/working-catalogs.md +0 -0
  70. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/building-a-host.md +0 -0
  71. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/meta.ts +0 -0
  72. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/mirrors.md +0 -0
  73. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/public-and-private.md +0 -0
  74. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
  75. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/serving-over-http.md +0 -0
  76. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/stores.md +0 -0
  77. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/ducklake-formats.md +0 -0
  78. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/from-write-to-read.md +0 -0
  79. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/inside-a-repository.md +0 -0
  80. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/meta.ts +0 -0
  81. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/meta.ts +0 -0
  82. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/data-files.md +0 -0
  83. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/index.md +0 -0
  84. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/meta.ts +0 -0
  85. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/refs.md +0 -0
  86. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/writing.md +0 -0
  87. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/meta.ts +0 -0
  88. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/data-files.md +0 -0
  89. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/index.md +0 -0
  90. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/meta.ts +0 -0
  91. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/refs.md +0 -0
  92. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/writing.md +0 -0
  93. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/package-lock.json +0 -0
  94. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/package.json +0 -0
  95. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/__init__.py +0 -0
  96. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/layout.py +0 -0
  97. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/objects.py +0 -0
  98. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/profiles.py +0 -0
  99. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/py.typed +0 -0
  100. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/refs.py +0 -0
  101. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/store.py +0 -0
  102. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/http_repo.py +0 -0
  103. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_objects.py +0 -0
  104. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_profiles.py +0 -0
  105. {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_stores.py +0 -0
@@ -0,0 +1,41 @@
1
+ name: Test
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches: [main]
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ pytest:
13
+ runs-on: ubuntu-latest
14
+ strategy:
15
+ fail-fast: false
16
+ matrix:
17
+ # The oldest Python the package supports, and the newest.
18
+ python: ["3.10", "3.13"]
19
+ # Catalogs written by either have to read on the other.
20
+ duckdb: ["1.5", "2.0"]
21
+ exclude:
22
+ # DuckDB 2.0 needs Python 3.11 or later.
23
+ - python: "3.10"
24
+ duckdb: "2.0"
25
+ steps:
26
+ - uses: actions/checkout@v5
27
+ - uses: astral-sh/setup-uv@v7
28
+ - run: uv sync --python ${{ matrix.python }}
29
+ - run: uv pip install --python .venv "duckdb~=${{ matrix.duckdb }}.0"
30
+ - run: uv run --no-sync pytest -q
31
+
32
+ docs:
33
+ runs-on: ubuntu-latest
34
+ steps:
35
+ - uses: actions/checkout@v5
36
+ - uses: actions/setup-node@v5
37
+ with:
38
+ node-version-file: .node-version
39
+ cache: npm
40
+ - run: npm ci
41
+ - run: npm run check
@@ -1,6 +1,35 @@
1
1
  # CHANGELOG
2
2
 
3
3
 
4
+ ## v0.22.0 (2026-11-10)
5
+
6
+ ### Features
7
+
8
+ - Checkout --storage writes new data files to the repository's storage; keep unknown dataset.json
9
+ keys ([#47](https://github.com/queria-io/fdl/pull/47),
10
+ [`3df2120`](https://github.com/queria-io/fdl/commit/3df212081c9cf79ebfab2582981171462a88fa96))
11
+
12
+ - Diff, show and status; DuckDB 2.0; keep the token on its origin; check catalogs on checkout; docs
13
+ for a beta ([#44](https://github.com/queria-io/fdl/pull/44),
14
+ [`13b83d5`](https://github.com/queria-io/fdl/commit/13b83d59f0ad936895e312b46fecf755c24b6138))
15
+
16
+ - Record what changed since the parent in version.json
17
+ ([#46](https://github.com/queria-io/fdl/pull/46),
18
+ [`eee1ec3`](https://github.com/queria-io/fdl/commit/eee1ec3099bceea5938c68c4d656182512ea4718))
19
+
20
+ - **dataset**: Read depends_on from a table's SQL ([#45](https://github.com/queria-io/fdl/pull/45),
21
+ [`75003ba`](https://github.com/queria-io/fdl/commit/75003ba5d97efed5868b0297a9e28953b69b13f7))
22
+
23
+
24
+ ## v0.21.1 (2026-11-08)
25
+
26
+ ### Bug Fixes
27
+
28
+ - Retry a data file upload when storage answers 5xx or 429
29
+ ([#43](https://github.com/queria-io/fdl/pull/43),
30
+ [`2fcaaf5`](https://github.com/queria-io/fdl/commit/2fcaaf56953237a4c7ae6c042d1b607e09752749))
31
+
32
+
4
33
  ## v0.21.0 (2026-11-06)
5
34
 
6
35
  ### Bug Fixes
@@ -8,7 +8,7 @@ uv run fdl --help
8
8
  uv run pytest
9
9
  ```
10
10
 
11
- Docs (Blume, served at https://fdl.flo8s.com):
11
+ Docs (Blume, served at https://fdl.queria.io):
12
12
 
13
13
  ```bash
14
14
  npm ci
@@ -18,18 +18,26 @@ uv run pytest
18
18
  ## Project structure
19
19
 
20
20
  ```
21
- docs/spec.md — the format
21
+ docs/ — the documentation site (Blume); docs/spec/ is the specification, docs/ja/ the Japanese mirror
22
22
  src/fdl/
23
23
  ├── layout.py — where each file of a repository sits
24
24
  ├── version.py — version.json and version IDs
25
25
  ├── refs.py — reading refs and moving them on condition
26
26
  ├── catalog.py — DuckLake catalogs in SQLite and DuckDB, and the conversion
27
- ├── repo.py — init, checkout, commit, push, log, expire
27
+ ├── dataset.py — dataset.json: reading the description and checking it against the catalog
28
+ ├── objects.py — assets and tree.json
29
+ ├── profiles.py — the profile of each table
30
+ ├── repo.py — init, checkout, commit, push, log, expire, withdraw
28
31
  ├── store.py — what a store has to provide
29
- ├── stores.py — a folder and S3 as stores
32
+ ├── stores.py — a folder, S3 and a host over HTTP as stores
30
33
  └── cli.py — the fdl command
34
+ tests/ — pytest; tests/http_repo.py is a small host over HTTP for the tests
31
35
  ```
32
36
 
37
+ Change the specification first, then the code. Every page in `docs/` has a Japanese counterpart under `docs/ja/`; change both in the same pull request. Check the docs with `npm ci && npm run check`.
38
+
39
+ Report a vulnerability privately, as [SECURITY.md](SECURITY.md) says.
40
+
33
41
  ## Commit conventions
34
42
 
35
43
  Follow [Conventional Commits](https://www.conventionalcommits.org/ja/v1.0.0/). Commit messages are parsed by [python-semantic-release](https://python-semantic-release.readthedocs.io/) to determine version bumps and generate the CHANGELOG automatically.
@@ -49,7 +57,7 @@ Do not manually edit the version in pyproject.toml or modify CHANGELOG.md — th
49
57
 
50
58
  ## Documentation
51
59
 
52
- Documentation is built with [Zensical](https://zensical.com/) and deployed to [fdl.flo8s.com](https://fdl.flo8s.com/).
60
+ Documentation is built with [Zensical](https://zensical.com/) and deployed to [fdl.queria.io](https://fdl.queria.io/).
53
61
 
54
62
  To preview locally:
55
63
 
@@ -1,16 +1,16 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fdl-cli
3
- Version: 0.21.0
3
+ Version: 0.22.0
4
4
  Summary: Versions of a DuckLake catalog on object storage, kept the way Git keeps commits
5
- Project-URL: Homepage, https://fdl.flo8s.com/
6
- Project-URL: Documentation, https://fdl.flo8s.com/
5
+ Project-URL: Homepage, https://fdl.queria.io/
6
+ Project-URL: Documentation, https://fdl.queria.io/
7
7
  Project-URL: Repository, https://github.com/queria-io/fdl
8
8
  Project-URL: Changelog, https://github.com/queria-io/fdl/blob/main/CHANGELOG.md
9
9
  Author: flo8s
10
10
  License-Expression: MIT
11
11
  License-File: LICENSE
12
12
  Requires-Python: >=3.10
13
- Requires-Dist: duckdb<2.0,>=1.5.2
13
+ Requires-Dist: duckdb<3.0,>=1.5.2
14
14
  Requires-Dist: pyyaml>=6.0
15
15
  Requires-Dist: tomli>=1.1; python_version < '3.11'
16
16
  Requires-Dist: typer>=0.15
@@ -39,7 +39,7 @@ FDL is a storage layout and a tool for it. Each version is a frozen catalog with
39
39
  data/main/towns/ducklake-….parquet
40
40
  ```
41
41
 
42
- The documentation and the specification are at [fdl.flo8s.com](https://fdl.flo8s.com).
42
+ The documentation and the specification are at [fdl.queria.io](https://fdl.queria.io).
43
43
 
44
44
  ## Quick start
45
45
 
@@ -52,6 +52,8 @@ fdl checkout s3://my-bucket/towns/ work/lake.sqlite
52
52
 
53
53
  The package is `fdl-cli` on PyPI. It installs the `fdl` command and the `fdl` Python package (`import fdl`).
54
54
 
55
+ `fdl init` makes the repository in the store itself, as `git init --bare` does on a server. Your own copy to write to is the working catalog that `checkout` makes, a SQLite file.
56
+
55
57
  Write to the working catalog with DuckDB, attached the way `checkout` prints:
56
58
 
57
59
  ```sql
@@ -64,6 +66,13 @@ CREATE TABLE lake.main.towns AS SELECT * FROM 'towns.csv';
64
66
 
65
67
  Rows have to go to Parquet, not into the catalog (`DATA_INLINING_ROW_LIMIT 0`): a version is read over HTTP, and inlined rows would not be in it.
66
68
 
69
+ Describe what the version holds in `dataset.yml`, next to where you run `fdl commit`. Only `name` and `title` are required; `fdl commit` fills in each table's columns and row count from the catalog:
70
+
71
+ ```yaml
72
+ name: towns
73
+ title: Towns
74
+ ```
75
+
67
76
  Then make a version and move `main` to it:
68
77
 
69
78
  ```bash
@@ -93,8 +102,14 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
93
102
  | `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
94
103
  | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version and push it |
95
104
  | `fdl log <remote>` | List versions from `main` back to the first |
96
- | `fdl url <remote>` | Print the catalog URL of the version `main` holds |
105
+ | `fdl status <working>` | What the working catalog changed since the checkout |
106
+ | `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
107
+ | `fdl show <remote> [version]` | A version's record, its tables and its changes |
108
+ | `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
109
+ | `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
97
110
  | `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
111
+ | `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
112
+ | `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
98
113
 
99
114
  A push that is not built on what `main` holds now is refused: check out again and redo the work.
100
115
 
@@ -19,7 +19,7 @@ FDL is a storage layout and a tool for it. Each version is a frozen catalog with
19
19
  data/main/towns/ducklake-….parquet
20
20
  ```
21
21
 
22
- The documentation and the specification are at [fdl.flo8s.com](https://fdl.flo8s.com).
22
+ The documentation and the specification are at [fdl.queria.io](https://fdl.queria.io).
23
23
 
24
24
  ## Quick start
25
25
 
@@ -32,6 +32,8 @@ fdl checkout s3://my-bucket/towns/ work/lake.sqlite
32
32
 
33
33
  The package is `fdl-cli` on PyPI. It installs the `fdl` command and the `fdl` Python package (`import fdl`).
34
34
 
35
+ `fdl init` makes the repository in the store itself, as `git init --bare` does on a server. Your own copy to write to is the working catalog that `checkout` makes, a SQLite file.
36
+
35
37
  Write to the working catalog with DuckDB, attached the way `checkout` prints:
36
38
 
37
39
  ```sql
@@ -44,6 +46,13 @@ CREATE TABLE lake.main.towns AS SELECT * FROM 'towns.csv';
44
46
 
45
47
  Rows have to go to Parquet, not into the catalog (`DATA_INLINING_ROW_LIMIT 0`): a version is read over HTTP, and inlined rows would not be in it.
46
48
 
49
+ Describe what the version holds in `dataset.yml`, next to where you run `fdl commit`. Only `name` and `title` are required; `fdl commit` fills in each table's columns and row count from the catalog:
50
+
51
+ ```yaml
52
+ name: towns
53
+ title: Towns
54
+ ```
55
+
47
56
  Then make a version and move `main` to it:
48
57
 
49
58
  ```bash
@@ -73,8 +82,14 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
73
82
  | `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
74
83
  | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version and push it |
75
84
  | `fdl log <remote>` | List versions from `main` back to the first |
76
- | `fdl url <remote>` | Print the catalog URL of the version `main` holds |
85
+ | `fdl status <working>` | What the working catalog changed since the checkout |
86
+ | `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
87
+ | `fdl show <remote> [version]` | A version's record, its tables and its changes |
88
+ | `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
89
+ | `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
77
90
  | `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
91
+ | `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
92
+ | `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
78
93
 
79
94
  A push that is not built on what `main` holds now is refused: check out again and redo the work.
80
95
 
@@ -0,0 +1,7 @@
1
+ # Security
2
+
3
+ Report a vulnerability in fdl or in the FDL specification privately, through GitHub's [private vulnerability reporting](https://github.com/queria-io/fdl/security/advisories/new). Do not open a public issue for it.
4
+
5
+ Say what is affected (the command, the part of the specification, the version of fdl-cli), how to reproduce it, and what an attacker gains. We reply within a week.
6
+
7
+ Fixes go out in a patch release of fdl-cli, and the advisory is published once the release is on PyPI.
@@ -7,7 +7,7 @@ export default defineConfig({
7
7
  accent: "#673ab7",
8
8
  },
9
9
  deployment: {
10
- site: "https://fdl.flo8s.com",
10
+ site: "https://fdl.queria.io",
11
11
  },
12
12
  content: {
13
13
  root: "docs",
@@ -29,6 +29,8 @@ towns/
29
29
 
30
30
  `HEAD` names the default branch, `main`. The branch itself does not exist yet: there is no version for it to point at.
31
31
 
32
+ `fdl init` makes the repository where readers will find it, as `git init --bare` does on a server. Your own place to write is the working catalog, made next.
33
+
32
34
  ## Check out a working catalog
33
35
 
34
36
  You never write to the repository directly. You write to a working catalog, a DuckLake catalog in a SQLite file on your own disk, and turn it into a version when you are done.
@@ -32,7 +32,27 @@ FDL is meant for data that is published, read by many and written by few:
32
32
 
33
33
  It is not a transactional database. Writers do not merge rows. Two people who push at once are settled by the store: the first push wins and the second is refused and has to build again on the new version.
34
34
 
35
- ## How the documentation is organised
35
+ ## FDL and Git
36
+
37
+ FDL keeps a catalog's versions the way Git keeps a project's commits. If you know Git, most of FDL maps onto it:
38
+
39
+ | Git | FDL |
40
+ | --- | --- |
41
+ | A bare repository on a server | A repository: a prefix of a bucket, or a folder |
42
+ | Commit | Version (`versions/<ID>/version.json`) |
43
+ | Tree | The frozen catalog (`ducklake.duckdb`) |
44
+ | Blob | Data file (Parquet), asset |
45
+ | Branch, tag, `HEAD` | `refs/heads/`, `refs/tags/`, `HEAD` |
46
+ | Working tree | Working catalog (SQLite on your disk) |
47
+ | `git init --bare` | `fdl init` |
48
+ | `git commit` and `git push` | `fdl commit` |
49
+ | `git log`, `git tag` | `fdl log`, `fdl tag` |
50
+
51
+ FDL does not merge, so a version has one parent. [From write to read](/internals/from-write-to-read) follows the files through a commit, step by step.
52
+
53
+ FDL is in beta. [Stability](/stability) says what stays the same across releases.
54
+
55
+ ## How the documentation is organized
36
56
 
37
57
  - [Getting started](/getting-started) makes a repository, writes a first version and reads it back
38
58
  - [Concepts](/concepts/repositories) explains repositories, versions, refs and working catalogs
@@ -40,6 +60,7 @@ It is not a transactional database. Writers do not merge rows. Two people who pu
40
60
  - [Guides](/guides/stores) cover stores, serving over HTTP, mirrors and building a host
41
61
  - The [specification](/spec) is the normative description of the format. Tools are written against it
42
62
  - The [reference](/reference/cli) lists the commands and the Python API
63
+ - [Stability](/stability) says what a repository written today can rely on
43
64
 
44
65
  The `fdl` command and the `fdl` Python package are the reference implementation. They are published on PyPI as `fdl-cli` under the MIT license.
45
66
 
@@ -29,6 +29,8 @@ towns/
29
29
 
30
30
  `HEAD` は既定のブランチ `main` を指します。ブランチそのものはまだありません。指す先のバージョンがないためです。
31
31
 
32
+ `fdl init` は、サーバーで `git init --bare` を打つのと同じく、読み手が読む場所にリポジトリを作ります。手元で書く場所は、次に作る作業カタログです。
33
+
32
34
  ## 作業カタログをチェックアウトする
33
35
 
34
36
  リポジトリには直接書き込みません。自分のディスクにある SQLite ファイルの DuckLake カタログ(作業カタログ)に書き、書き終えたらそれをバージョンにします。
@@ -32,6 +32,26 @@ FDL は、公開して多くの人が読み、少ない人が書くデータに
32
32
 
33
33
  FDL はトランザクションのためのデータベースではありません。書き手どうしで行をマージしません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られて、新しいバージョンの上に作り直します。
34
34
 
35
+ ## FDL と Git
36
+
37
+ FDL は、Git がプロジェクトのコミットを残すのと同じ形で、カタログのバージョンを残します。Git を知っていれば、FDL のほとんどは次のように対応します。
38
+
39
+ | Git | FDL |
40
+ | --- | --- |
41
+ | サーバー上の bare リポジトリ | リポジトリ(バケットのプレフィックス、またはフォルダ) |
42
+ | コミット | バージョン(`versions/<ID>/version.json`) |
43
+ | ツリー | 固めたカタログ(`ducklake.duckdb`) |
44
+ | ブロブ | データファイル(Parquet)、アセット |
45
+ | ブランチ・タグ・`HEAD` | `refs/heads/`・`refs/tags/`・`HEAD` |
46
+ | 作業ツリー | 作業カタログ(手元の SQLite) |
47
+ | `git init --bare` | `fdl init` |
48
+ | `git commit` と `git push` | `fdl commit` |
49
+ | `git log`・`git tag` | `fdl log`・`fdl tag` |
50
+
51
+ FDL はマージをしないので、バージョンの親は 1 つです。[書いてから読まれるまで](/ja/internals/from-write-to-read)で、コミットのときにファイルがどう動くかを順に追えます。
52
+
53
+ FDL はベータです。リリースをまたいで変わらないものは[安定性](/ja/stability)に書いています。
54
+
35
55
  ## ドキュメントの構成
36
56
 
37
57
  - [はじめかた](/ja/getting-started): リポジトリを作り、最初のバージョンを書いて読み返します
@@ -40,6 +60,7 @@ FDL はトランザクションのためのデータベースではありませ
40
60
  - [ガイド](/ja/guides/stores): 置き場、HTTP での配信、ミラー、ホストの作り方を扱います
41
61
  - [仕様](/ja/spec): 形式の規範となる説明です。ツールは仕様に合わせて作ります
42
62
  - [リファレンス](/ja/reference/cli): コマンドと Python API の一覧です
63
+ - [安定性](/ja/stability): 今書いたリポジトリが何を前提にできるかを書いています
43
64
 
44
65
  `fdl` コマンドと `fdl` Python パッケージが参照実装です。PyPI に `fdl-cli` として MIT ライセンスで公開しています。
45
66
 
@@ -7,7 +7,7 @@ description: fdl のコマンド、オプション、断られるとき。
7
7
 
8
8
  ## HTTP のトークン
9
9
 
10
- fdl はトークンを保存せず、ログインのコマンドもありません。HTTP のリポジトリには、次の順に見つけたトークンを `Authorization: Bearer` で送ります。
10
+ fdl はトークンを保存せず、ログインのコマンドもありません。HTTP のリポジトリは、手元のマシン(`localhost`)を除いて `https` でなければなりません。fdl はトークンをリポジトリと同じオリジンにだけ送り、別のオリジンへのリダイレクトの後には送りません。トークンは次の順に見つけたものを `Authorization: Bearer` で送ります。
11
11
 
12
12
  1. `FDL_TOKEN` があればそれ(CI 向け)
13
13
  2. 無ければ、fdl の設定でリポジトリの URL に設定した credential helper が答えたもの。helper が無ければトークンを送りません
@@ -32,14 +32,16 @@ fdl init <remote> [--data-dir data/]
32
32
  ## fdl checkout
33
33
 
34
34
  ```bash
35
- fdl checkout <remote> <working.sqlite> [--ref refs/heads/main]
35
+ fdl checkout <remote> <working.sqlite> [--ref refs/heads/main] [--storage s3://bucket/prefix/]
36
36
  ```
37
37
 
38
38
  ブランチが指すバージョンのカタログから作業カタログ(SQLite の DuckLake)を作ります。最初のバージョンの前は空のものを作ります。隣の `<working.sqlite>.fdl.json` に、リポジトリ、ブランチ、元のバージョンを記録します。書くときの `ATTACH` 文を表示します。
39
39
 
40
- HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/` に書かれ、コミットでアップロードされます。リポジトリに既にあるファイルは、その場所から HTTP で読みます。
40
+ HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/` に書かれ、コミットでアップロードされます。リポジトリに既にあるファイルは、その場所から HTTP で読みます。コミットはアップロードを終えると、新しいバージョンから作業カタログを作り直して手元の写しを削除するので、このフォルダにはまだコミットしていないファイルだけが残ります。
41
41
 
42
- バージョンの保持期間が過ぎていると断られます。
42
+ `--storage` を付けると、作業カタログはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir` の下に直接書かれるので、コミットでアップロードするものはありません。鍵は `AWS_*` の環境変数(R2 などの S3 互換ストレージは `AWS_ENDPOINT_URL`)か、自分で作った DuckDB の secret から取ります。作業カタログに書くビルドにも同じ鍵が要ります。
43
+
44
+ バージョンの保持期間が過ぎているとき、カタログの sha256 が `version.json` の記録と違うとき、カタログがデータフォルダの外のデータファイルを指しているときは断られます。
43
45
 
44
46
  ## fdl commit
45
47
 
@@ -61,7 +63,7 @@ fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.
61
63
 
62
64
  次のときは断られます。
63
65
 
64
- - `dataset.json` が無いとき、カタログに無い表や列を説明しているとき、形式が決めていないキーがあるとき
66
+ - `dataset.json` が無いとき、カタログに無い表や列を説明しているとき。形式が決めていないキーは、警告を出してそのまま残します
65
67
  - チェックアウトのあとにブランチが動いたとき。チェックアウトし直して作業をやり直す
66
68
  - 作業カタログが行をカタログの中に持っているとき
67
69
  - カタログが参照するデータファイルがリポジトリに無いとき
@@ -84,13 +86,51 @@ fdl log <remote> [--ref HEAD]
84
86
 
85
87
  ref が指すバージョンから最初のバージョンまで、最初の親をたどって並べます。`seq`、ID、時刻、作者、メッセージを表示します。保持期間を過ぎたバージョンには `(expired)` が付きます。
86
88
 
89
+ ## fdl status
90
+
91
+ ```bash
92
+ fdl status <working.sqlite> [--json]
93
+ ```
94
+
95
+ 作業カタログが checkout してから何を変えたかを、`fdl diff` と同じ区分で表示します。元のバージョンと同じ内容なら `Nothing to commit` と表示します。`dataset.json` の文言はコミットまで比べません。
96
+
97
+ ## fdl diff
98
+
99
+ ```bash
100
+ fdl diff <remote> [<version>] [--against <version>] [--json]
101
+ ```
102
+
103
+ バージョン(既定は `HEAD` が指すもの)が親から、または `--against` で指定したバージョンから何を変えたかを表示します。バージョンはバージョン ID か ref で指定します。1 行が 1 つの変更です。
104
+
105
+ ```
106
+ + table main.roads
107
+ - table main.old_towns
108
+ ~ rows main.towns: 1,741 -> 1,802
109
+ + column main.towns.note
110
+ - column main.towns.area (breaking)
111
+ ~ column main.towns.name -> town (breaking)
112
+ ~ column main.towns.id: int32 -> int64
113
+ ~ data main.towns
114
+ ~ description main.towns.population
115
+ ```
116
+
117
+ 親と比べるときは、バージョンの `diff` から取ります([diff](/ja/spec/versions#diff))。それ以外のときや `diff` のないバージョンでは、行数を `dataset.json` から、データファイルを `files.json` から取り、列は名前で比べます。そのため列名の変更は見分けられません。`~ data` は、行が同じでもテーブルのデータファイルが変わったことを示します。`--json` を付けると、同じ内容を `tables`(`added`・`dropped`)・`rows`・`columns`・`data`・`descriptions` を持つオブジェクトで表示します。
118
+
119
+ ## fdl show
120
+
121
+ ```bash
122
+ fdl show <remote> [<version>] [--json]
123
+ ```
124
+
125
+ バージョンの番号・ID・親・作者・時刻・メッセージと、テーブルとその行数、親からの変更を表示します。
126
+
87
127
  ## fdl url
88
128
 
89
129
  ```bash
90
- fdl url <remote> [--ref HEAD]
130
+ fdl url <remote> [--ref HEAD] [--attach] [--alias lake]
91
131
  ```
92
132
 
93
- ref が指すバージョンのカタログの URL を表示します。読み取り専用で `ATTACH` するのに使います。保持期間を過ぎたか取り下げたバージョンは、カタログがまだ配られていても断ります。
133
+ ref が指すバージョンのカタログの URL を表示します。読み取り専用で `ATTACH` するのに使います。`--attach` を付けると、データパス付きの `ATTACH` 文をそのまま表示します(トークンのある HTTP のリポジトリでは、その前に `CREATE SECRET` も表示します)。保持期間を過ぎたか取り下げたバージョンは、カタログがまだ配られていても断ります。
94
134
 
95
135
  ## fdl tag
96
136
 
@@ -15,6 +15,7 @@ for version in repo.log(store):
15
15
  | モジュール | 中身 |
16
16
  | --- | --- |
17
17
  | `fdl.repo` | 操作: `init`、`checkout`、`commit`、`push`、`log`、`expire`、`prune` |
18
+ | `fdl.diff` | 2 つのバージョンの違い(`diff.versions`)と作業カタログの変更(`diff.working`) |
18
19
  | `fdl.refs` | ref を読み、条件付きで動かす |
19
20
  | `fdl.version` | `Version`(`version.json` の記録)と新しい ID |
20
21
  | `fdl.catalog` | DuckDB と SQLite の DuckLake カタログと、その間の写し |
@@ -44,10 +45,10 @@ repo.init(store, *, data_dir="data/") -> Config
44
45
  リポジトリを作ります。既にあればそのままにして、設定を返します。
45
46
 
46
47
  ```python
47
- repo.checkout(store, working, *, ref="HEAD") -> Version | None
48
+ repo.checkout(store, working, *, ref="HEAD", local_data=None, version=None) -> Version | None
48
49
  ```
49
50
 
50
- `ref` が指すバージョンから、`working` に作業カタログを作ります。そのバージョンを返し、最初のバージョンの前は `None` を返します。
51
+ `ref` が指すバージョン、または `version` を渡したときはそのバージョンから、`working` に作業カタログを作ります。そのバージョンを返し、最初のバージョンの前は `None` を返します。HTTP の置き場では、新しいデータファイルを書くフォルダ `local_data` が要ります。カタログの sha256 が `version.json` の記録と違うときと、カタログがデータフォルダの外のデータファイルを指しているときは断ります。
51
52
 
52
53
  ```python
53
54
  repo.commit(working, out_dir, *, parent, data_path, author, message, inputs=(), annotations=None, dataset=None) -> Version
@@ -109,6 +110,16 @@ repo.withdraw(store, version_ids, *, plan=None) -> Withdrawal
109
110
 
110
111
  公開してはいけないデータを持つバージョンを取り下げます。`plan_withdrawal` は何も変えずに、消すタグ、消すデータファイル、残すバージョンが読むので残すファイルを返します。`withdraw` はタグ、データファイル、カタログの順に消します。ブランチかリクエストが該当するバージョンを指しているあいだは、どちらも `RepoError` を出します。
111
112
 
113
+ ## fdl.diff
114
+
115
+ ```python
116
+ diff.versions(store, old, new) -> dict
117
+ diff.working(working, base) -> dict
118
+ diff.lines(result) -> list[str]
119
+ ```
120
+
121
+ `versions` は 2 つのバージョンを、古い方が親なら新しい方の `diff` から、それ以外は `dataset.json`・`files.json` から比べます(最初のバージョンの前は `old` を `None` にします)。`working` は作業カタログを、checkout したときのバージョン `base` と比べます。どちらも `tables`(`added`・`dropped`)・`rows`・`columns`・`data`・`descriptions` を返し、`fdl diff --json` と同じ形です。`lines` は `fdl diff` が表示する行を返します。
122
+
112
123
  ## fdl.refs
113
124
 
114
125
  ```python
@@ -68,3 +68,5 @@ DuckDB は HTTP の URL にデータファイルを書けないので、こう
68
68
  - 新しいファイルは書き手のマシンのフォルダ(作業カタログのデータパス)に書く
69
69
 
70
70
  コミットで、リポジトリの `data_dir` の下を指す参照を相対に戻します。新しいファイルは初めから相対です。push では、リポジトリに無い新しいファイルを、カタログより先にアップロードします。
71
+
72
+ リポジトリのストレージの鍵を持つ書き手は、代わりに、ストレージでの `data_dir` の場所を作業カタログのデータパスにしてもかまいません。新しいファイルは作られたときにリポジトリに書かれ、push でアップロードするものはありません。ref を動かすときにホストが確認するのは同じです。
@@ -37,6 +37,8 @@ description: リポジトリのファイル、そのパス、fdl.json の中身
37
37
 
38
38
  ルートにほかの名前のファイルがあってもかまいません。読み手はそれを無視しなければなりません。
39
39
 
40
+ リポジトリのルートを、別のリポジトリのルートの下に置いてはいけません。外側のリポジトリで共有オブジェクトを削除するとき、内側のファイルをどのバージョンからも参照されていないオブジェクトとみなして削除してしまいます。
41
+
40
42
  ## fdl.json
41
43
 
42
44
  ```json
@@ -35,6 +35,17 @@ ssh-keygen -Y verify -f allowed_signers -I alice@example.org -n fdl \
35
35
 
36
36
  カタログの `data_path` は、書き手が公開したデータフォルダの絶対 URL です。読み手は `DATA_PATH '<root><data_dir>'` と `OVERRIDE_DATA_PATH true` を渡さなければなりません。`<root>` は、読み手がリポジトリを読んでいる場所です。こうすれば、元でもミラーでも同じ文で読め、別のホストに写したリポジトリもカタログを変えずに読めます。
37
37
 
38
+ ## カタログの確認
39
+
40
+ カタログはリポジトリに書き込める人が書きます。DuckDB は、カタログが指すファイルをすべて読み手の認証情報で読みます。リポジトリの外にも届く認証情報でカタログを ATTACH する読み手は、その前に次のことを確認するべきです。
41
+
42
+ - カタログの sha256 が `version.json` の `catalog.sha256` と一致する
43
+ - カタログが指すデータファイルはすべてデータパスからの相対パスで記録されていて、空・`.`・`..` の要素を含まない
44
+
45
+ 絶対パスや `data_dir` の外のファイルを指すカタログを開くと、読み手はその指す先を取得してしまいます。
46
+
47
+ HTTP では、読み手はトークンをリポジトリと同じオリジンにだけ送り、読み手自身のマシン以外には `https` でしか送りません。別のオリジンへのリダイレクトにはトークンを付けません。
48
+
38
49
  ## キャッシュ
39
50
 
40
51
  - バージョンのファイルは、[バージョン](/ja/spec/versions)に書いた例外を除いて変わらないので、カタログはいつまでもキャッシュしてよい
@@ -53,9 +53,15 @@ description: バージョン ID、version.json の項目、固めたカタログ
53
53
  "bytes": 214,
54
54
  "sha256": "3c5d…"
55
55
  },
56
- "changes": [
57
- { "table": "main.population", "kind": "add_column", "column": "note", "breaking": false }
58
- ],
56
+ "diff": {
57
+ "tables": { "added": [], "dropped": [] },
58
+ "rows": [{ "table": "main.population", "from": 1741, "to": 1802 }],
59
+ "columns": [
60
+ { "table": "main.population", "kind": "add_column", "column": "note", "breaking": false }
61
+ ],
62
+ "data": ["main.population"],
63
+ "descriptions": ["main.population.note"]
64
+ },
59
65
  "inputs": [
60
66
  {
61
67
  "source_id": "example:population-2025",
@@ -82,7 +88,7 @@ description: バージョン ID、version.json の項目、固めたカタログ
82
88
  | `ducklake` | must | DuckLake の形式、固めたスナップショット、親から足したスナップショットの範囲(最初と最後) |
83
89
  | `files` | may | カタログの隣の `files.json` を書いたときの、そのファイル名、大きさ、sha256([files.json](#filesjson)) |
84
90
  | `tree` | may | バージョンがほかのファイルを持つときの、カタログの隣の `tree.json` のファイル名、大きさ、sha256([tree.json](#treejson)) |
85
- | `changes` | may | 親との列の違い。`breaking` は、親に向けて書いた SQL が失敗しうるか(列の削除・改名・作り直し) |
91
+ | `diff` | may | 最初の親からの変更。最初のバージョンでは、そのバージョンの内容([diff](#diff)) |
86
92
  | `inputs` | may | 使った元のファイル。それぞれの取得元・取得日時・sha256 を書く。FDL はファイル自体を置かない。残したい書き手は、テーブルのアセットにする。`source_id` の付け方は書き手が決める |
87
93
  | `annotations` | may | 形式が解釈しない情報。読む側(ホストやツール)の名前をキーにする |
88
94
 
@@ -92,6 +98,31 @@ FDL 0.1 では、書き手が書く親は多くても 1 つです。`parents`
92
98
 
93
99
  スナップショットごとの説明と SQL は、DuckLake の `commit_message` と `commit_extra_info` としてカタログの中に残し、`version.json` には写しません。
94
100
 
101
+ ### diff
102
+
103
+ `diff` は、バージョンとその最初の親との違いです。読み手は `version.json` だけで履歴を表示できます。最初のバージョンでは、すべての表を追加として記録します。どのキーでも `table` は `schema.table` です。
104
+
105
+ | キー | 内容 |
106
+ | --- | --- |
107
+ | `tables` | `added`・`dropped`: 片方にしかない表 |
108
+ | `rows` | `table`・`from`・`to`: 両方にあり、行数が違う表 |
109
+ | `columns` | 列の違い(下の表) |
110
+ | `data` | 両方にあり、データファイルが違う表。行が同じでも記録します |
111
+ | `descriptions` | `dataset.json` の `title` か `description` が違うもの: `dataset`、表、または `schema.table.column` |
112
+
113
+ 書き手は、親のスナップショットのカタログと固めたカタログを比べます。カタログに親のスナップショットが残っていないときは `diff` を書きません。`descriptions` は、両方の `dataset.json` があるときだけ記録します。`diff` のないバージョンや、最初の親以外のバージョンと比べるときは、読み手が 2 つのバージョンの `dataset.json` と `files.json` を比べます。
114
+
115
+ `columns` の各項目は、両方にある表の、列 1 つの違いです。`column` は新しいバージョンでの列名です。
116
+
117
+ | `kind` | ほかに持つもの | `breaking` |
118
+ | --- | --- | --- |
119
+ | `add_column` | | `false` |
120
+ | `drop_column` | | `true` |
121
+ | `rename_column` | `from`: 前の列名 | `true` |
122
+ | `change_type` | `from_type`・`to_type`: DuckLake の型名 | 前の型の値がすべて新しい型に収まるとき(`int32` から `int64`、`float32` から `float64`)は `false`、それ以外は `true` |
123
+
124
+ 読み手は、知らない `kind` を無視し、その `breaking` は読みます。`diff` の知らないキーも無視します。
125
+
95
126
  ### 形式番号
96
127
 
97
128
  | 項目 | 指すもの | 変わるとき |
@@ -231,6 +262,7 @@ profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約
231
262
  "temporal_coverage": { "start": "2025", "end": "2025" },
232
263
  "spatial_coverage": ["JP"],
233
264
  "schemas": [{ "name": "main", "title": "Tables" }],
265
+ "catalogs": { "census": "https://example.org/census/" },
234
266
  "tables": [
235
267
  {
236
268
  "schema": "main",
@@ -238,7 +270,7 @@ profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約
238
270
  "title": "Population",
239
271
  "description": "One row per town, age group and sex",
240
272
  "primary_key": ["town_code", "age_group", "sex"],
241
- "depends_on": [],
273
+ "depends_on": ["https://example.org/census/#main.towns"],
242
274
  "sql": "SELECT …",
243
275
  "rows": 120000,
244
276
  "fields": [
@@ -254,9 +286,11 @@ profile は、`ducklake.snapshot_id` の時点の 1 つのテーブルの要約
254
286
  - 書き手は説明を YAML(`dataset.yml`)で持ってもよく、テーブルごとに別のファイル(`<name>.table.yml`、`tables` の 1 項目)に分けてもよい。バージョンには常に説明全体が 1 つの JSON で入る
255
287
  - `licenses` の各要素は SPDX の識別子か、`id` に書き手が足したいもの(`spdx`・`url`・`title`)を添えたオブジェクト
256
288
  - `tables` には、カタログの最後のスナップショットにある表をすべて並べる。書き手が説明しなかった表は、書き手のツールがカタログから分かることで足す。カタログに無い表や列を説明していたら断る
289
+ - `depends_on` は、その表の元になった表を並べる。このデータセットの表は `schema.name`、他のデータセットの表はそのリポジトリの URL・`#`・`schema.name` を続けて書く(`https://example.org/census/#main.towns`)。`sql` を持ち `depends_on` を持たない表は、書き手のツールが SQL から読む。SQL が読む表を並べ、自分以外のカタログは `catalogs` で URL に直す。SQL から解決できない参照は入れない
290
+ - `catalogs` は、SQL で他のデータセットを ATTACH している名前から、そのリポジトリの URL への対応(`{"census": "https://example.org/census/"}`)。読み手は、それを使うビューを読むために各リポジトリをこの名前で ATTACH できる
257
291
  - カタログのビューは表のあとに `"kind": "view"` を付けて並べ、`sql` はカタログのものを入れる。カタログはビューの列を記録しないので、ビューの `fields` は書き手が書いたままで、`type`・`nullable`・`rows` を持たない。表には `kind` を付けない
258
292
  - カタログから取るもの: 表ごとの `rows`、列ごとの `type`(DuckLake の型名)と `nullable`。書き手が `description` を書かなかったところには、カタログのコメント(`COMMENT ON`)を使う
259
- - この仕様が決めていないキーは断る。形式が解釈しない情報は、最上位・表・列それぞれの `annotations` に、読む側の名前をキーにして置く。書き手は書かれたまま残す
293
+ - 読み手は、この仕様が決めていないキーを無視する。書き手の道具は、綴りの誤りに気づけるよう、そのキーを断ってもよい。形式が解釈しない情報は、最上位・表・列それぞれの `annotations` に、読む側の名前をキーにして置く。書き手は書かれたまま残す
260
294
  - `annotations` という名前になる前のバージョンは、同じものを `extensions` に持つ。読み手は `extensions` を `annotations` として読む
261
295
  - ライセンスや出典に書いたことは書き手の主張で、ホストは公開する前に確かめてよい
262
296