Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 8e27be4

Browse files
bmomjianbmomjian
committed
This patch makes a few minor improvements to the docs: make the
<varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
1 parent 64a7b58 commit 8e27be4

File tree

6 files changed

+57
-50
lines changed

6 files changed

+57
-50
lines changed

‎doc/src/sgml/perform.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.31 2003/08/31 17:32:19 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.32 2003/09/11 17:31:45 momjian Exp $
33
-->
44

55
<chapter id="performance-tips">
@@ -603,7 +603,7 @@ SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
603603
<productname>PostgreSQL</productname> planner will switch from exhaustive
604604
search to a <firstterm>genetic</firstterm> probabilistic search
605605
through a limited number of possibilities. (The switch-over threshold is
606-
set by the <varname>geqo_threshold</varname> run-time
606+
set by the <varname>GEQO_THRESHOLD</varname> run-time
607607
parameter.)
608608
The genetic search takes less time, but it won't
609609
necessarily find the best possible plan.

‎doc/src/sgml/plpgsql.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.22 2003/09/03 22:17:07 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.23 2003/09/11 17:31:45 momjian Exp $
33
-->
44

55
<chapter id="plpgsql">
@@ -1350,7 +1350,7 @@ SELECT * FROM some_func();
13501350
allow users to allow users to define set-returning functions
13511351
that do not have this limitation. Currently, the point at
13521352
which data begins being written to disk is controlled by the
1353-
<varname>sort_mem</> configuration variable. Administrators
1353+
<varname>SORT_MEM</> configuration variable. Administrators
13541354
who have sufficient memory to store larger result sets in
13551355
memory should consider increasing this parameter.
13561356
</para>

‎doc/src/sgml/ref/analyze.sgml

Lines changed: 45 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.14 2003/09/09 18:28:52 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.15 2003/09/11 17:31:45 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -28,10 +28,10 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
2828
<title>Description</title>
2929

3030
<para>
31-
<command>ANALYZE</command> collects statistics about the contents of
32-
tables in the database, and stores the results in
33-
the system table <literal>pg_statistic</literal>. Subsequently,
34-
the query planner uses the statistics to help determine the most efficient
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
3535
execution plans for queries.
3636
</para>
3737

@@ -90,49 +90,56 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
9090
</para>
9191

9292
<para>
93-
Unlike <command>VACUUM FULL</command>,
94-
<command>ANALYZE</command> requires
95-
only a read lock on the target table, so it can run in parallel with
96-
other activity on the table.
93+
Unlike <command>VACUUM FULL</command>, <command>ANALYZE</command>
94+
requires only a read lock on the target table, so it can run in
95+
parallel with other activity on the table.
9796
</para>
9897

9998
<para>
100-
For large tables, <command>ANALYZE</command> takes a random sample of the
101-
table contents, rather than examining every row. This allows even very
102-
large tables to be analyzed in a small amount of time. Note, however,
103-
that the statistics are only approximate, and will change slightly each
104-
time <command>ANALYZE</command> is run, even if the actual table contents
105-
did not change. This may result in small changes in the planner's
106-
estimated costs shown by <command>EXPLAIN</command>.
99+
The statistics collected by <command>ANALYZE</command> usually
100+
include a list of some of the most common values in each column and
101+
a histogram showing the approximate data distribution in each
102+
column. One or both of these may be omitted if
103+
<command>ANALYZE</command> deems them uninteresting (for example,
104+
in a unique-key column, there are no common values) or if the
105+
column data type does not support the appropriate operators. There
106+
is more information about the statistics in <xref
107+
linkend="maintenance">.
107108
</para>
108109

109110
<para>
110-
The collected statistics usually include a list of some of the most common
111-
values in each column and a histogram showing the approximate data
112-
distribution in each column. One or both of these may be omitted if
113-
<command>ANALYZE</command> deems them uninteresting (for example, in
114-
a unique-key column, there are no common values) or if the column
115-
data type does not support the appropriate operators. There is more
116-
information about the statistics in <xref linkend="maintenance">.
111+
For large tables, <command>ANALYZE</command> takes a random sample
112+
of the table contents, rather than examining every row. This
113+
allows even very large tables to be analyzed in a small amount of
114+
time. Note, however, that the statistics are only approximate, and
115+
will change slightly each time <command>ANALYZE</command> is run,
116+
even if the actual table contents did not change. This may result
117+
in small changes in the planner's estimated costs shown by
118+
<command>EXPLAIN</command>. In rare situations, this
119+
non-determinism will cause the query optimizer to choose a
120+
different query plan between runs of <command>ANALYZE</command>. To
121+
avoid this, raise the amount of statistics collected by
122+
<command>ANALYZE</command>, as described below.
117123
</para>
118124

119125
<para>
120126
The extent of analysis can be controlled by adjusting the
121-
<literal>default_statistics_target</> parameter variable, or on a
122-
column-by-column basis by setting the per-column
123-
statistics target with <command>ALTER TABLE ... ALTER COLUMN ... SET
124-
STATISTICS</command> (see
125-
<xref linkend="sql-altertable" endterm="sql-altertable-title">). The
126-
target value sets the maximum number of entries in the most-common-value
127-
list and the maximum number of bins in the histogram. The default
128-
target value is 10, but this can be adjusted up or down to trade off
129-
accuracy of planner estimates against the time taken for
130-
<command>ANALYZE</command> and the amount of space occupied
131-
in <literal>pg_statistic</literal>.
132-
In particular, setting the statistics target to zero disables collection of
133-
statistics for that column. It may be useful to do that for columns that
134-
are never used as part of the <literal>WHERE</>, <literal>GROUP BY</>, or <literal>ORDER BY</> clauses of
135-
queries, since the planner will have no use for statistics on such columns.
127+
<varname>DEFAULT_STATISTICS_TARGET</varname> parameter variable, or
128+
on a column-by-column basis by setting the per-column statistics
129+
target with <command>ALTER TABLE ... ALTER COLUMN ... SET
130+
STATISTICS</command> (see <xref linkend="sql-altertable"
131+
endterm="sql-altertable-title">). The target value sets the
132+
maximum number of entries in the most-common-value list and the
133+
maximum number of bins in the histogram. The default target value
134+
is 10, but this can be adjusted up or down to trade off accuracy of
135+
planner estimates against the time taken for
136+
<command>ANALYZE</command> and the amount of space occupied in
137+
<literal>pg_statistic</literal>. In particular, setting the
138+
statistics target to zero disables collection of statistics for
139+
that column. It may be useful to do that for columns that are
140+
never used as part of the <literal>WHERE</>, <literal>GROUP BY</>,
141+
or <literal>ORDER BY</> clauses of queries, since the planner will
142+
have no use for statistics on such columns.
136143
</para>
137144

138145
<para>

‎doc/src/sgml/ref/create_user.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.28 2003/09/09 18:28:53 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.29 2003/09/11 17:31:45 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -98,7 +98,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
9898
These key words control whether the password is stored
9999
encrypted in the system catalogs. (If neither is specified,
100100
the default behavior is determined by the configuration
101-
parameter <varname>password_encryption</varname>.) If the
101+
parameter <varname>PASSWORD_ENCRYPTION</varname>.) If the
102102
presented password string is already in MD5-encrypted format,
103103
then it is stored encrypted as-is, regardless of whether
104104
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified

‎doc/src/sgml/ref/postmaster.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.37 2003/08/31 17:32:24 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.38 2003/09/11 17:31:45 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -376,7 +376,7 @@ PostgreSQL documentation
376376

377377
<listitem>
378378
<para>
379-
Default value of the <literal>datestyle</literal> run-time
379+
Default value of the <varname>DATESTYLE</varname> run-time
380380
parameter. (The use of this environment variable is deprecated.)
381381
</para>
382382
</listitem>
@@ -563,7 +563,7 @@ PostgreSQL documentation
563563
<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
564564
<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
565565
</screen>
566-
Either form overrides whatever setting might exist for <literal>sort_mem</>
566+
Either form overrides whatever setting might exist for <varname>SORT_MEM</>
567567
in <filename>postgresql.conf</>. Notice that underscores in parameter
568568
names can be written as either underscore or dash on the command line.
569569
</para>

‎doc/src/sgml/ref/reset.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.22 2003/09/09 18:28:53 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.23 2003/09/11 17:31:45 momjian Exp $
33
PostgreSQL documentation
44
-->
55

@@ -85,14 +85,14 @@ SET <replaceable class="parameter">parameter</replaceable> TO DEFAULT
8585
<title>Examples</title>
8686

8787
<para>
88-
Set <varname>datestyle</> to its default value:
88+
Set <varname>DATESTYLE</> to its default value:
8989
<screen>
9090
RESET datestyle;
9191
</screen>
9292
</para>
9393

9494
<para>
95-
Set <varname>geqo</> to its default value:
95+
Set <varname>GEQO</> to its default value:
9696
<screen>
9797
RESET geqo;
9898
</screen>

0 commit comments

Comments
 (0)