dbt docs generate

What Is dbt docs generate?

dbt docs generate is a CLI command that compiles your project metadata into a searchable static site, letting teams explore lineage, columns, and tests without opening code.

Why Use dbt docs generate in Analytics Engineering?

Accurate, always-up-to-date documentation reduces onboarding time, surfaces broken contracts early, and satisfies data governance requirements.

How Does dbt docs generate Work Under the Hood?

The command parses your manifest.json, catalog.json, and run results, then writes HTML, JS, and JSON assets to a target directory.

Which Files Does dbt docs generate Read?

It uses manifest.json for DAG and metadata, catalog.json for column stats, and run_results.json for test outcomes.

How Do I Run dbt docs generate?

Navigate to your project root and run the command in the same environment used for dbt run.

Basic Command

dbt docs generate

This builds docs in target by default.

Specifying Target and Output Directory

dbt docs generate --profiles-dir ~/.dbt --target prod --output-dir ./public_docs

Override where metadata is read and where HTML is written.

How Do I Serve and Share Generated Docs?

Use dbt docs serve for a localhost preview, then upload contents of the output directory to S3, GCS, GitHub Pages, or Vercel.

Example: Generating Docs for a Snowflake Project

# activate venv and set creds
source venv/bin/activate
export SNOWFLAKE_ROLE=TRANSFORMER
dbt run --target prod
dbt docs generate --target prod

Open target/index.html to explore lineage and tests.

Best Practices for dbt docs generate

Schedule docs generation after each production run, version docs per git tag, and enforce column descriptions via CI tests.

Common Pitfalls and How to Fix Them

Missing catalog.json often means dbt run was skipped; rerun models or pass --full-refresh to rebuild stats.

How Does Galaxy Enhance dbt docs Workflows?

Galaxy links directly from query results to the corresponding model in your generated docs, letting engineers jump from SQL to lineage in one click.

Key Takeaways

dbt docs generate produces shareable, self-service documentation that boosts team velocity and trust in data models.