Variables and the vars config

You pass variables to dbt models using the Jinja var function, defining default values in dbt_project.yml and overriding them from the command line using the vars argument. Variables provide dynamic parameterization for date boundaries, backfill windows, and model flags without requiring hardcoded values in SQL files.

Defining and referencing variables

You declare default variable values in dbt_project.yml under the vars dictionary:

vars:
  start_date: '2025-01-01'
  enable_experimental_features: false

Inside your model SQL, reference the variable using the var Jinja function, optionally providing an inline fallback default:

select
    order_id,
    customer_id,
    order_total,
    order_date
from {{ ref('stg_orders') }}
where order_date >= '{{ var("start_date", "2025-01-01") }}'

If no override is provided, dbt uses the configured default value.

Passing CLI overrides during backfills

The primary operational use case for variables is ad hoc backfilling and manual testing. When recomputing a specific time range, you override variables directly on the command line using JSON or YAML syntax:

dbt run --select fct_orders --vars '{"start_date": "2026-03-01", "end_date": "2026-03-31"}'

The CLI value takes precedence over any defaults defined in dbt_project.yml, allowing engineers to run scoped backfills without modifying git-tracked model files.

Variables versus environment variables

It is important to distinguish between var and env_var:

• The var function is designed for query parameterization, feature flags, and date intervals. Variables are project-scoped and recorded in manifest.json.
• The env_var function reads environment variables from the host operating system. It is reserved for environment-level secrets, database credentials, schema prefixes, and target connection names.
• Keep business logic visible in SQL: avoid burying core business definitions, revenue formulas, or tax logic inside variables. Hiding business rules in variables obscures lineage and makes models harder to test and maintain.

Using variables strictly for parameters keeps transformation logic transparent and testable.