From e51ac1b899cf9abdf07ee74e788ac9a02e809c3f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 8 Apr 2007 02:07:35 +0000
Subject: [PATCH] Minor editorialization on CLUSTER reference page.
---
doc/src/sgml/ref/cluster.sgml | 32 +++++++++++++++++++-------------
1 file changed, 19 insertions(+), 13 deletions(-)
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index c038d387c81..acb2468f7ba 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.41 2007/04/08 00:26:33 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.42 2007/04/08 02:07:35 tgl Exp $
PostgreSQL documentation
-->
@@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER <replaceable class="PARAMETER">tablename</replaceable> [ USING <replaceable class="PARAMETER">indexname</replaceable> ]
+CLUSTER <replaceable class="PARAMETER">tablename</replaceable> <optional> USING <replaceable class="PARAMETER">indexname</replaceable> </optional>
CLUSTER
</synopsis>
</refsynopsisdiv>
@@ -43,22 +43,24 @@ CLUSTER
based on the index information. Clustering is a one-time operation:
when the table is subsequently updated, the changes are
not clustered. That is, no attempt is made to store new or
- updated rows according to their index order. If one wishes, one can
- periodically recluster by issuing the command again.
+ updated rows according to their index order. (If one wishes, one can
+ periodically recluster by issuing the command again. Also, setting
+ the table's FILLFACTOR storage parameter to less than 100% can aid
+ in preserving cluster ordering during updates, since updated rows
+ are preferentially kept on the same page.)
</para>
<para>
When a table is clustered, <productname>PostgreSQL</productname>
- remembers on which index it was clustered. The form
+ remembers which index it was clustered by. The form
<command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>
- reclusters the table on the same index that it was clustered before.
+ reclusters the table using the same index as before.
</para>
<para>
- <command>CLUSTER</command> without any parameter reclusters all the tables
- in the
- current database that the calling user owns, or all tables if called
- by a superuser. (Never-clustered tables are not included.) This
+ <command>CLUSTER</command> without any parameter reclusters all the
+ previously-clustered tables in the current database that the calling user
+ owns, or all such tables if called by a superuser. This
form of <command>CLUSTER</command> cannot be executed inside a transaction
block.
</para>
@@ -197,12 +199,16 @@ CLUSTER;
<title>Compatibility</title>
<para>
- The syntax:
+ There is no <command>CLUSTER</command> statement in the SQL standard.
+ </para>
+
+ <para>
+ The syntax
<synopsis>
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
</synopsis>
- is also supported for compatibility with pre-8.3 <productname>PostgreSQL</> installations.
- There is no <command>CLUSTER</command> statement in the SQL standard.
+ is also supported for compatibility with pre-8.3 <productname>PostgreSQL</>
+ versions.
</para>
</refsect1>
--
GitLab