Skip to main content

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.