PHOENIX-7899 Emit plan level estimates only once in EXPLAIN

[apurtell]

The three effectively plan level estimate columns become part of the top-of-plan disclosure.

Today PhoenixStatement.ExecutableExplainStatement.compilePlan emits the same EST_BYTES_READ / EST_ROWS_READ / EST_INFO_TS cells on every planSteps row, so a reader scanning the result set sees them repeated on every operator and reasonably assumes they are per-step.

The three PhoenixKeyValueUtil.newKeyValue(...) calls for EXPLAIN_PLAN_BYTES_ESTIMATE, EXPLAIN_PLAN_ROWS_ESTIMATE, and EXPLAIN_PLAN_ESTIMATE_INFO_TS are hoisted. Subsequent rows carry just the EXPLAIN_PLAN_COLUMN cell and the missing estimate cells surface as SQL NULL. The RowProjector is unchanged, and the whole block is skipped when getEstimated*ToScan() returns null. The three plan-total fields are added to ExplainPlanAttributes.

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

[Copilot]

Pull request overview

This PR adjusts Phoenix’s EXPLAIN output so the plan-total estimate columns (EST_BYTES_READ, EST_ROWS_READ, EST_INFO_TS) are emitted only once at the top of the result set (instead of being repeated on every plan-step row), and threads these plan-total values through ExplainPlanAttributes while preserving per-scan estimates separately.

Changes:

• Emit plan-total estimate cells only on the first EXPLAIN row; subsequent rows return SQL NULL for those estimate columns.
• Extend ExplainPlanAttributes to carry plan-total estimates (estimatedRows, estimatedSizeInBytes, estimateInfoTs) and add explicit per-scan fields (scanEstimatedRows, scanEstimatedSizeInBytes).
• Update/extend unit and integration tests to validate first-row-only estimate cells and the new attributes/JSON normalization behavior.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTestUtil.java	Adds assertions for new scan-level estimate fields and estimate info timestamp.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTest.java	Updates JSON normalizer tests and default attribute set to include new fields.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainJsonNormalizer.java	Nulls additional estimate-related fields during normalization.
phoenix-core/src/it/java/org/apache/phoenix/schema/stats/BaseStatsCollectorIT.java	Migrates plan assertions to scan-level estimate accessors.
phoenix-core/src/it/java/org/apache/phoenix/end2end/ExplainPlanWithStatsEnabledIT.java	Adds IT coverage ensuring estimates match stats and appear only on the first EXPLAIN row.
phoenix-core-client/src/main/java/org/apache/phoenix/jdbc/PhoenixStatement.java	Changes EXPLAIN materialization to emit estimate cells only for the first row.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/ExplainTable.java	Adds helper to populate plan-total estimate attributes for root plans.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/BaseResultIterators.java	Switches builder population to the new scan-level estimate fields.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/UnionPlan.java	Populates root plan estimate attributes for union plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/SortMergeJoinPlan.java	Populates root plan estimate attributes for sort-merge join plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/HashJoinPlan.java	Populates root plan estimate attributes for hash join plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientScanPlan.java	Populates root plan estimate attributes for client scan plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/ClientAggregatePlan.java	Populates root plan estimate attributes for client aggregate plans.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/BaseQueryPlan.java	Ensures root plans include plan-total estimate attributes in V2 explain attributes.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/UpsertCompiler.java	Ensures UPSERT explain attributes include root plan estimate attributes.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainPlanAttributes.java	Adds plan-total estimate fields + scan-level estimate fields and builder support.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/DeleteCompiler.java	Ensures DELETE explain attributes include root plan estimate attributes.

---

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

[apurtell]

Test results

Suite	Type	Result
ExplainPlanTest	Connectionless UT	83 run, 0 failures, 0 errors, 0 skipped
ExplainPlanWithStatsDisabledIT	Integration	17 run, 0 failures, 0 errors, 0 skipped
ExplainPlanWithStatsEnabledIT	Integration	30 run, 0 failures, 0 errors, 0 skipped
NonTxStatsCollectorIT (concrete BaseStatsCollectorIT subclass)	Integration	39 run, 0 failures, 0 errors, 6 skipped (environment-driven)
LocalIndexIT	Integration	60 run, 0 failures, 4 errors (pre-existing, see PHOENIX-7893), 0 skipped