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

dbt предоставляет механизм [переменных](https://docs.getdbt.tech/reference/dbt-jinja-functions/var.md) для передачи данных в модели при компиляции. Переменные позволяют задавать настраиваемые значения для проекта вместо того, чтобы жёстко прописывать их в SQL.

(Версии dbt: v1.12 и новее)

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

* В файле `vars.yml` (рекомендуется для проектов с несколькими переменными или когда нужно обращаться к переменным из [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md))
* В файле `dbt_project.yml`
* В командной строке

Переменные, определённые в `vars.yml` или `dbt_project.yml`, служат значениями по умолчанию для всего проекта. Эти значения применяются везде, где есть обращение к переменной. Их можно переопределить при запуске с помощью аргумента командной строки `--vars`. Это удобно, когда нужно изменить значение для конкретного запуска. Например, при тестировании с другим диапазоном дат или запуске моделей с настройками, зависящими от окружения.

Переменные можно использовать, чтобы [настраивать часовые пояса](https://github.com/dbt-labs/snowplow/blob/0.3.9/dbt_project.yml#L22), задавать диапазоны дат для отчётности, [избегать жёстко заданных имён таблиц](https://github.com/dbt-labs/quickbooks/blob/v0.1.0/dbt_project.yml#L23) или иным образом управлять компиляцией моделей.

Чтобы использовать переменную в модели, хуке или макросе, используйте функцию `{{ var('...') }}`. Функция `var()` получает значение, определённое в проекте или переданное с помощью `--vars`. Подробнее см. в разделе [О функции var](https://docs.getdbt.tech/reference/dbt-jinja-functions/var.md).

Обратите внимание: см. раздел [YAML tips](https://docs.getdbt.tech/docs/build/dbt-tips.md#yaml-tips), чтобы узнать больше о работе с YAML.

(Версии dbt: v1.12 и новее)

### Определение переменных в `vars.yml`

Файл `vars.yml` в корне проекта предназначен для переменных проекта. dbt разбирает его *до* `dbt_project.yml`, поэтому в `dbt_project.yml` на эти переменные можно ссылаться через `{{ var('...') }}`. Подробнее см. [Использование переменных из vars.yml в dbt\_project.yml](#using-varsyml-variables-in-dbt_projectyml).

Добавьте блок `vars` в файл `vars.yml`. Переменные можно задать для всего проекта или для отдельного подключённого пакета. Пример:

vars.yml

```yaml
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

```yaml
vars:
  schema_name: analytics
  materialization: table
```

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

dbt\_project.yml

```yaml
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

```yaml
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.

Например:

```shell
$ dbt run --vars '{"event_type": "signup"}'
```

Такой же синтаксис `--vars` можно использовать с другими командами dbt, например с `dbt snapshot`:

```shell
$ dbt snapshot --select my_snapshot --vars '{"cutoff_date": "2026-01-01"}'
```

Внутри модели, снимка или макроса получить значение можно с помощью функции `var()`:

```shell
select '{{ var("event_type") }}' as event_type
```

Переменные, переданные с помощью `--vars`, доступны везде в проекте, где используется функция `var()`.

Можно передать сразу несколько переменных:

```shell
$ dbt run --vars '{event_type: signup, region: us}'
```

Если задаётся только одна переменная, фигурные скобки необязательны:

```shell
$ dbt run --vars 'event_type: signup'
```

Аргумент `--vars` принимает словарь YAML в виде строки в командной строке. YAML удобен тем, что не требует строгого использования кавычек, в отличие от JSON.

Оба следующих варианта допустимы и эквивалентны:

```shell
$ dbt run --vars '{"key": "value", "date": 20180101}'
$ dbt run --vars '{key: value, date: 20180101}'
```

Переменные, определённые с помощью `--var`, переопределяют значения, заданные в `dbt_project.yml`. Это позволяет использовать `--vars` для временного переопределения конфигурации без изменения файлов проекта, сохранённых в системе контроля версий. Полный порядок приоритетов (включая переменные, заданные для отдельных пакетов, и значения по умолчанию, определённые в `var()`) см. в разделе [Приоритет переменных](https://docs.getdbt.tech/docs/build/project-variables.md#variable-precedence).

Более подробную информацию об определении словарей с помощью YAML можно найти [здесь](https://github.com/Animosity/CraftIRC/wiki/Complete-idiot%27s-introduction-to-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 не удаётся найти определение переменной после проверки всех возможных мест объявления переменных, возникает ошибка компиляции.

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