From eddf7fc62fa7bcf67225ebd8bca9810aab84a1d0 Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Thu, 28 Aug 2025 00:18:20 +0800 Subject: [PATCH] docs: optimize EXPLAIN commands documentation - Remove unused EXPLAIN MEMO and EXPLAIN FRAGMENTS commands - Simplify EXPLAIN ANALYZE GRAPHICAL documentation - Add concise commands overview table with links - Improve documentation clarity and usability --- .../40-explain-cmds/explain-memo.md | 35 ------------- .../explain-analyze-graphical.md | 50 +++++-------------- .../40-explain-cmds/explain-fragments.md | 36 ------------- .../40-explain-cmds/explain-memo.md | 35 ------------- .../10-sql-commands/40-explain-cmds/index.md | 13 ++++- 5 files changed, 23 insertions(+), 146 deletions(-) delete mode 100644 docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md delete mode 100644 docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-fragments.md delete mode 100644 docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md diff --git a/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md b/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md deleted file mode 100644 index 7a100545bb..0000000000 --- a/docs/cn/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: EXPLAIN MEMO ---- - -返回查询的内部结构 `Memo`。 - -## 语法 - -```sql -EXPLAIN MEMO -``` - -## 示例 - -```sql -EXPLAIN MEMO SELECT * FROM numbers(10) t, numbers(100) t1; - - ---- - Group #0 - ├── best cost: [#1] 10 - ├── LogicalGet [] - └── PhysicalScan [] - - Group #1 - ├── best cost: [#1] 100 - ├── LogicalGet [] - └── PhysicalScan [] - - Group #2 - ├── best cost: [#3] 310 - ├── LogicalJoin [#0, #1] - ├── LogicalJoin [#1, #0] - ├── PhysicalHashJoin [#0, #1] - └── PhysicalHashJoin [#1, #0] -``` \ No newline at end of file diff --git a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-analyze-graphical.md b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-analyze-graphical.md index 19f220d86b..3a7d3b4669 100644 --- a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-analyze-graphical.md +++ b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-analyze-graphical.md @@ -6,9 +6,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -`EXPLAIN ANALYZE GRAPHICAL` is a command available exclusively in the BendSQL client. It allows you to analyze the performance and execution plan of a SQL query by automatically launching your default browser and presenting an interactive visual representation of the query execution process. - -This command is supported only in BendSQL v0.22.2 and above. Before using it, ensure that your BendSQL is properly configured. For setup instructions, see [Configuring BendSQL](#configuring-bendsql). +Analyzes query performance with an interactive visual representation in your browser. Available exclusively in BendSQL v0.22.2+. ## Syntax @@ -16,9 +14,9 @@ This command is supported only in BendSQL v0.22.2 and above. Before using it, en EXPLAIN ANALYZE GRAPHICAL ``` -## Configuring BendSQL +## Configuration -To enable graphical analysis and automatically open your default browser, add the following section to your BendSQL configuration file `~/.config/bendsql/config.toml`: +Add to your BendSQL config file `~/.config/bendsql/config.toml`: ```toml [server] @@ -26,44 +24,20 @@ bind_address = "127.0.0.1" auto_open_browser = true ``` -## Examples - -You can use `EXPLAIN ANALYZE GRAPHICAL` to analyze the performance of complex queries, such as TPC-H benchmark queries, and understand how each part of the query contributes to overall execution time. +## Example -Here is an example query that calculates aggregates from the `lineitem` table: - -```bash -eric@(eric-xsmall)/tpch_100> EXPLAIN ANALYZE GRAPHICAL select - l_returnflag, - l_linestatus, - sum(l_quantity) as sum_qty, - sum(l_extendedprice) as sum_base_price, - sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - avg(l_quantity) as avg_qty, - avg(l_extendedprice) as avg_price, - avg(l_discount) as avg_disc, - count(*) as count_order -from - lineitem -where - l_shipdate <= add_days(to_date('1998-12-01'), -90) -group by - l_returnflag, - l_linestatus -order by - l_returnflag, - l_linestatus; +```sql +EXPLAIN ANALYZE GRAPHICAL SELECT l_returnflag, COUNT(*) +FROM lineitem +WHERE l_shipdate <= '1998-09-01' +GROUP BY l_returnflag; ``` -After running the command, BendSQL outputs a message like: - +Output: ```bash View graphical online: http://127.0.0.1:8080?perf_id=1 - -1095 rows graphical in 21.762 sec. Processed 0 rows, 0 B (0 row/s, 0 B/s) ``` -This automatically opens your default browser and shows an interactive graphical view of the query execution plan, including operator runtimes, row counts, and data flow between stages. +Opens an interactive view showing execution plan, operator runtimes, and data flow. -![alt text](@site/static/img/documents/sql/explain-graphical.png) \ No newline at end of file +![Graphical Analysis](@site/static/img/documents/sql/explain-graphical.png) \ No newline at end of file diff --git a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-fragments.md b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-fragments.md deleted file mode 100644 index f30dbe32e3..0000000000 --- a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-fragments.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: EXPLAIN FRAGMENTS ---- - -Shows the distributed execution plan of an SQL statement. - -This command transforms the execution plan of an SQL statement into plan fragments where you can see the process of retrieving the data you need from Databend. - -## Syntax - -```sql -EXPLAIN FRAGMENTS -``` - -## Examples - -```sql -EXPLAIN FRAGMENTS select COUNT() from numbers(10) GROUP BY number % 3; - -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| explain | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Fragment 0: | -| DataExchange: Shuffle | -| AggregatorPartial: groupBy=[[(number % 3)]], aggr=[[COUNT()]] | -| Expression: (number % 3):UInt8 (Before GroupBy) | -| ReadDataSource: scan schema: [number:UInt64], statistics: [read_rows: 10, read_bytes: 80, partitions_scanned: 1, partitions_total: 1], push_downs: [projections: [0]] | -| | -| Fragment 2: | -| DataExchange: Merge | -| Projection: COUNT():UInt64 | -| AggregatorFinal: groupBy=[[(number % 3)]], aggr=[[COUNT()]] | -| Remote[receive fragment: 0] | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -11 rows in set (0.02 sec) -``` diff --git a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md deleted file mode 100644 index 517fd7f051..0000000000 --- a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-memo.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: EXPLAIN MEMO ---- - -Returns the internal structure `Memo` of the query. - -## Syntax - -```sql -EXPLAIN MEMO -``` - -## Examples - -```sql -EXPLAIN MEMO SELECT * FROM numbers(10) t, numbers(100) t1; - - ---- - Group #0 - ├── best cost: [#1] 10 - ├── LogicalGet [] - └── PhysicalScan [] - - Group #1 - ├── best cost: [#1] 100 - ├── LogicalGet [] - └── PhysicalScan [] - - Group #2 - ├── best cost: [#3] 310 - ├── LogicalJoin [#0, #1] - ├── LogicalJoin [#1, #0] - ├── PhysicalHashJoin [#0, #1] - └── PhysicalHashJoin [#1, #0] -``` diff --git a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/index.md b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/index.md index 7a016629b2..e018f4e12b 100644 --- a/docs/en/sql-reference/10-sql-commands/40-explain-cmds/index.md +++ b/docs/en/sql-reference/10-sql-commands/40-explain-cmds/index.md @@ -1,8 +1,17 @@ --- title: Explain Commands --- -import IndexOverviewList from '@site/src/components/IndexOverviewList'; This page provides reference information for the explain-related commands in Databend. - \ No newline at end of file +## Commands Overview + +| Command | Use Case | +|---------|----------| +| [`EXPLAIN`](./explain) | Understanding query structure and optimization | +| [`EXPLAIN ANALYZE`](./explain-analyze) | Performance analysis with runtime statistics | +| [`EXPLAIN ANALYZE GRAPHICAL`](./explain-analyze-graphical) | Visual performance analysis (BendSQL only) | +| [`EXPLAIN AST`](./explain-ast) | SQL parsing and syntax analysis | +| [`EXPLAIN PERF`](./explain-perf) | Query performance profiling (BendSQL only) | +| [`EXPLAIN RAW`](./explain-raw) | Internal query processing analysis | +| [`EXPLAIN SYNTAX`](./explain-syntax) | SQL code formatting and standardization | \ No newline at end of file