repack_comment.diff

diff --git a/doc/src/sgml/ref/repack.sgml b/doc/src/sgml/ref/repack.sgml
index 0cb72b6b289..c9ef358261e 100644
--- a/doc/src/sgml/ref/repack.sgml
+++ b/doc/src/sgml/ref/repack.sgml
@@ -78,11 +78,13 @@ REPACK [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] USING
 
    <para>
     If the <literal>USING INDEX</literal> clause is specified, the rows in
-    the table are stored in the order that the index specifies;
-    <firstterm>clustering</firstterm>, because rows are physically clustered
-    afterwards.
-    If an index name is specified in the command, the order implied by that
-    index is used, and that index is configured as the index to cluster on.
+    the table are physically rearranged according to the specified index;
+    this is known as <firstterm>clustering</firstterm>.  For b-tree indexes,
+    this means the table is stored in the index's sort order.  Other clusterable
+    index access methods use their own index scan order, which does not
+    necessarily correspond to a SQL sort order.
+    If an index name is specified in the command, that index is used for
+    clustering, and is configured as the index to cluster on.
     (This also applies to an index given to the <command>CLUSTER</command>
     command.)
     If no index name is specified, then the index that has
@@ -101,12 +103,12 @@ REPACK [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] USING
    <para>
     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.
-    Also, setting the table's <literal>fillfactor</literal> storage parameter
-    to less than 100% can aid in preserving cluster ordering during updates,
-    since updated rows are kept on the same page if enough space is available
-    there.)
+    is made to store new or updated rows according to the clustering order.
+    (If one wishes, one can periodically recluster by issuing the command
+    again.  Also, setting the table's <literal>fillfactor</literal> storage
+    parameter to less than 100% can aid in preserving cluster ordering during
+    updates, since updated rows are kept on the same page if enough space is
+    available there.)
    </para>
 
    <para>
@@ -123,11 +125,12 @@ REPACK [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] USING
    </para>
 
    <para>
-    <command>REPACK</command> can re-sort the table using either an index scan
-    on the specified index (if the index is a b-tree), or a sequential scan
-    followed by sorting.  It will attempt to choose the method that will be
-    faster, based on planner cost parameters and available statistical
-    information.
+    When clustering on a b-tree index, <command>REPACK</command> can rewrite
+    the table using either an index scan on the specified index, or a
+    sequential scan followed by sorting.  It will attempt to choose the method
+    that will be faster, based on planner cost parameters and available
+    statistical information.  When clustering on a non-b-tree index,
+    <command>REPACK</command> uses an index scan.
    </para>
 
    <para>
diff --git a/src/backend/commands/repack.c b/src/backend/commands/repack.c
index 860e2aecbe9..6eb685b2240 100644
--- a/src/backend/commands/repack.c
+++ b/src/backend/commands/repack.c
@@ -1364,10 +1364,16 @@ copy_table_data(Relation NewHeap, Relation OldHeap, Relation OldIndex,
 
 	/*
 	 * Decide whether to use an indexscan or seqscan-and-optional-sort to scan
-	 * the OldHeap.  We know how to use a sort to duplicate the ordering of a
-	 * btree index, and will use seqscan-and-sort for that case if the planner
-	 * tells us it's cheaper.  Otherwise, always indexscan if an index is
-	 * provided, else plain seqscan.
+	 * the OldHeap.  For btree indexes, the scan order is a well-defined sort
+	 * order that can also be reproduced by an explicit sort, so use the
+	 * planner to choose between indexscan and seqscan-and-sort.
+	 *
+	 * Other index AMs can be marked clusterable even though they do not
+	 * provide btree-style ordering information to the planner.  For those,
+	 * clustering means rewriting the heap in the AM's index scan order, which
+	 * may improve locality but cannot be duplicated by sorting here, so leave
+	 * use_sort false.  If no index is provided, use a plain seqscan.
+
 	 */
 	if (OldIndex != NULL && OldIndex->rd_rel->relam == BTREE_AM_OID)
 		use_sort = plan_cluster_use_sort(RelationGetRelid(OldHeap),