Principle:MaterializeInc Materialize Source and Model Definition
| Knowledge Sources | dbt-materialize adapter source code, dbt-core relation and adapter base classes, Materialize SQL documentation |
|---|---|
| Domains | Declarative Data Modeling, SQL Templating, Data Pipeline Architecture |
| Last Updated | 2026-02-08 |
Overview
Declarative data transformation modeling defines data sources and transformation models through SQL templates with metadata annotations, enabling model-driven data pipelines with introspection.
Description
The Source and Model Definition principle describes how a data transformation framework organizes data assets into two primary categories:
- Sources: External data feeds ingested into the database. These are declared (not created) by the framework, providing metadata that allows downstream models to reference them by logical name.
- Models: SQL-based transformations that read from sources or other models and produce new relations. Models are materialized into database objects whose type depends on configuration (views, materialized views, tables, sinks, etc.).
A critical abstraction in this principle is the relation. A relation is a typed reference to a database object, encapsulating its database, schema, identifier, and relation type (view, table, materialized view, source, sink, etc.). Relations provide:
- Type discrimination: Each relation carries a type enum that determines what DDL operations are valid (e.g., you cannot
DROP VIEWon a source). - Quoting policy: Relations enforce quoting rules for identifiers, preventing SQL injection and handling reserved words.
- Name length constraints: Different databases impose different limits on identifier lengths; the relation class enforces these.
- Introspection helpers: Boolean properties like
is_materialized_view,is_source,is_sinkallow the adapter to branch behavior based on relation type.
The adapter class ties relations to the framework by implementing methods for listing relations, resolving relation types from catalog metadata, and caching relation information for performance.
Usage
Apply this principle when:
- Defining new data sources or transformation models in a dbt project targeting a streaming or incremental database.
- Extending the set of supported materialization types for a database adapter (e.g., adding source tables, sinks).
- Understanding how the framework resolves logical model references to physical database objects.
- Implementing catalog introspection that correctly handles non-standard relation types.
Theoretical Basis
The declarative data pipeline paradigm treats data transformations as a directed acyclic graph (DAG) of SQL statements, where the framework handles dependency resolution, execution ordering, and materialization. Each node in the DAG is either a source (leaf node) or a model (internal/output node).
The relation type system is a form of algebraic data type applied to database objects. By enumerating all possible relation types and attaching behavior to each, the adapter avoids untyped string comparisons and provides exhaustive pattern matching over relation kinds. This is especially important for databases like Materialize that extend the standard SQL relation taxonomy with types such as source, source_table, sink, and legacy materializedview.
The adapter pattern with relation polymorphism allows the framework core to operate on generic relation objects while each database adapter supplies its own relation subclass with custom type enums, name length limits, and type-checking properties.