How to Document a Model in dbt: Syntax and Examples

In dbt, you document a model by adding a description field inside the model's entry in the schema.yml file. This description helps explain the model's purpose and appears in the dbt documentation site.

Syntax

To document a model in dbt, you add an entry under the models key in your schema.yml file. Each model is identified by its name, and you provide a description to explain what the model does.

• models: The top-level key for model documentation.
• - name: The exact name of the model file without extension.
• description: A string describing the model's purpose.

yaml

models:
  - name: my_model
    description: "This model aggregates sales data by region and month."

Example

This example shows how to document a model named orders_summary in the schema.yml file. The description explains what the model does, which helps team members understand its role.

yaml

version: 2

models:
  - name: orders_summary
    description: "Summarizes total orders and revenue by customer segment and month."
    columns:
      - name: customer_segment
        description: "The segment category of the customer."
      - name: total_orders
        description: "Total number of orders placed."
      - name: total_revenue
        description: "Total revenue generated from orders."

Common Pitfalls

Common mistakes when documenting models in dbt include:

• Not matching the name exactly to the model file name (without .sql).
• Forgetting to add version: 2 at the top of the schema.yml file.
• Not running dbt docs generate after adding documentation, so changes don’t appear in the docs site.
• Leaving out column descriptions, which reduces documentation usefulness.

yaml

Incorrect example (missing version):
models:
  - name: sales_data
    description: "Aggregates sales by product."

Correct example:
version: 2
models:
  - name: sales_data
    description: "Aggregates sales by product."

Quick Reference

Field	Description
version	Specifies the schema file version, must be 2 for model docs
models	List of models to document
name	Model file name without .sql
description	Text describing the model's purpose
columns	List of columns with their names and descriptions

Key Takeaways

Always add a description for each model in the schema.yml file under the models key.

Ensure the model name matches the SQL file name exactly without the extension.

Include version: 2 at the top of your schema.yml file for documentation to work.

Document columns with descriptions to improve clarity for users.

Run dbt docs generate to update the documentation site after changes.