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.
- fdl_cli-0.22.0/.github/workflows/test.yml +41 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CHANGELOG.md +29 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CLAUDE.md +1 -1
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/CONTRIBUTING.md +12 -4
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/PKG-INFO +21 -6
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/README.md +17 -2
- fdl_cli-0.22.0/SECURITY.md +7 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/blume.config.ts +1 -1
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/getting-started.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/index.md +22 -1
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/getting-started.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/index.md +21 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/cli.md +47 -7
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/python.md +13 -2
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/http.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/layout.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/reading.md +11 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/versions.md +40 -6
- fdl_cli-0.22.0/docs/ja/stability.md +40 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/cli.md +47 -7
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/python.md +13 -2
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/http.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/layout.md +2 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/reading.md +11 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/versions.md +40 -6
- fdl_cli-0.22.0/docs/stability.md +40 -0
- fdl_cli-0.22.0/public/CNAME +1 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/pyproject.toml +4 -4
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/catalog.py +198 -6
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/cli.py +217 -18
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/dataset.py +23 -6
- fdl_cli-0.22.0/src/fdl/diff.py +293 -0
- fdl_cli-0.22.0/src/fdl/lineage.py +127 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/repo.py +59 -5
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/stores.py +58 -2
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/version.py +9 -3
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_cli.py +56 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_dataset.py +81 -3
- fdl_cli-0.22.0/tests/test_http.py +354 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_repo.py +110 -3
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/uv.lock +2 -2
- fdl_cli-0.21.0/public/CNAME +0 -1
- fdl_cli-0.21.0/tests/test_http.py +0 -183
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/docs.yml +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/publish.yml +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.github/workflows/release.yml +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.gitignore +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.node-version +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/.python-version +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/LICENSE +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/repositories.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/building-a-host.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/mirrors.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/public-and-private.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/serving-over-http.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/guides/stores.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/internals/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/repositories.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/building-a-host.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/mirrors.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/public-and-private.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/serving-over-http.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/guides/stores.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/from-write-to-read.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/internals/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/reference/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/data-files.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/index.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/refs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/ja/spec/writing.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/reference/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/data-files.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/index.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/meta.ts +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/refs.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/docs/spec/writing.md +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/package-lock.json +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/package.json +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/__init__.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/layout.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/objects.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/profiles.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/py.typed +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/refs.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/src/fdl/store.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/http_repo.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_objects.py +0 -0
- {fdl_cli-0.21.0 → fdl_cli-0.22.0}/tests/test_profiles.py +0 -0
- {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
|
|
@@ -18,18 +18,26 @@ uv run pytest
|
|
|
18
18
|
## Project structure
|
|
19
19
|
|
|
20
20
|
```
|
|
21
|
-
docs/
|
|
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
|
-
├──
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
6
|
-
Project-URL: Documentation, https://fdl.
|
|
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<
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
@@ -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
|
-
##
|
|
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
|
|
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`
|
|
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 を動かすときにホストが確認するのは同じです。
|
|
@@ -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
|
-
"
|
|
57
|
-
|
|
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
|
-
| `
|
|
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
|
-
-
|
|
293
|
+
- 読み手は、この仕様が決めていないキーを無視する。書き手の道具は、綴りの誤りに気づけるよう、そのキーを断ってもよい。形式が解釈しない情報は、最上位・表・列それぞれの `annotations` に、読む側の名前をキーにして置く。書き手は書かれたまま残す
|
|
260
294
|
- `annotations` という名前になる前のバージョンは、同じものを `extensions` に持つ。読み手は `extensions` を `annotations` として読む
|
|
261
295
|
- ライセンスや出典に書いたことは書き手の主張で、ホストは公開する前に確かめてよい
|
|
262
296
|
|