# EXPLAIN
#### 功能描述
显示SQL语句的执行计划。
执行计划将显示SQL语句所引用的表会采用什么样的扫描方式，如：简单的顺序扫描、索引扫描等。如果引用了多个表，执行计划还会显示用到的JOIN算法。
执行计划的最关键的部分是语句的预计执行开销，这是计划生成器估算执行该语句将花费多长的时间。
若指定了ANALYZE选项，则该语句会被执行，然后根据实际的运行结果显示统计数据，包括每个计划节点内时间总开销（毫秒为单位）和实际返回的总行数。这对于判断计划生成器的估计值是否接近实际值非常有用。
#### 注意事项
- 在指定ANALYZE选项时，语句会被执行。如果用户想使用EXPLAIN分析INSERT，UPDATE，DELETE或EXECUTE语句，而不想改动数据（执行这些语句会影响数据），请使用如下方法。
  ```
  START TRANSACTION;
  EXPLAIN ANALYZE ...;
  ROLLBACK;
  ```
  
- 由于参数DETAIL，NODES，NUM_NODES是分布式模式下的功能，在单机模式中是被禁止使用的。假如使用，会产生如下错误。
  ```
  m_db=# CREATE TABLE student(id int, name char(20));
  CREATE TABLE
  m_db=# EXPLAIN (NODE true) INSERT INTO student VALUES(5,'a'),(6,'b');
  ERROR:  unrecognized EXPLAIN option "nodes"
  m_db=# EXPLAIN (NUM_NODES true) INSERT INTO student VALUES(5,'a'),(6,'b');
  ERROR:  unrecognized EXPLAIN option "num_nodes"
  ```
  
 
#### 语法格式
- 显示SQL语句的执行计划，支持多种选项，对选项顺序无要求。
  ```
  EXPLAIN [ (  option  [, ...] )  ] statement;
  ```
  其中选项option子句的语法为。
  ```
  ANALYZE [ boolean ] |
      VERBOSE [ boolean ] |
      COSTS [ boolean ] |
      CPU [ boolean ] |
      DETAIL [ boolean ] |
      NODES [ boolean ] |(仅分布式模式可用，集中式模式不可用)
      NUM_NODES [ boolean ] |(仅分布式模式可用，集中式模式不可用)
      BUFFERS [ boolean ] |
      TIMING [ boolean ] |
      PLAN [ boolean ] |
      BLOCKNAME [ boolean ] |
      OUTLINE [ boolean ] |
      ADAPTCOST [ boolean ] |
      FORMAT { TEXT | XML | JSON | YAML }
      OPTEVAL [ boolean ]
  ```
  
- 显示SQL语句的执行计划，且要按顺序给出选项。
  ```
  EXPLAIN  { [   ANALYZE    ] [ VERBOSE  ] } statement;
  ```
  
 
#### 参数说明
- **statement**
  指定要分析的SQL语句。
  
- **ANALYZE boolean**
  显示实际运行时间和其他统计数据。当两个参数同时使用时，在option中排在后面的一个生效。
  取值范围：
  - TRUE（缺省值）：显示实际运行时间和其他统计数据。
  
  - FALSE：不显示。
   
- **VERBOSE boolean**
  显示有关计划的额外信息。
  取值范围：
  - TRUE（缺省值）：显示额外信息。
  
  - FALSE：不显示。
   
- **COSTS boolean**
  包括每个规划节点的估计总成本，以及估计的行数和每行的宽度。
  取值范围：
  - TRUE（缺省值）：显示估计总成本和宽度。
  
  - FALSE：不显示。
   
- **CPU boolean**
  打印CPU的使用情况的信息。需要结合ANALYZE选项一起使用。
  取值范围：
  - TRUE（缺省值）：显示CPU的使用情况。
  
  - FALSE：不显示。
   
- **DETAIL boolean**
  打印数据库节点上的信息。需要结合ANALYZE选项一起使用。
  取值范围：
  - TRUE（缺省值）：打印数据库节点的信息。
  
  - FALSE：不打印。
   
- **NODES boolean** （仅分布式模式可用，集中式模式不可用）
  打印query执行的节点信息。
  取值范围：
  - TRUE（缺省值）：打印执行的节点的信息。
  
  - FALSE：不打印。
   
- **NUM_NODES boolean** （仅分布式模式可用，集中式模式不可用）
  打印执行中的节点的个数信息。
  取值范围：
  - TRUE（缺省值）：打印数据库节点个数的信息。
  
  - FALSE：不打印。
   
- **BUFFERS boolean**
  包括缓冲区的使用情况的信息。需要结合ANALYZE选项一起使用。
  取值范围：
  - TRUE：显示缓冲区的使用情况。
  
  - FALSE（缺省值）：不显示。
   
- **TIMING boolean**
  包括实际的启动时间和花费在输出节点上的时间信息。需要结合ANALYZE选项一起使用。
  取值范围：
  - TRUE（缺省值）：显示启动时间和花费在输出节点上的时间信息。
  
  - FALSE：不显示。
   
- **PLAN**
  是否将执行计划存储在plan_table中。当该选项开启时，会将执行计划存储在plan_table中，不打印到当前屏幕，因此该选项为on时，不能与其他选项同时使用。
  取值范围：
  - ON（缺省值）：将执行计划存储在plan_table中，不打印到当前屏幕。执行成功返回EXPLAIN SUCCESS。
  
  - OFF：不存储执行计划，将执行计划打印到当前屏幕。
   
- **BLOCKNAME** **boolean**
  是否显示计划的每个操作所处于的查询块。当该选项开启时，会将每个操作所处于的查询块的名字输出在Query Block列上，方便用户获取查询块名字，并使用Hint修改执行计划：
  - TRUE（缺省值）：显示计划时，将每个操作所处于的查询块的名字输出在新增列Query Block列上。该选项需要在pretty模式下使用。
  
  - FALSE：不对计划显示产生影响。
   
- **OUTLINE** **boolean**
  是否显示计划的Outline Hint信息。
  - ON：显示计划时，将Outline Hint显示在计划下方 。
  
  - OFF（缺省值）：不显示计划的Outline Hint信息。
   
- **ADAPTCOST** **boolean**
  在Normal模式下是否显示计划的基数估计方式信息。
  - ON（缺省值）：Normal模式下，在计划节点上展示基数估计的方式，包含默认方式和反馈方式，不对预备语句生效。
  
  - OFF：不展示基数估计的方式信息。
   
- **FORMAT**
  指定输出格式。
  取值范围：TEXT，XML，JSON和YAML。
  默认值：TEXT。
  
- **PERFORMANCE**
  使用此选项时，即打印执行中的所有相关信息。下述为部分信息描述：
  - ex c/r：代表平均每行使用cpu周期数，等于（ex cyc）/（ex row）。
  
  - ex row：执行行数。
  
  - ex cyc：代表使用的cpu周期数。
  
  - inc cyc：代表包含子节点使用的总cpu周期数。
  
  - shared hit：代表算子的share buffer命中情况。
  
  - loops：算子循环执行次数。
  
  - total_calls：生成元素总数。
  
  - remote query poll time stream gather：算子用于侦听各DN数据到达CN的网络poll时间。
  
  - deserialize time：反序列化所需时间。
  
  - estimated time：估计时间。
   
- **OPTEVAL boolean**
  是否显示SCAN算子（当前仅支持seqscan、indexscan、indexonlyscan、bitmapheapscan）的代价淘汰明细，当开启此开关的时候，会在执行计划中显示一个名字为Cost Evaluation Info (identified by plan id)的计划块，该选项仅仅可以和COSTS、VERBOSE、FORMAT三个选项共存。此计划块中的具体参数明细，请参考[示例2]。
  取值范围：
  - TRUE：显示SCAN算子的代价淘汰明细。
  
  - FALSE（缺省值）：不显示。
    
 
#### 示例1
```
--创建SCHEMA。
m_db=# CREATE SCHEMA tpcds; 
--创建表tpcds.customer_address。
m_db=# CREATE TABLE tpcds.customer_address
(
ca_address_sk         INTEGER           NOT NULL,
ca_address_id         CHARACTER(16)     NOT NULL
);
 
--向表中插入多条记录。
m_db=# INSERT INTO tpcds.customer_address VALUES (5000, 'AAAAAAAABAAAAAAA'),(10000, 'AAAAAAAACAAAAAAA');
--创建一个表tpcds.customer_address_p1。
m_db=# CREATE TABLE tpcds.customer_address_p1 LIKE tpcds.customer_address;
--修改explain_perf_mode为normal。
m_db=# SET explain_perf_mode=normal;
--显示表简单查询的执行计划。
m_db=# EXPLAIN SELECT * FROM tpcds.customer_address_p1;
                              QUERY PLAN                               
-----------------------------------------------------------------------
 Seq Scan on customer_address_p1  (cost=0.00..18.01 rows=801 width=72)
(1 row)
--以JSON格式输出的执行计划（explain_perf_mode为normal时）。
m_db=# EXPLAIN(FORMAT JSON) SELECT * FROM tpcds.customer_address_p1;
                  QUERY PLAN                   
-----------------------------------------------
 [                                            +
   {                                          +
     "Plan": {                                +
       "Node Type": "Seq Scan",               +
       "Relation Name": "customer_address_p1",+
       "Alias": "customer_address_p1",        +
       "Startup Cost": 0.00,                  +
       "Total Cost": 18.01,                   +
       "Plan Rows": 801,                      +
       "Plan Width": 72                       +
     }                                        +
   }                                          +
 ]
(1 row)
--如果有一个索引，当使用一个带索引WHERE条件的查询，可能会显示一个不同的计划。
m_db=# EXPLAIN SELECT * FROM tpcds.customer_address_p1 WHERE ca_address_sk=10000;
                             QUERY PLAN                              
---------------------------------------------------------------------
 Seq Scan on customer_address_p1  (cost=0.00..20.01 rows=4 width=72)
   Filter: (ca_address_sk = 10000)
(2 rows)
--以YAML格式输出的执行计划（explain_perf_mode为normal时）。
m_db=# EXPLAIN(FORMAT YAML) SELECT * FROM tpcds.customer_address_p1 WHERE ca_address_sk=10000;
                QUERY PLAN                
------------------------------------------
 - Plan:                                 +
     Node Type: "Seq Scan"               +
     Relation Name: "customer_address_p1"+
     Alias: "customer_address_p1"        +
     Startup Cost: 0.00                  +
     Total Cost: 20.01                   +
     Plan Rows: 4                        +
     Plan Width: 72                      +
     Filter: "(ca_address_sk = 10000)"
(1 row)
--禁止开销估计的执行计划。
m_db=# EXPLAIN(COSTS FALSE) SELECT * FROM tpcds.customer_address_p1 WHERE ca_address_sk=10000;
            QUERY PLAN             
-----------------------------------
 Seq Scan on customer_address_p1
   Filter: (ca_address_sk = 10000)
(2 rows)
--带有聚集函数查询的执行计划。
m_db=# EXPLAIN SELECT SUM(ca_address_sk) FROM tpcds.customer_address_p1 WHERE ca_address_sk<10000;
                                 QUERY PLAN                                 
----------------------------------------------------------------------------
 Aggregate  (cost=20.68..20.69 rows=1 width=12)
   ->  Seq Scan on customer_address_p1  (cost=0.00..20.01 rows=267 width=4)
         Filter: (ca_address_sk < 10000)
(3 rows)
--创建一个二级分区表。
m_db=# CREATE TABLE range_hash ( ID INT, purchased YEAR ) PARTITION BY RANGE ( ID ) SUBPARTITION BY HASH ( purchased ) (
PARTITION p0
VALUES
LESS THAN ( 1000 ) ( SUBPARTITION s0, SUBPARTITION s1 ),
PARTITION p1
VALUES
LESS THAN ( 2000 ) ( SUBPARTITION s2, SUBPARTITION s3 ),
PARTITION p2
VALUES
LESS THAN MAXVALUE ( SUBPARTITION s4, SUBPARTITION s5 ) 
);
--执行带有二级分区表的查询语句。
m_db=# EXPLAIN SELECT * FROM range_hash WHERE purchased  = '1';
                                  QUERY PLAN                                  
------------------------------------------------------------------------------
 Partition Iterator  (cost=0.00..36.86 rows=11 width=8)
   Iterations: 3, Sub Iterations: 6
   ->  Partitioned Seq Scan on range_hash  (cost=0.00..36.86 rows=11 width=8)
         Filter: (purchased = '2001'::year)
         Selected Partitions:  1..3
         Selected Subpartitions:  ALL
(6 rows)
--删除表tpcds.customer_address_p1。
m_db=# DROP TABLE tpcds.customer_address_p1;
--删除表tpcds.customer_address。
m_db=# DROP TABLE tpcds.customer_address;
--删除表range_list。
m_db=# DROP TABLE range_hash;
--删除SCHEMA。
m_db=# DROP SCHEMA tpcds;
```
 #### 示例2
```
--创建tb_a，tb_b。
m_db=# CREATE TABLE tb_a(c1 int);
m_db=# INSERT INTO tb_a VALUES(1),(2),(3);
m_db=# CREATE TABLE tb_b AS SELECT * FROM tb_a;
m_db=# EXPLAIN (OPTEVAL on )SELECT * FROM tb_a a, tb_b b WHERE a.c1=b.c1 AND a.c1=1;
                             QUERY PLAN                             
--------------------------------------------------------------------
 Nested Loop  (cost=0.00..81.88 rows=144 width=8)
   ->  Seq Scan on tb_a a  (cost=0.00..40.03 rows=12 width=4)
         Filter: (c1 = 1)
   ->  Materialize  (cost=0.00..40.09 rows=12 width=4)
         ->  Seq Scan on tb_b b  (cost=0.00..40.03 rows=12 width=4)
               Filter: (c1 = 1)
(6 rows)
--删除表tb_a，tb_b。
m_db=# DROP TABLE tb_a;
m_db=# DROP TABLE tb_b;
```
![](https://support.huaweicloud.com/centralized-m-comp-devg-v8-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
针对Cost Evaluation Info (identified by plan id)计划块：
1. "2 --"与"4 --"所在行表示的是当前胜选算子，它们各自下面的缩进计划块表示的是当前胜选算子直接淘汰的算子。如算子2淘汰的算子有Seq Scan算子和Bitmap Heap Scan算子。
2. 如上所示，对上述看到的关键参数进行说明：
   1. id表示当前算子从指定id的path转换而来，该值主要用于在debug2日志中方便定位某一条路径。
   
   2. rpage表示在代价模型计算过程中使用的基表的页面数。
   
   3. ipage表示在代价模型计算过程中使用的索引的页面数。
   
   4. tuples表示在代价模型计算过程中使用的tuple的数量。
   
   5. selec表示在代价模型计算过程中使用的索引选择率，-1表示当前算子的索引选择率无效。
   
   6. ml表示在代价模型计算过程中，当前触发的ML模型事件，1表示effective_cache_size指定的缓存足够，2表示effective_cache_size指定的缓存不足，3表示effective_cache_size指定的缓存严重不足。
   
   7. iscost表示在模型代价计算过程中是否发生过忽略启动代价的事件。
   
   8. lossy表示在代价模型计算过程中是否触发bitmap heap scan的lossy机制。
   
   9. uidx表示在代价模型计算过程中是否触发唯一索引优先规则。
    
 
#### 相关链接
[ANALYZE](https://support.huaweicloud.com/centralized-m-comp-devg-v8-gaussdb/gaussdb-81-0061.html#ZH-CN_TOPIC_0000002558939371)