Column descriptions in dbt

Introduction

Column descriptions help explain what each column in your data means. This makes your data easier to understand for everyone.

When you want to share your data model with teammates who are new to the project.

When you need to document what each column represents in a table or model.

When you want to improve data quality by making column purposes clear.

When you prepare data for reports or dashboards and want to add context.

When you maintain your data models over time and want to avoid confusion.

Syntax

dbt

columns:
  - name: column_name
    description: "Description of what this column means or contains."

Descriptions are added inside the model's YAML file under the columns section.

Each column has a name and a description field.

Examples

This describes the user_id column as a unique ID for users.

dbt

columns:
  - name: user_id
    description: "Unique identifier for each user."

This explains that order_date stores the date of an order.

dbt

columns:
  - name: order_date
    description: "Date when the order was placed."

This clarifies that total_amount is the order's price in dollars.

dbt

columns:
  - name: total_amount
    description: "Total price of the order in USD."

Sample Program

This YAML snippet shows how to add descriptions to columns in a dbt model named orders. Each column has a clear explanation to help users understand the data.

dbt

version: 2
models:
  - name: orders
    description: "Table containing customer orders."
    columns:
      - name: order_id
        description: "Unique ID for each order."
      - name: customer_id
        description: "ID of the customer who placed the order."
      - name: order_date
        description: "Date when the order was made."
      - name: total_amount
        description: "Total cost of the order in USD."

Important Notes

Descriptions appear in dbt documentation sites and help with data cataloging.

Keep descriptions short and clear for best results.

You can update descriptions anytime to keep documentation current.

Summary

Column descriptions explain what each column means.

They are added in the YAML file under the columns section.

Good descriptions make data easier to use and share.