Skip to main content

About the doc function

You can specify documentation text in a docs block, then use the doc() Jinja function in description fields as a way to reuse the same text in multiple places. You can only use the doc() Jinja function in properties YAML files for resources with description properties. For example, models, model columns, sources, source tables, source columns, and so on.

The doc() Jinja function, which is analogous to ref(), looks up the named docs block (for example, {% docs orders %} ... {% enddocs %} in a docs.md file) and returns its rendered content. For more information, refer to the Documentation guide.

Usage​

In dbt, column descriptions can be defined directly in a model's properties YAML file. These descriptions are written as plain text and are associated with a specific column.

Manually adding descriptions​

models/orders.yml
models:
  - name: orders
    columns:
      - name: order_total_cents
        description: "Total order amount in cents. This value is always a positive integer and excludes taxes and shipping."

When you run dbt docs generate and view the docs site, this text appears exactly as written but only for the order_total_cents column of the orders model.

Reusing descriptions with doc()​

To avoid repeating the same description across multiple models or columns, dbt lets you define documentation separately and reference it using the doc() function.

With this approach, documentation is written once in a markdown file using a named docs block, and then reused wherever needed in your project. This helps ensure consistency and makes it easier to maintain shared definitions over time.

First, define a reusable documentation block in a docs.md:

models/docs/example.md
{% docs order_total_cents %}
Total order amount in cents. This value is always a positive integer and excludes taxes and shipping.
{% enddocs %}

This defines a docs block named order_total_cents. Reference it with doc('order_total_cents') in description fields wherever you need the same text.

Next, reference this documentation in your properties YAML file:

models/orders.yml
models:
  - name: orders
    columns:
      - name: order_total_cents
        description: "{{ doc('order_total_cents') }}"

When you run dbt docs generate, dbt resolves the doc() reference by looking up the corresponding docs block and injecting its content into the generated documentation.

As a result, the column description displays the text defined in the markdown file, rather than inline YAML.

Avoid duplicate names​

Docs block names must be unique within your project. If you define multiple {% docs %} blocks with the same name, dbt cannot reliably determine which block to use when doc('DOCS_BLOCK_NAME') is called.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading