Support EXPLAIN FORMAT JSON for Table Model

[JackieTien97]

Summary

• Add FORMAT option to EXPLAIN and EXPLAIN ANALYZE statements in the Table Model, allowing users to choose the output format (JSON, GRAPHVIZ, or TEXT)
• JSON format outputs a single-row, machine-parseable JSON document instead of multi-line text, making it easy for tools and scripts to programmatically analyze query plans
• CLI output optimization: when using FORMAT JSON, the CLI now prints JSON content without | table borders, so users can directly copy the JSON for visualization. The column header retains its table border formatting.
• Backward compatible: default output formats remain unchanged (GRAPHVIZ for EXPLAIN, TEXT for EXPLAIN ANALYZE)

Syntax

-- EXPLAIN with format option
EXPLAIN (FORMAT <format>) <query>

-- EXPLAIN ANALYZE with format option
EXPLAIN ANALYZE [VERBOSE] (FORMAT <format>) <query>

Supported formats:

Format	EXPLAIN	EXPLAIN ANALYZE	Description
GRAPHVIZ	default	N/A	Box-drawing plan visualization
TEXT	N/A	default	Text-based output
JSON	supported	supported	Structured JSON output

CLI Output Format (FORMAT JSON)

Before (hard to copy JSON due to | borders):

+------------------------------------------+
|                          distribution plan|
+------------------------------------------+
|{                                         |
|  "name": "OutputNode-4",                 |
|  ...                                     |
|}                                         |
+------------------------------------------+

After (JSON content can be directly copied):

+-----------------+
|distribution plan|
+-----------------+
{
  "name": "OutputNode-4",
  "id": "4",
  "properties": { ... },
  "children": [ ... ]
}
+-----------------+
Total line number = 1

Examples

1. EXPLAIN (FORMAT JSON)

EXPLAIN (FORMAT JSON) SELECT * FROM testtb

2. EXPLAIN ANALYZE (FORMAT JSON)

EXPLAIN ANALYZE (FORMAT JSON) SELECT * FROM testtb

3. Invalid format produces clear error

EXPLAIN (FORMAT XML) SELECT * FROM testtb
-- Error: Unsupported EXPLAIN output format: XML

Key Design Decisions

• Single-row output: JSON format returns all data in a single row, simplifying client-side parsing.
• CLI border-free JSON: JSON content lines in CLI output have no | borders, while the column header retains its table formatting.
• Backward compatible: No syntax change for existing queries. The (FORMAT ...) clause is entirely optional.

Test Plan

• Unit tests for PlanGraphJsonPrinter and ExplainFormatTest
• Integration tests: JSON/GRAPHVIZ/TEXT formats, CTE, scalar subquery, multi-partition, error handling
• CLI output format IT (ExplainJsonCliOutputIT): verifies JSON content has no | borders while header retains table formatting

[codecov]

Codecov Report

❌ Patch coverage is 19.58525% with 349 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.74%. Comparing base (55082b2) to head (7c66201).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
...atistics/FragmentInstanceStatisticsJsonDrawer.java	0.00%	169 Missing ⚠️
...e/plan/planner/plan/node/PlanGraphJsonPrinter.java	36.66%	76 Missing ⚠️
...ine/execution/operator/ExplainAnalyzeOperator.java	0.00%	27 Missing ⚠️
...rc/main/java/org/apache/iotdb/cli/AbstractCli.java	0.00%	26 Missing ⚠️
...memory/TableModelStatementMemorySourceVisitor.java	0.00%	22 Missing ⚠️
...engine/plan/relational/sql/ast/ExplainAnalyze.java	33.33%	10 Missing ⚠️
...b/queryengine/plan/relational/sql/ast/Explain.java	30.76%	9 Missing ⚠️
...eryengine/plan/planner/TableOperatorGenerator.java	0.00%	4 Missing ⚠️
...an/relational/planner/node/ExplainAnalyzeNode.java	60.00%	2 Missing ⚠️
...yengine/plan/relational/sql/parser/AstBuilder.java	90.00%	2 Missing ⚠️
... and 2 more

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #17430      +/-   ##
============================================
- Coverage     39.75%   39.74%   -0.02%     
  Complexity      312      312              
============================================
  Files          5134     5138       +4     
  Lines        346907   347410     +503     
  Branches      44194    44273      +79     
============================================
+ Hits         137907   138070     +163     
- Misses       209000   209340     +340     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE