doc: explain - #34774
doc: explain#34774
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces new, detailed documentation for the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Pull request overview
Adds new SQL manual documentation pages for EXPLAIN in both English and Chinese, describing how to interpret execution plans and runtime metrics for query tuning and troubleshooting.
Changes:
- Introduces
EXPLAIN/EXPLAIN ANALYZEsyntax and parameter explanations (ANALYZE,VERBOSE). - Documents common plan operators and key metrics (including
Exec costand scanI/O costfields). - Provides multiple end-to-end examples and diagnostic suggestions for typical performance scenarios.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/zh/14-reference/03-taos-sql/28-explain.md | New Chinese documentation for EXPLAIN, including metrics reference, examples, and diagnostic guidance. |
| docs/en/14-reference/03-taos-sql/28-explain.md | New English documentation for EXPLAIN, mirroring the structure and guidance in the Chinese version. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
![gemini-code-assist[bot]](/s/com/githubusercontent/avatars/G.https/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation for the EXPLAIN command in both English and Chinese. The documentation is well-structured and provides a great level of detail. My review includes a few suggestions to fix minor typos and inconsistencies in the examples and text to further improve clarity and correctness.
| ```sql | ||
| taos> EXPLAIN ANALYZE VERBOSE true SELECT _wstart, _wend, count(*), avg(current) FROM meters INTERVAL(10s) \G; | ||
| *************************** 1.row *************************** | ||
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) |
There was a problem hiding this comment.
There appears to be a typo in the example output. There are two spaces after Column, which should probably be one.
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) | |
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) |
| *************************** 9.row *************************** | ||
| QUERY_PLAN: Output: Ignore Group Id: false | ||
| *************************** 10.row *************************** | ||
| QUERY_PLAN: Merge Key: _group_id asc, asc |
There was a problem hiding this comment.
The Merge Key in this example output is confusing: _group_id asc, asc. It seems a column name is missing after the comma. For clarity, please specify the second sort key. Given this is a time-window query, ts would be a likely candidate for the second key.
| QUERY_PLAN: Merge Key: _group_id asc, asc | |
| QUERY_PLAN: Merge Key: _group_id asc, ts asc |
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
There was a problem hiding this comment.
The unit for Execution Time appears to be a typo. It's given as m, which could mean minutes. However, other examples in this document use ms (milliseconds), and the corresponding Planning Time is in ms. It's likely this should also be ms, as 8 minutes seems inconsistent with the context.
| QUERY_PLAN: Execution Time: 8.138 m | |
| QUERY_PLAN: Execution Time: 8.138 ms |
| | `mode=ts_order` | 按时间序组织扫描 | 常见于普通时间序扫描 | | ||
| | `offset=` | 当前算子承接到的 `OFFSET` | 用于判断偏移是否参与了当前层裁剪 | | ||
| | `order=[asc\|x desc\|y]` | 扫描时顺序读取与逆序读取的计数 | 用于判断扫描是否主要按升序还是降序进行 | | ||
| | `origin_vgroup_num=` | 原始 vgroup 数量 | 用于观察虚拟稳定表查询的并行规模 | |
There was a problem hiding this comment.
The term "虚拟稳定表" is used here. However, in other parts of this document (e.g., lines 118, 134), "超级表" is used for "supertable". The English version of the documentation also uses "supertable". For consistency, please consider changing "虚拟稳定表" to "虚拟超级表".
| | `origin_vgroup_num=` | 原始 vgroup 数量 | 用于观察虚拟稳定表查询的并行规模 | | |
| | `origin_vgroup_num=` | 原始 vgroup 数量 | 用于观察虚拟超级表查询的并行规模 | |
| ```sql | ||
| taos> EXPLAIN ANALYZE VERBOSE true SELECT _wstart, _wend, count(*), avg(current) FROM meters INTERVAL(10s) \G; | ||
| *************************** 1.row *************************** | ||
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) |
There was a problem hiding this comment.
There appears to be a typo in the example output. There are two spaces after Column, which should probably be one.
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) | |
| QUERY_PLAN: -> Merge Aligned Interval on Column (cost=0.626..0.626 rows=10 functions=4 width=32 input_order=asc output_order=asc) |
| *************************** 9.row *************************** | ||
| QUERY_PLAN: Output: Ignore Group Id: false | ||
| *************************** 10.row *************************** | ||
| QUERY_PLAN: Merge Key: _group_id asc, asc |
There was a problem hiding this comment.
The Merge Key in this example output is confusing: _group_id asc, asc. It seems a column name is missing after the comma. For clarity, please specify the second sort key. Given this is a time-window query, ts would be a likely candidate for the second key.
| QUERY_PLAN: Merge Key: _group_id asc, asc | |
| QUERY_PLAN: Merge Key: _group_id asc, ts asc |
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
There was a problem hiding this comment.
The unit for Execution Time appears to be a typo. It's given as m, which could mean minutes. However, other examples in this document use ms (milliseconds), and the corresponding Planning Time is in ms. It's likely this should also be ms, as 8 minutes seems inconsistent with the context.
| QUERY_PLAN: Execution Time: 8.138 m | |
| QUERY_PLAN: Execution Time: 8.138 ms |
| - [数据查询](./20-select.md) | ||
| - [特色查询](./24-distinguished.md) | ||
| - [关联查询](./25-join.md) | ||
| - [标签索引](./26-tagindex.md) |
There was a problem hiding this comment.
The link to "标签索引" points to ./26-tagindex.md. The corresponding link in the English version is ./26-tag-index.md (with a hyphen). Please verify if 26-tagindex.md is the correct filename, as the missing hyphen might result in a broken link.
| - [标签索引](./26-tagindex.md) | |
| - [标签索引](./26-tag-index.md) |
77717fe to
df1c59e
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds new SQL manual pages documenting EXPLAIN / EXPLAIN ANALYZE output (plan tree structure, common operators, and key metrics) to help users interpret execution plans for tuning and troubleshooting.
Changes:
- Add a Chinese reference page for
EXPLAINwith metric/operator explanations and diagnostic guidance. - Add an English reference page for
EXPLAINwith parallel content and examples. - Provide multiple sample outputs covering plain plans, verbose plans, and analyzed runtime metrics.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/zh/14-reference/03-taos-sql/28-explain.md | New Chinese documentation for EXPLAIN, including syntax, metric quick reference, examples, and diagnostic suggestions. |
| docs/en/14-reference/03-taos-sql/28-explain.md | New English documentation for EXPLAIN, mirroring the Chinese content with examples and guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `EXPLAIN` returns a single column named `QUERY_PLAN`. Each row is either a node in the plan tree or a row with detailed statistic information. | ||
|
|
||
| The execution plan is displayed as a tree: | ||
|
|
||
| - The topmost node is where the final result is produced | ||
| - Deeper indentation means closer to the underlying scan | ||
| - The operator name appears after `->` | ||
| - When `VERBOSE true` is enabled, rows with detailed statistic information are appended below each operator |
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
| *************************** 80.row *************************** | ||
| QUERY_PLAN: Planning Time: 0.484 ms | ||
| *************************** 81.row *************************** | ||
| QUERY_PLAN: Execution Time: 8.138 m |
| `EXPLAIN` returns a single column named `QUERY_PLAN`. Each row is either a node in the plan tree or a row with detailed statistic information. | ||
|
|
||
| The execution plan is displayed as a tree: | ||
|
|
||
| - The topmost node is where the final result is produced | ||
| - Deeper indentation means closer to the underlying scan | ||
| - The operator name appears after `->` | ||
| - When `VERBOSE true` is enabled, rows with detailed statistic information are appended below each operator |
|
|
||
| ## 返回结果说明 | ||
|
|
||
| `EXPLAIN` 的返回结果只有一列，列名为 `QUERY_PLAN`。每一行是计划树中的一个节点或一个详细统计信息。 |
| ## 语法 | ||
|
|
||
| ```sql | ||
| EXPLAIN [ANALYZE] [VERBOSE {true | false}] query_or_subquery; |
There was a problem hiding this comment.
query_or_subquery 简单描述一下范围，比如流计算、Insert into select、show支不支持之类的
| | `Tag Scan on ...` | 标签扫描 | 判断是否只基于标签或元数据就能缩小扫描范围 | | ||
| | `Virtual Table Scan on ...` | 虚拟表扫描 | 判断虚拟表查询是否已经在逻辑层裁剪数据 | | ||
|
|
||
| ## 指标速查 |
There was a problem hiding this comment.
子查询的格式和计划没有说明，加一章节说明一下吧，举个示例
Description
Issue(s)
Checklist
Please check the items in the checklist if applicable.