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.
Files changed (50) hide show
  1. tabledoc-0.2.0/.github/workflows/pages.yml +56 -0
  2. tabledoc-0.2.0/.github/workflows/publish.yml +29 -0
  3. tabledoc-0.2.0/.github/workflows/release.yml +27 -0
  4. tabledoc-0.2.0/.github/workflows/test.yml +23 -0
  5. tabledoc-0.2.0/.gitignore +10 -0
  6. tabledoc-0.2.0/.node-version +1 -0
  7. tabledoc-0.2.0/CHANGELOG.md +29 -0
  8. tabledoc-0.2.0/CLAUDE.md +31 -0
  9. tabledoc-0.2.0/LICENSE +21 -0
  10. tabledoc-0.2.0/PKG-INFO +87 -0
  11. tabledoc-0.2.0/README.ja.md +70 -0
  12. tabledoc-0.2.0/README.md +70 -0
  13. tabledoc-0.2.0/blume.config.ts +28 -0
  14. tabledoc-0.2.0/docs/index.md +68 -0
  15. tabledoc-0.2.0/docs/ja/index.md +68 -0
  16. tabledoc-0.2.0/docs/ja/spec.md +251 -0
  17. tabledoc-0.2.0/docs/spec.md +251 -0
  18. tabledoc-0.2.0/package-lock.json +12056 -0
  19. tabledoc-0.2.0/package.json +16 -0
  20. tabledoc-0.2.0/public/CNAME +1 -0
  21. tabledoc-0.2.0/public/apple-touch-icon.png +0 -0
  22. tabledoc-0.2.0/public/favicon.ico +0 -0
  23. tabledoc-0.2.0/public/icon-512.png +0 -0
  24. tabledoc-0.2.0/public/icon.svg +12 -0
  25. tabledoc-0.2.0/pyproject.toml +37 -0
  26. tabledoc-0.2.0/src/tabledoc/__init__.py +8 -0
  27. tabledoc-0.2.0/src/tabledoc/__main__.py +5 -0
  28. tabledoc-0.2.0/src/tabledoc/cli.py +78 -0
  29. tabledoc-0.2.0/src/tabledoc/dbt.py +182 -0
  30. tabledoc-0.2.0/src/tabledoc/description.py +207 -0
  31. tabledoc-0.2.0/src/tabledoc/files.py +128 -0
  32. tabledoc-0.2.0/src/tabledoc/git.py +43 -0
  33. tabledoc-0.2.0/src/tabledoc/legacy.py +87 -0
  34. tabledoc-0.2.0/src/tabledoc/lineage.py +150 -0
  35. tabledoc-0.2.0/src/tabledoc/load.py +186 -0
  36. tabledoc-0.2.0/src/tabledoc/meta.py +441 -0
  37. tabledoc-0.2.0/src/tabledoc/report.py +63 -0
  38. tabledoc-0.2.0/src/tabledoc/schemas/dataset/v1.json +114 -0
  39. tabledoc-0.2.0/src/tabledoc/schemas/legacy/dataset/v1.json +117 -0
  40. tabledoc-0.2.0/src/tabledoc/schemas/legacy/table/v1.json +56 -0
  41. tabledoc-0.2.0/src/tabledoc/schemas/table/v1.json +84 -0
  42. tabledoc-0.2.0/src/tabledoc/schemas/tabledoc/v1.json +145 -0
  43. tabledoc-0.2.0/src/tabledoc/schemas.py +47 -0
  44. tabledoc-0.2.0/src/tabledoc/shape.py +117 -0
  45. tabledoc-0.2.0/src/tabledoc/source.py +188 -0
  46. tabledoc-0.2.0/tests/conftest.py +22 -0
  47. tabledoc-0.2.0/tests/test_git.py +18 -0
  48. tabledoc-0.2.0/tests/test_load.py +212 -0
  49. tabledoc-0.2.0/tests/test_read.py +280 -0
  50. 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,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ target/
5
+ dist/
6
+ .pytest_cache/
7
+
8
+ # Docs (Blume)
9
+ node_modules/
10
+ .blume/
@@ -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))
@@ -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.
@@ -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
@@ -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/` で配っています。