Skip to main content

About flags (global configs)

In dbt, "flags" (also called "global configs") are configurations for fine-tuning how dbt runs your project. They differ from resource-specific configs that tell dbt about what to run.

Flags control things like the visual output of logs, whether to treat specific warning messages as errors, or whether to "fail fast" after encountering the first error. Flags are "global" configs because they are available for all dbt commands and they can be set in multiple places.

There is a significant overlap between dbt's flags and dbt's command line options, but there are differences:

  • Certain flags can only be set in dbt_project.yml and cannot be overridden for specific invocations via CLI options.
  • If a CLI option is supported by specific commands, rather than supported by all commands ("global"), it is generally not considered to be a "flag".

Setting flags​

There are multiple ways of setting flags, which depend on the use case:

The most specific setting "wins." If you set the same flag in all three places, the CLI option will take precedence, followed by the environment variable, and finally, the value in dbt_project.yml. If you set the flag in none of those places, it will use the default value defined within dbt.

Most flags can be set in all three places:

# dbt_project.yml
flags:
  # set default for running this project -- anywhere, anytime, by anyone
  fail_fast: true
dbt run --fail-fast # set to True for this specific invocation
dbt run --no-fail-fast # set to False

There are two categories of exceptions:

  1. Flags setting file paths: Flags for file paths that are relevant to runtime execution (for example, --log-path or --state) cannot be set in dbt_project.yml. To override defaults, pass CLI options or set environment variables (). Flags that tell dbt where to find project resources (for example, model-paths) are set in dbt_project.yml, but as a top-level key, outside the flags dictionary; these configs are expected to be fully static and never vary based on the command or execution environment.
  2. Opt-in flags: Flags opting in or out of behavior changes can only be defined in dbt_project.yml. These are intended to be set in version control and migrated via pull/merge request. Their values should not diverge indefinitely across invocations, environments, or users.

Accessing flags​

Custom user-defined logic, written in Jinja, can check the values of flags using the flags context variable.

# dbt_project.yml

on-run-start:
  - '{{ log("I will stop at the first sign of trouble", info = true) if flags.FAIL_FAST }}'

Available flags​

Because the values of flags can differ across invocations, we strongly advise against using flags as an input to configurations or dependencies (ref + source) that dbt resolves during parsing.

Common flag examples​

Use the --target flag to specify which target (environment) to use when running dbt commands. For example:

dbt run --target dev
dbt run --target prod
dbt build --target staging

The --target flag allows you to run the same dbt project against different environments without modifying your configuration files. Define the target in your profiles.yml file. Learn more about connection profiles and targets.

Was this page helpful?

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

0
Loading