Setting project-wide configuration in dbt_project.yml

The dbt_project.yml file lets you define default configurations for models, seeds, snapshots, and other resources at the project, directory, or subdirectory level, avoiding the need to repeat config() blocks in every model. Configurations set here apply hierarchically based on file path, and can be overridden by more specific configs in individual model files or in yml property files.

1 · Learn the must-know

• 1Configurations in dbt_project.yml are nested under resource type keys (e.g., models:, seeds:, snapshots:) followed by the project name and then folder paths matching your file structure.
• 2The precedence order from lowest to highest is: dbt_project.yml defaults, then config() in the model/seed/snapshot file itself, then config defined in a schema.yml or properties file, with the most specific/local config always winning.
• 3Common configs set here include materialized, schema, tags, enabled, persist_docs, and grants, which can be applied broadly to a folder or narrowed to subfolders.
• 4Setting materialized: view or table at the top project level creates a default that individual folders (e.g., staging vs. marts) can override with more specific materializations like incremental or ephemeral.
• 5A common gotcha is indentation errors or mismatched folder paths in the yml hierarchy, which silently cause configs not to apply as expected since dbt won't always error loudly.
• 6The +config-key: value syntax (with a leading plus sign) is required for resource configs in dbt_project.yml to distinguish them from folder path keys, especially in dbt version 0.17+.

2 · Check your understanding