Перейти к основному содержимому

static_analysis

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

Конфигурация static_analysis доступна только в dbt v2. Она недоступна в dbt v1 и будет игнорироваться. Чтобы перейти на dbt v2, обратитесь к разделу Начало работы с dbt v2.

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

Какие функции доступны в режиме strict в dbt v2, описано в разделах Поддержка функций Snowflake и Поддержка функций BigQuery.

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

models/filename.yml
models:
  - name: model_name
    config:
      static_analysis: strict | baseline | off
models/model_name.sql
{{ config(static_analysis='strict' | 'baseline' | 'off') }}

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

Вы можете настроить static_analysis для моделей, тестов данных, модульных тестов, seed-файлов и снимков.

Вы можете настроить, будет ли dbt v2 выполнять статический анализ SQL для модели и когда именно. Задайте конфигурацию static_analysis в YAML-файле проекта (dbt_project.yml), YAML-файле свойств модели или в блоке конфигурации SQL в файле модели. Подробнее о различных режимах статического анализа см. в разделе Принципы статического анализа.

Установка режима strict для модели не устанавливает strict автоматически для нижестоящих моделей; они сохраняют настройку проекта по умолчанию, если вы не настроите их явно. Дополнительные сведения и примеры см. в разделе Наследование строгого режима.

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

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

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

При настройке static_analysis: strict dbt v2 разбирает операторы CREATE FUNCTION из sql_header и хуков проекта on-run-start, регистрирует эти UDF в реестре компилятора и делает их доступными при строгой статической компиляции. В режимах baseline и off такая регистрация UDF для статического анализа не выполняется.

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

Если строгий анализ по-прежнему не может разрешить ссылку на UDF, задайте static_analysis: off для затронутых моделей.

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

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

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

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

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

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

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

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

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

Более подробное обсуждение и иллюстрации см. на странице концепций v2: Новые концепции. Дополнительные сведения о схеме JSON см. в файле dbt-jsonschema.

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

К моделям, использующим пользовательскую материализацию, применяются те же правила static_analysis, что и к любой другой модели, независимо от того, даёте ли вы материализации новое имя или используете имя встроенной материализации, например table или incremental. Зависимые модели подчиняются обычным правилам каскадного распространения.

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

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

Дополнительные сведения см. в разделе Пользовательские материализации.

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

Вы можете переопределить конфигурацию уровня модели для отдельного запуска с помощью флага --static-analysis. Например, чтобы отключить статический анализ для запуска:

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

Примеры​

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

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

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

dbt_project.yml
name: jaffle_shop

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

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

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

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

В этом примере показано, как отключить статический анализ для всех моделей в пакете. Префикс + применяет конфигурацию ко всем моделям в пакете.

dbt_project.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
models:
  - name: model_with_static_analysis_off
    config:
      static_analysis: off

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

В этом примере показано, как отключить статический анализ для модели, использующей пользовательскую user-defined function (UDF), в SQL-файле.

models/my_udf_using_model.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
# dbt_project.yml
data_tests:
  +static_analysis: baseline

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

models/filename.yml
# 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 для модульных тестов, которые проверяют логику вашего SQL на статических тестовых данных перед построением модели.

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

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

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

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

Если для модульного теста задать compute: local (при этом тест выполняется с помощью 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
# dbt_project.yml
seeds:
  your_project:
    +static_analysis: baseline

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

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

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

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

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

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

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

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

  • Для моделей отключение статического анализа означает, что функции расширения VS Code, зависящие от понимания SQL, будут недоступны.
  • Для моделей статический анализ в некоторых случаях может завершаться ошибкой (например, при использовании динамических SQL-конструкций или нераспознанных UDF), и вам может потребоваться задать static_analysis: off. Дополнительные примеры приведены в разделе Когда следует отключать статический анализ?.
  • Поскольку режимы применяются каскадно, заданный вами режим не всегда совпадает с фактически действующим. Чтобы проверить действующий режим для модели, используйте CodeLens в расширении dbt для VS Code или в Studio IDE: он показывает, для каких моделей статический анализ отключён и почему.

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

Нашли ошибку?

0
Loading