# О блоках statement

(Версии dbt: v2.0 и новее)

Когда использовать блоки statement в dbt v2

Для запросов, результаты которых нужно получить (например, когда вашему макросу или коду Jinja нужны данные, возвращаемые из базы данных), можно использовать блоки `statement` с `fetch_result=True` или [макрос `run_query`](https://docs.getdbt.tech/reference/dbt-jinja-functions/run_query.md).

Для операций DDL или служебных операций (таких как `OPTIMIZE`, `VACUUM` или запросы для обслуживания) используйте блоки `statement` с `fetch_result=False`, если вам не нужен доступ к результатам в Jinja. Это позволяет избежать проблем со строгой проверкой типов в dbt v2, которая может завершиться ошибкой при обработке наборов результатов, содержащих значения `NULL` в столбцах, объявленных как не допускающие `NULL`.

Блоки `statement` — это SQL-запросы, которые обращаются к базе данных и возвращают результаты в ваш контекст Jinja. Вот пример блока `statement`, который получает все штаты из таблицы пользователей (таблица).

get\_states\_statement.sql

```sql
-- depends_on: {{ ref('users') }}

{%- call statement('states', fetch_result=True) -%}

    select distinct state from {{ ref('users') }}

{%- endcall -%}
```

Сигнатура блока `statement` выглядит следующим образом:

```text
statement(name=None, fetch_result=False, auto_begin=True)
```

При выполнении `statement` dbt должен понимать, как разрешать ссылки на другие модели или ресурсы dbt. Если вы уже используете `ref` для модели вне блока statement, зависимость будет автоматически определена, но в противном случае вам нужно будет [принудительно указать зависимость](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md#forcing-dependencies) с помощью `-- depends_on`.

 Пример использования -- depends\_on

```sql
-- depends_on: {{ ref('users') }}

{% call statement('states', fetch_result=True) -%}

    select distinct state from {{ ref('users') }}

    /*
    Уникальные штаты: {{ load_result('states')['data'] }}
    */
{%- endcall %}
```

 Пример использования функции ref()

```sql

{% call statement('states', fetch_result=True) -%}

    select distinct state from {{ ref('users') }}

    /*
    Уникальные штаты: {{ load_result('states')['data'] }}
    */

{%- endcall %}

select id * 2 from {{ ref('users') }}
```

**Аргументы**:

* `name` (строка): Имя для набора результатов, возвращаемого этим statement
* `fetch_result` (bool): Если True, загрузить результаты statement в Jinja-контекст
* `auto_begin` (bool): Если True, открыть транзакцию, если она не существует. Если False, не открывать транзакцию.

После выполнения блока statement набор результатов доступен через функцию `load_result`. Объект результата включает три ключа:

* `response`: Структурированный объект, содержащий метаданные, возвращаемые из базы данных, которые зависят от адаптера. Например, код успеха `code`, количество затронутых строк `rows_affected`, общий объем обработанных байт `bytes_processed` и т.д. Сравнимо с `adapter_response` в [объекте результата](https://docs.getdbt.tech/reference/dbt-classes.md#result-objects).
* `data`: Питоническое представление данных, возвращаемых запросом (массивы, кортежи, словари).
* `table`: Представление данных в виде таблицы [Agate](https://agate.readthedocs.io/page/api/table.html), возвращаемых запросом.

Для приведенного выше statement это может выглядеть так:

load\_states.sql

```sql
{%- set states = load_result('states') -%}
{%- set states_data = states['data'] -%}
{%- set states_status = states['response'] -%}
```

Содержимое возвращаемого поля `data` — это матрица. Она содержит список строк, каждая из которых является списком значений, возвращаемых базой данных. Для приведенного выше примера эта структура данных может выглядеть так:

states.sql

```python
>>> log(states_data)

[
  ['PA'],
  ['NY'],
  ['CA'],
	...
]
```

(Версии dbt: v2.0 и новее)

## Операции без получения результатов

Для операций DDL или служебных операций, результаты которых вам не нужны (поскольку вы не используете возвращаемые строки в Jinja), задайте `fetch_result=False`. Этот подход рекомендуется для таких операций, как `OPTIMIZE` или `VACUUM` в Databricks, которые возвращают наборы результатов, способные содержать значения null в столбцах, не допускающих null.

macros/optimize\_table.sql

```jinja
{% macro optimize_table(table, zorder_fields=[]) %}
  {% set zorder_str = zorder_fields | join(', ') %}

  {% set query %}
    OPTIMIZE {{ table }}
    {% if zorder_str | length > 0 %}
      ZORDER BY ({{ zorder_str }})
    {% endif %}
  {% endset %}

  {% call statement('optimize', fetch_result=False) %}
    {{ query }}
  {% endcall %}
{% endmacro %}
```

Этот макрос можно использовать в post-hook:

dbt\_project.yml

```yaml
models:
  my_project:
    +post-hook:
      - "{{ optimize_table(this, ['customer_id', 'order_date']) }}"
```
