raw/man7/analyze.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "ANALYZE" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 ANALYZE \- collect statistics about a database
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 ANALYZE [ VERBOSE ] [ \fItable\fR [ (\fIcolumn\fR [, ...] ) ] ]
  10 .sp
  11 .fi
  12 .SH "DESCRIPTION"
  13 .PP
  14 \fBANALYZE\fR collects statistics about the contents
  15 of tables in the database, and stores the results in the system
  16 table pg_statistic. Subsequently, the query
  17 planner uses these statistics to help determine the most efficient
  18 execution plans for queries.
  19 .PP
  20 With no parameter, \fBANALYZE\fR examines every table in the
  21 current database. With a parameter, \fBANALYZE\fR examines
  22 only that table. It is further possible to give a list of column names,
  23 in which case only the statistics for those columns are collected.
  24 .SH "PARAMETERS"
  25 .TP
  26 \fBVERBOSE\fR
  27 Enables display of progress messages.
  28 .TP
  29 \fB\fItable\fB\fR
  30 The name (possibly schema-qualified) of a specific table to
  31 analyze. Defaults to all tables in the current database.
  32 .TP
  33 \fB\fIcolumn\fB\fR
  34 The name of a specific column to analyze. Defaults to all columns.
  35 .SH "OUTPUTS"
  36 .PP
  37 When VERBOSE is specified, \fBANALYZE\fR emits
  38 progress messages to indicate which table is currently being
  39 processed. Various statistics about the tables are printed as well.
  40 .SH "NOTES"
  41 .PP
  42 It is a good idea to run \fBANALYZE\fR periodically, or
  43 just after making major changes in the contents of a table. Accurate
  44 statistics will help the planner to choose the most appropriate query
  45 plan, and thereby improve the speed of query processing. A common
  46 strategy is to run VACUUM [\fBvacuum\fR(7)]
  47 and \fBANALYZE\fR once a day during a low-usage time of day.
  48 .PP
  49 Unlike \fBVACUUM FULL\fR, \fBANALYZE\fR
  50 requires only a read lock on the target table, so it can run in
  51 parallel with other activity on the table.
  52 .PP
  53 The statistics collected by \fBANALYZE\fR usually
  54 include a list of some of the most common values in each column and
  55 a histogram showing the approximate data distribution in each
  56 column. One or both of these may be omitted if
  57 \fBANALYZE\fR deems them uninteresting (for example,
  58 in a unique-key column, there are no common values) or if the
  59 column data type does not support the appropriate operators. There
  60 is more information about the statistics in the chapter called ``Routine Database Maintenance'' in the documentation.
  61 .PP
  62 For large tables, \fBANALYZE\fR takes a random sample
  63 of the table contents, rather than examining every row. This
  64 allows even very large tables to be analyzed in a small amount of
  65 time. Note, however, that the statistics are only approximate, and
  66 will change slightly each time \fBANALYZE\fR is run,
  67 even if the actual table contents did not change. This may result
  68 in small changes in the planner's estimated costs shown by
  69 \fBEXPLAIN\fR. In rare situations, this
  70 non-determinism will cause the query optimizer to choose a
  71 different query plan between runs of \fBANALYZE\fR. To
  72 avoid this, raise the amount of statistics collected by
  73 \fBANALYZE\fR, as described below.
  74 .PP
  75 The extent of analysis can be controlled by adjusting the
  76 DEFAULT_STATISTICS_TARGET parameter variable, or
  77 on a column-by-column basis by setting the per-column statistics
  78 target with \fBALTER TABLE ... ALTER COLUMN ... SET
  79 STATISTICS\fR (see ALTER TABLE [\fBalter_table\fR(7)]). The target value sets the
  80 maximum number of entries in the most-common-value list and the
  81 maximum number of bins in the histogram. The default target value
  82 is 10, but this can be adjusted up or down to trade off accuracy of
  83 planner estimates against the time taken for
  84 \fBANALYZE\fR and the amount of space occupied in
  85 pg_statistic. In particular, setting the
  86 statistics target to zero disables collection of statistics for
  87 that column. It may be useful to do that for columns that are
  88 never used as part of the WHERE, GROUP BY,
  89 or ORDER BY clauses of queries, since the planner will
  90 have no use for statistics on such columns.
  91 .PP
  92 The largest statistics target among the columns being analyzed determines
  93 the number of table rows sampled to prepare the statistics. Increasing
  94 the target causes a proportional increase in the time and space needed
  95 to do \fBANALYZE\fR.
  96 .SH "COMPATIBILITY"
  97 .PP
  98 There is no \fBANALYZE\fR statement in the SQL standard.