fdl-cli 0.18.1__tar.gz → 0.19.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.1 → fdl_cli-0.19.0}/CHANGELOG.md +25 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/PKG-INFO +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/concepts/repositories.md +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/mirrors.md +3 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/serving-over-http.md +2 -1
- fdl_cli-0.19.0/docs/internals/from-write-to-read.md +109 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/internals/meta.ts +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/concepts/repositories.md +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/mirrors.md +3 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/serving-over-http.md +2 -1
- fdl_cli-0.19.0/docs/ja/internals/from-write-to-read.md +109 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/internals/meta.ts +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/reference/cli.md +17 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/reference/python.md +6 -0
- fdl_cli-0.19.0/docs/ja/spec/data-files.md +68 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/http.md +2 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/index.md +3 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/layout.md +2 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/versions.md +43 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/writing.md +5 -5
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/reference/cli.md +17 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/reference/python.md +6 -0
- fdl_cli-0.19.0/docs/spec/data-files.md +68 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/http.md +2 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/index.md +3 -2
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/layout.md +2 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/versions.md +43 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/writing.md +5 -5
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/pyproject.toml +1 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/cli.py +54 -6
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/dataset.py +8 -1
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/layout.py +4 -0
- fdl_cli-0.19.0/src/fdl/objects.py +217 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/repo.py +105 -5
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/version.py +8 -0
- fdl_cli-0.19.0/tests/test_objects.py +177 -0
- fdl_cli-0.18.1/docs/ja/spec/data-files.md +0 -60
- fdl_cli-0.18.1/docs/spec/data-files.md +0 -60
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.github/workflows/docs.yml +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.github/workflows/publish.yml +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.github/workflows/release.yml +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.gitignore +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.node-version +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/.python-version +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/CLAUDE.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/CONTRIBUTING.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/LICENSE +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/README.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/blume.config.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/concepts/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/getting-started.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/building-a-host.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/public-and-private.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/guides/stores.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/index.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/concepts/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/concepts/versions-and-refs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/concepts/working-catalogs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/getting-started.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/building-a-host.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/public-and-private.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/guides/stores.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/index.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/internals/ducklake-formats.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/internals/inside-a-repository.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/reference/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/reading.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/ja/spec/refs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/reference/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/meta.ts +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/reading.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/docs/spec/refs.md +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/package-lock.json +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/package.json +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/public/CNAME +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/__init__.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/catalog.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/py.typed +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/refs.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/store.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/src/fdl/stores.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/http_repo.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/test_cli.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/test_dataset.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/test_http.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/test_repo.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/tests/test_stores.py +0 -0
- {fdl_cli-0.18.1 → fdl_cli-0.19.0}/uv.lock +0 -0
|
@@ -1,6 +1,31 @@
|
|
|
1
1
|
# CHANGELOG
|
|
2
2
|
|
|
3
3
|
|
|
4
|
+
## v0.19.0 (2026-11-06)
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
- Keep the files rows point at and a version's other files as assets, listed in tree.json
|
|
9
|
+
([#38](https://github.com/queria-io/fdl/pull/38),
|
|
10
|
+
[`8c49933`](https://github.com/queria-io/fdl/commit/8c49933158f31f8c40d267ee76a6ed8e331b548b))
|
|
11
|
+
|
|
12
|
+
A column marked asset holds the sha256 of a file stored at assets/<sha256>. A version's other files
|
|
13
|
+
(README.md and docs/) go in versions/<ID>/tree.json, path to sha256, as Git's tree does; they are
|
|
14
|
+
stored as written and links are resolved through the tree. fdl commit uploads both, --assets gives
|
|
15
|
+
the folder of the files rows point at, and fdl assets lists a folder as CSV.
|
|
16
|
+
|
|
17
|
+
Co-authored-by: Claude <noreply@anthropic.com>
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
## v0.18.2 (2026-11-03)
|
|
21
|
+
|
|
22
|
+
### Bug Fixes
|
|
23
|
+
|
|
24
|
+
- Refuse a version past retention in fdl url, and explain how FDL works
|
|
25
|
+
([#35](https://github.com/queria-io/fdl/pull/35),
|
|
26
|
+
[`1130813`](https://github.com/queria-io/fdl/commit/1130813857d6dd5596c3b7fbb6ef3717b94c16f6))
|
|
27
|
+
|
|
28
|
+
|
|
4
29
|
## v0.18.1 (2026-11-03)
|
|
5
30
|
|
|
6
31
|
### 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
|
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: From write to read
|
|
3
|
+
description: One change followed from a working catalog to a reader, with the requests at each step, and what each part of FDL is in Git.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
This page follows one change from the writer's machine to a reader, and names the request made at each step. The files each step leaves in the repository are shown in [Inside a repository](/internals/inside-a-repository), and the rules are in the [specification](/spec).
|
|
7
|
+
|
|
8
|
+
## The parts and their Git counterparts
|
|
9
|
+
|
|
10
|
+
FDL keeps the roles and names of Git, and stores things its own way. Anyone who knows how Git keeps commits can read a repository by this table.
|
|
11
|
+
|
|
12
|
+
| FDL | Git | Notes |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Repository (a prefix of a store) | Bare repository on a server | No server process is needed |
|
|
15
|
+
| `fdl.json` | `config` | Holds the format, the repository's `id` and `data_dir` |
|
|
16
|
+
| `versions/<ID>/version.json` | Commit | Parents, author, message, and the sha256 of the catalog |
|
|
17
|
+
| `versions/<ID>/ducklake.duckdb` | Tree | Which tables there are and which data files they are made of |
|
|
18
|
+
| Data file (Parquet) | Blob | Written once and never changed. One file can be named by many versions |
|
|
19
|
+
| `refs/heads/<name>` | Branch | Moves forward only, on condition |
|
|
20
|
+
| `refs/tags/<name>` | Tag | Created once, never moved |
|
|
21
|
+
| `HEAD` | `HEAD` | Names the default branch |
|
|
22
|
+
| `refs.json` | `info/refs` | Lets a reader over plain HTTP find refs by name |
|
|
23
|
+
| `versions/<ID>/files.json` | Reachability bitmap | An index made from the catalog. A reader can do without it |
|
|
24
|
+
| `version.json.sig` | Signed commit | An SSH signature made with `ssh-keygen -Y sign` |
|
|
25
|
+
| Working catalog (SQLite) | Working tree and index | Made from a version and turned into the next one |
|
|
26
|
+
| `POST <root>/?batch` | Git LFS batch API | Hands out URLs for uploading straight to storage |
|
|
27
|
+
| `expired.json` | None | Says why a version has no catalog any more |
|
|
28
|
+
|
|
29
|
+
Three things differ on purpose:
|
|
30
|
+
|
|
31
|
+
- A version's ID is a UUIDv7, not a hash of its content. Two DuckDB releases can write the same catalog as different bytes, so a content hash would change with the tool. The sha256 in `version.json` checks the content instead
|
|
32
|
+
- There are no packfiles. Each file is its own object in the store, so a reader fetches only the parts of a Parquet file it needs
|
|
33
|
+
- There is no merge. A version has one parent, and a writer whose push is refused builds again on the newer version
|
|
34
|
+
|
|
35
|
+
## Writing a version
|
|
36
|
+
|
|
37
|
+
### Checkout
|
|
38
|
+
|
|
39
|
+
`fdl checkout` reads `HEAD`, then the ref it names, then that version's `version.json`, and copies its catalog into a SQLite file on the writer's machine. This is the working catalog. If the version has `expired.json`, checkout stops.
|
|
40
|
+
|
|
41
|
+
The working catalog's data path depends on the store:
|
|
42
|
+
|
|
43
|
+
- A folder or S3: the repository's data folder. DuckDB writes new Parquet files straight into the repository
|
|
44
|
+
- HTTP: a folder on the writer's machine. Files already in the repository are referred to by their URL under `data_dir` and are read over HTTP
|
|
45
|
+
|
|
46
|
+
### Writing
|
|
47
|
+
|
|
48
|
+
The writer runs SQL on the working catalog with DuckDB, directly or through a tool such as dbt. Each statement makes a DuckLake snapshot in the working catalog. Nothing a reader can see changes yet: the new Parquet files, if they are already in the repository, are named by no version.
|
|
49
|
+
|
|
50
|
+
### Commit
|
|
51
|
+
|
|
52
|
+
`fdl commit` copies the working catalog into a DuckDB file, sets its `data_path` to the repository's data folder, makes `dataset.json` from it, and writes `version.json` with a new ID and the previous version as its parent. If the tables hold the same rows as the parent's, there is no commit. The new version exists only on the writer's machine until it is pushed.
|
|
53
|
+
|
|
54
|
+
### Push
|
|
55
|
+
|
|
56
|
+
A push writes files in the order that keeps readers safe: whatever a file points at is written before it.
|
|
57
|
+
|
|
58
|
+
1. The new data files the repository lacks
|
|
59
|
+
2. `versions/<ID>/ducklake.duckdb`
|
|
60
|
+
3. `versions/<ID>/dataset.json` and `files.json`
|
|
61
|
+
4. `versions/<ID>/version.json`
|
|
62
|
+
5. The ref, with `If-Match: <ETag read before step 1>`, or `If-None-Match: *` for the first version
|
|
63
|
+
6. `refs.json`, rewritten from a fresh read of `HEAD` and every ref
|
|
64
|
+
|
|
65
|
+
Readers start from a ref, and the ref is written in step 5. A push that stops before then leaves files that no ref names, and readers never see them. If another writer moved the ref after step 1, the ETag no longer matches and the store refuses step 5. That writer checks out again and builds on the new version.
|
|
66
|
+
|
|
67
|
+
`refs.json` is written after the ref, so it may lag behind for a moment. That is why a reader that needs the current version reads the ref itself.
|
|
68
|
+
|
|
69
|
+
### Push over HTTP
|
|
70
|
+
|
|
71
|
+
Over HTTP, every key is a path under the repository's URL, and the host answers `GET`, `PUT` and the rest for it (see [Pushing over HTTP](/spec/http)). The order is the same as above. Two steps change:
|
|
72
|
+
|
|
73
|
+
- Before step 1, the writer sends `POST <root>/?batch` with the keys and sizes of the files it is about to upload. For each file, the host answers with an upload URL, says the file is already there, or answers 413 to have it sent through the host. Files with a URL go straight to storage with `PUT`, and the host is not in the path of the data. A host without batches answers 404, 405 or 501, and every file goes through the host
|
|
74
|
+
- In step 5, the host checks the push before it moves the ref: the version is complete, its parent is the version the ref holds now, the catalog matches `version.json`, and every data file the catalog names is in the repository. It answers 409 with the reason when a check fails. A host that moves refs itself also writes `refs.json`, and answers 403 when the writer tries to
|
|
75
|
+
|
|
76
|
+
A host can also keep writers from moving refs at all. The writer then uploads the version and stops after step 4, and the host moves the ref later, for example after someone approves the change.
|
|
77
|
+
|
|
78
|
+
## Reading a version
|
|
79
|
+
|
|
80
|
+
A reader needs only `GET`. It does not have to know who wrote the repository or whether a host is in front of it.
|
|
81
|
+
|
|
82
|
+
1. Read `HEAD`, or the ref asked for. `HEAD` holds `ref: refs/heads/main`, so read `refs/heads/main` next. A ref holds a version ID
|
|
83
|
+
2. Read `versions/<ID>/version.json`. Check that its `id` is the ID asked for and that the reader knows the major version in `fdl`
|
|
84
|
+
3. Check for `versions/<ID>/expired.json`. If it is there, stop: the version is past retention or withdrawn, and its catalog is gone
|
|
85
|
+
4. Attach the catalog read-only, with the repository's data folder as the data path
|
|
86
|
+
|
|
87
|
+
```sql
|
|
88
|
+
ATTACH 'ducklake:https://example.org/lake/versions/019a3c4e-…/ducklake.duckdb' AS lake (
|
|
89
|
+
DATA_PATH 'https://example.org/lake/data/', OVERRIDE_DATA_PATH true, READ_ONLY
|
|
90
|
+
);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
From here DuckDB reads the catalog and fetches the parts of the Parquet files a query needs. `fdl url` does steps 1 to 3 and prints the catalog's URL for step 4.
|
|
94
|
+
|
|
95
|
+
The reader passes the data path itself rather than using the one in the catalog. The catalog holds the URL where the writer published, and a mirror serves the same files somewhere else. With the data path given by the reader, the same statement works at the origin and at any mirror.
|
|
96
|
+
|
|
97
|
+
A version's catalog never changes, so it can be cached for good. `HEAD`, `refs/` and `refs.json` are served with `Cache-Control: no-store`, so a reader always sees where a ref points now.
|
|
98
|
+
|
|
99
|
+
### Readers that do not know FDL
|
|
100
|
+
|
|
101
|
+
A host may serve the catalog of the version `HEAD` holds at `<root>/ducklake.duckdb`. A reader that knows only DuckLake can then attach that one URL. The host sends the version ID in the `FDL-Version` header, so that a reader can find out which version it got. The store holds no file at that key: the host serves the catalog from `versions/`.
|
|
102
|
+
|
|
103
|
+
## Taking a version away
|
|
104
|
+
|
|
105
|
+
`fdl expire` takes old versions out of retention. It puts `expired.json` first, then deletes the catalog, and leaves `version.json`, so `fdl log` still shows the version and its place in the history. Data files that no live version names are deleted later, after a grace period, because a writer may be about to commit a version that names them.
|
|
106
|
+
|
|
107
|
+
Withdrawing removes data that must not be published, such as personal data published by mistake, from every version that holds it. The writer first makes a new version without the data and moves each affected branch forward to it, and deletes the tags that point at affected versions. Then the data files that hold the data are deleted at once, with no grace period, and each affected version gets `expired.json` with `"reason": "withdrawn"` and loses its catalog. The steps are in [Data files](/spec/data-files#withdrawal).
|
|
108
|
+
|
|
109
|
+
A reader that reaches an expired or withdrawn version stops at step 3 of reading and reports the reason.
|
|
@@ -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
|
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 書いてから読まれるまで
|
|
3
|
+
description: 1 つの変更を作業カタログから読み手まで追い、各段階のリクエストと、FDL の各部分が Git の何に当たるかを示します。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
このページでは、1 つの変更を書き手のマシンから読み手まで追い、各段階で送るリクエストを示します。各段階でリポジトリに残るファイルは[リポジトリの中身](/ja/internals/inside-a-repository)に、決まりは[仕様](/ja/spec)にあります。
|
|
7
|
+
|
|
8
|
+
## 各部分と Git での呼び名
|
|
9
|
+
|
|
10
|
+
FDL は Git の役割と名前をそのまま使い、保存の仕方は独自に決めています。Git がコミットをどう持つかを知っていれば、この表でリポジトリを読めます。
|
|
11
|
+
|
|
12
|
+
| FDL | Git | 補足 |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| リポジトリ(ストアの 1 つのプレフィックス) | サーバー上のベアリポジトリ | サーバーのプロセスは要りません |
|
|
15
|
+
| `fdl.json` | `config` | 形式、リポジトリの `id`、`data_dir` を持ちます |
|
|
16
|
+
| `versions/<ID>/version.json` | コミット | 親、作者、メッセージ、カタログの sha256 を持ちます |
|
|
17
|
+
| `versions/<ID>/ducklake.duckdb` | ツリー | どのテーブルがあり、それぞれがどのデータファイルでできているかを持ちます |
|
|
18
|
+
| データファイル(Parquet) | ブロブ | 一度書いたら変えません。1 つのファイルを多くのバージョンが指せます |
|
|
19
|
+
| `refs/heads/<name>` | ブランチ | 条件付き書き込みで、前にだけ進みます |
|
|
20
|
+
| `refs/tags/<name>` | タグ | 一度作ったら動かしません |
|
|
21
|
+
| `HEAD` | `HEAD` | 既定のブランチの名前を持ちます |
|
|
22
|
+
| `refs.json` | `info/refs` | 素の HTTP の読み手が ref を名前で探せるようにします |
|
|
23
|
+
| `versions/<ID>/files.json` | 到達可能性ビットマップ | カタログから作る索引です。読み手はこれが無くても読めます |
|
|
24
|
+
| `version.json.sig` | 署名付きコミット | `ssh-keygen -Y sign` で作る SSH 署名です |
|
|
25
|
+
| 作業カタログ(SQLite) | 作業ツリーとインデックス | バージョンから作り、次のバージョンにします |
|
|
26
|
+
| `POST <root>/?batch` | Git LFS の batch API | ストレージへ直接アップロードする URL を渡します |
|
|
27
|
+
| `expired.json` | なし | バージョンにカタログが無くなった理由を書きます |
|
|
28
|
+
|
|
29
|
+
次の 3 つは、意図して Git と変えています。
|
|
30
|
+
|
|
31
|
+
- バージョンの ID は UUIDv7 で、中身のハッシュではありません。DuckDB のリリースが違うと、同じカタログでも違うバイト列で書かれることがあり、中身のハッシュは道具によって変わってしまうためです。中身の確認には `version.json` の sha256 を使います
|
|
32
|
+
- packfile はありません。ファイルはそれぞれストアの 1 つのオブジェクトなので、読み手は Parquet ファイルのうち要る部分だけを取りに行けます
|
|
33
|
+
- マージはありません。バージョンの親は 1 つです。push を断られた書き手は、新しいバージョンの上で作り直します
|
|
34
|
+
|
|
35
|
+
## バージョンを書く
|
|
36
|
+
|
|
37
|
+
### checkout
|
|
38
|
+
|
|
39
|
+
`fdl checkout` は `HEAD` を読み、それが指す ref を読み、そのバージョンの `version.json` を読んでから、カタログを書き手のマシンの SQLite ファイルに写します。これが作業カタログです。バージョンに `expired.json` があれば、checkout は止まります。
|
|
40
|
+
|
|
41
|
+
作業カタログのデータパスは、ストアによって変わります。
|
|
42
|
+
|
|
43
|
+
- フォルダか S3: リポジトリのデータフォルダです。DuckDB は新しい Parquet ファイルをリポジトリへ直接書きます
|
|
44
|
+
- HTTP: 書き手のマシンのフォルダです。リポジトリに既にあるファイルは `data_dir` の下の URL で指し、HTTP で読みます
|
|
45
|
+
|
|
46
|
+
### 書く
|
|
47
|
+
|
|
48
|
+
書き手は作業カタログに対して、DuckDB で直接、または dbt などの道具を通して SQL を流します。文ごとに作業カタログに DuckLake のスナップショットができます。読み手から見えるものはまだ何も変わりません。新しい Parquet ファイルがリポジトリに書かれていても、どのバージョンもそれを指していないためです。
|
|
49
|
+
|
|
50
|
+
### commit
|
|
51
|
+
|
|
52
|
+
`fdl commit` は作業カタログを DuckDB ファイルに写し、その `data_path` をリポジトリのデータフォルダにし、そこから `dataset.json` を作り、新しい ID と、親として前のバージョンを持つ `version.json` を書きます。テーブルの行が親と同じなら、コミットしません。新しいバージョンは、push するまで書き手のマシンにしかありません。
|
|
53
|
+
|
|
54
|
+
### push
|
|
55
|
+
|
|
56
|
+
push は、読み手を守る順にファイルを書きます。あるファイルが指す先は、そのファイルより先に書きます。
|
|
57
|
+
|
|
58
|
+
1. リポジトリに無い新しいデータファイル
|
|
59
|
+
2. `versions/<ID>/ducklake.duckdb`
|
|
60
|
+
3. `versions/<ID>/dataset.json` と `files.json`
|
|
61
|
+
4. `versions/<ID>/version.json`
|
|
62
|
+
5. ref。`If-Match: <1 の前に読んだ ETag>` で書きます。最初のバージョンなら `If-None-Match: *` です
|
|
63
|
+
6. `refs.json`。`HEAD` とすべての ref を読み直して書き直します
|
|
64
|
+
|
|
65
|
+
読み手は ref から読み始め、ref は 5 で書きます。5 より前で止まった push は、どの ref も指さないファイルを残すだけで、読み手からは見えません。1 のあとに別の書き手が ref を動かしていれば、ETag が合わず、ストアは 5 を断ります。断られた書き手は checkout し直し、新しいバージョンの上で作り直します。
|
|
66
|
+
|
|
67
|
+
`refs.json` は ref のあとに書くので、少しの間は ref より古いことがあります。そのため、今のバージョンが要る読み手は ref 自体を読みます。
|
|
68
|
+
|
|
69
|
+
### HTTP での push
|
|
70
|
+
|
|
71
|
+
HTTP では、すべてのキーがリポジトリの URL の下のパスになり、ホストがそこへの `GET` や `PUT` などに答えます([HTTP での push](/ja/spec/http)を参照)。順番は上と同じで、2 つの段階が変わります。
|
|
72
|
+
|
|
73
|
+
- 1 の前に、書き手はこれから上げるファイルのキーと大きさを `POST <root>/?batch` で送ります。ホストはファイルごとに、アップロード用の URL を返すか、既にあると答えるか、ホスト経由で送らせるために 413 を返します。URL をもらったファイルは `PUT` でストレージへ直接送られ、データはホストを通りません。batch の無いホストは 404・405・501 のどれかを返し、すべてのファイルがホストを通ります
|
|
74
|
+
- 5 で、ホストは ref を動かす前に push を確かめます。バージョンがそろっていること、その親が今 ref の指すバージョンであること、カタログが `version.json` と合うこと、カタログが指すデータファイルがすべてリポジトリにあることです。確認に通らなければ、理由を付けて 409 を返します。ref を自分で動かすホストは `refs.json` も自分で書き、書き手が書こうとすると 403 を返します
|
|
75
|
+
|
|
76
|
+
ホストは、書き手に ref を一切動かさせないこともできます。その場合、書き手はバージョンを上げて 4 で止まり、ホストがあとで、たとえば誰かが変更を承認したときに ref を動かします。
|
|
77
|
+
|
|
78
|
+
## バージョンを読む
|
|
79
|
+
|
|
80
|
+
読み手に要るのは `GET` だけです。誰がリポジトリを書いたかも、前にホストがいるかどうかも知らなくて構いません。
|
|
81
|
+
|
|
82
|
+
1. `HEAD` か、求められた ref を読みます。`HEAD` は `ref: refs/heads/main` を持つので、次に `refs/heads/main` を読みます。ref はバージョンの ID を持ちます
|
|
83
|
+
2. `versions/<ID>/version.json` を読みます。`id` が求めた ID と同じで、`fdl` のメジャーバージョンを読み手が知っていることを確かめます
|
|
84
|
+
3. `versions/<ID>/expired.json` があるか確かめます。あれば止まります。そのバージョンは保持期間を過ぎたか取り下げられていて、カタログはもうありません
|
|
85
|
+
4. リポジトリのデータフォルダをデータパスにして、カタログを読み取り専用で ATTACH します
|
|
86
|
+
|
|
87
|
+
```sql
|
|
88
|
+
ATTACH 'ducklake:https://example.org/lake/versions/019a3c4e-…/ducklake.duckdb' AS lake (
|
|
89
|
+
DATA_PATH 'https://example.org/lake/data/', OVERRIDE_DATA_PATH true, READ_ONLY
|
|
90
|
+
);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
ここから先は DuckDB がカタログを読み、クエリに要る Parquet ファイルの部分を取りに行きます。`fdl url` は 1 から 3 までを行い、4 で使うカタログの URL を出します。
|
|
94
|
+
|
|
95
|
+
読み手はカタログに書かれたデータパスを使わず、自分で渡します。カタログが持つのは書き手が公開した場所の URL で、ミラーは同じファイルを別の場所から配るためです。読み手がデータパスを渡せば、同じ文が元のホストでもどのミラーでも動きます。
|
|
96
|
+
|
|
97
|
+
バージョンのカタログは変わらないので、ずっとキャッシュできます。`HEAD`・`refs/`・`refs.json` は `Cache-Control: no-store` で配るので、読み手は ref が今どこを指しているかを必ず知ることができます。
|
|
98
|
+
|
|
99
|
+
### FDL を知らない読み手
|
|
100
|
+
|
|
101
|
+
ホストは、`HEAD` が指すバージョンのカタログを `<root>/ducklake.duckdb` で配ってもかまいません。DuckLake しか知らない読み手は、その 1 つの URL を ATTACH できます。ホストは `FDL-Version` ヘッダーでバージョンの ID を送るので、読み手はどのバージョンを受け取ったかを知ることができます。ストアのそのキーにはファイルがありません。ホストが `versions/` のカタログを配ります。
|
|
102
|
+
|
|
103
|
+
## バージョンを消す
|
|
104
|
+
|
|
105
|
+
`fdl expire` は古いバージョンを保持期間から外します。先に `expired.json` を置き、次にカタログを消し、`version.json` は残します。そのため `fdl log` はそのバージョンと履歴の中の位置を表示し続けます。どの生きているバージョンも指さないデータファイルは、猶予期間のあとで消します。書き手がそのファイルを指すバージョンをこれからコミットするかもしれないためです。
|
|
106
|
+
|
|
107
|
+
取り下げは、間違って公開した個人データなど、公開してはいけないデータを、それを持つすべてのバージョンから消します。書き手はまず、そのデータを除いた新しいバージョンを作り、影響を受けるブランチをそこへ前に進め、影響を受けるバージョンを指すタグを消します。次に、そのデータを持つデータファイルを猶予期間を置かずにすぐ消し、影響を受けるバージョンに `"reason": "withdrawn"` の `expired.json` を置いてカタログを消します。手順は[データファイル](/ja/spec/data-files#取り下げ)にあります。
|
|
108
|
+
|
|
109
|
+
保持期間を過ぎたか取り下げられたバージョンにたどり着いた読み手は、読む手順の 3 で止まり、理由を伝えます。
|
|
@@ -44,13 +44,17 @@ 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
|
+
`asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、リポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
|
|
57
|
+
|
|
54
58
|
親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit` と表示し、ブランチを動かさずに終了コード 0 で終わります。同じ行を新しいファイルに書き直しただけの作り直しも、変更なしとみなします。`--allow-empty` を付けると、それでもバージョンを作ります。行を読めず判定できないときは、警告を出してバージョンを作ります。
|
|
55
59
|
|
|
56
60
|
次のときは断られます。
|
|
@@ -59,8 +63,17 @@ fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.
|
|
|
59
63
|
- チェックアウトのあとにブランチが動いたとき。チェックアウトし直して作業をやり直す
|
|
60
64
|
- 作業カタログが行をカタログの中に持っているとき
|
|
61
65
|
- カタログが参照するデータファイルがリポジトリに無いとき
|
|
66
|
+
- アセットの列が `varchar` でないとき、sha256 でない値を持つとき、リポジトリにも `--assets` にも無いファイルを指すとき
|
|
62
67
|
- データファイルが、データディレクトリの外を指す絶対パスで記録されているとき
|
|
63
68
|
|
|
69
|
+
## fdl assets
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
fdl assets <folder> > files.csv
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
フォルダより下のファイル(隠しファイルを除く)を、`path`・`sha256`・`bytes`・`media_type` の CSV で表示します。これを DuckDB の `read_csv` などでファイルを指すテーブルに読み込み、`sha256` の列に `asset: true` の印を付けて、`--assets <folder>` を付けてコミットします。ファイルの sha256 はここで 1 回だけ計算し、SQL でファイルを読む必要はありません。
|
|
76
|
+
|
|
64
77
|
## fdl log
|
|
65
78
|
|
|
66
79
|
```bash
|
|
@@ -75,7 +88,7 @@ ref が指すバージョンから最初のバージョンまで、最初の親
|
|
|
75
88
|
fdl url <remote> [--ref HEAD]
|
|
76
89
|
```
|
|
77
90
|
|
|
78
|
-
ref が指すバージョンのカタログの URL を表示します。読み取り専用で `ATTACH`
|
|
91
|
+
ref が指すバージョンのカタログの URL を表示します。読み取り専用で `ATTACH` するのに使います。保持期間を過ぎたか取り下げたバージョンは、カタログがまだ配られていても断ります。
|
|
79
92
|
|
|
80
93
|
## fdl tag
|
|
81
94
|
|
|
@@ -95,6 +108,8 @@ fdl withdraw <remote> <version>... [--yes]
|
|
|
95
108
|
|
|
96
109
|
間違って公開した個人データなど、公開してはいけないデータを持つバージョンを取り下げます([取り下げ](/ja/spec/data-files#取り下げ))。先にそのデータを除いたバージョンをコミットし、該当するバージョンを指すブランチが無い状態にします。そのうえでこのコマンドが、該当するバージョンを指すタグ、そのカタログが参照し残すバージョンが読まないデータファイル、カタログを消し、`"reason": "withdrawn"` の `expired.json` を置きます。`version.json` は残します。
|
|
97
110
|
|
|
111
|
+
アセットは、まだ消しません。データを持つものは `assets/` から手で消してください。
|
|
112
|
+
|
|
98
113
|
`--yes` を付けないと、消すものを表示するだけです。残すバージョンが読んでいるファイルは残すものとして表示します。それがそのデータを持つなら、そのバージョンも取り下げます。ブランチかリクエストが該当するバージョンを指しているあいだは断られます。
|
|
99
114
|
|
|
100
115
|
## fdl expire
|
|
@@ -75,6 +75,12 @@ repo.is_ancestor(store, ancestor_id, descendant) -> bool
|
|
|
75
75
|
|
|
76
76
|
最初の親をたどる、ref が指すバージョンを読む、あるバージョンが別のバージョンより前にあるかを確かめる、の 3 つです。
|
|
77
77
|
|
|
78
|
+
```python
|
|
79
|
+
repo.readable(store, name="HEAD") -> Version
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
ref が指すバージョンを、読み手がカタログを開く前に行う確認を済ませてから返します。最初のバージョンの前、読めない形式の `version.json`、保持期間を過ぎたか取り下げたバージョンでは `RepoError` を出します。`fdl url` はこれを使います。
|
|
83
|
+
|
|
78
84
|
```python
|
|
79
85
|
repo.expire(store, version_id, *, reason="retention") -> None
|
|
80
86
|
repo.prune(store, newest, *, keep=1, since=None, reason="retention") -> list[str]
|
|
@@ -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
|
|
|
@@ -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,12 @@ description: リポジトリのファイル、そのパス、fdl.json の中身
|
|
|
22
22
|
ducklake.duckdb 固めたカタログ
|
|
23
23
|
dataset.json バージョンの中身の説明
|
|
24
24
|
files.json カタログから作った、表ごとのデータファイルの索引(任意)
|
|
25
|
+
tree.json README など、バージョンのほかのファイルのパスの一覧(任意)
|
|
25
26
|
catalogs/<format>.duckdb 別の DuckLake 形式のカタログ(任意)
|
|
26
27
|
expired.json 保持期間を過ぎた印(過ぎたときだけ)
|
|
27
28
|
<others> ホストが足すファイル(プレビューなど)
|
|
28
29
|
<data_dir><schema>/<table>/ducklake-<uuid>.parquet データファイル(共有、変えない)
|
|
29
|
-
|
|
30
|
+
assets/<sha256> テーブルの行やバージョンの tree.json が指すファイル(共有、変更しない)
|
|
30
31
|
```
|
|
31
32
|
|
|
32
33
|
`HEAD` と `refs/` の下のファイルには、Git と同じく拡張子を付けません。中身は UTF-8 のテキストです。
|