← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/analyze.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/analyze.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/analyze.sgml,v 1.19 2004-03-09 16:57:47 neilc Exp $
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-ANALYZE">
 
7
 <refmeta>
 
8
  <refentrytitle id="sql-analyze-title">ANALYZE</refentrytitle>
 
9
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
10
 </refmeta>
 
11
 
 
12
 <refnamediv>
 
13
  <refname>ANALYZE</refname>
 
14
  <refpurpose>collect statistics about a database</refpurpose>
 
15
 </refnamediv>
 
16
 
 
17
 <indexterm zone="sql-analyze">
 
18
  <primary>ANALYZE</primary>
 
19
 </indexterm>
 
20
 
 
21
 <refsynopsisdiv>
 
22
<synopsis>
 
23
ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
 
24
</synopsis>
 
25
 </refsynopsisdiv>
 
26
 
 
27
 <refsect1>
 
28
  <title>Description</title>
 
29
 
 
30
  <para>
 
31
   <command>ANALYZE</command> collects statistics about the contents
 
32
   of tables in the database, and stores the results in the system
 
33
   table <literal>pg_statistic</literal>.  Subsequently, the query
 
34
   planner uses these statistics to help determine the most efficient
 
35
   execution plans for queries.
 
36
  </para>
 
37
 
 
38
  <para>
 
39
   With no parameter, <command>ANALYZE</command> examines every table in the
 
40
   current database.  With a parameter, <command>ANALYZE</command> examines
 
41
   only that table.  It is further possible to give a list of column names,
 
42
   in which case only the statistics for those columns are collected.
 
43
  </para>
 
44
 </refsect1>
 
45
 
 
46
 <refsect1>
 
47
  <title>Parameters</title>
 
48
 
 
49
  <variablelist>
 
50
   <varlistentry>
 
51
    <term><literal>VERBOSE</literal></term>
 
52
    <listitem>
 
53
     <para>
 
54
      Enables display of progress messages.
 
55
     </para>
 
56
    </listitem>
 
57
   </varlistentry>
 
58
 
 
59
   <varlistentry>
 
60
    <term><replaceable class="PARAMETER">table</replaceable></term>
 
61
    <listitem>
 
62
     <para>
 
63
      The name (possibly schema-qualified) of a specific table to
 
64
      analyze. Defaults to all tables in the current database.
 
65
     </para>
 
66
    </listitem>
 
67
   </varlistentry>
 
68
 
 
69
   <varlistentry>
 
70
    <term><replaceable class="PARAMETER">column</replaceable></term>
 
71
    <listitem>
 
72
     <para>
 
73
      The name of a specific column to analyze. Defaults to all columns.
 
74
     </para>
 
75
    </listitem>
 
76
   </varlistentry>
 
77
  </variablelist>
 
78
 </refsect1>
 
79
 
 
80
 <refsect1>
 
81
  <title>Outputs</title>
 
82
 
 
83
   <para>
 
84
    When <literal>VERBOSE</> is specified, <command>ANALYZE</> emits
 
85
    progress messages to indicate which table is currently being
 
86
    processed.  Various statistics about the tables are printed as well.
 
87
   </para>
 
88
 </refsect1>
 
89
 
 
90
 <refsect1>
 
91
  <title>Notes</title>
 
92
 
 
93
  <para>
 
94
   It is a good idea to run <command>ANALYZE</command> periodically, or
 
95
   just after making major changes in the contents of a table.  Accurate
 
96
   statistics will help the planner to choose the most appropriate query
 
97
   plan, and thereby improve the speed of query processing.  A common
 
98
   strategy is to run <xref linkend="sql-vacuum" endterm="sql-vacuum-title">
 
99
   and <command>ANALYZE</command> once a day during a low-usage time of day.
 
100
  </para>
 
101
 
 
102
  <para>
 
103
   Unlike <command>VACUUM FULL</command>, <command>ANALYZE</command>
 
104
   requires only a read lock on the target table, so it can run in
 
105
   parallel with other activity on the table.
 
106
  </para>
 
107
 
 
108
  <para>
 
109
   The statistics collected by <command>ANALYZE</command> usually
 
110
   include a list of some of the most common values in each column and
 
111
   a histogram showing the approximate data distribution in each
 
112
   column.  One or both of these may be omitted if
 
113
   <command>ANALYZE</command> deems them uninteresting (for example,
 
114
   in a unique-key column, there are no common values) or if the
 
115
   column data type does not support the appropriate operators.  There
 
116
   is more information about the statistics in <xref
 
117
   linkend="maintenance">.
 
118
  </para>
 
119
 
 
120
  <para>
 
121
   For large tables, <command>ANALYZE</command> takes a random sample
 
122
   of the table contents, rather than examining every row.  This
 
123
   allows even very large tables to be analyzed in a small amount of
 
124
   time.  Note, however, that the statistics are only approximate, and
 
125
   will change slightly each time <command>ANALYZE</command> is run,
 
126
   even if the actual table contents did not change.  This may result
 
127
   in small changes in the planner's estimated costs shown by
 
128
   <command>EXPLAIN</command>. In rare situations, this
 
129
   non-determinism will cause the query optimizer to choose a
 
130
   different query plan between runs of <command>ANALYZE</command>. To
 
131
   avoid this, raise the amount of statistics collected by
 
132
   <command>ANALYZE</command>, as described below.
 
133
  </para>
 
134
 
 
135
  <para>
 
136
   The extent of analysis can be controlled by adjusting the
 
137
   <xref linkend="guc-default-statistics-target"> configuration variable, or
 
138
   on a column-by-column basis by setting the per-column statistics
 
139
   target with <command>ALTER TABLE ... ALTER COLUMN ... SET
 
140
   STATISTICS</command> (see <xref linkend="sql-altertable"
 
141
   endterm="sql-altertable-title">).  The target value sets the
 
142
   maximum number of entries in the most-common-value list and the
 
143
   maximum number of bins in the histogram.  The default target value
 
144
   is 10, but this can be adjusted up or down to trade off accuracy of
 
145
   planner estimates against the time taken for
 
146
   <command>ANALYZE</command> and the amount of space occupied in
 
147
   <literal>pg_statistic</literal>.  In particular, setting the
 
148
   statistics target to zero disables collection of statistics for
 
149
   that column.  It may be useful to do that for columns that are
 
150
   never used as part of the <literal>WHERE</>, <literal>GROUP BY</>,
 
151
   or <literal>ORDER BY</> clauses of queries, since the planner will
 
152
   have no use for statistics on such columns.
 
153
  </para>
 
154
 
 
155
  <para>
 
156
   The largest statistics target among the columns being analyzed determines
 
157
   the number of table rows sampled to prepare the statistics.  Increasing
 
158
   the target causes a proportional increase in the time and space needed
 
159
   to do <command>ANALYZE</command>.
 
160
  </para>
 
161
 </refsect1>
 
162
 
 
163
 <refsect1>
 
164
  <title>Compatibility</title>
 
165
 
 
166
  <para>
 
167
   There is no <command>ANALYZE</command> statement in the SQL standard.
 
168
  </para>
 
169
 </refsect1>
 
170
</refentry>
 
171
 
 
172
<!-- Keep this comment at the end of the file
 
173
Local variables:
 
174
mode: sgml
 
175
sgml-omittag:nil
 
176
sgml-shorttag:t
 
177
sgml-minimize-attributes:nil
 
178
sgml-always-quote-attributes:t
 
179
sgml-indent-step:1
 
180
sgml-indent-data:t
 
181
sgml-parent-document:nil
 
182
sgml-default-dtd-file:"../reference.ced"
 
183
sgml-exposed-tags:nil
 
184
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
185
sgml-local-ecat-files:nil
 
186
End:
 
187
-->