tabledoc 0.2.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.
- tabledoc-0.2.0/.github/workflows/pages.yml +56 -0
- tabledoc-0.2.0/.github/workflows/publish.yml +29 -0
- tabledoc-0.2.0/.github/workflows/release.yml +27 -0
- tabledoc-0.2.0/.github/workflows/test.yml +23 -0
- tabledoc-0.2.0/.gitignore +10 -0
- tabledoc-0.2.0/.node-version +1 -0
- tabledoc-0.2.0/CHANGELOG.md +29 -0
- tabledoc-0.2.0/CLAUDE.md +31 -0
- tabledoc-0.2.0/LICENSE +21 -0
- tabledoc-0.2.0/PKG-INFO +87 -0
- tabledoc-0.2.0/README.ja.md +70 -0
- tabledoc-0.2.0/README.md +70 -0
- tabledoc-0.2.0/blume.config.ts +28 -0
- tabledoc-0.2.0/docs/index.md +68 -0
- tabledoc-0.2.0/docs/ja/index.md +68 -0
- tabledoc-0.2.0/docs/ja/spec.md +251 -0
- tabledoc-0.2.0/docs/spec.md +251 -0
- tabledoc-0.2.0/package-lock.json +12056 -0
- tabledoc-0.2.0/package.json +16 -0
- tabledoc-0.2.0/public/CNAME +1 -0
- tabledoc-0.2.0/public/apple-touch-icon.png +0 -0
- tabledoc-0.2.0/public/favicon.ico +0 -0
- tabledoc-0.2.0/public/icon-512.png +0 -0
- tabledoc-0.2.0/public/icon.svg +12 -0
- tabledoc-0.2.0/pyproject.toml +37 -0
- tabledoc-0.2.0/src/tabledoc/__init__.py +8 -0
- tabledoc-0.2.0/src/tabledoc/__main__.py +5 -0
- tabledoc-0.2.0/src/tabledoc/cli.py +78 -0
- tabledoc-0.2.0/src/tabledoc/dbt.py +182 -0
- tabledoc-0.2.0/src/tabledoc/description.py +207 -0
- tabledoc-0.2.0/src/tabledoc/files.py +128 -0
- tabledoc-0.2.0/src/tabledoc/git.py +43 -0
- tabledoc-0.2.0/src/tabledoc/legacy.py +87 -0
- tabledoc-0.2.0/src/tabledoc/lineage.py +150 -0
- tabledoc-0.2.0/src/tabledoc/load.py +186 -0
- tabledoc-0.2.0/src/tabledoc/meta.py +441 -0
- tabledoc-0.2.0/src/tabledoc/report.py +63 -0
- tabledoc-0.2.0/src/tabledoc/schemas/dataset/v1.json +114 -0
- tabledoc-0.2.0/src/tabledoc/schemas/legacy/dataset/v1.json +117 -0
- tabledoc-0.2.0/src/tabledoc/schemas/legacy/table/v1.json +56 -0
- tabledoc-0.2.0/src/tabledoc/schemas/table/v1.json +84 -0
- tabledoc-0.2.0/src/tabledoc/schemas/tabledoc/v1.json +145 -0
- tabledoc-0.2.0/src/tabledoc/schemas.py +47 -0
- tabledoc-0.2.0/src/tabledoc/shape.py +117 -0
- tabledoc-0.2.0/src/tabledoc/source.py +188 -0
- tabledoc-0.2.0/tests/conftest.py +22 -0
- tabledoc-0.2.0/tests/test_git.py +18 -0
- tabledoc-0.2.0/tests/test_load.py +212 -0
- tabledoc-0.2.0/tests/test_read.py +280 -0
- tabledoc-0.2.0/uv.lock +640 -0
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: Pages
|
|
2
|
+
|
|
3
|
+
# Builds the documentation site (Blume) and serves it with the JSON Schemas under schemas/.
|
|
4
|
+
# A schema keeps its URL for good: change one by adding v2, never by editing v1's meaning.
|
|
5
|
+
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
branches: [main]
|
|
9
|
+
paths:
|
|
10
|
+
- "docs/**"
|
|
11
|
+
- "public/**"
|
|
12
|
+
- "src/tabledoc/schemas/**"
|
|
13
|
+
- "blume.config.ts"
|
|
14
|
+
- "package.json"
|
|
15
|
+
- "package-lock.json"
|
|
16
|
+
- ".github/workflows/pages.yml"
|
|
17
|
+
workflow_dispatch:
|
|
18
|
+
|
|
19
|
+
permissions:
|
|
20
|
+
contents: read
|
|
21
|
+
pages: write
|
|
22
|
+
id-token: write
|
|
23
|
+
|
|
24
|
+
concurrency:
|
|
25
|
+
group: pages
|
|
26
|
+
cancel-in-progress: false
|
|
27
|
+
|
|
28
|
+
jobs:
|
|
29
|
+
build:
|
|
30
|
+
runs-on: ubuntu-latest
|
|
31
|
+
steps:
|
|
32
|
+
- uses: actions/checkout@v5
|
|
33
|
+
with:
|
|
34
|
+
fetch-depth: 0
|
|
35
|
+
- uses: actions/setup-node@v5
|
|
36
|
+
with:
|
|
37
|
+
node-version-file: .node-version
|
|
38
|
+
cache: npm
|
|
39
|
+
- run: npm ci
|
|
40
|
+
- run: npm run check
|
|
41
|
+
- run: |
|
|
42
|
+
cp -r src/tabledoc/schemas dist/schemas
|
|
43
|
+
rm -rf dist/schemas/legacy
|
|
44
|
+
- uses: actions/upload-pages-artifact@v4
|
|
45
|
+
with:
|
|
46
|
+
path: dist
|
|
47
|
+
|
|
48
|
+
deploy:
|
|
49
|
+
needs: build
|
|
50
|
+
runs-on: ubuntu-latest
|
|
51
|
+
environment:
|
|
52
|
+
name: github-pages
|
|
53
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
54
|
+
steps:
|
|
55
|
+
- id: deployment
|
|
56
|
+
uses: actions/deploy-pages@v5
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Builds a tagged release and publishes it to PyPI via trusted publishing.
|
|
4
|
+
# Decoupled from release.yml so a publish failure (e.g. a trusted-publisher
|
|
5
|
+
# misconfiguration) does not strand an already-created release: re-run this
|
|
6
|
+
# workflow with the tag to retry the upload.
|
|
7
|
+
|
|
8
|
+
on:
|
|
9
|
+
workflow_dispatch:
|
|
10
|
+
inputs:
|
|
11
|
+
ref:
|
|
12
|
+
description: Git ref (tag) to build and publish to PyPI
|
|
13
|
+
required: true
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
publish:
|
|
17
|
+
runs-on: ubuntu-latest
|
|
18
|
+
permissions:
|
|
19
|
+
id-token: write
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v5
|
|
22
|
+
with:
|
|
23
|
+
ref: ${{ inputs.ref }}
|
|
24
|
+
|
|
25
|
+
- uses: astral-sh/setup-uv@v7
|
|
26
|
+
|
|
27
|
+
- run: uv build
|
|
28
|
+
|
|
29
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_dispatch:
|
|
5
|
+
|
|
6
|
+
jobs:
|
|
7
|
+
release:
|
|
8
|
+
runs-on: ubuntu-latest
|
|
9
|
+
permissions:
|
|
10
|
+
contents: write
|
|
11
|
+
actions: write
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v5
|
|
14
|
+
with:
|
|
15
|
+
fetch-depth: 0
|
|
16
|
+
|
|
17
|
+
- uses: python-semantic-release/python-semantic-release@v9
|
|
18
|
+
id: release
|
|
19
|
+
with:
|
|
20
|
+
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
21
|
+
|
|
22
|
+
# Publishing runs in a separate workflow so a failed upload can be
|
|
23
|
+
# retried against the tag without re-running semantic-release.
|
|
24
|
+
- if: steps.release.outputs.released == 'true'
|
|
25
|
+
run: gh workflow run publish.yml --ref main -f ref=${{ steps.release.outputs.tag }}
|
|
26
|
+
env:
|
|
27
|
+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
@@ -0,0 +1,23 @@
|
|
|
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
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v5
|
|
21
|
+
- uses: astral-sh/setup-uv@v7
|
|
22
|
+
- run: uv sync --python ${{ matrix.python }}
|
|
23
|
+
- run: uv run --no-sync pytest -q
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
22
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# CHANGELOG
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
## v0.2.0 (2026-11-21)
|
|
5
|
+
|
|
6
|
+
### Documentation
|
|
7
|
+
|
|
8
|
+
- Add the documentation site built with Blume ([#2](https://github.com/queria-io/tabledoc/pull/2),
|
|
9
|
+
[`6ae0f45`](https://github.com/queria-io/tabledoc/commit/6ae0f45226b14c62197e24fed1345c0a3f23f95e))
|
|
10
|
+
|
|
11
|
+
Serve docs/ (English) and docs/ja/ (Japanese) at tabledoc.queria.io with the JSON Schemas under
|
|
12
|
+
schemas/, from one Pages deployment.
|
|
13
|
+
|
|
14
|
+
### Features
|
|
15
|
+
|
|
16
|
+
- Tabledoc load writes the description into a DuckLake catalog's _meta schema
|
|
17
|
+
([#5](https://github.com/queria-io/tabledoc/pull/5),
|
|
18
|
+
[`1957812`](https://github.com/queria-io/tabledoc/commit/1957812e63e9261f853ec30c652aacb75711c394))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
## v0.1.0 (2026-11-17)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## v0.0.0 (2026-11-17)
|
|
25
|
+
|
|
26
|
+
### Chores
|
|
27
|
+
|
|
28
|
+
- Add the license
|
|
29
|
+
([`705af18`](https://github.com/queria-io/tabledoc/commit/705af18f4889d5fa4bc5c2bfe724c6226c20bad3))
|
tabledoc-0.2.0/CLAUDE.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
## Development
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
uv sync
|
|
7
|
+
uv run tabledoc --help
|
|
8
|
+
uv run pytest
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Docs (Blume, served at https://tabledoc.queria.io):
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm ci
|
|
15
|
+
npm run dev
|
|
16
|
+
npm run check # blume build --strict && blume validate --strict
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`docs/spec.md` is the specification; change it first, then the code. English is the source and `docs/ja/` mirrors every page in Japanese (plain です・ます, 「バージョン」 not 「版」). Change both in the same PR.
|
|
20
|
+
|
|
21
|
+
The JSON Schemas in `src/tabledoc/schemas` are served at https://queria-io.github.io/tabledoc/schemas/ and their URLs never change. Adding a key keeps the version; changing what a key means or removing one makes v2.
|
|
22
|
+
|
|
23
|
+
## Code style
|
|
24
|
+
|
|
25
|
+
- Python 3.10+: `X | Y` unions are fine; nothing newer
|
|
26
|
+
- Comments, docstrings, CLI messages and commit messages in English
|
|
27
|
+
- Reading is deterministic: the same files give the same records, keys in the same order
|
|
28
|
+
|
|
29
|
+
## Commits and releases
|
|
30
|
+
|
|
31
|
+
Conventional Commits. python-semantic-release (manual `Release` workflow) sets the version from them: `fix:` patch, `feat:` minor. Do not edit the version in pyproject.toml or CHANGELOG.md by hand.
|
tabledoc-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 flo8s
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
tabledoc-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: tabledoc
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Describe the tables of a dataset in YAML and Markdown (or dbt), check it, and read it from Python
|
|
5
|
+
Project-URL: Homepage, https://github.com/queria-io/tabledoc
|
|
6
|
+
Project-URL: Repository, https://github.com/queria-io/tabledoc
|
|
7
|
+
Project-URL: Changelog, https://github.com/queria-io/tabledoc/blob/main/CHANGELOG.md
|
|
8
|
+
Author: flo8s
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Requires-Dist: duckdb>=1.1
|
|
13
|
+
Requires-Dist: jsonschema>=4.18
|
|
14
|
+
Requires-Dist: pyyaml>=6.0
|
|
15
|
+
Requires-Dist: referencing>=0.30
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
<p align="center"><img src="public/icon.svg" width="96" alt=""></p>
|
|
19
|
+
|
|
20
|
+
# tabledoc
|
|
21
|
+
|
|
22
|
+
[日本語](README.ja.md)
|
|
23
|
+
|
|
24
|
+
tabledoc reads the description of a dataset that people write in YAML and Markdown (or in a dbt project's yml), checks it, and reads it for other programs.
|
|
25
|
+
|
|
26
|
+
- One YAML file per table, next to a Markdown guide. Keys follow dbt's `models:` entries
|
|
27
|
+
- Semantics (join keys, dimensions, metrics) follow dbt's semantic layer
|
|
28
|
+
- In a dbt project, descriptions, SQL and lineage come from `target/manifest.json`
|
|
29
|
+
- From Python, `tabledoc.read` returns the checked description, with the guides and the files they link to by path and sha256
|
|
30
|
+
- `tabledoc load` writes the description into a DuckLake catalog as the tables of its `_meta` schema, so it travels with the data
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
uv tool install tabledoc # or: pip install tabledoc
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Use
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
tabledoc.yml the dataset
|
|
42
|
+
README.md its overview
|
|
43
|
+
sales/orders.yml the table sales.orders
|
|
44
|
+
sales/orders.md its guide
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```yaml
|
|
48
|
+
# tabledoc.yml
|
|
49
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/dataset/v1.json
|
|
50
|
+
name: shop
|
|
51
|
+
title: Shop sales
|
|
52
|
+
language: en
|
|
53
|
+
licenses: [CC-BY-4.0]
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```yaml
|
|
57
|
+
# sales/orders.yml
|
|
58
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/table/v1.json
|
|
59
|
+
title: Orders
|
|
60
|
+
description: One row is one order.
|
|
61
|
+
primary_key: [order_id]
|
|
62
|
+
columns:
|
|
63
|
+
- name: order_id
|
|
64
|
+
entity: primary
|
|
65
|
+
- name: ordered_at
|
|
66
|
+
dimension: time
|
|
67
|
+
granularity: day
|
|
68
|
+
metrics:
|
|
69
|
+
- name: revenue
|
|
70
|
+
agg: sum
|
|
71
|
+
expr: amount
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
tabledoc validate # check
|
|
76
|
+
tabledoc load --ducklake work.sqlite # check, then write it into the catalog's _meta schema
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
In a dbt project, run `dbt compile` first, and write `tabledoc.yml` next to `dbt_project.yml`.
|
|
80
|
+
|
|
81
|
+
## Specification
|
|
82
|
+
|
|
83
|
+
The documentation and the specification are at [tabledoc.queria.io](https://tabledoc.queria.io) (source: [docs/spec.md](docs/spec.md)). The JSON Schemas are in [src/tabledoc/schemas](src/tabledoc/schemas) and served at `https://queria-io.github.io/tabledoc/schemas/`.
|
|
84
|
+
|
|
85
|
+
## License
|
|
86
|
+
|
|
87
|
+
MIT
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
<p align="center"><img src="public/icon.svg" width="96" alt=""></p>
|
|
2
|
+
|
|
3
|
+
# tabledoc
|
|
4
|
+
|
|
5
|
+
[English](README.md)
|
|
6
|
+
|
|
7
|
+
tabledoc は、人が YAML と Markdown (または dbt のプロジェクトの yml) で書くデータセットの説明を検査し、ほかのプログラムのために読むツールです。
|
|
8
|
+
|
|
9
|
+
- テーブルごとに YAML を 1 つ書き、隣に Markdown のガイドを置きます。キーは dbt の `models:` の項目と同じです
|
|
10
|
+
- semantic (結合キー・ディメンション・メトリクス) は dbt のセマンティックレイヤーの書き方にそろえています
|
|
11
|
+
- dbt のプロジェクトでは、説明・SQL・依存関係を `target/manifest.json` から取ります
|
|
12
|
+
- Python からは `tabledoc.read` で、検査した説明を読めます。ガイドとそこから参照するファイルはパスと sha256 で並べます
|
|
13
|
+
- `tabledoc load` は説明を DuckLake のカタログの `_meta` スキーマのテーブルとして書きます。説明はデータと一緒に配布されます
|
|
14
|
+
|
|
15
|
+
## インストール
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
uv tool install tabledoc # または pip install tabledoc
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 使い方
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
tabledoc.yml データセット
|
|
25
|
+
README.md データセットの概要
|
|
26
|
+
sales/orders.yml テーブル sales.orders
|
|
27
|
+
sales/orders.md そのガイド
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
# tabledoc.yml
|
|
32
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/dataset/v1.json
|
|
33
|
+
name: shop
|
|
34
|
+
title: 店舗の売上
|
|
35
|
+
language: ja
|
|
36
|
+
licenses: [CC-BY-4.0]
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
# sales/orders.yml
|
|
41
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/table/v1.json
|
|
42
|
+
title: 注文
|
|
43
|
+
description: 1 行が 1 件の注文です。
|
|
44
|
+
primary_key: [order_id]
|
|
45
|
+
columns:
|
|
46
|
+
- name: order_id
|
|
47
|
+
entity: primary
|
|
48
|
+
- name: ordered_at
|
|
49
|
+
dimension: time
|
|
50
|
+
granularity: day
|
|
51
|
+
metrics:
|
|
52
|
+
- name: revenue
|
|
53
|
+
agg: sum
|
|
54
|
+
expr: amount
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
tabledoc validate # 検査する
|
|
59
|
+
tabledoc load --ducklake work.sqlite # 検査して、カタログの _meta スキーマに書く
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
dbt のプロジェクトでは先に `dbt compile` を実行し、`dbt_project.yml` の隣に `tabledoc.yml` を書きます。
|
|
63
|
+
|
|
64
|
+
## 仕様
|
|
65
|
+
|
|
66
|
+
ドキュメントと仕様は [tabledoc.queria.io/ja](https://tabledoc.queria.io/ja) にあります (元のファイルは [docs/ja/spec.md](docs/ja/spec.md))。JSON Schema は [src/tabledoc/schemas](src/tabledoc/schemas) にあり、`https://queria-io.github.io/tabledoc/schemas/` で配っています。
|
|
67
|
+
|
|
68
|
+
## ライセンス
|
|
69
|
+
|
|
70
|
+
MIT
|
tabledoc-0.2.0/README.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
<p align="center"><img src="public/icon.svg" width="96" alt=""></p>
|
|
2
|
+
|
|
3
|
+
# tabledoc
|
|
4
|
+
|
|
5
|
+
[日本語](README.ja.md)
|
|
6
|
+
|
|
7
|
+
tabledoc reads the description of a dataset that people write in YAML and Markdown (or in a dbt project's yml), checks it, and reads it for other programs.
|
|
8
|
+
|
|
9
|
+
- One YAML file per table, next to a Markdown guide. Keys follow dbt's `models:` entries
|
|
10
|
+
- Semantics (join keys, dimensions, metrics) follow dbt's semantic layer
|
|
11
|
+
- In a dbt project, descriptions, SQL and lineage come from `target/manifest.json`
|
|
12
|
+
- From Python, `tabledoc.read` returns the checked description, with the guides and the files they link to by path and sha256
|
|
13
|
+
- `tabledoc load` writes the description into a DuckLake catalog as the tables of its `_meta` schema, so it travels with the data
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
uv tool install tabledoc # or: pip install tabledoc
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Use
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
tabledoc.yml the dataset
|
|
25
|
+
README.md its overview
|
|
26
|
+
sales/orders.yml the table sales.orders
|
|
27
|
+
sales/orders.md its guide
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
# tabledoc.yml
|
|
32
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/dataset/v1.json
|
|
33
|
+
name: shop
|
|
34
|
+
title: Shop sales
|
|
35
|
+
language: en
|
|
36
|
+
licenses: [CC-BY-4.0]
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
# sales/orders.yml
|
|
41
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/table/v1.json
|
|
42
|
+
title: Orders
|
|
43
|
+
description: One row is one order.
|
|
44
|
+
primary_key: [order_id]
|
|
45
|
+
columns:
|
|
46
|
+
- name: order_id
|
|
47
|
+
entity: primary
|
|
48
|
+
- name: ordered_at
|
|
49
|
+
dimension: time
|
|
50
|
+
granularity: day
|
|
51
|
+
metrics:
|
|
52
|
+
- name: revenue
|
|
53
|
+
agg: sum
|
|
54
|
+
expr: amount
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
tabledoc validate # check
|
|
59
|
+
tabledoc load --ducklake work.sqlite # check, then write it into the catalog's _meta schema
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
In a dbt project, run `dbt compile` first, and write `tabledoc.yml` next to `dbt_project.yml`.
|
|
63
|
+
|
|
64
|
+
## Specification
|
|
65
|
+
|
|
66
|
+
The documentation and the specification are at [tabledoc.queria.io](https://tabledoc.queria.io) (source: [docs/spec.md](docs/spec.md)). The JSON Schemas are in [src/tabledoc/schemas](src/tabledoc/schemas) and served at `https://queria-io.github.io/tabledoc/schemas/`.
|
|
67
|
+
|
|
68
|
+
## License
|
|
69
|
+
|
|
70
|
+
MIT
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { defineConfig } from "blume";
|
|
2
|
+
|
|
3
|
+
export default defineConfig({
|
|
4
|
+
title: "tabledoc",
|
|
5
|
+
description: "Checks the description of a dataset and reads it for other programs",
|
|
6
|
+
logo: "/icon.svg",
|
|
7
|
+
theme: {
|
|
8
|
+
accent: "#7846be",
|
|
9
|
+
},
|
|
10
|
+
deployment: {
|
|
11
|
+
site: "https://tabledoc.queria.io",
|
|
12
|
+
},
|
|
13
|
+
content: {
|
|
14
|
+
root: "docs",
|
|
15
|
+
},
|
|
16
|
+
i18n: {
|
|
17
|
+
defaultLocale: "en",
|
|
18
|
+
locales: [
|
|
19
|
+
{ code: "en", label: "English" },
|
|
20
|
+
{ code: "ja", label: "日本語" },
|
|
21
|
+
],
|
|
22
|
+
},
|
|
23
|
+
seo: {
|
|
24
|
+
og: {
|
|
25
|
+
fonts: ["Noto Sans JP"],
|
|
26
|
+
},
|
|
27
|
+
},
|
|
28
|
+
});
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: tabledoc
|
|
3
|
+
sidebar:
|
|
4
|
+
label: Introduction
|
|
5
|
+
order: 1
|
|
6
|
+
description: Checks the description of a dataset written in YAML and Markdown (or a dbt project's yml) and reads it for other programs.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
tabledoc reads the description of a dataset that people write in YAML and Markdown (or in a dbt project's yml), checks it, and reads it for other programs.
|
|
10
|
+
|
|
11
|
+
- One YAML file per table, next to a Markdown guide. Keys follow dbt's `models:` entries
|
|
12
|
+
- Semantics (join keys, dimensions, metrics) follow dbt's semantic layer
|
|
13
|
+
- In a dbt project, descriptions, SQL and lineage come from `target/manifest.json`
|
|
14
|
+
- From Python, `tabledoc.read` returns the checked description, with the guides and the files they link to by path and sha256
|
|
15
|
+
- `tabledoc load` writes the description into a DuckLake catalog as the tables of its `_meta` schema, so it travels with the data
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
uv tool install tabledoc # or: pip install tabledoc
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Use
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
tabledoc.yml the dataset
|
|
27
|
+
README.md its overview
|
|
28
|
+
sales/orders.yml the table sales.orders
|
|
29
|
+
sales/orders.md its guide
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```yaml
|
|
33
|
+
# tabledoc.yml
|
|
34
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/dataset/v1.json
|
|
35
|
+
name: shop
|
|
36
|
+
title: Shop sales
|
|
37
|
+
language: en
|
|
38
|
+
licenses: [CC-BY-4.0]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```yaml
|
|
42
|
+
# sales/orders.yml
|
|
43
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/table/v1.json
|
|
44
|
+
title: Orders
|
|
45
|
+
description: One row is one order.
|
|
46
|
+
primary_key: [order_id]
|
|
47
|
+
columns:
|
|
48
|
+
- name: order_id
|
|
49
|
+
entity: primary
|
|
50
|
+
- name: ordered_at
|
|
51
|
+
dimension: time
|
|
52
|
+
granularity: day
|
|
53
|
+
metrics:
|
|
54
|
+
- name: revenue
|
|
55
|
+
agg: sum
|
|
56
|
+
expr: amount
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
tabledoc validate # check
|
|
61
|
+
tabledoc load --ducklake work.sqlite # check, then write it into the catalog's _meta schema
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
In a dbt project, run `dbt compile` first, and write `tabledoc.yml` next to `dbt_project.yml`.
|
|
65
|
+
|
|
66
|
+
## Specification
|
|
67
|
+
|
|
68
|
+
The [specification](/spec) defines the files, the checks and what `tabledoc.read` returns. The JSON Schemas are served at `https://queria-io.github.io/tabledoc/schemas/`.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: tabledoc
|
|
3
|
+
sidebar:
|
|
4
|
+
label: はじめに
|
|
5
|
+
order: 1
|
|
6
|
+
description: YAML と Markdown (または dbt のプロジェクトの yml) で書いたデータセットの説明を検査し、ほかのプログラムのために読みます。
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
tabledoc は、人が YAML と Markdown (または dbt のプロジェクトの yml) で書くデータセットの説明を検査し、ほかのプログラムのために読むツールです。
|
|
10
|
+
|
|
11
|
+
- テーブルごとに YAML を 1 つ書き、隣に Markdown のガイドを置きます。キーは dbt の `models:` の項目と同じです
|
|
12
|
+
- semantic (結合キー・ディメンション・メトリクス) は dbt のセマンティックレイヤーの書き方にそろえています
|
|
13
|
+
- dbt のプロジェクトでは、説明・SQL・依存関係を `target/manifest.json` から取ります
|
|
14
|
+
- Python からは `tabledoc.read` で、検査した説明を読めます。ガイドとそこから参照するファイルはパスと sha256 で並べます
|
|
15
|
+
- `tabledoc load` は説明を DuckLake のカタログの `_meta` スキーマのテーブルとして書きます。説明はデータと一緒に配布されます
|
|
16
|
+
|
|
17
|
+
## インストール
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
uv tool install tabledoc # または pip install tabledoc
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 使い方
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
tabledoc.yml データセット
|
|
27
|
+
README.md データセットの概要
|
|
28
|
+
sales/orders.yml テーブル sales.orders
|
|
29
|
+
sales/orders.md そのガイド
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```yaml
|
|
33
|
+
# tabledoc.yml
|
|
34
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/dataset/v1.json
|
|
35
|
+
name: shop
|
|
36
|
+
title: 店舗の売上
|
|
37
|
+
language: ja
|
|
38
|
+
licenses: [CC-BY-4.0]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```yaml
|
|
42
|
+
# sales/orders.yml
|
|
43
|
+
$schema: https://queria-io.github.io/tabledoc/schemas/table/v1.json
|
|
44
|
+
title: 注文
|
|
45
|
+
description: 1 行が 1 件の注文です。
|
|
46
|
+
primary_key: [order_id]
|
|
47
|
+
columns:
|
|
48
|
+
- name: order_id
|
|
49
|
+
entity: primary
|
|
50
|
+
- name: ordered_at
|
|
51
|
+
dimension: time
|
|
52
|
+
granularity: day
|
|
53
|
+
metrics:
|
|
54
|
+
- name: revenue
|
|
55
|
+
agg: sum
|
|
56
|
+
expr: amount
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
tabledoc validate # 検査する
|
|
61
|
+
tabledoc load --ducklake work.sqlite # 検査して、カタログの _meta スキーマに書く
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
dbt のプロジェクトでは先に `dbt compile` を実行し、`dbt_project.yml` の隣に `tabledoc.yml` を書きます。
|
|
65
|
+
|
|
66
|
+
## 仕様
|
|
67
|
+
|
|
68
|
+
ファイル・検査・`tabledoc.read` が返す値は[仕様](/ja/spec)で定めています。JSON Schema は `https://queria-io.github.io/tabledoc/schemas/` で配っています。
|