01. YAML Descriptions
What Are YAML Descriptions in dbt?
YAML descriptions in dbt allow you to document your models, sources, columns, and tests in a structured way.
They make your dbt project readable, maintainable, and self-documented.
Why Use YAML Descriptions?
Improves data discoverability
Helps create clear data dictionaries
Generates interactive documentation in dbt Docs (dbt docs generate)
Makes onboarding easier for new team members
Where Are YAML Descriptions Defined?
- In
.ymlfiles (typically inside themodels/oranalyses/folder) - Common filenames:
schema.ymlsources.yml
YAML Structure Example
version: 2
models:
- name: orders
description: "This model cleans and transforms raw order data."
columns:
- name: order_id
description: "Unique identifier for each order."
- name: customer_id
description: "Reference to the customer placing the order."
- name: total_amount
description: "Total amount of the order in USD."
Adding Descriptions for Sources
version: 2
sources:
- name: raw
tables:
- name: orders
description: "Raw orders data from the source system."
columns:
- name: order_date
description: "Date when the order was placed."
Key Points to Remember
Use clear, concise descriptions
Always describe columns (especially key fields)
Keep YAML files organized by feature or domain
Run dbt docs generate && dbt docs serve to view documentation
Benefits in dbt Docs
- YAML descriptions appear in the interactive lineage graph
- Users can click on models and see documentation
- Great for data governance and auditing