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
| Section | Purpose |
|---|---|
name | Project identifier |
profile | Links to connection details in profiles.yml |
model-paths | Directory where DBT looks for model SQL files |
seed-paths | Location for seed CSV files |
snapshot-paths | Location for snapshots |
models | Configure materialization defaults & tags for models |
4. Common Configurations
- Materializations: Set default as
viewortable - 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.ymlis mandatory for every DBT project- It defines paths, profiles, and configurations
- Acts as the blueprint for DBT execution