Перейти к основному содержимому

Поддержка Jinja по типам файлов

Поддержка Jinja зависит от типа файла. Некоторые файлы поддерживают выражения Jinja, встроенные функции dbt и пользовательские макросы. Другие поддерживают лишь несколько встроенных функций, а в некоторых Jinja вообще не обрабатывается. На этой странице можно узнать, что поддерживает каждый тип файлов.

На этой странице рассматриваются три вида поддержки:

  • Выражения Jinja ({{ }}, {% %} и {# #}): управление потоком выполнения, вывод строк и комментарии
  • Встроенные функции и переменные dbt: методы и переменные контекста, такие как env_var(), ref() и target
  • Пользовательские макросы: макросы, определенные в проекте, например {{ my_macro() }}

Выражения Jinja позволяют писать динамическую логику в файле. Пользовательские макросы — один из видов пользовательских блоков Jinja, которые определяются с помощью тегов, таких как {% macro %}. Другие типы блоков включают {% test %}, {% materialization %}, {% snapshot %} и {% docs %}. О том, где размещать каждый из них, см. в разделе Где определять пользовательские блоки Jinja.

Сводная таблица​

Тип файлаВыражения JinjaФункции и переменные dbtПользовательские макросыПримечания
Модели, аналитические запросы и единичные тесты .sql✅✅✅Здесь можно вызывать макросы, в том числе хуки и операции. См. раздел Где определять пользовательские блоки Jinja.
Универсальные тесты .sql ({% test %})✅✅✅
Снимки .sql (устаревший синтаксис {% snapshot %})✅✅✅Рекомендуется использовать снимки в YAML.
Материализации .sql ({% materialization %})✅✅✅
Блоки документации .md ({% docs %})✅❌❌Только чистый Jinja; для ссылок на блоки используйте doc().
dbt_project.yml✅Ограниченноv1: ❌ / v2: ОграниченноВ v2 пользовательские макросы поддерживаются только в хуках. Блок vars: верхнего уровня обрабатывается буквально (не как Jinja). См. раздел Контекст dbt_project.yml.
profiles.yml✅Ограниченно❌Поддерживает префикс DBT_ENV_SECRET_ для env_var(). См. раздел Контекст profiles.yml.
packages.yml✅Ограниченно❌Поддерживает префикс DBT_ENV_SECRET_ для env_var(). См. раздел Контекст packages.yml.
properties.yml / schema.yml✅Ограниченноv1: ❌ / v2: ✅В v2 можно вызывать пользовательские макросы в значениях YAML (например, в description). ref() и source() недоступны. См. раздел Контекст properties.yml.
selectors.yml✅Ограниченноv1: ❌ / v2: ✅Также поддерживает env_var(), target, as_bool() и связанный с ними контекст. См. раздел Селекторы YAML.
dependencies.ymlv1: ❌ / v2: ✅v1: ❌ / v2: Ограниченно❌В v2 Jinja работает (например, env_var() в URL Git). Если проект должен также работать в v1, рекомендуется использовать packages.yml.
Модели Python .py❌❌❌Вместо этого используйте API класса dbt для Python.
Сиды .csv❌❌❌Только файлы данных.
SQL-фикстуры юнит-тестов❌❌❌См. раздел Форматы данных.
.sql.j2 / .md.j2 (необязательно)Как у .sql / .mdКак у .sql / .mdКак у .sql / .mdТребуется allow_jinja_file_extensions (по умолчанию false).

Условные обозначения таблицы

  • Ограниченно: доступна только часть встроенных функций и переменных dbt (обычно env_var(), var() и target). Точный список зависит от типа файла.
  • Для пользовательских макросов «Ограниченно» означает поддержку только в определенных полях (например, в хуках в dbt_project.yml в v2).
  • Как у .sql / .md: необязательные расширения .j2 соответствуют типу файла без .j2 (например, .sql.j2 соответствует .sql).

Где определять пользовательские блоки Jinja​

Для вызова макроса ({{ my_macro() }}) используются выражения Jinja. Для его определения используется пользовательский блок Jinja ({% macro %}). В таблице ниже указано, где следует размещать каждый тип блока:

БлокТип файлаРасположениеПримечания
{% macro %}.sqlmacros/Можно вызывать из моделей, тестов, хуков и других мест.
{% test %}.sqltests/generic/ или macros/Может вызывать другие макросы.
{% materialization %}.sqlmacros/Здесь определяются пользовательские материализации.
{% snapshot %}.sqlsnapshots/ (устаревший вариант)Рекомендуется использовать снимки в YAML. О старом синтаксисе см. в разделе Устаревшие конфигурации снимков.
{% docs %}.mdЛюбой путь к ресурсам или docs/Только чистый Jinja; вызовы пользовательских макросов не поддерживаются.

Распространенные исключения​

Для некоторых полей конфигурации действуют более строгие ограничения, чем указано в сводной таблице.

Блок vars: в dbt_project.yml​

Значения в блоке vars: в dbt_project.yml обрабатываются буквально, а не как Jinja. Чтобы задавать значения динамически, используйте --vars в командной строке. См. раздел Переменные проекта.

Конфигурация sql_header​

Конфигурация sql_header не поддерживает Jinja и макросы, такие как ref(), source() и {{ this }}.

Различия в поддержке Jinja между v1 и v2​

В v2 поддерживаются некоторые возможности Jinja, недоступные в v1:

  • Пользовательские макросы в значениях properties.yml и selectors.yml
  • Пользовательские макросы в хуках dbt_project.yml (ограниченно)
  • Jinja в dependencies.yml

Если ваш проект должен также работать в v1, не используйте эти возможности. В v1 пользовательский макрос в файле YAML приводит к ошибке неопределенного макроса. Jinja в dependencies.yml остается необработанной строкой, которую dbt передает в git, что обычно приводит к сбою установки.

В этом примере пользовательский макрос вызывается в значении свойства. Он работает в v2, но приводит к ошибке в v1:

models/schema.yml
models:
  - name: customers
    description: "{{ my_macro() }}"

В этом примере env_var() используется в спецификации пакета. Разместите ее в packages.yml, чтобы она работала в v1 и v2:

packages.yml
packages:
  - git: "https://{{ env_var('DBT_ENV_SECRET_GIT_CREDENTIAL') }}@github.com/dbt-labs/awesome_repo.git"

Подробнее о файлах пакетов см. в разделе Сценарии использования пакетов.

Связанная документация​

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

0
Loading