begriffs open source - ai-pg/blob - full-docs/html/sql-cluster.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CLUSTER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-close.html" title="CLOSE" /><link rel="next" href="sql-comment.html" title="COMMENT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CLUSTER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-close.html" title="CLOSE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-comment.html" title="COMMENT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CLUSTER"><div class="titlepage"></div><a id="id-1.9.3.51.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CLUSTER</span></h2><p>CLUSTER — cluster a table according to an index</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 CLUSTER [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ] [ <em class="replaceable"><code>table_name</code></em> [ USING <em class="replaceable"><code>index_name</code></em> ] ]
   4
   5 <span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
   6
   7     VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
   8 </pre></div><div class="refsect1" id="id-1.9.3.51.5"><h2>Description</h2><p>
   9    <code class="command">CLUSTER</code> instructs <span class="productname">PostgreSQL</span>
  10    to cluster the table specified
  11    by <em class="replaceable"><code>table_name</code></em>
  12    based on the index specified by
  13    <em class="replaceable"><code>index_name</code></em>. The index must
  14    already have been defined on
  15    <em class="replaceable"><code>table_name</code></em>.
  16   </p><p>
  17    When a table is clustered, it is physically reordered
  18    based on the index information. Clustering is a one-time operation:
  19    when the table is subsequently updated, the changes are
  20    not clustered.  That is, no attempt is made to store new or
  21    updated rows according to their index order.  (If one wishes, one can
  22    periodically recluster by issuing the command again.  Also, setting
  23    the table's <code class="literal">fillfactor</code> storage parameter to less than
  24    100% can aid in preserving cluster ordering during updates, since updated
  25    rows are kept on the same page if enough space is available there.)
  26   </p><p>
  27    When a table is clustered, <span class="productname">PostgreSQL</span>
  28    remembers which index it was clustered by.  The form
  29    <code class="command">CLUSTER <em class="replaceable"><code>table_name</code></em></code>
  30    reclusters the table using the same index as before.  You can also
  31    use the <code class="literal">CLUSTER</code> or <code class="literal">SET WITHOUT CLUSTER</code>
  32    forms of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> to set the index to be used for
  33    future cluster operations, or to clear any previous setting.
  34   </p><p>
  35    <code class="command">CLUSTER</code> without a
  36    <em class="replaceable"><code>table_name</code></em> reclusters all the
  37    previously-clustered tables in the current database that the calling user
  38    has privileges for.  This form of <code class="command">CLUSTER</code> cannot be
  39    executed inside a transaction block.
  40   </p><p>
  41    When a table is being clustered, an <code class="literal">ACCESS
  42    EXCLUSIVE</code> lock is acquired on it. This prevents any other
  43    database operations (both reads and writes) from operating on the
  44    table until the <code class="command">CLUSTER</code> is finished.
  45   </p></div><div class="refsect1" id="id-1.9.3.51.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
  46       The name (possibly schema-qualified) of a table.
  47      </p></dd><dt><span class="term"><em class="replaceable"><code>index_name</code></em></span></dt><dd><p>
  48       The name of an index.
  49      </p></dd><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
  50       Prints a progress report as each table is clustered
  51       at <code class="literal">INFO</code> level.
  52      </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
  53       Specifies whether the selected option should be turned on or off.
  54       You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
  55       <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
  56       <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it.  The
  57       <em class="replaceable"><code>boolean</code></em> value can also
  58       be omitted, in which case <code class="literal">TRUE</code> is assumed.
  59      </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.51.7"><h2>Notes</h2><p>
  60     To cluster a table, one must have the <code class="literal">MAINTAIN</code> privilege
  61     on the table.
  62    </p><p>
  63     In cases where you are accessing single rows randomly
  64     within a table, the actual order of the data in the
  65     table is unimportant. However, if you tend to access some
  66     data more than others, and there is an index that groups
  67     them together, you will benefit from using <code class="command">CLUSTER</code>.
  68     If you are requesting a range of indexed values from a table, or a
  69     single indexed value that has multiple rows that match,
  70     <code class="command">CLUSTER</code> will help because once the index identifies the
  71     table page for the first row that matches, all other rows
  72     that match are probably already on the same table page,
  73     and so you save disk accesses and speed up the query.
  74    </p><p>
  75     <code class="command">CLUSTER</code> can re-sort the table using either an index scan
  76     on the specified index, or (if the index is a b-tree) a sequential
  77     scan followed by sorting.  It will attempt to choose the method that
  78     will be faster, based on planner cost parameters and available statistical
  79     information.
  80    </p><p>
  81     While <code class="command">CLUSTER</code> is running, the <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> is temporarily changed to <code class="literal">pg_catalog,
  82     pg_temp</code>.
  83    </p><p>
  84     When an index scan is used, a temporary copy of the table is created that
  85     contains the table data in the index order.  Temporary copies of each
  86     index on the table are created as well.  Therefore, you need free space on
  87     disk at least equal to the sum of the table size and the index sizes.
  88    </p><p>
  89     When a sequential scan and sort is used, a temporary sort file is
  90     also created, so that the peak temporary space requirement is as much
  91     as double the table size, plus the index sizes.  This method is often
  92     faster than the index scan method, but if the disk space requirement is
  93     intolerable, you can disable this choice by temporarily setting <a class="xref" href="runtime-config-query.html#GUC-ENABLE-SORT">enable_sort</a> to <code class="literal">off</code>.
  94    </p><p>
  95     It is advisable to set <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a> to
  96     a reasonably large value (but not more than the amount of RAM you can
  97     dedicate to the <code class="command">CLUSTER</code> operation) before clustering.
  98    </p><p>
  99     Because the planner records statistics about the ordering of
 100     tables, it is advisable to run <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
 101     on the newly clustered table.
 102     Otherwise, the planner might make poor choices of query plans.
 103    </p><p>
 104     Because <code class="command">CLUSTER</code> remembers which indexes are clustered,
 105     one can cluster the tables one wants clustered manually the first time,
 106     then set up a periodic maintenance script that executes
 107     <code class="command">CLUSTER</code> without any parameters, so that the desired tables
 108     are periodically reclustered.
 109    </p><p>
 110     Each backend running <code class="command">CLUSTER</code> will report its progress
 111     in the <code class="structname">pg_stat_progress_cluster</code> view. See
 112     <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="27.4.2. CLUSTER Progress Reporting">Section 27.4.2</a> for details.
 113   </p><p>
 114     Clustering a partitioned table clusters each of its partitions using the
 115     partition of the specified partitioned index.  When clustering a partitioned
 116     table, the index may not be omitted.  <code class="command">CLUSTER</code> on a
 117     partitioned table cannot be executed inside a transaction block.
 118    </p></div><div class="refsect1" id="id-1.9.3.51.8"><h2>Examples</h2><p>
 119    Cluster the table <code class="literal">employees</code> on the basis of
 120    its index <code class="literal">employees_ind</code>:
 121 </p><pre class="programlisting">
 122 CLUSTER employees USING employees_ind;
 123 </pre><p>
 124   </p><p>
 125    Cluster the <code class="literal">employees</code> table using the same
 126    index that was used before:
 127 </p><pre class="programlisting">
 128 CLUSTER employees;
 129 </pre><p>
 130   </p><p>
 131    Cluster all tables in the database that have previously been clustered:
 132 </p><pre class="programlisting">
 133 CLUSTER;
 134 </pre></div><div class="refsect1" id="id-1.9.3.51.9"><h2>Compatibility</h2><p>
 135    There is no <code class="command">CLUSTER</code> statement in the SQL standard.
 136   </p><p>
 137    The following syntax was used before <span class="productname">PostgreSQL</span>
 138    17 and is still supported:
 139 </p><pre class="synopsis">
 140 CLUSTER [ VERBOSE ] [ <em class="replaceable"><code>table_name</code></em> [ USING <em class="replaceable"><code>index_name</code></em> ] ]
 141 </pre><p>
 142   </p><p>
 143    The following syntax was used before <span class="productname">PostgreSQL</span>
 144    8.3 and is still supported:
 145 </p><pre class="synopsis">
 146 CLUSTER <em class="replaceable"><code>index_name</code></em> ON <em class="replaceable"><code>table_name</code></em>
 147 </pre><p>
 148   </p></div><div class="refsect1" id="id-1.9.3.51.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-clusterdb.html" title="clusterdb"><span class="refentrytitle"><span class="application">clusterdb</span></span></a>, <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="27.4.2. CLUSTER Progress Reporting">Section 27.4.2</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-close.html" title="CLOSE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-comment.html" title="COMMENT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CLOSE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMENT</td></tr></table></div></body></html>