persist_docs

Models

dbt_project.yml

models:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

models/<modelname>.sql

{{ config(
  persist_docs={"relation": true, "columns": true}
) }}

select ...

Sources

This config is not implemented for sources.

Seeds

dbt_project.yml

seeds:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

Snapshots

dbt_project.yml

snapshots:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

snapshots/<filename>.sql

{% snapshot snapshot_name %}

{{ config(
  persist_docs={"relation": true, "columns": true}
) }}

select ...

{% endsnapshot %}

Definition

Optionally persist resource descriptions as column and relation comments in the database. By default, documentation persistence is disabled, but it can be enabled for specific resources or groups of resources as needed.

▶Changelog

Support

The persist_docs config is supported on the most widely used dbt adapters:

• Postgres
• Redshift
• Snowflake
• BigQuery
• Apache Spark & Databricks

However, some databases limit where and how descriptions can be added to database objects. Those database adapters might not support persist_docs, or might offer only partial support.

Some known issues and limitations:

Databricks

• Column-level comments require file_format: delta (or another "v2 file format")
• Column-level comments aren't supported for models materialized as views (issue)

Snowflake

Usage

Documenting columns and relations

Supply a description for a model:

models/schema.yml

version: 2

models:
  - name: dim_customers
    description: One record per customer
    columns:
      - name: customer_id
        description: Primary key

Enable persist_docs for columns and relations in your project:

dbt_project.yml

models:
  +persist_docs:
    relation: true
    columns: true

Run dbt and observe that the created relation and columns are annotated with your descriptions:

Relation descriptions in BigQueryColumn descriptions in BigQuery