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 87.93103% with 56 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.64%. Comparing base (07b9cb0) to head (6f5c025).

Files with missing lines	Patch %	Lines
...ine/execution/operator/ExplainAnalyzeOperator.java	45.45%	18 Missing ⚠️
.../apache/iotdb/db/queryengine/plan/Coordinator.java	0.00%	9 Missing ⚠️
...memory/TableModelStatementMemorySourceVisitor.java	63.63%	8 Missing ⚠️
...al/planner/distribute/TableDistributedPlanner.java	0.00%	5 Missing ⚠️
...rc/main/java/org/apache/iotdb/cli/AbstractCli.java	84.61%	4 Missing ⚠️
...e/plan/planner/DataNodeTableOperatorGenerator.java	0.00%	4 Missing ⚠️
...e/plan/planner/plan/node/PlanGraphJsonPrinter.java	98.33%	2 Missing ⚠️
...b/queryengine/plan/relational/sql/ast/Explain.java	88.23%	2 Missing ⚠️
...engine/plan/relational/sql/ast/ExplainAnalyze.java	90.00%	2 Missing ⚠️
...ne/plan/relational/analyzer/StatementAnalyzer.java	50.00%	1 Missing ⚠️
... and 1 more

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #17430      +/-   ##
============================================
- Coverage     40.68%   40.64%   -0.04%     
  Complexity     2620     2620              
============================================
  Files          5244     5247       +3     
  Lines        362374   362809     +435     
  Branches      46653    46716      +63     
============================================
+ Hits         147419   147477      +58     
- Misses       214955   215332     +377     

☔ View full report in Codecov by Harness.
📢 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

[Caideyipi]

I found a few functional issues in the new JSON explain path:

1. EXPLAIN (FORMAT JSON) with materialized CTEs can fail. CTE subqueries only inherit ExplainType, not the requested ExplainOutputFormat (CteMaterializer -> Coordinator.executeForTableModel). The inner CTE explain plan is still captured via PlanGraphPrinter text output in TableDistributedPlanner, but TableModelStatementMemorySourceVisitor.mergeExplainResultsJson() later parses that CTE result with JsonParser.parseString(...). A query like this should be covered:

EXPLAIN (FORMAT JSON)
WITH cte1 AS MATERIALIZED (SELECT * FROM t)
SELECT * FROM cte1;

2. EXPLAIN ... EXECUTE and EXPLAIN ... EXECUTE IMMEDIATE lose the requested format when the prepared/immediate SQL is unwrapped in Coordinator. The code recreates new Explain(resolvedSql) / new ExplainAnalyze(resolvedSql, verbose), which resets the format to GRAPHVIZ / TEXT, so EXPLAIN (FORMAT JSON) EXECUTE stmt and EXPLAIN ANALYZE (FORMAT JSON) EXECUTE stmt will not return JSON.

3. In JSON analyze mode, ExplainAnalyzeOperator sets fragmentInstanceStatisticsDrawer to null, but the scheduled intermediate logger still calls buildFragmentInstanceStatistics(), which dereferences that text drawer. Long-running EXPLAIN ANALYZE (FORMAT JSON) can therefore log repeated errors instead of intermediate analyze output. It should either skip the intermediate logger in JSON mode or render through the JSON drawer.

[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