Using variables

dbt provides a mechanism, variables, to provide data to models for compilation. Variables can be used to configure timezones, avoid hardcoding table names or otherwise provide data to models to configure how they are compiled.

To use a variable in a model, hook, or macro, use the {{ var('...') }} function. More information on the var function can be found here.

Variables can defined in two ways:

  1. In the dbt_project.yml file
  2. On the command line

Defining variables in dbt_project.yml

New in v0.17.0

The syntax for specifying vars in the dbt_project.yml file has changed in dbt v0.17.0. See the migration guide for more information on these changes.

To define variables in a dbt project, add a vars config to your dbt_project.yml file. These vars can be scoped globally, or to a specific package imported in your project.

dbt_project.yml
name: my_dbt_project
version: 1.0.0
config-version: 2
vars:
# The `start_date` variable will be accessible in all resources
start_date: '2016-06-01'
# The `platforms` variable is only accessible to resources in the my_dbt_project project
my_dbt_project:
platforms: ['web', 'mobile']
# The `app_ids` variable is only accessible to resources in the snowplow package
snowplow:
app_ids: ['marketing', 'app', 'landing-page']
models:
...

Defining variables on the command line

The dbt_project.yml file is a great place to define variables that rarely change. Other types of variables, like date ranges, will change frequently. To define (or override) variables for a run of dbt, use the --vars command line option. In practice, this looks like:

$ dbt run --vars '{"key": "value"}'

The --vars argument accepts a YAML dictionary as a string on the command line. YAML is convenient because it does not require strict quoting as with JSON.

Both of the following are valid and equivalent:

$ dbt run --vars '{"key": "value", "date": 20180101}'
$ dbt run --vars '{key: value, date: 20180101}'

If only one variable is being set, the brackets are optional, eg:

$ dbt run --vars 'key: value'

You can find more information on defining dictionaries with YAML here.

Variable precedence

Variables defined with the --vars command line argument override variables defined in the dbt_project.yml file. They are globally scoped and will be accessible to all packages included in the project.

The order of precedence for variable declaration is as follows (highest priority first):

  1. The variables defined on the command line with --vars.
  2. The package-scoped variable declaration in the dbt_project.yml file
  3. The global variable declaration in the dbt_project.yml file.
  4. The variable's default argument (if one is provided).

If dbt is unable to find a definition for a variable after checking these four places, then a compilation error will be raised.