Переменные проекта
dbt предоставляет механизм переменных для передачи данных в модели при компиляции. Переменные позволяют задавать настраиваемые значения для проекта вместо того, чтобы жёстко прописывать их в SQL.
(Версии dbt: v1.12 и новее)Переменные можно определить тремя способами:
- В файле
vars.yml(рекомендуется для проектов с несколькими переменными или когда нужно обращаться к переменным изdbt_project.yml) - В файле
dbt_project.yml - В командной строке
Переменные, определённые в vars.yml или dbt_project.yml, служат значениями по умолчанию для всего проекта. Эти значения применяются везде, где есть обращение к переменной. Их можно переопределить при запуске с помощью аргумента командной строки --vars. Это удобно, когда нужно изменить значение для конкретного запуска. Например, при тестировании с другим диапазоном дат или запуске моделей с настройками, зависящими от окружения.
Переменные можно использовать, чтобы настраивать часовые пояса, задавать диапазоны дат для отчётности, избегать жёстко заданных имён таблиц или иным образом управлять компиляцией моделей.
Чтобы использовать переменную в модели, хуке или макросе, используйте функцию {{ var('...') }}. Функция var() получает значение, определённое в проекте или переданное с помощью --vars. Подробнее см. в разделе О функции var.
Обратите внимание: см. раздел YAML tips, чтобы узнать больше о работе с YAML.
(Версии dbt: v1.12 и новее)Определение переменных в vars.yml
Файл vars.yml в корне проекта предназначен для переменных проекта. dbt разбирает его до dbt_project.yml, поэтому в dbt_project.yml на эти переменные можно ссылаться через {{ var('...') }}. Подробнее см. Использование переменных из vars.yml в dbt_project.yml.
Добавьте блок vars в файл vars.yml. Переменные можно задать для всего проекта или для отдельного подключённого пакета. Пример:
vars:
# The `start_date` variable is accessible to all resources
start_date: '2016-06-01'
# The `platforms` variable is only accessible to resources in the my_dbt_project project
my_dbt_project:
platforms: ['web', 'mobile']
# The `app_ids` variable is only accessible to resources in the snowplow package
snowplow:
app_ids: ['marketing', 'app', 'landing-page']
Определять переменные одновременно в vars.yml и dbt_project.yml нельзя. Если в обоих файлах есть блок vars с определениями, dbt выдаст ошибку.
Если vars.yml пуст или отсутствует, dbt использует переменные из dbt_project.yml.
Использование переменных из vars.yml в dbt_project.yml
Поскольку dbt разбирает vars.yml раньше dbt_project.yml, в dbt_project.yml можно ссылаться на переменные из vars.yml через {{ var('...') }}. Ссылки разрешаются только через vars.yml или аргумент командной строки --vars. Если переменная определена только в блоке vars самого файла dbt_project.yml, dbt выдаст ошибку.
Например, в vars.yml определены следующие переменные:
vars:
schema_name: analytics
materialization: table
На них можно сослаться в dbt_project.yml:
models:
my_dbt_project:
+schema: "{{ var('schema_name') }}"
+materialized: "{{ var('materialization') }}"
Определение переменных в dbt_project.yml
Jinja не поддерживается в конфигурации vars, и все значения будут интерпретироваться буквально.
Чтобы определить переменные в проекте dbt, добавьте конфигурацию vars в файл dbt_project.yml.
Область действия этих переменных vars может быть глобальной или ограничиваться конкретным пакетом, импортированным в ваш
проект.
name: my_dbt_project
version: 1.0.0
config-version: 2
vars:
# Переменная `start_date` будет доступна во всех ресурсах
start_date: '2016-06-01'
# Переменная `platforms` доступна только для ресурсов в проекте my_dbt_project
my_dbt_project:
platforms: ['web', 'mobile']
# Переменная `app_ids` доступна только для ресурсов в пакете snowplow
snowplow:
app_ids: ['marketing', 'app', 'landing-page']
models:
...
Нельзя определять переменные одновременно в vars.yml и dbt_project.yml. Если оба файла содержат блок vars с определениями, dbt выдаёт ошибку.
Определение переменных в командной строке
Файл dbt_project.yml отлично подходит для определения переменных, которые редко меняются.
Когда нужно переопределить переменную для конкретного запуска, используйте параметр командной строки --vars. Например, если вы хотите выполнить тестирование с другим диапазоном дат, запустить модели с настройками для определённой среды или динамически изменить поведение.
Используйте --vars, чтобы передать одну или несколько переменных команде dbt. Укажите аргумент в виде строки, содержащей словарь YAML.
Например:
$ dbt run --vars '{"event_type": "signup"}'
Такой же синтаксис --vars можно использовать с другими командами dbt, например с dbt snapshot:
$ dbt snapshot --select my_snapshot --vars '{"cutoff_date": "2026-01-01"}'
Внутри модели, снимка или макроса получить значение можно с помощью функции var():
select '{{ var("event_type") }}' as event_type
Переменные, переданные с помощью --vars, доступны везде в проекте, где используется функция var().
Можно передать сразу несколько переменных:
$ dbt run --vars '{event_type: signup, region: us}'
Если задаётся только одна переменная, фигурные скобки необязательны:
$ dbt run --vars 'event_type: signup'
Аргумент --vars принимает словарь YAML в виде строки в командной строке.
YAML удобен тем, что не требует строгого использования кавычек, в отличие от JSON.
Оба следующих варианта допустимы и эквивалентны:
$ dbt run --vars '{"key": "value", "date": 20180101}'
$ dbt run --vars '{key: value, date: 20180101}'
Переменные, определённые с помощью --var, переопределяют значения, заданные в dbt_project.yml. Это позволяет использовать --vars для временного переопределения конфигурации без изменения файлов проекта, сохранённых в системе контроля версий. Полный порядок приоритетов (включая переменные, заданные для отдельных пакетов, и значения по умолчанию, определённые в var()) см. в разделе Приоритет переменных.
Более подробную информацию об определении словарей с помощью YAML можно найти здесь.
Приоритет переменных
(Версии dbt: v1.12 и новее)Переменные, определённые с помощью аргумента командной строки --vars, переопределяют переменные, определённые в vars.yml или dbt_project.yml. Они имеют глобальную область видимости и доступны корневому проекту и всем установленным пакетам.
Порядок приоритета объявлений переменных следующий (от высшего к низшему):
- Переменные, определённые в командной строке с помощью
--vars - Объявление переменной с областью видимости пакета в корневом файле
vars.yml(если он существует) - Объявление глобальной переменной в корневом файле
vars.yml(если он существует) - Объявление переменной с областью видимости пакета в корневом файле
dbt_project.yml - Объявление глобальной переменной в корневом файле
dbt_project.yml - Если этот узел определён в пакете: объявления переменных в файле
dbt_project.ymlэтого пакета - Значение переменной по умолчанию, переданное в качестве аргумента (если оно указано)
Файл vars.yml разбирается до dbt_project.yml, поэтому переменные, определённые в vars.yml, доступны при разборе dbt_project.yml. Если файл vars.yml пуст или не существует, вместо них используются переменные из dbt_project.yml. При изменении любой переменной (в vars.yml, dbt_project.yml или в командной строке) частичный разбор отключается для следующего запуска.
Если dbt не удаётся найти определение переменной после проверки всех возможных мест объявления переменных, возникает ошибка компиляции.
Примечание: Область видимости переменной основана на узле, который в конечном итоге использует эту переменную. Представьте случай, когда модель, определенная в корневом проекте, вызывает макрос, определенный в установленном пакете. Этот макрос, в свою очередь, использует значение переменной. Переменная будет разрешена на основе области видимости корневого проекта, а не области видимости пакета.