dbt · dbt Fundamentals

What is dbt_project.yml?

Easydbt_project.ymlconfigurationproject

Interview question

What is dbt_project.yml, and what does it configure?

How to answer

The short answer

dbt_project.yml is the project config file at the root of a dbt project. It tells dbt the project name, where folders live, default configs, and project-level variables.

Typical contents

YAML
name: my_analytics
version: 1.0.0
config-version: 2
profile: my_analytics   # which profile in profiles.yml

model-paths: ["models"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
test-paths: ["tests"]
analysis-paths: ["analyses"]

models:
  my_analytics:
    staging:
      +materialized: view
      +schema: staging
    marts:
      +materialized: table

vars:
  start_date: "2020-01-01"

What it controls

  • Project name and which profile to use
  • Paths for models, seeds, macros, tests, snapshots
  • Default materializations / schemas / tags by folder
  • Project vars (overridable on the CLI)
  • Package install behavior (with packages.yml separately)

Mental model

Output
dbt_project.yml  =  "how this repo is organized and defaulted"
profiles.yml     =  "how to connect to warehouses / environments"

Interview tip: dbt_project.yml is committed to git. Connection credentials are not stored here; they live in profiles.yml (or env-driven equivalents) outside the project or via secrets.

Two behaviours that surprise people

By default, a +schema setting is added to your target schema, it does not replace it. With a target schema of analytics, the staging folder above builds into analytics_staging. Teams that want the exact name override the generate_schema_name macro.

Configs also stack. A config() block inside a single model overrides the folder default from dbt_project.yml, which is why a mart folder set to table can still contain one view. For vars, a command line value wins over the file: dbt run --vars '{start_date: 2024-01-01}'.