dbt_project.yml

The dbt_project.yml file is the central configuration file for your dbt project. Every dbt project must have one in its root folder. It tells dbt the project name, which database profile to connect with, where to find different types of files, and what default settings to apply to models, seeds, and snapshots.

File Location

my_dbt_project/
├── dbt_project.yml    ← must be here (project root)
├── models/
├── seeds/
└── ...

Complete Annotated dbt_project.yml

# Project identity
name: 'my_dbt_project'         ← project name (used in ref() resolution)
version: '1.0.0'               ← your project version (for documentation)
config-version: 2              ← always 2 for modern dbt

# Connection
profile: 'my_warehouse'        ← must match a top-level key in profiles.yml

# File paths (relative to project root)
model-paths: ["models"]        ← where SQL model files live
analysis-paths: ["analyses"]   ← where analysis SQL files live
test-paths: ["tests"]          ← where singular test files live
seed-paths: ["seeds"]          ← where CSV seed files live
macro-paths: ["macros"]        ← where macro files live
snapshot-paths: ["snapshots"]  ← where snapshot files live

# Output paths
target-path: "target"          ← where compiled SQL goes
clean-targets:                 ← folders deleted by dbt clean
  - "target"
  - "dbt_packages"

# Model configurations
models:
  my_dbt_project:              ← must match the 'name' field above
    +materialized: view        ← default for all models
    staging:
      +materialized: view      ← override for staging/ folder
      +tags: ['staging']
    intermediate:
      +materialized: ephemeral ← override for intermediate/ folder
    marts:
      +materialized: table     ← override for marts/ folder
      +tags: ['mart']
      finance:
        +schema: finance       ← models in marts/finance/ go to finance schema
        +tags: ['finance', 'mart']

# Seed configurations
seeds:
  my_dbt_project:
    +schema: reference_data    ← all seeds go to reference_data schema
    country_codes:
      +column_types:
        code: varchar(2)

# Snapshot configurations
snapshots:
  my_dbt_project:
    +target_schema: snapshots  ← all snapshots go to snapshots schema

# Variable definitions
vars:
  start_date: '2024-01-01'
  minimum_order_amount: 10

The + Prefix

Properties prefixed with + are configuration properties that apply to all models in the scope. Properties without + are structural keys (like folder names).

models:
  my_project:
    staging:         ← structural key: refers to the staging/ folder
      +materialized: view   ← config property: applies to all models in staging/
      +tags: ['staging']    ← config property: tags all staging models

Config Inheritance

Configurations cascade from parent to child. A model in marts/finance/ inherits settings from my_dbt_project, then marts, then finance. More specific settings override less specific ones.

my_dbt_project:
  +materialized: view       ← all models default to view
  marts:
    +materialized: table    ← marts/ overrides to table
    finance:
      +schema: finance      ← marts/finance/ gets finance schema + table materialization

Applying Tags

models:
  my_project:
    +tags: ['all_models']
    staging:
      +tags: ['staging', 'daily']
    marts:
      +tags: ['mart']
      finance:
        +tags: ['finance']   ← models in finance/ get: all_models + mart + finance

Run models by tag:

dbt run --select tag:finance
dbt run --select tag:daily

Custom Schema per Folder

models:
  my_project:
    marts:
      finance:
        +schema: finance      ← writes to analytics_finance schema
      marketing:
        +schema: marketing    ← writes to analytics_marketing schema
      operations:
        +schema: ops          ← writes to analytics_ops schema

Grants Configuration

Automatically grant query permissions to roles after models run:

models:
  my_project:
    marts:
      +grants:
        select: ['REPORTER_ROLE', 'BI_TOOL_ROLE']

Meta Fields

Add custom key-value metadata to models for documentation and tooling:

models:
  my_project:
    marts:
      +meta:
        owner: 'data-team@company.com'
        tier: 'gold'
        sla_minutes: 30

Common Mistakes

Mistake 1: project name in models block doesn't match 'name' field
  name: 'my_project'
  models:
    my_dbt_project:    ← WRONG, should be my_project
      ...

Mistake 2: forgetting the + prefix on config properties
  models:
    my_project:
      staging:
        materialized: view   ← WRONG (no +)
        +materialized: view  ← CORRECT

Mistake 3: YAML indentation errors (use 2 spaces, not tabs)