EXPLAIN ANALYZE GRAPHICAL (#1989)

Co-authored-by: z <[email protected]>

Author: soyeric128

docs/en/sql-reference/10-sql-commands/40-explain-cmds/explain-analyze-graphical.md

@@ -4,50 +4,66 @@ title: EXPLAIN ANALYZE GRAPHICAL
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced: v1.2.647"/>
+<FunctionDescription description="Introduced or updated: v1.2.647"/>
 
-`EXPLAIN ANALYZE GRAPHICAL` used to open a browser page to display a query execution plan along with actual run-time performance statistics.
+`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 is useful for analyzing query performance and identifying bottlenecks in a query.
-
-**Note:** This feature is available only in BendSQL.
+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).
 
 ## Syntax
 
 ```sql
 EXPLAIN ANALYZE GRAPHICAL <statement>
 ```
 
+## Configuring BendSQL
+
+To enable graphical analysis and automatically open your default browser, add the following section to your BendSQL configuration file `~/.config/bendsql/config.toml`:
+
+```toml
+[server]
+bind_address = "127.0.0.1"        
+auto_open_browser = true      
+```
+
 ## Examples
 
-TPC-H Q21:
+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.
 
-```sql
-EXPLAIN ANALYZE GRAPHICAL SELECT s_name,
-    ->        Count(*) AS numwait
-    -> FROM   supplier,
-    ->        lineitem l1,
-    ->        orders,
-    ->        nation
-    -> WHERE  s_suppkey = l1.l_suppkey
-    ->        AND o_orderkey = l1.l_orderkey
-    ->        AND o_orderstatus = 'F'
-    ->        AND l1.l_receiptdate > l1.l_commitdate
-    ->        AND EXISTS (SELECT *
-    ->                    FROM   lineitem l2
-    ->                    WHERE  l2.l_orderkey = l1.l_orderkey
-    ->                           AND l2.l_suppkey <> l1.l_suppkey)
-    ->        AND NOT EXISTS (SELECT *
-    ->                        FROM   lineitem l3
-    ->                        WHERE  l3.l_orderkey = l1.l_orderkey
-    ->                               AND l3.l_suppkey <> l1.l_suppkey
-    ->                               AND l3.l_receiptdate > l3.l_commitdate)
-    ->        AND s_nationkey = n_nationkey
-    ->        AND n_name = 'EGYPT'
-    -> GROUP  BY s_name
-    -> ORDER  BY numwait DESC,
-    ->           s_name
-    -> LIMIT  100;
-
-// will open a browser page to display the query execution plan and performance statistics.
+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;
 ```
+
+After running the command, BendSQL outputs a message like:
+
+```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.
+
+![alt text](@site/static/img/documents/sql/explain-graphical.png)