02. Folder Structure & Naming Conventions
Organizing the models/ Directory
While DBT provides the top-level folders, it is entirely up to you how you organize the /models directory. Without strict naming conventions and deliberate sub-folders, a project with 500 models will become impossible to navigate.
Most enterprise teams follow a Layered Architecture (often compared to the Medallion Architecture: Bronze, Silver, Gold).
️ 1. The Three Primary Layers
A. The Staging Layer (models/staging/)
- Purpose: 1:1 reflection of raw source data, but cleaned up.
- Rules: Rename vague columns, cast data types (e.g., string to timestamp), and do baseline logic. No joining allowed.
- Naming Convention: Prefix with
stg_followed by the source system.- Example:
stg_salesforce_users.sql
- Example:
B. The Intermediate Layer (models/intermediate/)
- Purpose: Complex joins and pre-aggregations that are too messy to put in the final Mart models.
- Naming Convention: Prefix with
int_.- Example:
int_user_session_metrics.sql
- Example:
C. The Marts Layer (models/marts/)
- Purpose: The final, heavily-joined "Gold" tables that BI tools (Tableau, Looker) connect to. These are usually divided by business department.
- Naming Convention: Adhere strictly to Kimball dimensional modeling notation (
dim_orfct_).- Example:
marts/marketing/dim_campaigns.sql - Example:
marts/finance/fct_revenue.sql
- Example:
2. Best Practice Naming Checklist
When naming files, columns, and folders, follow these universal DBT standards:
The Golden Rules of Naming
- Lowercase Only: Always use
lowercasefor schema, table, and column names. (e.g.,user_id, notUserID). - Snake Case: Use underscores to separate words. (e.g.,
order_items, notorderItemsororder-items). - Plural vs Singular: Be consistent. Standard practice is to make table names plural (e.g.,
customers,orders). - Descriptive over Concise:
fct_monthly_recurring_revenue.sqlis drastically better thanfct_mrr.sql. Focus on clarity.
Summary
Strict rules around folder hierarchies (staging vs marts) and prefixes (stg_, fct_, dim_) ensure that anyone looking at your codebase instantly understands exactly what layer of the pipeline a file belongs to.