Why Doc blocks for reusable descriptions in dbt? - Purpose & Use Cases

The Big Idea

What if you could fix messy data docs with just one simple trick?

The Scenario

Imagine you have many data models and columns in your project. You want to explain what each column means, but you have to write the same description again and again for similar columns in different models.

The Problem

Writing descriptions manually for every column is slow and boring. It's easy to make mistakes or forget to update some descriptions. This causes confusion for anyone reading your data documentation.

The Solution

Doc blocks let you write a description once and reuse it everywhere. This keeps your documentation consistent and saves time. When you update the doc block, all places using it update automatically.

Before vs After

✗ Before

description: 'User ID representing the unique identifier for a user'
description: 'User ID representing the unique identifier for a user'

✓ After

docs:
  user_id: 'User ID representing the unique identifier for a user'

columns:
  - name: user_id
    description: "{{ doc('user_id') }}"
  - name: creator_id
    description: "{{ doc('user_id') }}"

What It Enables

You can maintain clear, consistent, and up-to-date data documentation effortlessly across your entire project.

Real Life Example

A data analyst quickly understands that both user_id and creator_id columns refer to the same concept without confusion, thanks to shared doc blocks.

Key Takeaways

Writing descriptions once and reusing them saves time.

Doc blocks keep documentation consistent and easy to update.

Everyone on the team understands data better with clear docs.