How to Organize Models in dbt for Clear Project Structure

In dbt, organize models by grouping SQL files into folders inside the models/ directory to reflect business domains or data layers. Use dbt_project.yml to configure folder-specific settings and apply clear naming conventions for easy navigation and maintenance.

Syntax

dbt organizes models as SQL files inside the models/ directory. You can create subfolders to group related models. The dbt_project.yml file lets you configure these folders with settings like materializations or tags.

Example structure:

• models/: root folder for models
• models/staging/: staging models
• models/marts/: data marts or business layer

In dbt_project.yml, you can specify configurations per folder:

yaml

models:
  staging:
    materialized: view
  marts:
    materialized: table

Example

This example shows a simple dbt project structure with two folders: staging and marts. The staging folder contains raw data transformations, and marts contains business logic models.

sql

# Directory structure:
# models/
# ├── staging/
# │   └── customers.sql
# └── marts/
#     └── customer_summary.sql

-- models/staging/customers.sql
select * from raw.customers

-- models/marts/customer_summary.sql
select
  customer_id,
  count(*) as order_count
from {{ ref('staging.customers') }}
group by customer_id

Common Pitfalls

Common mistakes when organizing models in dbt include:

• Putting all models in one folder, making it hard to find or manage them.
• Not using dbt_project.yml to configure folder-specific settings, leading to inconsistent materializations.
• Using unclear or inconsistent naming conventions, which confuse collaborators.

Correct organization improves readability and maintainability.

yaml

models:
  # Wrong: no folder config, all models mixed
  
  # Right: separate folders with configs
  staging:
    materialized: view
  marts:
    materialized: table

Quick Reference

Concept	Description	Example
Folder Structure	Group models by purpose or domain	models/staging/, models/marts/
dbt_project.yml	Configure folder-specific settings	models: staging: materialized: view
Naming Conventions	Use clear, consistent names	stg_customers.sql, mart_customer_summary.sql
References	Use {{ ref() }} to link models	{{ ref('staging.customers') }}
Materializations	Set how models are built (table/view)	materialized: table

Key Takeaways

Organize models into folders inside the models/ directory to reflect data layers or domains.

Use dbt_project.yml to set folder-specific configurations like materializations.

Apply clear and consistent naming conventions for easier collaboration.

Use {{ ref() }} to manage dependencies between models cleanly.

Avoid mixing all models in one folder to keep the project maintainable.