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.

Functions

run

Run the explain command.