PHOENIX-7918 Implement EXPLAIN VERBOSE disclosures

[apurtell]

EXPLAIN VERBOSE implements VERBOSE-gated disclosures for projections, predicate origin attribution on SERVER FILTER BY / CLIENT FILTER BY, and ignored hint comments.

The verbose flag is threaded from ExplainOptions onto StatementContext. ExplainPlanAttributes.serverProject : List<String> is populated from plan.getProjector().getColumnProjectors(). ExplainPlanAttributes also adds serverFilters : List<ExplainFilter>.

The per-scan /* !INDEX <name> -- <reason> */ text is now gated on verbose.

The chosen-plan INDEX <name> [<kind>] /* <rule> */ line stays in plain EXPLAIN and indexRejected populates in both modes.

StatementContext adds predicateOrigins, populated by WhereCompiler, HavingCompiler, JoinCompiler, IndexStatementRewriter, and RVCOffsetCompiler.

Under VERBOSE a fully-tagged AndExpression fans out to one SERVER FILTER BY (<child>) -- <child-origin> per child, otherwise a single line carries the comma-separated union.

JsonExistsFunction / BsonConditionExpressionFunction append (JSON EXISTS) / (BSON CONDITION).

For ignored hints StatementContext adds Map<Hint, IgnoredHintReason> populated at Hint.NO_INDEX, Hint.USE_SORT_MERGE_JOIN, and Hint.SMALL. Under VERBOSE ExplainTable emits one /*- HINT(args) -- <reason> */ per ignored hint, including partially honored hints.

The symmetric clientFilters : List<ExplainFilter> collects every CLIENT FILTER BY site in ClientScanPlan, ClientAggregatePlan, FilterResultIterator, FilterAggregatingResultIterator, and TupleProjectionPlan.

ExplainPlanTestUtil adds fluent getters, setters, and testers. ExplainJsonNormalizer recurses serverFilters / clientFilters.

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

[Copilot]

Pull request overview

This PR adds EXPLAIN VERBOSE support across Phoenix’s planning/explain pipeline, introducing VERBOSE-gated disclosures (server projection columns, per-predicate filter attribution, and ignored hints) while keeping plain EXPLAIN output stable.

Changes:

• Thread a verbose flag from ExplainOptions into StatementContext, and collect diagnostic metadata (predicate origins + ignored hints) during compilation/optimization.
• Extend ExplainTable and several client-side plans/iterators to emit VERBOSE-only disclosures (PROJECT, per-predicate SERVER/CLIENT FILTER BY … -- <origin>, and ignored-hint comments).
• Expand ExplainPlanAttributes (and test utilities/normalizers) to carry structured serverProject, serverFilters, clientFilters, and ignoredHints.

Reviewed changes

Copilot reviewed 23 out of 23 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 VERBOSE-focused assertion helpers and a plan-step getter that applies ExplainOptions.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTest.java	Adds/updates tests covering VERBOSE-only disclosures and gating behavior.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainJsonNormalizer.java	Normalizes temp aliases inside serverFilters/clientFilters[*].expr for stable JSON comparisons.
phoenix-core-client/src/main/java/org/apache/phoenix/schema/PTableImpl.java	Tags partial-index WHERE predicates with an origin for VERBOSE attribution.
phoenix-core-client/src/main/java/org/apache/phoenix/parse/ExplainOptions.java	Adds ExplainOptions.VERBOSE.
phoenix-core-client/src/main/java/org/apache/phoenix/optimize/QueryOptimizer.java	Records ignored hints (e.g., NO_INDEX, INDEX(...)) and carries them forward between candidate plans.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/FilterResultIterator.java	Adds VERBOSE client-filter breakdown emission and structured clientFilters population.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/FilterAggregatingResultIterator.java	Same as above for HAVING/post-aggregate client filters.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/ExplainTable.java	Implements VERBOSE-only PROJECT, !INDEX gating, ignored-hint disclosures, and per-predicate server-filter breakdown rendering.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/BaseResultIterators.java	Exposes the plan’s RowProjector to ExplainTable for VERBOSE PROJECT emission.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/TupleProjectionPlan.java	Emits VERBOSE client-filter breakdown for post-filters and passes context to runtime filter iterator.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/HashJoinPlan.java	Passes StatementContext into FilterResultIterator so VERBOSE client filter breakdown is available.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientScanPlan.java	Emits VERBOSE client-filter breakdown + structured clientFilters; passes context into runtime filter iterator.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientAggregatePlan.java	Emits VERBOSE client-filter breakdown for WHERE/HAVING and wires context through filter iterators.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/AggregatePlan.java	Wires context through HAVING filter iterator for VERBOSE attribution.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/WhereCompiler.java	Tags residual WHERE predicate conjuncts with "WHERE" origins for VERBOSE attribution.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/SubqueryRewriter.java	Plumbs StatementContext into decorrelation so JOIN-origin attribution can mention decorrelated subquery aliases.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/StatementContext.java	Adds VERBOSE plumbing: isVerbose(), predicate-origin tagging/unioning, lifted-HAVING tracking, decorrelated alias mapping, and ignored-hint recording.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/RVCOffsetCompiler.java	Tags the RVC offset predicate with origin "RVC OFFSET" for VERBOSE attribution.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/QueryCompiler.java	Records ignored USE_SORT_MERGE_JOIN when no join exists.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/JoinCompiler.java	Tags compiled ON predicates with "JOIN ON" or a decorrelation-based origin string.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/HavingCompiler.java	Tags HAVING residual predicates with "HAVING" origins and records which nodes were lifted into WHERE.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainPlanAttributes.java	Adds structured VERBOSE attributes (serverProject, serverFilters, clientFilters, ignoredHints) plus a filter element type.

---

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

[apurtell]

Amended with review feedback.

[apurtell]

Test Results

Unit Tests (*Test)

Module	Tests	Failures	Errors	Skipped	Result
phoenix-core-client	0	0	0	0	no unit tests in module
phoenix-core	2608	0	0	9	PASS
phoenix-pherf	60	1	1	0	pre-existing failures (see below)
phoenix-tracing-webapp	0	0	0	0	no unit tests in module

Integration Tests (*IT) — impacted set

IT class	Touched class exercised	Tests	Fail	Err	Result
ExplainPlanWithStatsEnabledIT	ExplainTable / ExplainPlanAttributes (plain EXPLAIN)	30	0	0	PASS
ExplainPlanWithStatsDisabledIT	ExplainTable / ExplainPlanAttributes (plain EXPLAIN)	17	0	0	PASS
AggregateIT	AggregatePlan + FilterAggregatingResultIterator (HAVING)	25	0	0	PASS
GroupByIT	AggregatePlan / group-by + HAVING	70	0	0	PASS
ClientHashAggregateIT	ClientAggregatePlan (client WHERE + HAVING)	2	0	0	PASS
DerivedTableIT	ClientScanPlan / TupleProjectionPlan post-filter	18	0	0	PASS
SubqueryIT	SubqueryRewriter decorrelation + HashJoinPlan post-filter	36	0	0	PASS
RowValueConstructorOffsetIT	RVCOffsetCompiler predicate tagging	33	0	0	PASS
Total		231	0	0	PASS