dbt Project Structure Guide: Practical Layout for models / seeds / macros

In dbt, folder layout and naming conventions translate directly into developer experience and operational cost. The layout of models, seeds, and macros in particular has a direct impact on DAG visibility, review-ability, and CI selectivity.

This article presents a layout you can run with minimal surprise, grounded in stable features and the official documentation. Exam-prep takeaways are woven in at the end.

Why Structure Matters

dbt follows a "file placement = resource definition" philosophy. Models turn SQL into database objects, seeds turn CSVs into tables, and macros let you reuse logic via Jinja. When placement is ambiguous, DAG boundaries blur and reviews and impact analysis become difficult.

Exams also frequently ask about the staging → intermediate → marts split, the proper use of seeds, and the role and scope of macros. Lock in roles and granularity first, then apply consistent schemas and tags through dbt_project.yml.

• Splitting the DAG into layers clarifies tests and ownership
• Operate directories together with a paired naming convention
• Apply schema, materialization, and tags in bulk via dbt_project.yml hierarchy settings

Recommended Layout: Practical Structure for models / seeds / macros

Following the principle of least surprise, split models in two tiers (layer then domain), organize seeds by purpose, and separate macros into general utilities and adapter dispatch. Declare schema and materialization per layer in dbt_project.yml, and tie them to CI selectors and tags.

The tree below is a general structure that scales from small to mid-sized projects. It uses three layers (stg/int/marts), groups seeds by function (e.g. mappings), and separates macros into util and tests.

• Organize models by layer (staging, intermediate, marts) → then by domain
• Split seeds into subfolders by change frequency and reference target (e.g. mappings)
• Break macros down by responsibility — util, tests, materializations

A standard dbt project structure and DAG layering

project/
  dbt_project.yml
  packages.yml
  models/
    staging/
      src__app/
        stg_app__users.sql
        stg_app__orders.sql
    intermediate/
      int__orders_enriched.sql
    marts/
      sales/
        dim_customer.sql
        fct_order.sql
  seeds/
    mappings/
      country_codes.csv
  macros/
    util/
      surrogate_key.sql
      cast_to_boolean.sql
    tests/
      relationships_if.sql
  snapshots/
    app/
      orders_snapshot.sql
  tests/
    generic/
      not_null_if.sql

DAG (conceptual):
[raw.sources] → [staging: stg_*] → [intermediate: int_*] → [marts: dim_*/fct_*]

Example dbt_project.yml plus model/macro snippets

# dbt_project.yml (excerpt)
name: my_project
version: 1.0.0
profile: my_profile
model-paths: ["models"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
test-paths: ["tests"]

models:
  +materialized: view
  my_project:
    staging:
      +schema: stg
      +tags: ["staging"]
    intermediate:
      +schema: int
      +tags: ["transform"]
    marts:
      +schema: mart
      +materialized: table
      sales:
        +schema: mart_sales

seeds:
  my_project:
    +schema: seed
    +quote_columns: false
    mappings:
      country_codes:
        +column_types:
          country_code: varchar(2)
          country_name: varchar(64)

# macros/util/surrogate_key.sql
{% macro surrogate_key(cols) %}
md5({{ cols | map('string') | join(" || '-' || ") }})
{% endmacro %}

# models/marts/sales/dim_customer.sql
{{ config(materialized='table') }}
with src as (
  select * from {{ ref('int__orders_enriched') }}
), dedup as (
  select distinct customer_id, customer_name from src
)
select
  {{ surrogate_key(["customer_id"]) }} as customer_sk,
  customer_id,
  customer_name
from dedup;

Key Points for dbt_project.yml

Project configuration is fundamentally hierarchical. Set defaults at the top and override them in lower directories to stabilize schema, materialization, and tags per layer. A conservative default is materialized=view, with marts as the only layer set to table.

For seeds, explicitly set schema, quote_columns, and column_types. In particular, give primary keys and code columns explicit lengths so you do not depend on each target warehouse's default types.

• Use hierarchical application of +schema, +materialized, +tags
• Align selectors.yml with tags so CI can run partial builds
• Set column_types on seeds explicitly to avoid drift from type mismatches

Naming Conventions and DAG Splits: stg / int / marts

Unify filenames with prefixes that indicate the layer. stg_ normalizes types and column names on raw data, int_ joins and aggregates business logic, and dim_ and fct_ are the final deliverables. Avoid cross-layer references; ref should ideally point only one layer downstream.

Splitting schemas per layer keeps table listings and privilege design clear. In DAG visualizations, ensure the edges between layers consistently point in one direction to prevent cycles.

• stg_: type unification, naming conventions, PK generation
• int_: multi-source integration, aggregation, window calculations
• dim_/fct_: analytics tables. Reverse references to upstream layers are forbidden

When to Use Seeds and What to Watch For

Seeds are intended for small reference tables. Manage code systems, labels, thresholds, and similar data — things that change infrequently but are joined into models — as CSVs. dbt seed loads them as database tables, and you can apply tests just like with models.

The pitfalls are size, types, and change management. Large CSVs are a bad fit. Set column_types explicitly, review diffs in pull requests, and pay attention to privileges and locale (delimiters, line endings) in operations.

• Limit to small, stable reference data
• Manage column_types and primary-key tests as a set
• Minimize per-environment differences (encoding, delimiters)

Design Principles and Reuse for Macros

Macros generate SQL at compile time. Functionize at a granularity that does not hide business logic too aggressively or hurt SQL readability. Surrogate-key generation, type conversion, and conditional tests are good examples.

Adapter differences can be absorbed via dispatch, but from a stability standpoint it is easier to debug if you avoid over-generalizing and keep adapter-specific branches lightweight. Pin versions when introducing external macro packages.

• Start at "functionize once a pattern repeats three or more times"
• Separate concerns: test macros vs. materializations
• Pin external package versions and verify changes carefully

Exam-Prep and Real-World Checklist

The Analytics Engineer exam targets the distinction between models / seeds / macros, the hierarchical settings in dbt_project.yml, ref/source, and the applicability of tests. In particular, the purpose of seeds, model-layer separation, and macro responsibilities are must-know.

In real-world work, use CI selectors (tags/paths) for partial builds, isolate privileges and catalogs with schema separation, and check for layer violations and macro overuse during reviews.

• By default, ref points one layer downstream to prevent cycles
• Manage seed CSVs as a set: types, primary keys, and tests
• Keep macros side-effect free and observable

Check Your Understanding

FAQ