PHOENIX-7896 EXPLAIN top-of-plan disclosures

[apurtell]

Top-of-plan disclosures rendered as clause style lines before the first operator.

A new ExplainTable.explainTopOfPlan(planSteps, ...) static helper is invoked from ExecutableExplainStatement.compilePlan after plan.getExplainPlan(). The block emits TENANT '<id>' when getTenantId() is non-null, VIEW <viewName> OVER <baseTableName> when tableRef.getTable().getType() == PTableType.VIEW, with the user visible view name resolved from plan.getStatement().getFrom() and the base from PTable.getParentName() or getBaseTableLogicalName(), a CDC scope line when the table type is CDC or StatementContext.getCDCIncludeScopes() is not null, and TXN OMID when isTransactional().

Parse tree and optimizer rewrites are surfaced as REWRITE <description> lines in the same block, fed by a new appliedRewrites list in StatementContext. BaseQueryPlan.getExplainPlan walks the query planning context, dedupes, preserving first occurrence order, and prepends one REWRITE line per breadcrumb. ExplainPlanAttributes gains a rewrites attribute. SubqueryRewriter emits one of IN SUBQUERY AS SEMI JOIN / EXISTS SUBQUERY AS SEMI JOIN / NOT EXISTS SUBQUERY AS ANTI JOIN / SCALAR SUBQUERY AS INNER JOIN / CORRELATED SUBQUERY AS LEFT JOIN per decorrelation. JoinCompiler.JoinTable.getStarJoinVector() emits STAR JOIN ON <n> RIGHT LEGS when there are at least two right legs. HavingCompiler emits HAVING PREDICATE AS WHERE. RVCOffsetCompiler emits RVC OFFSET 0x<hex>. OrderByCompiler.compile emits REVERSE SCAN SUBSTITUTION. QueryCompiler.compileJoinQuery and SortMergeJoinPlan emit RIGHT JOIN AS LEFT JOIN when the swap fires. IndexExpressionParseNodeRewriter emits INDEX EXPRESSION <expr> AS <indexcol>. QueryOptimizer.isPartialIndexUsable emits PARTIAL INDEX APPLICABLE or PARTIAL INDEX NOT APPLICABLE -- <reason>, deduped per table and per index. UnionCompiler.optimizeUnionOrderByIfPossible emits UNION ORDER BY MERGE. SubselectRewriter.flatten increments a counter slot on StatementContext per merge and emits DERIVED TABLE FLATTENED <n> once with the final count, suppressed when the count is zero.

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

[Copilot]

Pull request overview

This PR enhances Phoenix EXPLAIN output by introducing a “top-of-plan” disclosure block (tenant/view/CDC/txn + rewrite breadcrumbs) and plumbing structured attributes so both JSON explain attributes and JDBC EXPLAIN text can surface these diagnostics consistently.

Changes:

• Add top-of-plan disclosure attributes to ExplainPlanAttributes and populate them for root plans across plan types.
• Record optimizer/parser rewrite “breadcrumbs” in StatementContext and render them as REWRITE ... lines at the top of JDBC EXPLAIN output.
• Expand/adjust unit + integration tests to validate the new attributes and rendered disclosure text.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTestUtil.java	Adds fluent assertions for new disclosure + rewrite attributes.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTest.java	Updates expected explain attributes and adds tests for rewrite/disclosure rendering.
phoenix-core/src/test/java/org/apache/phoenix/compile/TenantSpecificViewIndexCompileTest.java	Minor formatting-only change.
phoenix-core/src/it/java/org/apache/phoenix/end2end/index/PartialIndexIT.java	Updates EXPLAIN assertions to use ExplainPlanTestUtil.getPlanSteps.
phoenix-core/src/it/java/org/apache/phoenix/end2end/index/ChildViewsUseParentViewIndexIT.java	Removes a stray blank line.
phoenix-core-client/src/main/java/org/apache/phoenix/util/ParseNodeUtil.java	Changes rewrite API to accept StatementContext so rewrite breadcrumbs can be recorded.
phoenix-core-client/src/main/java/org/apache/phoenix/parse/IndexExpressionParseNodeRewriter.java	Optionally records index-expression substitution breadcrumbs into the provided context.
phoenix-core-client/src/main/java/org/apache/phoenix/optimize/QueryOptimizer.java	Carries rewrite state across recompile and adds partial-index applicability breadcrumbs.
phoenix-core-client/src/main/java/org/apache/phoenix/jdbc/PhoenixStatement.java	Prepends disclosure text to JDBC EXPLAIN rows and threads rewrite context into compilation.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/ExplainTable.java	Populates top-of-plan attributes and renders disclosure text lines.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/UnionPlan.java	Populates top-of-plan attributes for root union plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/SortMergeJoinPlan.java	Populates top-of-plan attributes for root SMJ plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/HashJoinPlan.java	Populates top-of-plan attributes for root hash join plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientScanPlan.java	Populates top-of-plan attributes for root scan plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientAggregatePlan.java	Populates top-of-plan attributes for root aggregate plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/BaseQueryPlan.java	Populates top-of-plan attributes for root V2 explain-plan assembly.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/UpsertCompiler.java	Threads rewrite context into early rewrite passes and populates top-of-plan attributes for root DML plans.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/UnionCompiler.java	Records a breadcrumb when UNION ORDER BY merge optimization is preserved.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/SubselectRewriter.java	Adds optional context parameter to increment derived-table flatten counter.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/SubqueryRewriter.java	Adds optional context parameter and records subquery-to-join rewrite breadcrumbs.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/StatementContext.java	Adds breadcrumb storage, derived-table flatten counter, and partial-index dedupe tracking.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/RVCOffsetCompiler.java	Records an RVC offset breadcrumb.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/QueryCompiler.java	Adopts prebuilt rewrite state during compilation; passes context into join compilation; records RIGHT JOIN swap breadcrumb.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/OrderByCompiler.java	Records reverse-scan substitution breadcrumb.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/JoinCompiler.java	Threads context for breadcrumb recording; records star-join breadcrumb; passes context into derived-table flattening.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/HavingCompiler.java	Records HAVING→WHERE rewrite breadcrumb.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainPlanAttributes.java	Adds disclosure + rewrites fields to structured explain attributes and builder.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/DeleteCompiler.java	Threads rewrite context into early rewrite pass; populates top-of-plan attributes for root DML plans.

---

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

[apurtell]

Test Results

Suite	Scope	Tests	Failures	Errors	Result
ExplainPlanTest	Disclosure attributes + renderTopOfPlanText + compat baselines	83	0	0	PASS
Connectionless UT sweep	phoenix-core (all *Test)	2537	0	0	PASS
PartialIndexIT	Disclosure affected IT (migrated)	60	0	0	PASS
PartialIndexIT#testPartialIndexBreadcrumbsAreDistinctPerIndex	Per-index partial-index breadcrumb (×4 params)	4	0	0	PASS
HashJoinNoIndexIT	EXPLAIN relevant IT batch	33	0	0	PASS
SortMergeJoinNoIndexIT	EXPLAIN relevant IT batch	35	0	0	PASS
UnionAllIT	EXPLAIN relevant IT batch	19	0	0	PASS
IndexUsageIT	EXPLAIN relevant IT batch	39	0	0	PASS