head	1.50;
access;
symbols
	REL9_0_0:1.50
	REL9_1_ALPHA1:1.50
	REL9_0_RC1:1.50
	REL9_0_BETA4:1.50
	REL9_0_STABLE:1.50.0.2
	REL9_0_BETA3:1.50
	REL9_0_BETA2:1.50
	REL7_4_29:1.30.2.1
	REL8_0_25:1.35.4.1
	REL8_1_21:1.35.6.1
	REL8_2_17:1.38.2.1
	REL8_3_11:1.44
	REL8_4_4:1.46
	REL9_0_BETA1:1.49
	REL9_0_ALPHA5_BRANCH:1.48.0.4
	REL9_0_ALPHA5:1.48
	REL7_4_28:1.30.2.1
	REL8_0_24:1.35.4.1
	REL8_1_20:1.35.6.1
	REL8_2_16:1.38.2.1
	REL8_3_10:1.44
	REL8_4_3:1.46
	REL9_0_ALPHA4:1.48
	REL9_0_ALPHA4_BRANCH:1.48.0.2
	REL8_5_ALPHA3:1.47
	REL8_5_ALPHA3_BRANCH:1.47.0.4
	REL7_4_27:1.30.2.1
	REL8_0_23:1.35.4.1
	REL8_1_19:1.35.6.1
	REL8_2_15:1.38.2.1
	REL8_3_9:1.44
	REL8_4_2:1.46
	REL8_5_ALPHA2:1.47
	REL8_5_ALPHA2_BRANCH:1.47.0.2
	REL7_4_26:1.30.2.1
	REL8_0_22:1.35.4.1
	REL8_1_18:1.35.6.1
	REL8_2_14:1.38.2.1
	REL8_3_8:1.44
	REL8_4_1:1.46
	REL8_5_ALPHA1:1.46
	REL8_5_ALPHA1_BRANCH:1.46.0.4
	REL8_4_STABLE:1.46.0.2
	REL8_4_0:1.46
	REL8_4_RC2:1.46
	REL8_4_RC1:1.46
	REL8_4_BETA2:1.46
	REL8_4_BETA1:1.46
	REL7_4_25:1.30.2.1
	REL8_0_21:1.35.4.1
	REL8_1_17:1.35.6.1
	REL8_2_13:1.38.2.1
	REL8_3_7:1.44
	REL7_4_24:1.30.2.1
	REL8_0_20:1.35.4.1
	REL8_1_16:1.35.6.1
	REL8_2_12:1.38.2.1
	REL8_3_6:1.44
	REL7_4_23:1.30.2.1
	REL8_0_19:1.35.4.1
	REL8_1_15:1.35.6.1
	REL8_2_11:1.38.2.1
	REL8_3_5:1.44
	REL7_4_22:1.30.2.1
	REL8_0_18:1.35.4.1
	REL8_1_14:1.35.6.1
	REL8_2_10:1.38.2.1
	REL8_3_4:1.44
	REL7_4_21:1.30.2.1
	REL8_0_17:1.35.4.1
	REL8_1_13:1.35.6.1
	REL8_2_9:1.38.2.1
	REL8_3_3:1.44
	REL7_4_20:1.30.2.1
	REL8_0_16:1.35.4.1
	REL8_1_12:1.35.6.1
	REL8_2_8:1.38.2.1
	REL8_3_2:1.44
	REL8_2_7:1.38.2.1
	REL8_3_1:1.44
	REL8_3_STABLE:1.44.0.2
	REL8_3_0:1.44
	REL8_3_RC2:1.44
	REL7_3_21:1.20
	REL7_4_19:1.30.2.1
	REL8_0_15:1.35.4.1
	REL8_1_11:1.35.6.1
	REL8_2_6:1.38.2.1
	REL8_3_RC1:1.44
	REL8_3_BETA4:1.44
	REL8_3_BETA3:1.44
	REL8_3_BETA2:1.43
	REL8_3_BETA1:1.43
	REL7_3_20:1.20
	REL7_4_18:1.30.2.1
	REL8_0_14:1.35.4.1
	REL8_1_10:1.35.6.1
	REL8_2_5:1.38.2.1
	REL7_3_19:1.20
	REL7_4_17:1.30
	REL8_0_13:1.35
	REL8_1_9:1.35
	REL8_2_4:1.38
	REL8_0_12:1.35
	REL8_1_8:1.35
	REL8_2_3:1.38
	REL7_3_18:1.20
	REL7_4_16:1.30
	REL8_0_11:1.35
	REL8_1_7:1.35
	REL8_2_2:1.38
	REL8_0_10:1.35
	REL8_1_6:1.35
	REL8_2_1:1.38
	REL7_4_15:1.30
	REL7_3_17:1.20
	REL8_2_STABLE:1.38.0.2
	REL8_2_0:1.38
	REL8_2_RC1:1.38
	REL8_2_BETA3:1.38
	REL8_2_BETA2:1.36
	REL8_1_5:1.35
	REL8_0_9:1.35
	REL7_4_14:1.30
	REL7_3_16:1.20
	REL8_2_BETA1:1.36
	REL7_3_15:1.20
	REL7_4_13:1.30
	REL8_0_8:1.35
	REL8_1_4:1.35
	REL7_3_14:1.20
	REL7_4_12:1.30
	REL8_0_7:1.35
	REL8_1_3:1.35
	REL7_3_13:1.20
	REL7_4_11:1.30
	REL8_0_6:1.35
	REL8_1_2:1.35
	REL7_3_12:1.20
	REL7_4_10:1.30
	REL8_0_5:1.35
	REL8_1_1:1.35
	REL8_1_STABLE:1.35.0.6
	REL8_1_0:1.35
	REL8_1_0RC1:1.35
	REL8_1_0BETA4:1.35
	REL8_1_0BETA3:1.35
	REL7_3_11:1.20
	REL7_4_9:1.30
	REL8_0_4:1.35
	REL8_1_0BETA2:1.35
	REL8_1_0BETA1:1.35
	REL7_2_8:1.14
	REL7_3_10:1.20
	REL7_4_8:1.30
	REL8_0_3:1.35
	REL8_0_2:1.35
	REL7_2_7:1.14
	REL7_3_9:1.20
	REL7_4_7:1.30
	REL8_0_1:1.35
	REL8_0_STABLE:1.35.0.4
	REL8_0_0:1.35.0.2
	REL8_0_0RC5:1.35
	REL8_0_0RC4:1.35
	REL8_0_0RC3:1.34
	REL8_0_0RC2:1.34
	REL8_0_0RC1:1.34
	REL8_0_0BETA5:1.34
	REL8_0_0BETA4:1.33
	REL7_4_6:1.30
	REL7_3_8:1.20
	REL7_2_6:1.14
	REL8_0_0BETA3:1.33
	REL8_0_0BETA2:1.33
	REL7_2_5:1.14
	REL7_4_5:1.30
	REL7_3_7:1.20
	REL7_4_4:1.30
	REL8_0_0BETA1:1.32
	REL7_4_3:1.30
	REL7_4_2:1.30
	REL7_3_6:1.20
	REL7_4_1:1.30
	REL7_3_5:1.20
	REL7_4:1.30
	REL7_4_RC2:1.30
	REL7_4_STABLE:1.30.0.2
	REL7_4_RC1:1.30
	REL7_4_BETA5:1.29
	REL7_4_BETA4:1.29
	REL7_4_BETA3:1.29
	REL7_4_BETA2:1.26
	WIN32_DEV:1.26.0.2
	REL7_4_BETA1:1.26
	REL7_3_4:1.20
	REL7_3_2:1.20
	REL7_2_4:1.14
	REL7_3_STABLE:1.20.0.2
	REL7_2_3:1.14
	REL7_2_STABLE:1.14.0.2
	REL7_2:1.14
	REL7_2_RC2:1.14
	REL7_2_RC1:1.14
	REL7_2_BETA5:1.14
	REL7_2_BETA4:1.13
	REL7_2_BETA3:1.12
	REL7_2_BETA2:1.12
	REL7_2_BETA1:1.11
	REL7_1_2:1.10
	REL7_1_STABLE:1.10.0.2
	REL7_1_BETA:1.9
	REL7_1_BETA3:1.9
	REL7_1_BETA2:1.9
	REL7_1:1.10
	REL7_0_PATCHES:1.7.0.2
	REL7_0:1.7
	REL6_5_PATCHES:1.6.0.2
	REL6_5:1.6
	REL6_4:1.4.0.2;
locks; strict;
comment	@# @;


1.50
date	2010.05.11.16.07.42;	author rhaas;	state Exp;
branches;
next	1.49;

1.49
date	2010.04.03.07.22.57;	author petere;	state Exp;
branches;
next	1.48;

1.48
date	2010.02.07.20.48.09;	author tgl;	state Exp;
branches;
next	1.47;

1.47
date	2009.09.19.10.23.26;	author petere;	state Exp;
branches;
next	1.46;

1.46
date	2008.11.24.08.46.03;	author petere;	state Exp;
branches;
next	1.45;

1.45
date	2008.11.14.10.22.45;	author petere;	state Exp;
branches;
next	1.44;

1.44
date	2007.11.07.14.07.53;	author petere;	state Exp;
branches;
next	1.43;

1.43
date	2007.05.11.19.40.07;	author neilc;	state Exp;
branches;
next	1.42;

1.42
date	2007.04.08.02.07.35;	author tgl;	state Exp;
branches;
next	1.41;

1.41
date	2007.04.08.00.26.33;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	2007.02.01.00.28.18;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	2007.01.31.23.26.02;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2006.11.04.19.03.51;	author tgl;	state Exp;
branches
	1.38.2.1;
next	1.37;

1.37
date	2006.10.31.01.52.31;	author neilc;	state Exp;
branches;
next	1.36;

1.36
date	2006.09.16.00.30.17;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches
	1.35.4.1
	1.35.6.1;
next	1.34;

1.34
date	2004.11.15.06.32.15;	author neilc;	state Exp;
branches;
next	1.33;

1.33
date	2004.08.21.15.45.46;	author tgl;	state Exp;
branches;
next	1.32;

1.32
date	2004.03.23.13.21.41;	author neilc;	state Exp;
branches;
next	1.31;

1.31
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.30;

1.30
date	2003.11.02.12.59.54;	author petere;	state Exp;
branches
	1.30.2.1;
next	1.29;

1.29
date	2003.09.12.00.12.47;	author tgl;	state Exp;
branches;
next	1.28;

1.28
date	2003.09.09.18.28.52;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2003.08.31.17.32.21;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2003.04.15.13.25.08;	author petere;	state Exp;
branches
	1.26.2.1;
next	1.25;

1.25
date	2003.03.25.16.15.39;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2003.02.19.04.06.28;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2002.12.30.18.42.12;	author tgl;	state Exp;
branches;
next	1.22;

1.22
date	2002.11.18.17.12.06;	author momjian;	state Exp;
branches;
next	1.21;

1.21
date	2002.11.15.03.09.35;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2002.09.21.18.32.54;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2002.08.11.02.43.57;	author tgl;	state Exp;
branches;
next	1.18;

1.18
date	2002.08.10.21.03.33;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2002.08.10.20.43.46;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	2002.04.23.02.07.15;	author tgl;	state Exp;
branches;
next	1.15;

1.15
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.14;

1.14
date	2001.12.30.04.36.52;	author tgl;	state Exp;
branches;
next	1.13;

1.13
date	2001.12.08.03.24.34;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	2001.10.31.04.49.43;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2001.09.03.12.57.49;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2001.01.13.23.58.55;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2000.07.22.04.30.26;	author momjian;	state Exp;
branches;
next	1.8;

1.8
date	2000.07.22.02.39.10;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	99.07.22.15.09.06;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	99.07.06.17.16.34;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.12.29.02.24.33;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.10.30.19.33.37;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.16.14.42.56;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.09.07.15.58.03;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.05.13.05.33.58;	author thomas;	state Exp;
branches;
next	;

1.26.2.1
date	2003.09.07.04.36.44;	author momjian;	state Exp;
branches;
next	;

1.30.2.1
date	2007.05.13.16.04.22;	author mha;	state Exp;
branches;
next	;

1.35.4.1
date	2007.05.13.16.04.28;	author mha;	state Exp;
branches;
next	;

1.35.6.1
date	2007.05.13.16.04.35;	author mha;	state Exp;
branches;
next	;

1.38.2.1
date	2007.05.13.16.04.40;	author mha;	state Exp;
branches;
next	;


desc
@@


1.50
log
@Mention related ALTER TABLE variants in documentation for CLUSTER.

As suggested by Andy Lester.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.49 2010/04/03 07:22:57 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CLUSTER">
 <refmeta>
  <refentrytitle>CLUSTER</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CLUSTER</refname>
  <refpurpose>cluster a table according to an index</refpurpose>
 </refnamediv>

 <indexterm zone="sql-cluster">
  <primary>CLUSTER</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CLUSTER [VERBOSE] <replaceable class="PARAMETER">table_name</replaceable> [ USING <replaceable class="PARAMETER">index_name</replaceable> ]
CLUSTER [VERBOSE]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CLUSTER</command> instructs <productname>PostgreSQL</productname>
   to cluster the table specified
   by <replaceable class="parameter">table_name</replaceable>
   based on the index specified by
   <replaceable class="parameter">index_name</replaceable>. The index must
   already have been defined on
   <replaceable class="parameter">table_name</replaceable>.
  </para>

  <para>
   When a table is clustered, it is physically reordered
   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.  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>
   When a table is clustered, <productname>PostgreSQL</productname>
   remembers which index it was clustered by.  The form
   <command>CLUSTER <replaceable class="parameter">table_name</replaceable></command>
   reclusters the table using the same index as before.  You can also
   use the <literal>CLUSTER</literal> or <literal>SET WITHOUT CLUSTER</literal>
   forms of <xref linkend="SQL-ALTERTABLE"> to set the index to be used for
   future cluster operations, or to clear any previous setting.
  </para>

  <para>
   <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>

  <para>
   When a table is being clustered, an <literal>ACCESS
   EXCLUSIVE</literal> lock is acquired on it. This prevents any other
   database operations (both reads and writes) from operating on the
   table until the <command>CLUSTER</command> is finished.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="PARAMETER">table_name</replaceable></term>
    <listitem>
     <para>
      The name (possibly schema-qualified) of a table.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">index_name</replaceable></term>
    <listitem>
     <para>
      The name of an index.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>VERBOSE</literal></term>
    <listitem>
     <para>
      Prints a progress report as each table is clustered.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

   <para>
    In cases where you are accessing single rows randomly
    within a table, the actual order of the data in the
    table is unimportant. However, if you tend to access some
    data more than others, and there is an index that groups
    them together, you will benefit from using <command>CLUSTER</command>.
    If you are requesting a range of indexed values from a table, or a
    single indexed value that has multiple rows that match,
    <command>CLUSTER</command> will help because once the index identifies the
    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.
   </para>

   <para>
    During the cluster operation, a temporary copy of the table is created
    that contains the table data in the index order.  Temporary copies of
    each index on the table are created as well.  Therefore, you need free
    space on disk at least equal to the sum of the table size and the index
    sizes.
   </para>

   <para>
    Because <command>CLUSTER</command> remembers the clustering information,
    one can cluster the tables one wants clustered manually the first time, and
    setup a timed event similar to <command>VACUUM</command> so that the tables
    are periodically reclustered.
   </para>

   <para>
    Because the planner records statistics about the ordering of
    tables, it is advisable to run <xref linkend="sql-analyze">
    on the newly clustered table.
    Otherwise, the planner might make poor choices of query plans.
   </para>

   <para>
    There is another way to cluster data. The
    <command>CLUSTER</command> 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. (<productname>PostgreSQL</productname> 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:

<programlisting>
CREATE TABLE <replaceable class="parameter">newtable</replaceable> AS
    SELECT * FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>;
</programlisting>

    which uses the <productname>PostgreSQL</productname> 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
    <command>ALTER TABLE ... RENAME</command>
    to rename <replaceable class="parameter">newtable</replaceable> 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 &mdash; all such items must be
    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.
   </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Cluster the table <literal>employees</literal> on the basis of
   its index <literal>employees_ind</literal>:
<programlisting>
CLUSTER employees USING employees_ind;
</programlisting>
  </para>

  <para>
   Cluster the <literal>employees</literal> table using the same
   index that was used before:
<programlisting>
CLUSTER employees;
</programlisting>
  </para>

  <para>
   Cluster all tables in the database that have previously been clustered:
<programlisting>
CLUSTER;
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   There is no <command>CLUSTER</command> statement in the SQL standard.
  </para>

  <para>
   The syntax
<synopsis>
CLUSTER <replaceable class="PARAMETER">index_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable>
</synopsis>
  is also supported for compatibility with pre-8.3 <productname>PostgreSQL</>
  versions.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-clusterdb"></member>
  </simplelist>
 </refsect1>
</refentry>
@


1.49
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.48 2010/02/07 20:48:09 tgl Exp $
d58 4
a61 1
   reclusters the table using the same index as before.
@


1.48
log
@Create a "relation mapping" infrastructure to support changing the relfilenodes
of shared or nailed system catalogs.  This has two key benefits:

* The new CLUSTER-based VACUUM FULL can be applied safely to all catalogs.

* We no longer have to use an unsafe reindex-in-place approach for reindexing
  shared catalogs.

CLUSTER on nailed catalogs now works too, although I left it disabled on
shared catalogs because the resulting pg_index.indisclustered update would
only be visible in one database.

Since reindexing shared system catalogs is now fully transactional and
crash-safe, the former special cases in REINDEX behavior have been removed;
shared catalogs are treated the same as non-shared.

This commit does not do anything about the recently-discussed problem of
deadlocks between VACUUM FULL/CLUSTER on a system catalog and other
concurrent queries; will address that in a separate patch.  As a stopgap,
parallel_schedule has been tweaked to run vacuum.sql by itself, to avoid
such failures during the regression tests.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.47 2009/09/19 10:23:26 petere Exp $
d8 1
a8 1
  <refentrytitle id="sql-cluster-title">CLUSTER</refentrytitle>
d144 2
a145 2
    tables, it is advisable to run <xref linkend="sql-analyze"
    endterm="sql-analyze-title"> on the newly clustered table.
d229 1
a229 1
   <member><xref linkend="app-clusterdb" endterm="app-clusterdb-title"></member>
@


1.47
log
@Make the placeholder naming in the synopses of the SQL help more consistent
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.46 2008/11/24 08:46:03 petere Exp $
d33 1
a33 1
   <command>CLUSTER</command> instructs <productname>PostgreSQL</productname> 
d38 1
a38 1
   already have been defined on 
d49 3
a51 3
   the table's <literal>FILLFACTOR</literal> storage parameter to less than 100% can aid
   in preserving cluster ordering during updates, since updated rows
   are preferentially kept on the same page.)
@


1.46
log
@CLUSTER VERBOSE and corresponding clusterdb --verbose option

Jim Cox and Peter Eisentraut
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.45 2008/11/14 10:22:45 petere Exp $
d24 1
a24 1
CLUSTER [VERBOSE] <replaceable class="PARAMETER">tablename</replaceable> [ USING <replaceable class="PARAMETER">indexname</replaceable> ]
d35 1
a35 1
   by <replaceable class="parameter">tablename</replaceable>
d37 1
a37 1
   <replaceable class="parameter">indexname</replaceable>. The index must
d39 1
a39 1
   <replaceable class="parameter">tablename</replaceable>.
d57 1
a57 1
   <command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>
d82 1
a82 1
    <term><replaceable class="PARAMETER">tablename</replaceable></term>
d91 1
a91 1
    <term><replaceable class="PARAMETER">indexname</replaceable></term>
d218 1
a218 1
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
@


1.45
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.44 2007/11/07 14:07:53 petere Exp $
d24 2
a25 2
CLUSTER <replaceable class="PARAMETER">tablename</replaceable> [ USING <replaceable class="PARAMETER">indexname</replaceable> ]
CLUSTER
d98 9
@


1.44
log
@<optional> cannot be used here, because psql doesn't handle it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.43 2007/05/11 19:40:07 neilc Exp $
d9 1
@


1.43
log
@Improvements to the SGML docs for TRUNCATE and CLUSTER.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.42 2007/04/08 02:07:35 tgl Exp $
d23 1
a23 1
CLUSTER <replaceable class="PARAMETER">tablename</replaceable> <optional> USING <replaceable class="PARAMETER">indexname</replaceable> </optional>
@


1.42
log
@Minor editorialization on CLUSTER reference page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.41 2007/04/08 00:26:33 momjian Exp $
d48 1
a48 1
   the table's FILLFACTOR storage parameter to less than 100% can aid
@


1.41
log
@Support syntax "CLUSTER table USING index", which is more logical.

Holger Schurig
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.40 2007/02/01 00:28:18 momjian Exp $
d23 1
a23 1
CLUSTER <replaceable class="PARAMETER">tablename</replaceable> [ USING <replaceable class="PARAMETER">indexname</replaceable> ]
d46 5
a50 2
   updated rows according to their index order.  If one wishes, one can
   periodically recluster by issuing the command again.
d55 1
a55 1
   remembers on which index it was clustered.  The form
d57 1
a57 1
   reclusters the table on the same index that it was clustered before.
d61 3
a63 4
   <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
d202 5
a206 1
   The syntax:
d210 2
a211 2
  is also supported for compatibility with pre-8.3 <productname>PostgreSQL</> installations.
  There is no <command>CLUSTER</command> statement in the SQL standard.
@


1.40
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.39 2007/01/31 23:26:02 momjian Exp $
d23 1
a23 2
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
CLUSTER <replaceable class="PARAMETER">tablename</replaceable>
d79 1
a79 1
    <term><replaceable class="PARAMETER">indexname</replaceable></term>
d82 1
a82 1
      The name of an index.
d88 1
a88 1
    <term><replaceable class="PARAMETER">tablename</replaceable></term>
d91 1
a91 1
      The name (possibly schema-qualified) of a table.
d174 1
a174 1
   its index <literal>emp_ind</literal>:
d176 1
a176 1
CLUSTER emp_ind ON emp;
d184 1
a184 1
CLUSTER emp;
d200 6
a205 1
   There is no <command>CLUSTER</command> statement in the SQL standard.
@


1.39
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.38 2006/11/04 19:03:51 tgl Exp $
d147 1
a147 1
    The other way to cluster a table is to use
@


1.38
log
@Add note about space usage of 'manual' approach to clustering, per
suggestion from Sergey Koposov.  Also some other minor editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.37 2006/10/31 01:52:31 neilc Exp $
d135 1
a135 1
    Otherwise, the planner may make poor choices of query plans.
@


1.38.2.1
log
@Document that CLUSTER breaks MVCC visibility rules.
(Not needed in cvs head, because CLUSTER itself is fixed there)

Heikki Linnakangas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.38 2006/11/04 19:03:51 tgl Exp $
a102 11
    <command>CLUSTER</command> loses all visibility information of tuples,
    which makes the table look empty to any snapshot that was taken
    before the <command>CLUSTER</command> command finished. That makes
    <command>CLUSTER</command> unsuitable for applications where
    transactions that access the table being clustered are run concurrently
    with <command>CLUSTER</command>. This is most visible with serializable
    transactions, because they take only one snapshot at the beginning of the
    transaction, but read-committed transactions are also affected.
   </para>

   <para>
@


1.37
log
@Add text to the VACUUM, REINDEX, DROP TABLESPACE and CREATE TABLESPACE
reference pages documenting that these commands cannot be used within
a transaction block. Also make some minor improvements to the psql
reference page. Patch from Simon Riggs, minor editorialization by
myself.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.36 2006/09/16 00:30:17 momjian Exp $
d111 2
a112 2
    heap page for the first row that matches, all other rows
    that match are probably already on the same heap page,
d140 4
a143 4
    <command>CLUSTER</command> 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
d145 2
a146 2
    retrieved for every row moved. (<productname>PostgreSQL</productname> has a cache,
    but the majority of a big table will not fit in the cache.)
d151 1
a151 1
    SELECT <replaceable class="parameter">columnlist</replaceable> FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>;
d154 4
a157 4
    which uses the <productname>PostgreSQL</productname> sorting code in 
    the <literal>ORDER BY</literal> 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
d159 3
a161 2
    to rename <replaceable class="parameter">newtable</replaceable> to the old name, and
    recreate the table's indexes. However, this approach does not preserve
d164 3
a166 1
    manually recreated.
@


1.36
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
d63 2
a64 2
   form of <command>CLUSTER</command> cannot be called from inside a
   transaction or function.
@


1.35
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.34 2004/11/15 06:32:15 neilc Exp $
a209 18

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

@


1.35.6.1
log
@Document that CLUSTER breaks MVCC visibility rules.
(Not needed in cvs head, because CLUSTER itself is fixed there)

Heikki Linnakangas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
a102 11
    <command>CLUSTER</command> loses all visibility information of tuples,
    which makes the table look empty to any snapshot that was taken
    before the <command>CLUSTER</command> command finished. That makes
    <command>CLUSTER</command> unsuitable for applications where
    transactions that access the table being clustered are run concurrently
    with <command>CLUSTER</command>. This is most visible with serializable
    transactions, because they take only one snapshot at the beginning of the
    transaction, but read-committed transactions are also affected.
   </para>

   <para>
@


1.35.4.1
log
@Document that CLUSTER breaks MVCC visibility rules.
(Not needed in cvs head, because CLUSTER itself is fixed there)

Heikki Linnakangas
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
a102 11
    <command>CLUSTER</command> loses all visibility information of tuples,
    which makes the table look empty to any snapshot that was taken
    before the <command>CLUSTER</command> command finished. That makes
    <command>CLUSTER</command> unsuitable for applications where
    transactions that access the table being clustered are run concurrently
    with <command>CLUSTER</command>. This is most visible with serializable
    transactions, because they take only one snapshot at the beginning of the
    transaction, but read-committed transactions are also affected.
   </para>

   <para>
@


1.34
log
@Replace "--" and "---" with "&mdash;" as appropriate, for better-looking
output.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.33 2004/08/21 15:45:46 tgl Exp $
d187 1
a187 1
   Cluster all the tables on the database that have previously been clustered:
@


1.33
log
@Fix typo (extraneous comma).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.32 2004/03/23 13:21:41 neilc Exp $
d162 1
a162 1
    other ancillary properties of the table --- all such items must be
@


1.32
log
@Minor SGML improvements.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.31 2003/11/29 19:51:38 pgsql Exp $
d54 1
a54 1
   <command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>,
@


1.31
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.30 2003/11/02 12:59:54 petere Exp $
d132 4
a135 3
    Because the planner records statistics about the ordering of tables, it
    is advisable to run <command>ANALYZE</command> on the newly clustered
    table.  Otherwise, the planner may make poor choices of query plans.
d179 1
a179 1
   Cluster the <literal>employees</literal> relation using the same
@


1.30
log
@Fix language.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $
@


1.30.2.1
log
@Document that CLUSTER breaks MVCC visibility rules.
(Not needed in cvs head, because CLUSTER itself is fixed there)

Heikki Linnakangas
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.30 2003/11/02 12:59:54 petere Exp $
a102 11
    <command>CLUSTER</command> loses all visibility information of tuples,
    which makes the table look empty to any snapshot that was taken
    before the <command>CLUSTER</command> command finished. That makes
    <command>CLUSTER</command> unsuitable for applications where
    transactions that access the table being clustered are run concurrently
    with <command>CLUSTER</command>. This is most visible with serializable
    transactions, because they take only one snapshot at the beginning of the
    transaction, but read-committed transactions are also affected.
   </para>

   <para>
@


1.29
log
@More cleanup of Diagnostics sections.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.28 2003/09/09 18:28:52 tgl Exp $
d70 2
a71 3
   database operations (both reads and writes) from preceding on the
   table until the <command>CLUSTER</command> is finished. See
   <xref linkend="explicit-locking"> for more information on database locking.
@


1.28
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.27 2003/08/31 17:32:21 petere Exp $
d77 1
a77 1
  <title>Parameter</title>
@


1.27
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.26 2003/04/15 13:25:08 petere Exp $
a93 15
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <variablelist>
   <varlistentry>
    <term><computeroutput>CLUSTER</computeroutput></term>
    <listitem>
     <para>
      The clustering was done successfully.
@


1.26
log
@Bring SQL ref pages to consistent format, part 1.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.25 2003/03/25 16:15:39 petere Exp $
d16 4
@


1.26.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.27 2003/08/31 17:32:21 petere Exp $
a15 4

 <indexterm zone="sql-cluster">
  <primary>CLUSTER</primary>
 </indexterm>
@


1.25
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.24 2003/02/19 04:06:28 momjian Exp $
d11 1
d13 2
a14 6
  <refname>
   CLUSTER
  </refname>
  <refpurpose>
   cluster a table according to an index
  </refpurpose>
d16 1
d18 1
a18 4
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
d22 2
a23 39
  </synopsis>

  <refsect2 id="R2-SQL-CLUSTER-1">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
   </para>
   <variablelist>
    <varlistentry>
     <term><replaceable class="PARAMETER">indexname</replaceable></term>
     <listitem>
      <para>
       The name of an index.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><replaceable class="PARAMETER">table</replaceable></term>
     <listitem>
      <para>
       The name (possibly schema-qualified) of a table.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>

  <refsect2 id="R2-SQL-CLUSTER-2">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
d25 2
a26 15
    <variablelist>
     <varlistentry>
      <term><computeroutput>
CLUSTER
       </computeroutput></term>
      <listitem>
       <para>
	The clustering was done successfully.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>
a27 7
 <refsect1 id="R1-SQL-CLUSTER-1">
  <refsect1info>
   <date>1998-09-08</date>
  </refsect1info>
  <title>
   Description
  </title>
d31 1
a31 1
   by <replaceable class="parameter">table</replaceable>
d43 2
a44 2
   updated tuples according to their index order.  If one wishes, one can
   periodically re-cluster by issuing the command again.
d51 1
a51 1
   re-clusters the table on the same index that it was clustered before.
d55 1
a55 1
   <command>CLUSTER</command> without any parameter re-clusters all the tables
d70 4
d75 38
a112 7
  <refsect2 id="R2-SQL-CLUSTER-3">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    Notes
   </title>
d116 1
a116 1
    within a table, the actual order of the data in the heap
d120 1
a120 7
   </para>

   <para> 
    Another place where <command>CLUSTER</command> is helpful is in
    cases where you use an
    index to pull out several rows from a table. If you are
    requesting a range of indexed values from a table, or a
d125 1
a125 1
    saving disk accesses and speeding up the query.
a136 6
    <command>CLUSTER</command> preserves <command>GRANT</command>,
    inheritance, index, foreign key, and other ancillary information
    about the table.
   </para>

   <para>
d140 1
a140 1
    are periodically re-clustered.
d144 1
a144 1
    Because the optimizer records statistics about the ordering of tables, it
d146 1
a146 1
    table.  Otherwise, the optimizer may make poor choices of query plans.
d160 4
a163 4
    <programlisting>
SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <replaceable class="parameter">newtable</replaceable>
     FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>
    </programlisting>
d166 1
a166 1
    the ORDER BY clause to create the desired order; this is usually much
d169 1
a169 1
    <command>ALTER TABLE...RENAME</command>
d176 1
d178 2
a179 2
  </refsect2>
 </refsect1>
a180 4
 <refsect1 id="R1-SQL-CLUSTER-2">
  <title>
   Usage
  </title>
d182 5
a186 2
   Cluster the <literal>employees</literal> relation on the basis of
   its ID attribute:
d188 1
a188 3
  <programlisting>
CLUSTER emp_ind ON emp;
  </programlisting>
d192 3
d196 1
a196 3
  <programlisting>
CLUSTER emp;
  </programlisting>
d199 3
a202 3
  <programlisting>
CLUSTER;
  </programlisting>
d205 6
a210 16
 <refsect1 id="R1-SQL-CLUSTER-3">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-CLUSTER-4">
   <refsect2info>
    <date>1998-09-08</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>CLUSTER</command> statement in SQL92.
   </para>
  </refsect2>
@


1.24
log
@This patch makes the following changes to the documentation:

- more work from the SGML police

- some grammar improvements: rewriting a paragraph or two, replacing
contractions where (IMHO) appropriate

- fix missing utility commands in lock mode docs

- improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.23 2002/12/30 18:42:12 tgl Exp $
d129 2
a130 2
   table until the <command>CLUSTER</command> is finished. See the
   &cite-user; for more information on database locking.
@


1.23
log
@Code review for CLUSTER ALL patch.  Fix bogus locking, incorrect transaction
stop/start nesting, other infelicities.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.22 2002/11/18 17:12:06 momjian Exp $
d120 1
a120 1
   by a superuser.  (Never-clustered tables are not touched.)  This
d125 8
d170 3
a172 2
    <command>CLUSTER</command> preserves GRANT, inheritance, index, foreign
    key, and other ancillary information about the table.
d224 2
a225 1
   Cluster the employees relation on the basis of its ID attribute:
d231 2
a232 1
   Cluster the employees relation using the same index that was used before:
d261 8
@


1.22
log
@Remove ALL from CLUSTER ALL.  Use just CLUSTER.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.21 2002/11/15 03:09:35 momjian Exp $
d111 1
a111 1
   remembers on which index it was clustered.  In calls to
d113 1
a113 1
   the table is clustered on the same index that it was clustered before.
d117 4
a120 2
   A simple <command>CLUSTER</command> clusters all the tables in the database
   that the calling user owns and uses the saved cluster information.  This
d162 2
a163 2
	<command>CLUSTER</command> preserves GRANT, inheritance, index, foreign
	key, and other ancillary information about the table.
d167 4
a170 4
	Because <command>CLUSTER</command> remembers the clustering information,
	one can cluster the tables one wants clustered manually the first time, and
	setup a timed event similar to <command>VACUUM</command> so that the tables
	are periodically and automatically clustered.
@


1.21
log
@New version attached.  The following is implemented:

- CLUSTER ALL clusters all the tables that have some index with
  indisclustered set and the calling user owns.
- CLUSTER tablename clusters the named table, using the index with
  indisclustered set.  If no index has the bit set, throws elog(ERROR).
- The multi-relation version (CLUSTER ALL) uses a multitransaction
  approach, similar to what VACUUM does.

Alvaro Herrera
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.20 2002/09/21 18:32:54 petere Exp $
d26 1
a26 1
CLUSTER ALL
d117 2
a118 2
   In calls to <command>CLUSTER ALL</command>, all the tables in the database
   that the calling user owns are clustered using the saved information.  This
d228 1
a228 1
CLUSTER ALL;
@


1.20
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.19 2002/08/11 02:43:57 tgl Exp $
d25 2
d109 14
d160 9
a168 2
    CLUSTER preserves GRANT, inheritance, index, foreign key, and other
    ancillary information about the table.
d217 12
@


1.19
log
@Editorial improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.18 2002/08/10 21:03:33 momjian Exp $
d172 1
a172 1
    faster than an indexscan for
@


1.18
log
@Mention ANALYZE after CLUSTER.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.17 2002/08/10 20:43:46 momjian Exp $
a75 13
     <varlistentry>
      <term><computeroutput>
ERROR: Relation <replaceable class="PARAMETER">table</replaceable> does not exist!
       </computeroutput></term>
      <listitem>
       <para>
	<comment>
	 The specified relation was not shown in the error message,
	 which contained a random string instead of the relation name.
	</comment>
       </para>
      </listitem>
     </varlistentry>
d91 1
a91 1
   by <replaceable class="parameter">table</replaceable> approximately
d100 5
a104 5
   based on the index information. The clustering is static.
   In other words, as the table is updated, the changes are
   not clustered. No attempt is made to keep new instances or
   updated tuples clustered.  If one wishes, one can
   re-cluster manually by issuing the command again.
d136 21
a156 2
    There are two ways to cluster data. The first is with the
    <command>CLUSTER</command> command, which reorders the original table with
d161 3
a163 6
    retrieved for every row moved. <productname>PostgreSQL</productname> has a cache,
    but the majority of a big table will not fit in the cache.
   </para>

   <para> 
    Another way to cluster data is to use
d171 2
a172 1
    the ORDER BY clause to match the index, and which is much faster for
d176 4
a179 20
    recreate the table's indexes. The only problem is that <acronym>OID</acronym>s
    will not be preserved. From then on, <command>CLUSTER</command> should be
    fast because most of the heap data has already been
    ordered, and the existing index is used.
   </para>

   <para>
    During the cluster operation, a temporal table is created that contains
    the table in the index order. Due to this, you need to have free space
    on disk at least the size of the table itself, or the biggest index if
    you have one that is larger than the table.
   </para>

   <para>
    CLUSTER preserves GRANT, inheritance index, and foreign key information.
   </para>

   <para>
    Because the optimizer records the cluster status of tables, it is 
    advised to run <command>ANALYZE</command> on the newly clustered table.
d190 1
a190 1
   Cluster the employees relation on the basis of its salary attribute:
@


1.17
log
@Major improvement in CLUSTER which preserves table characteristics using
relfilenode.

I sent the CLUSTER patch a few days ago and I think it was missed.  I
append it again, this time including the regression test files.  For the
committer, please note that you have to cvs add the files as they don't
exist.  Maybe add to the parallel and serial schedules also, but I don't
know such stuff.

Alvaro Herrera (<alvherre[a]atentus.com>)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/cluster.sgml,v 1.16 2002/04/23 02:07:15 tgl Exp $
d186 6
a191 3
    As opposed to previous releases, CLUSTER does not lose GRANT,
    inheritance or foreign key information, and preserves indexes
    other than the one being used for the CLUSTER.
d244 1
@


1.16
log
@Update SQL-command reference pages for schema features.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $
a77 13
ERROR: relation &lt;<replaceable class="PARAMETER">tablerelation_number</replaceable>&gt; inherits "<replaceable class="PARAMETER">table</replaceable>"
       </computeroutput></term>
      <listitem>
       <para>
	<comment>
	 This is not documented anywhere. It seems not to be possible to
	 cluster a table that is inherited.
	</comment>
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
a128 7
    The table is actually copied to a temporary table in index
    order, then renamed back to the original name.  For this
    reason, all grant permissions and other indexes are lost
    when clustering is performed.
   </para>

   <para>
d177 14
@


1.15
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.14 2001/12/30 04:36:52 tgl Exp $
d49 1
a49 1
       The name of a table.
@


1.14
log
@Repair example, per note in interactive docs.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.13 2001/12/08 03:24:34 thomas Exp $
d8 1
a8 3
  <refentrytitle id="sql-cluster-title">
   CLUSTER
  </refentrytitle>
@


1.13
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.12 2001/10/31 04:49:43 momjian Exp $
d193 2
a194 2
    to rename <replaceable class="parameter">temp</replaceable> to the old name, and
    recreate any indexes. The only problem is that <acronym>OID</acronym>s
@


1.12
log
@Add ALTER TABLE ADD UNIQUE regression tests from Christopher Kings-Lynne.

Add space between slash for ALTER TABLE / ADD ....

Regression and *.po updates to follow.
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.11 2001/09/03 12:57:49 petere Exp $
Postgres documentation
d117 1
a117 1
   <command>CLUSTER</command> instructs <productname>Postgres</productname> 
d177 1
a177 1
    retrieved for every row moved. <productname>Postgres</productname> has a cache,
d189 1
a189 1
    which uses the <productname>Postgres</productname> sorting code in 
@


1.11
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.10 2001/01/13 23:58:55 petere Exp $
d192 1
a192 1
    <command>ALTER TABLE/RENAME</command>
@


1.10
log
@Terminology cleanup: class -> table, instance -> row, attribute -> column,
etc.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.9 2000/07/22 04:30:26 momjian Exp $
d18 1
a18 1
   Gives storage clustering advice to the server
@


1.9
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.8 2000/07/22 02:39:10 momjian Exp $
d26 1
a26 1
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">table</replaceable>
d118 1
a118 1
   to cluster the class specified
d123 1
a123 1
   <replaceable class="parameter">classname</replaceable>.
d127 1
a127 1
   When a class is clustered, it is physically reordered
d129 1
a129 1
   In other words, as the class is updated, the changes are
@


1.8
log
@Cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.7 1999/07/22 15:09:06 thomas Exp $
d132 1
a132 1
   recluster manually by issuing the command again.
@


1.7
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d207 1
a207 1
   Cluster the employees relation on the basis of its salary attribute
@


1.6
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d18 1
a18 1
   Gives storage clustering advice to the backend
d23 1
a23 1
   <date>1998-09-08</date>
d80 1
a80 1
ERROR: relation &lt;<replaceable class="PARAMETER">tablerelation_number</replaceable>&gt; inherits "invoice"
d93 1
a93 1
ERROR: Relation x does not exist!
d98 1
a98 1
	 The relation complained of was not shown in the error message,
d119 1
a119 1
   by <replaceable class="parameter">classname</replaceable> approximately
d125 1
d159 2
a160 1
    Another place <command>CLUSTER</command> is helpful is in cases where you use an
d183 1
d185 2
a186 1
SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ... ORDER BY ...
d188 3
a190 2
    This uses the <productname>Postgres</productname> sorting code in
    ORDER BY to match the index, and is much faster for
a217 2
  <para>
  </para>
@


1.5
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d1 14
a14 14
<REFENTRY ID="SQL-CLUSTER">
 <REFMETA>
 <REFENTRYTITLE>
  CLUSTER
 </REFENTRYTITLE>
 <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
 <REFNAME>
  CLUSTER
 </REFNAME>
 <REFPURPOSE>
  Gives storage clustering advice to the backend
 </REFPURPOSE>
d16 161
a176 167
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-08</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
   CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  </SYNOPSIS>
 
 <REFSECT2 ID="R2-SQL-CLUSTER-1">
  <REFSECT2INFO>
  <DATE>1998-09-08</DATE>
  </REFSECT2INFO>
  <TITLE>
  Inputs
  </TITLE>
  <PARA>
  </PARA>
  <VARIABLELIST>
  <VARLISTENTRY>
   <TERM>
    <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE>
   </TERM>
   <LISTITEM>
   <PARA>
    The name of an index.
   </PARA>
   </LISTITEM>
  </VARLISTENTRY>
  <VARLISTENTRY>
   <TERM>
    <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
   </TERM>
   <LISTITEM>
   <PARA>
    The name of a table.
   </PARA>
   </LISTITEM>
  </VARLISTENTRY>
  </VARIABLELIST>
 </REFSECT2>
 
 <REFSECT2 ID="R2-SQL-CLUSTER-2">
  <REFSECT2INFO>
  <DATE>1998-09-08</DATE>
  </REFSECT2INFO>
  <TITLE>
  Outputs
  </TITLE>
  <PARA>
    <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	 <returnvalue>CLUSTER</returnvalue>
	 </TERM>
	 <LISTITEM>
	 <PARA>
	  The clustering was done successfully.
	 </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
<returnvalue>ERROR: relation &lt;<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>&gt; inherits "invoice"</returnvalue>
	 </TERM>
	 <LISTITEM>
	 <PARA>

	  <comment>
	  This is not documented anywhere. It seems not to be possible to
	  cluster a table that is inherited.
	  </comment>
	 </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	 <returnvalue>ERROR: Relation x does not exist!</returnvalue>
	 </TERM>
	 <LISTITEM>
	 <PARA>

	  <comment>
	  The relation complained of was not shown in the error message,
	  which contained a random string instead of the relation name.
	  </comment>
	 </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

    </VARIABLELIST>
   </para>
  </REFSECT2>
 </REFSYNOPSISDIV>
 
 <REFSECT1 ID="R1-SQL-CLUSTER-1">
 <REFSECT1INFO>
  <DATE>1998-09-08</DATE>
 </REFSECT1INFO>
 <TITLE>
  Description
 </TITLE>
 <PARA>
  <command>CLUSTER</command> instructs <productname>Postgres</productname> 
to cluster the class specified
  by <replaceable class="parameter">classname</replaceable> approximately
  based on the index specified by
  <replaceable class="parameter">indexname</replaceable>. The index must
  already have been defined on 
<replaceable class="parameter">classname</replaceable>.
 </PARA>
 <para>
  When a class is clustered, it is physically reordered
  based on the index information. The clustering is static.
  In other words, as the class is updated, the changes are
  not clustered. No attempt is made to keep new instances or
  updated tuples clustered.  If one wishes, one can
  recluster manually by issuing the command again.
 </para>
 
 <REFSECT2 ID="R2-SQL-CLUSTER-3">
  <REFSECT2INFO>
  <DATE>1998-09-08</DATE>
  </REFSECT2INFO>
  <TITLE>
  Notes
  </TITLE>
 
 <para>
  The table is actually copied to a temporary table in index
  order, then renamed back to the original name.  For this
  reason, all grant permissions and other indexes are lost
  when clustering is performed.
 </para>
 
 <para>
  In cases where you are accessing single rows randomly
  within a table, the actual order of the data in the heap
  table is unimportant. However, if you tend to access some
  data more than others, and there is an index that groups
  them together, you will benefit from using <command>CLUSTER</command>.
 </para>
 
 <para> 
  Another place <command>CLUSTER</command> is helpful is in cases where you use an
  index to pull out several rows from a table. If you are
  requesting a range of indexed values from a table, or a
  single indexed value that has multiple rows that match,
  <command>CLUSTER</command> 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,
  saving disk accesses and speeding up the query.
 </para>
 
 <para>
  There are two ways to cluster data. The first is with the
  <command>CLUSTER</command> command, which reorders the original table with
  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
  entries are on random pages, so there is one disk page
  retrieved for every row moved. <productname>Postgres</productname> has a cache,
  but the majority of a big table will not fit in the cache.
 </para>
 
 <para> 
  Another way to cluster data is to use
<programlisting>
d178 10
a187 10
</programlisting>
  This uses the <productname>Postgres</productname> sorting code in
  ORDER BY to match the index, and is much faster for
  unordered data. You then drop the old table, use
<command>ALTER TABLE/RENAME</command>
 to rename <replaceable class="parameter">temp</replaceable> to the old name, and
  recreate any indexes. The only problem is that <acronym>OID</acronym>s
  will not be preserved. From then on, <command>CLUSTER</command> should be
  fast because most of the heap data has already been
  ordered, and the existing index is used.
d191 3
a193 3
   
 <REFSECT1 ID="R1-SQL-CLUSTER-2">
  <TITLE>
d195 2
a196 2
  </TITLE>
  <PARA>
d198 8
a205 8
  </PARA>
  <ProgramListing>
   CLUSTER emp_ind ON emp
  </ProgramListing>
 </REFSECT1>
 
 <REFSECT1 ID="R1-SQL-CLUSTER-3">
  <TITLE>
d207 9
a215 9
  </TITLE>
  <PARA>
  </PARA>
  
  <REFSECT2 ID="R2-SQL-CLUSTER-4">
   <REFSECT2INFO>
    <DATE>1998-09-08</DATE>
   </REFSECT2INFO>
   <TITLE>
d217 2
a218 2
   </TITLE>
   <PARA>
d220 1
a220 1
   </PARA>
d223 1
a223 2
</REFENTRY>

d228 1
a228 1
sgml-omittag:t
@


1.4
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
a15 1
 
d17 6
a22 6
 <REFSYNOPSISDIVINFO>
  <DATE>1998-09-08</DATE>
 </REFSYNOPSISDIVINFO>
 <SYNOPSIS>
CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
 </SYNOPSIS>
d105 3
a107 3
  </VARIABLELIST>
  
 </REFSECT2>
d142 1
a142 1
  <PARA>
d194 4
a197 3
 </para>
 
 
d199 9
a207 9
 <TITLE>
  Usage
 </TITLE>
 <PARA>
  Cluster the employees relation on the basis of its salary attribute
 </PARA>
 <ProgramListing>
CLUSTER emp_ind ON emp
 </ProgramListing>
a210 10
 <TITLE>
  Compatibility
 </TITLE>
 <PARA>
 </PARA>
 
 <REFSECT2 ID="R2-SQL-CLUSTER-4">
  <REFSECT2INFO>
  <DATE>1998-09-08</DATE>
  </REFSECT2INFO>
d212 1
a212 1
  SQL92
a214 1
  There is no <command>CLUSTER</command> statement in SQL92.
d216 12
a227 1
 </refsect2>
@


1.3
log
@Markup and editing adjustments...
@
text
@a64 8
  </PARA>
  <VARIABLELIST>
  <VARLISTENTRY>
   <TERM>
<replaceable>status</replaceable>
   </TERM>
   <LISTITEM>
   <PARA>
d104 1
a104 3
    </variablelist>
   </LISTITEM>
  </VARLISTENTRY>
@


1.2
log
@Very minor formatting fixup in the refentry id field to remove
 the trailing "-1". This makes a cleaner html output file name.
Clean up a few refpurpose fields.
@
text
@d18 1
a18 1
  <DATE>1998-04-15</DATE>
d21 1
a21 1
  CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
d26 1
a26 1
  <DATE>1998-04-15</DATE>
a35 1
   <ReturnValue>
a36 1
   </ReturnValue>
a45 1
   <ReturnValue>
a46 1
   </ReturnValue>
d59 1
a59 1
  <DATE>1998-04-15</DATE>
d69 1
d76 1
a76 1
	 <ReturnValue>CLUSTER</ReturnValue>
d86 1
a86 1
	 <ReturnValue>ERROR: relation &lt;<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>&gt; inherits "invoice"</ReturnValue>
d90 1
a90 1
	  ???
d100 1
a100 1
	 <ReturnValue>ERROR: Relation x does not exist!</ReturnValue>
d104 1
a104 1
	  ???
d122 1
a122 1
  <DATE>1998-04-15</DATE>
d128 2
a129 1
  This command instructs PostgreSQL to cluster the class specified
d133 2
a134 1
  already have been defined on <replaceable class="parameter">classname</replaceable>.
d141 1
a141 1
  updated tuples clustered.  If he wishes, the user can
d145 8
d165 1
a165 2
  them together, you will benefit from using the CLUSTER
  command.
d169 1
a169 1
  Another place CLUSTER is good is in cases where you use an
d173 1
a173 1
  CLUSTER will help because once the index identifies the
d181 1
a181 1
  CLUSTER command, which reorders the original table with
d186 1
a186 1
  retrieved for every row moved. PostgreSQL has a cache,
d191 5
a195 3
  Another way is to use
  <programlisting>SELECT ... INTO TABLE temp FROM ... ORDER BY ...</programlisting>
  This uses the PostgreSQL sorting code in
d198 4
a201 4
<programlisting>ALTER TABLE RENAME</programlisting>
 to rename 'temp' to the old name, and
  recreate the b bindexes. The only problem is that oids
  will not be preserved. From then on, CLUSTER should be
d215 1
a215 1
  CLUSTER emp_ind ON emp
d228 1
a228 1
  <DATE>1998-04-15</DATE>
d234 1
a234 1
  There is no CLUSTER statement in SQL92.
@


1.1
log
@First files for reference pages.
@
text
@d1 1
a1 1
<REFENTRY ID="SQL-CLUSTER-1">
d13 1
a13 1
  Gives storage clustering advice to PostgreSQL
@
