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

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.