Add note about space usage of 'manual' approach to clustering, per

suggestion from Sergey Koposov.  Also some other minor editing.

diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 17c185e076026ca879f52545da80992f2461feb6..5a2000f7bef8fc0ccaed1624b228c6c7d0333c48 100644 (file)
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -1,5 +1,5 @@
 
 
@@ -108,8 +108,8 @@ CLUSTER
     If you are requesting a range of indexed values from a table, or a
     single indexed value that has multiple rows that match,
     CLUSTER will help because once the index identifies the
-    heap page for the first row that matches, all other rows
-    that match are probably already on the same heap page,
+    table page for the first row that matches, all other rows
+    that match are probably already on the same table page,
     and so you save disk accesses and speed up the query.
    
 
@@ -137,30 +137,33 @@ CLUSTER
 
    
     There is another way to cluster data. The
-    CLUSTER command reorders the original table using
-    the ordering of the index you specify. This can be slow
-    on large tables because the rows are fetched from the heap
-    in index order, and if the heap table is unordered, the
+    CLUSTER command reorders the original table by
+    scanning it using the index you specify. This can be slow
+    on large tables because the rows are fetched from the table
+    in index order, and if the table is disordered, the
     entries are on random pages, so there is one disk page
-    retrieved for every row moved. (PostgreSQL has a cache,
-    but the majority of a big table will not fit in the cache.)
+    retrieved for every row moved. (PostgreSQL has
+    a cache, but the majority of a big table will not fit in the cache.)
     The other way to cluster a table is to use
 
 
 CREATE TABLE newtable AS
-    SELECT columnlist FROM table ORDER BY columnlist;
+    SELECT * FROM table ORDER BY columnlist;
 
 
-    which uses the PostgreSQL sorting code in 
-    the ORDER BY clause to create the desired order; this is usually much
-    faster than an index scan for
-    unordered data. You then drop the old table, use
+    which uses the PostgreSQL sorting code
+    to produce the desired order;
+    this is usually much faster than an index scan for disordered data.
+    Then you drop the old table, use
     ALTER TABLE ... RENAME
-    to rename newtable to the old name, and
-    recreate the table's indexes. However, this approach does not preserve
+    to rename newtable to the
+    old name, and recreate the table's indexes.
+    The big disadvantage of this approach is that it does not preserve
     OIDs, constraints, foreign key relationships, granted privileges, and
     other ancillary properties of the table — all such items must be
-    manually recreated.
+    manually recreated.  Another disadvantage is that this way requires a sort
+    temporary file about the same size as the table itself, so peak disk usage
+    is about three times the table size instead of twice the table size.