# О функции var

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

Вы можете передавать переменные из `vars.yml` или `dbt_project.yml` в модели во время компиляции. Эти переменные полезны для настройки пакетов при развёртывании в нескольких средах или для определения значений, которые должны использоваться в нескольких моделях одного пакета.

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

Чтобы получить значение переменной внутри модели, хука или макроса, используйте функцию `var()`. Функция `var()` возвращает значение, определённое в проекте или переданное с помощью `--vars`, в соответствии с порядком приоритетов.

Вы можете использовать `var()` везде, где dbt обрабатывает Jinja во время компиляции, в том числе в большинстве файлов `.sql` и `.yml` вашего проекта. Эта функция не работает в конфигурационных файлах, которые dbt читает до компиляции, таких как [`profiles.yml`](https://docs.getdbt.tech/reference/dbt-jinja-functions/profiles-yml-context.md) или [`packages.yml`](<https://docs.getdbt.tech/reference/dbt-jinja-functions/packages.yml context/.md>).

Чтобы добавить переменную в модель, используйте функцию `var()`:

my\_model.sql

```sql
select * from events where event_type = '{{ var("event_type") }}'
```

Если вы попытаетесь запустить эту модель, не передав переменную `event_type`, вы получите ошибку компиляции, которая будет выглядеть примерно так:

```text
Encountered an error:
! Compilation error while compiling model package_name.my_model:
! Required var 'event_type' not found in config:
Vars supplied to package_name.my_model = {
}
```

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

Чтобы определить переменную в проекте, добавьте конфигурацию `vars:` в отдельный файл `vars.yml` или в файл `dbt_project.yml`. Файл `vars.yml` обрабатывается *до* `dbt_project.yml`, поэтому в `dbt_project.yml` можно ссылаться на переменные из `vars.yml` с помощью `{{ var('...') }}`.

### vars.yml

vars.yml

```yaml
vars:
  event_type: activation
```

### dbt\_project.yml

Вы можете определить переменные в `dbt_project.yml` или сослаться на переменные из `vars.yml` (например, в конфигурации `models`):

dbt\_project.yml

```yaml
name: my_dbt_project
version: 1.0.0
config-version: 2

# Вариант 1: определите переменные здесь
vars:
  event_type: activation

# Вариант 2: сошлитесь на переменную из vars.yml
models:
  my_dbt_project:
    +schema: "{{ var('event_type') }}"
```

Нельзя определять переменные одновременно в `vars.yml` и `dbt_project.yml`; для этого можно использовать только один из этих файлов. Если оба файла содержат блок `vars` с определениями переменных, dbt выдаст ошибку.

Подробнее об определении переменных в проекте dbt см. в документации по [использованию переменных](https://docs.getdbt.tech/docs/build/project-variables.md).

### Значения переменных по умолчанию

Функция `var()` принимает необязательный второй аргумент — `default`. Если этот аргумент указан, он будет использоваться как значение переменной по умолчанию, если переменная не определена явно.

my\_model.sql

```sql
-- Use 'activation' as the event_type if the variable is not defined.
select * from events where event_type = '{{ var("event_type", "activation") }}'
```

### Переменные командной строки

Файл `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).
