Documenting models in YAML in dbt - Step-by-Step Execution

Concept Flow - Documenting models in YAML

Create YAML file

↓

Define model metadata

↓

Add descriptions and columns

↓

Save and run dbt docs generate

↓

View documentation in browser

This flow shows how to write model documentation in YAML, generate docs, and view them.

Execution Sample

dbt

version: 2
models:
  - name: customers
    description: "Customer details table"
    columns:
      - name: id
        description: "Unique customer ID"

This YAML snippet documents a model named 'customers' with a description and column info.

Execution Table

Step	Action	YAML Content	dbt Command	Result
1	Create YAML file	Empty file named schema.yml	N/A	File created
2	Add model metadata	version: 2 models: - name: customers description: "Customer details table" columns: - name: id description: "Unique customer ID"	N/A	YAML content added
3	Save file	schema.yml saved	N/A	File saved
4	Run dbt docs generate	N/A	dbt docs generate	Documentation site generated
5	Open docs site	N/A	dbt docs serve	Documentation visible in browser
6	Exit	N/A	N/A	Process complete

💡 Documentation generated and served successfully

Variable Tracker

Variable	Start	After Step 2	After Step 4	Final
schema.yml content	empty	model and columns defined	unchanged	unchanged
dbt docs site	not generated	not generated	generated	served and visible

Key Moments - 3 Insights

Why do we need to add descriptions under 'columns' in the YAML?

Descriptions under 'columns' explain each field in the model, making docs clearer. See execution_table step 2 where columns are defined.

What happens if we forget to run 'dbt docs generate' after editing YAML?

The documentation site won't update with new info. Step 4 in execution_table shows this command is needed to generate docs.

Can we document multiple models in one YAML file?

Yes, you list multiple models under 'models:' in the YAML. This is implied in step 2 where model metadata is added.

Visual Quiz - 3 Questions

Look at the execution_table, what is the YAML content after step 2?

A Documentation site generated

B Empty file

C Model name and description with columns

D File saved but empty

💡 Hint

Check the 'YAML Content' column in execution_table row for step 2

At which step does the documentation site become visible in the browser?

A Step 5

B Step 3

C Step 4

D Step 6

💡 Hint

Look at the 'Result' column in execution_table for step 5

If you add a new column description but skip 'dbt docs generate', what happens?

A New description appears immediately

B Documentation site does not show new description

C Documentation site updates automatically

D YAML file is deleted

💡 Hint

Refer to key_moments about the importance of running 'dbt docs generate'

Concept Snapshot

Document models in YAML with:
version: 2
models:
  - name: model_name
    description: "Model description"
    columns:
      - name: column_name
        description: "Column description"
Run 'dbt docs generate' to build docs, then 'dbt docs serve' to view.

Full Transcript

This visual execution shows how to document dbt models using YAML files. First, create a YAML file named schema.yml. Then add model metadata including the model name, description, and columns with their descriptions. Save the file. Next, run the command 'dbt docs generate' to build the documentation site. Finally, run 'dbt docs serve' to open the docs in a browser. The variable tracker shows the YAML content changes and when the docs site is generated. Key moments clarify why column descriptions matter and why running 'dbt docs generate' is necessary. The quiz tests understanding of YAML content at each step and the documentation generation process.