Skip to main content

Project variables

dbt provides a mechanism, variables, to provide data to models for compilation. Variables allow you to define configurable values for your project instead of hardcoding them in SQL.

Variables can be defined in two ways:

Variables defined in the dbt_project.yml act as project-wide defaults. These defaults apply anywhere the variable is referenced. You can override them at runtime using the --vars command-line argument, which is useful when you want to change a value for a specific run. For example, when testing with a different date range or running models with environment-specific settings.

You might use variables to configure timezones, set reporting date ranges, avoid hardcoding table names, or otherwise control how models are compiled.

To use a variable in a model, hook, or macro, use the {{ var('...') }} function. The var() function retrieves the value defined in your project or passed using --vars. For more information, see About var function.

Note, refer to YAML tips for more YAML information.

Defining variables in dbt_project.yml​

info

Jinja is not supported within the vars config, and all values will be interpreted literally.

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.

When you need to override a variable for a specific run, use the --vars command line option. For example, when you want to test with a different date range, run models with environment-specific settings, or adjust behavior dynamically.

Use --vars to pass one or more variables to a dbt command. Provide the argument as a YAML dictionary string.

For example:

$ dbt run --vars '{"event_type": "signup"}'

Inside a model or macro, access the value using the var() function:

select '{{ var("event_type") }}' as event_type

When you pass variables using --vars, you can access them anywhere you use the var() function in your project.

You can pass multiple variables at once:

$ dbt run --vars '{event_type: signup, region: us}'

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

$ dbt run --vars 'event_type: signup'

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

Variables defined using --var, override values defined in dbt_project.yml. This makes --vars useful for temporarily overriding configuration without changing your committed project files. For the complete order of precedence (including package-scoped variables and default values defined in var()), see Variable precedence.

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 accessible to the root project and all installed packages.

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 root dbt_project.yml file
  3. The global variable declaration in the root dbt_project.yml file
  4. If this node is defined in a package: variable declarations in that package's dbt_project.yml file
  5. The variable's default argument (if one is provided)

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

Note: Variable scope is based on the node ultimately using that variable. Imagine the case where a model defined in the root project is calling a macro defined in an installed package. That macro, in turn, uses the value of a variable. The variable will be resolved based on the root project's scope, rather than the package's scope.

Questions from the Community​

LoadingAsk the Community

Was this page helpful?

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

0
Loading