Hi everyone,
大家好，
I'd like to share a new feature that has been submitted in PR #17430:
**EXPLAIN FORMAT JSON support for the Table Model**.
我想和大家分享一个已提交在 PR #17430 中的新特性：**表模型的 EXPLAIN FORMAT JSON 支持**。
### What's New / 新特性
We've added an optional `(FORMAT JSON)` clause to the `EXPLAIN` and
`EXPLAIN ANALYZE` statements, allowing users to get query plan output as
structured JSON instead of the traditional text/graphviz formats.
我们为 `EXPLAIN` 和 `EXPLAIN ANALYZE` 语句新增了可选的 `(FORMAT JSON)` 子句，允许用户以结构化 JSON
格式获取查询计划输出，替代传统的文本/图形格式。
**Syntax / 语法：**
```sql
EXPLAIN (FORMAT JSON) <query>
EXPLAIN ANALYZE [VERBOSE] (FORMAT JSON) <query>
```
This change is fully backward compatible — the default output formats
remain unchanged (GRAPHVIZ for EXPLAIN, TEXT for EXPLAIN ANALYZE). The
`(FORMAT ...)` clause is entirely optional.
此改动完全向后兼容——默认输出格式保持不变（EXPLAIN 默认 GRAPHVIZ，EXPLAIN ANALYZE 默认 TEXT）。`(FORMAT
...)` 子句完全可选。
### Why JSON? / 为什么选择 JSON？
The existing text-based output is great for human reading in a terminal,
but it's difficult for tools and applications to parse programmatically.
With structured JSON output, we unlock the ability to:
现有的文本输出适合在终端中人工阅读，但工具和应用程序难以进行编程解析。有了结构化 JSON 输出，我们可以：
- Build visual query plan explorers in web UIs / 在 Web UI 中构建可视化查询计划浏览器
- Programmatically analyze query performance bottlenecks / 以编程方式分析查询性能瓶颈
- Compare plans across different query versions / 跨不同查询版本对比执行计划
- Integrate with monitoring and observability pipelines / 与监控和可观测性管道集成
### CLI Output Optimization / CLI 输出优化
We also optimized the CLI output for `FORMAT JSON`. Previously, the JSON
content was wrapped in table borders (`|`), making it hard to directly copy
for visualization or analysis. Now the JSON content is printed without `|`
borders while the column header retains its table formatting:
我们还优化了 CLI 中 `FORMAT JSON` 的输出格式。之前 JSON
内容被包裹在表格边框（`|`）中，不方便直接复制用于可视化或分析。现在 JSON 内容不再有 `|` 边框，同时列标题保留表格样式：
```
+-----------------+
|distribution plan|
+-----------------+
{
"name": "OutputNode-4",
"id": "4",
"properties": { ... },
"children": [ ... ]
}
+-----------------+
Total line number = 1
```
Users can now directly copy the JSON output from CLI and paste it into
visualization tools without any manual cleanup.
用户现在可以直接从 CLI 复制 JSON 输出，粘贴到可视化工具中，无需任何手动处理。
### Query Plan Visualization Tool / 查询计划可视化工具
To make query plan analysis more intuitive, I've open-sourced **IoTDB
Profiler**, a web-based query plan visualization system:
为了让查询计划分析更直观，我开源了 **IoTDB Profiler**，一个基于 Web 的查询计划可视化系统：
**https://github.com/JackieTien97/iotdb-profiler**
This tool supports multiple ways to visualize query plans:
该工具支持多种方式可视化查询计划：
- **Live connection**: Connect to an IoTDB instance, write and execute SQL
queries, and get interactive visual representations of the physical
execution plan
- **实时连接**：连接到 IoTDB 实例，编写和执行 SQL 查询，获取物理执行计划的交互式可视化展示
- **JSON file import**: Upload a JSON file containing the EXPLAIN output
for offline visualization
- **JSON 文件导入**：上传包含 EXPLAIN 输出的 JSON 文件进行离线可视化
- **Direct paste**: Copy the JSON string output from CLI and paste it
directly into the tool for instant visualization
- **直接粘贴**：从 CLI 复制 JSON 字符串输出，直接粘贴到工具中即时可视化
With the visualization, you can:
通过可视化，你可以：
- Inspect detailed execution information including operator-level runtime
statistics (CPU time, output rows, memory usage, etc.)
- 查看详细的执行信息，包括算子级别的运行时统计（CPU 时间、输出行数、内存使用等）
- Quickly identify performance bottlenecks across fragment instances
- 快速定位跨 Fragment Instance 的性能瓶颈
- Navigate the plan tree interactively
- 交互式地浏览计划树
Under the hood, it leverages the new `EXPLAIN ANALYZE (FORMAT JSON)` to
retrieve structured plan data and render it as an interactive
visualization. This is similar to tools like pgAdmin's graphical EXPLAIN or
MySQL Workbench's Visual Explain, but tailored specifically for IoTDB's
distributed query engine.
底层利用新增的 `EXPLAIN ANALYZE (FORMAT JSON)` 获取结构化计划数据并渲染为交互式可视化。这类似于 pgAdmin
的图形化 EXPLAIN 或 MySQL Workbench 的 Visual Explain，但专为 IoTDB 的分布式查询引擎量身定制。
### JSON Output Examples / JSON 输出示例
**EXPLAIN (FORMAT JSON)** produces a plan tree where each node has `name`,
`id`, `properties`, and `children`:
**EXPLAIN (FORMAT JSON)** 生成一棵计划树，每个节点包含 `name`、`id`、`properties` 和
`children`：
```json
{
"name": "OutputNode-12",
"id": "12",
"properties": {
"OutputColumns": ["time", "deviceid", "voltage"],
"OutputSymbols": ["time", "deviceid", "voltage"]
},
"children": [
{
"name": "DeviceTableScanNode-7",
"id": "7",
"properties": {
"QualifiedTableName": "testdb.testtb",
"ScanOrder": "ASC",
"RegionId": "4"
}
}
]
}
```
**EXPLAIN ANALYZE (FORMAT JSON)** adds runtime statistics including plan
costs, fragment instance details, and per-operator metrics:
**EXPLAIN ANALYZE (FORMAT JSON)** 在此基础上增加运行时统计，包括计划开销、Fragment Instance
详情和算子级别指标：
```json
{
"planStatistics": {
"analyzeCostMs": 12.5,
"logicalPlanCostMs": 3.1,
"distributionPlanCostMs": 1.5,
"dispatchCostMs": 0.9
},
"fragmentInstancesCount": 3,
"fragmentInstances": [
{
"id": "...",
"dataRegion": "4",
"state": "FINISHED",
"totalWallTimeMs": 50.0,
"operators": {
"nodeType": "DeviceTableScanNode",
"cpuTimeMs": 2.0,
"outputRows": 5
}
}
]
}
```
### PR & Feedback / PR 与反馈
PR: https://github.com/apache/iotdb/pull/17430
Any feedback on the feature design, JSON schema, or the visualization tool
is very welcome. Looking forward to your thoughts!
欢迎对功能设计、JSON schema 或可视化工具提出任何反馈意见，期待大家的想法！
Best regards,
----------------
Yuan Tian
