О функции doc
Текст документации можно определить в блоке docs и переиспользовать в полях описаний через функцию Jinja doc(). Она доступна только в YAML-файлах свойств ресурсов с полем описания, например моделей, столбцов моделей, источников, таблиц и столбцов источников.
Как и ref(), функция Jinja doc() ищет объект по имени. В данном случае она находит блок docs, например {% docs orders %} ... {% enddocs %} в файле docs.md, и возвращает его обработанное содержимое. См. Руководство по документации.
Использование
В dbt описания столбцов можно задать прямо в YAML-файле свойств модели. Описание задаётся обычным текстом и относится к конкретному столбцу.
Добавление описаний вручную
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."
Когда вы запускаете dbt docs generate и открываете сайт документации, этот текст отображается в точности так, как он написан, но только для столбца order_total_cents модели orders.
Повторное использование описаний с помощью doc()
Чтобы не повторять одно и то же описание для нескольких моделей или столбцов, dbt позволяет определять документацию отдельно и ссылаться на неё с помощью функции doc().
При таком подходе документация пишется один раз в markdown-файле в именованном блоке docs, а затем используется повторно везде, где это необходимо в проекте. Это помогает обеспечить согласованность и упрощает поддержку общих определений с течением времени.
Сначала определите блок документации для повторного использования в файле docs.md:
{% docs order_total_cents %}
Общая сумма заказа в центах. Это значение всегда является положительным целым числом и не включает налоги и стоимость доставки.
{% enddocs %}
Так определяется блок docs с именем order_total_cents. Ссылайтесь на него с помощью doc('order_total_cents') в полях описания везде, где нужен тот же текст.
Затем добавьте ссылку на эту документацию в YAML-файл свойств:
models:
- name: orders
columns:
- name: order_total_cents
description: "{{ doc('order_total_cents') }}"
Когда вы запускаете dbt docs generate, dbt разрешает ссылку doc(), находя соответствующий блок docs и вставляя его содержимое в сгенерированную документацию.
В результате в описании столбца отображается текст, заданный в markdown-файле, а не непосредственно в YAML.
Избегайте повторяющихся имён
Имена блоков docs должны быть уникальными в пределах проекта. Если вы определяете несколько блоков {% docs %} с одинаковым именем, dbt не может однозначно определить, какой блок использовать при вызове doc('DOCS_BLOCK_NAME').
В dbt v2 повторяющиеся имена блоков docs не допускаются. При обнаружении дубликатов dbt указывает конфликтующие файлы и выводит предупреждение. Переименуйте один из блоков, чтобы имя каждого блока docs было уникальным. Подробнее см. в разделе Более строгая проверка повторяющихся блоков docs.
{% docs order_total_cents %}
Общая сумма заказа в центах. Это значение всегда является положительным целым числом и не включает налоги и стоимость доставки.
{% enddocs %}
{% docs order_total_cents %}
Общая сумма заказа в центах без учёта налогов и платы за доставку.
{% enddocs %}
dbt found two docs with the same name: 'order_total_cents' in files: 'models/docs/example.md' and 'models/docs/example.md'