PHOENIX-7917 Expand the EXPLAIN WITH options list grammar

[apurtell]

Replace the EXPLAIN [WITH REGIONS] grammar with a comma-separated option list EXPLAIN [(<opt> [, <opt>]*)] <stmt> accepting REGIONS, VERBOSE, FORMAT TEXT, and FORMAT JSON, preserving EXPLAIN WITH REGIONS as a backward compatible alias.

Update PhoenixSQL.gexplain_node rule to accept either LPAREN id (COMMA id)* RPAREN or WITH REGIONS between EXPLAIN and the inner oneStatement, with FORMAT TEXT|JSON parsed as FORMAT followed by an identifier. VERBOSE, FORMAT, TEXT, and JSON are matched as identifier inside explain_node and validated against a closed set in the action block.

ExplainStatement replaces ExplainType with ExplainOptions { boolean regions; boolean verbose; Format format; }. ParseNodeFactory gains a factory.explain(stmt, ExplainOptions) overload. PhoenixStatement#ExecutableExplainStatement takes ExplainOptions and propagates regions through to BaseResultIterators.explainUtil.

Region locator lookup still happens unconditionally.

Co-authored-by: Claude Opus 4.8[1m] noreply@anthropic.com

[Copilot]

Pull request overview

This PR expands Phoenix SQL’s EXPLAIN grammar from the legacy EXPLAIN [WITH REGIONS] <stmt> form to an option-list form EXPLAIN [(<opt> [, <opt>]*)] <stmt>, introducing a new ExplainOptions carrier object that is propagated through parsing/compilation and into StatementContext so explain rendering can be option-aware (while keeping EXPLAIN WITH REGIONS as a backward-compatible alias).

Changes:

• Extend PhoenixSQL.g to parse EXPLAIN (...) option lists (plus EXPLAIN WITH REGIONS alias) and validate options into an ExplainOptions instance.
• Replace the old ExplainType enum with ExplainOptions, propagate it through ParseNodeFactory, ExplainStatement, PhoenixStatement, and StatementContext.
• Gate region-locations emission in ExplainTable on the REGIONS option and update tests/ITs to request region locations explicitly where needed.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTestUtil.java	Adds helpers to run optimization with explicit ExplainOptions and a convenience assertion entrypoint for REGIONS.
phoenix-core/src/test/java/org/apache/phoenix/parse/ExplainOptionsParserTest.java	Adds parser-level tests for the new EXPLAIN (...) option-list grammar and the legacy WITH REGIONS alias.
phoenix-core/src/it/java/org/apache/phoenix/end2end/QueryLoggerIT.java	Updates EXPLAIN usage to align explain output comparisons with logged plans.
phoenix-core/src/it/java/org/apache/phoenix/end2end/index/BaseIndexIT.java	Switches region-location assertions to use the new “with regions” explain helper.
phoenix-core/src/it/java/org/apache/phoenix/end2end/FlappingLocalIndexIT.java	Ensures tests requesting region-location attributes enable REGIONS explicitly; adds test categorization annotation.
phoenix-core/src/it/java/org/apache/phoenix/end2end/BaseAggregateIT.java	Switches region-location assertions to use the new “with regions” explain helper.
phoenix-core-client/src/main/java/org/apache/phoenix/parse/ParseNodeFactory.java	Updates explain(...) factory method to accept ExplainOptions.
phoenix-core-client/src/main/java/org/apache/phoenix/parse/ExplainType.java	Removes legacy ExplainType enum.
phoenix-core-client/src/main/java/org/apache/phoenix/parse/ExplainStatement.java	Stores parsed ExplainOptions (defaulting to ExplainOptions.DEFAULT).
phoenix-core-client/src/main/java/org/apache/phoenix/parse/ExplainOptions.java	Introduces ExplainOptions (regions/verbose/format) and a builder used by the parser.
phoenix-core-client/src/main/java/org/apache/phoenix/jdbc/PhoenixStatement.java	Propagates ExplainOptions into compiled plan context so explain rendering can respect options.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/ExplainTable.java	Emits region-location text/attributes only when REGIONS is requested via ExplainOptions.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/StatementContext.java	Adds ExplainOptions storage (defaulting to DEFAULT) with getters/setters.
phoenix-core-client/src/main/antlr3/PhoenixSQL.g	Extends grammar to parse option lists and validates allowed options into an ExplainOptions.Builder.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[apurtell]

Test Results

Unit tests (*Test)

Test class	Tests	Failures	Errors	Skipped	Result
ExplainOptionsParserTest (new)	16	0	0	0	PASS
QueryParserTest	93	0	0	0	PASS
ExplainPlanTest	94	0	0	0	PASS
Total	203	0	0	0	PASS

ExplainOptionsParserTest covers the new grammar: REGIONS, VERBOSE, FORMAT TEXT, FORMAT JSON, case-insensitivity, option ordering, the legacy WITH REGIONS alias, and the error paths (unknown option, unknown format kind, duplicate option, FORMAT without a value, REGIONS with a value, and mixing the legacy alias with the option list).

Integration tests (*IT)

Test class	Category	Tests	Failures	Errors	Skipped	Result
AggregateIT	ParallelStatsDisabled	25	0	0	0	PASS
GlobalImmutableNonTxIndexIT	ParallelStatsDisabled	46	0	0	0	PASS
LocalMutableNonTxIndexIT	ParallelStatsDisabled	46	0	0	4	PASS
QueryLoggerIT	NeedsOwnMiniCluster	7	0	0	0	PASS
FlappingLocalIndexIT	NeedsOwnMiniCluster	12	0	0	0	PASS

• AggregateIT drives the three migrated sites in BaseAggregateIT (testGroupByOrderPreserving, testSumGroupByOrderPreserving, testAvgGroupByOrderPreserving).
• GlobalImmutableNonTxIndexIT / LocalMutableNonTxIndexIT drive the three migrated sites in BaseIndexIT (testIndexWithNullableFixedWithCols, testIndexWithNullableDateCol, testSelectAllAndAliasWithIndex). The 4 skipped tests in LocalMutableNonTxIndexIT are pre-existing failing tests unrelated to this change tracked by PHOENIX-7893.
• FlappingLocalIndexIT was previously uncategorized and therefore skipped by all group-filtered failsafe executions. It is now annotated @Category(NeedsOwnMiniClusterTest.class).