Skip to main content

04. dbt_project.yml Explained

️ Understanding dbt_project.yml​

The dbt_project.yml file is the heart of any DBT project.
It defines project-level configurations, including model paths, naming conventions, and profile linkage.


1. What is dbt_project.yml?​

  • A YAML configuration file created when you initialize a DBT project
  • Stores:
    • Project name & version
    • Profile to connect to your warehouse
    • Source & model directories
    • Materialization defaults
    • Custom configurations

2. Example dbt_project.yml​

name: my_dbt_project        # Project name
version: 1.0.0 # Version
config-version: 2 # Current config version

profile: my_snowflake_conn # Profile name from profiles.yml

model-paths: ["models"] # Where DBT models are stored
seed-paths: ["seeds"] # Where CSV seeds are stored
snapshot-paths: ["snapshots"] # Where snapshots live
macro-paths: ["macros"] # Macros directory

models:
my_dbt_project: # Apply config to this project
materialized: view # Default materialization for models

3. Key Sections​

SectionPurpose
nameProject identifier
profileLinks to connection details in profiles.yml
model-pathsDirectory where DBT looks for model SQL files
seed-pathsLocation for seed CSV files
snapshot-pathsLocation for snapshots
modelsConfigure materialization defaults & tags for models

4. Common Configurations​

  • Materializations: Set default as view or table
  • Tags: Apply tags for models
  • Schema naming: Override schema for environments

Example:

models:
my_dbt_project:
+schema: analytics
+tags: ["core"]

5. Best Practices​

Keep it clean and organized Use config-version: 2 (latest) Use relative paths for portability Override configurations in dbt_project.yml instead of hardcoding in models


6. Why is it important?​

  • It controls how DBT runs your models
  • Ensures consistency across environments
  • Helps maintain flexible and scalable projects

Summary​

  • dbt_project.yml is mandatory for every DBT project
  • It defines paths, profiles, and configurations
  • Acts as the blueprint for DBT execution