PHOENIX-7916 Disclose atomic upsert flavors and RETURNING in EXPLAIN

[apurtell]

Disclose atomic upsert flavors and RETURNING in EXPLAIN.

Replace the single opaque PUT SINGLE ROW operator line with a switch on UpsertStatement.OnDuplicateKeyType, surface the server-side update assignments under ON DUPLICATE KEY UPDATE, and disclose RETURNING * on every mutation plan whose parsed statement has isReturningRow() == true — that is, every concrete UpsertCompiler plan (UpsertValuesMutationPlan, ServerUpsertSelectMutationPlan, ClientUpsertSelectMutationPlan) and every DeleteCompiler plan (SingleRowDeleteMutationPlan, ServerSelectDeleteMutationPlan, ClientSelectDeleteMutationPlan).

Add three new structured fields to ExplainPlanAttributes and matching fluent assertions on ExplainPlanTestUtil.

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

[Copilot]

Pull request overview

This PR enhances Phoenix EXPLAIN output for mutation plans by exposing previously opaque UPSERT/DELETE mutation details in both the textual plan steps and the structured ExplainPlanAttributes representation, including atomic UPSERT “ON DUPLICATE KEY” flavors, server-side update assignments, and RETURNING *.

Changes:

• Extend ExplainPlanAttributes with mutation-operator fields (onDuplicateKeyAction, serverUpdateSet, returningRow) and wire them into explain-plan builders.
• Update UPSERT/DELETE mutation plan explain output to disclose ON DUPLICATE KEY flavor, SERVER UPDATE SET assignments, and RETURNING * where applicable.
• Add test utilities and new tests validating the enriched textual and structured EXPLAIN output.

Reviewed changes

Copilot reviewed 5 out of 5 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 fluent assertions for new mutation-specific structured explain fields.
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainPlanTest.java	Adds new mutation EXPLAIN tests and updates default expected attribute JSON to include new fields.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/UpsertCompiler.java	Propagates RETURNING * and ON DUPLICATE KEY details into mutation plan explain steps/attributes.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainPlanAttributes.java	Introduces new structured fields and builder setters for mutation-operator disclosures.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/DeleteCompiler.java	Propagates RETURNING * into delete mutation plan explain steps/attributes across delete plan variants.

---

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

[apurtell]

Test Results

Unit tests (*Test) — all PASS

Test class	Tests	Failures	Errors	Skipped
ExplainPlanTest	94	0	0	0
QueryCompilerTest	215	0	0	2
QueryOptimizerTest	52	0	0	1
QueryPlanTest	4	0	0	0
StatementHintsCompilationTest	4	0	0	0
JoinQueryCompilerTest	2	0	0	0
TenantSpecificViewIndexCompileTest	6	0	0	0
Total	377	0	0	3

Integration tests (*IT) — all PASS

Test class	Tests	Failures	Errors	Skipped	Time (s)
UpsertSelectIT	54	0	0	0	207.4
DeleteIT	74	0	0	0	247.6
OnDuplicateKeyIT	154	0	0	0	465.4
GlobalIndexOptimizationIT	7	0	0	0	36.6
CostBasedDecisionIT	20	0	0	0	176.6
OnDuplicateKey2IT	252	0	0	32	422.5
Total	561	0	0	32	—

OnDuplicateKeyIT and OnDuplicateKey2IT directly exercise the rewritten atomic-upsert getExplainPlan() switch and the modified UpsertValuesMutationPlan constructor across the NONE/UPDATE/UPDATE_ONLY/IGNORE flavors. UpsertSelectIT exercises the modified ServerUpsertSelectMutationPlan / ClientUpsertSelectMutationPlan constructors. DeleteIT exercises all three modified DeleteCompiler plan constructors.