persist_docs

Models
Sources
Seeds
Snapshots

dbt_project.yml

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

models/<modelname>.sql


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

dbt_project.yml

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

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 all core dbt plugins: BigQuery, Redshift, Snowflake, and Postgres. Some databases impose limitations on the types of descriptions that can be added to database objects. At present, the persist_docs flag has the following known limitations:

Column-level comments are not supported on Snowflake views

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 BigQuery

Column descriptions in BigQuery