head	1.84;
access;
symbols
	REL9_0_0:1.82.2.1
	REL9_1_ALPHA1:1.84
	REL9_0_RC1:1.82.2.1
	REL9_0_BETA4:1.82.2.1
	REL9_0_STABLE:1.82.0.2
	REL9_0_BETA3:1.82
	REL9_0_BETA2:1.80
	REL7_4_29:1.37
	REL8_0_25:1.49
	REL8_1_21:1.54
	REL8_2_17:1.59
	REL8_3_11:1.68
	REL8_4_4:1.71.2.1
	REL9_0_BETA1:1.79
	REL9_0_ALPHA5_BRANCH:1.74.0.2
	REL9_0_ALPHA5:1.74
	REL7_4_28:1.37
	REL8_0_24:1.49
	REL8_1_20:1.54
	REL8_2_16:1.59
	REL8_3_10:1.68
	REL8_4_3:1.71.2.1
	REL9_0_ALPHA4:1.73
	REL9_0_ALPHA4_BRANCH:1.73.0.2
	REL8_5_ALPHA3:1.72
	REL8_5_ALPHA3_BRANCH:1.72.0.6
	REL7_4_27:1.37
	REL8_0_23:1.49
	REL8_1_19:1.54
	REL8_2_15:1.59
	REL8_3_9:1.68
	REL8_4_2:1.71.2.1
	REL8_5_ALPHA2:1.72
	REL8_5_ALPHA2_BRANCH:1.72.0.4
	REL7_4_26:1.37
	REL8_0_22:1.49
	REL8_1_18:1.54
	REL8_2_14:1.59
	REL8_3_8:1.68
	REL8_4_1:1.71.2.1
	REL8_5_ALPHA1:1.72
	REL8_5_ALPHA1_BRANCH:1.72.0.2
	REL8_4_STABLE:1.71.0.2
	REL8_4_0:1.71
	REL8_4_RC2:1.71
	REL8_4_RC1:1.70
	REL8_4_BETA2:1.70
	REL8_4_BETA1:1.69
	REL7_4_25:1.37
	REL8_0_21:1.49
	REL8_1_17:1.54
	REL8_2_13:1.59
	REL8_3_7:1.68
	REL7_4_24:1.37
	REL8_0_20:1.49
	REL8_1_16:1.54
	REL8_2_12:1.59
	REL8_3_6:1.68
	REL7_4_23:1.37
	REL8_0_19:1.49
	REL8_1_15:1.54
	REL8_2_11:1.59
	REL8_3_5:1.68
	REL7_4_22:1.37
	REL8_0_18:1.49
	REL8_1_14:1.54
	REL8_2_10:1.59
	REL8_3_4:1.68
	REL7_4_21:1.37
	REL8_0_17:1.49
	REL8_1_13:1.54
	REL8_2_9:1.59
	REL8_3_3:1.68
	REL7_4_20:1.37
	REL8_0_16:1.49
	REL8_1_12:1.54
	REL8_2_8:1.59
	REL8_3_2:1.68
	REL8_2_7:1.59
	REL8_3_1:1.68
	REL8_3_STABLE:1.68.0.2
	REL8_3_0:1.68
	REL8_3_RC2:1.68
	REL7_3_21:1.21.2.1
	REL7_4_19:1.37
	REL8_0_15:1.49
	REL8_1_11:1.54
	REL8_2_6:1.59
	REL8_3_RC1:1.68
	REL8_3_BETA4:1.67
	REL8_3_BETA3:1.66
	REL8_3_BETA2:1.66
	REL8_3_BETA1:1.65
	REL7_3_20:1.21.2.1
	REL7_4_18:1.37
	REL8_0_14:1.49
	REL8_1_10:1.54
	REL8_2_5:1.59
	REL7_3_19:1.21.2.1
	REL7_4_17:1.37
	REL8_0_13:1.49
	REL8_1_9:1.54
	REL8_2_4:1.59
	REL8_0_12:1.49
	REL8_1_8:1.54
	REL8_2_3:1.59
	REL7_3_18:1.21.2.1
	REL7_4_16:1.37
	REL8_0_11:1.49
	REL8_1_7:1.54
	REL8_2_2:1.59
	REL8_0_10:1.49
	REL8_1_6:1.54
	REL8_2_1:1.59
	REL7_4_15:1.37
	REL7_3_17:1.21.2.1
	REL8_2_STABLE:1.59.0.2
	REL8_2_0:1.59
	REL8_2_RC1:1.59
	REL8_2_BETA3:1.59
	REL8_2_BETA2:1.59
	REL8_1_5:1.54
	REL8_0_9:1.49
	REL7_4_14:1.37
	REL7_3_16:1.21.2.1
	REL8_2_BETA1:1.58
	REL7_3_15:1.21.2.1
	REL7_4_13:1.37
	REL8_0_8:1.49
	REL8_1_4:1.54
	REL7_3_14:1.21.2.1
	REL7_4_12:1.37
	REL8_0_7:1.49
	REL8_1_3:1.54
	REL7_3_13:1.21.2.1
	REL7_4_11:1.37
	REL8_0_6:1.49
	REL8_1_2:1.54
	REL7_3_12:1.21.2.1
	REL7_4_10:1.37
	REL8_0_5:1.49
	REL8_1_1:1.54
	REL8_1_STABLE:1.54.0.2
	REL8_1_0:1.54
	REL8_1_0RC1:1.53
	REL8_1_0BETA4:1.53
	REL8_1_0BETA3:1.53
	REL7_3_11:1.21.2.1
	REL7_4_9:1.37
	REL8_0_4:1.49
	REL8_1_0BETA2:1.53
	REL8_1_0BETA1:1.51
	REL7_2_8:1.16
	REL7_3_10:1.21.2.1
	REL7_4_8:1.37
	REL8_0_3:1.49
	REL8_0_2:1.49
	REL7_2_7:1.16
	REL7_3_9:1.21.2.1
	REL7_4_7:1.37
	REL8_0_1:1.49
	REL8_0_STABLE:1.49.0.4
	REL8_0_0:1.49.0.2
	REL8_0_0RC5:1.49
	REL8_0_0RC4:1.49
	REL8_0_0RC3:1.49
	REL8_0_0RC2:1.48
	REL8_0_0RC1:1.48
	REL8_0_0BETA5:1.47
	REL8_0_0BETA4:1.46
	REL7_4_6:1.37
	REL7_3_8:1.21.2.1
	REL7_2_6:1.16
	REL8_0_0BETA3:1.46
	REL8_0_0BETA2:1.46
	REL7_2_5:1.16
	REL7_4_5:1.37
	REL7_3_7:1.21.2.1
	REL7_4_4:1.37
	REL8_0_0BETA1:1.46
	REL7_4_3:1.37
	REL7_4_2:1.37
	REL7_3_6:1.21.2.1
	REL7_4_1:1.37
	REL7_3_5:1.21.2.1
	REL7_4:1.37
	REL7_4_RC2:1.37
	REL7_4_STABLE:1.37.0.2
	REL7_4_RC1:1.37
	REL7_4_BETA5:1.36
	REL7_4_BETA4:1.33
	REL7_4_BETA3:1.33
	REL7_4_BETA2:1.30
	WIN32_DEV:1.30.0.2
	REL7_4_BETA1:1.30
	REL7_3_4:1.21.2.1
	REL7_3_2:1.21.2.1
	REL7_2_4:1.16
	REL7_3_STABLE:1.21.0.2
	REL7_2_3:1.16
	REL7_2_STABLE:1.16.0.2
	REL7_2:1.16
	REL7_2_RC2:1.16
	REL7_2_RC1:1.16
	REL7_2_BETA5:1.15
	REL7_2_BETA4:1.15
	REL7_2_BETA3:1.13
	REL7_2_BETA2:1.13
	REL7_2_BETA1:1.13
	REL7_1_2:1.3
	REL7_1_STABLE:1.3.0.2
	REL7_1:1.3
	REL7_1_BETA3:1.1
	REL7_1_BETA2:1.1;
locks; strict;
comment	@# @;


1.84
date	2010.07.26.20.28.49;	author petere;	state Exp;
branches;
next	1.83;

1.83
date	2010.07.13.20.57.19;	author tgl;	state Exp;
branches;
next	1.82;

1.82
date	2010.06.28.22.46.11;	author momjian;	state Exp;
branches
	1.82.2.1;
next	1.81;

1.81
date	2010.06.28.21.57.17;	author momjian;	state Exp;
branches;
next	1.80;

1.80
date	2010.05.29.21.08.04;	author tgl;	state Exp;
branches;
next	1.79;

1.79
date	2010.04.28.21.23.29;	author tgl;	state Exp;
branches;
next	1.78;

1.78
date	2010.04.28.16.48.21;	author alvherre;	state Exp;
branches;
next	1.77;

1.77
date	2010.04.28.16.10.40;	author heikki;	state Exp;
branches;
next	1.76;

1.76
date	2010.04.20.00.26.06;	author rhaas;	state Exp;
branches;
next	1.75;

1.75
date	2010.04.03.07.22.55;	author petere;	state Exp;
branches;
next	1.74;

1.74
date	2010.02.26.02.31.52;	author momjian;	state Exp;
branches;
next	1.73;

1.73
date	2010.01.15.09.18.59;	author heikki;	state Exp;
branches;
next	1.72;

1.72
date	2009.08.07.20.54.31;	author alvherre;	state Exp;
branches;
next	1.71;

1.71
date	2009.06.17.21.58.49;	author tgl;	state Exp;
branches
	1.71.2.1;
next	1.70;

1.70
date	2009.04.27.16.27.36;	author momjian;	state Exp;
branches;
next	1.69;

1.69
date	2008.12.13.19.13.43;	author tgl;	state Exp;
branches;
next	1.68;

1.68
date	2007.12.28.21.03.31;	author tgl;	state Exp;
branches
	1.68.2.1;
next	1.67;

1.67
date	2007.11.28.15.42.31;	author petere;	state Exp;
branches;
next	1.66;

1.66
date	2007.10.22.21.34.33;	author tgl;	state Exp;
branches;
next	1.65;

1.65
date	2007.09.26.22.36.30;	author tgl;	state Exp;
branches;
next	1.64;

1.64
date	2007.03.29.00.15.36;	author tgl;	state Exp;
branches;
next	1.63;

1.63
date	2007.02.01.19.10.24;	author momjian;	state Exp;
branches;
next	1.62;

1.62
date	2007.02.01.00.28.17;	author momjian;	state Exp;
branches;
next	1.61;

1.61
date	2007.01.31.20.56.18;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	2007.01.25.02.17.25;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	2006.10.07.20.59.03;	author petere;	state Exp;
branches
	1.59.2.1;
next	1.58;

1.58
date	2006.09.16.00.30.14;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	2006.06.05.02.49.58;	author tgl;	state Exp;
branches;
next	1.56;

1.56
date	2006.03.10.19.10.48;	author momjian;	state Exp;
branches;
next	1.55;

1.55
date	2005.12.20.02.30.35;	author tgl;	state Exp;
branches;
next	1.54;

1.54
date	2005.11.04.23.14.00;	author petere;	state Exp;
branches
	1.54.2.1;
next	1.53;

1.53
date	2005.09.02.03.19.53;	author tgl;	state Exp;
branches;
next	1.52;

1.52
date	2005.09.02.00.57.57;	author tgl;	state Exp;
branches;
next	1.51;

1.51
date	2005.03.25.21.57.57;	author tgl;	state Exp;
branches;
next	1.50;

1.50
date	2005.02.03.07.12.37;	author neilc;	state Exp;
branches;
next	1.49;

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

1.48
date	2004.12.01.19.00.27;	author tgl;	state Exp;
branches;
next	1.47;

1.47
date	2004.11.15.06.32.14;	author neilc;	state Exp;
branches;
next	1.46;

1.46
date	2004.05.27.01.00.40;	author neilc;	state Exp;
branches;
next	1.45;

1.45
date	2004.04.22.17.38.14;	author neilc;	state Exp;
branches;
next	1.44;

1.44
date	2004.04.22.07.02.36;	author neilc;	state Exp;
branches;
next	1.43;

1.43
date	2004.03.25.18.57.57;	author tgl;	state Exp;
branches;
next	1.42;

1.42
date	2004.03.09.16.57.46;	author neilc;	state Exp;
branches;
next	1.41;

1.41
date	2004.02.03.17.34.02;	author tgl;	state Exp;
branches;
next	1.40;

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

1.39
date	2003.12.14.00.10.32;	author neilc;	state Exp;
branches;
next	1.38;

1.38
date	2003.11.29.19.51.37;	author pgsql;	state Exp;
branches;
next	1.37;

1.37
date	2003.11.01.01.56.29;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2003.10.17.22.38.20;	author tgl;	state Exp;
branches;
next	1.35;

1.35
date	2003.10.17.01.14.26;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2003.10.10.02.08.42;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2003.09.11.18.30.38;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2003.09.11.17.31.45;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2003.08.31.17.32.19;	author petere;	state Exp;
branches;
next	1.30;

1.30
date	2003.06.25.02.07.33;	author momjian;	state Exp;
branches
	1.30.2.1;
next	1.29;

1.29
date	2003.06.24.23.19.10;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	2003.03.25.16.15.37;	author petere;	state Exp;
branches;
next	1.27;

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

1.26
date	2003.01.28.03.34.29;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	2003.01.27.22.40.56;	author momjian;	state Exp;
branches;
next	1.24;

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

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

1.22
date	2002.11.11.20.14.03;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2002.09.21.18.32.53;	author petere;	state Exp;
branches
	1.21.2.1;
next	1.20;

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

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

1.18
date	2002.03.22.19.20.17;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2002.03.06.06.44.31;	author momjian;	state Exp;
branches;
next	1.16;

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

1.15
date	2001.11.28.20.49.10;	author petere;	state Exp;
branches;
next	1.14;

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

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

1.12
date	2001.10.12.23.32.34;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2001.10.09.18.46.00;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2001.09.18.01.59.05;	author tgl;	state Exp;
branches;
next	1.9;

1.9
date	2001.09.13.15.55.23;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2001.09.09.17.21.59;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2001.06.22.18.53.36;	author tgl;	state Exp;
branches;
next	1.6;

1.6
date	2001.06.11.00.52.09;	author tgl;	state Exp;
branches;
next	1.5;

1.5
date	2001.05.17.21.50.16;	author petere;	state Exp;
branches;
next	1.4;

1.4
date	2001.05.09.00.35.09;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2001.03.24.23.03.26;	author petere;	state Exp;
branches;
next	1.2;

1.2
date	2001.02.19.00.24.30;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2000.12.16.02.29.36;	author tgl;	state Exp;
branches;
next	;

1.21.2.1
date	2002.11.10.12.45.42;	author petere;	state Exp;
branches;
next	;

1.30.2.1
date	2003.09.07.04.36.42;	author momjian;	state Exp;
branches;
next	;

1.54.2.1
date	2010.07.26.20.30.07;	author petere;	state Exp;
branches;
next	;

1.59.2.1
date	2010.07.26.20.29.56;	author petere;	state Exp;
branches;
next	;

1.68.2.1
date	2010.07.26.20.29.35;	author petere;	state Exp;
branches;
next	;

1.71.2.1
date	2009.08.07.20.55.04;	author alvherre;	state Exp;
branches;
next	1.71.2.2;

1.71.2.2
date	2010.07.26.20.29.09;	author petere;	state Exp;
branches;
next	;

1.82.2.1
date	2010.07.26.20.28.35;	author petere;	state Exp;
branches;
next	;


desc
@@


1.84
log
@Fix grammar

backpatched to 8.1
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.83 2010/07/13 20:57:19 tgl Exp $ -->

 <chapter id="performance-tips">
  <title>Performance Tips</title>

  <indexterm zone="performance-tips">
   <primary>performance</primary>
  </indexterm>

  <para>
   Query performance can be affected by many things. Some of these can
   be controlled by the user, while others are fundamental to the underlying
   design of the system.  This chapter provides some hints about understanding
   and tuning <productname>PostgreSQL</productname> performance.
  </para>

  <sect1 id="using-explain">
   <title>Using <command>EXPLAIN</command></title>

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

   <indexterm zone="using-explain">
    <primary>query plan</primary>
   </indexterm>

   <para>
    <productname>PostgreSQL</productname> devises a <firstterm>query
    plan</firstterm> for each query it receives.  Choosing the right
    plan to match the query structure and the properties of the data
    is absolutely critical for good performance, so the system includes
    a complex <firstterm>planner</> that tries to choose good plans.
    You can use the
    <xref linkend="sql-explain"> command
    to see what query plan the planner creates for any query.
    Plan-reading is an art that deserves an extensive tutorial, which
    this is not; but here is some basic information.
   </para>

   <para>
    The structure of a query plan is a tree of <firstterm>plan nodes</>.
    Nodes at the bottom level of the tree are table scan nodes: they return raw rows
    from a table.  There are different types of scan nodes for different
    table access methods: sequential scans, index scans, and bitmap index
    scans.  If the query requires joining, aggregation, sorting, or other
    operations on the raw rows, then there will be additional nodes
    above the scan nodes to perform these operations.  Again,
    there is usually more than one possible way to do these operations,
    so different node types can appear here too.  The output
    of <command>EXPLAIN</command> has one line for each node in the plan
    tree, showing the basic node type plus the cost estimates that the planner
    made for the execution of that plan node.  The first line (topmost node)
    has the estimated total execution cost for the plan; it is this number
    that the planner seeks to minimize.
   </para>

   <para>
    Here is a trivial example, just to show what the output looks like:
    <footnote>
     <para>
      Examples in this section are drawn from the regression test database
      after doing a <command>VACUUM ANALYZE</>, using 8.2 development sources.
      You should be able to get similar results if you try the examples yourself,
      but your estimated costs and row counts might vary slightly
      because <command>ANALYZE</>'s statistics are random samples rather
      than exact.
     </para>
    </footnote>

<programlisting>
EXPLAIN SELECT * FROM tenk1;

                         QUERY PLAN
-------------------------------------------------------------
 Seq Scan on tenk1  (cost=0.00..458.00 rows=10000 width=244)
</programlisting>
   </para>

   <para>
    The numbers that are quoted by <command>EXPLAIN</command> are (left
    to right):

    <itemizedlist>
     <listitem>
      <para>
       Estimated start-up cost (time expended before the output scan can start,
       e.g., time to do the sorting in a sort node)
      </para>
     </listitem>

     <listitem>
      <para>
       Estimated total cost (if all rows are retrieved, though they might
       not be; e.g., a query with a <literal>LIMIT</> clause will stop
       short of paying the total cost of the <literal>Limit</> plan node's
       input node)
      </para>
     </listitem>

     <listitem>
      <para>
       Estimated number of rows output by this plan node (again, only if
       executed to completion)
      </para>
     </listitem>

     <listitem>
      <para>
       Estimated average width (in bytes) of rows output by this plan
       node
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    The costs are measured in arbitrary units determined by the planner's
    cost parameters (see <xref linkend="runtime-config-query-constants">).
    Traditional practice is to measure the costs in units of disk page
    fetches; that is, <xref linkend="guc-seq-page-cost"> is conventionally
    set to <literal>1.0</> and the other cost parameters are set relative
    to that.  (The examples in this section are run with the default cost
    parameters.)
   </para>

   <para>
    It's important to note that the cost of an upper-level node includes
    the cost of all its child nodes.  It's also important to realize that
    the cost only reflects things that the planner cares about.
    In particular, the cost does not consider the time spent transmitting
    result rows to the client, which could be an important
    factor in the real elapsed time; but the planner ignores it because
    it cannot change it by altering the plan.  (Every correct plan will
    output the same row set, we trust.)
   </para>

   <para>
    The <literal>rows</> value is a little tricky
    because it is <emphasis>not</emphasis> the
    number of rows processed or scanned by the plan node.  It is usually less,
    reflecting the estimated selectivity of any <literal>WHERE</>-clause
    conditions that are being
    applied at the node.  Ideally the top-level rows estimate will
    approximate the number of rows actually returned, updated, or deleted
    by the query.
   </para>

   <para>
    Returning to our example:

<programlisting>
EXPLAIN SELECT * FROM tenk1;

                         QUERY PLAN
-------------------------------------------------------------
 Seq Scan on tenk1  (cost=0.00..458.00 rows=10000 width=244)
</programlisting>
   </para>

   <para>
    This is about as straightforward as it gets.  If you do:

<programlisting>
SELECT relpages, reltuples FROM pg_class WHERE relname = 'tenk1';
</programlisting>

    you will find that <classname>tenk1</classname> has 358 disk
    pages and 10000 rows.  The estimated cost is computed as (disk pages read *
    <xref linkend="guc-seq-page-cost">) + (rows scanned *
    <xref linkend="guc-cpu-tuple-cost">).  By default,
    <varname>seq_page_cost</> is 1.0 and <varname>cpu_tuple_cost</> is 0.01,
    so the estimated cost is (358 * 1.0) + (10000 * 0.01) = 458.
   </para>

   <para>
    Now let's modify the original query to add a <literal>WHERE</> condition:

<programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 7000;

                         QUERY PLAN
------------------------------------------------------------
 Seq Scan on tenk1  (cost=0.00..483.00 rows=7033 width=244)
   Filter: (unique1 &lt; 7000)
</programlisting>

    Notice that the <command>EXPLAIN</> output shows the <literal>WHERE</>
    clause being applied as a <quote>filter</> condition; this means that
    the plan node checks the condition for each row it scans, and outputs
    only the ones that pass the condition.
    The estimate of output rows has been reduced because of the <literal>WHERE</>
    clause.
    However, the scan will still have to visit all 10000 rows, so the cost
    hasn't decreased; in fact it has gone up a bit (by 10000 * <xref
    linkend="guc-cpu-operator-cost">, to be exact) to reflect the extra CPU
    time spent checking the <literal>WHERE</> condition.
   </para>

   <para>
    The actual number of rows this query would select is 7000, but the <literal>rows</>
    estimate is only approximate.  If you try to duplicate this experiment,
    you will probably get a slightly different estimate; moreover, it will
    change after each <command>ANALYZE</command> command, because the
    statistics produced by <command>ANALYZE</command> are taken from a
    randomized sample of the table.
   </para>

   <para>
    Now, let's make the condition more restrictive:

<programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100;

                                  QUERY PLAN
------------------------------------------------------------------------------
 Bitmap Heap Scan on tenk1  (cost=2.37..232.35 rows=106 width=244)
   Recheck Cond: (unique1 &lt; 100)
   ->  Bitmap Index Scan on tenk1_unique1  (cost=0.00..2.37 rows=106 width=0)
         Index Cond: (unique1 &lt; 100)
</programlisting>

    Here the planner has decided to use a two-step plan: the bottom plan
    node visits an index to find the locations of rows matching the index
    condition, and then the upper plan node actually fetches those rows
    from the table itself.  Fetching the rows separately is much more
    expensive than sequentially reading them, but because not all the pages
    of the table have to be visited, this is still cheaper than a sequential
    scan.  (The reason for using two plan levels is that the upper plan
    node sorts the row locations identified by the index into physical order
    before reading them, to minimize the cost of separate fetches.
    The <quote>bitmap</> mentioned in the node names is the mechanism that
    does the sorting.)
   </para>

   <para>
    If the <literal>WHERE</> condition is selective enough, the planner might
    switch to a <quote>simple</> index scan plan:

<programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3;

                                  QUERY PLAN
------------------------------------------------------------------------------
 Index Scan using tenk1_unique1 on tenk1  (cost=0.00..10.00 rows=2 width=244)
   Index Cond: (unique1 &lt; 3)
</programlisting>

    In this case the table rows are fetched in index order, which makes them
    even more expensive to read, but there are so few that the extra cost
    of sorting the row locations is not worth it.  You'll most often see
    this plan type for queries that fetch just a single row, and for queries
    that have an <literal>ORDER BY</> condition that matches the index
    order.
   </para>

   <para>
    Add another condition to the <literal>WHERE</> clause:

<programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3 AND stringu1 = 'xxx';

                                  QUERY PLAN
------------------------------------------------------------------------------
 Index Scan using tenk1_unique1 on tenk1  (cost=0.00..10.01 rows=1 width=244)
   Index Cond: (unique1 &lt; 3)
   Filter: (stringu1 = 'xxx'::name)
</programlisting>

    The added condition <literal>stringu1 = 'xxx'</literal> reduces the
    output-rows estimate, but not the cost because we still have to visit the
    same set of rows.  Notice that the <literal>stringu1</> clause
    cannot be applied as an index condition (since this index is only on
    the <literal>unique1</> column).  Instead it is applied as a filter on
    the rows retrieved by the index.  Thus the cost has actually gone up
    slightly to reflect this extra checking.
   </para>

   <para>
    If there are indexes on several columns referenced in <literal>WHERE</>, the
    planner might choose to use an AND or OR combination of the indexes:

<programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000;

                                     QUERY PLAN
-------------------------------------------------------------------------------------
 Bitmap Heap Scan on tenk1  (cost=11.27..49.11 rows=11 width=244)
   Recheck Cond: ((unique1 &lt; 100) AND (unique2 &gt; 9000))
   -&gt;  BitmapAnd  (cost=11.27..11.27 rows=11 width=0)
         -&gt;  Bitmap Index Scan on tenk1_unique1  (cost=0.00..2.37 rows=106 width=0)
               Index Cond: (unique1 &lt; 100)
         -&gt;  Bitmap Index Scan on tenk1_unique2  (cost=0.00..8.65 rows=1042 width=0)
               Index Cond: (unique2 &gt; 9000)
</programlisting>

    But this requires visiting both indexes, so it's not necessarily a win
    compared to using just one index and treating the other condition as
    a filter.  If you vary the ranges involved you'll see the plan change
    accordingly.
   </para>

   <para>
    Let's try joining two tables, using the columns we have been discussing:

<programlisting>
EXPLAIN SELECT *
FROM tenk1 t1, tenk2 t2
WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;

                                      QUERY PLAN
--------------------------------------------------------------------------------------
 Nested Loop  (cost=2.37..553.11 rows=106 width=488)
   -&gt;  Bitmap Heap Scan on tenk1 t1  (cost=2.37..232.35 rows=106 width=244)
         Recheck Cond: (unique1 &lt; 100)
         -&gt;  Bitmap Index Scan on tenk1_unique1  (cost=0.00..2.37 rows=106 width=0)
               Index Cond: (unique1 &lt; 100)
   -&gt;  Index Scan using tenk2_unique2 on tenk2 t2  (cost=0.00..3.01 rows=1 width=244)
         Index Cond: (unique2 = t1.unique2)
</programlisting>
   </para>

   <para>
    In this nested-loop join, the outer (upper) scan is the same bitmap index scan we
    saw earlier, and so its cost and row count are the same because we are
    applying the <literal>WHERE</> clause <literal>unique1 &lt; 100</literal>
    at that node.
    The <literal>t1.unique2 = t2.unique2</literal> clause is not relevant yet,
    so it doesn't affect the row count of the outer scan.  For the inner (lower) scan, the
    <literal>unique2</> value of the current outer-scan row is plugged into
    the inner index scan to produce an index condition like
    <literal>unique2 = <replaceable>constant</replaceable></literal>.
    So we get the same inner-scan plan and costs that we'd get from, say,
    <literal>EXPLAIN SELECT * FROM tenk2 WHERE unique2 = 42</literal>.  The
    costs of the loop node are then set on the basis of the cost of the outer
    scan, plus one repetition of the inner scan for each outer row (106 * 3.01,
    here), plus a little CPU time for join processing.
   </para>

   <para>
    In this example the join's output row count is the same as the product
    of the two scans' row counts, but that's not true in all cases because
    you can have <literal>WHERE</> clauses that mention both tables
    and so can only be applied at the join point, not to either input scan.
    For example, if we added
    <literal>WHERE ... AND t1.hundred &lt; t2.hundred</literal>,
    that would decrease the output row count of the join node, but not change
    either input scan.
   </para>

   <para>
    One way to look at variant plans is to force the planner to disregard
    whatever strategy it thought was the cheapest, using the enable/disable
    flags described in <xref linkend="runtime-config-query-enable">.
    (This is a crude tool, but useful.  See
    also <xref linkend="explicit-joins">.)

<programlisting>
SET enable_nestloop = off;
EXPLAIN SELECT *
FROM tenk1 t1, tenk2 t2
WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;

                                        QUERY PLAN
------------------------------------------------------------------------------------------
 Hash Join  (cost=232.61..741.67 rows=106 width=488)
   Hash Cond: (t2.unique2 = t1.unique2)
   -&gt;  Seq Scan on tenk2 t2  (cost=0.00..458.00 rows=10000 width=244)
   -&gt;  Hash  (cost=232.35..232.35 rows=106 width=244)
         -&gt;  Bitmap Heap Scan on tenk1 t1  (cost=2.37..232.35 rows=106 width=244)
               Recheck Cond: (unique1 &lt; 100)
               -&gt;  Bitmap Index Scan on tenk1_unique1  (cost=0.00..2.37 rows=106 width=0)
                     Index Cond: (unique1 &lt; 100)
</programlisting>

    This plan proposes to extract the 100 interesting rows of <classname>tenk1</classname>
    using that same old index scan, stash them into an in-memory hash table,
    and then do a sequential scan of <classname>tenk2</classname>, probing into the hash table
    for possible matches of <literal>t1.unique2 = t2.unique2</literal> for each <classname>tenk2</classname> row.
    The cost to read <classname>tenk1</classname> and set up the hash table is a start-up
    cost for the hash join, since there will be no output until we can
    start reading <classname>tenk2</classname>.  The total time estimate for the join also
    includes a hefty charge for the CPU time to probe the hash table
    10000 times.  Note, however, that we are <emphasis>not</emphasis> charging 10000 times 232.35;
    the hash table setup is only done once in this plan type.
   </para>

   <para>
    It is possible to check the accuracy of the planner's estimated costs
    by using <command>EXPLAIN ANALYZE</>.  This command actually executes the query,
    and then displays the true run time accumulated within each plan node
    along with the same estimated costs that a plain <command>EXPLAIN</command> shows.
    For example, we might get a result like this:

<screen>
EXPLAIN ANALYZE SELECT *
FROM tenk1 t1, tenk2 t2
WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;

                                                            QUERY PLAN
----------------------------------------------------------------------------------------------------------------------------------
 Nested Loop  (cost=2.37..553.11 rows=106 width=488) (actual time=1.392..12.700 rows=100 loops=1)
   -&gt;  Bitmap Heap Scan on tenk1 t1  (cost=2.37..232.35 rows=106 width=244) (actual time=0.878..2.367 rows=100 loops=1)
         Recheck Cond: (unique1 &lt; 100)
         -&gt;  Bitmap Index Scan on tenk1_unique1  (cost=0.00..2.37 rows=106 width=0) (actual time=0.546..0.546 rows=100 loops=1)
               Index Cond: (unique1 &lt; 100)
   -&gt;  Index Scan using tenk2_unique2 on tenk2 t2  (cost=0.00..3.01 rows=1 width=244) (actual time=0.067..0.078 rows=1 loops=100)
         Index Cond: (unique2 = t1.unique2)
 Total runtime: 14.452 ms
</screen>

    Note that the <quote>actual time</quote> values are in milliseconds of
    real time, whereas the <literal>cost</> estimates are expressed in
    arbitrary units; so they are unlikely to match up.
    The thing to pay attention to is whether the ratios of actual time and
    estimated costs are consistent.
   </para>

   <para>
    In some query plans, it is possible for a subplan node to be executed more
    than once.  For example, the inner index scan is executed once per outer
    row in the above nested-loop plan.  In such cases, the
    <literal>loops</> value reports the
    total number of executions of the node, and the actual time and rows
    values shown are averages per-execution.  This is done to make the numbers
    comparable with the way that the cost estimates are shown.  Multiply by
    the <literal>loops</> value to get the total time actually spent in
    the node.
   </para>

   <para>
    The <literal>Total runtime</literal> shown by <command>EXPLAIN
    ANALYZE</command> includes executor start-up and shut-down time, as well
    as time spent processing the result rows.  It does not include parsing,
    rewriting, or planning time.  For a <command>SELECT</> query, the total
    run time will normally be just a little larger than the total time
    reported for the top-level plan node.  For <command>INSERT</>,
    <command>UPDATE</>, and <command>DELETE</> commands, the total run time
    might be considerably larger, because it includes the time spent processing
    the result rows.  For these commands, the time for the top plan node is
    essentially the time spent locating the old rows and/or computing
    the new ones, but it doesn't include the time spent applying the changes.
    Time spent firing triggers, if any, is also outside the top plan node,
    and is shown separately for each trigger.
   </para>

   <para>
    It is worth noting that <command>EXPLAIN</> results should not be extrapolated
    to situations other than the one you are actually testing; for example,
    results on a toy-sized table cannot be assumed to apply to large tables.
    The planner's cost estimates are not linear and so it might choose
    a different plan for a larger or smaller table.  An extreme example
    is that on a table that only occupies one disk page, you'll nearly
    always get a sequential scan plan whether indexes are available or not.
    The planner realizes that it's going to take one disk page read to
    process the table in any case, so there's no value in expending additional
    page reads to look at an index.
   </para>
  </sect1>

 <sect1 id="planner-stats">
  <title>Statistics Used by the Planner</title>

  <indexterm zone="planner-stats">
   <primary>statistics</primary>
   <secondary>of the planner</secondary>
  </indexterm>

  <para>
   As we saw in the previous section, the query planner needs to estimate
   the number of rows retrieved by a query in order to make good choices
   of query plans.  This section provides a quick look at the statistics
   that the system uses for these estimates.
  </para>

  <para>
   One component of the statistics is the total number of entries in
   each table and index, as well as the number of disk blocks occupied
   by each table and index.  This information is kept in the table
   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>,
   in the columns <structfield>reltuples</structfield> and
   <structfield>relpages</structfield>.  We can look at it with
   queries similar to this one:

<screen>
SELECT relname, relkind, reltuples, relpages
FROM pg_class
WHERE relname LIKE 'tenk1%';

       relname        | relkind | reltuples | relpages
----------------------+---------+-----------+----------
 tenk1                | r       |     10000 |      358
 tenk1_hundred        | i       |     10000 |       30
 tenk1_thous_tenthous | i       |     10000 |       30
 tenk1_unique1        | i       |     10000 |       30
 tenk1_unique2        | i       |     10000 |       30
(5 rows)
</screen>

   Here we can see that <structname>tenk1</structname> contains 10000
   rows, as do its indexes, but the indexes are (unsurprisingly) much
   smaller than the table.
  </para>

  <para>
   For efficiency reasons, <structfield>reltuples</structfield>
   and <structfield>relpages</structfield> are not updated on-the-fly,
   and so they usually contain somewhat out-of-date values.
   They are updated by <command>VACUUM</>, <command>ANALYZE</>, and a
   few DDL commands such as <command>CREATE INDEX</>.  A stand-alone
   <command>ANALYZE</>, that is one not part of <command>VACUUM</>,
   generates an approximate <structfield>reltuples</structfield> value
   since it does not read every row of the table.  The planner
   will scale the values it finds in <structname>pg_class</structname>
   to match the current physical table size, thus obtaining a closer
   approximation.
  </para>

  <indexterm>
   <primary>pg_statistic</primary>
  </indexterm>

  <para>
   Most queries retrieve only a fraction of the rows in a table, due
   to <literal>WHERE</> clauses that restrict the rows to be
   examined.  The planner thus needs to make an estimate of the
   <firstterm>selectivity</> of <literal>WHERE</> clauses, that is,
   the fraction of rows that match each condition in the
   <literal>WHERE</> clause.  The information used for this task is
   stored in the
   <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>
   system catalog.  Entries in <structname>pg_statistic</structname>
   are updated by the <command>ANALYZE</> and <command>VACUUM
   ANALYZE</> commands, and are always approximate even when freshly
   updated.
  </para>

  <indexterm>
   <primary>pg_stats</primary>
  </indexterm>

  <para>
   Rather than look at <structname>pg_statistic</structname> directly,
   it's better to look at its view
   <link linkend="view-pg-stats"><structname>pg_stats</structname></link>
   when examining the statistics manually.  <structname>pg_stats</structname>
   is designed to be more easily readable.  Furthermore,
   <structname>pg_stats</structname> is readable by all, whereas
   <structname>pg_statistic</structname> is only readable by a superuser.
   (This prevents unprivileged users from learning something about
   the contents of other people's tables from the statistics.  The
   <structname>pg_stats</structname> view is restricted to show only
   rows about tables that the current user can read.)
   For example, we might do:

<screen>
SELECT attname, inherited, n_distinct,
       array_to_string(most_common_vals, E'\n') as most_common_vals
FROM pg_stats
WHERE tablename = 'road';

 attname | inherited | n_distinct |          most_common_vals          
---------+-----------+------------+------------------------------------
 name    | f         |  -0.363388 | I- 580                        Ramp+
         |           |            | I- 880                        Ramp+
         |           |            | Sp Railroad                       +
         |           |            | I- 580                            +
         |           |            | I- 680                        Ramp
 name    | t         |  -0.284859 | I- 880                        Ramp+
         |           |            | I- 580                        Ramp+
         |           |            | I- 680                        Ramp+
         |           |            | I- 580                            +
         |           |            | State Hwy 13                  Ramp
(2 rows)
</screen>

   Note that two rows are displayed for the same column, one corresponding
   to the complete inheritance hierarchy starting at the
   <literal>road</literal> table (<literal>inherited</>=<literal>t</>),
   and another one including only the <literal>road</literal> table itself
   (<literal>inherited</>=<literal>f</>).
  </para>

  <para>
   The amount of information stored in <structname>pg_statistic</structname>
   by <command>ANALYZE</>, in particular the maximum number of entries in the
   <structfield>most_common_vals</> and <structfield>histogram_bounds</>
   arrays for each column, can be set on a
   column-by-column basis using the <command>ALTER TABLE SET STATISTICS</>
   command, or globally by setting the
   <xref linkend="guc-default-statistics-target"> configuration variable.
   The default limit is presently 100 entries.  Raising the limit
   might allow more accurate planner estimates to be made, particularly for
   columns with irregular data distributions, at the price of consuming
   more space in <structname>pg_statistic</structname> and slightly more
   time to compute the estimates.  Conversely, a lower limit might be
   sufficient for columns with simple data distributions.
  </para>

  <para>
   Further details about the planner's use of statistics can be found in
   <xref linkend="planner-stats-details">.
  </para>

 </sect1>

 <sect1 id="explicit-joins">
  <title>Controlling the Planner with Explicit <literal>JOIN</> Clauses</title>

  <indexterm zone="explicit-joins">
   <primary>join</primary>
   <secondary>controlling the order</secondary>
  </indexterm>

  <para>
   It is possible
   to control the query planner to some extent by using the explicit <literal>JOIN</>
   syntax.  To see why this matters, we first need some background.
  </para>

  <para>
   In a simple join query, such as:
<programlisting>
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
</programlisting>
   the planner is free to join the given tables in any order.  For
   example, it could generate a query plan that joins A to B, using
   the <literal>WHERE</> condition <literal>a.id = b.id</>, and then
   joins C to this joined table, using the other <literal>WHERE</>
   condition.  Or it could join B to C and then join A to that result.
   Or it could join A to C and then join them with B &mdash; but that
   would be inefficient, since the full Cartesian product of A and C
   would have to be formed, there being no applicable condition in the
   <literal>WHERE</> clause to allow optimization of the join.  (All
   joins in the <productname>PostgreSQL</productname> executor happen
   between two input tables, so it's necessary to build up the result
   in one or another of these fashions.)  The important point is that
   these different join possibilities give semantically equivalent
   results but might have hugely different execution costs.  Therefore,
   the planner will explore all of them to try to find the most
   efficient query plan.
  </para>

  <para>
   When a query only involves two or three tables, there aren't many join
   orders to worry about.  But the number of possible join orders grows
   exponentially as the number of tables expands.  Beyond ten or so input
   tables it's no longer practical to do an exhaustive search of all the
   possibilities, and even for six or seven tables planning might take an
   annoyingly long time.  When there are too many input tables, the
   <productname>PostgreSQL</productname> planner will switch from exhaustive
   search to a <firstterm>genetic</firstterm> probabilistic search
   through a limited number of possibilities.  (The switch-over threshold is
   set by the <xref linkend="guc-geqo-threshold"> run-time
   parameter.)
   The genetic search takes less time, but it won't
   necessarily find the best possible plan.
  </para>

  <para>
   When the query involves outer joins, the planner has less freedom
   than it does for plain (inner) joins. For example, consider:
<programlisting>
SELECT * FROM a LEFT JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
</programlisting>
   Although this query's restrictions are superficially similar to the
   previous example, the semantics are different because a row must be
   emitted for each row of A that has no matching row in the join of B and C.
   Therefore the planner has no choice of join order here: it must join
   B to C and then join A to that result.  Accordingly, this query takes
   less time to plan than the previous query.  In other cases, the planner
   might be able to determine that more than one join order is safe.
   For example, given:
<programlisting>
SELECT * FROM a LEFT JOIN b ON (a.bid = b.id) LEFT JOIN c ON (a.cid = c.id);
</programlisting>
   it is valid to join A to either B or C first.  Currently, only
   <literal>FULL JOIN</> completely constrains the join order.  Most
   practical cases involving <literal>LEFT JOIN</> or <literal>RIGHT JOIN</>
   can be rearranged to some extent.
  </para>

  <para>
   Explicit inner join syntax (<literal>INNER JOIN</>, <literal>CROSS
   JOIN</>, or unadorned <literal>JOIN</>) is semantically the same as
   listing the input relations in <literal>FROM</>, so it does not
   constrain the join order.
  </para>

  <para>
   Even though most kinds of <literal>JOIN</> don't completely constrain
   the join order, it is possible to instruct the
   <productname>PostgreSQL</productname> query planner to treat all
   <literal>JOIN</> clauses as constraining the join order anyway.
   For example, these three queries are logically equivalent:
<programlisting>
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
SELECT * FROM a CROSS JOIN b CROSS JOIN c WHERE a.id = b.id AND b.ref = c.id;
SELECT * FROM a JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
</programlisting>
   But if we tell the planner to honor the <literal>JOIN</> order,
   the second and third take less time to plan than the first.  This effect
   is not worth worrying about for only three tables, but it can be a
   lifesaver with many tables.
  </para>

  <para>
   To force the planner to follow the join order laid out by explicit
   <literal>JOIN</>s,
   set the <xref linkend="guc-join-collapse-limit"> run-time parameter to 1.
   (Other possible values are discussed below.)
  </para>

  <para>
   You do not need to constrain the join order completely in order to
   cut search time, because it's OK to use <literal>JOIN</> operators
   within items of a plain <literal>FROM</> list.  For example, consider:
<programlisting>
SELECT * FROM a CROSS JOIN b, c, d, e WHERE ...;
</programlisting>
   With <varname>join_collapse_limit</> = 1, this
   forces the planner to join A to B before joining them to other tables,
   but doesn't constrain its choices otherwise.  In this example, the
   number of possible join orders is reduced by a factor of 5.
  </para>

  <para>
   Constraining the planner's search in this way is a useful technique
   both for reducing planning time and for directing the planner to a
   good query plan.  If the planner chooses a bad join order by default,
   you can force it to choose a better order via <literal>JOIN</> syntax
   &mdash; assuming that you know of a better order, that is.  Experimentation
   is recommended.
  </para>

  <para>
   A closely related issue that affects planning time is collapsing of
   subqueries into their parent query.  For example, consider:
<programlisting>
SELECT *
FROM x, y,
    (SELECT * FROM a, b, c WHERE something) AS ss
WHERE somethingelse;
</programlisting>
   This situation might arise from use of a view that contains a join;
   the view's <literal>SELECT</> rule will be inserted in place of the view
   reference, yielding a query much like the above.  Normally, the planner
   will try to collapse the subquery into the parent, yielding:
<programlisting>
SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
</programlisting>
   This usually results in a better plan than planning the subquery
   separately.  (For example, the outer <literal>WHERE</> conditions might be such that
   joining X to A first eliminates many rows of A, thus avoiding the need to
   form the full logical output of the subquery.)  But at the same time,
   we have increased the planning time; here, we have a five-way join
   problem replacing two separate three-way join problems.  Because of the
   exponential growth of the number of possibilities, this makes a big
   difference.  The planner tries to avoid getting stuck in huge join search
   problems by not collapsing a subquery if more than <varname>from_collapse_limit</>
   <literal>FROM</> items would result in the parent
   query.  You can trade off planning time against quality of plan by
   adjusting this run-time parameter up or down.
  </para>

  <para>
   <xref linkend="guc-from-collapse-limit"> and <xref
   linkend="guc-join-collapse-limit">
   are similarly named because they do almost the same thing: one controls
   when the planner will <quote>flatten out</> subqueries, and the
   other controls when it will flatten out explicit joins.  Typically
   you would either set <varname>join_collapse_limit</> equal to
   <varname>from_collapse_limit</> (so that explicit joins and subqueries
   act similarly) or set <varname>join_collapse_limit</> to 1 (if you want
   to control join order with explicit joins).  But you might set them
   differently if you are trying to fine-tune the trade-off between planning
   time and run time.
  </para>
 </sect1>

 <sect1 id="populate">
  <title>Populating a Database</title>

  <para>
   One might need to insert a large amount of data when first populating
   a database. This section contains some suggestions on how to make
   this process as efficient as possible.
  </para>

  <sect2 id="disable-autocommit">
   <title>Disable Autocommit</title>

   <indexterm>
    <primary>autocommit</primary>
    <secondary>bulk-loading data</secondary>
   </indexterm>

   <para>
    When using multiple <command>INSERT</>s, turn off autocommit and just do
    one commit at the end.  (In plain
    SQL, this means issuing <command>BEGIN</command> at the start and
    <command>COMMIT</command> at the end.  Some client libraries might
    do this behind your back, in which case you need to make sure the
    library does it when you want it done.)  If you allow each
    insertion to be committed separately,
    <productname>PostgreSQL</productname> is doing a lot of work for
    each row that is added.  An additional benefit of doing all
    insertions in one transaction is that if the insertion of one row
    were to fail then the insertion of all rows inserted up to that
    point would be rolled back, so you won't be stuck with partially
    loaded data.
   </para>
  </sect2>

  <sect2 id="populate-copy-from">
   <title>Use <command>COPY</command></title>

   <para>
    Use <xref linkend="sql-copy"> to load
    all the rows in one command, instead of using a series of
    <command>INSERT</command> commands.  The <command>COPY</command>
    command is optimized for loading large numbers of rows; it is less
    flexible than <command>INSERT</command>, but incurs significantly
    less overhead for large data loads. Since <command>COPY</command>
    is a single command, there is no need to disable autocommit if you
    use this method to populate a table.
   </para>

   <para>
    If you cannot use <command>COPY</command>, it might help to use <xref
    linkend="sql-prepare"> to create a
    prepared <command>INSERT</command> statement, and then use
    <command>EXECUTE</command> as many times as required.  This avoids
    some of the overhead of repeatedly parsing and planning
    <command>INSERT</command>. Different interfaces provide this facility
    in different ways; look for <quote>prepared statements</> in the interface
    documentation.
   </para>

   <para>
    Note that loading a large number of rows using
    <command>COPY</command> is almost always faster than using
    <command>INSERT</command>, even if <command>PREPARE</> is used and
    multiple insertions are batched into a single transaction.
   </para>

   <para>
    <command>COPY</command> is fastest when used within the same
    transaction as an earlier <command>CREATE TABLE</command> or
    <command>TRUNCATE</command> command. In such cases no WAL
    needs to be written, because in case of an error, the files
    containing the newly loaded data will be removed anyway.
    However, this consideration only applies when
    <xref linkend="guc-wal-level"> is <literal>minimal</> as all commands
    must write WAL otherwise.
   </para>

  </sect2>

  <sect2 id="populate-rm-indexes">
   <title>Remove Indexes</title>

   <para>
    If you are loading a freshly created table, the fastest method is to
    create the table, bulk load the table's data using
    <command>COPY</command>, then create any indexes needed for the
    table.  Creating an index on pre-existing data is quicker than
    updating it incrementally as each row is loaded.
   </para>

   <para>
    If you are adding large amounts of data to an existing table,
    it might be a win to drop the indexes,
    load the table, and then recreate the indexes.  Of course, the
    database performance for other users might suffer
    during the time the indexes are missing.  One should also think
    twice before dropping a unique index, since the error checking
    afforded by the unique constraint will be lost while the index is
    missing.
   </para>
  </sect2>

  <sect2 id="populate-rm-fkeys">
   <title>Remove Foreign Key Constraints</title>

   <para>
    Just as with indexes, a foreign key constraint can be checked
    <quote>in bulk</> more efficiently than row-by-row.  So it might be
    useful to drop foreign key constraints, load data, and re-create
    the constraints.  Again, there is a trade-off between data load
    speed and loss of error checking while the constraint is missing.
   </para>

   <para>
    What's more, when you load data into a table with existing foreign key
    constraints, each new row requires an entry in the server's list of
    pending trigger events (since it is the firing of a trigger that checks
    the row's foreign key constraint).  Loading many millions of rows can
    cause the trigger event queue to overflow available memory, leading to
    intolerable swapping or even outright failure of the command.  Therefore
    it may be <emphasis>necessary</>, not just desirable, to drop and re-apply
    foreign keys when loading large amounts of data.  If temporarily removing
    the constraint isn't acceptable, the only other recourse may be to split
    up the load operation into smaller transactions.
   </para>
  </sect2>

  <sect2 id="populate-work-mem">
   <title>Increase <varname>maintenance_work_mem</varname></title>

   <para>
    Temporarily increasing the <xref linkend="guc-maintenance-work-mem">
    configuration variable when loading large amounts of data can
    lead to improved performance.  This will help to speed up <command>CREATE
    INDEX</> commands and <command>ALTER TABLE ADD FOREIGN KEY</> commands.
    It won't do much for <command>COPY</> itself, so this advice is
    only useful when you are using one or both of the above techniques.
   </para>
  </sect2>

  <sect2 id="populate-checkpoint-segments">
   <title>Increase <varname>checkpoint_segments</varname></title>

   <para>
    Temporarily increasing the <xref
    linkend="guc-checkpoint-segments"> configuration variable can also
    make large data loads faster.  This is because loading a large
    amount of data into <productname>PostgreSQL</productname> will
    cause checkpoints to occur more often than the normal checkpoint
    frequency (specified by the <varname>checkpoint_timeout</varname>
    configuration variable). Whenever a checkpoint occurs, all dirty
    pages must be flushed to disk. By increasing
    <varname>checkpoint_segments</varname> temporarily during bulk
    data loads, the number of checkpoints that are required can be
    reduced.
   </para>
  </sect2>

  <sect2 id="populate-pitr">
   <title>Disable WAL archival and streaming replication</title>

   <para>
    When loading large amounts of data into an installation that uses
    WAL archiving or streaming replication, it might be faster to take a
    new base backup after the load has completed than to process a large
    amount of incremental WAL data.  To prevent incremental WAL logging
    while loading, disable archiving and streaming replication, by setting
    <xref linkend="guc-wal-level"> to <literal>minimal</>,
    <xref linkend="guc-archive-mode"> to <literal>off</>, and
    <xref linkend="guc-max-wal-senders"> to zero.
    But note that changing these settings requires a server restart.
   </para>

   <para>
    Aside from avoiding the time for the archiver or WAL sender to
    process the WAL data,
    doing this will actually make certain commands faster, because they
    are designed not to write WAL at all if <varname>wal_level</varname>
    is <literal>minimal</>.  (They can guarantee crash safety more cheaply
    by doing an <function>fsync</> at the end than by writing WAL.)
    This applies to the following commands:
    <itemizedlist>
     <listitem>
      <para>
       <command>CREATE TABLE AS SELECT</command>
      </para>
     </listitem>
     <listitem>
      <para>
       <command>CREATE INDEX</command> (and variants such as
       <command>ALTER TABLE ADD PRIMARY KEY</command>)
      </para>
     </listitem>
     <listitem>
      <para>
       <command>ALTER TABLE SET TABLESPACE</command>
      </para>
     </listitem>
     <listitem>
      <para>
       <command>CLUSTER</command>
      </para>
     </listitem>
     <listitem>
      <para>
       <command>COPY FROM</command>, when the target table has been
       created or truncated earlier in the same transaction
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>

  <sect2 id="populate-analyze">
   <title>Run <command>ANALYZE</command> Afterwards</title>

   <para>
    Whenever you have significantly altered the distribution of data
    within a table, running <xref linkend="sql-analyze"> is strongly recommended. This
    includes bulk loading large amounts of data into the table.  Running
    <command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>)
    ensures that the planner has up-to-date statistics about the
    table.  With no statistics or obsolete statistics, the planner might
    make poor decisions during query planning, leading to poor
    performance on any tables with inaccurate or nonexistent
    statistics.  Note that if the autovacuum daemon is enabled, it might
    run <command>ANALYZE</command> automatically; see
    <xref linkend="vacuum-for-statistics">
    and <xref linkend="autovacuum"> for more information.
   </para>
  </sect2>

  <sect2 id="populate-pg-dump">
   <title>Some Notes About <application>pg_dump</></title>

   <para>
    Dump scripts generated by <application>pg_dump</> automatically apply
    several, but not all, of the above guidelines.  To reload a
    <application>pg_dump</> dump as quickly as possible, you need to
    do a few extra things manually.  (Note that these points apply while
    <emphasis>restoring</> a dump, not while <emphasis>creating</> it.
    The same points apply whether loading a text dump with
    <application>psql</> or using <application>pg_restore</> to load
    from a <application>pg_dump</> archive file.)
   </para>

   <para>
    By default, <application>pg_dump</> uses <command>COPY</>, and when
    it is generating a complete schema-and-data dump, it is careful to
    load data before creating indexes and foreign keys.  So in this case
    several guidelines are handled automatically.  What is left
    for you to do is to:
    <itemizedlist>
     <listitem>
      <para>
       Set appropriate (i.e., larger than normal) values for
       <varname>maintenance_work_mem</varname> and
       <varname>checkpoint_segments</varname>.
      </para>
     </listitem>
     <listitem>
      <para>
       If using WAL archiving or streaming replication, consider disabling
       them during the restore. To do that, set <varname>archive_mode</>
       to <literal>off</>,
       <varname>wal_level</varname> to <literal>minimal</>, and
       <varname>max_wal_senders</> to zero before loading the dump.
       Afterwards, set them back to the right values and take a fresh
       base backup.
      </para>
     </listitem>
     <listitem>
      <para>
       Consider whether the whole dump should be restored as a single
       transaction.  To do that, pass the <option>-1</> or
       <option>--single-transaction</> command-line option to
       <application>psql</> or <application>pg_restore</>. When using this
       mode, even the smallest of errors will rollback the entire restore,
       possibly discarding many hours of processing.  Depending on how
       interrelated the data is, that might seem preferable to manual cleanup,
       or not.  <command>COPY</> commands will run fastest if you use a single
       transaction and have WAL archiving turned off.
      </para>
     </listitem>
     <listitem>
      <para>
       If multiple CPUs are available in the database server, consider using
       <application>pg_restore</>'s <option>--jobs</> option.  This
       allows concurrent data loading and index creation.
      </para>
     </listitem>
     <listitem>
      <para>
       Run <command>ANALYZE</> afterwards.
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    A data-only dump will still use <command>COPY</>, but it does not
    drop or recreate indexes, and it does not normally touch foreign
    keys.

     <footnote>
      <para>
       You can get the effect of disabling foreign keys by using
       the <option>--disable-triggers</> option &mdash; but realize that
       that eliminates, rather than just postpones, foreign key
       validation, and so it is possible to insert bad data if you use it.
      </para>
     </footnote>

    So when loading a data-only dump, it is up to you to drop and recreate
    indexes and foreign keys if you wish to use those techniques.
    It's still useful to increase <varname>checkpoint_segments</varname>
    while loading the data, but don't bother increasing
    <varname>maintenance_work_mem</varname>; rather, you'd do that while
    manually recreating indexes and foreign keys afterwards.
    And don't forget to <command>ANALYZE</> when you're done; see
    <xref linkend="vacuum-for-statistics">
    and <xref linkend="autovacuum"> for more information.
   </para>
  </sect2>
  </sect1>

  <sect1 id="non-durability">
   <title>Non-Durable Settings</title>

   <indexterm zone="non-durability">
    <primary>non-durable</primary>
   </indexterm>

   <para>
    Durability is a database feature that guarantees the recording of
    committed transactions even if the server crashes or loses
    power.  However, durability adds significant database overhead,
    so if your site does not require such a guarantee,
    <productname>PostgreSQL</productname> can be configured to run
    much faster.  The following are configuration changes you can make
    to improve performance in such cases;  they do not invalidate
    commit guarantees related to database crashes, only abrupt operating
    system stoppage, except as mentioned below:

    <itemizedlist>
     <listitem>
      <para>
       Place the database cluster's data directory in a memory-backed
       file system (i.e. <acronym>RAM</> disk).  This eliminates all
       database disk I/O, but limits data storage to the amount of
       available memory (and perhaps swap).
      </para>
     </listitem>

     <listitem>
      <para>
       Turn off <xref linkend="guc-fsync">;  there is no need to flush
       data to disk.
      </para>
     </listitem>

     <listitem>
      <para>
       Turn off <xref linkend="guc-full-page-writes">;  there is no need
       to guard against partial page writes.
      </para>
     </listitem>

     <listitem>
      <para>
       Increase <xref linkend="guc-checkpoint-segments"> and <xref
       linkend="guc-checkpoint-timeout"> ; this reduces the frequency
       of checkpoints, but increases the storage requirements of
       <filename>/pg_xlog</>.
      </para>
     </listitem>

     <listitem>
      <para>
       Turn off <xref linkend="guc-synchronous-commit">;  there might be no
       need to write the <acronym>WAL</acronym> to disk on every
       commit.  This does affect database crash transaction durability.
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>

 </chapter>
@


1.83
log
@Teach EXPLAIN to print PARAM_EXEC Params as the referenced expressions,
rather than just $N.  This brings the display of nestloop-inner-indexscan
plans back to where it's been, and incidentally improves the display of
SubPlan parameters as well.  In passing, simplify the EXPLAIN code by
having it deal primarily in the PlanState tree rather than separately
searching Plan and PlanState trees.  This is noticeably cleaner for
subplans, and about a wash elsewhere.

One small difference from previous behavior is that EXPLAIN will no longer
qualify local variable references in inner-indexscan plan nodes, since it
no longer sees such nodes as possibly referencing multiple tables.  Vars
referenced through PARAM_EXEC Params are still forcibly qualified, though,
so I don't think the display is any more confusing than before.  Adjust a
couple of examples in the documentation to match this behavior.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.82 2010/06/28 22:46:11 momjian Exp $ -->
d1089 1
a1089 1
       that eliminates, rather than just postponing, foreign key
@


1.82
log
@Fix doc double-wording in non-durable patch.

Report from Thom Brown
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.81 2010/06/28 21:57:17 momjian Exp $ -->
d319 1
a319 1
         Index Cond: (t2.unique2 = t1.unique2)
d332 1
a332 1
    <literal>t2.unique2 = <replaceable>constant</replaceable></literal>.
d408 1
a408 1
         Index Cond: (t2.unique2 = t1.unique2)
@


1.82.2.1
log
@Fix grammar

backpatched to 8.1
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.82 2010/06/28 22:46:11 momjian Exp $ -->
d1089 1
a1089 1
       that eliminates, rather than just postpones, foreign key
@


1.81
log
@Add new Non-Durable Settings documentation section.

Document that synchronous_commit can lose transactions in a db crash,
not just a OS crash.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.80 2010/05/29 21:08:04 tgl Exp $ -->
d1116 1
a1116 1
    committed transactions even if if the server crashes or loses
@


1.80
log
@Add text to "Populating a Database" pointing out that bulk data load into a
table with foreign key constraints eats memory.  Per off-line discussion of
bug #5480 with its reporter.  Also do some minor wordsmithing elsewhere in
the same section.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.79 2010/04/28 21:23:29 tgl Exp $ -->
d1107 62
@


1.79
log
@Fix typo, per Thom Brown.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.78 2010/04/28 16:48:21 alvherre Exp $ -->
d873 2
a874 2
    it might be a win to drop the index,
    load the table, and then recreate the index.  Of course, the
d876 2
a877 2
    during the time the index is missing.  One should also think
    twice before dropping unique indexes, since the error checking
d893 13
d946 2
a947 2
    amount of incremental WAL data. You might want to disable archiving
    and streaming replication while loading, by setting
d949 2
a950 2
    <xref linkend="guc-archive-mode"> <literal>off</>, and
    <xref linkend="guc-max-wal-senders"> to zero).
d1022 2
a1023 1
    The same points apply when using <application>pg_restore</> to load
d1044 2
a1045 1
       them during the restore. To do that, set <varname>archive_mode</> off,
d1047 2
a1048 2
       <varname>max_wal_senders</> zero before loading the dump script,
       and afterwards set them back to the right values and take a fresh
d1062 8
a1069 4
       transaction and have WAL archiving turned off. 
       <application>pg_restore</> also has a <option>--jobs</> option
       which allows concurrent data loading and index creation, and has
       the performance advantages of doing COPY in a single transaction.
@


1.78
log
@Make pg_stats example query result a bit less wide, and add comment about
pg_stats.inherited
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.77 2010/04/28 16:10:40 heikki Exp $ -->
d1030 1
a1030 1
       them during the restore. To do that, set <varname>arcive_mode</> off,
@


1.77
log
@Introduce wal_level GUC to explicitly control if information needed for
archival or hot standby should be WAL-logged, instead of deducing that from
other options like archive_mode. This replaces recovery_connections GUC in
the primary, where it now has no effect, but it's still used in the standby
to enable/disable hot standby.

Remove the WAL-logging of "unlogged operations", like creating an index
without WAL-logging and fsyncing it at the end. Instead, we keep a copy of
the wal_mode setting and the settings that affect how much shared memory a
hot standby server needs to track master transactions (max_connections,
max_prepared_xacts, max_locks_per_xact) in pg_control. Whenever the settings
change, at server restart, write a WAL record noting the new settings and
update pg_control. This allows us to notice the change in those settings in
the standby at the right moment, they used to be included in checkpoint
records, but that meant that a changed value was not reflected in the
standby until the first checkpoint after the change.

Bump PG_CONTROL_VERSION and XLOG_PAGE_MAGIC. Whack XLOG_PAGE_MAGIC back to
the sequence it used to follow, before hot standby and subsequent patches
changed it to 0x9003.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.76 2010/04/20 00:26:06 rhaas Exp $ -->
d557 2
a558 1
SELECT attname, n_distinct, most_common_vals
d562 12
a573 4
 attname | n_distinct |                                                                                                                                                                                  most_common_vals                                                                                                                                                                                   
---------+------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 name    |  -0.467008 | {"I- 580                        Ramp","I- 880                        Ramp","Sp Railroad                       ","I- 580                            ","I- 680                        Ramp","I- 80                         Ramp","14th                          St  ","5th                           St  ","Mission                       Blvd","I- 880                            "}
 thepath |         20 | {"[(-122.089,37.71),(-122.0886,37.711)]"}
d576 6
@


1.76
log
@Update docs as to when WAL logging can be skipped.

In 8.4 and prior, WAL-logging could potentially be skipped whenever
archive_mode=off.  With streaming replication, this is now true only
if max_wal_senders=0.

Fujii Masao, with light copyediting by me
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.75 2010/04/03 07:22:55 petere Exp $ -->
d838 3
a840 4
    However, this consideration does not apply when
    <xref linkend="guc-archive-mode"> is on or streaming replication
    is allowed (i.e., <xref linkend="guc-max-wal-senders"> is more
    than or equal to one), as all commands must write WAL in that case.
d912 1
a912 1
   <title>Turn off <varname>archive_mode</varname> and streaming replication</title>
d916 8
a923 9
    WAL archiving or streaming replication, you might want to disable
    archiving (turn off the <xref linkend="guc-archive-mode">
    configuration variable) and replication (zero the
    <xref linkend="guc-max-wal-senders"> configuration variable)
    while loading.  It might be
    faster to take a new base backup after the load has completed
    than to process a large amount of incremental WAL data.
    But note that changing either of these variables requires
    a server restart.
d930 3
a932 4
    are designed not to write WAL at all if <varname>archive_mode</varname>
    is off and <varname>max_wal_senders</varname> is zero.  (They can
    guarantee crash safety more cheaply by doing an
    <function>fsync</> at the end than by writing WAL.)
d1014 6
a1019 4
       If using WAL archiving, consider disabling it during the restore.
       To do that, turn off <varname>archive_mode</varname> before loading the
       dump script, and afterwards turn it back on
       and take a fresh base backup.
@


1.75
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
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.74 2010/02/26 02:31:52 momjian Exp $ -->
d913 1
a913 1
   <title>Turn off <varname>archive_mode</varname></title>
d917 4
a920 2
    WAL archiving, you might want to disable archiving (turn off the
    <xref linkend="guc-archive-mode"> configuration variable)
d924 2
a925 2
    But note that turning <varname>archive_mode</varname> on or off
    requires a server restart.
d929 2
a930 1
    Aside from avoiding the time for the archiver to process the WAL data,
d933 2
a934 1
    is off.  (They can guarantee crash safety more cheaply by doing an
@


1.74
log
@Document pg_restore --jobs as a performance enhancement.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.73 2010/01/15 09:18:59 heikki Exp $ -->
d35 1
a35 1
    <xref linkend="sql-explain" endterm="sql-explain-title"> command
d804 1
a804 1
    Use <xref linkend="sql-copy" endterm="sql-copy-title"> to load
d816 1
a816 1
    linkend="sql-prepare" endterm="sql-prepare-title"> to create a
d970 1
a970 2
    within a table, running <xref linkend="sql-analyze"
    endterm="sql-analyze-title"> is strongly recommended. This
d979 2
a980 2
    <xref linkend="vacuum-for-statistics" endterm="vacuum-for-statistics-title">
    and <xref linkend="autovacuum" endterm="autovacuum-title"> for more information.
d1064 2
a1065 2
    <xref linkend="vacuum-for-statistics" endterm="vacuum-for-statistics-title">
    and <xref linkend="autovacuum" endterm="autovacuum-title"> for more information.
@


1.73
log
@Introduce Streaming Replication.

This includes two new kinds of postmaster processes, walsenders and
walreceiver. Walreceiver is responsible for connecting to the primary server
and streaming WAL to disk, while walsender runs in the primary server and
streams WAL from disk to the client.

Documentation still needs work, but the basics are there. We will probably
pull the replication section to a new chapter later on, as well as the
sections describing file-based replication. But let's do that as a separate
patch, so that it's easier to see what has been added/changed. This patch
also adds a new section to the chapter about FE/BE protocol, documenting the
protocol used by walsender/walreceivxer.

Bump catalog version because of two new functions,
pg_last_xlog_receive_location() and pg_last_xlog_replay_location(), for
monitoring the progress of replication.

Fujii Masao, with additional hacking by me
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.72 2009/08/07 20:54:31 alvherre Exp $ -->
d1030 4
a1033 1
       transaction and have WAL archiving turned off.
@


1.72
log
@Document that autovacuum may run ANALYZE
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.71 2009/06/17 21:58:49 tgl Exp $ -->
d839 3
a841 2
    <xref linkend="guc-archive-mode"> is on, as all commands
    must write WAL in that case.
@


1.71
log
@Proofreading for Bruce's recent round of documentation proofreading.
Most of those changes were good, but some not so good ...
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.70 2009/04/27 16:27:36 momjian Exp $ -->
d977 4
a980 1
    statistics.
d1060 3
a1062 1
    And don't forget to <command>ANALYZE</> when you're done.
@


1.71.2.1
log
@Document that autovacuum may run ANALYZE
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.71 2009/06/17 21:58:49 tgl Exp $ -->
d977 1
a977 4
    statistics.  Note that if the autovacuum daemon is enabled, it might
    run <command>ANALYZE</command> automatically; see
    <xref linkend="vacuum-for-statistics" endterm="vacuum-for-statistics-title">
    and <xref linkend="autovacuum" endterm="autovacuum-title"> for more information.
d1057 1
a1057 3
    And don't forget to <command>ANALYZE</> when you're done; see
    <xref linkend="vacuum-for-statistics" endterm="vacuum-for-statistics-title">
    and <xref linkend="autovacuum" endterm="autovacuum-title"> for more information.
@


1.71.2.2
log
@Fix grammar

backpatched to 8.1
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.71.2.1 2009/08/07 20:55:04 alvherre Exp $ -->
d1049 1
a1049 1
       that eliminates, rather than just postpones, foreign key
@


1.70
log
@Proofreading adjustments for first two parts of documentation (Tutorial
and SQL).
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.69 2008/12/13 19:13:43 tgl Exp $ -->
d48 3
a50 2
    above the scan nodes to perform these operations.  Other nodes types
    are also supported.  The output
d87 2
a88 2
       Estimated start-up cost, e.g., time expended before the output scan can start,
       time to do the sorting in a sort node
d94 3
a96 3
       Estimated total cost if all rows were to be retrieved (though they might
       not be, e.g., a query with a <literal>LIMIT</> clause will stop
       short of paying the total cost of the <literal>Limit</> node's
d103 2
a104 2
       Estimated number of rows output by this plan node (Again, only if
       executed to completion.)
d133 1
a133 1
    factor in the total elapsed time; but the planner ignores it because
d139 1
a139 1
    The <command>EXPLAIN</command> <literal>rows=</> value is a little tricky
d144 1
a144 1
    applied to the node.  Ideally the top-level rows estimate will
d201 1
a201 1
    The actual number of rows this query would select is 7000, but the <literal>rows=</>
d238 1
a238 1
    switch to a <emphasis>simple</> index scan plan:
d252 2
a253 2
    this plan type in queries that fetch just a single row, and for queries
    with an <literal>ORDER BY</> condition that matches the index
d324 1
a324 1
    In this nested-loop join, the outer scan (upper) is the same bitmap index scan we
d413 1
a413 1
    real time, whereas the <literal>cost=</> estimates are expressed in
d423 1
a423 1
    <literal>loops=</> value reports the
d427 1
a427 1
    the <literal>loops=</> value to get the total time actually spent in
d784 1
a784 1
    When doing <command>INSERT</>s, turn off autocommit and just do
d828 1
a828 1
    <command>INSERT</command>, even if the <command>PREPARE ... INSERT</> is used and
@


1.69
log
@Increase the default value of default_statistics_target from 10 to 100,
and its maximum value from 1000 to 10000.  ALTER TABLE SET STATISTICS
similarly now allows a value up to 10000.  Per discussion.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.68 2007/12/28 21:03:31 tgl Exp $ -->
d12 1
a12 1
   be manipulated by the user, while others are fundamental to the underlying
d30 1
a30 1
    plan</firstterm> for each query it is given.  Choosing the right
d33 1
a33 1
    a complex <firstterm>planner</> that tries to select good plans.
d43 1
a43 1
    Nodes at the bottom level are table scan nodes: they return raw rows
d48 2
a49 3
    <quote>atop</> the scan nodes to perform these operations.  Again,
    there is usually more than one possible way to do these operations,
    so different node types can appear here too.  The output
d58 1
a58 1
    Here is a trivial example, just to show what the output looks like.
d64 1
a64 1
      but your estimated costs and row counts will probably vary slightly
d66 1
a66 1
      than being exact.
d80 2
a81 1
    The numbers that are quoted by <command>EXPLAIN</command> are:
d86 2
a87 2
       Estimated start-up cost (Time expended before output scan can start,
       e.g., time to do the sorting in a sort node.)
d93 4
a96 4
       Estimated total cost (If all rows were to be retrieved, though they might
       not be: for example, a query with a <literal>LIMIT</> clause will stop
       short of paying the total cost of the <literal>Limit</> plan node's
       input node.)
d122 2
a123 2
    to that.  The examples in this section are run with the default cost
    parameters.
d132 1
a132 1
    factor in the true elapsed time; but the planner ignores it because
d138 2
a139 1
    Rows output is a little tricky because it is <emphasis>not</emphasis> the
d143 1
a143 1
    applied at the node.  Ideally the top-level rows estimate will
d167 2
a168 2
    you will find out that <classname>tenk1</classname> has 358 disk
    pages and 10000 rows.  The estimated cost is (disk pages read *
d171 2
a172 2
    <varname>seq_page_cost</> is 1.0 and <varname>cpu_tuple_cost</> is 0.01.
    So the estimated cost is (358 * 1.0) + (10000 * 0.01) = 458.
d176 1
a176 1
    Now let's modify the query to add a <literal>WHERE</> condition:
d191 1
a191 1
    The estimate of output rows has gone down because of the <literal>WHERE</>
d200 1
a200 1
    The actual number of rows this query would select is 7000, but the rows
d228 1
a228 1
    scan.  (The reason for using two levels of plan is that the upper plan
d230 1
a230 1
    before reading them, so as to minimize the costs of the separate fetches.
d237 1
a237 1
    switch to a <quote>simple</> index scan plan:
d251 2
a252 2
    this plan type for queries that fetch just a single row, and for queries
    that request an <literal>ORDER BY</> condition that matches the index
d275 1
a275 1
    a little bit to reflect this extra checking.
d279 1
a279 1
    If there are indexes on several columns used in <literal>WHERE</>, the
d306 3
a308 1
EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
d323 1
a323 1
    In this nested-loop join, the outer scan is the same bitmap index scan we
d328 1
a328 1
    so it doesn't affect row count of the outer scan.  For the inner scan, the
d341 2
a342 2
    of the two scans' row counts, but that's not true in general, because
    in general you can have <literal>WHERE</> clauses that mention both tables
d352 1
a352 1
    whatever strategy it thought was the winner, using the enable/disable
d359 3
a361 1
EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
d378 3
a380 3
    for possible matches of <literal>t1.unique2 = t2.unique2</literal> at each <classname>tenk2</classname> row.
    The cost to read <classname>tenk1</classname> and set up the hash table is entirely start-up
    cost for the hash join, since we won't get any rows out until we can
d388 1
a388 1
    It is possible to check on the accuracy of the planner's estimated costs
d395 3
a397 1
EXPLAIN ANALYZE SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
d412 1
a412 1
    real time, whereas the <quote>cost</quote> estimates are expressed in
d422 1
a422 1
    <quote>loops</quote> value reports the
d426 1
a426 1
    the <quote>loops</quote> value to get the total time actually spent in
d439 3
a441 3
    the result rows.  In these commands, the time for the top plan node
    essentially is the time spent computing the new rows and/or locating the
    old ones, but it doesn't include the time spent applying the changes.
d485 3
a487 1
SELECT relname, relkind, reltuples, relpages FROM pg_class WHERE relname LIKE 'tenk1%';
d524 1
a524 1
   to having <literal>WHERE</> clauses that restrict the rows to be
d556 3
a558 1
SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'road';
d783 2
a784 1
    Turn off autocommit and just do one commit at the end.  (In plain
d827 1
a827 1
    <command>INSERT</command>, even if <command>PREPARE</> is used and
d838 1
a838 1
    <xref linkend="guc-archive-mode"> is set, as all commands
d848 1
a848 1
    If you are loading a freshly created table, the fastest way is to
d859 2
a860 2
    database performance for other users might be adversely affected
    during the time that the index is missing.  One should also think
@


1.68
log
@Update examples in planstats.sgml for 8.3, and improve some aspects of
that discussion.  Add a link from perform.sgml.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.67 2007/11/28 15:42:31 petere Exp $ -->
d565 1
a565 1
   The default limit is presently 10 entries.  Raising the limit
@


1.68.2.1
log
@Fix grammar

backpatched to 8.1
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.68 2007/12/28 21:03:31 tgl Exp $ -->
d1033 1
a1033 1
       that eliminates, rather than just postpones, foreign key
@


1.67
log
@spell checker run
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.66 2007/10/22 21:34:33 tgl Exp $ -->
d11 1
a11 1
   Query performance can be affected by many things. Some of these can 
d141 1
a141 1
    conditions that are being 
d472 2
a473 2
   <link linkend="catalog-pg-class"><structname>pg_class</structname></link>, in
   the columns <structfield>reltuples</structfield> and
d496 1
a496 1
   For efficiency reasons, <structfield>reltuples</structfield> 
d520 2
a521 1
   stored in the <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>
d534 2
a535 1
   it's better to look at its view <structname>pg_stats</structname>
d558 2
a559 7
   <structname>pg_stats</structname> is described in detail in
   <xref linkend="view-pg-stats">.
  </para>

  <para>
   The amount of information stored in <structname>pg_statistic</structname>,
   in particular the maximum number of entries in the
d570 6
a575 1
   appropriate for columns with simple data distributions.
d918 1
a918 1
    This applies to the following commands: 
@


1.66
log
@Clarify example of planner cost computation, per a suggestion from
James Shaw.  Also update a couple of examples to reflect 8.3's improved
plan-printing code.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.65 2007/09/26 22:36:30 tgl Exp $ -->
d741 1
a741 1
   when the planner will <quote>flatten out</> subselects, and the
d744 1
a744 1
   <varname>from_collapse_limit</> (so that explicit joins and subselects
@


1.65
log
@Minor improvements in backup and recovery:

- create a separate archive_mode GUC, on which archive_command is dependent

- %r option in recovery.conf sends last restartpoint to recovery command

- %r used in pg_standby, updated README

- minor other code cleanup in pg_standby

- doc on Warm Standby now mentions pg_standby and %r

- log_restartpoints recovery option emits LOG message at each restartpoint

- end of recovery now displays last transaction end time, as requested
  by Warren Little; also shown at each restartpoint

- restart archiver if needed to carry away WAL files at shutdown

Simon Riggs
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.64 2007/03/29 00:15:36 tgl Exp $ -->
d167 5
a171 4
    pages and 10000 rows.  So the cost is estimated at 358 page
    reads, costing <xref linkend="guc-seq-page-cost"> apiece (1.0 by
    default), plus 10000 * <xref linkend="guc-cpu-tuple-cost"> which is
    0.01 by default.
d193 2
a194 1
    hasn't decreased; in fact it has gone up a bit to reflect the extra CPU
d315 1
a315 1
         Index Cond: ("outer".unique2 = t2.unique2)
d361 1
a361 1
   Hash Cond: ("outer".unique2 = "inner".unique2)
d400 1
a400 1
         Index Cond: ("outer".unique2 = t2.unique2)
@


1.64
log
@Teach CLUSTER to skip writing WAL if not needed (ie, not using archiving)
--- Simon.
Also, code review and cleanup for the previous COPY-no-WAL patches --- Tom.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.63 2007/02/01 19:10:24 momjian Exp $ -->
d822 1
a822 1
    <xref linkend="guc-archive-command"> is set, as all commands
d895 1
a895 1
   <title>Turn off <varname>archive_command</varname></title>
d899 2
a900 2
    WAL archiving, you might want to disable archiving (unset the
    <xref linkend="guc-archive-command"> configuration variable)
d904 2
d911 2
a912 2
    are designed not to write WAL at all if <varname>archive_command</varname>
    is unset.  (They can guarantee crash safety more cheaply by doing an
d994 2
a995 2
       To do that, unset <varname>archive_command</varname> before loading the
       dump script, and afterwards restore <varname>archive_command</varname>
@


1.63
log
@Wording cleanup for error messages.  Also change can't -> cannot.

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
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.62 2007/02/01 00:28:17 momjian Exp $ -->
d804 1
a804 1
    in different ways; look for Prepared Statements in the interface
d818 6
a823 8
    <command>TRUNCATE</command> command. In those cases, no WAL
    needs to be written because in case of an error, the files
    containing the newly loaded data will be removed automatically.
    <command>CREATE TABLE AS SELECT</command> is also optimized 
    to avoid writing WAL. <command>COPY</command> and
    <command>CREATE TABLE AS SELECT</command> will write WAL 
    when <xref linkend="guc-archive-command"> is set and will not
    therefore be optimized in that case.
d898 6
a903 4
    When loading large amounts of data you might want to unset the
    <xref linkend="guc-archive-command"> before loading. It might be
    faster to take a new base backup once the load has completed
    than to allow a large archive to accumulate.
d907 5
a911 3
    This is particularly important advice because certain commands 
    will perform more slowly when <varname>archive_command</varname>
    is set, as a result of their needing to write large amounts of WAL.
d913 29
a941 4
    <command>CREATE TABLE AS SELECT</command>, 
    <command>CREATE INDEX</command> and also <command>COPY</command>, when
    it is executed in the same transaction as a prior 
    <command>CREATE TABLE</command> or <command>TRUNCATE</command> command.
a942 1

d979 37
a1015 9
    the first several guidelines are handled automatically.  What is left
    for you to do is to set appropriate (i.e., larger than normal) values
    for <varname>maintenance_work_mem</varname> and
    <varname>checkpoint_segments</varname>, as well as unsetting 
    <varname>archive_command</varname> before loading the dump script,
    and then to run <command>ANALYZE</> afterwards and resetting
    <varname>archive_command</varname> if required. All of the 
    parameters can be reset once the load has completed without needing
    to restart the server, as described in <xref linkend="config-setting">.
@


1.62
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.61 2007/01/31 20:56:18 momjian Exp $ -->
d440 1
a440 1
    results on a toy-sized table can't be assumed to apply to large tables.
@


1.61
log
@Update 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".

Also update two error messages mentioned in the documenation to match.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.60 2007/01/25 02:17:25 momjian Exp $ -->
d160 1
a160 1
    This is about as straightforward as it gets.  If you do
d591 1
a591 1
   In a simple join query, such as
d631 1
a631 1
   than it does for plain (inner) joins. For example, consider
d642 1
a642 1
   For example, given
d686 1
a686 1
   within items of a plain <literal>FROM</> list.  For example, consider
d707 1
a707 1
   subqueries into their parent query.  For example, consider
d717 1
a717 1
   will try to collapse the subquery into the parent, yielding
@


1.60
log
@Prevent WAL logging when COPY is done in the same transation that
created it.

Simon Riggs
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.59 2006/10/07 20:59:03 petere Exp $ -->
d93 1
a93 1
       Estimated total cost (If all rows were to be retrieved, which they may
d233 1
a233 1
    If the <literal>WHERE</> condition is selective enough, the planner may
d429 1
a429 1
    may be considerably larger, because it includes the time spent processing
d441 1
a441 1
    The planner's cost estimates are not linear and so it may well choose
d567 1
a567 1
   may allow more accurate planner estimates to be made, particularly for
d570 1
a570 1
   time to compute the estimates.  Conversely, a lower limit may be
d608 1
a608 1
   results but may have hugely different execution costs.  Therefore,
d618 1
a618 1
   possibilities, and even for six or seven tables planning may take an
d641 1
a641 1
   may be able to determine that more than one join order is safe.
d754 1
a754 1
   One may need to insert a large amount of data when first populating
d770 1
a770 1
    <command>COMMIT</command> at the end.  Some client libraries may
d798 1
a798 1
    If you cannot use <command>COPY</command>, it may help to use <xref
d843 1
a843 1
    it may be a win to drop the index,
d845 1
a845 1
    database performance for other users may be adversely affected
d858 1
a858 1
    <quote>in bulk</> more efficiently than row-by-row.  So it may be
d900 2
a901 2
    When loading large amounts of data you may want to unset the
    <xref linkend="guc-archive-command"> before loading. It may be
d929 1
a929 1
    table.  With no statistics or obsolete statistics, the planner may
@


1.59
log
@The -X option in pg_dump was supposed to be a workaround for the lack of
portable long options.  But we have had portable long options for a long
time now, so this is obsolete.  Now people have added options which *only*
work with -X but not as regular long option, so I'm putting a stop to this:
-X is deprecated; it still works, but it has been removed from the
documentation, and please don't add more of them.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.58 2006/09/16 00:30:14 momjian Exp $ -->
d803 3
a805 1
    <command>INSERT</command>.
d814 14
d896 23
d956 6
a961 2
    <varname>checkpoint_segments</varname> before loading the dump script,
    and then to run <command>ANALYZE</> afterwards.
@


1.59.2.1
log
@Fix grammar

backpatched to 8.1
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.59 2006/10/07 20:59:03 petere Exp $ -->
d930 1
a930 1
       that eliminates, rather than just postpones, foreign key
@


1.58
log
@Remove emacs info from footer of SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.57 2006/06/05 02:49:58 tgl Exp $ -->
d929 1
a929 1
       the <option>-X disable-triggers</> option &mdash; but realize that
@


1.57
log
@Add a GUC parameter seq_page_cost, and use that everywhere we formerly
assumed that a sequential page fetch has cost 1.0.  This patch doesn't
in itself change the system's behavior at all, but it opens the door to
people adopting other units of measurement for EXPLAIN costs.  Also, if
we ever decide it's worth inventing per-tablespace access cost settings,
this change provides a workable intellectual framework for that.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.56 2006/03/10 19:10:48 momjian Exp $ -->
a946 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.56
log
@Make $PostgreSQL CVS tags consistent for SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.49 2005/04/09 03:52:43 momjian Exp $ -->
d63 1
a63 1
      after doing a <command>VACUUM ANALYZE</>, using 8.1 development sources.
d117 7
a123 6
    The costs are measured in units of disk page fetches; that is, 1.0
    equals one sequential disk page read, by definition.  (CPU effort
    estimates are made too; they are converted into disk-page units using some
    fairly arbitrary fudge factors. If you want to experiment with these
    factors, see the list of run-time configuration parameters in
    <xref linkend="runtime-config-query-constants">.)
d168 3
a170 3
    reads, defined as costing 1.0 apiece, plus 10000 * <xref
    linkend="guc-cpu-tuple-cost"> which is
    typically 0.01 (try <command>SHOW cpu_tuple_cost</command>).
d404 3
a406 2
    arbitrary units of disk fetches; so they are unlikely to match up.
    The thing to pay attention to is the ratios.
d432 1
a432 1
    old ones, but it doesn't include the time spent making the changes.
@


1.55
log
@Teach planner how to rearrange join order for some classes of OUTER JOIN.
Per my recent proposal.  I ended up basing the implementation on the
existing mechanism for enforcing valid join orders of IN joins --- the
rules for valid outer-join orders are somewhat similar.
@
text
@d1 1
a1 3
<!--
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.54 2005/11/04 23:14:00 petere Exp $
-->
@


1.54
log
@Spellchecking run, final cleanups
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.53 2005/09/02 03:19:53 tgl Exp $
d630 1
a630 1
   When the query involves outer joins, the planner has much less freedom
d640 10
a649 1
   less time to plan than the previous query.
d655 9
a663 4
   listing the input relations in <literal>FROM</>, so it does not need to
   constrain the join order.  But it is possible to instruct the
   <productname>PostgreSQL</productname> query planner to treat
   explicit inner <literal>JOIN</>s as constraining the join order anyway.
d677 2
a678 1
   To force the planner to follow the <literal>JOIN</> order for inner joins,
d715 3
a717 3
   the view's <literal>SELECT</> rule will be inserted in place of the view reference,
   yielding a query much like the above.  Normally, the planner will try
   to collapse the subquery into the parent, yielding
d740 1
a740 1
   other controls when it will flatten out explicit inner joins.  Typically
d745 1
a745 1
   differently if you are trying to fine-tune the trade off between planning
@


1.54.2.1
log
@Fix grammar

backpatched to 8.1
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.54 2005/11/04 23:14:00 petere Exp $
d915 1
a915 1
       that eliminates, rather than just postpones, foreign key
@


1.53
log
@Add some notes about how pg_dump relates to the practices recommended
under 'Populating a Database'.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.52 2005/09/02 00:57:57 tgl Exp $
d829 1
a829 1
    the constraints.  Again, there is a tradeoff between data load
@


1.52
log
@Update performance discussion for 8.1.  Add a little more explanatory
material in the EXPLAIN section, update examples to match current reality,
show examples of bitmap indexscans as well as plain ones.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.51 2005/03/25 21:57:57 tgl Exp $
d881 48
@


1.51
log
@Improve EXPLAIN ANALYZE to show the time spent in each trigger when
executing a statement that fires triggers.  Formerly this time was
included in "Total runtime" but not otherwise accounted for.
As a side benefit, we avoid re-opening relations when firing non-deferred
AFTER triggers, because the trigger code can re-use the main executor's
ResultRelInfo data structure.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.50 2005/02/03 07:12:37 neilc Exp $
d34 3
a36 1
    is absolutely critical for good performance.  You can use the
d38 1
a38 1
    to see what query plan the system creates for any query.
d44 40
a83 1
    The numbers that are currently quoted by <command>EXPLAIN</command> are:
d95 4
a98 3
       Estimated total cost (If all rows were to be retrieved, which they may not
       be: a query with a <literal>LIMIT</> clause will stop short of paying the total cost,
       for example.)
d105 1
a105 1
       executed to completion)
d119 3
a121 2
    The costs are measured in units of disk page fetches.  (CPU effort
    estimates are converted into disk-page units using some
d130 1
a130 1
    the cost only reflects things that the planner/optimizer cares about.
d132 1
a132 1
    result rows to the frontend, which could be a pretty dominant
d140 4
a143 4
    number of rows
    processed/scanned by the query, it is usually less, reflecting the
    estimated selectivity of any <literal>WHERE</>-clause conditions that are being
    applied at this node.  Ideally the top-level rows estimate will
d149 1
a149 2
    Here are some examples (using the regression test database after a
    <command>VACUUM ANALYZE</>, and 7.3 development sources):
d156 1
a156 1
 Seq Scan on tenk1  (cost=0.00..333.00 rows=10000 width=148)
d164 1
a164 1
SELECT * FROM pg_class WHERE relname = 'tenk1';
d167 2
a168 2
    you will find out that <classname>tenk1</classname> has 233 disk
    pages and 10000 rows.  So the cost is estimated at 233 page
d171 1
a171 1
    currently 0.01 (try <command>SHOW cpu_tuple_cost</command>).
d178 1
a178 1
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 1000;
d182 2
a183 2
 Seq Scan on tenk1  (cost=0.00..358.00 rows=1033 width=148)
   Filter: (unique1 &lt; 1000)
d186 6
a191 1
    The estimate of output rows has gone down because of the <literal>WHERE</> clause.
d198 1
a198 1
    The actual number of rows this query would select is 1000, but the
d207 29
a235 1
    Modify the query to restrict the condition even more:
d238 1
a238 1
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 50;
d240 4
a243 4
                                   QUERY PLAN
-------------------------------------------------------------------------------
 Index Scan using tenk1_unique1 on tenk1  (cost=0.00..179.33 rows=49 width=148)
   Index Cond: (unique1 &lt; 50)
d246 6
a251 6
    and you will see that if we make the <literal>WHERE</> condition selective
    enough, the planner will
    eventually decide that an index scan is cheaper than a sequential scan.
    This plan will only have to visit 50 rows because of the index,
    so it wins despite the fact that each individual fetch is more expensive
    than reading a whole disk page sequentially.
d258 1
a258 1
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 50 AND stringu1 = 'xxx';
d261 3
a263 3
-------------------------------------------------------------------------------
 Index Scan using tenk1_unique1 on tenk1  (cost=0.00..179.45 rows=1 width=148)
   Index Cond: (unique1 &lt; 50)
d277 24
d304 1
a304 1
EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 50 AND t1.unique2 = t2.unique2;
d306 8
a313 8
                               QUERY PLAN
----------------------------------------------------------------------------
 Nested Loop  (cost=0.00..327.02 rows=49 width=296)
   -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
                                      (cost=0.00..179.33 rows=49 width=148)
         Index Cond: (unique1 &lt; 50)
   -&gt;  Index Scan using tenk2_unique2 on tenk2 t2
                                      (cost=0.00..3.01 rows=1 width=148)
d319 14
a332 14
    In this nested-loop join, the outer scan is the same index scan we had
    in the example before last, and so its cost and row count are the same
    because we are applying the <literal>WHERE</> clause <literal>unique1 &lt; 50</literal> at that node.
    The <literal>t1.unique2 = t2.unique2</literal> clause is not relevant yet, so it doesn't
    affect row count of the outer scan.  For the inner scan, the <literal>unique2</> value of the
    current
    outer-scan row is plugged into the inner index scan
    to produce an index condition like
    <literal>t2.unique2 = <replaceable>constant</replaceable></literal>.  So we get the
     same inner-scan plan and costs that we'd get from, say, <literal>EXPLAIN SELECT
     * FROM tenk2 WHERE unique2 = 42</literal>.  The costs of the loop node are then set
     on the basis of the cost of the outer scan, plus one repetition of the
     inner scan for each outer row (49 * 3.01, here), plus a little CPU
     time for join processing.
d338 4
a341 3
    in general you can have <literal>WHERE</> clauses that mention both tables and
    so can only be applied at the join point, not to either input scan.
    For example, if we added <literal>WHERE ... AND t1.hundred &lt; t2.hundred</literal>,
d349 2
a350 1
    flags for each plan type.  (This is a crude tool, but useful.  See
d355 1
a355 1
EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 50 AND t1.unique2 = t2.unique2;
d357 3
a359 3
                               QUERY PLAN
--------------------------------------------------------------------------
 Hash Join  (cost=179.45..563.06 rows=49 width=296)
d361 6
a366 5
   -&gt;  Seq Scan on tenk2 t2  (cost=0.00..333.00 rows=10000 width=148)
   -&gt;  Hash  (cost=179.33..179.33 rows=49 width=148)
         -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
                                    (cost=0.00..179.33 rows=49 width=148)
               Index Cond: (unique1 &lt; 50)
d369 2
a370 2
    This plan proposes to extract the 50 interesting rows of <classname>tenk1</classname>
    using ye same olde index scan, stash them into an in-memory hash table,
d377 1
a377 1
    10000 times.  Note, however, that we are <emphasis>not</emphasis> charging 10000 times 179.33;
d389 1
a389 1
EXPLAIN ANALYZE SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 50 AND t1.unique2 = t2.unique2;
d391 8
a398 11
                                   QUERY PLAN
-------------------------------------------------------------------------------
 Nested Loop  (cost=0.00..327.02 rows=49 width=296)
                                 (actual time=1.181..29.822 rows=50 loops=1)
   -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
                  (cost=0.00..179.33 rows=49 width=148)
                                 (actual time=0.630..8.917 rows=50 loops=1)
         Index Cond: (unique1 &lt; 50)
   -&gt;  Index Scan using tenk2_unique2 on tenk2 t2
                  (cost=0.00..3.01 rows=1 width=148)
                                 (actual time=0.295..0.324 rows=1 loops=50)
d400 1
a400 1
 Total runtime: 31.604 ms
d478 8
a485 7
    relname    | relkind | reltuples | relpages
---------------+---------+-----------+----------
 tenk1         | r       |     10000 |      233
 tenk1_hundred | i       |     10000 |       30
 tenk1_unique1 | i       |     10000 |       30
 tenk1_unique2 | i       |     10000 |       30
(4 rows)
d521 1
a521 1
   ANALYZE</> commands and are always approximate even when freshly
d600 1
a600 1
   Or it could join A to C and then join them with B, but that
d811 3
a813 2
    If you are augmenting an existing table, you can drop the index,
    load the table, and then recreate the index. Of course, the
d822 12
d840 4
a843 6
    lead to improved performance. This is because when a B-tree index
    is created from scratch, the existing content of the table needs
    to be sorted. Allowing the merge sort to use more memory
    means that fewer merge passes will be required.  A larger setting for
    <varname>maintenance_work_mem</varname> may also speed up validation
    of foreign-key constraints.
d854 1
a854 1
    amount of data into <productname>PostgreSQL</productname> can
@


1.50
log
@Minor SGML improvements.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.49 2004/12/23 23:07:38 tgl Exp $
d323 13
a335 10
    The <literal>Total runtime</literal> shown by <command>EXPLAIN ANALYZE</command> includes
    executor start-up and shut-down time, as well as time spent processing
    the result rows.  It does not include parsing, rewriting, or planning
    time.  For a <command>SELECT</> query, the total run time will normally be just a
    little larger than the total time reported for the top-level plan node.
    For <command>INSERT</>, <command>UPDATE</>, and <command>DELETE</> commands, the total run time may be
    considerably larger, because it includes the time spent processing the
    result rows.  In these commands, the time for the top plan node
    essentially is the time spent computing the new rows and/or locating
    the old ones, but it doesn't include the time spent making the changes.
@


1.49
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.48 2004/12/01 19:00:27 tgl Exp $
d365 7
a371 6
   One component of the statistics is the total number of entries in each
   table and index, as well as the number of disk blocks occupied by each
   table and index.  This information is kept in the table
   <structname>pg_class</structname> in the columns <structfield>reltuples</structfield>
   and <structfield>relpages</structfield>.  We can look at it
   with queries similar to this one:
d410 10
a419 8
   to having <literal>WHERE</> clauses that restrict the rows to be examined.
   The planner thus needs to make an estimate of the
   <firstterm>selectivity</> of <literal>WHERE</> clauses, that is, the fraction of
   rows that match each condition in the <literal>WHERE</> clause.  The information
   used for this task is stored in the <structname>pg_statistic</structname>
   system catalog.  Entries in <structname>pg_statistic</structname> are
   updated by <command>ANALYZE</> and <command>VACUUM ANALYZE</> commands
   and are always approximate even when freshly updated.
@


1.48
log
@Change planner to use the current true disk file size as its estimate of
a relation's number of blocks, rather than the possibly-obsolete value
in pg_class.relpages.  Scale the value in pg_class.reltuples correspondingly
to arrive at a hopefully more accurate number of rows.  When pg_class
contains 0/0, estimate a tuple width from the column datatypes and divide
that into current file size to estimate number of rows.  This improved
methodology allows us to jettison the ancient hacks that put bogus default
values into pg_class when a table is first created.  Also, per a suggestion
from Simon, make VACUUM (but not VACUUM FULL or ANALYZE) adjust the value
it puts into pg_class.reltuples to try to represent the mean tuple density
instead of the minimal density that actually prevails just after VACUUM.
These changes alter the plans selected for certain regression tests, so
update the expected files accordingly.  (I removed join_1.out because
it's not clear if it still applies; we can add back any variant versions
as they are shown to be needed.)
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.47 2004/11/15 06:32:14 neilc Exp $
d81 1
a81 1
    <xref linkend="runtime-config-resource">.)
a659 10

   <para>
    If you are issuing a large sequence of <command>INSERT</command>
    commands to bulk load some data, also consider using <xref
    linkend="sql-prepare" endterm="sql-prepare-title"> to create a
    prepared <command>INSERT</command> statement. Since you are
    executing the same command multiple times, it is more efficient to
    prepare the command once and then use <command>EXECUTE</command>
    as many times as required.
   </para>
d677 9
d688 2
a689 3
    <command>INSERT</command>, even if multiple
    <command>INSERT</command> commands are batched into a single
    transaction.
d720 1
a720 1
    configuration variable when restoring large amounts of data can
d723 1
a723 1
    to be sorted. Allowing the external merge sort to use more memory
d755 1
a755 2
    includes when bulk loading large amounts of data into
    <productname>PostgreSQL</productname>.  Running
@


1.47
log
@Replace "--" and "---" with "&mdash;" as appropriate, for better-looking
output.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.46 2004/05/27 01:00:40 neilc Exp $
d392 3
a394 5
   and so they usually contain only approximate values (which is good
   enough for the planner's purposes).  They are initialized with dummy
   values (presently 1000 and 10 respectively) when a table is created.
   They are updated by certain commands, presently <command>VACUUM</>,
   <command>ANALYZE</>, and <command>CREATE INDEX</>.  A stand-alone
d397 4
a400 1
   since it does not read every row of the table.
@


1.46
log
@Add an index entry for "Performance Tips". Patch from Alvaro Herrera.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.45 2004/04/22 17:38:14 neilc Exp $
d579 1
a579 1
   --- assuming that you know of a better order, that is.  Experimentation
@


1.45
log
@Make psql's \d+ command indicate whether the table in question
contains OIDs. Also, minor documentation improvements to the
psql reference page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.44 2004/04/22 07:02:36 neilc Exp $
d7 4
@


1.44
log
@Improvements to the backup & restore documentation.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.43 2004/03/25 18:57:57 tgl Exp $
d636 1
a636 1
   <indexterm zone="disable-autocommit">
d638 1
@


1.43
log
@Convert some GUC variable references to links.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.42 2004/03/09 16:57:46 neilc Exp $
d31 2
a32 2
    <command>EXPLAIN</command> command to see what query plan the system
    creates for any query.
d641 22
a662 12
    Turn off autocommit and just do one commit at
    the end.  (In plain SQL, this means issuing <command>BEGIN</command>
    at the start and <command>COMMIT</command> at the end.  Some client
    libraries may do this behind your back, in which case you need to
    make sure the library does it when you want it done.)
    If you allow each insertion to be committed separately,
    <productname>PostgreSQL</productname> is doing a lot of work for each
    row that is added.
    An additional benefit of doing all insertions in one transaction
    is that if the insertion of one row were to fail then the
    insertion of all rows inserted up to that point would be rolled
    back, so you won't be stuck with partially loaded data.
d667 12
a678 1
   <title>Use <command>COPY FROM</command></title>
d681 5
a685 5
    Use <command>COPY FROM STDIN</command> to load all the rows in one
    command, instead of using a series of <command>INSERT</command>
    commands.  This reduces parsing, planning, etc.  overhead a great
    deal. If you do this then it is not necessary to turn off
    autocommit, since it is only one command anyway.
d702 6
a707 5
    load the table, then recreate the index. Of
    course, the database performance for other users may be adversely 
    affected during the time that the index is missing.  One should also
    think twice before dropping unique indexes, since the error checking
    afforded by the unique constraint will be lost while the index is missing.
d726 18
d748 11
a758 6
    It's a good idea to run <command>ANALYZE</command> or <command>VACUUM
    ANALYZE</command> anytime you've added or updated a lot of data,
    including just after initially populating a table.  This ensures that
    the planner has up-to-date statistics about the table.  With no statistics
    or obsolete statistics, the planner may make poor choices of query plans,
    leading to bad performance on queries that use your table.
@


1.42
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/perform.sgml,v 1.41 2004/02/03 17:34:02 tgl Exp $
d123 2
a124 1
    reads, defined as costing 1.0 apiece, plus 10000 * <varname>cpu_tuple_cost</varname> which is
d454 1
a454 1
   <varname>default_statistics_target</varname> runtime parameter.
d603 1
a603 1
   problems by not collapsing a subquery if more than <xref linkend="guc-from-collapse-limit">
d610 2
a611 1
   <varname>from_collapse_limit</> and <varname>join_collapse_limit</>
@


1.41
log
@Rename SortMem and VacuumMem to work_mem and maintenance_work_mem.
Make btree index creation and initial validation of foreign-key constraints
use maintenance_work_mem rather than work_mem as their memory limit.
Add some code to guc.c to allow these variables to be referenced by their
old names in SHOW and SET commands, for backwards compatibility.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.40 2004/01/11 05:46:58 neilc Exp $
d511 1
a511 1
   set by the <varname>geqo_threshold</varname> run-time
d552 1
a552 1
   set the <varname>join_collapse_limit</> run-time parameter to 1.
d602 2
a603 2
   problems by not collapsing a subquery if more than
   <varname>from_collapse_limit</> <literal>FROM</> items would result in the parent
d691 1
a691 1
    Temporarily increasing the <varname>maintenance_work_mem</varname>
d695 1
a695 1
    to be sorted. Allowing the merge sort to use more memory
@


1.40
log
@Minor documentation improvements.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.39 2003/12/14 00:10:32 neilc Exp $
d687 2
a688 2
  <sect2 id="populate-sort-mem">
   <title>Increase <varname>sort_mem</varname></title>
d691 1
a691 1
    Temporarily increasing the <varname>sort_mem</varname>
d695 4
a698 2
    to be sorted. Allowing the merge sort to use more buffer pages
    means that fewer merge passes will be required.
@


1.39
log
@This patch makes some improvements and adds some additional detail
to the documentation on routine database maintainence activities.
I also corrected a bunch of SGML markup.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/perform.sgml,v 1.38 2003/11/29 19:51:37 pgsql Exp $
d626 3
a628 3
   One may need to do a large number of table insertions when first
   populating a database. Here are some tips and techniques for making that as
   efficient as possible.
d646 1
a646 1
    row added.
@


1.38
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.37 2003/11/01 01:56:29 petere Exp $
d103 1
a103 1
    <literal>VACUUM ANALYZE</>, and 7.3 development sources):
@


1.37
log
@Spell checking, consistent terminology.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.36 2003/10/17 22:38:20 tgl Exp $
@


1.36
log
@Document all the system views created by initdb (several of these were
never documented anywhere, sigh).  Centralize the detailed documentation
of system views into catalogs.sgml, and provide cross-references.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.35 2003/10/17 01:14:26 tgl Exp $
d617 1
a617 1
   differently if you are trying to fine-tune the tradeoff between planning
@


1.35
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/perform.sgml,v 1.34 2003/10/10 02:08:42 momjian Exp $
d442 2
a443 2
   <xref linkend="planner-pg-stats-table"> shows the columns that
   exist in <structname>pg_stats</structname>.
a445 99
  <table id="planner-pg-stats-table">
   <title><structname>pg_stats</structname> Columns</title>

   <tgroup cols=3>
    <thead>
     <row>
      <entry>Name</entry>
      <entry>Data Type</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><literal>schemaname</literal></entry>
      <entry><type>name</type></entry>
      <entry>Name of the schema containing the table.</entry>
     </row>

     <row>
      <entry><literal>tablename</literal></entry>
      <entry><type>name</type></entry>
      <entry>Name of the table containing the column.</entry>
     </row>

     <row>
      <entry><literal>attname</literal></entry>
      <entry><type>name</type></entry>
      <entry>Name of the column described by this row.</entry>
     </row>

     <row>
      <entry><literal>null_frac</literal></entry>
      <entry><type>real</type></entry>
      <entry>Fraction of column entries that are null.</entry>
     </row>

     <row>
      <entry><literal>avg_width</literal></entry>
      <entry><type>integer</type></entry>
      <entry>Average width in bytes of the column entries.</entry>
     </row>

     <row>
      <entry><literal>n_distinct</literal></entry>
      <entry><type>real</type></entry>
      <entry>If greater than zero, the estimated number of distinct values
      in the column.  If less than zero, the negative of the number of
      distinct values divided by the number of rows.  (The negated form
      is used when <command>ANALYZE</> believes that the number of distinct values
      is likely to increase as the table grows; the positive form is used
      when the column seems to have a fixed number of possible values.)
      For example, -1 indicates a unique column in which the number of
      distinct values is the same as the number of rows.
      </entry>
     </row>

     <row>
      <entry><literal>most_common_vals</literal></entry>
      <entry><type>text[]</type></entry>
      <entry>A list of the most common values in the column. (Omitted if
      no values seem to be more common than any others.)</entry>
     </row>

     <row>
      <entry><literal>most_common_freqs</literal></entry>
      <entry><type>real[]</type></entry>
      <entry>A list of the frequencies of the most common values,
      i.e., number of occurrences of each divided by total number of rows.
     </entry>
     </row>

     <row>
      <entry><literal>histogram_bounds</literal></entry>
      <entry><type>text[]</type></entry>
      <entry>A list of values that divide the column's values into
      groups of approximately equal population.  The values in
      <structfield>most_common_vals</>, if present, are omitted from this
      histogram calculation.  (This columns is not filled if the column data type does not have a
      <literal>&lt;</> operator or if the <structfield>most_common_vals</>
      list accounts for the entire population.)
      </entry>
     </row>

     <row>
      <entry><literal>correlation</literal></entry>
      <entry><type>real</type></entry>
      <entry>Statistical correlation between physical row ordering and
      logical ordering of the column values.  This ranges from -1 to +1.
      When the value is near -1 or +1, an index scan on the column will
      be estimated to be cheaper than when it is near zero, due to reduction
      of random access to the disk.  (This column is not filled if the column data type does
      not have a <literal>&lt;</> operator.)
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

d447 4
a450 2
   The maximum number of entries in the <structfield>most_common_vals</>
   and <structfield>histogram_bounds</> arrays can be set on a
d452 3
a454 1
   command.  The default limit is presently 10 entries.  Raising the limit
@


1.34
log
@> That's a fairly useless place to put it, though, since someone would
> only think to look at sort_mem if they already had a clue.  It should
> be mentioned under bulk data load (in performance tips chapter)

Attached is a doc patch that does this. The way I've worded it may not
be the best, though.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.33 2003/09/11 18:30:38 momjian Exp $
d287 1
a287 1
                                 (actual time=1.18..29.82 rows=50 loops=1)
d290 1
a290 1
                                 (actual time=0.63..8.91 rows=50 loops=1)
d294 1
a294 1
                                 (actual time=0.29..0.32 rows=1 loops=50)
d296 1
a296 1
 Total runtime: 31.60 msec
@


1.33
log
@Consistenly lowercase GUC variable names, in docs and error messages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.32 2003/09/11 17:31:45 momjian Exp $
d754 4
a757 5
    command, instead of using
    a series of <command>INSERT</command> commands.  This reduces parsing,
    planning, etc.
    overhead a great deal. If you do this then it is not necessary to turn
    off autocommit, since it is only one command anyway.
d766 3
a768 3
    create the table, bulk-load with <command>COPY</command>, then create any
    indexes needed 
    for the table.  Creating an index on pre-existing data is quicker than
d779 13
@


1.32
log
@This patch makes a few minor improvements to the docs: make the
<varname> conventions more consistent, and improve the ANALYZE ref page.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.31 2003/08/31 17:32:19 petere Exp $
d606 1
a606 1
   set by the <varname>GEQO_THRESHOLD</varname> run-time
@


1.31
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.30 2003/06/25 02:07:33 momjian Exp $
d606 1
a606 1
   set by the <varname>geqo_threshold</varname> run-time
@


1.30
log
@Seems the runtime.sgml and perform.sgml patches combined are
incompatible.

I believe the attached xref meets the intent of the perform.sgml change.

--
Rod Taylor <rbt@@rbt.ca>
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.29 2003/06/24 23:19:10 momjian Exp $
d18 8
d347 5
d397 4
d413 4
d562 5
d728 4
@


1.30.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/perform.sgml,v 1.31 2003/08/31 17:32:19 petere Exp $
a17 8
   <indexterm zone="using-explain">
    <primary>EXPLAIN</primary>
   </indexterm>

   <indexterm zone="using-explain">
    <primary>query plan</primary>
   </indexterm>

a338 5
  <indexterm zone="planner-stats">
   <primary>statistics</primary>
   <secondary>of the planner</secondary>
  </indexterm>

a383 4
  <indexterm>
   <primary>pg_statistic</primary>
  </indexterm>

a395 4
  <indexterm>
   <primary>pg_stats</primary>
  </indexterm>

a540 5
  <indexterm zone="explicit-joins">
   <primary>join</primary>
   <secondary>controlling the order</secondary>
  </indexterm>

a701 4

   <indexterm zone="disable-autocommit">
    <primary>autocommit</primary>
   </indexterm>
@


1.29
log
@Small patch to link to the proper place in the "runtime" file,
and to add the "schemaname" column to the description of the
pg_stats view.

Greg Sabino Mullane
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.28 2003/03/25 16:15:37 petere Exp $
d69 1
a69 1
    <xref linkend="runtime-config-optimizer">.)
@


1.28
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/perform.sgml,v 1.27 2003/03/13 01:30:29 petere Exp $
d69 1
a69 1
    <xref linkend="runtime-config">.)
d438 6
@


1.27
log
@Big editing for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.26 2003/01/28 03:34:29 momjian Exp $
d68 2
a69 2
    factors, see the list of run-time configuration parameters in the
    &cite-admin;.)
d575 1
a575 1
   parameter described in the &cite-admin;.)
@


1.26
log
@Revert optimizer page count change.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.25 2003/01/27 22:40:56 momjian Exp $
d42 2
a43 2
       Estimated total cost (If all rows are retrieved, which they may not
       be --- a query with a <literal>LIMIT</> clause will stop short of paying the total cost,
d51 1
a51 1
       executed to completion.)
d77 2
a78 2
    result rows to the frontend --- which could be a pretty dominant
    factor in the true elapsed time, but the planner ignores it because
d86 2
a87 2
    processed/scanned by the query --- it is usually less, reflecting the
    estimated selectivity of any <literal>WHERE</>-clause constraints that are being
d94 1
a94 1
    Here are some examples (using the regress test database after a
d98 2
a99 1
regression=# EXPLAIN SELECT * FROM tenk1;
d123 2
a124 1
regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 1000;
d150 2
a151 1
regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 50;
d167 1
a167 1
    Add another clause to the <literal>WHERE</> condition:
d170 2
a171 2
regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 50 AND
regression-# stringu1 = 'xxx';
d179 1
a179 1
    The added clause <literal>stringu1 = 'xxx'</literal> reduces the
d189 1
a189 1
    Let's try joining two tables, using the fields we have been discussing:
d192 2
a193 2
regression=# EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 50
regression-# AND t1.unique2 = t2.unique2;
d209 1
a209 1
    because we are applying the <literal>unique1 &lt; 50</literal> <literal>WHERE</> clause at that node.
d224 1
a224 1
    In this example the loop's output row count is the same as the product
d226 1
a226 1
    in general you can have <literal>WHERE</> clauses that mention both relations and
d240 3
a242 4
regression=# SET enable_nestloop = off;
SET
regression=# EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 &lt; 50
regression-# AND t1.unique2 = t2.unique2;
d274 2
a275 3
regression=# EXPLAIN ANALYZE
regression-# SELECT * FROM tenk1 t1, tenk2 t2
regression-# WHERE t1.unique1 &lt; 50 AND t1.unique2 = t2.unique2;
d349 3
a351 3
   table and index.  This information is kept in
   <structname>pg_class</structname>'s <structfield>reltuples</structfield>
   and <structfield>relpages</structfield> columns.  We can look at it
d355 2
a356 2
regression=# SELECT relname, relkind, reltuples, relpages FROM pg_class
regression-# WHERE relname LIKE 'tenk1%';
d389 1
a389 1
   rows that match each clause of the <literal>WHERE</> condition.  The information
d392 1
a392 1
   updated by <command>ANALYZE</> and <command>VACUUM ANALYZE</> commands,
d402 1
a402 1
   <structname>pg_statistic</structname> is only readable by the superuser.
d410 2
a411 1
regression=# SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'road';
a416 1
regression=#
d432 1
a432 1
      <entry>Type</entry>
d441 1
a441 1
      <entry>Name of the table containing the column</entry>
d447 1
a447 1
      <entry>Column described by this row</entry>
d453 1
a453 1
      <entry>Fraction of column's entries that are null</entry>
d459 1
a459 1
      <entry>Average width in bytes of the column's entries</entry>
d492 1
a492 1
      <entry>histogram_bounds</entry>
d495 4
a498 4
      groups of approximately equal population.  The 
      <structfield>most_common_vals</>, if present, are omitted from the
      histogram calculation.  (Omitted if column data type does not have a
      <literal>&lt;</> operator, or if the <structfield>most_common_vals</>
d504 1
a504 1
      <entry>correlation</entry>
d510 1
a510 1
      of random access to the disk.  (Omitted if column data type does
d536 1
a536 1
   Beginning with <productname>PostgreSQL</productname> 7.1 it has been possible
d551 1
a551 1
   Or it could join A to C and then join them with B --- but that
d574 1
a574 1
   set by the <varname>GEQO_THRESHOLD</varname> run-time
d615 1
a615 1
   set the <varname>JOIN_COLLAPSE_LIMIT</> run-time parameter to 1.
d626 1
a626 1
   With <varname>JOIN_COLLAPSE_LIMIT</> = 1, this
d643 1
a643 1
   sub-SELECTs into their parent query.  For example, consider
d647 2
a648 2
     (SELECT * FROM a, b, c WHERE something) AS ss
WHERE somethingelse
d651 1
a651 1
   the view's SELECT rule will be inserted in place of the view reference,
d653 1
a653 1
   to collapse the sub-query into the parent, yielding
d655 1
a655 1
SELECT * FROM x, y, a, b, c WHERE something AND somethingelse
d657 2
a658 2
   This usually results in a better plan than planning the sub-query
   separately.  (For example, the outer WHERE conditions might be such that
d660 1
a660 1
   form the full logical output of the sub-select.)  But at the same time,
d665 2
a666 2
   problems by not collapsing a sub-query if more than
   <varname>FROM_COLLAPSE_LIMIT</> FROM-items would result in the parent
d672 1
a672 1
   <varname>FROM_COLLAPSE_LIMIT</> and <varname>JOIN_COLLAPSE_LIMIT</>
d674 6
a679 6
   when the planner will <quote>flatten out</> sub-SELECTs, and the
   other controls when it will flatten out explicit inner JOINs.  Typically
   you would either set <varname>JOIN_COLLAPSE_LIMIT</> equal to
   <varname>FROM_COLLAPSE_LIMIT</> (so that explicit JOINs and sub-SELECTs
   act similarly) or set <varname>JOIN_COLLAPSE_LIMIT</> to 1 (if you want
   to control join order with explicit JOINs).  But you might set them
d705 1
a705 1
    record added.
d707 2
a708 2
    is that if the insertion of one record were to fail then the
    insertion of all records inserted up to that point would be rolled
d714 1
a714 1
   <title>Use COPY FROM</title>
d717 1
a717 1
    Use <command>COPY FROM STDIN</command> to load all the records in one
d734 1
a734 1
    updating it incrementally as each record is loaded.
d738 2
a739 2
    If you are augmenting an existing table, you can <command>DROP
    INDEX</command>, load the table, then recreate the index. Of
d748 1
a748 1
   <title>Run ANALYZE Afterwards</title>
@


1.25
log
@Fix typo 233 pages -> 333 pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.24 2003/01/25 23:10:27 tgl Exp $
d112 2
a113 2
    you will find out that <classname>tenk1</classname> has 333 disk
    pages and 10000 rows.  So the cost is estimated at 333 page
@


1.24
log
@Allow the planner to collapse explicit inner JOINs together, rather than
necessarily following the JOIN syntax to develop the query plan.  The old
behavior is still available by setting GUC variable JOIN_COLLAPSE_LIMIT
to 1.  Also create a GUC variable FROM_COLLAPSE_LIMIT to control the
similar decision about when to collapse sub-SELECT lists into their parent
lists.  (This behavior existed already, but the limit was always
GEQO_THRESHOLD/2; now it's separately adjustable.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.23 2003/01/12 18:42:59 tgl Exp $
d112 2
a113 2
    you will find out that <classname>tenk1</classname> has 233 disk
    pages and 10000 rows.  So the cost is estimated at 233 page
@


1.23
log
@Fix some minor grammatical errors.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.22 2002/11/11 20:14:03 petere Exp $
d594 7
a600 4
   The <productname>PostgreSQL</productname> query planner treats all
   explicit <literal>JOIN</> syntaxes as constraining the join order, even though
   it is not logically necessary to make such a constraint for inner
   joins.  Therefore, although all of these queries give the same result:
d606 1
d613 6
d620 2
a621 2
   cut search time, because it's OK to use <literal>JOIN</> operators in a plain
   <literal>FROM</> list.  For example,
d625 1
d632 36
a667 12
   If you have a mix of outer and inner joins in a complex query, you
   might not want to constrain the planner's search for a good ordering
   of inner joins inside an outer join.  You can't do that directly in the
   <literal>JOIN</> syntax, but you can get around the syntactic limitation by using
   subselects.  For example,
<programlisting>
SELECT * FROM d LEFT JOIN
        (SELECT * FROM a, b, c WHERE ...) AS ss
        ON (...);
</programlisting>
   Here, joining to D must be the last step in the query plan, but the
   planner is free to consider various join orders for A, B, and C.
d671 10
a680 5
   Constraining the planner's search in this way is a useful technique
   both for reducing planning time and for directing the planner to a
   good query plan.  If the planner chooses a bad join order by default,
   you can force it to choose a better order via <literal>JOIN</> syntax --- assuming
   that you know of a better order, that is.  Experimentation is recommended.
@


1.22
log
@Merge documentation updates from 7.3 branch.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 petere Exp $
d603 1
a603 1
   but the second and third take less time to plan than the first.  This effect
d631 2
a632 2
   Here, joining D must be the last step in the query plan, but the
   planner is free to consider various join orders for A, B, C.
@


1.21
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.20 2002/03/24 17:11:37 tgl Exp $
d35 2
a36 2
       Estimated start-up cost (time expended before output scan can start,
       e.g., time to do the sorting in a SORT node).
d42 3
a44 3
       Estimated total cost (if all tuples are retrieved, which they may not
       be --- a query with a LIMIT will stop short of paying the total cost,
       for example).
d50 2
a51 2
       Estimated number of rows output by this plan node (again, only if
       executed to completion).
d58 1
a58 1
       node.
d67 1
a67 1
    fairly arbitrary fudge-factors. If you want to experiment with these
d69 1
a69 1
    <citetitle>Administrator's Guide</citetitle>.)
d77 1
a77 1
    result tuples to the frontend --- which could be a pretty dominant
d80 1
a80 1
    output the same tuple set, we trust.)
d87 1
a87 1
    estimated selectivity of any WHERE-clause constraints that are being
d95 1
a95 1
    vacuum analyze, and 7.3 development sources):
d97 1
a97 1
    <programlisting>
d102 1
a102 1
    </programlisting>
d108 1
a108 1
    <programlisting>
d110 1
a110 1
    </programlisting>
d113 3
a115 3
    pages and 10000 tuples.  So the cost is estimated at 233 page
    reads, defined as 1.0 apiece, plus 10000 * <varname>cpu_tuple_cost</varname> which is
    currently 0.01 (try <command>show cpu_tuple_cost</command>).
d119 1
a119 1
    Now let's modify the query to add a WHERE condition:
d121 1
a121 1
    <programlisting>
d127 1
a127 1
    </programlisting>
d129 1
a129 1
    The estimate of output rows has gone down because of the WHERE clause.
d132 1
a132 1
    time spent checking the WHERE condition.
d147 1
a147 1
    <programlisting>
d153 1
a153 1
    </programlisting>
d155 1
a155 1
    and you will see that if we make the WHERE condition selective
d158 1
a158 1
    This plan will only have to visit 50 tuples because of the index,
d164 1
a164 1
    Add another clause to the WHERE condition:
d166 1
a166 1
    <programlisting>
d174 1
a174 1
    </programlisting>
d178 1
a178 1
    same set of tuples.  Notice that the <literal>stringu1</> clause
d188 1
a188 1
    <programlisting>
d200 1
a200 1
    </programlisting>
d206 1
a206 1
    because we are applying the <literal>unique1 &lt; 50</literal> WHERE clause at that node.
d208 1
a208 1
    affect row count of the outer scan.  For the inner scan, the unique2 value of the
d210 1
a210 1
    outer-scan tuple is plugged into the inner index scan
d213 2
a214 2
     same inner-scan plan and costs that we'd get from, say, <literal>explain select
     * from tenk2 where unique2 = 42</literal>.  The costs of the loop node are then set
d216 1
a216 1
     inner scan for each outer tuple (49 * 3.01, here), plus a little CPU
d223 1
a223 1
    in general you can have WHERE clauses that mention both relations and
d236 3
a238 3
    <programlisting>
regression=# set enable_nestloop = off;
SET VARIABLE
d250 1
a250 1
    </programlisting>
d255 1
a255 1
    for possible matches of <literal>t1.unique2 = t2.unique2</literal> at each <classname>tenk2</classname> tuple.
d257 1
a257 1
    cost for the hash join, since we won't get any tuples out until we can
d259 2
a260 2
    includes a hefty charge for CPU time to probe the hash table
    10000 times.  Note, however, that we are NOT charging 10000 times 179.33;
d266 1
a266 1
    by using EXPLAIN ANALYZE.  This command actually executes the query,
d268 1
a268 1
    along with the same estimated costs that a plain EXPLAIN shows.
d299 1
a299 1
    tuple in the above nested-loop plan.  In such cases, the
d310 3
a312 3
    executor start-up and shutdown time, as well as time spent processing
    the result tuples.  It does not include parsing, rewriting, or planning
    time.  For a SELECT query, the total run time will normally be just a
d314 1
a314 1
    For INSERT, UPDATE, and DELETE queries, the total run time may be
d316 2
a317 2
    result tuples.  In these queries, the time for the top plan node
    essentially is the time spent computing the new tuples and/or locating
d322 1
a322 1
    It is worth noting that EXPLAIN results should not be extrapolated
d336 1
a336 1
  <title>Statistics used by the Planner</title>
d354 2
a355 2
regression=# select relname, relkind, reltuples, relpages from pg_class
regression-# where relname like 'tenk1%';
d385 1
a385 1
   to having WHERE clauses that restrict the rows to be examined.
d387 2
a388 2
   <firstterm>selectivity</> of WHERE clauses, that is, the fraction of
   rows that match each clause of the WHERE condition.  The information
d409 1
a409 1
regression=# select attname, n_distinct, most_common_vals from pg_stats where tablename = 'road';
d417 1
d419 3
a421 2
   As of <productname>PostgreSQL</productname> 7.2 the following columns exist
   in <structname>pg_stats</structname>:
d424 1
a424 1
  <table>
d440 1
a440 1
      <entry>Name of table containing column</entry>
d452 1
a452 1
      <entry>Fraction of column's entries that are NULL</entry>
d458 1
a458 1
      <entry>Average width in bytes of column's entries</entry>
d467 1
a467 1
      is used when ANALYZE believes that the number of distinct values
d486 1
a486 1
      ie, number of occurrences of each divided by total number of rows.
d535 2
a536 2
   Beginning with <productname>PostgreSQL</productname> 7.1 it is possible
   to control the query planner to some extent by using explicit <literal>JOIN</>
d542 19
a560 17
    <programlisting>
SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id;
    </programlisting>
   the planner is free to join the given tables in any order.  For example,
   it could generate a query plan that joins A to B, using the WHERE clause
   a.id = b.id, and then joins C to this joined table, using the other
   WHERE clause.  Or it could join B to C and then join A to that result.
   Or it could join A to C and then join them with B --- but that would
   be inefficient, since the full Cartesian product of A and C would have
   to be formed, there being no applicable WHERE clause to allow optimization
   of the join.
   (All joins in the <productname>PostgreSQL</productname> executor happen
   between two input tables, so it's necessary to build up the result in one
   or another of these fashions.)  The important point is that these different
   join possibilities give semantically equivalent results but may have hugely
   different execution costs.  Therefore, the planner will explore all of them
   to try to find the most efficient query plan.
d574 1
a574 1
   parameter described in the <citetitle>Administrator's Guide</citetitle>.)
d582 1
a582 1
    <programlisting>
d584 1
a584 1
    </programlisting>
d594 2
a595 2
   In <productname>PostgreSQL</productname> 7.1, the planner treats all
   explicit JOIN syntaxes as constraining the join order, even though
d598 2
a599 2
    <programlisting>
SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id;
d602 2
a603 2
    </programlisting>
   the second and third take less time to plan than the first.  This effect
d610 3
a612 3
   cut search time, because it's OK to use JOIN operators in a plain
   FROM list.  For example,
    <programlisting>
d614 1
a614 1
    </programlisting>
d624 1
a624 1
   JOIN syntax, but you can get around the syntactic limitation by using
d626 1
a626 1
    <programlisting>
d630 1
a630 1
    </programlisting>
d632 1
a632 1
   planner is free to consider various join orders for A,B,C.
d639 1
a639 1
   you can force it to choose a better order via JOIN syntax --- assuming
d665 4
d707 1
a707 1
   <title>ANALYZE Afterwards</title>
@


1.21.2.1
log
@Cleanup pass over User's Guide.  Key word table updated.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 petere Exp $
d35 2
a36 2
       Estimated start-up cost (Time expended before output scan can start,
       e.g., time to do the sorting in a sort node.)
d42 3
a44 3
       Estimated total cost (If all rows are retrieved, which they may not
       be --- a query with a <literal>LIMIT</> clause will stop short of paying the total cost,
       for example.)
d50 2
a51 2
       Estimated number of rows output by this plan node (Again, only if
       executed to completion.)
d58 1
a58 1
       node
d67 1
a67 1
    fairly arbitrary fudge factors. If you want to experiment with these
d69 1
a69 1
    &cite-admin;.)
d77 1
a77 1
    result rows to the frontend --- which could be a pretty dominant
d80 1
a80 1
    output the same row set, we trust.)
d87 1
a87 1
    estimated selectivity of any <literal>WHERE</>-clause constraints that are being
d95 1
a95 1
    <literal>VACUUM ANALYZE</>, and 7.3 development sources):
d97 1
a97 1
<programlisting>
d102 1
a102 1
</programlisting>
d108 1
a108 1
<programlisting>
d110 1
a110 1
</programlisting>
d113 3
a115 3
    pages and 10000 rows.  So the cost is estimated at 233 page
    reads, defined as costing 1.0 apiece, plus 10000 * <varname>cpu_tuple_cost</varname> which is
    currently 0.01 (try <command>SHOW cpu_tuple_cost</command>).
d119 1
a119 1
    Now let's modify the query to add a <literal>WHERE</> condition:
d121 1
a121 1
<programlisting>
d127 1
a127 1
</programlisting>
d129 1
a129 1
    The estimate of output rows has gone down because of the <literal>WHERE</> clause.
d132 1
a132 1
    time spent checking the <literal>WHERE</> condition.
d147 1
a147 1
<programlisting>
d153 1
a153 1
</programlisting>
d155 1
a155 1
    and you will see that if we make the <literal>WHERE</> condition selective
d158 1
a158 1
    This plan will only have to visit 50 rows because of the index,
d164 1
a164 1
    Add another clause to the <literal>WHERE</> condition:
d166 1
a166 1
<programlisting>
d174 1
a174 1
</programlisting>
d178 1
a178 1
    same set of rows.  Notice that the <literal>stringu1</> clause
d188 1
a188 1
<programlisting>
d200 1
a200 1
</programlisting>
d206 1
a206 1
    because we are applying the <literal>unique1 &lt; 50</literal> <literal>WHERE</> clause at that node.
d208 1
a208 1
    affect row count of the outer scan.  For the inner scan, the <literal>unique2</> value of the
d210 1
a210 1
    outer-scan row is plugged into the inner index scan
d213 2
a214 2
     same inner-scan plan and costs that we'd get from, say, <literal>EXPLAIN SELECT
     * FROM tenk2 WHERE unique2 = 42</literal>.  The costs of the loop node are then set
d216 1
a216 1
     inner scan for each outer row (49 * 3.01, here), plus a little CPU
d223 1
a223 1
    in general you can have <literal>WHERE</> clauses that mention both relations and
d236 3
a238 3
<programlisting>
regression=# SET enable_nestloop = off;
SET
d250 1
a250 1
</programlisting>
d255 1
a255 1
    for possible matches of <literal>t1.unique2 = t2.unique2</literal> at each <classname>tenk2</classname> row.
d257 1
a257 1
    cost for the hash join, since we won't get any rows out until we can
d259 2
a260 2
    includes a hefty charge for the CPU time to probe the hash table
    10000 times.  Note, however, that we are <emphasis>not</emphasis> charging 10000 times 179.33;
d266 1
a266 1
    by using <command>EXPLAIN ANALYZE</>.  This command actually executes the query,
d268 1
a268 1
    along with the same estimated costs that a plain <command>EXPLAIN</command> shows.
d299 1
a299 1
    row in the above nested-loop plan.  In such cases, the
d310 3
a312 3
    executor start-up and shut-down time, as well as time spent processing
    the result rows.  It does not include parsing, rewriting, or planning
    time.  For a <command>SELECT</> query, the total run time will normally be just a
d314 1
a314 1
    For <command>INSERT</>, <command>UPDATE</>, and <command>DELETE</> commands, the total run time may be
d316 2
a317 2
    result rows.  In these commands, the time for the top plan node
    essentially is the time spent computing the new rows and/or locating
d322 1
a322 1
    It is worth noting that <command>EXPLAIN</> results should not be extrapolated
d336 1
a336 1
  <title>Statistics Used by the Planner</title>
d354 2
a355 2
regression=# SELECT relname, relkind, reltuples, relpages FROM pg_class
regression-# WHERE relname LIKE 'tenk1%';
d385 1
a385 1
   to having <literal>WHERE</> clauses that restrict the rows to be examined.
d387 2
a388 2
   <firstterm>selectivity</> of <literal>WHERE</> clauses, that is, the fraction of
   rows that match each clause of the <literal>WHERE</> condition.  The information
d409 1
a409 1
regression=# SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'road';
a416 1
  </para>
d418 2
a419 3
  <para>
   <xref linkend="planner-pg-stats-table"> shows the columns that
   exist in <structname>pg_stats</structname>.
d422 1
a422 1
  <table id="planner-pg-stats-table">
d438 1
a438 1
      <entry>Name of the table containing the column</entry>
d450 1
a450 1
      <entry>Fraction of column's entries that are null</entry>
d456 1
a456 1
      <entry>Average width in bytes of the column's entries</entry>
d465 1
a465 1
      is used when <command>ANALYZE</> believes that the number of distinct values
d484 1
a484 1
      i.e., number of occurrences of each divided by total number of rows.
d533 2
a534 2
   Beginning with <productname>PostgreSQL</productname> 7.1 it has been possible
   to control the query planner to some extent by using the explicit <literal>JOIN</>
d540 17
a556 19
<programlisting>
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
</programlisting>
   the planner is free to join the given tables in any order.  For
   example, it could generate a query plan that joins A to B, using
   the <literal>WHERE</> condition <literal>a.id = b.id</>, and then
   joins C to this joined table, using the other <literal>WHERE</>
   condition.  Or it could join B to C and then join A to that result.
   Or it could join A to C and then join them with B --- but that
   would be inefficient, since the full Cartesian product of A and C
   would have to be formed, there being no applicable condition in the
   <literal>WHERE</> clause to allow optimization of the join.  (All
   joins in the <productname>PostgreSQL</productname> executor happen
   between two input tables, so it's necessary to build up the result
   in one or another of these fashions.)  The important point is that
   these different join possibilities give semantically equivalent
   results but may have hugely different execution costs.  Therefore,
   the planner will explore all of them to try to find the most
   efficient query plan.
d570 1
a570 1
   parameter described in the &cite-admin;.)
d578 1
a578 1
<programlisting>
d580 1
a580 1
</programlisting>
d590 2
a591 2
   The <productname>PostgreSQL</productname> query planner treats all
   explicit <literal>JOIN</> syntaxes as constraining the join order, even though
d594 2
a595 2
<programlisting>
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
d598 2
a599 2
</programlisting>
   but the second and third take less time to plan than the first.  This effect
d606 3
a608 3
   cut search time, because it's OK to use <literal>JOIN</> operators in a plain
   <literal>FROM</> list.  For example,
<programlisting>
d610 1
a610 1
</programlisting>
d620 1
a620 1
   <literal>JOIN</> syntax, but you can get around the syntactic limitation by using
d622 1
a622 1
<programlisting>
d626 1
a626 1
</programlisting>
d628 1
a628 1
   planner is free to consider various join orders for A, B, C.
d635 1
a635 1
   you can force it to choose a better order via <literal>JOIN</> syntax --- assuming
a660 4
    An additional benefit of doing all insertions in one transaction
    is that if the insertion of one record were to fail then the
    insertion of all records inserted up to that point would be rolled
    back, so you won't be stuck with partially loaded data.
d699 1
a699 1
   <title>Run ANALYZE Afterwards</title>
@


1.20
log
@Tweak labeling of plan qual conditions for more consistency.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.19 2002/03/24 04:31:05 tgl Exp $
d530 1
a530 1
  <title>Controlling the Planner with Explicit JOINs</title>
d534 1
a534 1
   to control the query planner to some extent by using explicit JOIN
@


1.19
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/perform.sgml,v 1.18 2002/03/22 19:20:17 petere Exp $
d119 1
a119 1
    Now let's modify the query to add a qualification clause:
d145 1
a145 1
    Modify the query to restrict the qualification even more:
d152 1
a152 1
   Index Filter: (unique1 &lt; 50)
d164 1
a164 1
    Add another condition to the qualification:
d172 1
a172 1
   Index Filter: (unique1 &lt; 50)
d196 1
a196 1
         Index Filter: (unique1 &lt; 50)
d199 1
a199 1
         Index Filter: ("outer".unique2 = t2.unique2)
d211 1
a211 1
    to produce an index qualification like
d249 1
a249 1
               Index Filter: (unique1 &lt; 50)
d282 1
a282 1
         Index Filter: (unique1 &lt; 50)
d286 1
a286 1
         Index Filter: ("outer".unique2 = t2.unique2)
@


1.18
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.17 2002/03/06 06:44:31 momjian Exp $
d50 2
a51 2
       Estimated number of rows output by this plan node (again, without
       regard for any LIMIT).
d95 1
a95 1
    vacuum analyze, and 7.2 development sources):
d99 3
a101 3
INFO:  QUERY PLAN:

Seq Scan on tenk1  (cost=0.00..333.00 rows=10000 width=148)
d123 4
a126 3
INFO:  QUERY PLAN:

Seq Scan on tenk1  (cost=0.00..358.00 rows=1007 width=148)
d149 4
a152 3
INFO:  QUERY PLAN:

Index Scan using tenk1_unique1 on tenk1  (cost=0.00..181.09 rows=49 width=148)
d169 5
a173 3
INFO:  QUERY PLAN:

Index Scan using tenk1_unique1 on tenk1  (cost=0.00..181.22 rows=1 width=148)
d176 7
a182 2
    The added clause <literal>stringu1 = 'xxx'</literal> reduces the output-rows estimate,
    but not the cost because we still have to visit the same set of tuples.
d191 9
a199 7
INFO:  QUERY PLAN:

Nested Loop  (cost=0.00..330.41 rows=49 width=296)
  -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
               (cost=0.00..181.09 rows=49 width=148)
  -&gt;  Index Scan using tenk2_unique2 on tenk2 t2
               (cost=0.00..3.01 rows=1 width=148)
d241 9
a249 8
INFO:  QUERY PLAN:

Hash Join  (cost=181.22..564.83 rows=49 width=296)
  -&gt;  Seq Scan on tenk2 t2
               (cost=0.00..333.00 rows=10000 width=148)
  -&gt;  Hash  (cost=181.09..181.09 rows=49 width=148)
        -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
               (cost=0.00..181.09 rows=49 width=148)
d260 1
a260 1
    10000 times.  Note, however, that we are NOT charging 10000 times 181.09;
d275 13
a287 8
INFO:  QUERY PLAN:

Nested Loop  (cost=0.00..330.41 rows=49 width=296) (actual time=1.31..28.90 rows=50 loops=1)
  -&gt;  Index Scan using tenk1_unique1 on tenk1 t1
               (cost=0.00..181.09 rows=49 width=148) (actual time=0.69..8.84 rows=50 loops=1)
  -&gt;  Index Scan using tenk2_unique2 on tenk2 t2
               (cost=0.00..3.01 rows=1 width=148) (actual time=0.28..0.31 rows=1 loops=50)
Total runtime: 30.67 msec
d316 1
a316 1
    output tuples.  In these queries, the time for the top plan node
@


1.17
log
@Update docs for new INFO, NOTICE, WARNING elog() levels.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.16 2002/01/20 22:19:56 petere Exp $
d255 1
a255 1
    and then displays the true runtime accumulated within each plan node
d292 2
a293 2
    The <quote>total runtime</quote> shown by EXPLAIN ANALYZE includes
    executor startup and shutdown time, as well as time spent processing
d295 1
a295 1
    time.  For a SELECT query, the total runtime will normally be just a
d297 1
a297 1
    For INSERT, UPDATE, and DELETE queries, the total runtime may be
@


1.16
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.15 2001/11/28 20:49:10 petere Exp $
d99 1
a99 1
NOTICE:  QUERY PLAN:
d123 1
a123 1
NOTICE:  QUERY PLAN:
d148 1
a148 1
NOTICE:  QUERY PLAN:
d167 1
a167 1
NOTICE:  QUERY PLAN:
d182 1
a182 1
NOTICE:  QUERY PLAN:
d230 1
a230 1
NOTICE:  QUERY PLAN:
d263 1
a263 1
NOTICE:  QUERY PLAN:
@


1.15
log
@proof-reading
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.14 2001/11/21 05:53:41 thomas Exp $
d406 1
a406 1
   <title>pg_stats Columns</title>
d419 1
a419 1
      <entry>tablename</entry>
d425 1
a425 1
      <entry>attname</entry>
d431 1
a431 1
      <entry>null_frac</entry>
d437 1
a437 1
      <entry>avg_width</entry>
d443 1
a443 1
      <entry>n_distinct</entry>
d457 1
a457 1
      <entry>most_common_vals</entry>
d464 1
a464 1
      <entry>most_common_freqs</entry>
d477 1
a477 1
      histogram calculation.  (Omitted if column datatype does not have a
d488 1
a488 1
      When the value is near -1 or +1, an indexscan on the column will
d490 1
a490 1
      of random access to the disk.  (Omitted if column datatype does
@


1.14
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.13 2001/10/16 01:13:44 tgl Exp $
d633 1
a633 1
   <title>Disable Auto-commit</title>
d636 1
a636 1
    Turn off auto-commit and just do one commit at
d654 3
a656 3
    planning, etc
    overhead a great deal. If you do this then it's not necessary to fool
    around with auto-commit, since it's only one command anyway.
d676 2
a677 2
    think twice before dropping UNIQUE indexes, since the error checking
    afforded by the UNIQUE constraint will be lost while the index is missing.
@


1.13
log
@Add a section about the planner's statistics, including a description
of the new pg_stats view.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.12 2001/10/12 23:32:34 momjian Exp $
d12 1
a12 1
   and tuning <productname>Postgres</productname> performance.
d19 1
a19 1
    <productname>Postgres</productname> devises a <firstterm>query
d401 1
a401 1
   As of <productname>Postgres</productname> 7.2 the following columns exist
d516 1
a516 1
   Beginning with <productname>Postgres</productname> 7.1 it is possible
d534 1
a534 1
   (All joins in the <productname>Postgres</productname> executor happen
d549 1
a549 1
   <productname>Postgres</productname> planner will switch from exhaustive
d573 1
a573 1
   In <productname>Postgres</productname> 7.1, the planner treats all
d642 1
a642 1
    <productname>Postgres</productname> is doing a lot of work for each
@


1.12
log
@Uppercase keywords where appropriate.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.11 2001/10/09 18:46:00 petere Exp $
d317 194
@


1.11
log
@Bunch of copy fitting and style sheet tweakage to get decent looking print
output (from pdfjadetex).  Also updated instructions to install documentation
processing toolchain.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.10 2001/09/18 01:59:05 tgl Exp $
d98 1
a98 1
regression=# explain select * from tenk1;
d109 1
a109 1
select * from pg_class where relname = 'tenk1';
d122 1
a122 1
regression=# explain select * from tenk1 where unique1 &lt; 1000;
d147 1
a147 1
regression=# explain select * from tenk1 where unique1 &lt; 50;
d165 1
a165 1
regression=# explain select * from tenk1 where unique1 &lt; 50 and
d180 2
a181 2
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 &lt; 50
regression-# and t1.unique2 = t2.unique2;
d228 2
a229 2
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 &lt; 50
regression-# and t1.unique2 = t2.unique2;
d260 3
a262 3
regression=# explain analyze
regression-# select * from tenk1 t1, tenk2 t2
regression-#          where t1.unique1 &lt; 50 and t1.unique2 = t2.unique2;
@


1.10
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 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.9 2001/09/13 15:55:23 petere Exp $
d259 4
a262 3
    <programlisting>
regression=# explain analyze select * from tenk1 t1, tenk2 t2 where t1.unique1 &lt; 50
regression-# and t1.unique2 = t2.unique2;
d271 1
a271 1
    </programlisting>
d281 1
a281 1
    than once.  For example, the inner indexscan is executed once per outer
@


1.9
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.8 2001/09/09 17:21:59 petere Exp $
d125 1
a125 1
Seq Scan on tenk1  (cost=0.00..358.00 rows=1003 width=148)
d150 1
a150 1
Index Scan using tenk1_unique1 on tenk1  (cost=0.00..173.32 rows=47 width=148)
d169 1
a169 1
Index Scan using tenk1_unique1 on tenk1  (cost=0.00..173.44 rows=1 width=148)
d184 1
a184 1
Nested Loop  (cost=0.00..269.11 rows=47 width=296)
d186 1
a186 1
               (cost=0.00..173.32 rows=47 width=148)
d188 1
a188 1
               (cost=0.00..2.01 rows=1 width=148)
d205 1
a205 1
     inner scan for each outer tuple (47 * 2.01, here), plus a little CPU
d232 1
a232 1
Hash Join  (cost=173.44..557.03 rows=47 width=296)
d235 1
a235 1
  -&gt;  Hash  (cost=173.32..173.32 rows=47 width=148)
d237 1
a237 1
               (cost=0.00..173.32 rows=47 width=148)
d248 1
a248 1
    10000 times.  Note, however, that we are NOT charging 10000 times 173.32;
d250 51
@


1.8
log
@Markup additions and spell check. (covers User's Guide)
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.7 2001/06/22 18:53:36 tgl Exp $
d195 2
a196 2
    because we are applying the "unique1 &lt; 50" WHERE clause at that node.
    The "t1.unique2 = t2.unique2" clause isn't relevant yet, so it doesn't
d201 1
a201 1
    "t2.unique2 = <replaceable>constant</replaceable>".  So we get the
d214 1
a214 1
    For example, if we added "WHERE ... AND t1.hundred &lt; t2.hundred",
d243 1
a243 1
    for possible matches of "t1.unique2 = t2.unique2" at each <classname>tenk2</classname> tuple.
@


1.7
log
@Mention that EXPLAIN results on small tables shouldn't be extrapolated
to large tables.  Recommend ANALYZE or VACUUM ANALYZE after populating
a table.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.6 2001/06/11 00:52:09 tgl Exp $
d112 1
a112 1
    you'll find out that tenk1 has 233 disk
d114 1
a114 1
    reads, defined as 1.0 apiece, plus 10000 * cpu_tuple_cost which is
d155 1
a155 1
    eventually decide that an indexscan is cheaper than a sequential scan.
d172 1
a172 1
    The added clause "stringu1 = 'xxx'" reduces the output-rows estimate,
d193 1
a193 1
    In this nested-loop join, the outer scan is the same indexscan we had
d197 1
a197 1
    affect the outer scan's row count.  For the inner scan, the
d199 2
a200 2
    outer-scan tuple's unique2 value is plugged into the inner indexscan
    to produce an indexqual like
d202 3
a204 3
     same inner-scan plan and costs that we'd get from, say, "explain select
     * from tenk2 where unique2 = 42".  The loop node's costs are then set
     on the basis of the outer scan's cost, plus one repetition of the
d215 1
a215 1
    that'd decrease the output row count of the join node, but not change
d240 5
a244 5
    This plan proposes to extract the 50 interesting rows of tenk1
    using ye same olde indexscan, stash them into an in-memory hash table,
    and then do a sequential scan of tenk2, probing into the hash table
    for possible matches of "t1.unique2 = t2.unique2" at each tenk2 tuple.
    The cost to read tenk1 and set up the hash table is entirely start-up
d246 1
a246 1
    start reading tenk2.  The total time estimate for the join also
d305 2
a306 2
   through a limited number of possibilities.  (The switchover threshold is
   set by the GEQO_THRESHOLD run-time
@


1.6
log
@Update EXPLAIN discussion and examples to match current sources.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.5 2001/05/17 21:50:16 petere Exp $
d113 1
a113 1
    pages and 10000 tuples.  So the cost is estimated at 233 block
d251 13
d391 7
a397 4
    the end.  Otherwise <productname>Postgres</productname> is doing a
    lot of work for each record
    added.  In general when you are doing bulk inserts, you want
    to turn off some of the database features to gain speed.
d406 3
a408 2
    command, instead
    of a series of INSERT commands.  This reduces parsing, planning, etc
d410 1
a410 1
    around with autocommit, since it's only one command anyway.
d419 2
a420 1
    create the table, bulk-load with COPY, then create any indexes needed
d427 1
a427 1
     INDEX</command>, load the table, then recreate the index. Of
d429 16
a444 1
    affected during the time that the index is missing.
@


1.5
log
@Change "indices" to "indexes", per OED.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.4 2001/05/09 00:35:09 tgl Exp $
a17 7
   <note>
    <title>Author</title>
    <para>
     Written by Tom Lane, from e-mail dated 2000-03-27.
    </para>
   </note>

d24 3
a26 3
    creates for any query.  Unfortunately,
    plan-reading is an art that deserves a tutorial, and I haven't
    had time to write one.  Here is some quick &amp; dirty explanation.
d30 1
a30 1
    The numbers that are currently quoted by EXPLAIN are:
d90 1
a90 1
    by the query (again, without considering the effects of LIMIT).
d95 1
a95 1
    vacuum analyze, and almost-7.0 sources):
d125 1
a125 1
Seq Scan on tenk1  (cost=0.00..358.00 rows=1000 width=148)
d129 12
a140 7
    (This estimate is uncannily accurate because tenk1 is a particularly
    simple case --- the unique1 column has 10000 distinct values ranging
    from 0 to 9999, so the estimator's linear interpolation between min and
    max column values is dead-on.)  However, the scan will still have to
    visit all 10000 rows, so the cost hasn't decreased; in fact it has gone
    up a bit to reflect the extra CPU time spent checking the WHERE
    condition.
d147 1
a147 1
regression=# explain select * from tenk1 where unique1 &lt; 100;
d150 1
a150 1
Index Scan using tenk1_unique1 on tenk1  (cost=0.00..89.35 rows=100 width=148)
d156 3
a158 2
    This plan will only have to visit 100 tuples because of the index,
    so it wins despite the fact that each individual fetch is expensive.
d165 1
a165 1
regression=# explain select * from tenk1 where unique1 &lt; 100 and
d169 1
a169 1
Index Scan using tenk1_unique1 on tenk1  (cost=0.00..89.60 rows=1 width=148)
d180 1
a180 1
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 &lt; 100
d184 1
a184 1
Nested Loop  (cost=0.00..144.07 rows=100 width=296)
d186 1
a186 1
             (cost=0.00..89.35 rows=100 width=148)
d188 1
a188 1
             (cost=0.00..0.53 rows=1 width=148)
d195 1
a195 1
    because we are applying the "unique1 &lt; 100" WHERE clause at that node.
d205 1
a205 1
     inner scan for each outer tuple (100 * 0.53, here), plus a little CPU
d228 1
a228 1
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 < 100
d232 1
a232 1
Hash Join  (cost=89.60..574.10 rows=100 width=296)
d235 1
a235 1
  -&gt;  Hash  (cost=89.35..89.35 rows=100 width=148)
d237 1
a237 1
               (cost=0.00..89.35 rows=100 width=148)
d240 1
a240 1
    This plan proposes to extract the 100 interesting rows of tenk1
d247 2
a248 2
    includes a pretty hefty charge for CPU time to probe the hash table
    10000 times.  Note, however, that we are NOT charging 10000 times 89.35;
@


1.4
log
@Cause planner to make use of average-column-width statistic that is now
collected by ANALYZE.  Also, add some modest amount of intelligence to
guesses that are used for varlena columns in the absence of any ANALYZE
statistics.  The 'width' reported by EXPLAIN is finally something less
than totally bogus for varlena columns ... and, in consequence, hashjoin
estimating should be a little better ...
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.3 2001/03/24 23:03:26 petere Exp $
d398 2
a399 2
  <sect2 id="populate-rm-indices">
   <title>Remove Indices</title>
@


1.3
log
@minor copy editing
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.2 2001/02/19 00:24:30 tgl Exp $
a97 7
   </para>

   <para>
    Average width is pretty bogus because the thing really doesn't have
    any idea of the average length of variable-length columns.  I'm thinking
    about improving that in the future, but it may not be worth the trouble,
    because the width isn't used for very much.
@


1.2
log
@Update example of partially constraining join order to use a subselect
in FROM instead of an auxiliary view.  We didn't have subselect-in-FROM
when I wrote this originally...
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.1 2000/12/16 02:29:36 tgl Exp $
d43 1
a43 1
       eg, time to do the sorting in a SORT node).
@


1.1
log
@Restructure performance tips into a single chapter ('populating a
database' was way too small to make a chapter).  Add a section about
using JOIN syntax to direct the planner.
@
text
@d2 1
a2 1
$Header: $
d353 1
a353 1
   views.  For example,
d355 3
a357 2
CREATE VIEW v1 AS SELECT ... FROM a, b, c WHERE ...;
SELECT * FROM d LEFT JOIN v1 ON (...);
d401 1
a401 1
    around with autocommit.
@
