Do I need to write descriptions in dbt first?

No. The workflow uses whatever descriptions already exist and writes plain-English definitions for the rest based on each table's columns and its place in your pipeline. It also tells you every week which tables still have no description, so your team can fill in the ones that matter most rather than all of them at once.

Will this create duplicate pages in Notion every week?

No. It looks for an existing page for each model by name before writing anything, and updates that page if it finds one. New pages are only created for models that are genuinely new, so the dictionary stays clean over months of running.

Why not just use the documentation site dbt already generates?

Built-in dbt docs are great for the data team, but business users tend to find them too technical and rarely visit them. This puts the same information in Notion, where marketing, finance, and sales already work, written in language they can actually read.

What happens if my production build fails that week?

The workflow only documents a run that finished successfully, so a broken build will never overwrite good definitions. It falls back to the most recent successful production run instead.

Can business users edit the Notion pages themselves?

Yes, they are normal Notion pages, so anyone can comment or add context. Keep in mind the definition section is refreshed each week, so any correction you want to keep permanently is best added as a description in dbt itself.

dbt to Notion data dictionary: plain-English docs for business users

Every Monday at 7am, rebuild a plain-English data dictionary for my dbt Cloud project in Notion, so business users can understand what our tables actually mean without asking the data team.

Start by finding the right run to document. Use dbt Cloud List Jobs to see the jobs on my account and identify the ones that build my production environment. Then use List Runs to find the most recent run of those jobs that finished successfully, checking that the run is complete and its status is Success (status code 10). Note that dbt Cloud wraps every response in a status and data envelope, so read the actual records from data. Never document a failed, cancelled, or still running build, because that would overwrite good definitions with broken ones.

Once you have that run, call List Run Artifacts to see what it produced, then use Retrieve Run Artifact to download manifest.json and catalog.json from it. Artifacts default to the last step of the run, which is what you want for a completed production build. Between them, these two files carry every model, its existing description, its columns and their types, and its upstream lineage.

Work through the models in the manifest, skipping dbt's own internal artifacts, test and seed nodes, and ephemeral models that never land as a real table. Prioritize models that exist in the production environment. For each model, write a short business-friendly definition covering: what this table represents in everyday language, who typically uses it (for example marketing, finance, or the sales team), which upstream sources and models feed it, and what each key column means. Translate warehouse jargon into language a marketer or finance analyst would understand, so a grain of one row per order line becomes something like one row for every individual item on a customer order. Where dbt already has a description, build on it rather than ignoring it.

Sync the results into my Notion data dictionary database. For each model, use Notion Search by Title to look for an existing page named after that model. If a page already exists, use Update a Page to refresh its properties and Append Block Children to write the current definition and column table, calling Retrieve Block Children first so you can see what is already on the page and avoid duplicating content that is there. If no page exists yet, use Create a Page in the data dictionary database. The goal is that the catalog stays current rather than accumulating duplicate pages week after week. Keep every page short and readable: one definition paragraph, a line naming the upstream sources, and a table of key columns with plain-English meanings. Never dump raw JSON onto a page.

Finish with a Slack Bot Send a Message summary to my data team channel. Tell me how many model pages were added versus updated, which models had their definitions change since last week, and which models still have no description in dbt so someone can go and fill those gaps. That last list matters most, because it is the nudge that keeps the dictionary improving over time.

What it does

Finds your most recent successful production build in dbt Cloud and reads the full list of models, their columns, and how they connect to each other.
Writes a short, plain-English definition for every table: what it represents, who typically uses it, where the data comes from, and what each key column means.
Keeps a Notion data dictionary up to date, refreshing existing entries instead of piling up duplicate pages every week.
Posts a Slack summary of what was added, what changed, and which tables still have no description, so your team knows exactly where the gaps are.

What you’ll need

A dbt Cloud account with a production job that builds your models on a schedule
Your production job set to generate documentation, so table and column details are available to read
A Notion workspace with a database to hold the data dictionary, shared with your Notion connection
A Slack workspace and a channel where your data team already talks

How to customize it

Change the schedule: run it daily if your models change often, or monthly if your project is stable.
Choose which models get documented, for example only your reporting tables, skipping staging and intermediate layers entirely.
Adjust how each definition reads, from a single sentence to a fuller explanation, depending on how technical your business users are.
Send the list of undocumented models to the owner of each model instead of the whole channel.

Use cases

Data Sync
Content Generation

Turn your dbt project into a plain-English data dictionary in Notion

Integrations

Type

Categories

What it does

What you’ll need

How to customize it

Use cases

FAQs

Related prompts