Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 41 ยท Projects and Models

Project Structure and dbt_project.yml

Learn every folder in a dbt project and how dbt_project.yml configures paths, folder-level settings, variables and hooks, with a runnable config-resolution stand-in.

A dbt project is just a folder of text files with a predictable layout. Once you know what each folder is for, you can open any dbt repository and find your way around in a minute. At the center is dbt_project.yml, the file that tells dbt where things are and how to configure them.

The folders

TEXT
shop_analytics/
โ”œโ”€โ”€ dbt_project.yml        project settings
โ”œโ”€โ”€ packages.yml           third-party packages
โ”œโ”€โ”€ profiles.yml           (usually NOT here; see the setup lesson)
โ”œโ”€โ”€ models/                SELECT statements: the core of the project
โ”‚   โ”œโ”€โ”€ staging/
โ”‚   โ”œโ”€โ”€ intermediate/
โ”‚   โ””โ”€โ”€ marts/
โ”œโ”€โ”€ seeds/                 small CSV files loaded as tables
โ”œโ”€โ”€ snapshots/             history tracking definitions
โ”œโ”€โ”€ macros/                reusable Jinja functions
โ”œโ”€โ”€ tests/                 custom singular tests (SQL files)
โ”œโ”€โ”€ analyses/              SQL that is compiled but never run
โ”œโ”€โ”€ target/                compiled output (generated, ignored by Git)
โ”œโ”€โ”€ dbt_packages/          installed packages (generated, ignored by Git)
โ””โ”€โ”€ logs/                  dbt.log (generated)
  • models/ holds the SQL you build and the YAML that describes it. You will spend most of your time here.
  • seeds/ is for small reference data that lives in Git, such as a country-code mapping.
  • snapshots/ records how rows change over time.
  • macros/ contains reusable Jinja code, and also overrides of built-in behavior.
  • tests/ holds one-off tests written as SQL queries.
  • analyses/ keeps SQL you want version-controlled and compiled (with ref) but not materialized, for example an ad hoc finance query.

dbt_project.yml in detail

YAML
name: "shop_analytics"
version: "1.0.0"
config-version: 2
profile: "shop_analytics"

model-paths: ["models"]
seed-paths: ["seeds"]
test-paths: ["tests"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
analysis-paths: ["analyses"]

clean-targets: ["target", "dbt_packages"]

vars:
  start_date: "2024-01-01"

models:
  shop_analytics:
    +materialized: view
    staging:
      +schema: staging
    marts:
      +materialized: table
      +tags: ["marts"]

seeds:
  shop_analytics:
    +schema: reference

on-run-end:
  - "{{ log('Finished run for ' ~ target.name, info=True) }}"

Walking through it:

  • name identifies the project. It must be a valid identifier and is also the root of the models: config tree.
  • profile links to profiles.yml.
  • *-paths say where each resource type lives. The defaults match the layout above, so you can leave them out.
  • vars defines project variables read with {{ var('start_date') }}. See Context Functions.
  • models:, seeds: and snapshots: set configs by folder. A + before a key marks it as a config (as opposed to a folder name).
  • on-run-start and on-run-end run SQL or macros at the beginning and end of an invocation, for example to grant permissions.

Folder-level configuration

The models: block is a tree that mirrors your folders. Under shop_analytics:, the key staging: means "every model in models/staging/". Settings you put there apply to all models below it, and a more specific path overrides a less specific one.

With the file above, models/staging/stg_orders.sql becomes a view in schema staging, and models/marts/fct_orders.sql becomes a table tagged marts. You wrote no config inside any SQL file.

Let us simulate how dbt resolves the final configuration. This Python stand-in (not dbt) merges folder-level settings from the most general to the most specific, then applies a file-level override:

Python Stand-in: resolving the config of a model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last line shows the override rule: a config() call inside the model file beats any folder setting. The full list of config levels is in Model Configs.

Naming and organization advice

  • Use snake_case for file, model and column names.
  • Make folders mean something: layers (staging, intermediate, marts) and, inside them, sources or business domains.
  • One model per file, and the file name is the model name. Names must be unique across the whole project and its packages, even when files sit in different folders.
  • Keep target/, dbt_packages/ and logs/ in .gitignore.

A typical .gitignore:

TEXT
target/
dbt_packages/
logs/
.venv/
*.duckdb

Other project files you will meet

  • packages.yml lists packages (shared dbt code) to install with dbt deps.
  • selectors.yml defines named selections for repeatable jobs.
  • dependencies.yml declares projects you reference in multi-project setups.
  • .sqlfluff or .pre-commit-config.yaml configure linting and checks in your repository.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do you put reusable Jinja functions?

    Macros live in the macros folder, so any model can call them.
  2. 2. What does a + in front of a key in the models: block mean?

    The plus sign marks a config, as opposed to a sub-folder or model name.
  3. 3. Which folders should normally be excluded from Git?

    target/ and dbt_packages/ are generated and can be rebuilt with dbt run and dbt deps.
  4. 4. Two settings conflict: one in dbt_project.yml for the folder and one in config() inside the model. Which wins?

    More specific configuration overrides general configuration, and an in-file config() is the most specific.

Summary

  • A dbt project is a folder with models/, seeds/, snapshots/, macros/, tests/ and analyses/.
  • dbt_project.yml names the project, links the profile, sets paths, variables, hooks and folder-level configs.
  • The models: tree mirrors your folders; keys starting with + are configs.
  • Specific settings override general ones, and an in-file config() is the most specific of all.

Next: Writing Models and Using ref()