Organizing models in directories in dbt

Introduction

Organizing models in directories helps keep your project neat and easy to understand. It makes finding and managing your data models faster.

When you have many data models and want to group them by topic or function.

When working in a team and need a clear structure everyone can follow.

When you want to separate raw data models from cleaned or aggregated models.

When you want to reuse parts of your project in different places easily.

When you want to improve navigation and reduce mistakes in large projects.

Syntax

dbt

models/
  ├── staging/
  │     ├── customers.sql
  │     └── orders.sql
  ├── marts/
  │     ├── sales.sql
  │     └── finance.sql
  └── intermediate/
        └── customer_orders.sql

Each folder inside models/ is a directory for related models.

dbt automatically finds models in subdirectories without extra config.

Examples

Models grouped by their role: staging for raw data, marts for business logic.

dbt

models/staging/customers.sql
models/staging/orders.sql
models/marts/sales.sql

Models organized by department or business area.

dbt

models/finance/revenue.sql
models/finance/expenses.sql
models/marketing/campaigns.sql

Models organized by time periods like quarters or years.

dbt

models/2024_Q1/sales.sql
models/2024_Q1/returns.sql
models/2024_Q2/sales.sql

Sample Program

This example shows two models in different folders. The customer_summary.sql model uses ref() to connect to models in the staging folder.

dbt

/* File: models/staging/customers.sql */
select * from raw.customers

/* File: models/marts/customer_summary.sql */
select
  customer_id,
  count(order_id) as total_orders
from {{ ref('customers') }}
join {{ ref('orders') }} using (customer_id)
group by customer_id

Important Notes

Use meaningful folder names to make your project easy to navigate.

dbt runs models in dependency order using ref(), so folder structure does not affect build order.

You can add dbt_project.yml configs to control model materializations per folder.

Summary

Organizing models in directories keeps your dbt project clean and easy to manage.

Folders help group models by function, team, or time period.

dbt automatically detects models in subfolders and builds them correctly.