dbt
Intermediate 13 min read dbt

dbt Project Structure

One folder, one vocabulary for the whole warehouse

A dbt project is a folder with models, sources, seeds, macros, tests, and a series of configuration files. Naming and folder conventions make the warehouse readable and the dependencies obvious.

dbtproject structuremodels folderschema.ymlprofiles.ymlconventions
Prerequisites: What is dbt?
Before we start

What you will learn

  • Name the key folders and files in a dbt project
  • Explain staging vs marts folder conventions
  • Wire up a dbt project to a warehouse
Introduction

What is this?

A dbt project is a git repository containing a dbt_project.yml, models organized into folders (staging, intermediate, marts), YAML schema files describing sources and columns, seeds, macros, and tests. Conventions like prefixing staging models with stg_ make every model's job obvious from its name.

Motivation

Why do you need it?

  • A consistent project layout means any analyst can find any model.
  • Folder structure signals the layer — nobody queries staging for a board metric.
  • dbt_project.yml centralizes materialization and path configs so models stay simple.
Think about it

Mental model

Imagine

A shared kitchen

Think of

A dbt project

There is a spot for produce (staging), a spot for prep (intermediate), and the pass (marts) — everyone knows where things go and why.

Mechanics

How it works

  • dbt_project.yml declares the project name, model paths, and default materializations.
  • Models live in folders that map to layers: staging, intermediate, marts.
  • YAML schema files sit beside models to declare tests, descriptions, and sources.
  • profiles.yml holds the warehouse connection; dbt reads it to run the project.

A dbt project organizes models by layer with config at the root.

Root
Models
YAML
Output
Real world

In production

  • New analysts find the daily revenue mart because it lives in marts and is documented.
  • The whole team renames an upstream source column by editing one staging model.
  • CI validates the folder conventions with a lint rule before merging.
Guidelines

Best practices

  • Use the staging/intermediate/marts convention and name models with their layer prefix.
  • Keep schema YAML next to the models it describes.
  • Put shared logic in macros or intermediate models, not duplicated in marts.
Watch out

Common mistakes

  • Flat folders with descriptive-but-unlayered names like orders_v3_final.
  • Configuring materializations inside model files instead of the project file.
  • Letting analyzer-only notebooks query staging and drift into the dependency graph.
When things break

Debugging tips

  • If dbt cannot find a model, check the model-path config in dbt_project.yml.
  • If two models share a name in different folders, dbt fails on ambiguity — rename one.
Interviews

Interview checkpoint

Practice

Hands-on lab

Scaffold a Layered dbt Project
35 min · beginner
In progress
Objectives
  • Initialize a dbt project and configure a warehouse target
  • Create staging, intermediate, and marts folders
  • Check that the project compiles and runs empty

Scaffold a Layered dbt Project

35 min · beginner

0/4 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Staging models in the convention are usually prefixed

2

profiles.yml holds the

Go deeper

Official documentation

dbt project structure
docs
dbt_project.yml
docs