tabledoc
Makes a dataset's tables readable by people and AI, from dbt's manifest and the descriptions people and AI write.
tabledoc makes a dataset’s tables readable by people and AI. It takes what dbt already knows about the tables (descriptions, SQL and lineage from target/manifest.json), adds what people and AI write in YAML and Markdown (titles, column descriptions, join keys, guides), checks the result, and writes it as Markdown files or as tables in a DuckLake catalog.
- One YAML file per table, next to a Markdown guide. Keys follow dbt’s
models:entries - Semantics (join keys, dimensions, metrics) follow dbt’s semantic layer
- In a dbt project, descriptions, SQL and lineage come from
target/manifest.json - From Python,
tabledoc.readreturns the checked description, with the guides and the files they link to by path and sha256 tabledoc export --markdown <folder>writes one Markdown file per table (columns, semantics, primary key, lineage, SQL and the guide) and one for the dataset that lists them, for AI assistants and people to readtabledoc loadwrites the description into a DuckLake catalog as ordinary tables of one schema (_tabledocby default), so it travels with the data and is versioned with it by FDL.tabledoc dumpwrites the files back from it
Install
uv tool install tabledoc # or: pip install tabledoc
Use
tabledoc.yml the dataset
README.md its overview
sales/orders.yml the table sales.orders
sales/orders.md its guide
# tabledoc.yml
$schema: https://tabledoc.queria.io/schemas/dataset/v1.json
name: shop
title: Shop sales
language: en
licenses: [CC-BY-4.0]
# sales/orders.yml
$schema: https://tabledoc.queria.io/schemas/table/v1.json
title: Orders
description: One row is one order.
primary_key: [order_id]
columns:
- name: order_id
entity: primary
- name: ordered_at
dimension: time
granularity: day
metrics:
- name: revenue
agg: sum
expr: amount
tabledoc validate # check
tabledoc load --ducklake work.sqlite # check, then write it into the catalog's _tabledoc schema
tabledoc dump --ducklake work.sqlite --out description/ # the files again, from the catalog
tabledoc export --markdown ai-docs/ # one Markdown file per table, for AI to read
In a dbt project, run dbt compile first, and write tabledoc.yml next to dbt_project.yml.
Specification
The specification defines the files, the checks and what tabledoc.read returns. The JSON Schemas are served at https://tabledoc.queria.io/schemas/.