Implementation:MaterializeInc Materialize Dbt Adapter Exceptions

Overview

The dbt-materialize adapter exceptions module defines custom error classes for handling configuration validation failures in the Materialize dbt adapter. These exceptions are raised when the refresh_interval configuration for materialized views cannot be parsed or does not conform to the expected structure.

The module is located at misc/dbt-materialize/dbt/adapters/materialize/exceptions.py.

Exception Hierarchy

Both exceptions extend dbt_common.exceptions.CompilationError, which is the standard dbt mechanism for reporting errors that occur during model compilation (before SQL execution).

CompilationError (dbt_common)
  +-- RefreshIntervalConfigNotDictError
  +-- RefreshIntervalConfigError

RefreshIntervalConfigNotDictError

Raised when the refresh_interval configuration value is not a dictionary.

Constructor

class RefreshIntervalConfigNotDictError(CompilationError):
    def __init__(self, raw_refresh_interval: Any):
        self.raw_refresh_interval = raw_refresh_interval
        super().__init__(msg=self.get_message())

Error Message

The message reports the actual value received and describes the expected format:

Invalid refresh_interval config:
  Got: <actual_value>
  Expected a dictionary with at minimum a "at", "at_creation", or "every" key

Expected Input

The refresh_interval config must be a dictionary containing at least one of the following keys:

Key	Purpose
at	Specifies a fixed time for refresh
at_creation	Triggers refresh at view creation time
every	Specifies a periodic refresh interval

RefreshIntervalConfigError

Raised when the refresh_interval dictionary has the correct type but fails detailed validation (e.g., invalid field values or types).

Constructor

class RefreshIntervalConfigError(CompilationError):
    def __init__(self, exc: TypeError):
        self.exc = exc
        super().__init__(msg=self.get_message())

Error Message

Delegates to the inherited validator_error_message method to extract a human-readable description from the underlying TypeError:

def get_message(self) -> str:
    validator_msg = self.validator_error_message(self.exc)
    msg = f"Could not parse refresh interval config: {validator_msg}"
    return msg

Usage Context

These exceptions are part of the dbt-materialize adapter's model configuration pipeline. When a user defines a refresh_interval in their dbt model config (e.g., in dbt_project.yml or a model's config block), the adapter validates the value before generating SQL. If validation fails, one of these exceptions halts compilation with a descriptive error message.

Key Source Files

File	Path
Exception definitions	misc/dbt-materialize/dbt/adapters/materialize/exceptions.py