Implementation:MaterializeInc Materialize MaterializeAdapter Parse Index

Knowledge Sources	misc/dbt-materialize/dbt/adapters/materialize/impl.py
Domains	Compute Resource Allocation, Index Strategy, Materialized View Configuration
Last Updated	2026-02-08

Overview

Concrete index parsing, refresh interval parsing, and cluster name generation methods for Materialize provided by the MaterializeAdapter, translating declarative configurations into validated typed objects for DDL generation.

Description

This implementation covers three related methods on the MaterializeAdapter class that handle compute resource and index configuration:

parse_index() (L185-186): Accepts a raw dictionary from dbt model configuration and delegates to MaterializeIndexConfig.parse(). The MaterializeIndexConfig dataclass validates and deserializes the dictionary, ensuring it contains valid fields: columns (list of column names), default (boolean), name (optional custom index name), and cluster (optional cluster override).

parse_refresh_interval() (L188-192): Decorated with @available to expose it to Jinja macros. Accepts a raw dictionary and delegates to MaterializeRefreshIntervalConfig.parse(). The config dataclass supports fields: at (timestamp), at_creation (boolean), every (interval string), aligned_to (alignment timestamp), and on_commit (boolean, the default behavior).

generate_final_cluster_name() (L341-357): Decorated with @available. Resolves the final cluster name through a two-stage macro chain:

1. Calls generate_cluster_name macro with the provided cluster name (allows custom naming conventions).
2. If the deploy CLI variable is set or force_deploy_suffix is True, additionally calls generate_deploy_cluster_name to append the deployment suffix (e.g., _dbt_deploy).

Usage

Use this implementation when:

• Defining indexes on materialized views or views via dbt model configuration.
• Configuring refresh intervals for materialized views (periodic, scheduled, or on-commit).
• Understanding how cluster names are resolved during normal runs vs. blue-green deployments.
• Debugging index or refresh interval configuration validation errors.

Code Reference

Source Location

File	Lines	Description
misc/dbt-materialize/dbt/adapters/materialize/impl.py	L185-186	parse_index() method
misc/dbt-materialize/dbt/adapters/materialize/impl.py	L188-192	parse_refresh_interval() method
misc/dbt-materialize/dbt/adapters/materialize/impl.py	L341-357	generate_final_cluster_name() method
misc/dbt-materialize/dbt/adapters/materialize/impl.py	L49-74	MaterializeIndexConfig dataclass
misc/dbt-materialize/dbt/adapters/materialize/impl.py	L80-100	MaterializeRefreshIntervalConfig dataclass

Signature

@dataclass
class MaterializeIndexConfig(dbtClassMixin):
    columns: Optional[List[str]] = None
    default: Optional[bool] = False
    name: Optional[str] = None
    cluster: Optional[str] = None

    @classmethod
    def parse(cls, raw_index) -> Optional["MaterializeIndexConfig"]: ...


@dataclass
class MaterializeRefreshIntervalConfig(dbtClassMixin):
    at: Optional[str] = None
    at_creation: Optional[bool] = False
    every: Optional[str] = None
    aligned_to: Optional[str] = None
    on_commit: Optional[bool] = False

    @classmethod
    def parse(cls, raw_refresh_interval) -> Optional["MaterializeRefreshIntervalConfig"]: ...


class MaterializeAdapter(PostgresAdapter, SQLAdapter):
    def parse_index(self, raw_index: Any) -> Optional[MaterializeIndexConfig]: ...

    @available
    def parse_refresh_interval(
        self, raw_refresh_interval: Any
    ) -> Optional[MaterializeRefreshIntervalConfig]: ...

    @available
    def generate_final_cluster_name(
        self, cluster_name: str, force_deploy_suffix: bool = False
    ) -> Optional[str]: ...

Import

from dbt.adapters.materialize import MaterializeAdapter

I/O Contract

Inputs

Parameter	Type	Description
raw_index (for parse_index)	Any (typically dict)	A dictionary with keys: columns (list of str), optional default (bool), optional name (str), optional cluster (str). Returns None if input is None.
raw_refresh_interval (for parse_refresh_interval)	Any (typically dict)	A dictionary with optional keys: at (str), at_creation (bool), every (str), aligned_to (str), on_commit (bool). Returns None if input is None.
cluster_name (for generate_final_cluster_name)	str	The logical cluster name from model configuration.
force_deploy_suffix (for generate_final_cluster_name)	bool	When True, always appends the deploy suffix regardless of the deploy CLI variable. Default: False.

Outputs

Return	Type	Description
(from parse_index)	Optional[MaterializeIndexConfig]	A validated index configuration object, or None if input was None.
(from parse_refresh_interval)	Optional[MaterializeRefreshIntervalConfig]	A validated refresh interval configuration object, or None if input was None.
(from generate_final_cluster_name)	Optional[str]	The resolved cluster name after applying naming macros and optional deploy suffix.

Usage Examples

-- dbt model with index and refresh interval configuration
{{
  config(
    materialized='materialized_view',
    cluster='analytics',
    indexes=[
      {'columns': ['user_id'], 'cluster': 'analytics'},
      {'columns': ['created_at', 'user_id'], 'name': 'idx_time_user'}
    ],
    refresh_interval={'every': '1 hour', 'aligned_to': '2024-01-01T00:00:00'}
  )
}}

SELECT user_id, created_at, event_type
FROM {{ source('events', 'raw_events') }}

# Programmatic usage (typically called internally by dbt macros)
from dbt.adapters.materialize import MaterializeAdapter

# Parse an index configuration
index_config = adapter.parse_index({
    'columns': ['user_id', 'timestamp'],
    'cluster': 'analytics',
    'default': False,
})
# index_config.columns == ['user_id', 'timestamp']
# index_config.cluster == 'analytics'

# Generate a cluster name during deployment
cluster = adapter.generate_final_cluster_name('analytics', force_deploy_suffix=True)
# Returns 'analytics_dbt_deploy' (after macro chain)

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Cluster_and_Index_Configuration

Requires Environment

• Environment:MaterializeInc_Materialize_Dbt_Materialize_Runtime