Skip to main content

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 .yml files (typically inside the models/ or analyses/ folder)
  • Common filenames:
    • schema.yml
    • sources.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