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

   1 '\" t
   2 .\"     Title: EXPLAIN
   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 "EXPLAIN" "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 EXPLAIN \- show the execution plan of a statement
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 EXPLAIN [ ( \fIoption\fR [, \&.\&.\&.] ) ] \fIstatement\fR
  36
  37 where \fIoption\fR can be one of:
  38
  39     ANALYZE [ \fIboolean\fR ]
  40     VERBOSE [ \fIboolean\fR ]
  41     COSTS [ \fIboolean\fR ]
  42     SETTINGS [ \fIboolean\fR ]
  43     GENERIC_PLAN [ \fIboolean\fR ]
  44     BUFFERS [ \fIboolean\fR ]
  45     SERIALIZE [ { NONE | TEXT | BINARY } ]
  46     WAL [ \fIboolean\fR ]
  47     TIMING [ \fIboolean\fR ]
  48     SUMMARY [ \fIboolean\fR ]
  49     MEMORY [ \fIboolean\fR ]
  50     FORMAT { TEXT | XML | JSON | YAML }
  51 .fi
  52 .SH "DESCRIPTION"
  53 .PP
  54 This command displays the execution plan that the
  55 PostgreSQL
  56 planner generates for the supplied statement\&. The execution plan shows how the table(s) referenced by the statement will be scanned \(em by plain sequential scan, index scan, etc\&. \(em and if multiple tables are referenced, what join algorithms will be used to bring together the required rows from each input table\&.
  57 .PP
  58 The most critical part of the display is the estimated statement execution cost, which is the planner\*(Aqs guess at how long it will take to run the statement (measured in cost units that are arbitrary, but conventionally mean disk page fetches)\&. Actually two numbers are shown: the start\-up cost before the first row can be returned, and the total cost to return all the rows\&. For most queries the total cost is what matters, but in contexts such as a subquery in
  59 EXISTS, the planner will choose the smallest start\-up cost instead of the smallest total cost (since the executor will stop after getting one row, anyway)\&. Also, if you limit the number of rows to return with a
  60 LIMIT
  61 clause, the planner makes an appropriate interpolation between the endpoint costs to estimate which plan is really the cheapest\&.
  62 .PP
  63 The
  64 ANALYZE
  65 option causes the statement to be actually executed, not only planned\&. Then actual run time statistics are added to the display, including the total elapsed time expended within each plan node (in milliseconds) and the total number of rows it actually returned\&. This is useful for seeing whether the planner\*(Aqs estimates are close to reality\&.
  66 .if n \{\
  67 .sp
  68 .\}
  69 .RS 4
  70 .it 1 an-trap
  71 .nr an-no-space-flag 1
  72 .nr an-break-flag 1
  73 .br
  74 .ps +1
  75 \fBImportant\fR
  76 .ps -1
  77 .br
  78 .PP
  79 Keep in mind that the statement is actually executed when the
  80 ANALYZE
  81 option is used\&. Although
  82 \fBEXPLAIN\fR
  83 will discard any output that a
  84 \fBSELECT\fR
  85 would return, other side effects of the statement will happen as usual\&. If you wish to use
  86 \fBEXPLAIN ANALYZE\fR
  87 on an
  88 \fBINSERT\fR,
  89 \fBUPDATE\fR,
  90 \fBDELETE\fR,
  91 \fBMERGE\fR,
  92 \fBCREATE TABLE AS\fR, or
  93 \fBEXECUTE\fR
  94 statement without letting the command affect your data, use this approach:
  95 .sp
  96 .if n \{\
  97 .RS 4
  98 .\}
  99 .nf
 100 BEGIN;
 101 EXPLAIN ANALYZE \&.\&.\&.;
 102 ROLLBACK;
 103 .fi
 104 .if n \{\
 105 .RE
 106 .\}
 107 .sp .5v
 108 .RE
 109 .SH "PARAMETERS"
 110 .PP
 111 ANALYZE
 112 .RS 4
 113 Carry out the command and show actual run times and other statistics\&. This parameter defaults to
 114 FALSE\&.
 115 .RE
 116 .PP
 117 VERBOSE
 118 .RS 4
 119 Display additional information regarding the plan\&. Specifically, include the output column list for each node in the plan tree, schema\-qualify table and function names, always label variables in expressions with their range table alias, and always print the name of each trigger for which statistics are displayed\&. The query identifier will also be displayed if one has been computed, see
 120 compute_query_id
 121 for more details\&. This parameter defaults to
 122 FALSE\&.
 123 .RE
 124 .PP
 125 COSTS
 126 .RS 4
 127 Include information on the estimated startup and total cost of each plan node, as well as the estimated number of rows and the estimated width of each row\&. This parameter defaults to
 128 TRUE\&.
 129 .RE
 130 .PP
 131 SETTINGS
 132 .RS 4
 133 Include information on configuration parameters\&. Specifically, include options affecting query planning with value different from the built\-in default value\&. This parameter defaults to
 134 FALSE\&.
 135 .RE
 136 .PP
 137 GENERIC_PLAN
 138 .RS 4
 139 Allow the statement to contain parameter placeholders like
 140 $1, and generate a generic plan that does not depend on the values of those parameters\&. See
 141 \fBPREPARE\fR
 142 for details about generic plans and the types of statement that support parameters\&. This parameter cannot be used together with
 143 ANALYZE\&. It defaults to
 144 FALSE\&.
 145 .RE
 146 .PP
 147 BUFFERS
 148 .RS 4
 149 Include information on buffer usage\&. Specifically, include the number of shared blocks hit, read, dirtied, and written, the number of local blocks hit, read, dirtied, and written, the number of temp blocks read and written, and the time spent reading and writing data file blocks, local blocks and temporary file blocks (in milliseconds) if
 150 track_io_timing
 151 is enabled\&. A
 152 \fIhit\fR
 153 means that a read was avoided because the block was found already in cache when needed\&. Shared blocks contain data from regular tables and indexes; local blocks contain data from temporary tables and indexes; while temporary blocks contain short\-term working data used in sorts, hashes, Materialize plan nodes, and similar cases\&. The number of blocks
 154 \fIdirtied\fR
 155 indicates the number of previously unmodified blocks that were changed by this query; while the number of blocks
 156 \fIwritten\fR
 157 indicates the number of previously\-dirtied blocks evicted from cache by this backend during query processing\&. The number of blocks shown for an upper\-level node includes those used by all its child nodes\&. In text format, only non\-zero values are printed\&. Buffers information is automatically included when
 158 ANALYZE
 159 is used\&.
 160 .RE
 161 .PP
 162 SERIALIZE
 163 .RS 4
 164 Include information on the cost of
 165 serializing
 166 the query\*(Aqs output data, that is converting it to text or binary format to send to the client\&. This can be a significant part of the time required for regular execution of the query, if the datatype output functions are expensive or if
 167 TOASTed values must be fetched from out\-of\-line storage\&.
 168 \fBEXPLAIN\fR\*(Aqs default behavior,
 169 SERIALIZE NONE, does not perform these conversions\&. If
 170 SERIALIZE TEXT
 171 or
 172 SERIALIZE BINARY
 173 is specified, the appropriate conversions are performed, and the time spent doing so is measured (unless
 174 TIMING OFF
 175 is specified)\&. If the
 176 BUFFERS
 177 option is also specified, then any buffer accesses involved in the conversions are counted too\&. In no case, however, will
 178 \fBEXPLAIN\fR
 179 actually send the resulting data to the client; hence network transmission costs cannot be investigated this way\&. Serialization may only be enabled when
 180 ANALYZE
 181 is also enabled\&. If
 182 SERIALIZE
 183 is written without an argument,
 184 TEXT
 185 is assumed\&.
 186 .RE
 187 .PP
 188 WAL
 189 .RS 4
 190 Include information on WAL record generation\&. Specifically, include the number of records, number of full page images (fpi), the amount of WAL generated in bytes and the number of times the WAL buffers became full\&. In text format, only non\-zero values are printed\&. This parameter may only be used when
 191 ANALYZE
 192 is also enabled\&. It defaults to
 193 FALSE\&.
 194 .RE
 195 .PP
 196 TIMING
 197 .RS 4
 198 Include actual startup time and time spent in each node in the output\&. The overhead of repeatedly reading the system clock can slow down the query significantly on some systems, so it may be useful to set this parameter to
 199 FALSE
 200 when only actual row counts, and not exact times, are needed\&. Run time of the entire statement is always measured, even when node\-level timing is turned off with this option\&. This parameter may only be used when
 201 ANALYZE
 202 is also enabled\&. It defaults to
 203 TRUE\&.
 204 .RE
 205 .PP
 206 SUMMARY
 207 .RS 4
 208 Include summary information (e\&.g\&., totaled timing information) after the query plan\&. Summary information is included by default when
 209 ANALYZE
 210 is used but otherwise is not included by default, but can be enabled using this option\&. Planning time in
 211 \fBEXPLAIN EXECUTE\fR
 212 includes the time required to fetch the plan from the cache and the time required for re\-planning, if necessary\&.
 213 .RE
 214 .PP
 215 MEMORY
 216 .RS 4
 217 Include information on memory consumption by the query planning phase\&. Specifically, include the precise amount of storage used by planner in\-memory structures, as well as total memory considering allocation overhead\&. This parameter defaults to
 218 FALSE\&.
 219 .RE
 220 .PP
 221 FORMAT
 222 .RS 4
 223 Specify the output format, which can be TEXT, XML, JSON, or YAML\&. Non\-text output contains the same information as the text output format, but is easier for programs to parse\&. This parameter defaults to
 224 TEXT\&.
 225 .RE
 226 .PP
 227 \fIboolean\fR
 228 .RS 4
 229 Specifies whether the selected option should be turned on or off\&. You can write
 230 TRUE,
 231 ON, or
 232 1
 233 to enable the option, and
 234 FALSE,
 235 OFF, or
 236 0
 237 to disable it\&. The
 238 \fIboolean\fR
 239 value can also be omitted, in which case
 240 TRUE
 241 is assumed\&.
 242 .RE
 243 .PP
 244 \fIstatement\fR
 245 .RS 4
 246 Any
 247 \fBSELECT\fR,
 248 \fBINSERT\fR,
 249 \fBUPDATE\fR,
 250 \fBDELETE\fR,
 251 \fBMERGE\fR,
 252 \fBVALUES\fR,
 253 \fBEXECUTE\fR,
 254 \fBDECLARE\fR,
 255 \fBCREATE TABLE AS\fR, or
 256 \fBCREATE MATERIALIZED VIEW AS\fR
 257 statement, whose execution plan you wish to see\&.
 258 .RE
 259 .SH "OUTPUTS"
 260 .PP
 261 The command\*(Aqs result is a textual description of the plan selected for the
 262 \fIstatement\fR, optionally annotated with execution statistics\&.
 263 Section\ \&14.1
 264 describes the information provided\&.
 265 .SH "NOTES"
 266 .PP
 267 In order to allow the
 268 PostgreSQL
 269 query planner to make reasonably informed decisions when optimizing queries, the
 270 pg_statistic
 271 data should be up\-to\-date for all tables used in the query\&. Normally the
 272 autovacuum daemon
 273 will take care of that automatically\&. But if a table has recently had substantial changes in its contents, you might need to do a manual
 274 \fBANALYZE\fR
 275 rather than wait for autovacuum to catch up with the changes\&.
 276 .PP
 277 In order to measure the run\-time cost of each node in the execution plan, the current implementation of
 278 \fBEXPLAIN ANALYZE\fR
 279 adds profiling overhead to query execution\&. As a result, running
 280 \fBEXPLAIN ANALYZE\fR
 281 on a query can sometimes take significantly longer than executing the query normally\&. The amount of overhead depends on the nature of the query, as well as the platform being used\&. The worst case occurs for plan nodes that in themselves require very little time per execution, and on machines that have relatively slow operating system calls for obtaining the time of day\&.
 282 .SH "EXAMPLES"
 283 .PP
 284 To show the plan for a simple query on a table with a single
 285 integer
 286 column and 10000 rows:
 287 .sp
 288 .if n \{\
 289 .RS 4
 290 .\}
 291 .nf
 292 EXPLAIN SELECT * FROM foo;
 293
 294                        QUERY PLAN
 295 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 296  Seq Scan on foo  (cost=0\&.00\&.\&.155\&.00 rows=10000 width=4)
 297 (1 row)
 298 .fi
 299 .if n \{\
 300 .RE
 301 .\}
 302 .PP
 303 Here is the same query, with JSON output formatting:
 304 .sp
 305 .if n \{\
 306 .RS 4
 307 .\}
 308 .nf
 309 EXPLAIN (FORMAT JSON) SELECT * FROM foo;
 310            QUERY PLAN
 311 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 312  [                             +
 313    {                           +
 314      "Plan": {                 +
 315        "Node Type": "Seq Scan",+
 316        "Relation Name": "foo", +
 317        "Alias": "foo",         +
 318        "Startup Cost": 0\&.00,   +
 319        "Total Cost": 155\&.00,   +
 320        "Plan Rows": 10000,     +
 321        "Plan Width": 4         +
 322      }                         +
 323    }                           +
 324  ]
 325 (1 row)
 326 .fi
 327 .if n \{\
 328 .RE
 329 .\}
 330 .PP
 331 If there is an index and we use a query with an indexable
 332 WHERE
 333 condition,
 334 \fBEXPLAIN\fR
 335 might show a different plan:
 336 .sp
 337 .if n \{\
 338 .RS 4
 339 .\}
 340 .nf
 341 EXPLAIN SELECT * FROM foo WHERE i = 4;
 342
 343                          QUERY PLAN
 344 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 345  Index Scan using fi on foo  (cost=0\&.00\&.\&.5\&.98 rows=1 width=4)
 346    Index Cond: (i = 4)
 347 (2 rows)
 348 .fi
 349 .if n \{\
 350 .RE
 351 .\}
 352 .PP
 353 Here is the same query, but in YAML format:
 354 .sp
 355 .if n \{\
 356 .RS 4
 357 .\}
 358 .nf
 359 EXPLAIN (FORMAT YAML) SELECT * FROM foo WHERE i=\*(Aq4\*(Aq;
 360           QUERY PLAN
 361 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 362  \- Plan:                      +
 363      Node Type: "Index Scan"  +
 364      Scan Direction: "Forward"+
 365      Index Name: "fi"         +
 366      Relation Name: "foo"     +
 367      Alias: "foo"             +
 368      Startup Cost: 0\&.00       +
 369      Total Cost: 5\&.98         +
 370      Plan Rows: 1             +
 371      Plan Width: 4            +
 372      Index Cond: "(i = 4)"
 373 (1 row)
 374 .fi
 375 .if n \{\
 376 .RE
 377 .\}
 378 .sp
 379 XML format is left as an exercise for the reader\&.
 380 .PP
 381 Here is the same plan with cost estimates suppressed:
 382 .sp
 383 .if n \{\
 384 .RS 4
 385 .\}
 386 .nf
 387 EXPLAIN (COSTS FALSE) SELECT * FROM foo WHERE i = 4;
 388
 389         QUERY PLAN
 390 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 391  Index Scan using fi on foo
 392    Index Cond: (i = 4)
 393 (2 rows)
 394 .fi
 395 .if n \{\
 396 .RE
 397 .\}
 398 .PP
 399 Here is an example of a query plan for a query using an aggregate function:
 400 .sp
 401 .if n \{\
 402 .RS 4
 403 .\}
 404 .nf
 405 EXPLAIN SELECT sum(i) FROM foo WHERE i < 10;
 406
 407                              QUERY PLAN
 408 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\:\-\-
 409  Aggregate  (cost=23\&.93\&.\&.23\&.93 rows=1 width=4)
 410    \->  Index Scan using fi on foo  (cost=0\&.00\&.\&.23\&.92 rows=6 width=4)
 411          Index Cond: (i < 10)
 412 (3 rows)
 413 .fi
 414 .if n \{\
 415 .RE
 416 .\}
 417 .PP
 418 Here is an example of using
 419 \fBEXPLAIN EXECUTE\fR
 420 to display the execution plan for a prepared query:
 421 .sp
 422 .if n \{\
 423 .RS 4
 424 .\}
 425 .nf
 426 PREPARE query(int, int) AS SELECT sum(bar) FROM test
 427     WHERE id > $1 AND id < $2
 428     GROUP BY foo;
 429
 430 EXPLAIN ANALYZE EXECUTE query(100, 200);
 431
 432                                                        QUERY PLAN
 433 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 434  HashAggregate  (cost=10\&.77\&.\&.10\&.87 rows=10 width=12) (actual time=0\&.043\&.\&.0\&.044 rows=10\&.00 loops=1)
 435    Group Key: foo
 436    Batches: 1  Memory Usage: 24kB
 437    Buffers: shared hit=4
 438    \->  Index Scan using test_pkey on test  (cost=0\&.29\&.\&.10\&.27 rows=99 width=8) (actual time=0\&.009\&.\&.0\&.025 rows=99\&.00 loops=1)
 439          Index Cond: ((id > 100) AND (id < 200))
 440          Index Searches: 1
 441          Buffers: shared hit=4
 442  Planning Time: 0\&.244 ms
 443  Execution Time: 0\&.073 ms
 444 (10 rows)
 445 .fi
 446 .if n \{\
 447 .RE
 448 .\}
 449 .PP
 450 Of course, the specific numbers shown here depend on the actual contents of the tables involved\&. Also note that the numbers, and even the selected query strategy, might vary between
 451 PostgreSQL
 452 releases due to planner improvements\&. In addition, the
 453 \fBANALYZE\fR
 454 command uses random sampling to estimate data statistics; therefore, it is possible for cost estimates to change after a fresh run of
 455 \fBANALYZE\fR, even if the actual distribution of data in the table has not changed\&.
 456 .PP
 457 Notice that the previous example showed a
 458 \(lqcustom\(rq
 459 plan for the specific parameter values given in
 460 \fBEXECUTE\fR\&. We might also wish to see the generic plan for a parameterized query, which can be done with
 461 GENERIC_PLAN:
 462 .sp
 463 .if n \{\
 464 .RS 4
 465 .\}
 466 .nf
 467 EXPLAIN (GENERIC_PLAN)
 468   SELECT sum(bar) FROM test
 469     WHERE id > $1 AND id < $2
 470     GROUP BY foo;
 471
 472                                   QUERY PLAN
 473 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\:\-\-\-\-\-\-\-\-\-\-\-\-
 474  HashAggregate  (cost=26\&.79\&.\&.26\&.89 rows=10 width=12)
 475    Group Key: foo
 476    \->  Index Scan using test_pkey on test  (cost=0\&.29\&.\&.24\&.29 rows=500 width=8)
 477          Index Cond: ((id > $1) AND (id < $2))
 478 (4 rows)
 479 .fi
 480 .if n \{\
 481 .RE
 482 .\}
 483 .sp
 484 In this case the parser correctly inferred that
 485 $1
 486 and
 487 $2
 488 should have the same data type as
 489 id, so the lack of parameter type information from
 490 \fBPREPARE\fR
 491 was not a problem\&. In other cases it might be necessary to explicitly specify types for the parameter symbols, which can be done by casting them, for example:
 492 .sp
 493 .if n \{\
 494 .RS 4
 495 .\}
 496 .nf
 497 EXPLAIN (GENERIC_PLAN)
 498   SELECT sum(bar) FROM test
 499     WHERE id > $1::integer AND id < $2::integer
 500     GROUP BY foo;
 501 .fi
 502 .if n \{\
 503 .RE
 504 .\}
 505 .sp
 506 .SH "COMPATIBILITY"
 507 .PP
 508 There is no
 509 \fBEXPLAIN\fR
 510 statement defined in the SQL standard\&.
 511 .PP
 512 The following syntax was used before
 513 PostgreSQL
 514 version 9\&.0 and is still supported:
 515 .sp
 516 .if n \{\
 517 .RS 4
 518 .\}
 519 .nf
 520 EXPLAIN [ ANALYZE ] [ VERBOSE ] \fIstatement\fR
 521 .fi
 522 .if n \{\
 523 .RE
 524 .\}
 525 .sp
 526 Note that in this syntax, the options must be specified in exactly the order shown\&.
 527 .SH "SEE ALSO"
 528 \fBANALYZE\fR(7)