Building dbt Docs with an AI Agent
The project had 50% model coverage and 20% column coverage. The AI rewrote all of it in 17 minutes for $1.
OVERVIEW
dbt documentation is universally important and universally neglected. It's one of those things that everyone agrees should be done well, but few teams have the time or discipline to maintain properly. An overall score of 50% model coverage and 20% column coverage is more common than most data teams want to admit.
This demo audits an Airbnb dbt project's documentation, finds the gaps, and auto-writes descriptions for every undocumented model and column. The agent doesn't just fill in placeholder text. It reads the underlying SQL transformations to understand what each model actually does, then writes descriptions that explain the business logic, the upstream sources, the transformations applied, and the downstream consumers.
The generated descriptions are more complete than what most engineers write by hand. For a column like listing_count_classification, the agent reads the CASE statement in the SQL and documents the accepted values with their exact thresholds (inactive=0, single=1, small=2-5, medium=6-15, large=16+). For models, it includes where the data comes from, what joins are applied, and what feeds downstream, the kind of lineage context that takes real time to write manually. Total cost: $1.
WHAT YOU'LL LEARN
- →How to audit documentation coverage across an entire dbt project
- →Why AI-generated descriptions are often more complete than manually-written ones
- →How to document column accepted values from CASE statement logic in the SQL
- →How to validate documentation with dbt docs generate and the catalog
KEY POINTS
- Audits project: finds 50% model coverage, 20% column coverage across all layers
- Reads SQL transformations to write business-logic descriptions, not generic placeholders
- Documents accepted values by extracting thresholds from CASE statements
- Includes upstream/downstream lineage context in every model description
- Validates with dbt docs generate, all 12 models and 3 sources in catalog, zero errors
