dbt project structure

Introduction

dbt project structure helps organize your data transformation work clearly. It makes your data models easy to find and manage.

When starting a new dbt project to transform raw data into clean tables.

When you want to keep your SQL models, tests, and documentation organized.

When collaborating with a team on data analytics projects.

When you need to version control your data transformation code.

When deploying data models to production with clear folder setup.

Syntax

dbt

my_dbt_project/
  ├── models/
  │    ├── staging/
  │    ├── marts/
  │    └── schema.yml
  ├── macros/
  ├── tests/
  ├── snapshots/
  ├── analyses/
  ├── data/
  ├── dbt_project.yml
  └── profiles.yml

models/ folder contains SQL files for data transformations.

dbt_project.yml is the main config file for your project settings.

Examples

Organize models by purpose: staging for raw data cleaning, marts for business logic.

dbt

models/
  ├── staging/
  │    └── customers.sql
  ├── marts/
  │    └── sales.sql
  └── schema.yml

Macros folder holds reusable SQL snippets to simplify your models.

dbt

macros/
  └── my_macros.sql

Snapshots folder stores SQL to capture data changes over time.

dbt

snapshots/
  └── customer_snapshot.sql

Sample Program

This config file tells dbt where to find models and macros. It also sets how models are built.

dbt

# This is a folder structure example, not runnable code
# But here is a simple dbt_project.yml content example

name: 'my_dbt_project'
version: '1.0'
config-version: 2

model-paths: ['models']
macro-paths: ['macros']

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

Important Notes

Always keep your SQL files inside the models/ folder for dbt to find them.

Use schema.yml files to define tests and documentation for your models.

Profiles.yml is usually outside the project folder and stores connection info securely.

Summary

dbt project structure organizes your data models, macros, tests, and configs.

Use folders like models/, macros/, and snapshots/ for clear separation.

The dbt_project.yml file controls project settings and paths.