What you will be able to do
- Identify which jobs and environments feed metadata into dbt Catalog, and why CI jobs do not
- Predict what happens when
dbt docs generateis added as a step in a dbt platform job running v2 - Choose job commands so that Catalog shows lineage, test results, source freshness and column statistics
- Keep Catalog metadata from being removed by model deletion or environment inactivity
Key concept
Catalog is populated by job runs — In the dbt platform, nobody builds or hosts documentation. Each run of a v2 job in a production or staging environment refreshes the metadata that Catalog displays, and the job's commands decide which metadata exists.
1.Which jobs feed Catalog
Catalog is the documentation experience in the dbt platform, available on Starter, Enterprise and Enterprise+ plans. In Catalog you search resources, follow the lineage graph, and open a model to see its description, columns, tests and recent run results. It always shows your project's latest production state. Because of that, "generating documentation" here means running the right job in the right environment. There is no site to build and nothing to deploy.
The environment matters first. Catalog reads metadata through the Discovery API, and that metadata comes from the deployment environments you have designated as production or staging. After every job run in one of those environments, Catalog fetches the update automatically. Before anything appears, you need at least one successful job run there. Setting up such an environment is covered in [creating a deployment environment](lesson:3.5).
The job type matters as well. Deploy jobs and merge jobs both update Catalog. CI jobs never do, even when they run against the same project. A CI run builds a pull request's changes into a temporary schema, so its results describe code that has not shipped. Letting it overwrite production documentation would make Catalog describe a state that does not exist. For the same reason, a team that only runs [CI jobs with deferral](lesson:4.1) on a new project will find Catalog empty until a deploy job runs.
Anyone with a Developer or read-only seat can open Catalog. To share documentation with stakeholders who never write dbt code, give them read-only seats. You don't need a separate docs site.
Checkpoint 1 of 8· Check yourself
A team has a staging environment with a nightly deploy job, a merge job on main, and a CI job that runs on every pull request. Which runs refresh what Catalog shows?
Catalog picks up runs of deploy and merge jobs in production or staging environments. CI jobs are excluded because they don't reflect the production state.
“This includes deploy and merge jobs. Note that CI jobs don't update Catalog.”Source: docs.getdbt.com
Checkpoint 2 of 8· Exam question
A dbt Cloud project has three deploy jobs, each running `dbt build` and each configured with the "Generate docs on run" setting enabled. The admin team wants exactly one job's output to be treated as the authoritative source for the project's Catalog page, instead of whichever job happens to finish last. Where should the admin designate that job?
Correct answer: A — Open Account settings, select the project, edit it, and choose the job under the Artifacts setting.
- A. The project's Artifacts setting under Account settings is exactly where a single job is designated as the source of the project's documentation, which is what makes the Catalog page authoritative rather than dependent on whichever job last happened to run docs generation.
- B. Leaving the checkbox enabled on all three jobs does not designate an authoritative source; the Catalog would keep reflecting whichever of the three jobs most recently completed successfully, which is the exact ambiguity the admin wants to remove.
- C. There is no environment-level toggle that selects a project's authoritative documentation job; that assignment lives in the project's Artifacts configuration, not in environment settings.
- D. Running `dbt docs generate` as a chained command in all three jobs still leaves three separate jobs producing documentation artifacts, so it does not answer which one is treated as authoritative for the Catalog page.
2.What a docs step does inside a platform job
A v2 job doesn't need a docs command. Every run already refreshes Catalog metadata. This includes catalog.json, the artifact that holds warehouse details such as column types and table statistics. Locally you would produce it by adding the --write-catalog flag to dbt build, dbt run, dbt parse or dbt compile. In platform jobs on v2, the flag is added for you.
Checkpoint 3 of 8· Fill the gap
When you run dbt v2 on your own machine, which flag makes this build also produce catalog.json?
dbt build ? --write-catalog generates catalog.json and does nothing else to build a site. --write-index and --no-compile belong to the dbt Docs v2 site workflow.
dbt docs generate has a different job: it builds dbt Docs v2, a static site of HTML plus Parquet artifacts that you serve yourself. That only works locally or in your own pipeline. In the dbt platform, the step is silently replaced by dbt compile --write-catalog, and the run has no index.html to show. Teams migrating old job definitions are often surprised by this. The step still passes, but the static site it used to produce no longer exists.
--write-catalog flag compared with the dbt docs generate command| Aspect | --write-catalog flag | dbt docs generate command |
|---|---|---|
| What it produces | catalog.json, plus the artifacts the command already generates | index.html, assets/, and the index files |
| What it's for | Metadata for Catalog and the metadata APIs | A static site you can preview with dbt docs serve or host anywhere |
| Where it works | Locally and in dbt platform; added automatically in platform jobs on v2 | Locally only in v2; platform job runs use dbt compile --write-catalog instead |
Sometimes you want Catalog's warehouse metadata refreshed without rebuilding anything. Say a table was altered outside dbt and its column list in Catalog is stale. For that case, put dbt compile --write-catalog in the job's Commands section. It refreshes metadata without materialising a single model.
Checkpoint 4 of 8· Check yourself
A column was added directly in the warehouse to a table that dbt manages. You want Catalog to show the new column tonight without rebuilding any models. What should the job run?
Compiling with --write-catalog refreshes catalog metadata and builds nothing. docs serve is a local preview tool, and CI jobs never update Catalog.
“To refresh Catalog metadata without building models, add dbt compile --write-catalog in the Commands section.”Source: docs.getdbt.com
Checkpoint 5 of 8· Exam question
Which two artifacts does running `dbt docs generate` produce, and which together power the dbt Catalog and dbt Docs pages?(Select 2)
Correct answers: A, B — catalog.json; manifest.json
- A. This artifact holds the warehouse metadata, such as column types and table statistics, that the documentation UI displays for each database object.
- B. This artifact holds the compiled project structure, including models, sources, and their dependency relationships, which drives the lineage graph and node details shown in the UI.
- C. This artifact records timing and pass/fail results from the most recent invocation, which is used for run history and state comparisons, not for rendering the documentation UI itself.
- D. This is not one of the artifacts produced by `dbt docs generate`; source freshness information is captured separately and is not required to render the documentation UI.
3.Choosing commands so Catalog is complete
Every run refreshes Catalog, but the commands decide what it refreshes. A model gets lineage, details and results in Catalog when two conditions both hold. It must exist in the manifest, and it must appear in the run_results of a dbt build, dbt run or dbt clone. That second condition holds whether the run succeeded or failed. Data test results appear only when tests ran. Freshness results appear only when freshness was checked.
| To view in Catalog | The job must run |
|---|---|
| All metadata | dbt build and dbt source freshness together, in the same job |
| Model lineage, details, or results | dbt run or dbt build on that model |
| Columns and statistics for models, sources, and snapshots | Any job run in the environment (v2 refreshes this automatically) |
| Data test and unit test results | dbt test or dbt build |
| Source freshness results | dbt source freshness |
| Snapshot details / Seed details | dbt snapshot or dbt build / dbt seed or dbt build |
The first row explains a common gap. A production job that runs only dbt build still populates lineage and tests, but freshness never appears in Catalog. You can add dbt source freshness to the command list, or enable the Run source freshness checkbox, which invokes the command before the rest of the job. The two differ when freshness fails. Built-in commands are [chained run steps](lesson:4.2), so a failing command stops the chain and the job ends in Error. A failure from the checkbox step does not stop the job, which can still succeed if the later steps pass.
Unit test results rarely appear in a production Catalog, even with dbt build in the job. Unit tests usually run in development or CI environments, and CI runs don't reach Catalog.
Checkpoint 6 of 8· Match them up
Match each kind of Catalog metadata to the command a job needs to run for it to appear
Tap a term, then the definition that fits it.
Catalog only shows the metadata that some command produced. Column statistics are the exception, because v2 refreshes them on every run.
“The resulting metadata depends on the commands executed by the jobs.”Source: docs.getdbt.com
Checkpoint 7 of 8· Exam question
A production job runs `dbt build` across the full project and also has "Generate docs on run" enabled. The team notices this job frequently runs out of memory and takes a long time to complete, and the docs step sometimes never gets reached. Following recommended job design, what should the admin do to reliably populate the Catalog page without destabilizing the production build?
Correct answer: A — Create a dedicated job that runs a lightweight command such as `dbt compile` and enable documentation generation only there.
- A. Splitting documentation generation into its own job that runs a minimal command avoids competing for memory with the full production build, which is the recommended pattern for reliably keeping the Catalog page populated.
- B. Raising thread count increases warehouse concurrency for `dbt build` but does not reduce the memory pressure inside the dbt process that is causing the out-of-memory condition, so the docs step remains at risk.
- C. Dropping tests from the production job changes what gets validated but does not address the root cause of the memory exhaustion, and it still leaves documentation generation bundled with an unstable job.
- D. Running the same unstable job more often does not fix the underlying resource contention; it just increases the chance that instability affects the warehouse and the job schedule without resolving the memory issue.
4.When Catalog metadata disappears
Catalog metadata is removed in two ways, and only one of them is something you intend. The first is deleting a model from the project. Its entry stays in Catalog until the next job run that no longer includes it, and then it is gone. So a deleted model still showing in Catalog usually means no production job has run since the merge.
The second is inactivity. If a production or staging environment has had no job runs for 3 months, all of that environment's metadata is purged. This can hit environments that only run on demand, such as a quarterly finance project or a staging environment nobody triggers. The protection is a [scheduled job](lesson:4.3) that runs at least once every 3 months. Once metadata is in place, [exploring lineage in Catalog](lesson:8.1) depends on these runs continuing.
Checkpoint 8 of 8· Check yourself
A staging environment's only job was paused in January. In mid-April, users report that Catalog shows nothing for that environment. What happened?
Inactivity of 3 months purges an environment's metadata. Scheduling a run at least once every 3 months prevents it.
“If an environment has had no job runs in the past 3 months, all metadata for that environment is purged.”Source: docs.getdbt.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A CI job that builds every model on each pull request keeps Catalog up to date.Why is that wrong?
CI jobs never update Catalog, because they don't reflect the production state. Only deploy and merge job runs in production or staging environments do.
Covered in Which jobs feed Catalog
2.A platform job needs a
dbt docs generatestep, or Catalog will not be populated.Why is that wrong?v2 jobs refresh Catalog metadata on every run. A
dbt docs generatestep is unnecessary, and the platform replaces it withdbt compile --write-catalog.Covered in What a docs step does inside a platform job
3.Adding
dbt docs generateto a platform job produces a static docs site you can open from the run.Why is that wrong?dbt Docs v2 static sites are local or self-hosted only. In a platform job, the step produces no static site and no index.html.
Covered in What a docs step does inside a platform job
4.A job that runs only
dbt buildgives Catalog all of its metadata.Why is that wrong?Complete metadata needs
dbt buildanddbt source freshnesstogether in the same job. Without the freshness command, Catalog has no freshness results.Covered in Choosing commands so Catalog is complete
Practise it for real
Configure a production deploy job so that its runs populate Catalog with complete metadata, then confirm the result in Catalog.
1.Click Deploy in the top left and select Jobs. Then open (or create) a job whose environment is production or staging, and click Settings.
Why: Catalog only reads metadata from production or staging deployment environments.
You should see: The job's settings page shows its environment as production or staging.
2.Under Execution settings, set the commands to
dbt build, and enable Run source freshness (or adddbt source freshnessas a command). Click Save.Why: Running build and source freshness together is what gives Catalog all of its metadata. No docs command is needed on v2.
You should see: The command list shows
dbt build, with freshness enabled, and nodbt docs generatestep.3.Trigger a run of the job and wait for it to finish.
Why: Catalog fetches metadata after each run in the environment.
You should see: The run history shows a new run with its run steps and artifacts.
4.Click Catalog in the navigation, select your project, click View lineage, and open a model.
Why: This confirms that lineage, descriptions, columns and test results arrived from the run.
You should see: The model shows its description, columns, tests and recent run results. Its sources show freshness results.
Stuck? Get a nudge
If freshness results are missing, check whether the source freshness command actually ran in the same job as dbt build.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The default documentation experience in dbt is Catalog, available on Starter, Enterprise, or Enterprise+ plans.”
↩︎ Which jobs feed Catalog“Catalog is available to Developer and read-only users.”
↩︎ Which jobs feed Catalog“dbt Docs v2 isn't available in the dbt platform.”
↩︎ What a docs step does inside a platform job“Jobs running v2 generate this metadata automatically on every job run”
↩︎ Key concept“If you add dbt docs generate as a run step, dbt runs dbt compile --write-catalog instead and displays a banner directing you to Catalog.”
↩︎ Prediction“To refresh Catalog metadata without building models, add dbt compile --write-catalog in the Commands section.”
↩︎ Checkpoint - 2.
“Catalog automatically retrieves the metadata updates after each job run in the production or staging deployment environment”
↩︎ Which jobs feed Catalog“Catalog uses the metadata provided by the Discovery API to display the details about the state of your dbt project.”
↩︎ Which jobs feed Catalog“You have at least one successful job run in the deployment environment.”
↩︎ Which jobs feed Catalog“The model appears in the run_results of a dbt build, dbt run, or dbt clone command, regardless of the run's success or failure status.”
↩︎ Choosing commands so Catalog is complete“Unit tests are typically run in development or CI environments, so their results rarely appear in production Catalog.”
↩︎ Choosing commands so Catalog is complete“its metadata is removed after a subsequent job run in which the model is no longer included.”
↩︎ When Catalog metadata disappears“To prevent this, schedule jobs to run at least once every 3 months.”
↩︎ When Catalog metadata disappears“This is because they don't reflect the production state and don't provide the necessary metadata updates.”
↩︎ Exam trap 1“dbt build and dbt source freshness together as part of the same job in the environment”
↩︎ Exam trap 4“This includes deploy and merge jobs. Note that CI jobs don't update Catalog.”
↩︎ Checkpoint“The resulting metadata depends on the commands executed by the jobs.”
↩︎ Checkpoint“If an environment has had no job runs in the past 3 months, all metadata for that environment is purged.”
↩︎ Checkpoint - 3.https://docs.getdbt.com/reference/commands/cmd-docsOfficial docs
“dbt v2 jobs in dbt platform refresh Catalog metadata automatically on every run, so you don't need to add the --write-catalog flag there.”
↩︎ What a docs step does inside a platform job“The job doesn't produce the static site or index.html.”
↩︎ Exam trap 3 - 4.
“Check the Generate docs on run checkbox to configure the job to automatically generate project docs each time this job runs.”
↩︎ What a docs step does inside a platform job - 5.https://docs.getdbt.com/docs/deploy/deploy-jobsOfficial docs
“Enable this option to invoke the dbt source freshness command before running the deploy job.”
↩︎ Choosing commands so Catalog is complete“If the step fails, the job can succeed if subsequent steps pass.”
↩︎ Choosing commands so Catalog is complete - 6.https://docs.getdbt.com/docs/deploy/artifactsOfficial docs
“The following steps are for legacy dbt Docs only.”
↩︎ When Catalog metadata disappears“you should only associate one production job with a given project to produce the project's artifacts.”
↩︎ When Catalog metadata disappears
Also cited
“You don't need to add a docs command. Every job run refreshes Catalog metadata automatically.”
↩︎ Exam trap 2