# static\_analysis

static\_analysis управляет тем, как dbt v2 анализирует SQL на этапе компиляции для моделей, тестов, seed-файлов и снимков.

к сведению

Конфигурация `static_analysis` доступна только в dbt v2. Она недоступна в dbt v1 и будет игнорироваться. Чтобы перейти на dbt v2, обратитесь к разделу [Начало работы с dbt v2](https://docs.getdbt.tech/docs/dbt/get-started-dbt.md).

Настройка `static_analysis` определяет, как dbt v2 проверяет SQL до выполнения. Режим `strict` выполняет строгий анализ, `baseline` сочетает проверки с совместимостью, а `off` отключает анализ. Допустимые места настройки зависят от типа ресурса.

Какие функции доступны в режиме `strict` в dbt v2, описано в разделах [Поддержка функций Snowflake](https://docs.getdbt.tech/reference/resource-configs/snowflake-function-support.md) и [Поддержка функций BigQuery](https://docs.getdbt.tech/reference/resource-configs/bigquery-function-support.md).

### Модели

dbt\_project.yml

```yml
models:
  resource-path:
    +static_analysis: strict | baseline | off
```

models/filename.yml

```yml
models:
  - name: model_name
    config:
      static_analysis: strict | baseline | off
```

models/model\_name.sql

```sql
{{ config(static_analysis='strict' | 'baseline' | 'off') }}
```

### Тесты

dbt\_project.yml

```yml
data_tests:
  +static_analysis: strict | baseline | off
```

models/filename.yml

```yml
models:
  - name: model_name
    data_tests:
      - not_null:
          arguments:
            column_name: your_column_name
          config:
            static_analysis: strict | baseline | off
```

### Исходные данные (seeds)

dbt\_project.yml

```yml
seeds:
  resource-path:
    +static_analysis: strict | baseline | off
```

seeds/filename.yml

```yml
seeds:
  - name: seed_name
    config:
      static_analysis: strict | baseline | off
```

### Снимки

dbt\_project.yml

```yml
snapshots:
  resource-path:
    +static_analysis: strict | baseline | off
```

snapshots/filename.yml

```yml
snapshots:
  - name: snapshot_name
    config:
      static_analysis: strict | baseline | off
```

### Модульные тесты

dbt\_project.yml

```yml
unit_tests:
  resource-path:
    +static_analysis: strict | baseline | off
```

models/filename.yml

```yml
unit_tests:
  - name: unit_test_name
    model: model_name
    config:
      static_analysis: strict | baseline | off
```

## Определение

Вы можете настроить `static_analysis` для [моделей](https://docs.getdbt.tech/docs/build/sql-models.md), [тестов данных](https://docs.getdbt.tech/docs/build/data-tests.md), [модульных тестов](https://docs.getdbt.tech/docs/build/unit-tests.md), [seed-файлов](https://docs.getdbt.tech/docs/build/seeds.md) и [снимков](https://docs.getdbt.tech/docs/build/snapshots.md).

Вы можете настроить, будет ли dbt v2 выполнять статический анализ SQL для модели и когда именно. Задайте конфигурацию `static_analysis` в YAML-файле проекта (`dbt_project.yml`), YAML-файле свойств модели или в блоке конфигурации SQL в файле модели. Подробнее о различных режимах статического анализа см. в разделе [Принципы статического анализа](https://docs.getdbt.tech/docs/build/about-static-analysis.md?version=1.12#principles-of-static-analysis).

Установка режима `strict` для модели не устанавливает `strict` автоматически для нижестоящих моделей; они сохраняют настройку проекта по умолчанию, если вы не настроите их явно. Дополнительные сведения и примеры см. в разделе [Наследование строгого режима](https://docs.getdbt.tech/docs/build/about-static-analysis.md#strict-mode-inheritance).

Для `static_analysis` доступны следующие значения:

* `baseline` (по умолчанию): статический анализ SQL. Это рекомендуемый начальный режим для пользователей, переходящих с dbt v1: он обеспечивает плавную миграцию и при этом выявляет большинство ошибок SQL. Со временем вы можете постепенно переходить к более строгому анализу.
* `strict`: статический анализ всего SQL до начала выполнения. Используйте этот режим для максимально полной проверки — выполнение не начнётся, пока не будет подтверждена корректность всего проекта.
* `off`: отключение анализа SQL для этой модели и всех её потомков.

### Пользовательские функции (UDF) в режиме `strict`

При настройке `static_analysis: strict` dbt v2 разбирает операторы `CREATE FUNCTION` из [`sql_header`](https://docs.getdbt.tech/reference/resource-configs/sql_header.md) и хуков проекта [`on-run-start`](https://docs.getdbt.tech/reference/project-configs/on-run-start-on-run-end.md), регистрирует эти UDF в реестре компилятора и делает их доступными при строгой статической компиляции. В режимах `baseline` и `off` такая регистрация UDF для статического анализа не выполняется.

Параметр `sql_header` модели может содержать несколько операторов. dbt v2 регистрирует UDF из операторов `CREATE FUNCTION` и на этом этапе игнорирует остальные операторы.

Если строгий анализ по-прежнему не может разрешить ссылку на UDF, задайте [`static_analysis: off`](https://docs.getdbt.tech/reference/resource-configs/static-analysis.md#disable-static-analysis-in-sql-for-a-model-using-a-custom-udf) для затронутых моделей.

### Как каскадно распространяются режимы статического анализа

Применение режимов `static_analysis` в графе зависимостей определяется двумя правилами:

* Правило допустимости: статический анализ модели возможен только в том случае, если он возможен для всех её «родителей» (под родителями понимаются модели, расположенные выше текущей модели в графе зависимостей).
* Правило строгости: режим «дочерней» модели не может быть строже режима родительской (под дочерними понимаются модели, расположенные ниже текущей модели в графе зависимостей).

Настройка статического анализа каскадно распространяется от наиболее строгого режима к наименее строгому. Иерархия строгости выглядит так: `strict` → `baseline` → `off`

**Допустимые режимы для зависимых моделей в зависимости от режима родительской модели**<br />При движении вниз по графу зависимостей можно сохранить тот же режим или ослабить его, но нельзя сделать режим дочерней модели строже родительского. В следующей таблице показаны допустимые режимы для зависимых моделей в зависимости от режима родительской модели:

| Режим родительской модели | Допустимый режим дочерней модели      |
| ------------------------- | ------------------------------------- |
| `strict`                  | `strict`, `baseline` или `off`        |
| `baseline`                | `baseline` или `off` (но не `strict`) |
| `off`                     | только `off`                          |

Например, для цепочки зависимостей «Модель A → Модель B → Модель C»:

* Если для модели A задан режим `baseline`, вы *не можете* задать для модели B режим `strict`
* Если для модели A задан режим `strict`, вы *можете* задать для модели B режим `baseline`

Это гарантирует, что более строгие требования к проверке не будут применяться к зависимым моделям, если родительские модели не соответствуют этим требованиям. Режим `baseline` не формирует полную проанализированную схему, которая нужна режиму `strict` от вышестоящих моделей, поэтому модель, зависящая от модели с режимом `baseline`, не может выполнять проверку типов на уровне `strict`.

Более подробное обсуждение и иллюстрации см. на странице концепций v2: [Новые концепции](https://docs.getdbt.tech/docs/build/about-static-analysis.md). Дополнительные сведения о схеме JSON см. в [файле dbt-jsonschema](https://github.com/dbt-labs/dbt-jsonschema/blob/1e2c1536fbdd421e49c8b65c51de619e3cd313ff/schemas/latest_fusion/dbt_project-latest-fusion.json#L4689).

### Пользовательские материализации

К моделям, использующим [пользовательскую материализацию](https://docs.getdbt.tech/guides/create-new-materializations.md), применяются те же правила `static_analysis`, что и к любой другой модели, независимо от того, даёте ли вы материализации новое имя или используете имя встроенной материализации, например `table` или `incremental`. Зависимые модели подчиняются обычным [правилам каскадного распространения](#how-static-analysis-modes-cascade).

Если пользовательская материализация добавляет или переименовывает столбцы либо меняет их типы, dbt v2 не может предсказать эти изменения на основе SQL модели. В первую очередь это влияет на режим `strict`, которому нужны точные схемы вышестоящих моделей. Если вы используете `strict`, задайте `static_analysis: off` для моделей, использующих такую материализацию.

Поскольку режим `off` распространяется каскадно, все зависимые модели также теряют возможность статического анализа и использования связанных с ним функций, таких как отслеживание зависимостей на уровне столбцов и проверка типов. Чтобы сохранить охват статическим анализом в вашем DAG, используйте материализации, изменяющие схему, для моделей, от которых не зависят другие модели.

Дополнительные сведения см. в разделе [Пользовательские материализации](https://docs.getdbt.tech/docs/build/about-static-analysis.md#custom-materializations).

## Переопределение в CLI

Вы можете переопределить конфигурацию уровня модели для отдельного запуска с помощью флага [`--static-analysis`](https://docs.getdbt.tech/reference/global-configs/static-analysis-flag.md). Например, чтобы отключить статический анализ для запуска:

```bash
dbt run --static-analysis off # disable static analysis for all models
dbt run --static-analysis baseline # use baseline analysis for all models
```

## Примеры

Следующие примеры показывают, как отключить или настроить `static_analysis` для различных сценариев:

* [Включение строгого анализа для всех моделей](#enable-strict-analysis-for-all-your-models)
* [Отключение статического анализа для всех моделей в пакете](#disable-static-analysis-for-all-models-in-a-package)
* [Отключение статического анализа в YAML для отдельной модели](#disable-static-analysis-in-yaml-for-a-single-model)
* [Отключение статического анализа в SQL для модели, использующей пользовательскую UDF](#disable-static-analysis-in-sql-for-a-model-using-a-custom-udf)
* [Настройка статического анализа для тестов данных](#configure-static-analysis-for-data-tests)
* [Настройка статического анализа для модульных тестов](#configure-static-analysis-for-unit-tests)
* [Настройка статического анализа для seed-файлов](#configure-static-analysis-for-seeds)
* [Настройка статического анализа для снимков](#configure-static-analysis-for-snapshots)

### Включение строгого анализа для всех моделей

Рекомендуемый способ обеспечить максимально полную проверку SQL во всём проекте — задать значение `strict` в конфигурации `models` верхнего уровня в файле `dbt_project.yml`. Эта конфигурация включает строгий анализ для каждой модели в проекте, поэтому настраивать каждую модель отдельно не требуется:

dbt\_project.yml

```yml
name: jaffle_shop

models:
  jaffle_shop:
    +static_analysis: strict
    staging:
      +materialized: view
    marts:
      +materialized: table
```

При необходимости для отдельных подкаталогов или моделей можно задать значение `baseline` или `off` (например, для моделей, использующих неподдерживаемые UDF). Для отдельных моделей можно использовать менее строгие настройки, чем в конфигурации уровня проекта, но нельзя задать более строгие. Значение по умолчанию для проекта — `baseline`.

В этом примере строгий статический анализ применяется только к моделям Jaffle Shop. Установленные пакеты сохраняют настройку по умолчанию `baseline`, если вы явно не настроите их иначе.

### Отключение статического анализа для всех моделей в пакете

В этом примере показано, как отключить статический анализ для всех моделей в пакете. [Префикс `+`](https://docs.getdbt.tech/reference/resource-configs/plus-prefix.md) применяет конфигурацию ко всем моделям в пакете.

dbt\_project.yml

```yml
name: jaffle_shop

models:
  jaffle_shop:
    marts:
      +materialized: table

  a_package_with_introspective_queries:
    +static_analysis: off
```

### Отключение статического анализа в YAML для отдельной модели

В этом примере показано, как отключить статический анализ для одной модели в YAML.

models/my\_udf\_using\_model.yml

```yml
models:
  - name: model_with_static_analysis_off
    config:
      static_analysis: off
```

### Отключение статического анализа SQL для модели, использующей пользовательскую UDF

В этом примере показано, как отключить статический анализ для модели, использующей пользовательскую [user-defined function (UDF)](https://docs.getdbt.tech/docs/build/udfs.md), в SQL-файле.

models/my\_udf\_using\_model.sql

```sql
{{ config(static_analysis='off') }}

select
  user_id,
  my_cool_udf(ip_address) as cleaned_ip
from {{ ref('my_model') }}
```

### Настройка статического анализа для тестов данных

В этом примере показано, как настроить статический анализ для всех тестов в проекте с помощью `dbt_project.yml`.

dbt\_project.yml

```yaml
# dbt_project.yml
data_tests:
  +static_analysis: baseline
```

Чтобы настроить статический анализ для конкретного теста данных модели:

models/filename.yml

```yaml
# models/filename.yml
models:
  - name: my_model
    data_tests:
      - not_null:
          arguments:
            column_name: order_id
          config:
            static_analysis: off
```

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

### Настройка статического анализа для модульных тестов

Вы можете задать `static_analysis` для [модульных тестов](https://docs.getdbt.tech/docs/build/unit-tests.md), которые проверяют логику вашего SQL на статических тестовых данных перед построением модели.

В этом примере показано, как настроить статический анализ для всех модульных тестов в проекте с помощью `dbt_project.yml`.

dbt\_project.yml

```yaml
# dbt_project.yml
unit_tests:
  my_project:
    +static_analysis: baseline
```

Чтобы настроить отдельный модульный тест в файле свойств:

models/filename.yml

```yaml
# models/filename.yml
unit_tests:
  - name: test_is_valid_email_address
    model: dim_customers
    config:
      static_analysis: off
```

Если для модульного теста задать [`compute: local`](https://docs.getdbt.tech/reference/resource-configs/compute.md) (при этом тест выполняется с помощью DuckDB, а не вашей платформы данных), его режим `static_analysis` повышается до `strict`, поскольку для локального выполнения требуется строгий анализ, позволяющий преобразовать ваш SQL в диалект DuckDB. Это происходит, даже если вы сами задали для теста `baseline`.

Если задать `static_analysis: off` для модульного теста, настроенного на локальное выполнение, тест не сможет выполниться и завершится с ошибкой `ExecutorFailed (dbt1401)`. Вместо этого используйте для такого теста `compute: remote`.

`compute: local` — экспериментальная возможность, для которой требуется установить переменную окружения `DBT_ENGINE_EXPERIMENTAL_LOCAL_UNIT_TESTS` в значение `true`, поэтому описанное взаимодействие действует только после её явного включения.

### Настройка статического анализа для seed-файлов

В этом примере показано, как настроить статический анализ для всех seed-файлов в проекте.

dbt\_project.yml

```yaml
# dbt_project.yml
seeds:
  your_project:
    +static_analysis: baseline
```

Чтобы настроить отдельный seed-файл в файле свойств:

seeds/filename.yml

```yaml
# seeds/filename.yml
seeds:
  - name: my_seed
    config:
      static_analysis: off
```

### Настройка статического анализа для снимков

В этом примере показано, как настроить статический анализ для всех снимков в проекте.

dbt\_project.yml

```yaml
# dbt_project.yml
snapshots:
  your_project:
    +static_analysis: baseline
```

Чтобы настроить отдельный снимок в файле свойств:

snapshots/filename.yml

```yaml
# snapshots/filename.yml
snapshots:
  - name: my_snapshot
    config:
      static_analysis: off
```

## Особенности использования

* Для моделей отключение статического анализа означает, что функции расширения VS Code, зависящие от понимания SQL, будут недоступны.
* Для моделей статический анализ в некоторых случаях может завершаться ошибкой (например, при использовании динамических SQL-конструкций или нераспознанных UDF), и вам может потребоваться задать `static_analysis: off`. Дополнительные примеры приведены в разделе [Когда следует отключать статический анализ?](https://docs.getdbt.tech/docs/build/about-static-analysis.md#when-should-i-turn-static-analysis-off).
* Поскольку режимы применяются каскадно, заданный вами режим не всегда совпадает с фактически действующим. Чтобы проверить действующий режим для модели, используйте CodeLens в расширении dbt для VS Code или в Studio IDE: он показывает, для каких моделей статический анализ отключён и почему.

## Связанная документация

* [О статическом анализе](https://docs.getdbt.tech/docs/build/about-static-analysis.md)
* [Флаг `--static-analysis`](https://docs.getdbt.tech/reference/global-configs/static-analysis-flag.md)
* [Оптимизация статического анализа для разработки и развёртывания](https://docs.getdbt.tech/best-practices/optimize-static-analysis-for-development-and-deployment.md)