How to Use Variables in dbt
Last updated July 25, 2026 · By the SaturnSQL team
Define vars in dbt_project.yml and read them with the var() function, passing a second argument as a default for when the var is unset. Override values at runtime with the --vars flag, which takes a YAML/JSON dict string.
Project defaults
Vars declared at the top level of dbt_project.yml apply to every package in the project. You can also scope them per package by nesting them under the package name, which matters when an installed package happens to declare a var with the same name as one of yours.
# dbt_project.yml
vars:
start_date: '2024-01-01'
excluded_statuses: ['test', 'internal']In a model
var() is resolved at compile time, so the value is baked into the SQL dbt sends to the warehouse. The second argument is the fallback used when the var is not set anywhere; without it, a missing var is a compilation error. Note the quoting: the Jinja uses double quotes because the surrounding SQL string already uses single ones.
SELECT *
FROM {{ ref('stg_orders') }}
WHERE created_at >= '{{ var("start_date", "2020-01-01") }}'Override at runtime
--vars takes a YAML dict as a single string and overrides both project defaults and values set elsewhere. This is the usual way to parameterize a backfill, running the same models over an earlier start_date without editing the project. Quote carefully in a shell, since the outer single quotes are what keep the JSON intact.
dbt run --vars '{"start_date": "2026-01-01"}'Run this in SaturnSQL
SaturnSQL is a browser-based SQL editor for teams: shared query library, schema-aware autocomplete, and scheduled exports to Google Sheets and Slack.
Try it free