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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.34 2004/09/30 04:23:27 neilc Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-EXPLAIN">
   7  <refmeta>
   8   <refentrytitle id="SQL-EXPLAIN-TITLE">EXPLAIN</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>EXPLAIN</refname>
  14   <refpurpose>show the execution plan of a statement</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-explain">
  18   <primary>EXPLAIN</primary>
  19  </indexterm>
  20
  21  <indexterm zone="sql-explain">
  22   <primary>prepared statements</primary>
  23   <secondary>showing the query plan</secondary>
  24  </indexterm>
  25
  26  <indexterm zone="sql-explain">
  27   <primary>cursor</primary>
  28   <secondary>showing the query plan</secondary>
  29  </indexterm>
  30
  31  <refsynopsisdiv>
  32 <synopsis>
  33 EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
  34 </synopsis>
  35  </refsynopsisdiv>
  36
  37  <refsect1>
  38   <title>Description</title>
  39
  40   <para>
  41    This command displays the execution plan that the
  42    <productname>PostgreSQL</productname> planner generates for the
  43    supplied statement.  The execution plan shows how the table(s)
  44    referenced by the statement will be scanned---by plain sequential scan,
  45    index scan, etc.---and if multiple tables are referenced, what join
  46    algorithms will be used to bring together the required row from
  47    each input table.
  48   </para>
  49
  50   <para>
  51    The most critical part of the display is the estimated statement execution
  52    cost, which is the planner's guess at how long it will take to run the
  53    statement (measured in units of disk page fetches).  Actually two numbers
  54    are shown: the start-up time before the first row can be returned, and
  55    the total time to return all the rows.  For most queries the total time
  56    is what matters, but in contexts such as a subquery in <literal>EXISTS</literal>, the planner
  57    will choose the smallest start-up time instead of the smallest total time
  58    (since the executor will stop after getting one row, anyway).
  59    Also, if you limit the number of rows to return with a <literal>LIMIT</literal> clause,
  60    the planner makes an appropriate interpolation between the endpoint
  61    costs to estimate which plan is really the cheapest.
  62   </para>
  63
  64   <para>
  65    The <literal>ANALYZE</literal> option causes the statement to be actually executed, not only
  66    planned.  The total elapsed time expended within each plan node (in
  67    milliseconds) and total number of rows it actually returned are added to
  68    the display.  This is useful for seeing whether the planner's estimates
  69    are close to reality.
  70   </para>
  71
  72   <important>
  73    <para>
  74     Keep in mind that the statement is actually executed when
  75     <literal>ANALYZE</literal> is used.  Although
  76     <command>EXPLAIN</command> will discard any output that a
  77     <command>SELECT</command> would return, other side effects of the
  78     statement will happen as usual.  If you wish to use
  79     <command>EXPLAIN ANALYZE</command> on an
  80     <command>INSERT</command>, <command>UPDATE</command>,
  81     <command>DELETE</command>, or <command>EXECUTE</command> statement
  82     without letting the command affect your data, use this approach:
  83 <programlisting>
  84 BEGIN;
  85 EXPLAIN ANALYZE ...;
  86 ROLLBACK;
  87 </programlisting>
  88    </para>
  89   </important>
  90  </refsect1>
  91
  92  <refsect1>
  93   <title>Parameters</title>
  94
  95   <variablelist>
  96    <varlistentry>
  97     <term><literal>ANALYZE</literal></term>
  98     <listitem>
  99      <para>
 100       Carry out the command and show the actual run times.
 101      </para>
 102     </listitem>
 103    </varlistentry>
 104
 105    <varlistentry>
 106     <term><literal>VERBOSE</literal></term>
 107     <listitem>
 108      <para>
 109       Show the full internal representation of the plan tree, rather
 110       than just a summary.  Usually this option is only useful for
 111       debugging <productname>PostgreSQL</productname>.  The
 112       <literal>VERBOSE</literal> output is either pretty-printed or
 113       not, depending on the setting of the <xref
 114       linkend="guc-explain-pretty-print"> configuration parameter.
 115      </para>
 116     </listitem>
 117    </varlistentry>
 118
 119    <varlistentry>
 120     <term><replaceable class="parameter">statement</replaceable></term>
 121     <listitem>
 122      <para>
 123       Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
 124       <command>DELETE</>, <command>EXECUTE</>, or <command>DECLARE</>
 125       statement, whose execution plan you wish to see.
 126      </para>
 127     </listitem>
 128    </varlistentry>
 129   </variablelist>
 130  </refsect1>
 131
 132  <refsect1>
 133   <title>Notes</title>
 134
 135   <para>
 136    There is only sparse documentation on the optimizer's use of cost
 137    information in <productname>PostgreSQL</productname>.  Refer to
 138    <xref linkend="using-explain"> for more information.
 139   </para>
 140
 141   <para>
 142    In order to allow the <productname>PostgreSQL</productname> query
 143    planner to make reasonably informed decisions when optimizing
 144    queries, the <command>ANALYZE</command> statement should be run to
 145    record statistics about the distribution of data within the
 146    table. If you have not done this (or if the statistical
 147    distribution of the data in the table has changed significantly
 148    since the last time <command>ANALYZE</command> was run), the
 149    estimated costs are unlikely to conform to the real properties of
 150    the query, and consequently an inferior query plan may be chosen.
 151   </para>
 152
 153   <para>
 154    Prior to <productname>PostgreSQL</productname> 7.3, the plan was
 155    emitted in the form of a <literal>NOTICE</literal> message.  Now it
 156    appears as a query result (formatted like a table with a single
 157    text column).
 158   </para>
 159  </refsect1>
 160
 161  <refsect1>
 162   <title>Examples</title>
 163
 164   <para>
 165    To show the plan for a simple query on a table with a single
 166    <type>integer</type> column and 10000 rows:
 167
 168 <programlisting>
 169 EXPLAIN SELECT * FROM foo;
 170
 171                        QUERY PLAN
 172 ---------------------------------------------------------
 173  Seq Scan on foo  (cost=0.00..155.00 rows=10000 width=4)
 174 (1 row)
 175 </programlisting>
 176   </para>
 177
 178   <para>
 179    If there is an index and we use a query with an indexable
 180    <literal>WHERE</literal> condition, <command>EXPLAIN</command>
 181    might show a different plan:
 182
 183 <programlisting>
 184 EXPLAIN SELECT * FROM foo WHERE i = 4;
 185
 186                          QUERY PLAN
 187 --------------------------------------------------------------
 188  Index Scan using fi on foo  (cost=0.00..5.98 rows=1 width=4)
 189    Index Cond: (i = 4)
 190 (2 rows)
 191 </programlisting>
 192   </para>
 193
 194   <para>
 195    And here is an example of a query plan for a query
 196    using an aggregate function:
 197
 198 <programlisting>
 199 EXPLAIN SELECT sum(i) FROM foo WHERE i &lt; 10;
 200
 201                              QUERY PLAN
 202 ---------------------------------------------------------------------
 203  Aggregate  (cost=23.93..23.93 rows=1 width=4)
 204    -&gt;  Index Scan using fi on foo  (cost=0.00..23.92 rows=6 width=4)
 205          Index Cond: (i &lt; 10)
 206 (3 rows)
 207 </programlisting>
 208   </para>
 209
 210   <para>
 211    Here is an example of using <command>EXPLAIN EXECUTE</command> to
 212    display the execution plan for a prepared query:
 213
 214 <programlisting>
 215 PREPARE query(int, int) AS SELECT sum(bar) FROM test
 216     WHERE id &gt; $1 AND id &lt; $2
 217     GROUP BY foo;
 218
 219 EXPLAIN ANALYZE EXECUTE query(100, 200);
 220
 221                                                        QUERY PLAN
 222 -------------------------------------------------------------------------------------------------------------------------
 223  HashAggregate  (cost=39.53..39.53 rows=1 width=8) (actual time=0.661..0.672 rows=7 loops=1)
 224    -&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)
 225          Index Cond: ((id &gt; $1) AND (id &lt; $2))
 226  Total runtime: 0.851 ms
 227 (4 rows)
 228 </programlisting>
 229   </para>
 230
 231   <para>
 232    Of course, the specific numbers shown here depend on the actual
 233    contents of the tables involved.  Also note that the numbers, and
 234    even the selected query strategy, may vary between
 235    <productname>PostgreSQL</productname> releases due to planner
 236    improvements. In addition, the <command>ANALYZE</command> command
 237    uses random sampling to estimate data statistics; therefore, it is
 238    possible for cost estimates to change after a fresh run of
 239    <command>ANALYZE</command>, even if the actual distribution of data
 240    in the table has not changed.
 241   </para>
 242  </refsect1>
 243
 244  <refsect1>
 245   <title>Compatibility</title>
 246
 247   <para>
 248    There is no <command>EXPLAIN</command> statement defined in the SQL standard.
 249   </para>
 250  </refsect1>
 251 </refentry>
 252
 253 <!-- Keep this comment at the end of the file
 254 Local variables:
 255 mode: sgml
 256 sgml-omittag:nil
 257 sgml-shorttag:t
 258 sgml-minimize-attributes:nil
 259 sgml-always-quote-attributes:t
 260 sgml-indent-step:1
 261 sgml-indent-data:t
 262 sgml-parent-document:nil
 263 sgml-default-dtd-file:"../reference.ced"
 264 sgml-exposed-tags:nil
 265 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 266 sgml-local-ecat-files:nil
 267 End:
 268 -->