Handbook contents

Handbook

Choose the route you need

This handbook explains how and why the project works. It assumes you have written SQL, but not that you know dbt, Git or dimensional modelling. You can read the examples without installing anything. The field guides provide the steps when you are ready to work in the project.

I am new to dbt

Read the handbook at your own pace, or use the guided course for shorter interactive lessons. You do not need to complete both.

I need to answer a new question

Begin with the request, discover what the project already knows, then design and test the missing change.

I need to make a safe PR

Use the practical route for setup, local builds, evidence, review and changing models that already have consumers.

I am responsible for production

Understand the project workflows, then use the shared run history to investigate health, impact and recovery.

The complete learning sequence

Read in order for the full explanation. Take a break after the foundations, after model design, or after local validation. Times allow for reading and examples; hands-on practice and revisiting unfamiliar ideas take longer.

Begin with purpose, data and analytical tables. Then follow dependencies, layers, discovery and design. Finish with testing, local validation, review and production. Use the dataset directory and production reference for details you need to look up rather than remember.

  1. 1Why dbt?How a SQL query becomes a shared, repeatable model · ~8 min
  2. 2Analysts and dbtContributing safely and knowing who should help with a decision · ~6 min
  3. 3The data we modelSource families, people, identifiers and the limits of linkage · ~10 min
  4. 4Understanding analytical tablesRows, keys, joins, missing values, facts and dimensions · ~18 min
  5. 5How models depend on each otherReferences, sources and the dependency graph · ~9 min
  6. 6Data layersWhere source preparation, shared definitions and products belong · ~20 min
  7. 7Reading model namesUse prefixes, subjects and suffixes to interpret a model · ~9 min
  8. 8Finding and reusing modelsFollow a question through candidate models, evidence and a decision · ~12 min
  9. 9Designing modelsChoose useful boundaries, preserve meaning and compose analytical models · ~24 min
  10. 10Tests & documentationWrite model promises and choose tests that can disprove them · ~18 min
  11. 11Building and checking a changeRun the right commands and reconcile the analytical result · ~13 min
  12. 12Git & pull requestsUnderstand Git states, review focused changes and record decisions · ~22 min
  13. 13From merge to productionRelease small changes, validate their effect and follow later refreshes · ~15 min
  14. 14Observing productionInvestigate failures, assess impact and confirm recovery · ~12 min