← 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-analyze.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-analyze.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
>ANALYZE</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="ALTER VIEW"
 
19
HREF="sql-alterview.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="BEGIN"
 
22
HREF="sql-begin.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="ALTER VIEW"
 
57
HREF="sql-alterview.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="ALTER VIEW"
 
67
HREF="sql-alterview.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="BEGIN"
 
81
HREF="sql-begin.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="BEGIN"
 
90
HREF="sql-begin.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-ANALYZE"
 
102
></A
 
103
>ANALYZE</H1
 
104
><DIV
 
105
CLASS="REFNAMEDIV"
 
106
><A
 
107
NAME="AEN62993"
 
108
></A
 
109
><H2
 
110
>Name</H2
 
111
>ANALYZE&nbsp;--&nbsp;collect statistics about a database</DIV
 
112
><DIV
 
113
CLASS="REFSYNOPSISDIV"
 
114
><A
 
115
NAME="AEN62998"
 
116
></A
 
117
><H2
 
118
>Synopsis</H2
 
119
><PRE
 
120
CLASS="SYNOPSIS"
 
121
>ANALYZE [ VERBOSE ] [ <TT
 
122
CLASS="REPLACEABLE"
 
123
><I
 
124
>table</I
 
125
></TT
 
126
> [ ( <TT
 
127
CLASS="REPLACEABLE"
 
128
><I
 
129
>column</I
 
130
></TT
 
131
> [, ...] ) ] ]</PRE
 
132
></DIV
 
133
><DIV
 
134
CLASS="REFSECT1"
 
135
><A
 
136
NAME="AEN63002"
 
137
></A
 
138
><H2
 
139
>Description</H2
 
140
><P
 
141
>   <TT
 
142
CLASS="COMMAND"
 
143
>ANALYZE</TT
 
144
> collects statistics about the contents
 
145
   of tables in the database, and stores the results in the <A
 
146
HREF="catalog-pg-statistic.html"
 
147
><TT
 
148
CLASS="STRUCTNAME"
 
149
>pg_statistic</TT
 
150
></A
 
151
>
 
152
   system catalog.  Subsequently, the query planner uses these
 
153
   statistics to help determine the most efficient execution plans for
 
154
   queries.
 
155
  </P
 
156
><P
 
157
>   With no parameter, <TT
 
158
CLASS="COMMAND"
 
159
>ANALYZE</TT
 
160
> examines every table in the
 
161
   current database.  With a parameter, <TT
 
162
CLASS="COMMAND"
 
163
>ANALYZE</TT
 
164
> examines
 
165
   only that table.  It is further possible to give a list of column names,
 
166
   in which case only the statistics for those columns are collected.
 
167
  </P
 
168
></DIV
 
169
><DIV
 
170
CLASS="REFSECT1"
 
171
><A
 
172
NAME="AEN63011"
 
173
></A
 
174
><H2
 
175
>Parameters</H2
 
176
><P
 
177
></P
 
178
><DIV
 
179
CLASS="VARIABLELIST"
 
180
><DL
 
181
><DT
 
182
><TT
 
183
CLASS="LITERAL"
 
184
>VERBOSE</TT
 
185
></DT
 
186
><DD
 
187
><P
 
188
>      Enables display of progress messages.
 
189
     </P
 
190
></DD
 
191
><DT
 
192
><TT
 
193
CLASS="REPLACEABLE"
 
194
><I
 
195
>table</I
 
196
></TT
 
197
></DT
 
198
><DD
 
199
><P
 
200
>      The name (possibly schema-qualified) of a specific table to
 
201
      analyze. Defaults to all tables in the current database.
 
202
     </P
 
203
></DD
 
204
><DT
 
205
><TT
 
206
CLASS="REPLACEABLE"
 
207
><I
 
208
>column</I
 
209
></TT
 
210
></DT
 
211
><DD
 
212
><P
 
213
>      The name of a specific column to analyze. Defaults to all columns.
 
214
     </P
 
215
></DD
 
216
></DL
 
217
></DIV
 
218
></DIV
 
219
><DIV
 
220
CLASS="REFSECT1"
 
221
><A
 
222
NAME="AEN63029"
 
223
></A
 
224
><H2
 
225
>Outputs</H2
 
226
><P
 
227
>    When <TT
 
228
CLASS="LITERAL"
 
229
>VERBOSE</TT
 
230
> is specified, <TT
 
231
CLASS="COMMAND"
 
232
>ANALYZE</TT
 
233
> emits
 
234
    progress messages to indicate which table is currently being
 
235
    processed.  Various statistics about the tables are printed as well.
 
236
   </P
 
237
></DIV
 
238
><DIV
 
239
CLASS="REFSECT1"
 
240
><A
 
241
NAME="AEN63034"
 
242
></A
 
243
><H2
 
244
>Notes</H2
 
245
><P
 
246
>   In the default <SPAN
 
247
CLASS="PRODUCTNAME"
 
248
>PostgreSQL</SPAN
 
249
> configuration,
 
250
   the autovacuum daemon (see <A
 
251
HREF="routine-vacuuming.html#AUTOVACUUM"
 
252
>Section 23.1.5</A
 
253
>)
 
254
   takes care of automatic analyzing of tables when they are first loaded
 
255
   with data, and as they change throughout regular operation.
 
256
   When autovacuum is disabled,
 
257
   it is a good idea to run <TT
 
258
CLASS="COMMAND"
 
259
>ANALYZE</TT
 
260
> periodically, or
 
261
   just after making major changes in the contents of a table.  Accurate
 
262
   statistics will help the planner to choose the most appropriate query
 
263
   plan, and thereby improve the speed of query processing.  A common
 
264
   strategy is to run <A
 
265
HREF="sql-vacuum.html"
 
266
>VACUUM</A
 
267
>
 
268
   and <TT
 
269
CLASS="COMMAND"
 
270
>ANALYZE</TT
 
271
> once a day during a low-usage time of day.
 
272
  </P
 
273
><P
 
274
>   <TT
 
275
CLASS="COMMAND"
 
276
>ANALYZE</TT
 
277
>
 
278
   requires only a read lock on the target table, so it can run in
 
279
   parallel with other activity on the table.
 
280
  </P
 
281
><P
 
282
>   The statistics collected by <TT
 
283
CLASS="COMMAND"
 
284
>ANALYZE</TT
 
285
> usually
 
286
   include a list of some of the most common values in each column and
 
287
   a histogram showing the approximate data distribution in each
 
288
   column.  One or both of these can be omitted if
 
289
   <TT
 
290
CLASS="COMMAND"
 
291
>ANALYZE</TT
 
292
> deems them uninteresting (for example,
 
293
   in a unique-key column, there are no common values) or if the
 
294
   column data type does not support the appropriate operators.  There
 
295
   is more information about the statistics in <A
 
296
HREF="maintenance.html"
 
297
>Chapter 23</A
 
298
>.
 
299
  </P
 
300
><P
 
301
>   For large tables, <TT
 
302
CLASS="COMMAND"
 
303
>ANALYZE</TT
 
304
> takes a random sample
 
305
   of the table contents, rather than examining every row.  This
 
306
   allows even very large tables to be analyzed in a small amount of
 
307
   time.  Note, however, that the statistics are only approximate, and
 
308
   will change slightly each time <TT
 
309
CLASS="COMMAND"
 
310
>ANALYZE</TT
 
311
> is run,
 
312
   even if the actual table contents did not change.  This might result
 
313
   in small changes in the planner's estimated costs shown by
 
314
   <A
 
315
HREF="sql-explain.html"
 
316
>EXPLAIN</A
 
317
>.
 
318
   In rare situations, this non-determinism will cause the planner's
 
319
   choices of query plans to change after <TT
 
320
CLASS="COMMAND"
 
321
>ANALYZE</TT
 
322
> is run.
 
323
   To avoid this, raise the amount of statistics collected by
 
324
   <TT
 
325
CLASS="COMMAND"
 
326
>ANALYZE</TT
 
327
>, as described below.
 
328
  </P
 
329
><P
 
330
>   The extent of analysis can be controlled by adjusting the
 
331
   <A
 
332
HREF="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET"
 
333
>default_statistics_target</A
 
334
> configuration variable, or
 
335
   on a column-by-column basis by setting the per-column statistics
 
336
   target with <TT
 
337
CLASS="COMMAND"
 
338
>ALTER TABLE ... ALTER COLUMN ... SET
 
339
   STATISTICS</TT
 
340
> (see <A
 
341
HREF="sql-altertable.html"
 
342
>ALTER TABLE</A
 
343
>).
 
344
   The target value sets the
 
345
   maximum number of entries in the most-common-value list and the
 
346
   maximum number of bins in the histogram.  The default target value
 
347
   is 100, but this can be adjusted up or down to trade off accuracy of
 
348
   planner estimates against the time taken for
 
349
   <TT
 
350
CLASS="COMMAND"
 
351
>ANALYZE</TT
 
352
> and the amount of space occupied in
 
353
   <TT
 
354
CLASS="LITERAL"
 
355
>pg_statistic</TT
 
356
>.  In particular, setting the
 
357
   statistics target to zero disables collection of statistics for
 
358
   that column.  It might be useful to do that for columns that are
 
359
   never used as part of the <TT
 
360
CLASS="LITERAL"
 
361
>WHERE</TT
 
362
>, <TT
 
363
CLASS="LITERAL"
 
364
>GROUP BY</TT
 
365
>,
 
366
   or <TT
 
367
CLASS="LITERAL"
 
368
>ORDER BY</TT
 
369
> clauses of queries, since the planner will
 
370
   have no use for statistics on such columns.
 
371
  </P
 
372
><P
 
373
>   The largest statistics target among the columns being analyzed determines
 
374
   the number of table rows sampled to prepare the statistics.  Increasing
 
375
   the target causes a proportional increase in the time and space needed
 
376
   to do <TT
 
377
CLASS="COMMAND"
 
378
>ANALYZE</TT
 
379
>.
 
380
  </P
 
381
><P
 
382
>   One of the values estimated by <TT
 
383
CLASS="COMMAND"
 
384
>ANALYZE</TT
 
385
> is the number of
 
386
   distinct values that appear in each column.  Because only a subset of the
 
387
   rows are examined, this estimate can sometimes be quite inaccurate, even
 
388
   with the largest possible statistics target.  If this inaccuracy leads to
 
389
   bad query plans, a more accurate value can be determined manually and then
 
390
   installed with
 
391
   <TT
 
392
CLASS="COMMAND"
 
393
>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</TT
 
394
>
 
395
   (see <A
 
396
HREF="sql-altertable.html"
 
397
>ALTER TABLE</A
 
398
>).
 
399
  </P
 
400
><P
 
401
>    If the table being analyzed has one or more children,
 
402
    <TT
 
403
CLASS="COMMAND"
 
404
>ANALYZE</TT
 
405
> will gather statistics twice: once on the
 
406
    rows of the parent table only, and a second time on the rows of the
 
407
    parent table with all of its children.  The autovacuum daemon, however,
 
408
    will only consider inserts or updates on the parent table when deciding
 
409
    whether to trigger an automatic analyze.  If that table is rarely
 
410
    inserted into or updated, the inheritance statistics will not be up to date
 
411
    unless you run <TT
 
412
CLASS="COMMAND"
 
413
>ANALYZE</TT
 
414
> manually.
 
415
  </P
 
416
></DIV
 
417
><DIV
 
418
CLASS="REFSECT1"
 
419
><A
 
420
NAME="AEN63072"
 
421
></A
 
422
><H2
 
423
>Compatibility</H2
 
424
><P
 
425
>   There is no <TT
 
426
CLASS="COMMAND"
 
427
>ANALYZE</TT
 
428
> statement in the SQL standard.
 
429
  </P
 
430
></DIV
 
431
><DIV
 
432
CLASS="REFSECT1"
 
433
><A
 
434
NAME="AEN63076"
 
435
></A
 
436
><H2
 
437
>See Also</H2
 
438
><A
 
439
HREF="sql-vacuum.html"
 
440
>VACUUM</A
 
441
>, <A
 
442
HREF="app-vacuumdb.html"
 
443
><SPAN
 
444
CLASS="APPLICATION"
 
445
>vacuumdb</SPAN
 
446
></A
 
447
>, <A
 
448
HREF="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST"
 
449
>Section 18.4.3</A
 
450
>, <A
 
451
HREF="routine-vacuuming.html#AUTOVACUUM"
 
452
>Section 23.1.5</A
 
453
></DIV
 
454
><DIV
 
455
CLASS="NAVFOOTER"
 
456
><HR
 
457
ALIGN="LEFT"
 
458
WIDTH="100%"><TABLE
 
459
SUMMARY="Footer navigation table"
 
460
WIDTH="100%"
 
461
BORDER="0"
 
462
CELLPADDING="0"
 
463
CELLSPACING="0"
 
464
><TR
 
465
><TD
 
466
WIDTH="33%"
 
467
ALIGN="left"
 
468
VALIGN="top"
 
469
><A
 
470
HREF="sql-alterview.html"
 
471
ACCESSKEY="P"
 
472
>Prev</A
 
473
></TD
 
474
><TD
 
475
WIDTH="34%"
 
476
ALIGN="center"
 
477
VALIGN="top"
 
478
><A
 
479
HREF="index.html"
 
480
ACCESSKEY="H"
 
481
>Home</A
 
482
></TD
 
483
><TD
 
484
WIDTH="33%"
 
485
ALIGN="right"
 
486
VALIGN="top"
 
487
><A
 
488
HREF="sql-begin.html"
 
489
ACCESSKEY="N"
 
490
>Next</A
 
491
></TD
 
492
></TR
 
493
><TR
 
494
><TD
 
495
WIDTH="33%"
 
496
ALIGN="left"
 
497
VALIGN="top"
 
498
>ALTER VIEW</TD
 
499
><TD
 
500
WIDTH="34%"
 
501
ALIGN="center"
 
502
VALIGN="top"
 
503
><A
 
504
HREF="sql-commands.html"
 
505
ACCESSKEY="U"
 
506
>Up</A
 
507
></TD
 
508
><TD
 
509
WIDTH="33%"
 
510
ALIGN="right"
 
511
VALIGN="top"
 
512
>BEGIN</TD
 
513
></TR
 
514
></TABLE
 
515
></DIV
 
516
></BODY
 
517
></HTML
 
518
>
 
 
b'\\ No newline at end of file'