Custom materializations let you control the full lifecycle of how dbt builds a model — from checking existing state through creating the final relation. They’re macros with a specific structure, and they solve problems that built-in materializations don’t address: zero-downtime swaps, pre-swap validation, and automated security policy management.
This hub connects the notes that cover the topic end to end.
Foundations
- dbt Materialization Anatomy — The six-step structure every materialization follows, the key context objects (
this,sql,config,adapter), and the adapter methods you’ll use constantly. - When to Write Custom dbt Materializations — Decision framework: when to use post-hooks, macros, or built-in incrementals instead, and the specific scenarios where custom materializations are worth the maintenance cost.
Patterns
- Zero-Downtime Table Materialization in dbt — Build to a temp name, validate row counts (absolute and relative), then swap via rename. The old table stays queryable until the new one is confirmed ready. The simpler of the two patterns and a good starting point.
- Secured Table Materialization in dbt — Automatically reapply BigQuery row access policies, column descriptions, and data masking tags after every rebuild. Makes security configuration declarative instead of buried in post-hooks.
Operations
- Debugging Custom dbt Materializations — Common error messages and their causes, a systematic testing approach (first-run path, subsequent-run path, failure paths), and debugging techniques for materialization development.
Related Concepts
Custom materializations sit at the intersection of several dbt and BigQuery concepts:
- Incremental Models in dbt — The built-in materialization that handles most incremental patterns. Understand what it covers before going custom.
- Incremental Strategy Decision Framework — Decision framework for the built-in incremental strategies (merge, delete+insert, insert_overwrite, microbatch).
- dbt Materialization Cost Impact on BigQuery — How materialization choices affect BigQuery costs. Custom materializations add a COUNT query for validation but save costs by preventing bad data from propagating.
- BigQuery IAM Patterns — The IAM layer that controls dataset-level access. The secured table materialization adds row-level and column-level controls on top of IAM.
- dbt Macros — The foundation. Materializations are macros with a specific contract.