Column descriptions in dbt - Step-by-Step Execution

Concept Flow - Column descriptions

Define model SQL

↓

Add column descriptions in schema.yml

↓

Run dbt docs generate

↓

View docs site

↓

See column descriptions in docs

This flow shows how to add descriptions to columns in dbt models and view them in generated documentation.

Execution Sample

dbt

models/my_model.sql:
select id, name, created_at from source_table

schema.yml:
models:
  - name: my_model
    columns:
      - name: id
        description: "Unique identifier"
      - name: name
        description: "Name of the entity"

This code defines a model selecting columns and adds descriptions for those columns in the schema.yml file.

Execution Table

Step	Action	File Affected	Result
1	Write SQL model selecting columns	models/my_model.sql	Model created with columns: id, name, created_at
2	Add column descriptions in schema.yml	models/schema.yml	Descriptions added for id and name columns
3	Run 'dbt docs generate'	Command line	Documentation site generated with column descriptions
4	Open docs site in browser	Browser	Column descriptions visible under my_model columns
5	Check column without description	Docs site	created_at shows no description (empty)

💡 All columns with descriptions appear in docs; columns without descriptions show empty.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
model_columns	[]	[id, name, created_at]	[id, name, created_at]	[id, name, created_at]
column_descriptions	{}	{"id": "Unique identifier", "name": "Name of the entity"}	{"id": "Unique identifier", "name": "Name of the entity"}	{"id": "Unique identifier", "name": "Name of the entity"}
docs_generated	False	False	True	True

Key Moments - 2 Insights

Why does the created_at column show no description in the docs?

Because in the schema.yml file, only id and name columns have descriptions. created_at was not given a description, so it appears empty in the docs (see execution_table step 5).

Do column descriptions affect the SQL model output?

No, descriptions only add metadata for documentation. The SQL model output remains the same (see execution_table step 1 and 2).

Visual Quiz - 3 Questions

Look at the execution table, at which step are column descriptions added?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Check the 'Action' column in execution_table rows for when descriptions are added.

According to variable_tracker, what is the value of docs_generated after step 3?

A False

B Undefined

C True

D Null

💡 Hint

Look at the docs_generated row in variable_tracker after step 3.

If you add a description for created_at in schema.yml, what changes in the docs?

A created_at column will show its description

B No change, descriptions are ignored

C Model SQL will change

D Docs site will fail to generate

💡 Hint

Refer to key_moments about columns without descriptions and their effect on docs.

Concept Snapshot

dbt Column Descriptions:
- Add descriptions in schema.yml under models > columns
- Descriptions do not affect SQL output
- Run 'dbt docs generate' to build docs
- View descriptions in docs site
- Columns without descriptions show empty

Full Transcript

In dbt, you write SQL models selecting columns. To add descriptions for these columns, you edit the schema.yml file and list each column with a description. Running 'dbt docs generate' creates a documentation site where these descriptions appear. Columns without descriptions show no text in docs. Descriptions help explain columns but do not change the SQL output. This process helps teams understand data better by reading docs.