Skip to main content

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

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

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_ or fct_).
    • Example: marts/marketing/dim_campaigns.sql
    • Example: marts/finance/fct_revenue.sql

2. Best Practice Naming Checklist​

When naming files, columns, and folders, follow these universal DBT standards:

The Golden Rules of Naming
  1. Lowercase Only: Always use lowercase for schema, table, and column names. (e.g., user_id, not UserID).
  2. Snake Case: Use underscores to separate words. (e.g., order_items, not orderItems or order-items).
  3. Plural vs Singular: Be consistent. Standard practice is to make table names plural (e.g., customers, orders).
  4. Descriptive over Concise: fct_monthly_recurring_revenue.sql is drastically better than fct_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.