begriffs open source - ai-pg/blob - full-docs/man7/ANALYZE.7

   1 '\" t
   2 .\"     Title: ANALYZE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "ANALYZE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 ANALYZE \- collect statistics about a database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ANALYZE [ ( \fIoption\fR [, \&.\&.\&.] ) ] [ \fItable_and_columns\fR [, \&.\&.\&.] ]
  36
  37 where \fIoption\fR can be one of:
  38
  39     VERBOSE [ \fIboolean\fR ]
  40     SKIP_LOCKED [ \fIboolean\fR ]
  41     BUFFER_USAGE_LIMIT \fIsize\fR
  42
  43 and \fItable_and_columns\fR is:
  44
  45     [ ONLY ] \fItable_name\fR [ * ] [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ]
  46 .fi
  47 .SH "DESCRIPTION"
  48 .PP
  49 \fBANALYZE\fR
  50 collects statistics about the contents of tables in the database, and stores the results in the
  51 pg_statistic
  52 system catalog\&. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries\&.
  53 .PP
  54 Without a
  55 \fItable_and_columns\fR
  56 list,
  57 \fBANALYZE\fR
  58 processes every table and materialized view in the current database that the current user has permission to analyze\&. With a list,
  59 \fBANALYZE\fR
  60 processes only those table(s)\&. It is further possible to give a list of column names for a table, in which case only the statistics for those columns are collected\&.
  61 .SH "PARAMETERS"
  62 .PP
  63 VERBOSE
  64 .RS 4
  65 Enables display of progress messages at
  66 INFO
  67 level\&.
  68 .RE
  69 .PP
  70 SKIP_LOCKED
  71 .RS 4
  72 Specifies that
  73 \fBANALYZE\fR
  74 should not wait for any conflicting locks to be released when beginning work on a relation: if a relation cannot be locked immediately without waiting, the relation is skipped\&. Note that even with this option,
  75 \fBANALYZE\fR
  76 may still block when opening the relation\*(Aqs indexes or when acquiring sample rows from partitions, table inheritance children, and some types of foreign tables\&. Also, while
  77 \fBANALYZE\fR
  78 ordinarily processes all partitions of specified partitioned tables, this option will cause
  79 \fBANALYZE\fR
  80 to skip all partitions if there is a conflicting lock on the partitioned table\&.
  81 .RE
  82 .PP
  83 BUFFER_USAGE_LIMIT
  84 .RS 4
  85 Specifies the
  86 Buffer Access Strategy
  87 ring buffer size for
  88 \fBANALYZE\fR\&. This size is used to calculate the number of shared buffers which will be reused as part of this strategy\&.
  89 0
  90 disables use of a
  91 Buffer Access Strategy\&. When this option is not specified,
  92 \fBANALYZE\fR
  93 uses the value from
  94 vacuum_buffer_usage_limit\&. Higher settings can allow
  95 \fBANALYZE\fR
  96 to run more quickly, but having too large a setting may cause too many other useful pages to be evicted from shared buffers\&. The minimum value is
  97 128 kB
  98 and the maximum value is
  99 16 GB\&.
 100 .RE
 101 .PP
 102 \fIboolean\fR
 103 .RS 4
 104 Specifies whether the selected option should be turned on or off\&. You can write
 105 TRUE,
 106 ON, or
 107 1
 108 to enable the option, and
 109 FALSE,
 110 OFF, or
 111 0
 112 to disable it\&. The
 113 \fIboolean\fR
 114 value can also be omitted, in which case
 115 TRUE
 116 is assumed\&.
 117 .RE
 118 .PP
 119 \fIsize\fR
 120 .RS 4
 121 Specifies an amount of memory in kilobytes\&. Sizes may also be specified as a string containing the numerical size followed by any one of the following memory units:
 122 B
 123 (bytes),
 124 kB
 125 (kilobytes),
 126 MB
 127 (megabytes),
 128 GB
 129 (gigabytes), or
 130 TB
 131 (terabytes)\&.
 132 .RE
 133 .PP
 134 \fItable_name\fR
 135 .RS 4
 136 The name (possibly schema\-qualified) of a specific table to analyze\&. If omitted, all regular tables, partitioned tables, and materialized views in the current database are analyzed (but not foreign tables)\&. If
 137 ONLY
 138 is specified before the table name, only that table is analyzed\&. If
 139 ONLY
 140 is not specified, the table and all its inheritance child tables or partitions (if any) are analyzed\&. Optionally,
 141 *
 142 can be specified after the table name to explicitly indicate that inheritance child tables (or partitions) are to be analyzed\&.
 143 .RE
 144 .PP
 145 \fIcolumn_name\fR
 146 .RS 4
 147 The name of a specific column to analyze\&. Defaults to all columns\&.
 148 .RE
 149 .SH "OUTPUTS"
 150 .PP
 151 When
 152 VERBOSE
 153 is specified,
 154 \fBANALYZE\fR
 155 emits progress messages to indicate which table is currently being processed\&. Various statistics about the tables are printed as well\&.
 156 .SH "NOTES"
 157 .PP
 158 To analyze a table, one must ordinarily have the
 159 MAINTAIN
 160 privilege on the table\&. However, database owners are allowed to analyze all tables in their databases, except shared catalogs\&.
 161 \fBANALYZE\fR
 162 will skip over any tables that the calling user does not have permission to analyze\&.
 163 .PP
 164 Foreign tables are analyzed only when explicitly selected\&. Not all foreign data wrappers support
 165 \fBANALYZE\fR\&. If the table\*(Aqs wrapper does not support
 166 \fBANALYZE\fR, the command prints a warning and does nothing\&.
 167 .PP
 168 In the default
 169 PostgreSQL
 170 configuration, the autovacuum daemon (see
 171 Section\ \&24.1.6) takes care of automatic analyzing of tables when they are first loaded with data, and as they change throughout regular operation\&. When autovacuum is disabled, it is a good idea to run
 172 \fBANALYZE\fR
 173 periodically, or just after making major changes in the contents of a table\&. Accurate statistics will help the planner to choose the most appropriate query plan, and thereby improve the speed of query processing\&. A common strategy for read\-mostly databases is to run
 174 \fBVACUUM\fR
 175 and
 176 \fBANALYZE\fR
 177 once a day during a low\-usage time of day\&. (This will not be sufficient if there is heavy update activity\&.)
 178 .PP
 179 While
 180 \fBANALYZE\fR
 181 is running, the
 182 search_path
 183 is temporarily changed to
 184 pg_catalog, pg_temp\&.
 185 .PP
 186 \fBANALYZE\fR
 187 requires only a read lock on the target table, so it can run in parallel with other non\-DDL activity on the table\&.
 188 .PP
 189 The statistics collected by
 190 \fBANALYZE\fR
 191 usually include a list of some of the most common values in each column and a histogram showing the approximate data distribution in each column\&. One or both of these can be omitted if
 192 \fBANALYZE\fR
 193 deems them uninteresting (for example, in a unique\-key column, there are no common values) or if the column data type does not support the appropriate operators\&. There is more information about the statistics in
 194 Chapter\ \&24\&.
 195 .PP
 196 For large tables,
 197 \fBANALYZE\fR
 198 takes a random sample of the table contents, rather than examining every row\&. This allows even very large tables to be analyzed in a small amount of time\&. Note, however, that the statistics are only approximate, and will change slightly each time
 199 \fBANALYZE\fR
 200 is run, even if the actual table contents did not change\&. This might result in small changes in the planner\*(Aqs estimated costs shown by
 201 \fBEXPLAIN\fR\&. In rare situations, this non\-determinism will cause the planner\*(Aqs choices of query plans to change after
 202 \fBANALYZE\fR
 203 is run\&. To avoid this, raise the amount of statistics collected by
 204 \fBANALYZE\fR, as described below\&.
 205 .PP
 206 The extent of analysis can be controlled by adjusting the
 207 default_statistics_target
 208 configuration variable, or on a column\-by\-column basis by setting the per\-column statistics target with
 209 \fBALTER TABLE \&.\&.\&. ALTER COLUMN \&.\&.\&. SET STATISTICS\fR\&. The target value sets the maximum number of entries in the most\-common\-value list and the maximum number of bins in the histogram\&. The default target value is 100, but this can be adjusted up or down to trade off accuracy of planner estimates against the time taken for
 210 \fBANALYZE\fR
 211 and the amount of space occupied in
 212 pg_statistic\&. In particular, setting the statistics target to zero disables collection of statistics for that column\&. It might be useful to do that for columns that are never used as part of the
 213 WHERE,
 214 GROUP BY, or
 215 ORDER BY
 216 clauses of queries, since the planner will have no use for statistics on such columns\&.
 217 .PP
 218 The largest statistics target among the columns being analyzed determines the number of table rows sampled to prepare the statistics\&. Increasing the target causes a proportional increase in the time and space needed to do
 219 \fBANALYZE\fR\&.
 220 .PP
 221 One of the values estimated by
 222 \fBANALYZE\fR
 223 is the number of distinct values that appear in each column\&. Because only a subset of the rows are examined, this estimate can sometimes be quite inaccurate, even with the largest possible statistics target\&. If this inaccuracy leads to bad query plans, a more accurate value can be determined manually and then installed with
 224 \fBALTER TABLE \&.\&.\&. ALTER COLUMN \&.\&.\&. SET (n_distinct = \&.\&.\&.)\fR\&.
 225 .PP
 226 If the table being analyzed has inheritance children,
 227 \fBANALYZE\fR
 228 gathers two sets of statistics: one on the rows of the parent table only, and a second including rows of both the parent table and all of its children\&. This second set of statistics is needed when planning queries that process the inheritance tree as a whole\&. The autovacuum daemon, however, will only consider inserts or updates on the parent table itself when deciding whether to trigger an automatic analyze for that table\&. If that table is rarely inserted into or updated, the inheritance statistics will not be up to date unless you run
 229 \fBANALYZE\fR
 230 manually\&. By default,
 231 \fBANALYZE\fR
 232 will also recursively collect and update the statistics for each inheritance child table\&. The
 233 ONLY
 234 keyword may be used to disable this\&.
 235 .PP
 236 For partitioned tables,
 237 \fBANALYZE\fR
 238 gathers statistics by sampling rows from all partitions\&. By default,
 239 \fBANALYZE\fR
 240 will also recursively collect and update the statistics for each partition\&. The
 241 ONLY
 242 keyword may be used to disable this\&.
 243 .PP
 244 The autovacuum daemon does not process partitioned tables, nor does it process inheritance parents if only the children are ever modified\&. It is usually necessary to periodically run a manual
 245 \fBANALYZE\fR
 246 to keep the statistics of the table hierarchy up to date\&.
 247 .PP
 248 If any child tables or partitions are foreign tables whose foreign data wrappers do not support
 249 \fBANALYZE\fR, those tables are ignored while gathering inheritance statistics\&.
 250 .PP
 251 If the table being analyzed is completely empty,
 252 \fBANALYZE\fR
 253 will not record new statistics for that table\&. Any existing statistics will be retained\&.
 254 .PP
 255 Each backend running
 256 \fBANALYZE\fR
 257 will report its progress in the
 258 pg_stat_progress_analyze
 259 view\&. See
 260 Section\ \&27.4.1
 261 for details\&.
 262 .SH "COMPATIBILITY"
 263 .PP
 264 There is no
 265 \fBANALYZE\fR
 266 statement in the SQL standard\&.
 267 .PP
 268 The following syntax was used before
 269 PostgreSQL
 270 version 11 and is still supported:
 271 .sp
 272 .if n \{\
 273 .RS 4
 274 .\}
 275 .nf
 276 ANALYZE [ VERBOSE ] [ \fItable_and_columns\fR [, \&.\&.\&.] ]
 277 .fi
 278 .if n \{\
 279 .RE
 280 .\}
 281 .sp
 282 .SH "SEE ALSO"
 283 \fBVACUUM\fR(7), \fBvacuumdb\fR(1), Section\ \&19.10.2, Section\ \&24.1.6, Section\ \&27.4.1