← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/sql-cluster.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/sql-cluster.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>CLUSTER</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 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
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="REFENTRY"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="CLOSE"
 
57
HREF="sql-close.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="CLOSE"
 
67
HREF="sql-close.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
></TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="COMMENT"
 
81
HREF="sql-comment.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="COMMENT"
 
90
HREF="sql-comment.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><H1
 
100
><A
 
101
NAME="SQL-CLUSTER"
 
102
></A
 
103
>CLUSTER</H1
 
104
><DIV
 
105
CLASS="REFNAMEDIV"
 
106
><A
 
107
NAME="AEN63270"
 
108
></A
 
109
><H2
 
110
>Name</H2
 
111
>CLUSTER&nbsp;--&nbsp;cluster a table according to an index</DIV
 
112
><DIV
 
113
CLASS="REFSYNOPSISDIV"
 
114
><A
 
115
NAME="AEN63275"
 
116
></A
 
117
><H2
 
118
>Synopsis</H2
 
119
><PRE
 
120
CLASS="SYNOPSIS"
 
121
>CLUSTER [VERBOSE] <TT
 
122
CLASS="REPLACEABLE"
 
123
><I
 
124
>table_name</I
 
125
></TT
 
126
> [ USING <TT
 
127
CLASS="REPLACEABLE"
 
128
><I
 
129
>index_name</I
 
130
></TT
 
131
> ]
 
132
CLUSTER [VERBOSE]</PRE
 
133
></DIV
 
134
><DIV
 
135
CLASS="REFSECT1"
 
136
><A
 
137
NAME="AEN63279"
 
138
></A
 
139
><H2
 
140
>Description</H2
 
141
><P
 
142
>   <TT
 
143
CLASS="COMMAND"
 
144
>CLUSTER</TT
 
145
> instructs <SPAN
 
146
CLASS="PRODUCTNAME"
 
147
>PostgreSQL</SPAN
 
148
>
 
149
   to cluster the table specified
 
150
   by <TT
 
151
CLASS="REPLACEABLE"
 
152
><I
 
153
>table_name</I
 
154
></TT
 
155
>
 
156
   based on the index specified by
 
157
   <TT
 
158
CLASS="REPLACEABLE"
 
159
><I
 
160
>index_name</I
 
161
></TT
 
162
>. The index must
 
163
   already have been defined on
 
164
   <TT
 
165
CLASS="REPLACEABLE"
 
166
><I
 
167
>table_name</I
 
168
></TT
 
169
>.
 
170
  </P
 
171
><P
 
172
>   When a table is clustered, it is physically reordered
 
173
   based on the index information. Clustering is a one-time operation:
 
174
   when the table is subsequently updated, the changes are
 
175
   not clustered.  That is, no attempt is made to store new or
 
176
   updated rows according to their index order.  (If one wishes, one can
 
177
   periodically recluster by issuing the command again.  Also, setting
 
178
   the table's <TT
 
179
CLASS="LITERAL"
 
180
>FILLFACTOR</TT
 
181
> storage parameter to less than
 
182
   100% can aid in preserving cluster ordering during updates, since updated
 
183
   rows are kept on the same page if enough space is available there.)
 
184
  </P
 
185
><P
 
186
>   When a table is clustered, <SPAN
 
187
CLASS="PRODUCTNAME"
 
188
>PostgreSQL</SPAN
 
189
>
 
190
   remembers which index it was clustered by.  The form
 
191
   <TT
 
192
CLASS="COMMAND"
 
193
>CLUSTER <TT
 
194
CLASS="REPLACEABLE"
 
195
><I
 
196
>table_name</I
 
197
></TT
 
198
></TT
 
199
>
 
200
   reclusters the table using the same index as before.  You can also
 
201
   use the <TT
 
202
CLASS="LITERAL"
 
203
>CLUSTER</TT
 
204
> or <TT
 
205
CLASS="LITERAL"
 
206
>SET WITHOUT CLUSTER</TT
 
207
>
 
208
   forms of <A
 
209
HREF="sql-altertable.html"
 
210
>ALTER TABLE</A
 
211
> to set the index to be used for
 
212
   future cluster operations, or to clear any previous setting.
 
213
  </P
 
214
><P
 
215
>   <TT
 
216
CLASS="COMMAND"
 
217
>CLUSTER</TT
 
218
> without any parameter reclusters all the
 
219
   previously-clustered tables in the current database that the calling user
 
220
   owns, or all such tables if called by a superuser.  This
 
221
   form of <TT
 
222
CLASS="COMMAND"
 
223
>CLUSTER</TT
 
224
> cannot be executed inside a transaction
 
225
   block.
 
226
  </P
 
227
><P
 
228
>   When a table is being clustered, an <TT
 
229
CLASS="LITERAL"
 
230
>ACCESS
 
231
   EXCLUSIVE</TT
 
232
> lock is acquired on it. This prevents any other
 
233
   database operations (both reads and writes) from operating on the
 
234
   table until the <TT
 
235
CLASS="COMMAND"
 
236
>CLUSTER</TT
 
237
> is finished.
 
238
  </P
 
239
></DIV
 
240
><DIV
 
241
CLASS="REFSECT1"
 
242
><A
 
243
NAME="AEN63302"
 
244
></A
 
245
><H2
 
246
>Parameters</H2
 
247
><P
 
248
></P
 
249
><DIV
 
250
CLASS="VARIABLELIST"
 
251
><DL
 
252
><DT
 
253
><TT
 
254
CLASS="REPLACEABLE"
 
255
><I
 
256
>table_name</I
 
257
></TT
 
258
></DT
 
259
><DD
 
260
><P
 
261
>      The name (possibly schema-qualified) of a table.
 
262
     </P
 
263
></DD
 
264
><DT
 
265
><TT
 
266
CLASS="REPLACEABLE"
 
267
><I
 
268
>index_name</I
 
269
></TT
 
270
></DT
 
271
><DD
 
272
><P
 
273
>      The name of an index.
 
274
     </P
 
275
></DD
 
276
><DT
 
277
><TT
 
278
CLASS="LITERAL"
 
279
>VERBOSE</TT
 
280
></DT
 
281
><DD
 
282
><P
 
283
>      Prints a progress report as each table is clustered.
 
284
     </P
 
285
></DD
 
286
></DL
 
287
></DIV
 
288
></DIV
 
289
><DIV
 
290
CLASS="REFSECT1"
 
291
><A
 
292
NAME="AEN63320"
 
293
></A
 
294
><H2
 
295
>Notes</H2
 
296
><P
 
297
>    In cases where you are accessing single rows randomly
 
298
    within a table, the actual order of the data in the
 
299
    table is unimportant. However, if you tend to access some
 
300
    data more than others, and there is an index that groups
 
301
    them together, you will benefit from using <TT
 
302
CLASS="COMMAND"
 
303
>CLUSTER</TT
 
304
>.
 
305
    If you are requesting a range of indexed values from a table, or a
 
306
    single indexed value that has multiple rows that match,
 
307
    <TT
 
308
CLASS="COMMAND"
 
309
>CLUSTER</TT
 
310
> will help because once the index identifies the
 
311
    table page for the first row that matches, all other rows
 
312
    that match are probably already on the same table page,
 
313
    and so you save disk accesses and speed up the query.
 
314
   </P
 
315
><P
 
316
>    <TT
 
317
CLASS="COMMAND"
 
318
>CLUSTER</TT
 
319
> can re-sort the table using either an indexscan
 
320
    on the specified index, or (if the index is a b-tree) a sequential
 
321
    scan followed by sorting.  It will attempt to choose the method that
 
322
    will be faster, based on planner cost parameters and available statistical
 
323
    information.
 
324
   </P
 
325
><P
 
326
>    When an indexscan is used, a temporary copy of the table is created that
 
327
    contains the table data in the index order.  Temporary copies of each
 
328
    index on the table are created as well.  Therefore, you need free space on
 
329
    disk at least equal to the sum of the table size and the index sizes.
 
330
   </P
 
331
><P
 
332
>    When a sequential scan and sort is used, a temporary sort file is
 
333
    also created, so that the peak temporary space requirement is as much
 
334
    as double the table size, plus the index sizes.  This method is often
 
335
    faster than the indexscan method, but if the disk space requirement is
 
336
    intolerable, you can disable this choice by temporarily setting <A
 
337
HREF="runtime-config-query.html#GUC-ENABLE-SORT"
 
338
>enable_sort</A
 
339
> to <TT
 
340
CLASS="LITERAL"
 
341
>off</TT
 
342
>.
 
343
   </P
 
344
><P
 
345
>    It is advisable to set <A
 
346
HREF="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM"
 
347
>maintenance_work_mem</A
 
348
> to
 
349
    a reasonably large value (but not more than the amount of RAM you can
 
350
    dedicate to the <TT
 
351
CLASS="COMMAND"
 
352
>CLUSTER</TT
 
353
> operation) before clustering.
 
354
   </P
 
355
><P
 
356
>    Because the planner records statistics about the ordering of
 
357
    tables, it is advisable to run <A
 
358
HREF="sql-analyze.html"
 
359
>ANALYZE</A
 
360
>
 
361
    on the newly clustered table.
 
362
    Otherwise, the planner might make poor choices of query plans.
 
363
   </P
 
364
><P
 
365
>    Because <TT
 
366
CLASS="COMMAND"
 
367
>CLUSTER</TT
 
368
> remembers which indexes are clustered,
 
369
    one can cluster the tables one wants clustered manually the first time,
 
370
    then set up a periodic maintenance script that executes
 
371
    <TT
 
372
CLASS="COMMAND"
 
373
>CLUSTER</TT
 
374
> without any parameters, so that the desired tables
 
375
    are periodically reclustered.
 
376
   </P
 
377
></DIV
 
378
><DIV
 
379
CLASS="REFSECT1"
 
380
><A
 
381
NAME="AEN63339"
 
382
></A
 
383
><H2
 
384
>Examples</H2
 
385
><P
 
386
>   Cluster the table <TT
 
387
CLASS="LITERAL"
 
388
>employees</TT
 
389
> on the basis of
 
390
   its index <TT
 
391
CLASS="LITERAL"
 
392
>employees_ind</TT
 
393
>:
 
394
</P><PRE
 
395
CLASS="PROGRAMLISTING"
 
396
>CLUSTER employees USING employees_ind;</PRE
 
397
><P>
 
398
  </P
 
399
><P
 
400
>   Cluster the <TT
 
401
CLASS="LITERAL"
 
402
>employees</TT
 
403
> table using the same
 
404
   index that was used before:
 
405
</P><PRE
 
406
CLASS="PROGRAMLISTING"
 
407
>CLUSTER employees;</PRE
 
408
><P>
 
409
  </P
 
410
><P
 
411
>   Cluster all tables in the database that have previously been clustered:
 
412
</P><PRE
 
413
CLASS="PROGRAMLISTING"
 
414
>CLUSTER;</PRE
 
415
><P>
 
416
  </P
 
417
></DIV
 
418
><DIV
 
419
CLASS="REFSECT1"
 
420
><A
 
421
NAME="AEN63350"
 
422
></A
 
423
><H2
 
424
>Compatibility</H2
 
425
><P
 
426
>   There is no <TT
 
427
CLASS="COMMAND"
 
428
>CLUSTER</TT
 
429
> statement in the SQL standard.
 
430
  </P
 
431
><P
 
432
>   The syntax
 
433
</P><PRE
 
434
CLASS="SYNOPSIS"
 
435
>CLUSTER <TT
 
436
CLASS="REPLACEABLE"
 
437
><I
 
438
>index_name</I
 
439
></TT
 
440
> ON <TT
 
441
CLASS="REPLACEABLE"
 
442
><I
 
443
>table_name</I
 
444
></TT
 
445
></PRE
 
446
><P>
 
447
  is also supported for compatibility with pre-8.3 <SPAN
 
448
CLASS="PRODUCTNAME"
 
449
>PostgreSQL</SPAN
 
450
>
 
451
  versions.
 
452
  </P
 
453
></DIV
 
454
><DIV
 
455
CLASS="REFSECT1"
 
456
><A
 
457
NAME="AEN63359"
 
458
></A
 
459
><H2
 
460
>See Also</H2
 
461
><A
 
462
HREF="app-clusterdb.html"
 
463
><SPAN
 
464
CLASS="APPLICATION"
 
465
>clusterdb</SPAN
 
466
></A
 
467
></DIV
 
468
><DIV
 
469
CLASS="NAVFOOTER"
 
470
><HR
 
471
ALIGN="LEFT"
 
472
WIDTH="100%"><TABLE
 
473
SUMMARY="Footer navigation table"
 
474
WIDTH="100%"
 
475
BORDER="0"
 
476
CELLPADDING="0"
 
477
CELLSPACING="0"
 
478
><TR
 
479
><TD
 
480
WIDTH="33%"
 
481
ALIGN="left"
 
482
VALIGN="top"
 
483
><A
 
484
HREF="sql-close.html"
 
485
ACCESSKEY="P"
 
486
>Prev</A
 
487
></TD
 
488
><TD
 
489
WIDTH="34%"
 
490
ALIGN="center"
 
491
VALIGN="top"
 
492
><A
 
493
HREF="index.html"
 
494
ACCESSKEY="H"
 
495
>Home</A
 
496
></TD
 
497
><TD
 
498
WIDTH="33%"
 
499
ALIGN="right"
 
500
VALIGN="top"
 
501
><A
 
502
HREF="sql-comment.html"
 
503
ACCESSKEY="N"
 
504
>Next</A
 
505
></TD
 
506
></TR
 
507
><TR
 
508
><TD
 
509
WIDTH="33%"
 
510
ALIGN="left"
 
511
VALIGN="top"
 
512
>CLOSE</TD
 
513
><TD
 
514
WIDTH="34%"
 
515
ALIGN="center"
 
516
VALIGN="top"
 
517
><A
 
518
HREF="sql-commands.html"
 
519
ACCESSKEY="U"
 
520
>Up</A
 
521
></TD
 
522
><TD
 
523
WIDTH="33%"
 
524
ALIGN="right"
 
525
VALIGN="top"
 
526
>COMMENT</TD
 
527
></TR
 
528
></TABLE
 
529
></DIV
 
530
></BODY
 
531
></HTML
 
532
>
 
 
b'\\ No newline at end of file'