granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/cluster.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CLUSTER">
   7  <refmeta>
   8   <refentrytitle id="sql-cluster-title">CLUSTER</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CLUSTER</refname>
  14   <refpurpose>cluster a table according to an index</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-cluster">
  18   <primary>CLUSTER</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
  24 CLUSTER <replaceable class="PARAMETER">tablename</replaceable>
  25 CLUSTER
  26 </synopsis>
  27  </refsynopsisdiv>
  28
  29  <refsect1>
  30   <title>Description</title>
  31
  32   <para>
  33    <command>CLUSTER</command> instructs <productname>PostgreSQL</productname>
  34    to cluster the table specified
  35    by <replaceable class="parameter">tablename</replaceable>
  36    based on the index specified by
  37    <replaceable class="parameter">indexname</replaceable>. The index must
  38    already have been defined on
  39    <replaceable class="parameter">tablename</replaceable>.
  40   </para>
  41
  42   <para>
  43    When a table is clustered, it is physically reordered
  44    based on the index information. Clustering is a one-time operation:
  45    when the table is subsequently updated, the changes are
  46    not clustered.  That is, no attempt is made to store new or
  47    updated rows according to their index order.  If one wishes, one can
  48    periodically recluster by issuing the command again.
  49   </para>
  50
  51   <para>
  52    When a table is clustered, <productname>PostgreSQL</productname>
  53    remembers on which index it was clustered.  The form
  54    <command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>
  55    reclusters the table on the same index that it was clustered before.
  56   </para>
  57
  58   <para>
  59    <command>CLUSTER</command> without any parameter reclusters all the tables
  60    in the
  61    current database that the calling user owns, or all tables if called
  62    by a superuser.  (Never-clustered tables are not included.)  This
  63    form of <command>CLUSTER</command> cannot be called from inside a
  64    transaction or function.
  65   </para>
  66
  67   <para>
  68    When a table is being clustered, an <literal>ACCESS
  69    EXCLUSIVE</literal> lock is acquired on it. This prevents any other
  70    database operations (both reads and writes) from operating on the
  71    table until the <command>CLUSTER</command> is finished.
  72   </para>
  73  </refsect1>
  74
  75  <refsect1>
  76   <title>Parameters</title>
  77
  78   <variablelist>
  79    <varlistentry>
  80     <term><replaceable class="PARAMETER">indexname</replaceable></term>
  81     <listitem>
  82      <para>
  83       The name of an index.
  84      </para>
  85     </listitem>
  86    </varlistentry>
  87
  88    <varlistentry>
  89     <term><replaceable class="PARAMETER">tablename</replaceable></term>
  90     <listitem>
  91      <para>
  92       The name (possibly schema-qualified) of a table.
  93      </para>
  94     </listitem>
  95    </varlistentry>
  96   </variablelist>
  97  </refsect1>
  98
  99  <refsect1>
 100   <title>Notes</title>
 101
 102    <para>
 103     In cases where you are accessing single rows randomly
 104     within a table, the actual order of the data in the
 105     table is unimportant. However, if you tend to access some
 106     data more than others, and there is an index that groups
 107     them together, you will benefit from using <command>CLUSTER</command>.
 108     If you are requesting a range of indexed values from a table, or a
 109     single indexed value that has multiple rows that match,
 110     <command>CLUSTER</command> will help because once the index identifies the
 111     heap page for the first row that matches, all other rows
 112     that match are probably already on the same heap page,
 113     and so you save disk accesses and speed up the query.
 114    </para>
 115
 116    <para>
 117     During the cluster operation, a temporary copy of the table is created
 118     that contains the table data in the index order.  Temporary copies of
 119     each index on the table are created as well.  Therefore, you need free
 120     space on disk at least equal to the sum of the table size and the index
 121     sizes.
 122    </para>
 123
 124    <para>
 125     Because <command>CLUSTER</command> remembers the clustering information,
 126     one can cluster the tables one wants clustered manually the first time, and
 127     setup a timed event similar to <command>VACUUM</command> so that the tables
 128     are periodically reclustered.
 129    </para>
 130
 131    <para>
 132     Because the planner records statistics about the ordering of
 133     tables, it is advisable to run <xref linkend="sql-analyze"
 134     endterm="sql-analyze-title"> on the newly clustered table.
 135     Otherwise, the planner may make poor choices of query plans.
 136    </para>
 137
 138    <para>
 139     There is another way to cluster data. The
 140     <command>CLUSTER</command> command reorders the original table using
 141     the ordering of the index you specify. This can be slow
 142     on large tables because the rows are fetched from the heap
 143     in index order, and if the heap table is unordered, the
 144     entries are on random pages, so there is one disk page
 145     retrieved for every row moved. (<productname>PostgreSQL</productname> has a cache,
 146     but the majority of a big table will not fit in the cache.)
 147     The other way to cluster a table is to use
 148
 149 <programlisting>
 150 CREATE TABLE <replaceable class="parameter">newtable</replaceable> AS
 151     SELECT <replaceable class="parameter">columnlist</replaceable> FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>;
 152 </programlisting>
 153
 154     which uses the <productname>PostgreSQL</productname> sorting code in
 155     the <literal>ORDER BY</literal> clause to create the desired order; this is usually much
 156     faster than an index scan for
 157     unordered data. You then drop the old table, use
 158     <command>ALTER TABLE ... RENAME</command>
 159     to rename <replaceable class="parameter">newtable</replaceable> to the old name, and
 160     recreate the table's indexes. However, this approach does not preserve
 161     OIDs, constraints, foreign key relationships, granted privileges, and
 162     other ancillary properties of the table &mdash; all such items must be
 163     manually recreated.
 164    </para>
 165  </refsect1>
 166
 167  <refsect1>
 168   <title>Examples</title>
 169
 170   <para>
 171    Cluster the table <literal>employees</literal> on the basis of
 172    its index <literal>emp_ind</literal>:
 173 <programlisting>
 174 CLUSTER emp_ind ON emp;
 175 </programlisting>
 176   </para>
 177
 178   <para>
 179    Cluster the <literal>employees</literal> table using the same
 180    index that was used before:
 181 <programlisting>
 182 CLUSTER emp;
 183 </programlisting>
 184   </para>
 185
 186   <para>
 187    Cluster all tables in the database that have previously been clustered:
 188 <programlisting>
 189 CLUSTER;
 190 </programlisting>
 191   </para>
 192  </refsect1>
 193
 194  <refsect1>
 195   <title>Compatibility</title>
 196
 197   <para>
 198    There is no <command>CLUSTER</command> statement in the SQL standard.
 199   </para>
 200  </refsect1>
 201
 202  <refsect1>
 203   <title>See Also</title>
 204
 205   <simplelist type="inline">
 206    <member><xref linkend="app-clusterdb" endterm="app-clusterdb-title"></member>
 207   </simplelist>
 208  </refsect1>
 209 </refentry>
 210
 211 <!-- Keep this comment at the end of the file
 212 Local variables:
 213 mode: sgml
 214 sgml-omittag:nil
 215 sgml-shorttag:t
 216 sgml-minimize-attributes:nil
 217 sgml-always-quote-attributes:t
 218 sgml-indent-step:1
 219 sgml-indent-data:t
 220 sgml-parent-document:nil
 221 sgml-default-dtd-file:"../reference.ced"
 222 sgml-exposed-tags:nil
 223 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 224 sgml-local-ecat-files:nil
 225 End:
 226 -->
 227