描述

此命令显示 PostgreSQL 规划器为给定语句生成的执行计划。执行计划显示语句引用的表将如何被扫描——通过普通顺序扫描、索引扫描等——如果引用了多个表，将使用什么连接算法来整合来自每个输入表的必需行。

显示中最关键的部分是估计的语句执行成本，这是规划器对运行该语句所需时间的猜测（以任意的成本单位衡量，但通常表示磁盘页面读取）。实际上显示了两个数字：返回第一行之前的启动成本，以及返回所有行的总成本。对于大多数查询，总成本才是重要的，但在像 EXISTS 中的子查询这样的上下文中，规划器会选择最小的启动成本而不是最小的总成本（因为执行器将在获取一行后停止）。此外，如果您使用 LIMIT 子句限制要返回的行数，规划器会在端点成本之间进行适当的插值，以估计哪个计划才是真正最便宜的。

使用 ANALYZE 选项会实际执行该语句，而不仅仅是计划。然后，执行时间统计信息将被添加到显示中，包括每个计划节点实际花费的总时间（以毫秒为单位）以及它实际返回的总行数。这有助于了解规划器的估计是否接近实际情况。

BEGIN;
EXPLAIN ANALYZE ...;
ROLLBACK;

参数

输出

命令的结果是对为 statement 选择的计划的文本描述，可选择性地附带执行统计信息。第 14.1 节 描述了提供的信息。

注释

为了让 PostgreSQL 查询规划器在优化查询时做出合理的决策，查询中使用的所有表的 pg_statistic 数据应是最新的。通常 autovacuum 守护进程 会自动处理此问题。但是，如果一个表的 DDL 最近有substantial 变化，您可能需要执行手动 ANALYZE，而不是等待 autovacuum 跟上这些 DDL。

为了测量执行计划中每个节点的运行成本，EXPLAIN ANALYZE 的当前实现会为查询执行添加分析开销。因此，对查询运行 EXPLAIN ANALYZE 有时会比正常执行查询花费更长的时间。开销的大小取决于查询的性质以及使用的平台。最坏的情况发生在计划节点本身每次执行所需时间非常短，并且在具有相对缓慢的操作系统调用来获取一天时间的机器上。

示例

要显示具有单个 integer 列和 10000 行的表的简单查询的计划

EXPLAIN SELECT * FROM foo;

                       QUERY PLAN
---------------------------------------------------------
 Seq Scan on foo  (cost=0.00..155.00 rows=10000 width=4)
(1 row)

这是同一个查询，使用 JSON 输出格式

EXPLAIN (FORMAT JSON) SELECT * FROM foo;
           QUERY PLAN
--------------------------------
 [                             +
   {                           +
     "Plan": {                 +
       "Node Type": "Seq Scan",+
       "Relation Name": "foo", +
       "Alias": "foo",         +
       "Startup Cost": 0.00,   +
       "Total Cost": 155.00,   +
       "Plan Rows": 10000,     +
       "Plan Width": 4         +
     }                         +
   }                           +
 ]
(1 row)

如果存在索引并且我们使用带有可索引 WHERE 条件的查询，EXPLAIN 可能会显示不同的计划

EXPLAIN SELECT * FROM foo WHERE i = 4;

                         QUERY PLAN
--------------------------------------------------------------
 Index Scan using fi on foo  (cost=0.00..5.98 rows=1 width=4)
   Index Cond: (i = 4)
(2 rows)

这是同一个查询，但采用 YAML 格式

EXPLAIN (FORMAT YAML) SELECT * FROM foo WHERE i='4';
          QUERY PLAN
-------------------------------
 - Plan:                      +
     Node Type: "Index Scan"  +
     Scan Direction: "Forward"+
     Index Name: "fi"         +
     Relation Name: "foo"     +
     Alias: "foo"             +
     Startup Cost: 0.00       +
     Total Cost: 5.98         +
     Plan Rows: 1             +
     Plan Width: 4            +
     Index Cond: "(i = 4)"
(1 row)

XML 格式留给读者作为练习。

这是相同的计划，但抑制了成本估算

EXPLAIN (COSTS FALSE) SELECT * FROM foo WHERE i = 4;

        QUERY PLAN
----------------------------
 Index Scan using fi on foo
   Index Cond: (i = 4)
(2 rows)

这是一个使用聚合函数的查询的查询计划示例

EXPLAIN SELECT sum(i) FROM foo WHERE i < 10;

                             QUERY PLAN
-------------------------------------------------------------------​--
 Aggregate  (cost=23.93..23.93 rows=1 width=4)
   ->  Index Scan using fi on foo  (cost=0.00..23.92 rows=6 width=4)
         Index Cond: (i < 10)
(3 rows)

这是使用 EXPLAIN EXECUTE 显示预备查询执行计划的示例

PREPARE query(int, int) AS SELECT sum(bar) FROM test
    WHERE id > $1 AND id < $2
    GROUP BY foo;

EXPLAIN ANALYZE EXECUTE query(100, 200);

                                                       QUERY PLAN
-------------------------------------------------------------------​------------------------------------------------------
 HashAggregate  (cost=10.77..10.87 rows=10 width=12) (actual time=0.043..0.044 rows=10.00 loops=1)
   Group Key: foo
   Batches: 1  Memory Usage: 24kB
   Buffers: shared hit=4
   ->  Index Scan using test_pkey on test  (cost=0.29..10.27 rows=99 width=8) (actual time=0.009..0.025 rows=99.00 loops=1)
         Index Cond: ((id > 100) AND (id < 200))
         Index Searches: 1
         Buffers: shared hit=4
 Planning Time: 0.244 ms
 Execution Time: 0.073 ms
(10 rows)

当然，这里显示的具体数字取决于相关表的实际内容。还要注意，由于规划器的改进，数字，甚至选择的查询策略，在 PostgreSQL 的不同版本之间可能会有所不同。此外，ANALYZE 命令使用随机抽样来估算数据统计信息；因此，即使表中数据的实际分布没有改变，成本估算在每次运行 ANALYZE 后也可能发生变化。

请注意，前面的示例显示了一个针对 EXECUTE 中给定的特定参数值的“custom”计划。我们也可能希望看到参数化查询的通用计划，这可以通过 GENERIC_PLAN 来实现

EXPLAIN (GENERIC_PLAN)
  SELECT sum(bar) FROM test
    WHERE id > $1 AND id < $2
    GROUP BY foo;

                                  QUERY PLAN
-------------------------------------------------------------------​------------
 HashAggregate  (cost=26.79..26.89 rows=10 width=12)
   Group Key: foo
   ->  Index Scan using test_pkey on test  (cost=0.29..24.29 rows=500 width=8)
         Index Cond: ((id > $1) AND (id < $2))
(4 rows)

在这种情况下，解析器正确推断出 $1 和 $2 应该与 id 具有相同的数据类型，因此 PREPARE 缺少参数类型信息不成问题。在其他情况下，可能需要显式指定参数符号的类型，可以通过强制类型转换来实现，例如

EXPLAIN (GENERIC_PLAN)
  SELECT sum(bar) FROM test
    WHERE id > $1::integer AND id < $2::integer
    GROUP BY foo;

兼容性

SQL 标准中没有定义 EXPLAIN 语句。

在 PostgreSQL 版本 9.0 之前使用了以下语法，并且仍然支持

EXPLAIN [ ANALYZE ] [ VERBOSE ] statement

请注意，在此语法中，选项必须按所示顺序精确指定。

另请参阅