postgresql/doc/src/sgml/ref/explain.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.11 2000/10/05 19:48:18 momjian Exp $
Postgres documentation
-->

<refentry id="SQL-EXPLAIN">
 <refmeta>
  <refentrytitle id="SQL-EXPLAIN-TITLE">
   EXPLAIN
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   EXPLAIN
  </refname>
  <refpurpose>
   Shows statement execution plan
  </refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
EXPLAIN [ VERBOSE ] <replaceable class="PARAMETER">query</replaceable>        
  </synopsis>

  <refsect2 id="R2-SQL-EXPLAIN-1">
   <refsect2info>
    <date>1998-09-01</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term>VERBOSE</term>
      <listitem>
       <para>
	Flag to show detailed query plan.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">query</replaceable></term>
      <listitem>
       <para>
	Any <replaceable class="PARAMETER">query</replaceable>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-EXPLAIN-2">
   <refsect2info>
    <date>1998-04-15</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
NOTICE:  QUERY PLAN:
<replaceable>plan</replaceable>
      </computeroutput></term>
      <listitem>
       <para>
	Explicit query plan from the <productname>Postgres</productname> backend.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
EXPLAIN
       </computeroutput></term>
      <listitem>
       <para>
	Flag sent after query plan is shown.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-EXPLAIN-1">
  <refsect1info>
   <date>1998-04-15</date>
  </refsect1info>
  <title>
   Description
  </title>

  <para>
   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 start-up 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 start-up 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">
   <refsect2info>
    <date>1998-04-15</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    There is only sparse documentation on the optimizer's use of cost
    information in <productname>Postgres</productname>.
    General information on cost estimation for query optimization
    can be found in database textbooks.
    Refer to the <citetitle>Programmer's Guide</citetitle>
    in the chapters on indexes and the genetic query optimizer for
    more information.
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-EXPLAIN-2">
  <title>
   Usage
  </title>

  <para>
   To show a query plan for a simple query on a table with a single
   <type>int4</type> column and 128 rows:

   <programlisting>
EXPLAIN SELECT * FROM foo;
    <computeroutput>
NOTICE:  QUERY PLAN:

Seq Scan on foo  (cost=0.00..2.28 rows=128 width=4)

EXPLAIN
    </computeroutput>
   </programlisting>
  </para>

  <para>
   For the same table with an index to support an
   <firstterm>equijoin</firstterm> condition on the query,
   <command>EXPLAIN</command> will show a different plan:

   <programlisting>
EXPLAIN SELECT * FROM foo WHERE i = 4;
    <computeroutput>
NOTICE:  QUERY PLAN:

Index Scan using fi on foo  (cost=0.00..0.42 rows=1 width=4)

EXPLAIN
    </computeroutput>
   </programlisting>
  </para>

  <para>
   And finally, for the same table with an index to support an
   <firstterm>equijoin</firstterm> condition on the query,
   <command>EXPLAIN</command> will show the following for a query
   using an aggregate function:

   <programlisting>
EXPLAIN SELECT sum(i) FROM foo WHERE i = 4;
    <computeroutput>
NOTICE:  QUERY PLAN:

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">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-EXPLAIN-4">
   <refsect2info>
    <date>1998-09-01</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>EXPLAIN</command> statement defined in SQL92.
   </para>
  </refsect2>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->