A new concept: static analysis

The dbt Fusion engine fully comprehends your project's SQL, enabling advanced capabilities like dialect-aware validation and precise column-level lineage.

It can do this because its compilation step is more comprehensive than that of the dbt Core engine. When dbt Core referred to compilation, it only meant rendering — converting Jinja-templated strings into a SQL query to send to a database.

The dbt Fusion engine can also render Jinja, but then it completes a second phase: static analysis, producing and validating a logical plan for every rendered query in the project. This step is the cornerstone of Fusion's new capabilities.

Step	dbt Core engine	dbt Fusion engine
Render Jinja into SQL	✅	✅
Produce and statically analyze logical plan	❌	✅
Run rendered SQL	✅	✅

Loading table...

Principles of static analysis

The software engineering concept of static analysis describes checks that can be done on code before it runs (static == not running).

The most rigorous static analysis means you can trust that if the analysis succeeds, the code will run in production without compilation errors.

Less strict static analysis also surfaces helpful information to developers as they work. There's no free lunch—what you gain in responsiveness you lose in correctness guarantees.

The dbt Fusion engine uses the static_analysis config to help you control how it performs static analysis for your models.

The dbt Fusion engine is unique in that it can statically analyze not just a single model in isolation, but every query from one end of your DAG to the other. Even your database can only validate the query in front of it! Concepts like information flow theory — although not incorporated into the dbt platform yet — rely on stable inputs and the ability to trace columns DAG-wide.

Baseline mode: A smooth transition from dbt Core

The dbt Fusion engine defaults to static_analysis: baseline mode, inspired by similar type-checking and linting tools like TypeScript's migration approach, basedpyright's baseline feature, and Pydantic's strict/lax modes.

The philosophy behind the above-mentioned tools and Fusion's baseline mode is:

• Smooth transition: Provide a familiar first-time experience for users coming from dbt Core.
• Incremental opt-in: Offer a clear pathway to adopt more Fusion features over time.
• Pragmatic validation: Catch most SQL errors without requiring a complete project overhaul.

Use this style of gradual typing to start with lightweight validation, then incrementally adopt strict guarantees as your project is ready.

What baseline mode changes

Baseline mode introduces several fundamental behavior changes compared to the previous binary (off/on) approach:

• No downloading of remote schemas — Baseline mode does not fetch schemas from the warehouse.
• Unit tests work without strict mode — Previously, unit tests required static analysis to be fully on. In baseline mode, they work out of the box.
• No unsafe introspection warnings — We no longer warn about unsafe introspection, though we'd still love to help you assess it in the future.

The following table shows how baseline mode expands what's available without requiring strict mode.

LSP feature comparison

Baseline mode unlocks a meaningful set of features without requiring strict mode. We're also investing in moving more features into baseline over time.

VS Code extension features by static analysis configuration:

✅ = Available | ❌ = Not available

Feature	off	baseline	strict
Go-to-definition	✅*	✅	✅
Table lineage	✅	✅	✅
YAML validation	✅	✅	✅
Render + preview SQL	✅	✅	✅
Unit tests	✅	✅	✅
Detect syntax errors	❌	✅	✅
Preview CTE results	❌	✅	✅
Automatic refactor column names	❌	❌**	✅
Column lineage (local)	❌	❌**	✅
Detect data type and function signature errors	❌	❌	✅

Loading table...

*Column-level go-to-definition requires baseline; macros, refs, and docs work without it.

Feature	off	baseline	strict
Go-to-definition/reference (except columns)	✅	✅	✅
Table lineage	✅	✅	✅
YAML validation	✅	✅	✅
Render + preview SQL	✅	✅	✅
Unit tests	✅	✅	✅
Detect syntax errors	❌	✅	✅
Preview CTE results	❌	✅	✅
Go-to-definition/reference (columns)	❌	❌	✅
Automatic refactor column names	❌	❌	✅
Rich column lineage	❌	❌	✅
Detect data type and function signature errors	❌	❌	✅

Loading table...

CodeLens visibility

The VS Code extension and Studio IDE provide CodeLens even when static analysis is off, giving you visibility into which models have static analysis disabled and why.

Ultimately, we want everyone developing in strict mode for maximum guarantees. We acknowledge this isn't a change that can happen overnight — baseline exists to smooth the transition. Many planned features (like local compute) require strict mode. We're also exploring inferring column types on your behalf, which would enable more functionality in baseline mode without requiring you to manually provide type information.

Introspection handling in baseline mode

In baseline mode, all static analysis findings are warnings, not errors — your project can continue running even when the compiler flags invalid or problematic SQL. This section is a good example of why that design exists.

Previously, with strict mode, the system assumed local schemas of your compiled models would be available. In baseline mode, we can no longer assume the full local schema is available and complete, so baseline uses the remote database as the source of truth — similar to dbt Core.

The practical result is that the Fusion compiler may sometimes flag incorrect queries that result from introspective queries that come back empty. If you encounter this, you can:

1. Ignore the warning
2. Build the model locally
3. (Coming soon) Use warn_error_options to disable the warning

For example, consider this query using the dbt_utils.unpivot macro:

select * from (
{{
    dbt_utils.unpivot(
        relation=ref('example_model'),
        cast_to='integer',
        exclude=['order_id', 'customer_id'],
        field_name='product_type',
        value_name='quantity'
    )
}}
)

If the introspection query fails or returns no results, this renders to:

select * from (

)

This is invalid SQL. In baseline mode, Fusion displays a warning so your project can continue running while still alerting you to the issue:

dbt0101: no viable alternative at input '(
    
)'
  --> models/example_model.sql:17:1

Migration scenarios

Migrating to Fusion can involve more than moving YAML around. Some scenarios that can make migration more involved include:

1. Limited access to sources: You don't have access to all the sources and models of a large dbt project.
2. Intricate Jinja workflows: Your project uses post-hooks and introspection extensively.
3. Package compatibility: Your project depends on packages that aren't yet Fusion-compatible.
4. Unsupported SQL features: Your models or sources use advanced data types (STRUCT, ARRAY, GEOGRAPHY) or built-in functions (AI.PREDICT, JSON_FLATTEN, st_pointfromgeohash) not yet supported by the dbt Fusion engine.

Setting static_analysis to baseline mode lets you start using Fusion immediately while you address these scenarios incrementally. As you resolve compatibility issues, you can opt specific models or your entire project into strict mode for maximum validation guarantees.

Recapping the differences between engines

dbt Core:

• Renders and runs models one at a time.
• Never runs static analysis.

The dbt Fusion engine (baseline mode — default):

• Statically analyzes all models, catching most SQL errors while providing a familiar migration experience.

The dbt Fusion engine (strict mode):

• Renders and statically analyzes all models before execution begins.
• Guarantees nothing runs until the entire project is proven valid.

Configuring static_analysis

You can modify the way static analysis is applied for specific models in your project. The static analysis configuration cascades from most strict to least strict. Going downstream in your lineage, a model can keep the same mode or relax it — it can't be stricter than its parent. For the full rules and examples, see How static analysis modes cascade.

The static_analysis config options are:

• 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.
• 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 on this model and its descendants.

Deprecated values

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

When you disable static analysis, features of the VS Code extension which depend on SQL comprehension will be unavailable.

The best place to configure static_analysis is as a config on an individual model or group of models. As a debugging aid, you can also use the --static-analysis strict or --static-analysis off CLI flags to override all model-level configuration.

Incrementally adopting strict mode

Once you're comfortable with Fusion in baseline mode, you can incrementally opt models or directories into strict mode:

dbt_project.yml

name: jaffle_shop

models:
  jaffle_shop:
    # Start with strict analysis on your cleanest models
    staging:
      +static_analysis: strict
    # Keep baseline for models that need more work
    marts:
      +static_analysis: baseline

This approach lets you gain the benefits of strict validation where possible while keeping the flexibility of baseline analysis for models that aren't yet compatible.

Refer to CLI options and Configurations and properties to learn more about configs.

Example configurations

Disable static analysis for all models in a 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:

models/my_udf_using_model.yml

models:
  - name: model_with_static_analysis_off
    config:
      static_analysis: off

Disable static analysis for a model using a custom UDF:

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

When should I turn static analysis off?

With baseline mode enabled by default, static analysis is less likely to block your runs. You should only disable it if the dbt Fusion engine cannot parse SQL that is valid for your database of choice.

This is a very rare occurrence. If you encounter this situation, please open an issue with an example of the failing SQL so we can update our parsers.

More information about Fusion

Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations:

• About the dbt Fusion engine
• About the dbt extension
• New concepts in Fusion
• Supported features matrix
• Installing Fusion CLI
• Installing VS Code extension
• Fusion release track
• Quickstart for Fusion
• Upgrade guide
• Fusion licensing

Was this page helpful?

Privacy policyCreate a GitHub issue

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