head	1.30;
access;
symbols
	REL9_0_0:1.30
	REL9_1_ALPHA1:1.30
	REL9_0_RC1:1.30
	REL9_0_BETA4:1.30
	REL9_0_STABLE:1.30.0.2
	REL9_0_BETA3:1.30
	REL9_0_BETA2:1.29
	REL7_4_29:1.16
	REL8_0_25:1.19
	REL8_1_21:1.19
	REL8_2_17:1.20
	REL8_3_11:1.23
	REL8_4_4:1.25
	REL9_0_BETA1:1.29
	REL9_0_ALPHA5_BRANCH:1.28.0.4
	REL9_0_ALPHA5:1.28
	REL7_4_28:1.16
	REL8_0_24:1.19
	REL8_1_20:1.19
	REL8_2_16:1.20
	REL8_3_10:1.23
	REL8_4_3:1.25
	REL9_0_ALPHA4:1.28
	REL9_0_ALPHA4_BRANCH:1.28.0.2
	REL8_5_ALPHA3:1.27
	REL8_5_ALPHA3_BRANCH:1.27.0.6
	REL7_4_27:1.16
	REL8_0_23:1.19
	REL8_1_19:1.19
	REL8_2_15:1.20
	REL8_3_9:1.23
	REL8_4_2:1.25
	REL8_5_ALPHA2:1.27
	REL8_5_ALPHA2_BRANCH:1.27.0.4
	REL7_4_26:1.16
	REL8_0_22:1.19
	REL8_1_18:1.19
	REL8_2_14:1.20
	REL8_3_8:1.23
	REL8_4_1:1.25
	REL8_5_ALPHA1:1.27
	REL8_5_ALPHA1_BRANCH:1.27.0.2
	REL8_4_STABLE:1.25.0.2
	REL8_4_0:1.25
	REL8_4_RC2:1.25
	REL8_4_RC1:1.25
	REL8_4_BETA2:1.25
	REL8_4_BETA1:1.25
	REL7_4_25:1.16
	REL8_0_21:1.19
	REL8_1_17:1.19
	REL8_2_13:1.20
	REL8_3_7:1.23
	REL7_4_24:1.16
	REL8_0_20:1.19
	REL8_1_16:1.19
	REL8_2_12:1.20
	REL8_3_6:1.23
	REL7_4_23:1.16
	REL8_0_19:1.19
	REL8_1_15:1.19
	REL8_2_11:1.20
	REL8_3_5:1.23
	REL7_4_22:1.16
	REL8_0_18:1.19
	REL8_1_14:1.19
	REL8_2_10:1.20
	REL8_3_4:1.23
	REL7_4_21:1.16
	REL8_0_17:1.19
	REL8_1_13:1.19
	REL8_2_9:1.20
	REL8_3_3:1.23
	REL7_4_20:1.16
	REL8_0_16:1.19
	REL8_1_12:1.19
	REL8_2_8:1.20
	REL8_3_2:1.23
	REL8_2_7:1.20
	REL8_3_1:1.23
	REL8_3_STABLE:1.23.0.2
	REL8_3_0:1.23
	REL8_3_RC2:1.23
	REL7_3_21:1.9
	REL7_4_19:1.16
	REL8_0_15:1.19
	REL8_1_11:1.19
	REL8_2_6:1.20
	REL8_3_RC1:1.23
	REL8_3_BETA4:1.23
	REL8_3_BETA3:1.23
	REL8_3_BETA2:1.23
	REL8_3_BETA1:1.22
	REL7_3_20:1.9
	REL7_4_18:1.16
	REL8_0_14:1.19
	REL8_1_10:1.19
	REL8_2_5:1.20
	REL7_3_19:1.9
	REL7_4_17:1.16
	REL8_0_13:1.19
	REL8_1_9:1.19
	REL8_2_4:1.20
	REL8_0_12:1.19
	REL8_1_8:1.19
	REL8_2_3:1.20
	REL7_3_18:1.9
	REL7_4_16:1.16
	REL8_0_11:1.19
	REL8_1_7:1.19
	REL8_2_2:1.20
	REL8_0_10:1.19
	REL8_1_6:1.19
	REL8_2_1:1.20
	REL7_4_15:1.16
	REL7_3_17:1.9
	REL8_2_STABLE:1.20.0.2
	REL8_2_0:1.20
	REL8_2_RC1:1.20
	REL8_2_BETA3:1.20
	REL8_2_BETA2:1.20
	REL8_1_5:1.19
	REL8_0_9:1.19
	REL7_4_14:1.16
	REL7_3_16:1.9
	REL8_2_BETA1:1.20
	REL7_3_15:1.9
	REL7_4_13:1.16
	REL8_0_8:1.19
	REL8_1_4:1.19
	REL7_3_14:1.9
	REL7_4_12:1.16
	REL8_0_7:1.19
	REL8_1_3:1.19
	REL7_3_13:1.9
	REL7_4_11:1.16
	REL8_0_6:1.19
	REL8_1_2:1.19
	REL7_3_12:1.9
	REL7_4_10:1.16
	REL8_0_5:1.19
	REL8_1_1:1.19
	REL8_1_STABLE:1.19.0.6
	REL8_1_0:1.19
	REL8_1_0RC1:1.19
	REL8_1_0BETA4:1.19
	REL8_1_0BETA3:1.19
	REL7_3_11:1.9
	REL7_4_9:1.16
	REL8_0_4:1.19
	REL8_1_0BETA2:1.19
	REL8_1_0BETA1:1.19
	REL7_2_8:1.6
	REL7_3_10:1.9
	REL7_4_8:1.16
	REL8_0_3:1.19
	REL8_0_2:1.19
	REL7_2_7:1.6
	REL7_3_9:1.9
	REL7_4_7:1.16
	REL8_0_1:1.19
	REL8_0_STABLE:1.19.0.4
	REL8_0_0:1.19.0.2
	REL8_0_0RC5:1.19
	REL8_0_0RC4:1.19
	REL8_0_0RC3:1.19
	REL8_0_0RC2:1.19
	REL8_0_0RC1:1.19
	REL8_0_0BETA5:1.19
	REL8_0_0BETA4:1.19
	REL7_4_6:1.16
	REL7_3_8:1.9
	REL7_2_6:1.6
	REL8_0_0BETA3:1.19
	REL8_0_0BETA2:1.19
	REL7_2_5:1.6
	REL7_4_5:1.16
	REL7_3_7:1.9
	REL7_4_4:1.16
	REL8_0_0BETA1:1.19
	REL7_4_3:1.16
	REL7_4_2:1.16
	REL7_3_6:1.9
	REL7_4_1:1.16
	REL7_3_5:1.9
	REL7_4:1.16
	REL7_4_RC2:1.16
	REL7_4_STABLE:1.16.0.2
	REL7_4_RC1:1.16
	REL7_4_BETA5:1.16
	REL7_4_BETA4:1.16
	REL7_4_BETA3:1.16
	REL7_4_BETA2:1.12
	WIN32_DEV:1.12.0.2
	REL7_4_BETA1:1.12
	REL7_3_4:1.9
	REL7_3_2:1.9
	REL7_2_4:1.6
	REL7_3_STABLE:1.9.0.2
	REL7_2_3:1.6
	REL7_2_STABLE:1.6.0.2
	REL7_2:1.6
	REL7_2_RC2:1.6
	REL7_2_RC1:1.6
	REL7_2_BETA5:1.5
	REL7_2_BETA4:1.5
	REL7_2_BETA3:1.4
	REL7_2_BETA2:1.3
	REL7_2_BETA1:1.3;
locks; strict;
comment	@# @;


1.30
date	2010.06.15.18.43.35;	author rhaas;	state Exp;
branches;
next	1.29;

1.29
date	2010.04.03.07.22.57;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2010.01.22.16.40.18;	author rhaas;	state Exp;
branches;
next	1.27;

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

1.26
date	2009.08.02.22.14.51;	author tgl;	state Exp;
branches;
next	1.25;

1.25
date	2008.12.13.19.13.44;	author tgl;	state Exp;
branches;
next	1.24;

1.24
date	2008.11.14.10.22.45;	author petere;	state Exp;
branches;
next	1.23;

1.23
date	2007.10.07.01.16.42;	author alvherre;	state Exp;
branches;
next	1.22;

1.22
date	2007.05.15.19.13.55;	author neilc;	state Exp;
branches;
next	1.21;

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

1.20
date	2006.09.16.00.30.16;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2004.03.09.16.57.47;	author neilc;	state Exp;
branches;
next	1.18;

1.18
date	2003.12.14.00.15.03;	author neilc;	state Exp;
branches;
next	1.17;

1.17
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.16;

1.16
date	2003.09.12.23.04.45;	author tgl;	state Exp;
branches;
next	1.15;

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

1.14
date	2003.09.09.18.28.52;	author tgl;	state Exp;
branches;
next	1.13;

1.13
date	2003.08.31.17.32.21;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2003.04.15.13.25.08;	author petere;	state Exp;
branches
	1.12.2.1;
next	1.11;

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

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

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

1.8
date	2002.04.23.02.07.15;	author tgl;	state Exp;
branches;
next	1.7;

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

1.6
date	2002.01.20.22.19.56;	author petere;	state Exp;
branches;
next	1.5;

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

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

1.3
date	2001.10.16.01.13.44;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2001.09.03.12.57.49;	author petere;	state Exp;
branches;
next	1.1;

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

1.12.2.1
date	2003.09.07.04.36.44;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.30
log
@Document new 9.0 behavior of ANALYZE on inheritance hierarchies.

In particular, note that autovacuum does not yet understand that it might
need to vacuum inheritance parents as a result of changes to the child
tables.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.29 2010/04/03 07:22:57 petere Exp $
PostgreSQL documentation
-->

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

 <refnamediv>
  <refname>ANALYZE</refname>
  <refpurpose>collect statistics about a database</refpurpose>
 </refnamediv>

 <indexterm zone="sql-analyze">
  <primary>ANALYZE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>ANALYZE</command> collects statistics about the contents
   of tables in the database, and stores the results in the <link
   linkend="catalog-pg-statistic"><structname>pg_statistic</></>
   system catalog.  Subsequently, the query planner uses these
   statistics to help determine the most efficient execution plans for
   queries.
  </para>

  <para>
   With no parameter, <command>ANALYZE</command> examines every table in the
   current database.  With a parameter, <command>ANALYZE</command> examines
   only that table.  It is further possible to give a list of column names,
   in which case only the statistics for those columns are collected.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><literal>VERBOSE</literal></term>
    <listitem>
     <para>
      Enables display of progress messages.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">table</replaceable></term>
    <listitem>
     <para>
      The name (possibly schema-qualified) of a specific table to
      analyze. Defaults to all tables in the current database.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">column</replaceable></term>
    <listitem>
     <para>
      The name of a specific column to analyze. Defaults to all columns.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Outputs</title>

   <para>
    When <literal>VERBOSE</> is specified, <command>ANALYZE</> emits
    progress messages to indicate which table is currently being
    processed.  Various statistics about the tables are printed as well.
   </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   In the default <productname>PostgreSQL</productname> configuration,
   the autovacuum daemon (see <xref linkend="autovacuum">)
   takes care of automatic analyzing of tables when they are first loaded
   with data, and as they change throughout regular operation.
   When autovacuum is disabled,
   it is a good idea to run <command>ANALYZE</command> periodically, or
   just after making major changes in the contents of a table.  Accurate
   statistics will help the planner to choose the most appropriate query
   plan, and thereby improve the speed of query processing.  A common
   strategy is to run <xref linkend="sql-vacuum">
   and <command>ANALYZE</command> once a day during a low-usage time of day.
  </para>

  <para>
   <command>ANALYZE</command>
   requires only a read lock on the target table, so it can run in
   parallel with other activity on the table.
  </para>

  <para>
   The statistics collected by <command>ANALYZE</command> usually
   include a list of some of the most common values in each column and
   a histogram showing the approximate data distribution in each
   column.  One or both of these can be omitted if
   <command>ANALYZE</command> deems them uninteresting (for example,
   in a unique-key column, there are no common values) or if the
   column data type does not support the appropriate operators.  There
   is more information about the statistics in <xref
   linkend="maintenance">.
  </para>

  <para>
   For large tables, <command>ANALYZE</command> takes a random sample
   of the table contents, rather than examining every row.  This
   allows even very large tables to be analyzed in a small amount of
   time.  Note, however, that the statistics are only approximate, and
   will change slightly each time <command>ANALYZE</command> is run,
   even if the actual table contents did not change.  This might result
   in small changes in the planner's estimated costs shown by
   <xref linkend="sql-explain">.
   In rare situations, this non-determinism will cause the planner's
   choices of query plans to change after <command>ANALYZE</command> is run.
   To avoid this, raise the amount of statistics collected by
   <command>ANALYZE</command>, as described below.
  </para>

  <para>
   The extent of analysis can be controlled by adjusting the
   <xref linkend="guc-default-statistics-target"> configuration variable, or
   on a column-by-column basis by setting the per-column statistics
   target with <command>ALTER TABLE ... ALTER COLUMN ... SET
   STATISTICS</command> (see <xref linkend="sql-altertable">).
   The target value sets the
   maximum number of entries in the most-common-value list and the
   maximum number of bins in the histogram.  The default target value
   is 100, but this can be adjusted up or down to trade off accuracy of
   planner estimates against the time taken for
   <command>ANALYZE</command> and the amount of space occupied in
   <literal>pg_statistic</literal>.  In particular, setting the
   statistics target to zero disables collection of statistics for
   that column.  It might be useful to do that for columns that are
   never used as part of the <literal>WHERE</>, <literal>GROUP BY</>,
   or <literal>ORDER BY</> clauses of queries, since the planner will
   have no use for statistics on such columns.
  </para>

  <para>
   The largest statistics target among the columns being analyzed determines
   the number of table rows sampled to prepare the statistics.  Increasing
   the target causes a proportional increase in the time and space needed
   to do <command>ANALYZE</command>.
  </para>

  <para>
   One of the values estimated by <command>ANALYZE</command> is the number of
   distinct values that appear in each column.  Because only a subset of the
   rows are examined, this estimate can sometimes be quite inaccurate, even
   with the largest possible statistics target.  If this inaccuracy leads to
   bad query plans, a more accurate value can be determined manually and then
   installed with
   <command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</>
   (see <xref linkend="sql-altertable">).
  </para>

  <para>
    If the table being analyzed has one or more children,
    <command>ANALYZE</command> will gather statistics twice: once on the
    rows of the parent table only, and a second time on the rows of the
    parent table with all of its children.  The autovacuum daemon, however,
    will only consider inserts or updates on the parent table when deciding
    whether to trigger an automatic analyze.  If that table is rarely
    inserted into or updated, the inheritance statistics will not be up to date
    unless you run <command>ANALYZE</command> manually.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

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

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

  <simplelist type="inline">
   <member><xref linkend="sql-vacuum"></member>
   <member><xref linkend="app-vacuumdb"></member>
   <member><xref linkend="runtime-config-resource-vacuum-cost"></member>
   <member><xref linkend="autovacuum"></member>
  </simplelist>
 </refsect1>
</refentry>
@


1.29
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.28 2010/01/22 16:40:18 rhaas Exp $
d179 11
@


1.28
log
@Replace ALTER TABLE ... SET STATISTICS DISTINCT with a more general mechanism.

Attributes can now have options, just as relations and tablespaces do, and
the reloptions code is used to parse, validate, and store them.  For
simplicity and because these options are not performance critical, we store
them in a separate cache rather than the main relcache.

Thanks to Alex Hunsaker for the review.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.27 2009/08/04 22:04:37 petere Exp $
d8 1
a8 1
  <refentrytitle id="sql-analyze-title">ANALYZE</refentrytitle>
d105 1
a105 1
   strategy is to run <xref linkend="sql-vacuum" endterm="sql-vacuum-title">
d135 1
a135 1
   <xref linkend="sql-explain" endterm="sql-explain-title">.
d147 2
a148 2
   STATISTICS</command> (see <xref linkend="sql-altertable"
   endterm="sql-altertable-title">).  The target value sets the
d177 1
a177 1
   (see <xref linkend="sql-altertable" endterm="sql-altertable-title">).
d193 4
a196 4
   <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
   <member><xref linkend="app-vacuumdb" endterm="app-vacuumdb-title"></member>
   <member><xref linkend="runtime-config-resource-vacuum-cost" endterm="runtime-config-resource-vacuum-cost-title"></member>
   <member><xref linkend="autovacuum" endterm="autovacuum-title"></member>
@


1.27
log
@Use DocBook XSL stylesheets for man page building

This switches the man page building process to use the DocBook XSL stylesheet
toolchain.  The previous targets for Docbook2X are removed. configure has been
updated to look for the new tools.  The Documentation appendix contains the
new build instructions.  There are also a few isolated tweaks in the
documentation to improve places that came out strangely in the man pages.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.26 2009/08/02 22:14:51 tgl Exp $
d176 1
a176 1
   <command>ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT</>
@


1.26
log
@Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT

Robert Haas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.25 2008/12/13 19:13:44 tgl Exp $
d97 1
a97 1
   <xref linkend="autovacuum" endterm="autovacuum-title">
@


1.25
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.24 2008/11/14 10:22:45 petere Exp $
d168 11
@


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

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.23 2007/10/07 01:16:42 alvherre Exp $
d135 4
a138 4
   <xref linkend="sql-explain" endterm="sql-explain-title">. In rare situations, this
   non-determinism will cause the query optimizer to choose a
   different query plan between runs of <command>ANALYZE</command>. To
   avoid this, raise the amount of statistics collected by
d151 1
a151 1
   is 10, but this can be adjusted up or down to trade off accuracy of
@


1.23
log
@A few improvements to analyze and vacuum sections in documentation: add "see
also" entries for autovacuum in analyze and vacuum reference pages, and
enhance usage of cross-references in the maintenance page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.22 2007/05/15 19:13:55 neilc Exp $
d9 1
@


1.22
log
@Various fixes for the SGML docs. Consistently use spaces before/after
parentheses in syntax descriptions. Consistently use the present tense
when describing the basic purpose of each "DROP" command. Add a few
more hyperlinks.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.21 2007/01/31 23:26:02 momjian Exp $
d95 6
a100 1
   It is a good idea to run <command>ANALYZE</command> periodically, or
d109 1
a109 1
   Unlike <command>VACUUM FULL</command>, <command>ANALYZE</command>
d176 11
@


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

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

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

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

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.20 2006/09/16 00:30:16 momjian Exp $
d23 1
a23 1
ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
d32 5
a36 4
   of tables in the database, and stores the results in the system
   table <literal>pg_statistic</literal>.  Subsequently, the query
   planner uses these statistics to help determine the most efficient
   execution plans for queries.
d129 1
a129 1
   <command>EXPLAIN</command>. In rare situations, this
@


1.20
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.19 2004/03/09 16:57:47 neilc Exp $
d112 1
a112 1
   column.  One or both of these may be omitted if
d126 1
a126 1
   even if the actual table contents did not change.  This may result
d149 1
a149 1
   that column.  It may be useful to do that for columns that are
@


1.19
log
@Refer to GUC variables using <xref> tags rather than <varname> tags,
where appropriate. Add "id" and "xreflabel" tags to the descriptions
of the GUC variables to facilitate this. Also make a few minor docs
cleanups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.18 2003/12/14 00:15:03 neilc Exp $
a170 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.18
log
@This patch fixes a few more uppercase GUC vars. I also removed an
example from the RESET reference page because it seemed completely
redundant.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.17 2003/11/29 19:51:38 pgsql Exp $
d137 1
a137 1
   <varname>default_statistics_target</varname> parameter variable, or
@


1.17
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.16 2003/09/12 23:04:45 tgl Exp $
d137 1
a137 1
   <varname>DEFAULT_STATISTICS_TARGET</varname> parameter variable, or
@


1.16
log
@Mop-up for error-message updates in documentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.15 2003/09/11 17:31:45 momjian Exp $
@


1.15
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/ref/analyze.sgml,v 1.14 2003/09/09 18:28:52 tgl Exp $
d78 10
@


1.14
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.13 2003/08/31 17:32:21 petere Exp $
d31 4
a34 4
   <command>ANALYZE</command> collects statistics about the contents of
   tables in the database, and stores the results in
   the system table <literal>pg_statistic</literal>.  Subsequently,
   the query planner uses the statistics to help determine the most efficient
d93 3
a95 4
   Unlike <command>VACUUM FULL</command>,
   <command>ANALYZE</command> requires
   only a read lock on the target table, so it can run in parallel with
   other activity on the table.
d99 9
a107 7
   For large tables, <command>ANALYZE</command> takes a random sample of the
   table contents, rather than examining every row.  This allows even very
   large tables to be analyzed in a small amount of time.  Note, however,
   that the statistics are only approximate, and will change slightly each
   time <command>ANALYZE</command> is run, even if the actual table contents
   did not change.  This may result in small changes in the planner's
   estimated costs shown by <command>EXPLAIN</command>.
d111 12
a122 7
   The collected statistics usually include a list of some of the most common
   values in each column and a histogram showing the approximate data
   distribution in each column.  One or both of these may be omitted if
   <command>ANALYZE</command> deems them uninteresting (for example, in
   a unique-key column, there are no common values) or if the column
   data type does not support the appropriate operators.  There is more
   information about the statistics in <xref linkend="maintenance">.
d127 16
a142 15
   <literal>default_statistics_target</> parameter variable, or on a
   column-by-column basis by setting the per-column
   statistics target with <command>ALTER TABLE ... ALTER COLUMN ... SET
   STATISTICS</command> (see
   <xref linkend="sql-altertable" endterm="sql-altertable-title">).  The
   target value sets the maximum number of entries in the most-common-value
   list and the maximum number of bins in the histogram.  The default
   target value is 10, but this can be adjusted up or down to trade off
   accuracy of planner estimates against the time taken for
   <command>ANALYZE</command> and the amount of space occupied
   in <literal>pg_statistic</literal>.
   In particular, setting the statistics target to zero disables collection of
   statistics for that column.  It may be useful to do that for columns that
   are never used as part of the <literal>WHERE</>, <literal>GROUP BY</>, or <literal>ORDER BY</> clauses of
   queries, since the planner will have no use for statistics on such columns.
@


1.13
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.12 2003/04/15 13:25:08 petere Exp $
a73 15
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <variablelist>
   <varlistentry>
    <term><computeroutput>ANALYZE</computeroutput></term>
    <listitem>
     <para>
      The command is complete.
@


1.12
log
@Bring SQL ref pages to consistent format, part 1.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.11 2003/03/25 16:15:39 petere Exp $
d16 4
@


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

 <indexterm zone="sql-analyze">
  <primary>ANALYZE</primary>
 </indexterm>
@


1.11
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.10 2003/01/19 00:13:29 momjian Exp $
d11 1
d13 2
a14 6
  <refname>
   ANALYZE
  </refname>
  <refpurpose>
   collect statistics about a database
  </refpurpose>
d16 1
d18 1
a18 4
  <refsynopsisdivinfo>
   <date>2001-05-04</date>
  </refsynopsisdivinfo>
  <synopsis>
d20 2
a21 1
  </synopsis>
d23 2
a24 64
  <refsect2 id="R2-SQL-ANALYZE-1">
   <refsect2info>
    <date>2001-05-04</date>
   </refsect2info>
   <title>
    Inputs
   </title>

   <para>
    <variablelist>
     <varlistentry>
      <term>VERBOSE</term>
      <listitem>
       <para>
	Enables display of progress messages.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">table</replaceable></term>
      <listitem>
       <para>
	The name (possibly schema-qualified) of a specific table to
	analyze. Defaults to all tables in the current database.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">column</replaceable></term>
      <listitem>
       <para>
	The name of a specific column to analyze. Defaults to all columns.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-ANALYZE-2">
   <refsect2info>
    <date>2001-05-04</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
<returnvalue>ANALYZE</returnvalue>
       </computeroutput></term>
      <listitem>
       <para>
	The command is complete.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>
a25 7
 <refsect1 id="R1-SQL-ANALYZE-1">
  <refsect1info>
   <date>2001-05-04</date>
  </refsect1info>
  <title>
   Description
  </title>
d28 1
a28 1
   <productname>PostgreSQL</productname> tables, and stores the results in
d38 1
a38 1
   in which case only the statistics for those columns are updated.
d40 35
d76 17
a92 7
  <refsect2 id="R2-SQL-ANALYZE-3">
   <refsect2info>
    <date>2001-05-04</date>
   </refsect2info>
   <title>
    Notes
   </title>
d113 1
a113 1
   large tables to be analyzed in a small amount of time.  Note however
d134 1
a134 1
   statistics target with <command>ALTER TABLE ALTER COLUMN SET
d145 1
a145 1
   are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of
d155 1
d157 2
a158 2
  </refsect2>
 </refsect1>
d160 3
a162 16
 <refsect1 id="R1-SQL-ANALYZE-3">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-ANALYZE-4">
   <refsect2info>
    <date>2001-05-04</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>ANALYZE</command> statement in <acronym>SQL92</acronym>.
   </para>
  </refsect2>
@


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

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

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

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

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/analyze.sgml,v 1.9 2002/07/31 17:19:51 tgl Exp $
d155 1
a155 1
   information about the statistics in the &cite-user;.
@


1.9
log
@Instead of having a configure-time DEFAULT_ATTSTATTARGET, store -1 in
attstattarget to indicate 'use the default'.  The default is now a GUC
variable default_statistics_target, and so may be changed on the fly.  Along
the way we gain the ability to have pg_dump dump the per-column statistics
target when it's not the default.  Patch by Neil Conway, with some kibitzing
from Tom Lane.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.8 2002/04/23 02:07:15 tgl Exp $
d155 1
a155 2
   information about the statistics in the <citetitle>User's
   Guide</citetitle>.
@


1.8
log
@Update SQL-command reference pages for schema features.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.7 2002/04/21 19:02:39 thomas Exp $
d160 3
a162 1
   The extent of analysis can be controlled by adjusting the per-column
d170 2
a171 2
   <command>ANALYZE</command> and the
   amount of space occupied in <literal>pg_statistic</literal>.
@


1.7
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.6 2002/01/20 22:19:56 petere Exp $
d49 2
a50 1
	The name of a specific table to analyze. Defaults to all tables.
@


1.6
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.5 2001/12/08 03:24:34 thomas Exp $
d8 1
a8 3
  <refentrytitle id="sql-analyze-title">
   ANALYZE
  </refentrytitle>
@


1.5
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.4 2001/11/18 22:17:30 tgl Exp $
d155 1
a155 1
   datatype does not support the appropriate operators.  There is more
@


1.4
log
@Update various obsolete remarks about VACUUM.
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.3 2001/10/16 01:13:44 tgl Exp $
Postgres documentation
d102 1
a102 1
   <productname>Postgres</productname> tables, and stores the results in
@


1.3
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/ref/analyze.sgml,v 1.2 2001/09/03 12:57:49 petere Exp $
d128 2
a129 2
   strategy is to run <command>VACUUM</command> and <command>ANALYZE</command>
   once a day during a low-usage time of day.
d133 1
a133 1
   Unlike <xref linkend="sql-vacuum" endterm="sql-vacuum-title">,
@


1.2
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.1 2001/05/07 00:43:15 tgl Exp $
d155 3
a157 1
   datatype does not support the appropriate operators.
@


1.1
log
@Rewrite of planner statistics-gathering code.  ANALYZE is now available as
a separate statement (though it can still be invoked as part of VACUUM, too).
pg_statistic redesigned to be more flexible about what statistics are
stored.  ANALYZE now collects a list of several of the most common values,
not just one, plus a histogram (not just the min and max values).  Random
sampling is used to make the process reasonably fast even on very large
tables.  The number of values and histogram bins collected is now
user-settable via an ALTER TABLE command.

There is more still to do; the new stats are not being used everywhere
they could be in the planner.  But the remaining changes for this project
should be localized, and the behavior is already better than before.

A not-very-related change is that sorting now makes use of btree comparison
routines if it can find one, rather than invoking '<' twice.
@
text
@d2 1
a2 1
$Header$
d18 1
a18 1
   Collect statistics about a <productname>Postgres</productname> database
@
