# О команде dbt run-operation

## Обзор

Команда `dbt run-operation` используется для вызова макроса или выполнения строки SQL или Jinja непосредственно в целевой базе данных. Информацию об использовании операций на основе макросов см. в разделе [Операции](https://docs.getdbt.tech/docs/build/hooks-operations.md#about-operations).

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

При вызове макроса с помощью `dbt run-operation` dbt не применяет ограничения моделей, заданные через [access](https://docs.getdbt.tech/reference/resource-configs/access.md) или [group](https://docs.getdbt.tech/reference/resource-configs/group.md), поэтому макрос может использовать `ref()` для обращения ко всем моделям (включая модели с уровнем доступа `private` и `protected`).

Например, макрос может ссылаться на приватную модель:

```jinja
{% macro example_macro() %}
  {{ ref('my_private_model') }}
{% endmacro %}
```

Затем этот макрос можно запустить с помощью `dbt run-operation`:

```bash
dbt run-operation example_macro
```

## Использование

```text
$ dbt run-operation [macro] --args '{args}'
$ dbt run-operation --sql '{sql}'
 
  [macro]               Укажите макрос для вызова. dbt вызовет этот макрос
                        с переданными аргументами, а затем завершит работу. Обязателен,
                        если не указан --sql. Нельзя использовать вместе с --sql.
 
  --args ARGS           Передайте аргументы макросу. Этот словарь будет
                        сопоставлен с именованными аргументами, определёнными в
                        выбранном макросе. Аргумент должен быть строкой YAML,
                        например '{my_variable: my_value}'. Нельзя использовать с --sql.
 
  --sql SQL             Выполните строку SQL или Jinja непосредственно в
                        целевой базе данных без необходимости определять макрос.
                        Нельзя сочетать с именем макроса или --args.
                        Доступно в dbt v1.12+.
```

## Использование флага `--sql`

Начиная с dbt v1.12, флаг `--sql` позволяет выполнять разовые SQL-команды прямо в хранилище без отдельного макроса. Например, можно удалить или изменить таблицу, выдать права или исправить данные. Выражение проходит полную компиляцию Jinja с доступом к `ref()`, `source()`, `var()`, `target` и другим переменным контекста. Если в SQL нет Jinja, dbt пропускает компиляцию манифеста, поэтому выполнение ускоряется.

Например:

```bash
# Удалить таблицу в хранилище данных
dbt run-operation --sql "DROP TABLE IF EXISTS my_schema.old_table"

# Использовать переменные контекста Jinja в SQL-инструкции
dbt run-operation --sql "GRANT SELECT ON {{ target.schema }}.my_table TO reporter"
```

Во время выполнения операции dbt выводит в терминал строки состояния:

```text
1 of 1 START executing inline_query ........... [RUN]
1 of 1 OK executed inline_query ............... [SELECT 1 in 0.05s]
```

В логах операция называется `inline_query`. Если операция завершается с ошибкой, в строке состояния отображается `ERROR` вместо `OK`.

Обратите внимание: флаг `--sql` нельзя использовать вместе с именем макроса или `--args`.

### Когда использовать `--sql` вместо макроса

`--sql` удобен для быстрых разовых операций, ради которых не стоит создавать файл макроса (например, для предоставления прав доступа, удаления таблицы или исправления данных).

Если вам нужно повторно использовать операцию в разных средах или поделиться ею с командой, напишите [макрос](https://docs.getdbt.tech/docs/build/jinja-macros.md), чтобы его можно было хранить в системе контроля версий и тестировать.

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

* Вызов макроса:

  ```bash
  # Передать макросу один аргумент
  dbt run-operation grant_select --args '{role: reporter}'

  # Передать макросу несколько аргументов
  dbt run-operation clean_stale_models --args '{days: 7, dry_run: True}'
  ```

* Использование флага `--sql`:

  ```bash
  # Выполнить DDL-инструкцию
  dbt run-operation --sql "CREATE TABLE my_schema.my_table (id int)"

  # Предоставить право SELECT на модель dbt с помощью ref()
  dbt run-operation --sql "GRANT SELECT ON {{ ref('my_model') }} TO reporter"
  ```
