03. dbt_project.yml Explained
The Blueprint of Your Project: dbt_project.yml
While profiles.yml tells DBT where your data warehouse is, dbt_project.yml tells DBT how to execute the code in your repository.
Every single DBT project must contain a dbt_project.yml file at its root. This file acts as the ultimate configuration blueprint, binding your raw SQL files into a cohesive application.
1. The Interaction of Configuration Files
2. Dissecting the Configuration File
When you initialize a new project, DBT generates a default dbt_project.yml. Let's break down its essential sections:
A. Project Identity
name: 'jaffle_shop'
version: '1.0.0'
config-version: 2
This defines the foundational metadata of your project. The name must be unique and is referenced globally throughout DBT.
B. The Warehouse Bridge
profile: 'jaffle_shop_profile'
This is the critical link. When DBT runs, it looks at this profile string, and then searches your ~/.dbt/profiles.yml file for matching credentials.
C. Directory Mapping
model-paths: ["models"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
test-paths: ["tests"]
This tells DBT exactly which folders inside your repository contain which types of files. If you rename your /models folder to /transformations, you must update this path.
D. Global Materialization Rules
models:
jaffle_shop:
+materialized: view # Default rule for the whole project
staging:
+materialized: view # Sub-folder override
marts:
+materialized: table # Sub-folder override
Instead of hardcoding configuration inside every single SQL file, you can apply overriding rules to entire folders. In the example above, everything in the marts folder will be built as physical TABLES, while everything in staging will be built as virtual VIEWS.
Summary
The dbt_project.yml file transforms a directory of isolated SELECT statements into an orchestrated pipeline. By utilizing environment-wide configurations, it keeps your project incredibly DRY (Don't Repeat Yourself) and scalable.