dbt Project Structure Best Practice: Organize Your Data Models

The best practice for a dbt project structure is to organize your files into clear folders like models, macros, and tests, with subfolders for different business domains or data layers. This helps keep your project clean, easy to navigate, and scalable as it grows.

How It Works

Think of a dbt project like a well-organized kitchen. You want your ingredients (data models) in labeled containers (folders) so you can find and use them quickly. The models folder holds SQL files that transform raw data into useful tables. Inside, you can create subfolders for different areas like sales, marketing, or finance, just like separating spices from baking ingredients.

Other folders like macros store reusable code snippets, similar to having a set of kitchen tools you use often. The tests folder keeps checks to make sure your data is accurate, like tasting your food to ensure it’s just right. This structure helps teams work together smoothly and makes it easier to add new recipes (models) without confusion.

Example

This example shows a simple dbt project folder structure with domain subfolders inside models:

plaintext

my_dbt_project/
├── dbt_project.yml
├── models/
│   ├── sales/
│   │   ├── customers.sql
│   │   └── orders.sql
│   ├── marketing/
│   │   ├── campaigns.sql
│   │   └── leads.sql
│   └── staging/
│       ├── stg_customers.sql
│       └── stg_orders.sql
├── macros/
│   └── date_utils.sql
└── tests/
    └── unique_customer_id.sql

When to Use

Use this project structure best practice when you want to keep your dbt project organized and easy to maintain as it grows. It is especially helpful when multiple people work on the same project or when your data models cover many business areas.

For example, a retail company can separate models for sales, inventory, and marketing to avoid confusion. This structure also makes it easier to test and update parts of the project without breaking others, improving reliability and collaboration.

Key Points

• Organize models into subfolders by domain or data layer.
• Keep reusable code in macros for easy sharing.
• Use tests folder to store data quality checks.
• Maintain a clear, consistent naming convention for files and folders.
• Structure helps teams collaborate and scale projects smoothly.

Key Takeaways

Organize your dbt project with folders like models, macros, and tests for clarity.

Use subfolders in models to separate business domains or data layers.

Keep reusable SQL code in macros to avoid repetition.

Store data quality checks in tests to ensure accuracy.

A clean structure improves teamwork and project scalability.