granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/explain.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.9 2000/02/15 23:37:49 tgl Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-EXPLAIN">
   7  <refmeta>
   8   <refentrytitle id="SQL-EXPLAIN-TITLE">
   9    EXPLAIN
  10   </refentrytitle>
  11   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    EXPLAIN
  16   </refname>
  17   <refpurpose>
  18    Shows statement execution plan
  19   </refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <refsynopsisdivinfo>
  24    <date>1999-07-20</date>
  25   </refsynopsisdivinfo>
  26   <synopsis>
  27 EXPLAIN [ VERBOSE ] <replaceable class="PARAMETER">query</replaceable>
  28   </synopsis>
  29
  30   <refsect2 id="R2-SQL-EXPLAIN-1">
  31    <refsect2info>
  32     <date>1998-09-01</date>
  33    </refsect2info>
  34    <title>
  35     Inputs
  36    </title>
  37    <para>
  38
  39     <variablelist>
  40      <varlistentry>
  41       <term>VERBOSE</term>
  42       <listitem>
  43        <para>
  44         Flag to show detailed query plan.
  45        </para>
  46       </listitem>
  47      </varlistentry>
  48      <varlistentry>
  49       <term><replaceable class="PARAMETER">query</replaceable></term>
  50       <listitem>
  51        <para>
  52         Any <replaceable class="PARAMETER">query</replaceable>.
  53        </para>
  54       </listitem>
  55      </varlistentry>
  56     </variablelist>
  57    </para>
  58   </refsect2>
  59
  60   <refsect2 id="R2-SQL-EXPLAIN-2">
  61    <refsect2info>
  62     <date>1998-04-15</date>
  63    </refsect2info>
  64    <title>
  65     Outputs
  66    </title>
  67    <para>
  68
  69     <variablelist>
  70      <varlistentry>
  71       <term><computeroutput>
  72 NOTICE:  QUERY PLAN:
  73 <replaceable>plan</replaceable>
  74       </computeroutput></term>
  75       <listitem>
  76        <para>
  77         Explicit query plan from the <productname>Postgres</productname> backend.
  78        </para>
  79       </listitem>
  80      </varlistentry>
  81      <varlistentry>
  82       <term><computeroutput>
  83 EXPLAIN
  84        </computeroutput></term>
  85       <listitem>
  86        <para>
  87         Flag sent after query plan is shown.
  88        </para>
  89       </listitem>
  90      </varlistentry>
  91     </variablelist>
  92    </para>
  93   </refsect2>
  94  </refsynopsisdiv>
  95
  96  <refsect1 id="R1-SQL-EXPLAIN-1">
  97   <refsect1info>
  98    <date>1998-04-15</date>
  99   </refsect1info>
 100   <title>
 101    Description
 102   </title>
 103
 104   <para>
 105    This command displays the execution plan that the Postgres planner
 106    generates for the supplied query.  The execution plan shows how
 107    the table(s) referenced by the query will be scanned --- by plain
 108    sequential scan, index scan etc --- and if multiple tables are
 109    referenced, what join algorithms will be used to bring together
 110    the required tuples from each input table.
 111   </para>
 112
 113   <para>
 114    The most critical part of the display is the estimated query execution
 115    cost, which is the planner's guess at how long it will take to run the
 116    query (measured in units of disk page fetches).  Actually two numbers
 117    are shown: the startup time before the first tuple can be returned, and
 118    the total time to return all the tuples.  For most queries the total time
 119    is what matters, but in contexts such as an EXISTS sub-query the planner
 120    will choose the smallest startup time instead of the smallest total time
 121    (since the executor will stop after getting one tuple, anyway).
 122    Also, if you limit the number of tuples to return with a LIMIT clause,
 123    the planner makes an appropriate interpolation between the endpoint
 124    costs to estimate which plan is really the cheapest.
 125   </para>
 126
 127   <para>
 128    The VERBOSE option emits the full internal representation of the plan tree,
 129    rather than just a summary (and sends it to the postmaster log file, too).
 130    Usually this option is only useful for debugging Postgres.
 131   </para>
 132
 133   <refsect2 id="R2-SQL-EXPLAIN-3">
 134    <refsect2info>
 135     <date>1998-04-15</date>
 136    </refsect2info>
 137    <title>
 138     Notes
 139    </title>
 140    <para>
 141     There is only sparse documentation on the optimizer's use of cost
 142     information in <productname>Postgres</productname>.
 143     General information on cost estimation for query optimization
 144     can be found in database textbooks.
 145     Refer to the <citetitle>Programmer's Guide</citetitle>
 146     in the chapters on indexes and the genetic query optimizer for
 147     more information.
 148    </para>
 149   </refsect2>
 150  </refsect1>
 151
 152  <refsect1 id="R1-SQL-EXPLAIN-2">
 153   <title>
 154    Usage
 155   </title>
 156
 157   <para>
 158    To show a query plan for a simple query on a table with a single
 159    <type>int4</type> column and 128 rows:
 160
 161    <programlisting>
 162 EXPLAIN SELECT * FROM foo;
 163     <computeroutput>
 164 NOTICE:  QUERY PLAN:
 165
 166 Seq Scan on foo  (cost=0.00..2.28 rows=128 width=4)
 167
 168 EXPLAIN
 169     </computeroutput>
 170    </programlisting>
 171   </para>
 172
 173   <para>
 174    For the same table with an index to support an
 175    <firstterm>equijoin</firstterm> condition on the query,
 176    <command>EXPLAIN</command> will show a different plan:
 177
 178    <programlisting>
 179 EXPLAIN SELECT * FROM foo WHERE i = 4;
 180     <computeroutput>
 181 NOTICE:  QUERY PLAN:
 182
 183 Index Scan using fi on foo  (cost=0.00..0.42 rows=1 width=4)
 184
 185 EXPLAIN
 186     </computeroutput>
 187    </programlisting>
 188   </para>
 189
 190   <para>
 191    And finally, for the same table with an index to support an
 192    <firstterm>equijoin</firstterm> condition on the query,
 193    <command>EXPLAIN</command> will show the following for a query
 194    using an aggregate function:
 195
 196    <programlisting>
 197 EXPLAIN SELECT sum(i) FROM foo WHERE i = 4;
 198     <computeroutput>
 199 NOTICE:  QUERY PLAN:
 200
 201 Aggregate  (cost=0.42..0.42 rows=1 width=4)
 202   ->  Index Scan using fi on foo  (cost=0.00..0.42 rows=1 width=4)
 203     </computeroutput>
 204    </programlisting>
 205   </para>
 206
 207   <para>
 208    Note that the specific numbers shown, and even the selected query
 209    strategy, may vary between Postgres releases due to planner improvements.
 210   </para>
 211  </refsect1>
 212
 213  <refsect1 id="R1-SQL-EXPLAIN-3">
 214   <title>
 215    Compatibility
 216   </title>
 217
 218   <refsect2 id="R2-SQL-EXPLAIN-4">
 219    <refsect2info>
 220     <date>1998-09-01</date>
 221    </refsect2info>
 222    <title>
 223     SQL92
 224    </title>
 225    <para>
 226     There is no <command>EXPLAIN</command> statement defined in SQL92.
 227    </para>
 228   </refsect2>
 229  </refsect1>
 230 </refentry>
 231
 232 <!-- Keep this comment at the end of the file
 233 Local variables:
 234 mode: sgml
 235 sgml-omittag:nil
 236 sgml-shorttag:t
 237 sgml-minimize-attributes:nil
 238 sgml-always-quote-attributes:t
 239 sgml-indent-step:1
 240 sgml-indent-data:t
 241 sgml-parent-document:nil
 242 sgml-default-dtd-file:"../reference.ced"
 243 sgml-exposed-tags:nil
 244 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 245 sgml-local-ecat-files:nil
 246 End:
 247 -->