Skip to main content

static_analysis

static_analysis controls how the Fusion engine analyzes SQL at compile time for models, tests, seeds, and snapshots.

info

The static_analysis config is available in the dbt Fusion engine only. It isn't available in dbt Core and will be ignored. To upgrade to Fusion, refer to Get started with Fusion.

The static_analysis config sets how the dbt Fusion engine validates SQL before execution—using strict analysis, a baseline that balances checks with compatibility, or off to skip analysis when needed. You can find supported configuration locations for each resource type.

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') }}

Definition​

You can configure static_analysis for models, tests, seeds, and snapshots.

You can configure if and when the dbt Fusion engine performs static SQL analysis for a model. Configure the static_analysis config in your project YAML file (dbt_project.yml), model properties YAML file, or in a SQL config block in your model file. Refer to Principles of static analysis for more information on the different modes of static analysis.

Setting a model to strict does not automatically set strict for downstream models; they keep the project default unless you configure them explicitly. For more information and examples, refer to strict mode inheritance.

The following values are available for static_analysis:

  • baseline (default): Statically analyze SQL. This is the recommended starting point for users transitioning from dbt Core, providing a smooth migration experience while still catching most SQL errors. You can incrementally opt-in to stricter analysis over time.
  • strict (previously on): Statically analyze all SQL before execution begins. Use this for maximum validation guarantees — nothing runs until the entire project is proven valid.
  • off: Skip SQL analysis for this model and its descendants.
Deprecated values

The on and unsafe values are deprecated and will be removed in May 2026. Use strict instead.

User-defined functions (UDFs) in strict mode​

When static_analysis: strict is in effect, the dbt Fusion engine parses CREATE FUNCTION statements from sql_header and from on-run-start project hooks, registers those UDFs in the compiler registry, and makes them available during strict static compilation. The baseline and off modes don't perform this UDF registration for static analysis.

A model’s sql_header can include multiple statements. Fusion registers UDFs from CREATE FUNCTION statements and ignores other statements for this step.

If strict analysis still cannot resolve a UDF, set static_analysis: off on the affected models.

How static analysis modes cascade​

Two rules determine how static_analysis modes apply in a lineage:

  • Eligibility rule: A model is eligible for static analysis only if all of its "parents" are eligible (by parents, we mean the models that are upstream of the current model in the lineage).
  • Strictness rule: A "child" model cannot be stricter than its parent (by child, we mean the models that are downstream of the current model in the lineage).

The static analysis configuration cascades from most strict to least strict. Here's the strictness hierarchy: strict → baseline → off

Allowed downstream by parent mode
When going downstream in your lineage, you can keep the same mode or relax it; but you cannot make a child stricter than its parent. The following table shows the allowed downstream modes by parent mode:

Parent modeChild can be
strictstrict, baseline, or off
baselinebaseline or off (not strict)
offoff only

For example, for the lineage Model A → Model B → Model C:

  • If Model A is baseline, you cannot set Model B to strict
  • If Model A is strict, you can set Model B to baseline

This makes sure that stricter validation requirements don't apply downstream when parent models haven't met those requirements.

Refer to the Fusion concepts page for deeper discussion and visuals: New concepts. For more info on the JSON schema, refer to the dbt-jsonschema file.

CLI override​

You can override model-level configuration for a run using the following CLI flags. For example, to disable static analysis for a run:

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

See static analysis CLI flag.

Examples​

The following examples show how to disable static analysis for all models in a package, for a single model, and for a model that uses a custom UDF, and how to configure static analysis for tests, seeds, and snapshots.

Disable static analysis for all models in a package​

This example shows how to disable static analysis for all models in a package. The + prefix applies the config to all models in the package.

dbt_project.yml
name: jaffle_shop

models:
  jaffle_shop:
    marts:
      +materialized: table

  a_package_with_introspective_queries:
    +static_analysis: off

Disable static analysis in YAML for a single model​

This example shows how to disable static analysis for a single model in YAML.

models/my_udf_using_model.yml
models:
  - name: model_with_static_analysis_off
    config:
      static_analysis: off

Disable static analysis in SQL for a model using a custom UDF​

This example shows how to disable static analysis for a model using a custom user-defined function (UDF) in a SQL file.

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') }}

Configure static analysis for tests​

This example shows how to set static analysis for all tests in a project using dbt_project.yml.

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

To configure static analysis for a specific test on a model:

models/filename.yml
# models/filename.yml
models:
  - name: my_model
    data_tests:
      - not_null:
          config:
            static_analysis: off

Configure static analysis for seeds​

This example shows how to set static analysis for all seeds in a project.

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

To configure a single seed in a properties file:

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

Configure static analysis for snapshots​

This example shows how to set static analysis for all snapshots in a project.

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

To configure a single snapshot in a properties file:

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

Considerations​

  • For models, disabling static analysis means that features of the VS Code extension that depend on SQL comprehension will be unavailable.
  • For models, static analysis might fail in some cases (for example, dynamic SQL constructs or unrecognized UDFs) and may require setting static_analysis: off. For more examples, refer to When should I turn static analysis off?.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading