Module explain 

Explain command — show the EXPLAIN plan for a materialized view or index.

This command compiles the project, spins up an ephemeral Materialize Docker container, stages the target object’s dependencies in a dedicated schema, creates the target, and runs EXPLAIN to show the query plan.

Target Format

database.schema.object — explain a materialized view database.schema.object#index_name — explain a specific index

Dependency Staging Algorithm

For each dependency of the target object:

1. If the dependency has indexes on the same cluster as the target → stub as TABLE + create those matching indexes on quickstart.
2. Else if the dependency is a materialized view, table, or table-from-source → stub as TABLE only.
3. Else (plain view) → recursively stage its dependencies, then create it.

All IN CLUSTER clauses are rewritten to quickstart via the ExplainTransformer.

Schema Lifecycle

The target’s database is created with IF NOT EXISTS and a dedicated schema _mz_explain_<timestamp> is created before staging. The schema is dropped with CASCADE after completion (even on error). The Docker container itself is reused across runs.

Structs

ExplainOutput 🔒

Output of the explain command.

ExplainTarget 🔒

The parsed explain target: an object and optional index name.

Enums

StagingAction 🔒

Actions to stage dependencies before running EXPLAIN.

Functions

build_explain_sql 🔒

Build the EXPLAIN SQL statement.

build_index_sql 🔒

Build SQL for creating an index in the explain schema.

build_view_sql 🔒

Build SQL for creating a view in the explain schema.

create_target 🔒

Create the target object (MV + indexes if explaining an index).

execute_explain 🔒

Execute the staging actions, create the target, and run EXPLAIN.

extract_text_from_messages 🔒

Extract raw text lines from SimpleQueryMessage results.

get_columns_for_stub 🔒

Get column schemas for a stub table.

load_types_and_cache 🔒

Load types.lock and open ProjectCache for stub table column schemas.

parse_target 🔒

Parse a target string like database.schema.object or database.schema.object#index.

plan_dep 🔒

Recursively plan staging for a single dependency.

plan_staging 🔒

Build the staging actions for all transitive dependencies of the target.

run

Run the explain command.

validate_target 🔒

Validate the target is an MV or index and return the target cluster name.