I386LINUX/util/I386LINUX/doc/postgresql/html/sql-cluster.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >CLUSTER</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="SQL Commands"
  16 HREF="sql-commands.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="CLOSE"
  19 HREF="sql-close.html"><LINK
  20 REL="NEXT"
  21 TITLE="COMMENT"
  22 HREF="sql-comment.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="sql-close.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="sql-close.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="sql-comment.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="sql-comment.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><H1
  91 ><A
  92 NAME="SQL-CLUSTER"
  93 ></A
  94 >CLUSTER</H1
  95 ><DIV
  96 CLASS="REFNAMEDIV"
  97 ><A
  98 NAME="AEN35876"
  99 ></A
 100 ><H2
 101 >Name</H2
 102 >CLUSTER&nbsp;--&nbsp;cluster a table according to an index</DIV
 103 ><A
 104 NAME="AEN35879"
 105 ></A
 106 ><DIV
 107 CLASS="REFSYNOPSISDIV"
 108 ><A
 109 NAME="AEN35881"
 110 ></A
 111 ><H2
 112 >Synopsis</H2
 113 ><PRE
 114 CLASS="SYNOPSIS"
 115 >CLUSTER <VAR
 116 CLASS="REPLACEABLE"
 117 >indexname</VAR
 118 > ON <VAR
 119 CLASS="REPLACEABLE"
 120 >tablename</VAR
 121 >
 122 CLUSTER <VAR
 123 CLASS="REPLACEABLE"
 124 >tablename</VAR
 125 >
 126 CLUSTER</PRE
 127 ></DIV
 128 ><DIV
 129 CLASS="REFSECT1"
 130 ><A
 131 NAME="AEN35886"
 132 ></A
 133 ><H2
 134 >Description</H2
 135 ><P
 136 >   <TT
 137 CLASS="COMMAND"
 138 >CLUSTER</TT
 139 > instructs <SPAN
 140 CLASS="PRODUCTNAME"
 141 >PostgreSQL</SPAN
 142 >
 143    to cluster the table specified
 144    by <VAR
 145 CLASS="REPLACEABLE"
 146 >tablename</VAR
 147 >
 148    based on the index specified by
 149    <VAR
 150 CLASS="REPLACEABLE"
 151 >indexname</VAR
 152 >. The index must
 153    already have been defined on
 154    <VAR
 155 CLASS="REPLACEABLE"
 156 >tablename</VAR
 157 >.
 158   </P
 159 ><P
 160 >   When a table is clustered, it is physically reordered
 161    based on the index information. Clustering is a one-time operation:
 162    when the table is subsequently updated, the changes are
 163    not clustered.  That is, no attempt is made to store new or
 164    updated rows according to their index order.  If one wishes, one can
 165    periodically recluster by issuing the command again.
 166   </P
 167 ><P
 168 >   When a table is clustered, <SPAN
 169 CLASS="PRODUCTNAME"
 170 >PostgreSQL</SPAN
 171 >
 172    remembers on which index it was clustered.  The form
 173    <TT
 174 CLASS="COMMAND"
 175 >CLUSTER <VAR
 176 CLASS="REPLACEABLE"
 177 >tablename</VAR
 178 ></TT
 179 >,
 180    reclusters the table on the same index that it was clustered before.
 181   </P
 182 ><P
 183 >   <TT
 184 CLASS="COMMAND"
 185 >CLUSTER</TT
 186 > without any parameter reclusters all the tables
 187    in the
 188    current database that the calling user owns, or all tables if called
 189    by a superuser.  (Never-clustered tables are not included.)  This
 190    form of <TT
 191 CLASS="COMMAND"
 192 >CLUSTER</TT
 193 > cannot be called from inside a
 194    transaction or function.
 195   </P
 196 ><P
 197 >   When a table is being clustered, an <TT
 198 CLASS="LITERAL"
 199 >ACCESS
 200    EXCLUSIVE</TT
 201 > lock is acquired on it. This prevents any other
 202    database operations (both reads and writes) from operating on the
 203    table until the <TT
 204 CLASS="COMMAND"
 205 >CLUSTER</TT
 206 > is finished.
 207   </P
 208 ></DIV
 209 ><DIV
 210 CLASS="REFSECT1"
 211 ><A
 212 NAME="AEN35905"
 213 ></A
 214 ><H2
 215 >Parameters</H2
 216 ><P
 217 ></P
 218 ><DIV
 219 CLASS="VARIABLELIST"
 220 ><DL
 221 ><DT
 222 ><VAR
 223 CLASS="REPLACEABLE"
 224 >indexname</VAR
 225 ></DT
 226 ><DD
 227 ><P
 228 >      The name of an index.
 229      </P
 230 ></DD
 231 ><DT
 232 ><VAR
 233 CLASS="REPLACEABLE"
 234 >tablename</VAR
 235 ></DT
 236 ><DD
 237 ><P
 238 >      The name (possibly schema-qualified) of a table.
 239      </P
 240 ></DD
 241 ></DL
 242 ></DIV
 243 ></DIV
 244 ><DIV
 245 CLASS="REFSECT1"
 246 ><A
 247 NAME="AEN35918"
 248 ></A
 249 ><H2
 250 >Notes</H2
 251 ><P
 252 >    In cases where you are accessing single rows randomly
 253     within a table, the actual order of the data in the
 254     table is unimportant. However, if you tend to access some
 255     data more than others, and there is an index that groups
 256     them together, you will benefit from using <TT
 257 CLASS="COMMAND"
 258 >CLUSTER</TT
 259 >.
 260     If you are requesting a range of indexed values from a table, or a
 261     single indexed value that has multiple rows that match,
 262     <TT
 263 CLASS="COMMAND"
 264 >CLUSTER</TT
 265 > will help because once the index identifies the
 266     heap page for the first row that matches, all other rows
 267     that match are probably already on the same heap page,
 268     and so you save disk accesses and speed up the query.
 269    </P
 270 ><P
 271 >    During the cluster operation, a temporary copy of the table is created
 272     that contains the table data in the index order.  Temporary copies of
 273     each index on the table are created as well.  Therefore, you need free
 274     space on disk at least equal to the sum of the table size and the index
 275     sizes.
 276    </P
 277 ><P
 278 >    Because <TT
 279 CLASS="COMMAND"
 280 >CLUSTER</TT
 281 > remembers the clustering information,
 282     one can cluster the tables one wants clustered manually the first time, and
 283     setup a timed event similar to <TT
 284 CLASS="COMMAND"
 285 >VACUUM</TT
 286 > so that the tables
 287     are periodically reclustered.
 288    </P
 289 ><P
 290 >    Because the planner records statistics about the ordering of tables, it
 291     is advisable to run <TT
 292 CLASS="COMMAND"
 293 >ANALYZE</TT
 294 > on the newly clustered
 295     table.  Otherwise, the planner may make poor choices of query plans.
 296    </P
 297 ><P
 298 >    There is another way to cluster data. The
 299     <TT
 300 CLASS="COMMAND"
 301 >CLUSTER</TT
 302 > command reorders the original table using
 303     the ordering of the index you specify. This can be slow
 304     on large tables because the rows are fetched from the heap
 305     in index order, and if the heap table is unordered, the
 306     entries are on random pages, so there is one disk page
 307     retrieved for every row moved. (<SPAN
 308 CLASS="PRODUCTNAME"
 309 >PostgreSQL</SPAN
 310 > has a cache,
 311     but the majority of a big table will not fit in the cache.)
 312     The other way to cluster a table is to use
 313
 314 </P><PRE
 315 CLASS="PROGRAMLISTING"
 316 >CREATE TABLE <VAR
 317 CLASS="REPLACEABLE"
 318 >newtable</VAR
 319 > AS
 320     SELECT <VAR
 321 CLASS="REPLACEABLE"
 322 >columnlist</VAR
 323 > FROM <VAR
 324 CLASS="REPLACEABLE"
 325 >table</VAR
 326 > ORDER BY <VAR
 327 CLASS="REPLACEABLE"
 328 >columnlist</VAR
 329 >;</PRE
 330 ><P>
 331
 332     which uses the <SPAN
 333 CLASS="PRODUCTNAME"
 334 >PostgreSQL</SPAN
 335 > sorting code in
 336     the <TT
 337 CLASS="LITERAL"
 338 >ORDER BY</TT
 339 > clause to create the desired order; this is usually much
 340     faster than an index scan for
 341     unordered data. You then drop the old table, use
 342     <TT
 343 CLASS="COMMAND"
 344 >ALTER TABLE ... RENAME</TT
 345 >
 346     to rename <VAR
 347 CLASS="REPLACEABLE"
 348 >newtable</VAR
 349 > to the old name, and
 350     recreate the table's indexes. However, this approach does not preserve
 351     OIDs, constraints, foreign key relationships, granted privileges, and
 352     other ancillary properties of the table --- all such items must be
 353     manually recreated.
 354    </P
 355 ></DIV
 356 ><DIV
 357 CLASS="REFSECT1"
 358 ><A
 359 NAME="AEN35941"
 360 ></A
 361 ><H2
 362 >Examples</H2
 363 ><P
 364 >   Cluster the table <TT
 365 CLASS="LITERAL"
 366 >employees</TT
 367 > on the basis of
 368    its index <TT
 369 CLASS="LITERAL"
 370 >emp_ind</TT
 371 >:
 372 </P><PRE
 373 CLASS="PROGRAMLISTING"
 374 >CLUSTER emp_ind ON emp;</PRE
 375 ><P>
 376   </P
 377 ><P
 378 >   Cluster the <TT
 379 CLASS="LITERAL"
 380 >employees</TT
 381 > relation using the same
 382    index that was used before:
 383 </P><PRE
 384 CLASS="PROGRAMLISTING"
 385 >CLUSTER emp;</PRE
 386 ><P>
 387   </P
 388 ><P
 389 >   Cluster all the tables on the database that have previously been clustered:
 390 </P><PRE
 391 CLASS="PROGRAMLISTING"
 392 >CLUSTER;</PRE
 393 ><P>
 394   </P
 395 ></DIV
 396 ><DIV
 397 CLASS="REFSECT1"
 398 ><A
 399 NAME="AEN35952"
 400 ></A
 401 ><H2
 402 >Compatibility</H2
 403 ><P
 404 >   There is no <TT
 405 CLASS="COMMAND"
 406 >CLUSTER</TT
 407 > statement in the SQL standard.
 408   </P
 409 ></DIV
 410 ><DIV
 411 CLASS="REFSECT1"
 412 ><A
 413 NAME="AEN35956"
 414 ></A
 415 ><H2
 416 >See Also</H2
 417 ><A
 418 HREF="app-clusterdb.html"
 419 ><I
 420 ><I
 421 >clusterdb</I
 422 ></I
 423 ></A
 424 ></DIV
 425 ><DIV
 426 CLASS="NAVFOOTER"
 427 ><HR
 428 ALIGN="LEFT"
 429 WIDTH="100%"><TABLE
 430 SUMMARY="Footer navigation table"
 431 WIDTH="100%"
 432 BORDER="0"
 433 CELLPADDING="0"
 434 CELLSPACING="0"
 435 ><TR
 436 ><TD
 437 WIDTH="33%"
 438 ALIGN="left"
 439 VALIGN="top"
 440 ><A
 441 HREF="sql-close.html"
 442 ACCESSKEY="P"
 443 >Prev</A
 444 ></TD
 445 ><TD
 446 WIDTH="34%"
 447 ALIGN="center"
 448 VALIGN="top"
 449 ><A
 450 HREF="index.html"
 451 ACCESSKEY="H"
 452 >Home</A
 453 ></TD
 454 ><TD
 455 WIDTH="33%"
 456 ALIGN="right"
 457 VALIGN="top"
 458 ><A
 459 HREF="sql-comment.html"
 460 ACCESSKEY="N"
 461 >Next</A
 462 ></TD
 463 ></TR
 464 ><TR
 465 ><TD
 466 WIDTH="33%"
 467 ALIGN="left"
 468 VALIGN="top"
 469 >CLOSE</TD
 470 ><TD
 471 WIDTH="34%"
 472 ALIGN="center"
 473 VALIGN="top"
 474 ><A
 475 HREF="sql-commands.html"
 476 ACCESSKEY="U"
 477 >Up</A
 478 ></TD
 479 ><TD
 480 WIDTH="33%"
 481 ALIGN="right"
 482 VALIGN="top"
 483 >COMMENT</TD
 484 ></TR
 485 ></TABLE
 486 ></DIV
 487 ></BODY
 488 ></HTML
 489 >