PHOENIX-7890 Improve EXPLAIN for joins and unions

[apurtell]

The chosen JoinCompiler.Strategy and the SKIP MERGE and DELAYED EVALUATION decorators move out of inline parentheticals into a single trailing SQL comment per join operator line. HashJoinPlan and SortMergeJoinPlan gain a JoinCompiler.Strategy strategy field and getter/setter. QueryCompiler.compileJoinQuery threads the chosen strategy through HashJoinPlan.create(...).

UnionPlan.getExplainPlan() is rewritten to compose recursively from each branch's getExplainPlan() (like SortMergeJoinPlan.getExplainPlan()). The N branches are represented via the existing subPlans list. A new UnionResultIterators.explainBranches(plans, planSteps, builder) helper is the single source of truth for branch composition. The two ResultIterators.explain(...) SPI overrides on UnionResultIterators become thin delegates to it. UnionPlan.getExplainPlan() no longer triggers sub-plan execution, so connectionless tests can check them.

Minor housekeeping: Replace string 'Truncate Table' with 'TRUNCATE TABLE' in EXPLAIN DDL.

Add TPC-DS derived ITs asserting the full ordered results of various UNION and JOIN plans and expected assertPlan assertions.

[Copilot]

Pull request overview

This PR refactors EXPLAIN output for JOIN and UNION plans to make join strategy/decorators clearer and to make UNION explain composition recursive (without executing sub-plans), and updates/extends tests accordingly.

Changes:

• Move join strategy + decorators (e.g., SKIP MERGE, DELAYED EVALUATION) into a single trailing SQL comment per join-operator line, and thread join strategy into HashJoinPlan / SortMergeJoinPlan.
• Rewrite UnionPlan.getExplainPlan() to recursively compose branch explain plans via a shared UnionResultIterators.explainBranches(...) helper (avoiding sub-plan execution during explain).
• Add TPC-DS-derived deterministic fixtures + integration tests asserting ordered results and expected plan fragments for UNION/JOIN queries; update existing plan-assert tests for the new explain format.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTest.java	Updates expected EXPLAIN strings and adds UNION-of-joins coverage aligned with new recursive composition.
phoenix-core/src/test/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeExpectedRegenerator.java	Adds a developer utility to regenerate embedded expected result arrays for the new TPC-DS-like ITs.
phoenix-core/src/test/java/org/apache/phoenix/compile/QueryCompilerTest.java	Updates join explain assertions to include the new trailing strategy comment.
phoenix-core/src/it/java/org/apache/phoenix/end2end/UnionAllIT.java	Updates UNION EXPLAIN attribute assertions to validate subPlans branch structure.
phoenix-core/src/it/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeSingleChannelIT.java	Adds single-channel TPC-DS-derived ITs asserting full ordered results + plan markers.
phoenix-core/src/it/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeFixture.java	Adds deterministic fixture schema/data generation for the new TPC-DS-like IT suite.
phoenix-core/src/it/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeCrossChannelIT.java	Adds cross-channel UNION/SORT-MERGE focused ITs with result + plan assertions.
phoenix-core/src/it/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeBaseIT.java	Adds shared parameterization/plumbing for the TPC-DS-like ITs (base vs indexed schema).
phoenix-core/src/it/java/org/apache/phoenix/end2end/tpcds/TPCDSLikeAssertions.java	Adds helpers to assert full ordered results and plan fragments; supports regeneration mode.
phoenix-core/src/it/java/org/apache/phoenix/end2end/QueryWithTableSampleIT.java	Updates UNION and JOIN explain assertions to the new subPlans/comment format.
phoenix-core/src/it/java/org/apache/phoenix/end2end/join/HashJoinNoIndexIT.java	Updates join plan assertions to include trailing strategy comment.
phoenix-core/src/it/java/org/apache/phoenix/end2end/join/HashJoinMoreIT.java	Updates join plan assertions (incl. SKIP MERGE) to the new trailing comment format.
phoenix-core/src/it/java/org/apache/phoenix/end2end/join/HashJoinLocalIndexIT.java	Updates join plan assertions to include trailing strategy comment.
phoenix-core/src/it/java/org/apache/phoenix/end2end/join/HashJoinGlobalIndexIT.java	Updates join plan assertions to include trailing strategy comment.
phoenix-core/src/it/java/org/apache/phoenix/end2end/index/IndexUsageIT.java	Updates join explain assertion to the new trailing comment format.
phoenix-core/src/it/java/org/apache/phoenix/end2end/index/GlobalIndexOptimizationIT.java	Updates SKIP-SCAN-JOIN explain assertion to include trailing strategy comment.
phoenix-core/src/it/java/org/apache/phoenix/end2end/CostBasedDecisionIT.java	Updates UNION/JOIN explain assertions to use subPlans instead of lhs/rhs chaining.
phoenix-core-client/src/main/java/org/apache/phoenix/jdbc/PhoenixStatement.java	Normalizes TRUNCATE explain text to TRUNCATE TABLE.
phoenix-core-client/src/main/java/org/apache/phoenix/iterate/UnionResultIterators.java	Introduces explainBranches(...) helper and delegates explain methods to it.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/UnionPlan.java	Rewrites union explain composition to be branch-recursive and non-executing; appends tail steps explicitly.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/SortMergeJoinPlan.java	Adds strategy field and updates sort-merge join header to include /* SORT_MERGE */.
phoenix-core-client/src/main/java/org/apache/phoenix/execute/HashJoinPlan.java	Adds strategy field, updates join headers to trailing comment format, and threads strategy through create().
phoenix-core-client/src/main/java/org/apache/phoenix/compile/QueryCompiler.java	Threads join strategy into HashJoinPlan.create(...) calls and updates subquery wrapping call sites.

---

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

[apurtell]

Test Results

Unit tests (connectionless)

Test	Run	Failures	Errors	Skipped	Result
org.apache.phoenix.query.explain.ExplainPlanTest	63	0	0	0	PASS
org.apache.phoenix.compile.QueryCompilerTest	215	0	0	2	PASS

ExplainPlanTest includes the new testUnionAllOfHashJoins case covering the deeply nested
union-of-hash-joins explain output (union root → branch scan → hash-join sub-plan), plus the
updated testHashJoinInner, testHashJoinSemiInSubquery, testSortMergeJoin, and testUnionAll.

Integration tests

Test	Run	Failures	Errors	Skipped	Result
org.apache.phoenix.end2end.join.HashJoinNoIndexIT	33	0	0	0	PASS
org.apache.phoenix.end2end.join.HashJoinGlobalIndexIT	33	0	0	0	PASS
org.apache.phoenix.end2end.join.HashJoinLocalIndexIT	34	0	0	0	PASS
org.apache.phoenix.end2end.join.HashJoinMoreIT	10	0	0	0	PASS
org.apache.phoenix.end2end.index.IndexUsageIT	39	0	0	0	PASS
org.apache.phoenix.end2end.index.GlobalIndexOptimizationIT	7	0	0	0	PASS
org.apache.phoenix.end2end.QueryWithTableSampleIT	12	0	0	0	PASS
org.apache.phoenix.end2end.UnionAllIT	19	0	0	0	PASS
org.apache.phoenix.end2end.CostBasedDecisionIT	20	0	0	0	PASS
org.apache.phoenix.end2end.join.SortMergeJoinNoIndexIT	35	0	0	0	PASS
org.apache.phoenix.end2end.join.SortMergeJoinGlobalIndexIT	35	0	0	0	PASS
org.apache.phoenix.end2end.join.SortMergeJoinLocalIndexIT	35	0	0	0	PASS
org.apache.phoenix.end2end.SortMergeJoinMoreIT	10	0	0	0	PASS
org.apache.phoenix.end2end.join.SubqueryUsingSortMergeJoinIT	21	0	0	0	PASS
org.apache.phoenix.end2end.tpcds.TPCDSLikeSingleChannelIT	28	0	0	0	PASS
org.apache.phoenix.end2end.tpcds.TPCDSLikeCrossChannelIT	12	0	0	0	PASS

The two TPCDSLike*IT classes are new TPC-DS derived ITs that exercise joins and unions. Each query runs over a deterministic fixture and is parameterized across NO_INDEX and GLOBAL_INDEX schemas. Every case asserts the full ordered result plus the EXPLAIN operator markers (HASH BUILD, UNION ALL OVER N QUERIES, SORT-MERGE-JOIN (INNER/FULL)) in both parameters, and additionally verifies covering-index usage (SS_I, INV_I, CS_I) in the GLOBAL_INDEX parameter where the optimizer rewrites the fact-table scan onto a global index.

Totals

• Unit tests: 278 run, 0 failures, 0 errors (2 skipped).
• Integration tests: 383 run, 0 failures, 0 errors, 0 skipped.
• Overall: 661 run, 0 failures, 0 errors.