head	1.51;
access;
symbols
	REL9_0_0:1.50.2.1
	REL9_1_ALPHA1:1.51
	REL9_0_RC1:1.50.2.1
	REL9_0_BETA4:1.50
	REL9_0_STABLE:1.50.0.2
	REL9_0_BETA3:1.50
	REL9_0_BETA2:1.50
	REL7_4_29:1.31
	REL8_0_25:1.35
	REL8_1_21:1.35.6.1
	REL8_2_17:1.38
	REL8_3_11:1.41
	REL8_4_4:1.44
	REL9_0_BETA1:1.50
	REL9_0_ALPHA5_BRANCH:1.49.0.4
	REL9_0_ALPHA5:1.49
	REL7_4_28:1.31
	REL8_0_24:1.35
	REL8_1_20:1.35.6.1
	REL8_2_16:1.38
	REL8_3_10:1.41
	REL8_4_3:1.44
	REL9_0_ALPHA4:1.49
	REL9_0_ALPHA4_BRANCH:1.49.0.2
	REL8_5_ALPHA3:1.48
	REL8_5_ALPHA3_BRANCH:1.48.0.2
	REL7_4_27:1.31
	REL8_0_23:1.35
	REL8_1_19:1.35.6.1
	REL8_2_15:1.38
	REL8_3_9:1.41
	REL8_4_2:1.44
	REL8_5_ALPHA2:1.46
	REL8_5_ALPHA2_BRANCH:1.46.0.4
	REL7_4_26:1.31
	REL8_0_22:1.35
	REL8_1_18:1.35.6.1
	REL8_2_14:1.38
	REL8_3_8:1.41
	REL8_4_1:1.44
	REL8_5_ALPHA1:1.46
	REL8_5_ALPHA1_BRANCH:1.46.0.2
	REL8_4_STABLE:1.44.0.2
	REL8_4_0:1.44
	REL8_4_RC2:1.44
	REL8_4_RC1:1.44
	REL8_4_BETA2:1.44
	REL8_4_BETA1:1.44
	REL7_4_25:1.31
	REL8_0_21:1.35
	REL8_1_17:1.35.6.1
	REL8_2_13:1.38
	REL8_3_7:1.41
	REL7_4_24:1.31
	REL8_0_20:1.35
	REL8_1_16:1.35.6.1
	REL8_2_12:1.38
	REL8_3_6:1.41
	REL7_4_23:1.31
	REL8_0_19:1.35
	REL8_1_15:1.35.6.1
	REL8_2_11:1.38
	REL8_3_5:1.41
	REL7_4_22:1.31
	REL8_0_18:1.35
	REL8_1_14:1.35.6.1
	REL8_2_10:1.38
	REL8_3_4:1.41
	REL7_4_21:1.31
	REL8_0_17:1.35
	REL8_1_13:1.35.6.1
	REL8_2_9:1.38
	REL8_3_3:1.41
	REL7_4_20:1.31
	REL8_0_16:1.35
	REL8_1_12:1.35.6.1
	REL8_2_8:1.38
	REL8_3_2:1.41
	REL8_2_7:1.38
	REL8_3_1:1.41
	REL8_3_STABLE:1.41.0.2
	REL8_3_0:1.41
	REL8_3_RC2:1.41
	REL7_3_21:1.20
	REL7_4_19:1.31
	REL8_0_15:1.35
	REL8_1_11:1.35.6.1
	REL8_2_6:1.38
	REL8_3_RC1:1.41
	REL8_3_BETA4:1.41
	REL8_3_BETA3:1.40
	REL8_3_BETA2:1.40
	REL8_3_BETA1:1.40
	REL7_3_20:1.20
	REL7_4_18:1.31
	REL8_0_14:1.35
	REL8_1_10:1.35.6.1
	REL8_2_5:1.38
	REL7_3_19:1.20
	REL7_4_17:1.31
	REL8_0_13:1.35
	REL8_1_9:1.35.6.1
	REL8_2_4:1.38
	REL8_0_12:1.35
	REL8_1_8:1.35.6.1
	REL8_2_3:1.38
	REL7_3_18:1.20
	REL7_4_16:1.31
	REL8_0_11:1.35
	REL8_1_7:1.35.6.1
	REL8_2_2:1.38
	REL8_0_10:1.35
	REL8_1_6:1.35.6.1
	REL8_2_1:1.38
	REL7_4_15:1.31
	REL7_3_17:1.20
	REL8_2_STABLE:1.38.0.2
	REL8_2_0:1.38
	REL8_2_RC1:1.38
	REL8_2_BETA3:1.38
	REL8_2_BETA2:1.38
	REL8_1_5:1.35.6.1
	REL8_0_9:1.35
	REL7_4_14:1.31
	REL7_3_16:1.20
	REL8_2_BETA1:1.38
	REL7_3_15:1.20
	REL7_4_13:1.31
	REL8_0_8:1.35
	REL8_1_4:1.35.6.1
	REL7_3_14:1.20
	REL7_4_12:1.31
	REL8_0_7:1.35
	REL8_1_3:1.35.6.1
	REL7_3_13:1.20
	REL7_4_11:1.31
	REL8_0_6:1.35
	REL8_1_2:1.35
	REL7_3_12:1.20
	REL7_4_10:1.31
	REL8_0_5:1.35
	REL8_1_1:1.35
	REL8_1_STABLE:1.35.0.6
	REL8_1_0:1.35
	REL8_1_0RC1:1.35
	REL8_1_0BETA4:1.35
	REL8_1_0BETA3:1.35
	REL7_3_11:1.20
	REL7_4_9:1.31
	REL8_0_4:1.35
	REL8_1_0BETA2:1.35
	REL8_1_0BETA1:1.35
	REL7_2_8:1.14
	REL7_3_10:1.20
	REL7_4_8:1.31
	REL8_0_3:1.35
	REL8_0_2:1.35
	REL7_2_7:1.14
	REL7_3_9:1.20
	REL7_4_7:1.31
	REL8_0_1:1.35
	REL8_0_STABLE:1.35.0.4
	REL8_0_0:1.35.0.2
	REL8_0_0RC5:1.35
	REL8_0_0RC4:1.35
	REL8_0_0RC3:1.34
	REL8_0_0RC2:1.34
	REL8_0_0RC1:1.34
	REL8_0_0BETA5:1.34
	REL8_0_0BETA4:1.34
	REL7_4_6:1.31
	REL7_3_8:1.20
	REL7_2_6:1.14
	REL8_0_0BETA3:1.33
	REL8_0_0BETA2:1.33
	REL7_2_5:1.14
	REL7_4_5:1.31
	REL7_3_7:1.20
	REL7_4_4:1.31
	REL8_0_0BETA1:1.33
	REL7_4_3:1.31
	REL7_4_2:1.31
	REL7_3_6:1.20
	REL7_4_1:1.31
	REL7_3_5:1.20
	REL7_4:1.31
	REL7_4_RC2:1.31
	REL7_4_STABLE:1.31.0.2
	REL7_4_RC1:1.31
	REL7_4_BETA5:1.31
	REL7_4_BETA4:1.30
	REL7_4_BETA3:1.30
	REL7_4_BETA2:1.26
	WIN32_DEV:1.26.0.2
	REL7_4_BETA1:1.26
	REL7_3_4:1.20
	REL7_3_2:1.20
	REL7_2_4:1.14
	REL7_3_STABLE:1.20.0.2
	REL7_2_3:1.14
	REL7_2_STABLE:1.14.0.2
	REL7_2:1.14
	REL7_2_RC2:1.14
	REL7_2_RC1:1.14
	REL7_2_BETA5:1.14
	REL7_2_BETA4:1.14
	REL7_2_BETA3:1.13
	REL7_2_BETA2:1.13
	REL7_2_BETA1:1.13
	REL7_1_2:1.11
	REL7_1_STABLE:1.11.0.2
	REL7_1_BETA:1.11
	REL7_1_BETA3:1.11
	REL7_1_BETA2:1.11
	REL7_1:1.11
	REL7_0_PATCHES:1.9.0.2
	REL7_0:1.9
	REL6_5_PATCHES:1.7.0.2
	REL6_5:1.7
	REL6_4:1.4.0.2;
locks; strict;
comment	@# @;


1.51
date	2010.08.03.17.14.19;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2010.04.03.07.23.01;	author petere;	state Exp;
branches
	1.50.2.1;
next	1.49;

1.49
date	2010.02.17.04.19.39;	author tgl;	state Exp;
branches;
next	1.48;

1.48
date	2009.12.15.04.57.47;	author rhaas;	state Exp;
branches;
next	1.47;

1.47
date	2009.12.11.01.33.35;	author adunstan;	state Exp;
branches;
next	1.46;

1.46
date	2009.08.10.05.46.50;	author tgl;	state Exp;
branches;
next	1.45;

1.45
date	2009.07.26.23.34.17;	author tgl;	state Exp;
branches;
next	1.44;

1.44
date	2008.11.14.10.22.47;	author petere;	state Exp;
branches;
next	1.43;

1.43
date	2008.10.27.08.47.13;	author petere;	state Exp;
branches;
next	1.42;

1.42
date	2008.04.18.01.42.17;	author tgl;	state Exp;
branches;
next	1.41;

1.41
date	2007.11.28.15.42.31;	author petere;	state Exp;
branches;
next	1.40;

1.40
date	2007.04.12.22.39.21;	author neilc;	state Exp;
branches;
next	1.39;

1.39
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2006.09.18.19.54.01;	author tgl;	state Exp;
branches;
next	1.37;

1.37
date	2006.09.16.00.30.18;	author momjian;	state Exp;
branches;
next	1.36;

1.36
date	2006.01.20.16.41.55;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches
	1.35.6.1;
next	1.34;

1.34
date	2004.09.30.04.23.27;	author neilc;	state Exp;
branches;
next	1.33;

1.33
date	2004.03.09.16.57.47;	author neilc;	state Exp;
branches;
next	1.32;

1.32
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.31;

1.31
date	2003.10.17.01.14.26;	author tgl;	state Exp;
branches;
next	1.30;

1.30
date	2003.09.12.00.12.47;	author tgl;	state Exp;
branches;
next	1.29;

1.29
date	2003.09.09.18.28.53;	author tgl;	state Exp;
branches;
next	1.28;

1.28
date	2003.09.08.22.33.13;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2003.08.31.17.32.23;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2003.04.26.23.56.51;	author petere;	state Exp;
branches
	1.26.2.1;
next	1.25;

1.25
date	2003.03.25.16.15.41;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2003.03.10.03.53.49;	author tgl;	state Exp;
branches;
next	1.23;

1.23
date	2003.02.02.23.46.37;	author tgl;	state Exp;
branches;
next	1.22;

1.22
date	2003.01.19.00.13.29;	author momjian;	state Exp;
branches;
next	1.21;

1.21
date	2002.11.15.03.11.18;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.19;

1.19
date	2002.03.24.17.11.37;	author tgl;	state Exp;
branches;
next	1.18;

1.18
date	2002.03.24.16.57.29;	author tgl;	state Exp;
branches;
next	1.17;

1.17
date	2002.03.24.04.31.07;	author tgl;	state Exp;
branches;
next	1.16;

1.16
date	2002.03.22.19.20.40;	author petere;	state Exp;
branches;
next	1.15;

1.15
date	2002.03.06.06.48.04;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2001.12.08.03.24.36;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	2001.09.18.01.59.05;	author tgl;	state Exp;
branches;
next	1.12;

1.12
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.11;

1.11
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	2000.08.29.20.02.09;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	2000.02.15.23.37.49;	author tgl;	state Exp;
branches;
next	1.8;

1.8
date	99.07.22.15.09.12;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	99.07.06.17.16.38;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	99.04.23.21.23.48;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	98.12.29.02.24.42;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.10.30.19.34.21;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.10.15.05.47.00;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	98.09.25.13.42.29;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.09.05.06.02.55;	author thomas;	state Exp;
branches;
next	;

1.26.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;

1.35.6.1
date	2006.01.20.16.42.02;	author momjian;	state Exp;
branches;
next	;

1.50.2.1
date	2010.08.09.23.49.33;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.51
log
@Add EXPLAIN documentation example.

gabrielle <gorthx@@gmail.com>
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.50 2010/04/03 07:23:01 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-EXPLAIN">
 <refmeta>
  <refentrytitle>EXPLAIN</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>EXPLAIN</refname>
  <refpurpose>show the execution plan of a statement</refpurpose>
 </refnamediv>

 <indexterm zone="sql-explain">
  <primary>EXPLAIN</primary>
 </indexterm>

 <indexterm zone="sql-explain">
  <primary>prepared statements</primary>
  <secondary>showing the query plan</secondary>
 </indexterm>

 <indexterm zone="sql-explain">
  <primary>cursor</primary>
  <secondary>showing the query plan</secondary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
EXPLAIN [ ( { ANALYZE <replaceable class="parameter">boolean</replaceable> | VERBOSE <replaceable class="parameter">boolean</replaceable> | COSTS <replaceable class="parameter">boolean</replaceable> | BUFFERS <replaceable class="parameter">boolean</replaceable> | FORMAT { TEXT | XML | JSON | YAML } } [, ...] ) ] <replaceable class="parameter">statement</replaceable>
EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   This command displays the execution plan that the
   <productname>PostgreSQL</productname> planner generates for the
   supplied statement.  The execution plan shows how the table(s)
   referenced by the statement will be scanned &mdash; by plain sequential scan,
   index scan, etc. &mdash; and if multiple tables are referenced, what join
   algorithms will be used to bring together the required rows from
   each input table.
  </para>

  <para>
   The most critical part of the display is the estimated statement execution
   cost, which is the planner's guess at how long it will take to run the
   statement (measured in units of disk page fetches).  Actually two numbers
   are shown: the start-up time before the first row can be returned, and
   the total time to return all the rows.  For most queries the total time
   is what matters, but in contexts such as a subquery in <literal>EXISTS</literal>, the planner
   will choose the smallest start-up time instead of the smallest total time
   (since the executor will stop after getting one row, anyway).
   Also, if you limit the number of rows to return with a <literal>LIMIT</literal> clause,
   the planner makes an appropriate interpolation between the endpoint
   costs to estimate which plan is really the cheapest.
  </para>

  <para>
   The <literal>ANALYZE</literal> option causes the statement to be actually executed, not only
   planned.  The total elapsed time expended within each plan node (in
   milliseconds) and total number of rows it actually returned are added to
   the display.  This is useful for seeing whether the planner's estimates
   are close to reality.
  </para>

  <important>
   <para>
    Keep in mind that the statement is actually executed when
    the <literal>ANALYZE</literal> option is used.  Although
    <command>EXPLAIN</command> will discard any output that a
    <command>SELECT</command> would return, other side effects of the
    statement will happen as usual.  If you wish to use
    <command>EXPLAIN ANALYZE</command> on an
    <command>INSERT</command>, <command>UPDATE</command>,
    <command>DELETE</command>, <command>CREATE TABLE AS</command>,
    or <command>EXECUTE</command> statement
    without letting the command affect your data, use this approach:
<programlisting>
BEGIN;
EXPLAIN ANALYZE ...;
ROLLBACK;
</programlisting>
   </para>
  </important>

  <para>
   Only the <literal>ANALYZE</literal> and <literal>VERBOSE</literal> options
   can be specified, and only in that order, without surrounding the option
   list in parentheses.  Prior to <productname>PostgreSQL</productname> 9.0,
   the unparenthesized syntax was the only one supported.  It is expected that
   all new options will be supported only in the parenthesized syntax.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><literal>ANALYZE</literal></term>
    <listitem>
     <para>
      Carry out the command and show the actual run times.  This
      parameter defaults to <literal>FALSE</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>VERBOSE</literal></term>
    <listitem>
     <para>
      Display additional information regarding the plan.  Specifically, include
      the output column list for each node in the plan tree, schema-qualify
      table and function names, always label variables in expressions with
      their range table alias, and always print the name of each trigger for
      which statistics are displayed.  This parameter defaults to
      <literal>FALSE</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>COSTS</literal></term>
    <listitem>
     <para>
      Include information on the estimated startup and total cost of each
      plan node, as well as the estimated number of rows and the estimated
      width of each row.  This parameter defaults to <literal>TRUE</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>BUFFERS</literal></term>
    <listitem>
     <para>
      Include information on buffer usage. Specifically, include the number of
      shared blocks hits, reads, and writes, the number of local blocks hits,
      reads, and writes, and the number of temp blocks reads and writes.
      Shared blocks, local blocks, and temp blocks contain tables and indexes,
      temporary tables and temporary indexes, and disk blocks used in sort and
      materialized plans, respectively. The number of blocks shown for an
      upper-level node includes those used by all its child nodes.  In text
      format, only non-zero values are printed.  This parameter may only be
      used with <literal>ANALYZE</literal> parameter.  It defaults to
      <literal>FALSE</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>FORMAT</literal></term>
    <listitem>
     <para>
      Specify the output format, which can be TEXT, XML, JSON, or YAML.
      Non-text output contains the same information as the text output
      format, but is easier for programs to parse.  This parameter defaults to
      <literal>TEXT</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">boolean</replaceable></term>
    <listitem>
     <para>
      Specifies whether the selected option should be turned on or off.
      You can write <literal>TRUE</literal>, <literal>ON</>, or
      <literal>1</literal> to enable the option, and <literal>FALSE</literal>,
      <literal>OFF</>, or <literal>0</literal> to disable it.  The
      <replaceable class="parameter">boolean</replaceable> value can also
      be omitted, in which case <literal>TRUE</literal> is assumed.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">statement</replaceable></term>
    <listitem>
     <para>
      Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
      <command>DELETE</>, <command>VALUES</>, <command>EXECUTE</>,
      <command>DECLARE</>, or <command>CREATE TABLE AS</command>
      statement, whose execution plan you wish to see.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   There is only sparse documentation on the optimizer's use of cost
   information in <productname>PostgreSQL</productname>.  Refer to
   <xref linkend="using-explain"> for more information.
  </para>

  <para>
   In order to allow the <productname>PostgreSQL</productname> query
   planner to make reasonably informed decisions when optimizing
   queries, the <xref linkend="sql-analyze">
   statement should be run to record statistics about the distribution
   of data within the table. If you have not done this (or if the
   statistical distribution of the data in the table has changed
   significantly since the last time <command>ANALYZE</command> was
   run), the estimated costs are unlikely to conform to the real
   properties of the query, and consequently an inferior query plan
   might be chosen.
  </para>

  <para>
   In order to measure the run-time cost of each node in the execution
   plan, the current implementation of <command>EXPLAIN
   ANALYZE</command> can add considerable profiling overhead to query
   execution. As a result, running <command>EXPLAIN ANALYZE</command>
   on a query can sometimes take significantly longer than executing
   the query normally. The amount of overhead depends on the nature of
   the query.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

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

<programlisting>
EXPLAIN SELECT * FROM foo;

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

  <para>
  Here is the same query, with JSON formatting:
<programlisting>
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)
</programlisting>
  </para>

  <para>
   If there is an index and we use a query with an indexable
   <literal>WHERE</literal> condition, <command>EXPLAIN</command>
   might show a different plan:

<programlisting>
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)
</programlisting>
  </para>

  <para>
  Here is the same query, but in YAML output:
<programlisting>
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)
</programlisting>

    XML output is left as an exercise to the reader.
  </para>
  <para>
   Here is the same plan with costs suppressed:

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

        QUERY PLAN
----------------------------
 Index Scan using fi on foo
   Index Cond: (i = 4)
(2 rows)
</programlisting>
  </para>

  <para>
   Here is an example of a query plan for a query using an aggregate
   function:

<programlisting>
EXPLAIN SELECT sum(i) FROM foo WHERE i &lt; 10;

                             QUERY PLAN
---------------------------------------------------------------------
 Aggregate  (cost=23.93..23.93 rows=1 width=4)
   -&gt;  Index Scan using fi on foo  (cost=0.00..23.92 rows=6 width=4)
         Index Cond: (i &lt; 10)
(3 rows)
</programlisting>
  </para>

  <para>
   Here is an example of using <command>EXPLAIN EXECUTE</command> to
   display the execution plan for a prepared query:

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

EXPLAIN ANALYZE EXECUTE query(100, 200);

                                                       QUERY PLAN                                                        
-------------------------------------------------------------------------------------------------------------------------
 HashAggregate  (cost=39.53..39.53 rows=1 width=8) (actual time=0.661..0.672 rows=7 loops=1)
   -&gt;  Index Scan using test_pkey on test  (cost=0.00..32.97 rows=1311 width=8) (actual time=0.050..0.395 rows=99 loops=1)
         Index Cond: ((id &gt; $1) AND (id &lt; $2))
 Total runtime: 0.851 ms
(4 rows)
</programlisting>
  </para>

  <para>
   Of course, the specific numbers shown here depend on the actual
   contents of the tables involved.  Also note that the numbers, and
   even the selected query strategy, might vary between
   <productname>PostgreSQL</productname> releases due to planner
   improvements. In addition, the <command>ANALYZE</command> command
   uses random sampling to estimate data statistics; therefore, it is
   possible for cost estimates to change after a fresh run of
   <command>ANALYZE</command>, even if the actual distribution of data
   in the table has not changed.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   There is no <command>EXPLAIN</command> statement defined in the SQL standard.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-analyze"></member>
  </simplelist>
 </refsect1>
</refentry>
@


1.50
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.49 2010/02/17 04:19:39 tgl Exp $
d251 23
d290 22
@


1.50.2.1
log
@Add EXPLAIN documentation example.

gabrielle <gorthx@@gmail.com>

Backpatch to 9.0.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.51 2010/08/03 17:14:19 momjian Exp $
a250 23
  Here is the same query, with JSON formatting:
<programlisting>
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)
</programlisting>
  </para>

  <para>
a266 22
  Here is the same query, but in YAML output:
<programlisting>
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)
</programlisting>

    XML output is left as an exercise to the reader.
  </para>
  <para>
@


1.49
log
@Stamp HEAD as 9.0devel, and update various places that were referring to 8.5
(hope I got 'em all).  Per discussion, this release will be 9.0 not 8.5.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.48 2009/12/15 04:57:47 rhaas Exp $
d8 1
a8 1
  <refentrytitle id="SQL-EXPLAIN-TITLE">EXPLAIN</refentrytitle>
d212 1
a212 1
   queries, the <xref linkend="sql-analyze" endterm="sql-analyze-title">
d342 1
a342 1
   <member><xref linkend="sql-analyze" endterm="sql-analyze-title"></member>
@


1.48
log
@Add an EXPLAIN (BUFFERS) option to show buffer-usage statistics.

This patch also removes buffer-usage statistics from the track_counts
output, since this (or the global server statistics) is deemed to be a better
interface to this information.

Itagaki Takahiro, reviewed by Euler Taveira de Oliveira.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.47 2009/12/11 01:33:35 adunstan Exp $
d97 1
a97 1
   list in parentheses.  Prior to <productname>PostgreSQL</productname> 8.5,
@


1.47
log
@Add YAML to list of EXPLAIN formats. Greg Sabino Mullane, reviewed by Takahiro Itagaki.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.46 2009/08/10 05:46:50 tgl Exp $
d34 1
a34 1
EXPLAIN [ ( { ANALYZE <replaceable class="parameter">boolean</replaceable> | VERBOSE <replaceable class="parameter">boolean</replaceable> | COSTS <replaceable class="parameter">boolean</replaceable> | FORMAT { TEXT | XML | JSON | YAML } } [, ...] ) ] <replaceable class="parameter">statement</replaceable>
d143 18
@


1.46
log
@Extend EXPLAIN to support output in XML or JSON format.

There are probably still some adjustments to be made in the details
of the output, but this gets the basic structure in place.

Robert Haas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.45 2009/07/26 23:34:17 tgl Exp $
d34 1
a34 1
EXPLAIN [ ( { ANALYZE <replaceable class="parameter">boolean</replaceable> | VERBOSE <replaceable class="parameter">boolean</replaceable> | COSTS <replaceable class="parameter">boolean</replaceable> | FORMAT { TEXT | XML | JSON } } [, ...] ) ] <replaceable class="parameter">statement</replaceable>
d146 2
a147 2
      Specify the output format, which can be TEXT, XML, or JSON.
      XML or JSON output contains the same information as the text output
@


1.45
log
@Extend EXPLAIN to allow generic options to be specified.

The original syntax made it difficult to add options without making them
into reserved words.  This change parenthesizes the options to avoid that
problem, and makes provision for an explicit (and perhaps non-Boolean)
value for each option.  The original syntax is still supported, but only
for the two original options ANALYZE and VERBOSE.

As a test case, add a COSTS option that can suppress the planner cost
estimates.  This may be useful for including EXPLAIN output in the regression
tests, which are otherwise unable to cope with cross-platform variations in
cost estimates.

Robert Haas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.44 2008/11/14 10:22:47 petere Exp $
d34 1
a34 1
EXPLAIN [ ( { ANALYZE <replaceable class="parameter">boolean</replaceable> | VERBOSE <replaceable class="parameter">boolean</replaceable> | COSTS <replaceable class="parameter">boolean</replaceable> } [, ...] ) ] <replaceable class="parameter">statement</replaceable>
d112 1
a112 1
      parameter defaults to <command>FALSE</command>.
d121 6
a126 2
      Include the output column list for each node in the plan tree.  This
      parameter defaults to <command>FALSE</command>.
d137 13
a149 1
      width of each row.  This parameter defaults to <command>TRUE</command>.
@


1.44
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.43 2008/10/27 08:47:13 petere Exp $
d34 1
d93 8
d111 2
a112 1
      Carry out the command and show the actual run times.
d121 27
a147 1
      Include the output column list for each node in the plan tree.
a188 8
   Genetic query optimization (<acronym>GEQO</acronym>) randomly tests
   execution plans.  Therefore, when the number of join relations
   exceeds <xref linkend="guc-geqo-threshold"> causing genetic query
   optimization to be used, the execution plan is likely to change
   each time the statement is executed.
  </para>

  <para>
d233 14
@


1.43
log
@Allow EXPLAIN on CREATE TABLE AS.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.42 2008/04/18 01:42:17 tgl Exp $
d9 1
@


1.42
log
@Cause EXPLAIN's VERBOSE option to print the target list (output column list)
of each plan node, instead of its former behavior of dumping the internal
representation of the plan tree.  The latter display is still available for
those who really want it (see debug_print_plan), but uses for it are certainly
few and and far between.  Per discussion.

This patch also removes the explain_pretty_print GUC, which is obsoleted
by the change.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.41 2007/11/28 15:42:31 petere Exp $
d81 2
a82 1
    <command>DELETE</command>, or <command>EXECUTE</command> statement
d120 3
a122 2
      <command>DELETE</>, <command>VALUES</>, <command>EXECUTE</>, or
      <command>DECLARE</> statement, whose execution plan you wish to see.
@


1.41
log
@spell checker run
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.40 2007/04/12 22:39:21 neilc Exp $
d109 1
a109 6
      Show the full internal representation of the plan tree, rather
      than just a summary.  Usually this option is only useful for
      specialized debugging purposes.  The
      <literal>VERBOSE</literal> output is either pretty-printed or
      not, depending on the setting of the <xref
      linkend="guc-explain-pretty-print"> configuration parameter.
@


1.40
log
@Minor fixes for the EXPLAIN reference page. Mention the fact that
EXPLAIN ANALYZE can sometimes be significantly slower than running
the same query normally, and make some minor markup improvements.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.39 2007/01/31 23:26:04 momjian Exp $
d163 1
a163 1
   In order to measure the runtime cost of each node in the execution
@


1.39
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.38 2006/09/18 19:54:01 tgl Exp $
d75 1
a75 1
    <literal>ANALYZE</literal> is used.  Although
d144 8
a151 7
   queries, the <command>ANALYZE</command> statement should be run to
   record statistics about the distribution of data within the
   table. If you have not done this (or if the statistical
   distribution of the data in the table has changed significantly
   since the last time <command>ANALYZE</command> was run), the
   estimated costs are unlikely to conform to the real properties of
   the query, and consequently an inferior query plan might be chosen.
d155 5
a159 5
   Genetic query optimization (<acronym>GEQO</acronym>) randomly 
   tests execution plans.  Therefore, when the number of tables exceeds
   <varname>geqo_threshold</> causing genetic query optimization to be 
   used, the execution plan is likely to change each time the statement
   is executed.
d162 9
d207 2
a208 2
   And here is an example of a query plan for a query
   using an aggregate function:
@


1.38
log
@Documentation for VALUES lists.  Joe Conway and Tom Lane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.37 2006/09/16 00:30:18 momjian Exp $
d150 1
a150 1
   the query, and consequently an inferior query plan may be chosen.
d236 1
a236 1
   even the selected query strategy, may vary between
@


1.37
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.36 2006/01/20 16:41:55 momjian Exp $
d124 2
a125 2
      <command>DELETE</>, <command>EXECUTE</>, or <command>DECLARE</>
      statement, whose execution plan you wish to see.
@


1.36
log
@Update EXPLAIN wording for GEQO usage.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
a261 17

<!-- 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:
-->
@


1.35
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.34 2004/09/30 04:23:27 neilc Exp $
d154 5
a158 4
   Prior to <productname>PostgreSQL</productname> 7.3, the plan was
   emitted in the form of a <literal>NOTICE</literal> message.  Now it
   appears as a query result (formatted like a table with a single
   text column).
d160 1
@


1.35.6.1
log
@Update EXPLAIN wording for GEQO usage.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
a153 8
   Genetic query optimization (<acronym>GEQO</acronym>) randomly 
   tests execution plans.  Therefore, when the number of tables exceeds
   <varname>geqo_threshold</> causing genetic query optimization to be 
   used, the execution plan is likely to change each time the statement
   is executed.
  </para>

  <para>
@


1.34
log
@Add more index entries for reference pages related to prepare queries.
From Alvaro Herrera, editorializing by Neil Conway.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.33 2004/03/09 16:57:47 neilc Exp $
d44 3
a46 3
   referenced by the statement 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 row from
d111 1
a111 1
      debugging <productname>PostgreSQL</productname>.  The
d251 8
@


1.33
log
@Refer to GUC variables using <xref> tags rather than <varname> tags,
where appropriate. Add "id" and "xreflabel" tags to the descriptions
of the GUC variables to facilitate this. Also make a few minor docs
cleanups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.32 2003/11/29 19:51:38 pgsql Exp $
d21 10
@


1.32
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.31 2003/10/17 01:14:26 tgl Exp $
d103 2
a104 2
      not, depending on the setting of the
      <varname>explain_pretty_print</varname> configuration parameter.
@


1.31
log
@Adjust display of actual runtimes in EXPLAIN output to use three fractional
digits, and label it 'ms' not 'msec', for consistency with psql's \timing
display.  Per recent discussions.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.30 2003/09/12 00:12:47 tgl Exp $
@


1.30
log
@More cleanup of Diagnostics sections.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.29 2003/09/09 18:28:53 tgl Exp $
d213 2
a214 2
 HashAggregate  (cost=39.53..39.53 rows=1 width=8) (actual time=0.66..0.67 rows=7 loops=1)
   -&gt;  Index Scan using test_pkey on test  (cost=0.00..32.97 rows=1311 width=8) (actual time=0.05..0.39 rows=99 loops=1)
d216 1
a216 1
 Total runtime: 0.85 msec
@


1.29
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.28 2003/09/08 22:33:13 tgl Exp $
d83 1
a83 1
  <title>Parameter</title>
@


1.28
log
@"statenebt" ?
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.27 2003/08/31 17:32:23 petere Exp $
a119 10
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <para>
   <command>EXPLAIN</command> prints the execution plan of the
   specified statement from the <productname>PostgreSQL</productname>
   planner.
  </para>
@


1.27
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.26 2003/04/26 23:56:51 petere Exp $
d33 1
a33 1
   supplied statenebt.  The execution plan shows how the table(s)
@


1.26
log
@Editing of more reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.25 2003/03/25 16:15:41 petere Exp $
d16 4
@


1.26.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.27 2003/08/31 17:32:23 petere Exp $
a15 4

 <indexterm zone="sql-explain">
  <primary>EXPLAIN</primary>
 </indexterm>
@


1.25
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.24 2003/03/10 03:53:49 tgl Exp $
d11 1
d13 2
a14 6
  <refname>
   EXPLAIN
  </refname>
  <refpurpose>
   show the execution plan of a statement
  </refpurpose>
d18 3
a20 78
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
EXPLAIN [ ANALYZE ] [ 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>ANALYZE</term>
      <listitem>
       <para>
	Flag to carry out the query and show actual run times.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>VERBOSE</term>
      <listitem>
       <para>
	Flag to show detailed query plan dump.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">query</replaceable></term>
      <listitem>
       <para>
	Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
	<command>DELETE</>, <command>EXECUTE</>,
	or <command>DECLARE CURSOR</> query.
       </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>Query plan</term>
      <listitem>
       <para>
	Explicit query plan from the <productname>PostgreSQL</productname>
	planner.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <note>
    <para>
     Prior to <productname>PostgreSQL</productname> 7.3, the query
     plan was emitted in the form of a <literal>NOTICE</literal>
     message.  Now it appears as a query result (formatted like a
     table with a single text column).
    </para>
   </note>
  </refsect2>
d23 2
a24 7
 <refsect1 id="R1-SQL-EXPLAIN-1">
  <refsect1info>
   <date>1998-04-15</date>
  </refsect1info>
  <title>
   Description
  </title>
d29 2
a30 2
   supplied query.  The execution plan shows how the table(s)
   referenced by the query will be scanned---by plain sequential scan,
d32 1
a32 1
   algorithms will be used to bring together the required tuples from
d37 1
a37 1
   The most critical part of the display is the estimated query execution
d39 4
a42 4
   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
d44 2
a45 2
   (since the executor will stop after getting one tuple, anyway).
   Also, if you limit the number of tuples to return with a LIMIT clause,
a49 14
  <note>
   <para>
    In order to allow the <productname>PostgreSQL</productname> query
    planner to make reasonably informed decisions when optimizing
    queries, the <command>ANALYZE</command> statement should be run
    to record statistics about the distribution of data within the
    table. If you have not done this (or if the statistical distribution
    of the data in the table has changed significantly since the last
    time <command>ANALYZE</command> was run), the estimated costs
    are unlikely to conform to the real properties of the query,
    and consequently an inferior query plan may be chosen.
   </para>
  </note>

d51 1
a51 1
   The ANALYZE option causes the query to be actually executed, not only
d58 1
a58 1
  <caution>
d60 10
a69 8
    Keep in mind that the query is actually executed when ANALYZE is used.
    Although <command>EXPLAIN</command> will discard any output that a SELECT
    would return,
    other side-effects of the query will happen as usual.
    If you wish to use <command>EXPLAIN ANALYZE</command> on an INSERT,
    UPDATE, DELETE, or EXECUTE query without letting the query affect your
    data, use this approach:
      <programlisting>
d73 1
a73 1
      </programlisting>
d75 61
a135 1
  </caution>
d138 17
a154 21
   The VERBOSE option emits the full internal representation of the plan tree,
   rather than just a summary.
   Usually this option is only useful for debugging
   <productname>PostgreSQL</productname>.   The VERBOSE dump is either
   pretty-printed or not, depending on the setting of the
   <option>EXPLAIN_PRETTY_PRINT</option> configuration parameter.
  </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>PostgreSQL</productname>.
    Refer to <xref linkend="using-explain"> for more information.
   </para>
  </refsect2>
d157 2
a158 4
 <refsect1 id="R1-SQL-EXPLAIN-2">
  <title>
   Usage
  </title>
d161 2
a162 2
   To show a query plan for a simple query on a table with a single
   <type>int4</type> column and 10000 rows:
d164 1
a164 1
   <programlisting>
d166 1
a166 1
    <computeroutput>
d171 1
a171 2
    </computeroutput>
   </programlisting>
d175 3
a177 2
   If there is an index and we use a query with an indexable WHERE condition,
   <command>EXPLAIN</command> will show a different plan:
d179 1
a179 1
   <programlisting>
d181 1
a181 1
    <computeroutput>
d187 1
a187 2
    </computeroutput>
   </programlisting>
d194 1
a194 1
   <programlisting>
d196 1
a196 1
    <computeroutput>
d203 1
a203 2
    </computeroutput>
   </programlisting>
d207 2
a208 2
   Here is an example of using EXPLAIN EXECUTE to display the query
   plan for a prepared query:
d210 1
a210 1
   <programlisting>
d216 1
a216 1
    <computeroutput>
d224 1
a224 2
    </computeroutput>
   </programlisting>
d228 7
a234 6
   Note that the specific numbers shown, and even the selected query
   strategy, may vary between <productname>PostgreSQL</productname>
   releases due to planner improvements. In addition, the
   <command>ANALYZE</command> command uses random sampling to estimate
   data statistics; therefore, it is possible
   for cost estimates to change after a fresh run of
d240 6
a245 16
 <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>
@


1.24
log
@Restructure parsetree representation of DECLARE CURSOR: now it's a
utility statement (DeclareCursorStmt) with a SELECT query dangling from
it, rather than a SELECT query with a few unusual fields in it.  Add
code to determine whether a planned query can safely be run backwards.
If DECLARE CURSOR specifies SCROLL, ensure that the plan can be run
backwards by adding a Materialize plan node if it can't.  Without SCROLL,
you get an error if you try to fetch backwards from a cursor that can't
handle it.  (There is still some discussion about what the exact
behavior should be, but this is necessary infrastructure in any case.)
Along the way, make EXPLAIN DECLARE CURSOR work.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.23 2003/02/02 23:46:37 tgl Exp $
d191 1
a191 1
    Refer to the &cite-user; and &cite-programmer; for more information.
@


1.23
log
@Implement EXPLAIN EXECUTE.  By Neil Conway, with some kibitzing from
Tom Lane.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.22 2003/01/19 00:13:29 momjian Exp $
d59 2
a60 1
	<command>DELETE</>, or <command>EXECUTE</> query.
@


1.22
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.21 2002/11/15 03:11:18 momjian Exp $
d58 2
a59 1
	Any <replaceable class="PARAMETER">query</replaceable>.
d136 1
a136 1
    queries, the <command>ANALYZE</command> statement should be used
d138 1
a138 1
    table. If you have not done this (or the statistical distribution
d140 3
a142 3
    time <command>ANALYZE</command> was run), the estimated costs and
    the resulting query plan displayed by <command>EXPLAIN</command>
    are unlikely to conform to the real properties of the query.
d151 1
a151 1
   are close to the actual performance of the query.
d161 2
a162 2
    UPDATE, or DELETE query without letting the query affect your data,
    use this approach:
d249 22
d273 4
a276 4
   releases due to planner improvements. In addition, the algorithm
   used by <command>ANALYZE</command> to generate statistics is not
   completely deterministic; therefore, it is possible (although not
   likely) for cost estimations to change between runs of
@


1.21
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/explain.sgml,v 1.20 2002/04/21 19:02:39 thomas Exp $
d90 4
a93 3
     Prior to <productname>PostgreSQL</productname> 7.3, the query plan
     was emitted in the form of a NOTICE message.  Now it appears as a
     query result (formatted like a table with a single text column).
d131 14
d150 1
a150 1
   are close to reality.
d189 1
a189 2
    Refer to the <citetitle>User's Guide</citetitle> and
    <citetitle>Programmer's Guide</citetitle> for more information.
d250 6
a255 1
   releases due to planner improvements.
@


1.20
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.19 2002/03/24 17:11:37 tgl Exp $
d90 1
a90 1
     Prior to <application>PostgreSQL</application> 7.3, the query plan
d108 6
a113 6
   <application>PostgreSQL</application> 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.
d159 1
a159 1
   <application>PostgreSQL</application>.   The VERBOSE dump is either
d235 1
a235 1
   strategy, may vary between <application>PostgreSQL</application>
@


1.19
log
@Tweak labeling of plan qual conditions for more consistency.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.18 2002/03/24 16:57:29 tgl Exp $
d8 1
a8 3
  <refentrytitle id="SQL-EXPLAIN-TITLE">
   EXPLAIN
  </refentrytitle>
@


1.18
log
@Fix cut-and-paste-o.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.17 2002/03/24 04:31:07 tgl Exp $
d212 1
a212 1
   Index Filter: (i = 4)
d229 1
a229 1
         Index Filter: (i &lt; 10)
@


1.17
log
@EXPLAIN output now comes out as a query result, not a NOTICE message.
Also, fix debug logging of parse/plan trees so that the messages actually
go through elog(), not directly to stdout.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.16 2002/03/22 19:20:40 petere Exp $
d223 1
a223 1
EXPLAIN SELECT sum(i) FROM foo WHERE i < 4;
d228 2
a229 2
   ->  Index Scan using fi on foo  (cost=0.00..23.92 rows=6 width=4)
         Index Filter: (i < 10)
@


1.16
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.15 2002/03/06 06:48:04 momjian Exp $
d52 1
a52 1
	Flag to show detailed query plan.
d79 1
a79 4
      <term><computeroutput>
INFO:  QUERY PLAN:
<replaceable>plan</replaceable>
      </computeroutput></term>
d82 2
a83 11
	Explicit query plan from the <productname>PostgreSQL</productname> backend.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
EXPLAIN
       </computeroutput></term>
      <listitem>
       <para>
	Flag sent after query plan is shown.
d89 8
a139 7
  <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
   <application>PostgreSQL</application>. 
  </para>

d157 9
d189 1
a189 1
   <type>int4</type> column and 128 rows:
d194 4
a197 5
INFO:  QUERY PLAN:

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

EXPLAIN
d203 1
a203 2
   For the same table with an index to support an
   <firstterm>equijoin</firstterm> condition on the query,
d209 5
a213 5
INFO:  QUERY PLAN:

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

EXPLAIN
d219 1
a219 3
   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
d223 1
a223 1
EXPLAIN SELECT sum(i) FROM foo WHERE i = 4;
d225 6
a230 4
INFO:  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)
@


1.15
log
@Update reference pages for new INFO, NOTICE, WARNING elog() levels.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.14 2001/12/08 03:24:36 thomas Exp $
d44 1
a44 1
	Flag to carry out the query and show actual runtimes.
@


1.14
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.13 2001/09/18 01:59:05 tgl Exp $
d80 1
a80 1
NOTICE:  QUERY PLAN:
d196 1
a196 1
NOTICE:  QUERY PLAN:
d213 1
a213 1
NOTICE:  QUERY PLAN:
d231 1
a231 1
NOTICE:  QUERY PLAN:
@


1.13
log
@EXPLAIN ANALYZE feature to measure and show actual runtimes and tuple
counts alongside the planner's estimates.  By Martijn van Oosterhout,
with some further work by Tom Lane.
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.12 2001/09/03 12:57:50 petere Exp $
Postgres documentation
d85 1
a85 1
	Explicit query plan from the <productname>Postgres</productname> backend.
d113 2
a114 1
   This command displays the execution plan that the Postgres planner
d147 2
a148 1
   Usually this option is only useful for debugging Postgres.
d177 1
a177 1
    information in <productname>Postgres</productname>.
d241 2
a242 1
   strategy, may vary between Postgres releases due to planner improvements.
@


1.12
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.11 2000/10/05 19:48:18 momjian Exp $
d27 1
a27 1
EXPLAIN [ VERBOSE ] <replaceable class="PARAMETER">query</replaceable>        
d41 8
d136 8
d149 17
d176 2
a177 5
    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.
@


1.11
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.10 2000/08/29 20:02:09 momjian Exp $
d18 1
a18 1
   Shows statement execution plan
@


1.10
log
@Startup is actually start-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.9 2000/02/15 23:37:49 tgl Exp $
d107 2
a108 2
   the table(s) referenced by the query will be scanned --- by plain
   sequential scan, index scan etc --- and if multiple tables are
@


1.9
log
@Update EXPLAIN documentation to reflect the fact that the
planner now produces two cost numbers instead of one.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.8 1999/07/22 15:09:12 thomas Exp $
d117 1
a117 1
   are shown: the startup time before the first tuple can be returned, and
d120 1
a120 1
   will choose the smallest startup time instead of the smallest total time
@


1.8
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d18 1
a18 1
   Shows statement execution details
d105 26
a130 6
   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.   
d166 1
a166 1
Seq Scan on foo  (cost=5.22 rows=128 width=4)
d183 1
a183 1
Index Scan using fi on foo  (cost=2.05 rows=1 width=4)
d201 2
a202 2
Aggregate  (cost=2.05 rows=1 width=4)
  ->  Index Scan using fi on foo  (cost=2.05 rows=1 width=4)
d205 5
@


1.7
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d24 1
a24 1
   <date>1998-09-01</date>
d103 1
d136 1
d138 2
a139 1
   To show a query plan for a simple query:
d142 2
a143 1
EXPLAIN select * from foo;
d146 1
a146 1
Seq Scan on foo  (cost=0.00 rows=0 width=4)
d149 35
a191 2
  <para>
  </para>
@


1.6
log
@Rename explain's "size" to "rows".
@
text
@d1 66
a66 70
<REFENTRY ID="SQL-EXPLAIN">
<REFMETA>
<REFENTRYTITLE>
EXPLAIN
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
EXPLAIN
</REFNAME>
<REFPURPOSE>
Shows statement execution details
</REFPURPOSE>
</refnamediv>

<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</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>
d69 9
a77 9
</TERM>
<LISTITEM>
<PARA>
Explicit query plan from the <productname>Postgres</productname> backend.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
d79 20
a98 20
</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>
d105 27
a131 26
</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:
d133 2
a134 2
<ProgramListing>
postgres=> explain select * from foo;
d140 40
a179 43
</ProgramListing>
</para>
</REFSECT1>

<REFSECT1 ID="R1-SQL-EXPLAIN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>

<REFSECT2 ID="R2-SQL-EXPLAIN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
   There is no EXPLAIN statement defined in SQL92.
</para>
</refsect2>
</refsect1>
</REFENTRY>

<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
@


1.5
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d105 2
d140 1
a140 1
Seq Scan on foo  (cost=0.00 size=0 width=4)
@


1.4
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
d42 3
a44 1

d52 3
a54 1

d56 1
a56 1

d77 3
a79 1

d87 3
a89 1

d91 1
a91 1

d107 1
a107 1

d123 1
a123 1

d125 1
d142 1
a142 1

d161 3
@


1.3
log
@SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
@
text
@a72 7
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
a80 1
</VARIABLELIST>
@


1.2
log
@Cleanup markup and minor editing to prepare for first release.
@
text
@d104 2
a105 1
   VERBOSE displays the full query plan and cost.
@


1.1
log
@Add new reference pages adapted from Jose'.
@
text
@d13 1
a13 1
Shows statement execution details.
d67 1
d73 7
d89 1
d114 7
@
