docs: document EXPLAIN REPLAN

[claude]

Requested by Pranshu Maheshwari · Slack thread

Before: a reader searching the docs site for REPLAN found nothing. The SQL commands index listed five EXPLAIN pages, the RBAC command-privileges appendix listed five EXPLAIN rows, and the "Explained object" table on EXPLAIN PLAN stopped at MATERIALIZED VIEW name. The only trace of the keyword anywhere in doc/user was the mechanical keyword appendix.

After: there is an EXPLAIN REPLAN reference page at /sql/explain-replan, listed alongside its siblings in both index listings, and the "Explained object" table on EXPLAIN PLAN has a row pointing at it.

This documents EXPLAIN [<stage> PLAN ... FOR] REPLAN <VIEW | MATERIALIZED VIEW | INDEX> <name>, which re-runs the optimizer on an existing object instead of printing the plan that is already installed.

The page follows the layout of the other EXPLAIN pages: front matter with menu.main.parent: commands, a one-paragraph lede, the shared EXPLAIN instability warning, ## Syntax backed by a new doc/user/data/examples/explain_replan.yml via include-syntax (the mechanism EXPLAIN TIMESTAMP, EXPLAIN SCHEMA, and EXPLAIN FILTER PUSHDOWN use), ## Details, ## Examples, and ## Privileges backed by a new headless snippet. Output blocks are shown in psql's aligned form, matching the example blocks on the sibling pages. The lede states that REPLAN is an explained object of EXPLAIN PLAN rather than a statement of its own, so the stages, formats, and output modifiers are inherited from that page and are linked rather than duplicated.

Motivation

The syntax was introduced in #25026 (merged Feb 2024), whose description introduced it as "new (for now undocumented) syntax". REPLAN VIEW followed in #25586. The omission was therefore deliberate at the time, but explicitly temporary, and it was never revisited: there is no feature flag, no unsafe-mode gate, and no RBAC difference. EXPLAIN ... FOR REPLAN ... is reachable today by any user with USAGE on the object's schema. This closes that gap.

Description

New files:

• doc/user/content/sql/explain-replan.md — the reference page.
• doc/user/data/examples/explain_replan.yml — the syntax block and syntax-element table.
• doc/user/content/headless/sql-command-privileges/explain-replan.md — the privileges snippet. EXPLAIN REPLAN shares the Plan::ExplainPlan RBAC arm, so the requirement is the same as EXPLAIN PLAN: USAGE on the schemas containing the relations in the explainee.

Modified files:

• doc/user/content/sql/explain-plan.md — one row added to the "Explained object" table.
• doc/user/data/sql_commands_all.yml — index entry, alphabetically between EXPLAIN PLAN and EXPLAIN SCHEMA.
• doc/user/data/rbac/command_privileges.yml — appendix entry in the same position.

The non-obvious part worth a reviewer's attention is the stage/object-type support matrix. Every cell below was executed against a live server, not inferred:

Stage	REPLAN VIEW	REPLAN MATERIALIZED VIEW	REPLAN INDEX
Stage omitted (defaults to PHYSICAL PLAN AS TEXT)	No	Yes	Yes
RAW PLAN	Yes	Yes	No
DECORRELATED PLAN	Yes	Yes	No
LOCALLY OPTIMIZED PLAN	Yes	Yes	No
OPTIMIZED PLAN	No	Yes	Yes
PHYSICAL PLAN	No	Yes	Yes

A view rejects the post-optimization stages, an index rejects the pre-optimization stages, and only a materialized view accepts all of them. Bare EXPLAIN REPLAN VIEW v fails with "EXPLAIN statement for a view needs an explicit stage", which the page shows. DECORRELATED PLAN is included because REPLAN runs the full CREATE ... optimizer pipeline, the same pipeline for which EXPLAIN PLAN already documents that stage under its CREATE VIEW and CREATE MATERIALIZED VIEW forms.

Verification

Docs-only change, no automated tests. Validation run locally:

• Every example in the page, including the schema setup, was executed against a Materialize emulator running v26.38.1 (e7e46f0d1). All plan output in the page is verbatim server output, not hand-edited.
• All 18 cells of the matrix above were executed individually against the same server.
• Both hugo builds from ci/test/lint-docs.sh (default config, and config.toml,config.skill.toml for the markdown-docs build) with hugo v0.152.2+extended. Clean.
• htmltest -s ci/www/public -c doc/user/.htmltest.yml: passed, 974 documents.
• bin/format-docs and ci/test/lint-main/checks/check-whitespace.sh: clean, no reformatting needed.
• Rendered HTML spot-checked for the syntax-element table, the #supported-stages and #optimizer-feature-overrides anchors referenced from the YAML, the SQL commands index entry, and the RBAC appendix row.

---

Generated by Claude Code