PHOENIX-7919 Support EXPLAIN FORMAT JSON

[apurtell]

EXPLAIN (FORMAT JSON) <stmt> returns a single VARCHAR cell whose value is the Jackson serialization of the in-memory ExplainPlanAttributes tree. A new ExplainJsonRenderer owns a private static ObjectWriter configured for the EXPLAIN JSON contract and a DefaultPrettyPrinter whose DefaultIndenter is set on both the object and array indenters, so the output is human readable with two space indentation for both objects and arrays, render(...) wraps JsonProcessingException as SQLException. PhoenixStatement#ExecutableExplainStatement.compilePlan branches on getOptions().getFormat(). TEXT is unchanged. JSON skips renderTopOfPlanText and emits exactly one row carrying the rendered document, with the three plan-total estimate cells attached to the first row. regionLocations populates under (REGIONS, FORMAT JSON) and is null otherwise.

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

[Copilot]

Pull request overview

Adds end-to-end support for EXPLAIN (FORMAT JSON) <stmt> by rendering the ExplainPlanAttributes tree as a pretty-printed JSON document and returning it as a single-row result set.

Changes:

• Introduces ExplainJsonRenderer to serialize ExplainPlanAttributes to pretty-printed JSON (2-space indentation for objects and arrays).
• Updates PhoenixStatement#ExecutableExplainStatement.compilePlan to branch on ExplainOptions.Format.JSON and return exactly one row for JSON format.
• Adds a new end-to-end test validating JSON output and the (REGIONS, FORMAT JSON) combination.

Reviewed changes

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

File	Description
phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainJsonOutputTest.java	New E2E tests for EXPLAIN (FORMAT JSON) output shape and equivalence to in-process attributes (post-normalization).
phoenix-core-client/src/main/java/org/apache/phoenix/jdbc/PhoenixStatement.java	Routes EXPLAIN rendering based on format; JSON produces a single rendered-document row.
phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainJsonRenderer.java	New renderer encapsulating Jackson configuration for EXPLAIN JSON serialization and pretty-printing.

---

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

[apurtell]

Test Results

Unit tests

Test	Tests run	Failures	Errors	Skipped
ExplainPlanTest	105	0	0	0
ExplainJsonOutputTest	2	0	0	0
ExplainOptionsParserTest	16	0	0	0
StatementHintsCompilationTest	4	0	0	0
Total	127	0	0	0

Integration tests

Test	Tests run	Failures	Errors	Skipped
ExplainPlanWithStatsEnabledIT	30	0	0	0
ExplainPlanWithStatsDisabledIT	17	0	0	0
Total	47	0	0	0

Notes

• ExplainJsonOutputTest validates the end-to-end Statement.executeQuery path for both (FORMAT JSON) and (REGIONS, FORMAT JSON): exactly one result-set row, pretty-printed (two-space) indentation present in the raw cell, and deep equality of the normalized JSON against the in-process ExplainPlanAttributes for the same query.
• regionLocations is elided by ExplainJsonNormalizer, so the (REGIONS, FORMAT JSON) case confirms the combination produces one well-formed JSON row rather than asserting on cluster-specific region content.