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

Переменные проекта

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.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.yml
vars:
schema_name: analytics
materialization: table

На них можно сослаться в dbt_project.yml:

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 может быть глобальной или ограничиваться конкретным пакетом, импортированным в ваш проект.

dbt_project.yml
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:
...
(Версии dbt: v1.12 и новее)

Нельзя определять переменные одновременно в 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. Они имеют глобальную область видимости и доступны корневому проекту и всем установленным пакетам.

Порядок приоритета объявлений переменных следующий (от высшего к низшему):

  1. Переменные, определённые в командной строке с помощью --vars
  2. Объявление переменной с областью видимости пакета в корневом файле vars.yml (если он существует)
  3. Объявление глобальной переменной в корневом файле vars.yml (если он существует)
  4. Объявление переменной с областью видимости пакета в корневом файле dbt_project.yml
  5. Объявление глобальной переменной в корневом файле dbt_project.yml
  6. Если этот узел определён в пакете: объявления переменных в файле dbt_project.yml этого пакета
  7. Значение переменной по умолчанию, переданное в качестве аргумента (если оно указано)

Файл vars.yml разбирается до dbt_project.yml, поэтому переменные, определённые в vars.yml, доступны при разборе dbt_project.yml. Если файл vars.yml пуст или не существует, вместо них используются переменные из dbt_project.yml. При изменении любой переменной (в vars.yml, dbt_project.yml или в командной строке) частичный разбор отключается для следующего запуска.

Если dbt не удаётся найти определение переменной после проверки всех возможных мест объявления переменных, возникает ошибка компиляции.

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

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

0
Loading