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

Эта конфигурация не реализована для источников.

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 %}

Определение

Опционально сохраняйте описания ресурсов в виде комментариев к столбцам и отношениям в базе данных. По умолчанию сохранение документации отключено, но его можно включить для конкретных ресурсов или групп ресурсов по мере необходимости.

Поддержка

Конфигурация persist_docs поддерживается на наиболее широко используемых адаптерах dbt:

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

Однако некоторые базы данных ограничивают, где и как можно добавлять описания к объектам базы данных. Эти адаптеры баз данных могут не поддерживать persist_docs или могут предлагать только частичную поддержку.

Некоторые известные проблемы и ограничения:

Databricks

• Комментарии на уровне колонок требуют file_format: delta (или другого «v2 file format»).

Snowflake

• Если имя колонки в SQL-модели задано в смешанном регистре (например, ca_net_ht_N), документация для этой колонки не будет сохранена. Чтобы документация сохранялась, есть два варианта:

  • Определить имя колонки в соответствующем YML-файле, используя только строчные или только заглавные буквы.
  • Использовать конфигурацию quote в соответствующем YML-файле.

  Ниже приведён пример пошаговых действий, показывающий, как использовать поле quote для колонок со смешанным регистром.

1. Создайте следующие SQL- и YML-файлы:

   <modelname>.sql

   {{ config(materialized='table') }}
   
   select 1 as "ca_net_ht_N" # обратите внимание на использование двойных кавычек для имени колонки
   <modelname>.yml

   models:
     - name: <modelname>
       description: This is the table description
   
   columns:
     - name: "ca_net_ht_N"
       description: This should be the description of the column
       quote: true

2. Выполните команду dbt build -s models/<modelname>.sql --full-refresh.

3. Откройте логи в файле logs/dbt.log и проверьте описание колонки:

   alter table analytics.<schema>.<modelname> alter
       "ca_net_ht_N" COMMENT $$This should be the description of the column$$;

Использование

Документирование столбцов и отношений

Предоставьте описание для модели:

models/schema.yml

models:
  - name: dim_customers
    description: Одна запись на клиента
    columns:
      - name: customer_id
        description: Первичный ключ

Включите persist_docs для столбцов и отношений в вашем проекте:

dbt_project.yml

models:
  +persist_docs:
    relation: true
    columns: true

Запустите dbt и убедитесь, что созданные отношения и столбцы аннотированы вашими описаниями:

Описания отношений в BigQuery

Описания столбцов в BigQuery

Нашли ошибку?

Создать GitHub Issue