From 9c80cceb023130ac94f1167ce8ab9355de1a9bd0 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 15 Feb 2000 23:37:49 +0000
Subject: [PATCH] Update EXPLAIN documentation to reflect the fact that the
 planner now produces two cost numbers instead of one.

---
 doc/src/sgml/ref/explain.sgml | 49 ++++++++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 12 deletions(-)

diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index cc73bcf7ff..e7622fb026 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.8 1999/07/22 15:09:12 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.9 2000/02/15 23:37:49 tgl Exp $
 Postgres documentation
 -->
 
@@ -15,7 +15,7 @@ Postgres documentation
    EXPLAIN
   </refname>
   <refpurpose>
-   Shows statement execution details
+   Shows statement execution plan
   </refpurpose>
  </refnamediv>
 
@@ -102,12 +102,32 @@ EXPLAIN
   </title>
 
   <para>
-   This command outputs details about the supplied query.
-   The default output is the computed query cost. 
-   The cost value is only meaningful to the optimizer in comparing
-   various query plans.
-   VERBOSE displays the full query plan and cost to your screen,
-   and pretty-prints the plan to the postmaster log file.   
+   This command displays the execution plan that the Postgres planner
+   generates for the supplied query.  The execution plan shows how
+   the table(s) referenced by the query will be scanned --- by plain
+   sequential scan, index scan etc --- and if multiple tables are
+   referenced, what join algorithms will be used to bring together
+   the required tuples from each input table.
+  </para>
+
+  <para>
+   The most critical part of the display is the estimated query execution
+   cost, which is the planner's guess at how long it will take to run the
+   query (measured in units of disk page fetches).  Actually two numbers
+   are shown: the startup time before the first tuple can be returned, and
+   the total time to return all the tuples.  For most queries the total time
+   is what matters, but in contexts such as an EXISTS sub-query the planner
+   will choose the smallest startup time instead of the smallest total time
+   (since the executor will stop after getting one tuple, anyway).
+   Also, if you limit the number of tuples to return with a LIMIT clause,
+   the planner makes an appropriate interpolation between the endpoint
+   costs to estimate which plan is really the cheapest.
+  </para>
+
+  <para>
+   The VERBOSE option emits the full internal representation of the plan tree,
+   rather than just a summary (and sends it to the postmaster log file, too).
+   Usually this option is only useful for debugging Postgres.
   </para>
 
   <refsect2 id="R2-SQL-EXPLAIN-3">
@@ -143,7 +163,7 @@ EXPLAIN SELECT * FROM foo;
     <computeroutput>
 NOTICE:  QUERY PLAN:
 
-Seq Scan on foo  (cost=5.22 rows=128 width=4)
+Seq Scan on foo  (cost=0.00..2.28 rows=128 width=4)
 
 EXPLAIN
     </computeroutput>
@@ -160,7 +180,7 @@ EXPLAIN SELECT * FROM foo WHERE i = 4;
     <computeroutput>
 NOTICE:  QUERY PLAN:
 
-Index Scan using fi on foo  (cost=2.05 rows=1 width=4)
+Index Scan using fi on foo  (cost=0.00..0.42 rows=1 width=4)
 
 EXPLAIN
     </computeroutput>
@@ -178,11 +198,16 @@ EXPLAIN SELECT sum(i) FROM foo WHERE i = 4;
     <computeroutput>
 NOTICE:  QUERY PLAN:
 
-Aggregate  (cost=2.05 rows=1 width=4)
-  ->  Index Scan using fi on foo  (cost=2.05 rows=1 width=4)
+Aggregate  (cost=0.42..0.42 rows=1 width=4)
+  ->  Index Scan using fi on foo  (cost=0.00..0.42 rows=1 width=4)
     </computeroutput>
    </programlisting>
   </para>
+
+  <para>
+   Note that the specific numbers shown, and even the selected query
+   strategy, may vary between Postgres releases due to planner improvements.
+  </para>
  </refsect1>
 
  <refsect1 id="R1-SQL-EXPLAIN-3">
-- 
2.40.0