Skip to content
tabledoc
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.read returns 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 read
  • tabledoc load writes the description into a DuckLake catalog as ordinary tables of one schema (_tabledoc by default), so it travels with the data and is versioned with it by FDL. tabledoc dump writes 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/.

Was this page helpful?