begriffs open source - ai-pg/blob - full-docs/src/sgml/html/pgstatstatements.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.32. pg_stat_statements — track statistics of SQL planning and execution</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information" /><link rel="next" href="pgstattuple.html" title="F.33. pgstattuple — obtain tuple-level statistics" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.32. pg_stat_statements — track statistics of SQL planning and execution</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgstattuple.html" title="F.33. pgstattuple — obtain tuple-level statistics">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGSTATSTATEMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.32. pg_stat_statements — track statistics of SQL planning and execution <a href="#PGSTATSTATEMENTS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-PG-STAT-STATEMENTS">F.32.1. The <code class="structname">pg_stat_statements</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-PG-STAT-STATEMENTS-INFO">F.32.2. The <code class="structname">pg_stat_statements_info</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-FUNCS">F.32.3. Functions</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-CONFIG-PARAMS">F.32.4. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-SAMPLE-OUTPUT">F.32.5. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#PGSTATSTATEMENTS-AUTHORS">F.32.6. Authors</a></span></dt></dl></div><a id="id-1.11.7.42.2" class="indexterm"></a><p>
   3   The <code class="filename">pg_stat_statements</code> module provides a means for
   4   tracking planning and execution statistics of all SQL statements executed by
   5   a server.
   6  </p><p>
   7   The module must be loaded by adding <code class="literal">pg_stat_statements</code> to
   8   <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> in
   9   <code class="filename">postgresql.conf</code>, because it requires additional shared memory.
  10   This means that a server restart is needed to add or remove the module.
  11   In addition, query identifier calculation must be enabled in order for the
  12   module to be active, which is done automatically if <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a>
  13   is set to <code class="literal">auto</code> or <code class="literal">on</code>, or any third-party
  14   module that calculates query identifiers is loaded.
  15  </p><p>
  16    When <code class="filename">pg_stat_statements</code> is active, it tracks
  17    statistics across all databases of the server.  To access and manipulate
  18    these statistics, the module provides views
  19    <code class="structname">pg_stat_statements</code> and
  20    <code class="structname">pg_stat_statements_info</code>,
  21    and the utility functions <code class="function">pg_stat_statements_reset</code> and
  22    <code class="function">pg_stat_statements</code>.  These are not available globally but
  23    can be enabled for a specific database with
  24    <code class="command">CREATE EXTENSION pg_stat_statements</code>.
  25  </p><div class="sect2" id="PGSTATSTATEMENTS-PG-STAT-STATEMENTS"><div class="titlepage"><div><div><h3 class="title">F.32.1. The <code class="structname">pg_stat_statements</code> View <a href="#PGSTATSTATEMENTS-PG-STAT-STATEMENTS" class="id_link">#</a></h3></div></div></div><p>
  26    The statistics gathered by the module are made available via a
  27    view named <code class="structname">pg_stat_statements</code>.  This view
  28    contains one row for each distinct combination of database ID, user
  29    ID, query ID and whether it's a top-level statement or not (up to
  30    the maximum number of distinct statements that the module can track).
  31    The columns of the view are shown in
  32    <a class="xref" href="pgstatstatements.html#PGSTATSTATEMENTS-COLUMNS" title="Table F.22. pg_stat_statements Columns">Table F.22</a>.
  33   </p><div class="table" id="PGSTATSTATEMENTS-COLUMNS"><p class="title"><strong>Table F.22. <code class="structname">pg_stat_statements</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stat_statements Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
  34        Column Type
  35       </p>
  36       <p>
  37        Description
  38       </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
  39        <code class="structfield">userid</code> <code class="type">oid</code>
  40        (references <a class="link" href="catalog-pg-authid.html" title="52.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
  41       </p>
  42       <p>
  43        OID of user who executed the statement
  44       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  45        <code class="structfield">dbid</code> <code class="type">oid</code>
  46        (references <a class="link" href="catalog-pg-database.html" title="52.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
  47       </p>
  48       <p>
  49        OID of database in which the statement was executed
  50       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  51        <code class="structfield">toplevel</code> <code class="type">bool</code>
  52       </p>
  53       <p>
  54        True if the query was executed as a top-level statement
  55        (always true if <code class="varname">pg_stat_statements.track</code> is set to
  56        <code class="literal">top</code>)
  57       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  58        <code class="structfield">queryid</code> <code class="type">bigint</code>
  59       </p>
  60       <p>
  61        Hash code to identify identical normalized queries.
  62       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  63        <code class="structfield">query</code> <code class="type">text</code>
  64       </p>
  65       <p>
  66        Text of a representative statement
  67       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  68        <code class="structfield">plans</code> <code class="type">bigint</code>
  69       </p>
  70       <p>
  71        Number of times the statement was planned
  72        (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
  73        otherwise zero)
  74       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  75        <code class="structfield">total_plan_time</code> <code class="type">double precision</code>
  76       </p>
  77       <p>
  78        Total time spent planning the statement, in milliseconds
  79        (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
  80        otherwise zero)
  81       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  82        <code class="structfield">min_plan_time</code> <code class="type">double precision</code>
  83       </p>
  84       <p>
  85        Minimum time spent planning the statement, in milliseconds.
  86        This field will be zero if <code class="varname">pg_stat_statements.track_planning</code>
  87        is disabled, or if the counter has been reset using the
  88        <code class="function">pg_stat_statements_reset</code> function with the
  89        <code class="structfield">minmax_only</code> parameter set to <code class="literal">true</code>
  90        and never been planned since.
  91       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
  92        <code class="structfield">max_plan_time</code> <code class="type">double precision</code>
  93       </p>
  94       <p>
  95        Maximum time spent planning the statement, in milliseconds.
  96        This field will be zero if <code class="varname">pg_stat_statements.track_planning</code>
  97        is disabled, or if the counter has been reset using the
  98        <code class="function">pg_stat_statements_reset</code> function with the
  99        <code class="structfield">minmax_only</code> parameter set to <code class="literal">true</code>
 100        and never been planned since.
 101       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 102        <code class="structfield">mean_plan_time</code> <code class="type">double precision</code>
 103       </p>
 104       <p>
 105        Mean time spent planning the statement, in milliseconds
 106        (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
 107        otherwise zero)
 108       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 109        <code class="structfield">stddev_plan_time</code> <code class="type">double precision</code>
 110       </p>
 111       <p>
 112        Population standard deviation of time spent planning the statement,
 113        in milliseconds
 114        (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
 115        otherwise zero)
 116       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 117        <code class="structfield">calls</code> <code class="type">bigint</code>
 118       </p>
 119       <p>
 120        Number of times the statement was executed
 121       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 122        <code class="structfield">total_exec_time</code> <code class="type">double precision</code>
 123       </p>
 124       <p>
 125        Total time spent executing the statement, in milliseconds
 126       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 127        <code class="structfield">min_exec_time</code> <code class="type">double precision</code>
 128       </p>
 129       <p>
 130        Minimum time spent executing the statement, in milliseconds,
 131        this field will be zero until this statement
 132        is executed first time after reset performed by the
 133        <code class="function">pg_stat_statements_reset</code> function with the
 134        <code class="structfield">minmax_only</code> parameter set to <code class="literal">true</code>
 135       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 136        <code class="structfield">max_exec_time</code> <code class="type">double precision</code>
 137       </p>
 138       <p>
 139        Maximum time spent executing the statement, in milliseconds,
 140        this field will be zero until this statement
 141        is executed first time after reset performed by the
 142        <code class="function">pg_stat_statements_reset</code> function with the
 143        <code class="structfield">minmax_only</code> parameter set to <code class="literal">true</code>
 144       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 145        <code class="structfield">mean_exec_time</code> <code class="type">double precision</code>
 146       </p>
 147       <p>
 148        Mean time spent executing the statement, in milliseconds
 149       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 150        <code class="structfield">stddev_exec_time</code> <code class="type">double precision</code>
 151       </p>
 152       <p>
 153        Population standard deviation of time spent executing the statement, in milliseconds
 154       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 155        <code class="structfield">rows</code> <code class="type">bigint</code>
 156       </p>
 157       <p>
 158        Total number of rows retrieved or affected by the statement
 159       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 160        <code class="structfield">shared_blks_hit</code> <code class="type">bigint</code>
 161       </p>
 162       <p>
 163        Total number of shared block cache hits by the statement
 164       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 165        <code class="structfield">shared_blks_read</code> <code class="type">bigint</code>
 166       </p>
 167       <p>
 168        Total number of shared blocks read by the statement
 169       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 170        <code class="structfield">shared_blks_dirtied</code> <code class="type">bigint</code>
 171       </p>
 172       <p>
 173        Total number of shared blocks dirtied by the statement
 174       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 175        <code class="structfield">shared_blks_written</code> <code class="type">bigint</code>
 176       </p>
 177       <p>
 178        Total number of shared blocks written by the statement
 179       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 180        <code class="structfield">local_blks_hit</code> <code class="type">bigint</code>
 181       </p>
 182       <p>
 183        Total number of local block cache hits by the statement
 184       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 185        <code class="structfield">local_blks_read</code> <code class="type">bigint</code>
 186       </p>
 187       <p>
 188        Total number of local blocks read by the statement
 189       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 190        <code class="structfield">local_blks_dirtied</code> <code class="type">bigint</code>
 191       </p>
 192       <p>
 193        Total number of local blocks dirtied by the statement
 194       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 195        <code class="structfield">local_blks_written</code> <code class="type">bigint</code>
 196       </p>
 197       <p>
 198        Total number of local blocks written by the statement
 199       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 200        <code class="structfield">temp_blks_read</code> <code class="type">bigint</code>
 201       </p>
 202       <p>
 203        Total number of temp blocks read by the statement
 204       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 205        <code class="structfield">temp_blks_written</code> <code class="type">bigint</code>
 206       </p>
 207       <p>
 208        Total number of temp blocks written by the statement
 209       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 210        <code class="structfield">shared_blk_read_time</code> <code class="type">double precision</code>
 211       </p>
 212       <p>
 213        Total time the statement spent reading shared blocks, in milliseconds
 214        (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
 215       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 216        <code class="structfield">shared_blk_write_time</code> <code class="type">double precision</code>
 217       </p>
 218       <p>
 219        Total time the statement spent writing shared blocks, in milliseconds
 220        (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
 221       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 222        <code class="structfield">local_blk_read_time</code> <code class="type">double precision</code>
 223       </p>
 224       <p>
 225        Total time the statement spent reading local blocks, in milliseconds
 226        (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
 227       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 228        <code class="structfield">local_blk_write_time</code> <code class="type">double precision</code>
 229       </p>
 230       <p>
 231        Total time the statement spent writing local blocks, in milliseconds
 232        (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
 233       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 234        <code class="structfield">temp_blk_read_time</code> <code class="type">double precision</code>
 235       </p>
 236       <p>
 237        Total time the statement spent reading temporary file blocks, in
 238        milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
 239        otherwise zero)
 240       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 241        <code class="structfield">temp_blk_write_time</code> <code class="type">double precision</code>
 242       </p>
 243       <p>
 244        Total time the statement spent writing temporary file blocks, in
 245        milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
 246        otherwise zero)
 247       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 248        <code class="structfield">wal_records</code> <code class="type">bigint</code>
 249       </p>
 250       <p>
 251        Total number of WAL records generated by the statement
 252       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 253        <code class="structfield">wal_fpi</code> <code class="type">bigint</code>
 254       </p>
 255       <p>
 256        Total number of WAL full page images generated by the statement
 257       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 258        <code class="structfield">wal_bytes</code> <code class="type">numeric</code>
 259       </p>
 260       <p>
 261        Total amount of WAL generated by the statement in bytes
 262       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 263        <code class="structfield">wal_buffers_full</code> <code class="type">bigint</code>
 264       </p>
 265       <p>
 266        Number of times the WAL buffers became full
 267       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 268        <code class="structfield">jit_functions</code> <code class="type">bigint</code>
 269       </p>
 270       <p>
 271        Total number of functions JIT-compiled by the statement
 272       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 273        <code class="structfield">jit_generation_time</code> <code class="type">double precision</code>
 274       </p>
 275       <p>
 276        Total time spent by the statement on generating JIT code, in milliseconds
 277       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 278        <code class="structfield">jit_inlining_count</code> <code class="type">bigint</code>
 279       </p>
 280       <p>
 281        Number of times functions have been inlined
 282       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 283        <code class="structfield">jit_inlining_time</code> <code class="type">double precision</code>
 284       </p>
 285       <p>
 286        Total time spent by the statement on inlining functions, in milliseconds
 287       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 288        <code class="structfield">jit_optimization_count</code> <code class="type">bigint</code>
 289       </p>
 290       <p>
 291        Number of times the statement has been optimized
 292       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 293        <code class="structfield">jit_optimization_time</code> <code class="type">double precision</code>
 294       </p>
 295       <p>
 296        Total time spent by the statement on optimizing, in milliseconds
 297       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 298        <code class="structfield">jit_emission_count</code> <code class="type">bigint</code>
 299       </p>
 300       <p>
 301        Number of times code has been emitted
 302       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 303        <code class="structfield">jit_emission_time</code> <code class="type">double precision</code>
 304       </p>
 305       <p>
 306        Total time spent by the statement on emitting code, in milliseconds
 307       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 308        <code class="structfield">jit_deform_count</code> <code class="type">bigint</code>
 309       </p>
 310       <p>
 311        Total number of tuple deform functions JIT-compiled by the statement
 312       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 313        <code class="structfield">jit_deform_time</code> <code class="type">double precision</code>
 314       </p>
 315       <p>
 316        Total time spent by the statement on JIT-compiling tuple deform
 317        functions, in milliseconds
 318       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 319        <code class="structfield">parallel_workers_to_launch</code> <code class="type">bigint</code>
 320       </p>
 321       <p>
 322        Number of parallel workers planned to be launched
 323       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 324        <code class="structfield">parallel_workers_launched</code> <code class="type">bigint</code>
 325       </p>
 326       <p>
 327        Number of parallel workers actually launched
 328       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 329        <code class="structfield">stats_since</code> <code class="type">timestamp with time zone</code>
 330       </p>
 331       <p>
 332        Time at which statistics gathering started for this statement
 333       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 334        <code class="structfield">minmax_stats_since</code> <code class="type">timestamp with time zone</code>
 335       </p>
 336       <p>
 337        Time at which min/max statistics gathering started for this
 338        statement (fields <code class="structfield">min_plan_time</code>,
 339        <code class="structfield">max_plan_time</code>,
 340        <code class="structfield">min_exec_time</code> and
 341        <code class="structfield">max_exec_time</code>)
 342       </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
 343    For security reasons, only superusers and roles with privileges of the
 344    <code class="literal">pg_read_all_stats</code> role are allowed to see the SQL text and
 345    <code class="structfield">queryid</code> of queries executed by other users.
 346    Other users can see the statistics, however, if the view has been installed
 347    in their database.
 348   </p><p>
 349    Plannable queries (that is, <code class="command">SELECT</code>, <code class="command">INSERT</code>,
 350    <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and <code class="command">MERGE</code>)
 351    and utility commands are combined into a single
 352    <code class="structname">pg_stat_statements</code> entry whenever they have identical query
 353    structures according to an internal hash calculation.  Typically, two
 354    queries will be considered the same for this purpose if they are
 355    semantically equivalent except for the values of literal constants
 356    appearing in the query.
 357   </p><div class="note"><h3 class="title">Note</h3><p>
 358     The following details about constant replacement and
 359     <code class="structfield">queryid</code> only apply when <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a> is enabled.  If you use an external
 360     module instead to compute <code class="structfield">queryid</code>, you
 361     should refer to its documentation for details.
 362    </p></div><p>
 363    When a constant's value has been ignored for purposes of matching the query
 364    to other queries, the constant is replaced by a parameter symbol, such
 365    as <code class="literal">$1</code>, in the <code class="structname">pg_stat_statements</code>
 366    display.
 367    The rest of the query text is that of the first query that had the
 368    particular <code class="structfield">queryid</code> hash value associated with the
 369    <code class="structname">pg_stat_statements</code> entry.
 370   </p><p>
 371    Queries on which normalization can be applied may be observed with constant
 372    values in <code class="structname">pg_stat_statements</code>, especially when there
 373    is a high rate of entry deallocations. To reduce the likelihood of this
 374    happening, consider increasing <code class="varname">pg_stat_statements.max</code>.
 375    The <code class="structname">pg_stat_statements_info</code> view, discussed below
 376    in <a class="xref" href="pgstatstatements.html#PGSTATSTATEMENTS-PG-STAT-STATEMENTS-INFO" title="F.32.2. The pg_stat_statements_info View">Section F.32.2</a>,
 377    provides statistics about entry deallocations.
 378   </p><p>
 379    In some cases, queries with visibly different texts might get merged into a
 380    single <code class="structname">pg_stat_statements</code> entry; as explained above,
 381    this is expected to happen for semantically equivalent queries.
 382    In addition, if the only difference between queries is the number of elements
 383    in a list of constants, the list will get squashed down to a single element but shown
 384    with a commented-out list indicator:
 385
 386 </p><pre class="screen">
 387 =# SELECT pg_stat_statements_reset();
 388 =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7);
 389 =# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7, 8);
 390 =# SELECT query, calls FROM pg_stat_statements
 391    WHERE query LIKE 'SELECT%';
 392 -[ RECORD 1 ]------------------------------
 393 query | SELECT * FROM test WHERE a IN ($1 /*, ... */)
 394 calls | 2
 395 </pre><p>
 396
 397    In addition to these cases, there is a small chance of hash collisions
 398    causing unrelated queries to be merged into one entry.
 399    (This cannot happen for queries belonging to different users or databases,
 400    however.)
 401   </p><p>
 402    Since the <code class="structfield">queryid</code> hash value is computed on the
 403    post-parse-analysis representation of the queries, the opposite is
 404    also possible: queries with identical texts might appear as
 405    separate entries, if they have different meanings as a result of
 406    factors such as different <code class="varname">search_path</code> settings.
 407   </p><p>
 408    Consumers of <code class="structname">pg_stat_statements</code> may wish to use
 409    <code class="structfield">queryid</code> (perhaps in combination with
 410    <code class="structfield">dbid</code> and <code class="structfield">userid</code>) as a more stable
 411    and reliable identifier for each entry than its query text.
 412    However, it is important to understand that there are only limited
 413    guarantees around the stability of the <code class="structfield">queryid</code> hash
 414    value.  Since the identifier is derived from the
 415    post-parse-analysis tree, its value is a function of, among other
 416    things, the internal object identifiers appearing in this representation.
 417    This has some counterintuitive implications.  For example,
 418    <code class="filename">pg_stat_statements</code> will consider two apparently-identical
 419    queries to be distinct, if they reference for example a function that was
 420    dropped and recreated between the executions of the two queries.
 421    Conversely, if a table is dropped and recreated between the
 422    executions of queries, two apparently-identical queries may be
 423    considered the same. However, if the alias for a table is different
 424    for otherwise-similar queries, these queries will be considered
 425    distinct.
 426    The hashing process is also sensitive to differences in
 427    machine architecture and other facets of the platform.
 428    Furthermore, it is not safe to assume that <code class="structfield">queryid</code>
 429    will be stable across major versions of <span class="productname">PostgreSQL</span>.
 430   </p><p>
 431    Two servers participating in replication based on physical WAL replay can
 432    be expected to have identical <code class="structfield">queryid</code> values for
 433    the same query.  However, logical replication schemes do not promise to
 434    keep replicas identical in all relevant details, so
 435    <code class="structfield">queryid</code> will not be a useful identifier for
 436    accumulating costs across a set of logical replicas.
 437    If in doubt, direct testing is recommended.
 438   </p><p>
 439    Generally, it can be assumed that <code class="structfield">queryid</code> values
 440    are stable between minor version releases of <span class="productname">PostgreSQL</span>,
 441    providing that instances are running on the same machine architecture and
 442    the catalog metadata details match.  Compatibility will only be broken
 443    between minor versions as a last resort.
 444   </p><p>
 445    The parameter symbols used to replace constants in
 446    representative query texts start from the next number after the
 447    highest <code class="literal">$</code><em class="replaceable"><code>n</code></em> parameter in the original query
 448    text, or <code class="literal">$1</code> if there was none.  It's worth noting that in
 449    some cases there may be hidden parameter symbols that affect this
 450    numbering.  For example, <span class="application">PL/pgSQL</span> uses hidden parameter
 451    symbols to insert values of function local variables into queries, so that
 452    a <span class="application">PL/pgSQL</span> statement like <code class="literal">SELECT i + 1 INTO j</code>
 453    would have representative text like <code class="literal">SELECT i + $2</code>.
 454   </p><p>
 455    The representative query texts are kept in an external disk file, and do
 456    not consume shared memory.  Therefore, even very lengthy query texts can
 457    be stored successfully.  However, if many long query texts are
 458    accumulated, the external file might grow unmanageably large.  As a
 459    recovery method if that happens, <code class="filename">pg_stat_statements</code> may
 460    choose to discard the query texts, whereupon all existing entries in
 461    the <code class="structname">pg_stat_statements</code> view will show
 462    null <code class="structfield">query</code> fields, though the statistics associated with
 463    each <code class="structfield">queryid</code> are preserved.  If this happens, consider
 464    reducing <code class="varname">pg_stat_statements.max</code> to prevent
 465    recurrences.
 466   </p><p>
 467    <code class="structfield">plans</code> and <code class="structfield">calls</code> aren't
 468    always expected to match because planning and execution statistics are
 469    updated at their respective end phase, and only for successful operations.
 470    For example, if a statement is successfully planned but fails during
 471    the execution phase, only its planning statistics will be updated.
 472    If planning is skipped because a cached plan is used, only its execution
 473    statistics will be updated.
 474   </p></div><div class="sect2" id="PGSTATSTATEMENTS-PG-STAT-STATEMENTS-INFO"><div class="titlepage"><div><div><h3 class="title">F.32.2. The <code class="structname">pg_stat_statements_info</code> View <a href="#PGSTATSTATEMENTS-PG-STAT-STATEMENTS-INFO" class="id_link">#</a></h3></div></div></div><a id="id-1.11.7.42.7.2" class="indexterm"></a><p>
 475    The statistics of the <code class="filename">pg_stat_statements</code> module
 476    itself are tracked and made available via a view named
 477    <code class="structname">pg_stat_statements_info</code>.  This view contains
 478    only a single row.  The columns of the view are shown in
 479    <a class="xref" href="pgstatstatements.html#PGSTATSTATEMENTSINFO-COLUMNS" title="Table F.23. pg_stat_statements_info Columns">Table F.23</a>.
 480   </p><div class="table" id="PGSTATSTATEMENTSINFO-COLUMNS"><p class="title"><strong>Table F.23. <code class="structname">pg_stat_statements_info</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stat_statements_info Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
 481        Column Type
 482       </p>
 483       <p>
 484        Description
 485       </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
 486        <code class="structfield">dealloc</code> <code class="type">bigint</code>
 487       </p>
 488       <p>
 489        Total number of times <code class="structname">pg_stat_statements</code>
 490        entries about the least-executed statements were deallocated
 491        because more distinct statements than
 492        <code class="varname">pg_stat_statements.max</code> were observed
 493       </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
 494        <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
 495       </p>
 496       <p>
 497        Time at which all statistics in the
 498        <code class="structname">pg_stat_statements</code> view were last reset.
 499       </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="PGSTATSTATEMENTS-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.32.3. Functions <a href="#PGSTATSTATEMENTS-FUNCS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
 500      <code class="function">pg_stat_statements_reset(userid Oid, dbid Oid, queryid
 501      bigint, minmax_only boolean) returns timestamp with time zone</code>
 502      <a id="id-1.11.7.42.8.2.1.1.2" class="indexterm"></a>
 503     </span></dt><dd><p>
 504       <code class="function">pg_stat_statements_reset</code> discards statistics
 505       gathered so far by <code class="filename">pg_stat_statements</code> corresponding
 506       to the specified <code class="structfield">userid</code>, <code class="structfield">dbid</code>
 507       and <code class="structfield">queryid</code>.  If any of the parameters are not
 508       specified, the default value <code class="literal">0</code>(invalid) is used for
 509       each of them and the statistics that match with other parameters will be
 510       reset.  If no parameter is specified or all the specified parameters are
 511       <code class="literal">0</code>(invalid), it will discard all statistics.
 512       If all statistics in the <code class="filename">pg_stat_statements</code>
 513       view are discarded, it will also reset the statistics in the
 514       <code class="structname">pg_stat_statements_info</code> view.
 515       When <code class="structfield">minmax_only</code> is <code class="literal">true</code> only the
 516       values of minimum and maximum planning and execution time will be reset (i.e.
 517       <code class="structfield">min_plan_time</code>, <code class="structfield">max_plan_time</code>,
 518       <code class="structfield">min_exec_time</code> and <code class="structfield">max_exec_time</code>
 519       fields). The default value for <code class="structfield">minmax_only</code> parameter is
 520       <code class="literal">false</code>. Time of last min/max reset performed is shown in
 521       <code class="structfield">minmax_stats_since</code> field of the
 522       <code class="structname">pg_stat_statements</code> view.
 523       This function returns the time of a reset. This time is saved to
 524       <code class="structfield">stats_reset</code> field of
 525       <code class="structname">pg_stat_statements_info</code> view or to
 526       <code class="structfield">minmax_stats_since</code> field of the
 527       <code class="structname">pg_stat_statements</code> view if the corresponding reset was
 528       actually performed.
 529       By default, this function can only be executed by superusers.
 530       Access may be granted to others using <code class="command">GRANT</code>.
 531      </p></dd><dt><span class="term">
 532      <code class="function">pg_stat_statements(showtext boolean) returns setof record</code>
 533      <a id="id-1.11.7.42.8.2.2.1.2" class="indexterm"></a>
 534     </span></dt><dd><p>
 535       The <code class="structname">pg_stat_statements</code> view is defined in
 536       terms of a function also named <code class="function">pg_stat_statements</code>.
 537       It is possible for clients to call
 538       the <code class="function">pg_stat_statements</code> function directly, and by
 539       specifying <code class="literal">showtext := false</code> have query text be
 540       omitted (that is, the <code class="literal">OUT</code> argument that corresponds
 541       to the view's <code class="structfield">query</code> column will return nulls).  This
 542       feature is intended to support external tools that might wish to avoid
 543       the overhead of repeatedly retrieving query texts of indeterminate
 544       length.  Such tools can instead cache the first query text observed
 545       for each entry themselves, since that is
 546       all <code class="filename">pg_stat_statements</code> itself does, and then retrieve
 547       query texts only as needed.  Since the server stores query texts in a
 548       file, this approach may reduce physical I/O for repeated examination
 549       of the <code class="structname">pg_stat_statements</code> data.
 550      </p></dd></dl></div></div><div class="sect2" id="PGSTATSTATEMENTS-CONFIG-PARAMS"><div class="titlepage"><div><div><h3 class="title">F.32.4. Configuration Parameters <a href="#PGSTATSTATEMENTS-CONFIG-PARAMS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
 551      <code class="varname">pg_stat_statements.max</code> (<code class="type">integer</code>)
 552      <a id="id-1.11.7.42.9.2.1.1.3" class="indexterm"></a>
 553     </span></dt><dd><p>
 554       <code class="varname">pg_stat_statements.max</code> is the maximum number of
 555       statements tracked by the module (i.e., the maximum number of rows
 556       in the <code class="structname">pg_stat_statements</code> view).  If more distinct
 557       statements than that are observed, information about the least-executed
 558       statements is discarded.  The number of times such information was
 559       discarded can be seen in the
 560       <code class="structname">pg_stat_statements_info</code> view.
 561       The default value is 5000.
 562       This parameter can only be set at server start.
 563      </p></dd><dt><span class="term">
 564      <code class="varname">pg_stat_statements.track</code> (<code class="type">enum</code>)
 565      <a id="id-1.11.7.42.9.2.2.1.3" class="indexterm"></a>
 566     </span></dt><dd><p>
 567       <code class="varname">pg_stat_statements.track</code> controls which statements
 568       are counted by the module.
 569       Specify <code class="literal">top</code> to track top-level statements (those issued
 570       directly by clients), <code class="literal">all</code> to also track nested statements
 571       (such as statements invoked within functions), or <code class="literal">none</code> to
 572       disable statement statistics collection.
 573       The default value is <code class="literal">top</code>.
 574       Only superusers can change this setting.
 575      </p></dd><dt><span class="term">
 576      <code class="varname">pg_stat_statements.track_utility</code> (<code class="type">boolean</code>)
 577      <a id="id-1.11.7.42.9.2.3.1.3" class="indexterm"></a>
 578     </span></dt><dd><p>
 579       <code class="varname">pg_stat_statements.track_utility</code> controls whether
 580       utility commands are tracked by the module.  Utility commands are
 581       all those other than <code class="command">SELECT</code>, <code class="command">INSERT</code>,
 582       <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and <code class="command">MERGE</code>.
 583       The default value is <code class="literal">on</code>.
 584       Only superusers can change this setting.
 585      </p></dd><dt><span class="term">
 586      <code class="varname">pg_stat_statements.track_planning</code> (<code class="type">boolean</code>)
 587      <a id="id-1.11.7.42.9.2.4.1.3" class="indexterm"></a>
 588     </span></dt><dd><p>
 589       <code class="varname">pg_stat_statements.track_planning</code> controls whether
 590       planning operations and duration are tracked by the module.
 591       Enabling this parameter may incur a noticeable performance penalty,
 592       especially when statements with identical query structure are executed
 593       by many concurrent connections which compete to update a small number of
 594       <code class="structname">pg_stat_statements</code> entries.
 595       The default value is <code class="literal">off</code>.
 596       Only superusers can change this setting.
 597      </p></dd><dt><span class="term">
 598      <code class="varname">pg_stat_statements.save</code> (<code class="type">boolean</code>)
 599      <a id="id-1.11.7.42.9.2.5.1.3" class="indexterm"></a>
 600     </span></dt><dd><p>
 601       <code class="varname">pg_stat_statements.save</code> specifies whether to
 602       save statement statistics across server shutdowns.
 603       If it is <code class="literal">off</code> then statistics are not saved at
 604       shutdown nor reloaded at server start.
 605       The default value is <code class="literal">on</code>.
 606       This parameter can only be set in the <code class="filename">postgresql.conf</code>
 607       file or on the server command line.
 608      </p></dd></dl></div><p>
 609    The module requires additional shared memory proportional to
 610    <code class="varname">pg_stat_statements.max</code>.  Note that this
 611    memory is consumed whenever the module is loaded, even if
 612    <code class="varname">pg_stat_statements.track</code> is set to <code class="literal">none</code>.
 613   </p><p>
 614    These parameters must be set in <code class="filename">postgresql.conf</code>.
 615    Typical usage might be:
 616
 617 </p><pre class="programlisting">
 618 # postgresql.conf
 619 shared_preload_libraries = 'pg_stat_statements'
 620
 621 compute_query_id = on
 622 pg_stat_statements.max = 10000
 623 pg_stat_statements.track = all
 624 </pre><p>
 625   </p></div><div class="sect2" id="PGSTATSTATEMENTS-SAMPLE-OUTPUT"><div class="titlepage"><div><div><h3 class="title">F.32.5. Sample Output <a href="#PGSTATSTATEMENTS-SAMPLE-OUTPUT" class="id_link">#</a></h3></div></div></div><pre class="screen">
 626 bench=# SELECT pg_stat_statements_reset();
 627
 628 $ pgbench -i bench
 629 $ pgbench -c10 -t300 bench
 630
 631 bench=# \x
 632 bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
 633                nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
 634           FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
 635 -[ RECORD 1 ]---+--------------------------------------------------------------------
 636 query           | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2
 637 calls           | 3000
 638 total_exec_time | 25565.855387
 639 rows            | 3000
 640 hit_percent     | 100.0000000000000000
 641 -[ RECORD 2 ]---+--------------------------------------------------------------------
 642 query           | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
 643 calls           | 3000
 644 total_exec_time | 20756.669379
 645 rows            | 3000
 646 hit_percent     | 100.0000000000000000
 647 -[ RECORD 3 ]---+--------------------------------------------------------------------
 648 query           | copy pgbench_accounts from stdin
 649 calls           | 1
 650 total_exec_time | 291.865911
 651 rows            | 100000
 652 hit_percent     | 100.0000000000000000
 653 -[ RECORD 4 ]---+--------------------------------------------------------------------
 654 query           | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
 655 calls           | 3000
 656 total_exec_time | 271.232977
 657 rows            | 3000
 658 hit_percent     | 98.8454011741682975
 659 -[ RECORD 5 ]---+--------------------------------------------------------------------
 660 query           | alter table pgbench_accounts add primary key (aid)
 661 calls           | 1
 662 total_exec_time | 160.588563
 663 rows            | 0
 664 hit_percent     | 100.0000000000000000
 665
 666
 667 bench=# SELECT pg_stat_statements_reset(0,0,s.queryid) FROM pg_stat_statements AS s
 668             WHERE s.query = 'UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2';
 669
 670 bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
 671                nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
 672           FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
 673 -[ RECORD 1 ]---+--------------------------------------------------------------------
 674 query           | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
 675 calls           | 3000
 676 total_exec_time | 20756.669379
 677 rows            | 3000
 678 hit_percent     | 100.0000000000000000
 679 -[ RECORD 2 ]---+--------------------------------------------------------------------
 680 query           | copy pgbench_accounts from stdin
 681 calls           | 1
 682 total_exec_time | 291.865911
 683 rows            | 100000
 684 hit_percent     | 100.0000000000000000
 685 -[ RECORD 3 ]---+--------------------------------------------------------------------
 686 query           | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
 687 calls           | 3000
 688 total_exec_time | 271.232977
 689 rows            | 3000
 690 hit_percent     | 98.8454011741682975
 691 -[ RECORD 4 ]---+--------------------------------------------------------------------
 692 query           | alter table pgbench_accounts add primary key (aid)
 693 calls           | 1
 694 total_exec_time | 160.588563
 695 rows            | 0
 696 hit_percent     | 100.0000000000000000
 697 -[ RECORD 5 ]---+--------------------------------------------------------------------
 698 query           | vacuum analyze pgbench_accounts
 699 calls           | 1
 700 total_exec_time | 136.448116
 701 rows            | 0
 702 hit_percent     | 99.9201915403032721
 703
 704 bench=# SELECT pg_stat_statements_reset(0,0,0);
 705
 706 bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
 707                nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
 708           FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
 709 -[ RECORD 1 ]---+-----------------------------------------------------------------------------
 710 query           | SELECT pg_stat_statements_reset(0,0,0)
 711 calls           | 1
 712 total_exec_time | 0.189497
 713 rows            | 1
 714 hit_percent     |
 715 -[ RECORD 2 ]---+-----------------------------------------------------------------------------
 716 query           | SELECT query, calls, total_exec_time, rows, $1 * shared_blks_hit /          +
 717                 |                nullif(shared_blks_hit + shared_blks_read, $2) AS hit_percent+
 718                 |           FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT $3
 719 calls           | 0
 720 total_exec_time | 0
 721 rows            | 0
 722 hit_percent     |
 723
 724 </pre></div><div class="sect2" id="PGSTATSTATEMENTS-AUTHORS"><div class="titlepage"><div><div><h3 class="title">F.32.6. Authors <a href="#PGSTATSTATEMENTS-AUTHORS" class="id_link">#</a></h3></div></div></div><p>
 725    Takahiro Itagaki <code class="email">&lt;<a class="email" href="mailto:itagaki.takahiro@oss.ntt.co.jp">itagaki.takahiro@oss.ntt.co.jp</a>&gt;</code>.
 726    Query normalization added by Peter Geoghegan <code class="email">&lt;<a class="email" href="mailto:peter@2ndquadrant.com">peter@2ndquadrant.com</a>&gt;</code>.
 727   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgstattuple.html" title="F.33. pgstattuple — obtain tuple-level statistics">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.31. pgrowlocks — show a table's row locking information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.33. pgstattuple — obtain tuple-level statistics</td></tr></table></div></body></html>