Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
pgstattuple.html199 linesDownload Raw Back to 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.33. pgstattuple — obtain tuple-level statistics</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="pgstatstatements.html" title="F.32. pg_stat_statements — track statistics of SQL planning and execution" /><link rel="next" href="pgsurgery.html" title="F.34. pg_surgery — perform low-level surgery on relation data" /></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.33. pgstattuple — obtain tuple-level statistics</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgstatstatements.html" title="F.32. pg_stat_statements — track statistics of SQL planning and execution">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 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgsurgery.html" title="F.34. pg_surgery — perform low-level surgery on relation data">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGSTATTUPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.33. pgstattuple — obtain tuple-level statistics <a href="#PGSTATTUPLE" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgstattuple.html#PGSTATTUPLE-FUNCS">F.33.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgstattuple.html#PGSTATTUPLE-AUTHORS">F.33.2. Authors</a></span></dt></dl></div><a id="id-1.11.7.43.2" class="indexterm"></a><p>3  The <code class="filename">pgstattuple</code> module provides various functions to4  obtain tuple-level statistics.5 </p><p>6  Because these functions return detailed page-level information, access is7  restricted by default.  By default, only the8  role <code class="literal">pg_stat_scan_tables</code> has <code class="literal">EXECUTE</code>9  privilege.  Superusers of course bypass this restriction.  After the10  extension has been installed, users may issue <code class="command">GRANT</code>11  commands to change the privileges on the functions to allow others to12  execute them.  However, it might be preferable to add those users to13  the <code class="literal">pg_stat_scan_tables</code> role instead.14 </p><div class="sect2" id="PGSTATTUPLE-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.33.1. Functions <a href="#PGSTATTUPLE-FUNCS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">15     <a id="id-1.11.7.43.5.2.1.1.1" class="indexterm"></a>16     <code class="function">pgstattuple(regclass) returns record</code>17    </span></dt><dd><p>18      <code class="function">pgstattuple</code> returns a relation's physical length,19      percentage of <span class="quote">“<span class="quote">dead</span>”</span> tuples, and other info. This may help users20      to determine whether vacuum is necessary or not.  The argument is the21      target relation's name (optionally schema-qualified) or OID.22      For example:23</p><pre class="programlisting">24test=&gt; SELECT * FROM pgstattuple('pg_catalog.pg_proc');25-[ RECORD 1 ]------+-------26table_len          | 45875227tuple_count        | 147028tuple_len          | 43889629tuple_percent      | 95.6730dead_tuple_count   | 1131dead_tuple_len     | 315732dead_tuple_percent | 0.6933free_space         | 893234free_percent       | 1.9535</pre><p>36     The output columns are described in <a class="xref" href="pgstattuple.html#PGSTATTUPLE-COLUMNS" title="Table F.24. pgstattuple Output Columns">Table F.24</a>.37    </p><div class="table" id="PGSTATTUPLE-COLUMNS"><p class="title"><strong>Table F.24. <code class="function">pgstattuple</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pgstattuple Output Columns" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">table_len</code></td><td><code class="type">bigint</code></td><td>Physical relation length in bytes</td></tr><tr><td><code class="structfield">tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of live tuples</td></tr><tr><td><code class="structfield">tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of live tuples in bytes</td></tr><tr><td><code class="structfield">tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of live tuples</td></tr><tr><td><code class="structfield">dead_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples</td></tr><tr><td><code class="structfield">dead_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of dead tuples in bytes</td></tr><tr><td><code class="structfield">dead_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of dead tuples</td></tr><tr><td><code class="structfield">free_space</code></td><td><code class="type">bigint</code></td><td>Total free space in bytes</td></tr><tr><td><code class="structfield">free_percent</code></td><td><code class="type">float8</code></td><td>Percentage of free space</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>38      The <code class="literal">table_len</code> will always be greater than the sum39      of the <code class="literal">tuple_len</code>, <code class="literal">dead_tuple_len</code>40      and <code class="literal">free_space</code>. The difference is accounted for by41      fixed page overhead, the per-page table of pointers to tuples, and42      padding to ensure that tuples are correctly aligned.43     </p></div><p>44     <code class="function">pgstattuple</code> acquires only a read lock on the45     relation. So the results do not reflect an instantaneous snapshot;46     concurrent updates will affect them.47    </p><p>48     <code class="function">pgstattuple</code> judges a tuple is <span class="quote">“<span class="quote">dead</span>”</span> if49     <code class="function">HeapTupleSatisfiesDirty</code> returns false.50    </p></dd><dt><span class="term">51     <code class="function">pgstattuple(text) returns record</code>52    </span></dt><dd><p>53      This is the same as <code class="function">pgstattuple(regclass)</code>, except54      that the target relation is specified as TEXT. This function is kept55      because of backward-compatibility so far, and will be deprecated in56      some future release.57     </p></dd><dt><span class="term">58    <a id="id-1.11.7.43.5.2.3.1.1" class="indexterm"></a>59     <code class="function">pgstatindex(regclass) returns record</code>60    </span></dt><dd><p>61      <code class="function">pgstatindex</code> returns a record showing information62      about a B-tree index.  For example:63</p><pre class="programlisting">64test=&gt; SELECT * FROM pgstatindex('pg_cast_oid_index');65-[ RECORD 1 ]------+------66version            | 267tree_level         | 068index_size         | 1638469root_block_no      | 170internal_pages     | 071leaf_pages         | 172empty_pages        | 073deleted_pages      | 074avg_leaf_density   | 54.2775leaf_fragmentation | 076</pre><p>77     </p><p>78     The output columns are:79 80    </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>B-tree version number</td></tr><tr><td><code class="structfield">tree_level</code></td><td><code class="type">integer</code></td><td>Tree level of the root page</td></tr><tr><td><code class="structfield">index_size</code></td><td><code class="type">bigint</code></td><td>Total index size in bytes</td></tr><tr><td><code class="structfield">root_block_no</code></td><td><code class="type">bigint</code></td><td>Location of root page (zero if none)</td></tr><tr><td><code class="structfield">internal_pages</code></td><td><code class="type">bigint</code></td><td>Number of <span class="quote">“<span class="quote">internal</span>”</span> (upper-level) pages</td></tr><tr><td><code class="structfield">leaf_pages</code></td><td><code class="type">bigint</code></td><td>Number of leaf pages</td></tr><tr><td><code class="structfield">empty_pages</code></td><td><code class="type">bigint</code></td><td>Number of empty pages</td></tr><tr><td><code class="structfield">deleted_pages</code></td><td><code class="type">bigint</code></td><td>Number of deleted pages</td></tr><tr><td><code class="structfield">avg_leaf_density</code></td><td><code class="type">float8</code></td><td>Average density of leaf pages</td></tr><tr><td><code class="structfield">leaf_fragmentation</code></td><td><code class="type">float8</code></td><td>Leaf page fragmentation</td></tr></tbody></table></div><p>81    </p><p>82     The reported <code class="literal">index_size</code> will normally correspond to one more83     page than is accounted for by <code class="literal">internal_pages + leaf_pages +84     empty_pages + deleted_pages</code>, because it also includes the85     index's metapage.86    </p><p>87     As with <code class="function">pgstattuple</code>, the results are accumulated88     page-by-page, and should not be expected to represent an89     instantaneous snapshot of the whole index.90    </p></dd><dt><span class="term">91     <code class="function">pgstatindex(text) returns record</code>92    </span></dt><dd><p>93      This is the same as <code class="function">pgstatindex(regclass)</code>, except94      that the target index is specified as TEXT. This function is kept95      because of backward-compatibility so far, and will be deprecated in96      some future release.97     </p></dd><dt><span class="term">98     <a id="id-1.11.7.43.5.2.5.1.1" class="indexterm"></a>99     <code class="function">pgstatginindex(regclass) returns record</code>100    </span></dt><dd><p>101      <code class="function">pgstatginindex</code> returns a record showing information102      about a GIN index.  For example:103</p><pre class="programlisting">104test=&gt; SELECT * FROM pgstatginindex('test_gin_index');105-[ RECORD 1 ]--+--106version        | 1107pending_pages  | 0108pending_tuples | 0109</pre><p>110     </p><p>111     The output columns are:112 113    </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>GIN version number</td></tr><tr><td><code class="structfield">pending_pages</code></td><td><code class="type">integer</code></td><td>Number of pages in the pending list</td></tr><tr><td><code class="structfield">pending_tuples</code></td><td><code class="type">bigint</code></td><td>Number of tuples in the pending list</td></tr></tbody></table></div><p>114    </p></dd><dt><span class="term">115     <a id="id-1.11.7.43.5.2.6.1.1" class="indexterm"></a>116     <code class="function">pgstathashindex(regclass) returns record</code>117    </span></dt><dd><p>118      <code class="function">pgstathashindex</code> returns a record showing information119      about a HASH index.  For example:120</p><pre class="programlisting">121test=&gt; select * from pgstathashindex('con_hash_index');122-[ RECORD 1 ]--+-----------------123version        | 4124bucket_pages   | 33081125overflow_pages | 0126bitmap_pages   | 1127unused_pages   | 32455128live_items     | 10204006129dead_items     | 0130free_percent   | 61.8005949100872131</pre><p>132     </p><p>133     The output columns are:134 135    </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>HASH version number</td></tr><tr><td><code class="structfield">bucket_pages</code></td><td><code class="type">bigint</code></td><td>Number of bucket pages</td></tr><tr><td><code class="structfield">overflow_pages</code></td><td><code class="type">bigint</code></td><td>Number of overflow pages</td></tr><tr><td><code class="structfield">bitmap_pages</code></td><td><code class="type">bigint</code></td><td>Number of bitmap pages</td></tr><tr><td><code class="structfield">unused_pages</code></td><td><code class="type">bigint</code></td><td>Number of unused pages</td></tr><tr><td><code class="structfield">live_items</code></td><td><code class="type">bigint</code></td><td>Number of live tuples</td></tr><tr><td><code class="structfield">dead_tuples</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples</td></tr><tr><td><code class="structfield">free_percent</code></td><td><code class="type">float</code></td><td>Percentage of free space</td></tr></tbody></table></div><p>136    </p></dd><dt><span class="term">137     <a id="id-1.11.7.43.5.2.7.1.1" class="indexterm"></a>138     <code class="function">pg_relpages(regclass) returns bigint</code>139    </span></dt><dd><p>140      <code class="function">pg_relpages</code> returns the number of pages in the141      relation.142     </p></dd><dt><span class="term">143     <code class="function">pg_relpages(text) returns bigint</code>144    </span></dt><dd><p>145      This is the same as <code class="function">pg_relpages(regclass)</code>, except146      that the target relation is specified as TEXT. This function is kept147      because of backward-compatibility so far, and will be deprecated in148      some future release.149     </p></dd><dt><span class="term">150     <a id="id-1.11.7.43.5.2.9.1.1" class="indexterm"></a>151     <code class="function">pgstattuple_approx(regclass) returns record</code>152    </span></dt><dd><p>153      <code class="function">pgstattuple_approx</code> is a faster alternative to154      <code class="function">pgstattuple</code> that returns approximate results.155      The argument is the target relation's name or OID.156      For example:157</p><pre class="programlisting">158test=&gt; SELECT * FROM pgstattuple_approx('pg_catalog.pg_proc'::regclass);159-[ RECORD 1 ]--------+-------160table_len            | 573440161scanned_percent      | 2162approx_tuple_count   | 2740163approx_tuple_len     | 561210164approx_tuple_percent | 97.87165dead_tuple_count     | 0166dead_tuple_len       | 0167dead_tuple_percent   | 0168approx_free_space    | 11996169approx_free_percent  | 2.09170</pre><p>171      The output columns are described in <a class="xref" href="pgstattuple.html#PGSTATAPPROX-COLUMNS" title="Table F.25. pgstattuple_approx Output Columns">Table F.25</a>.172     </p><p>173      Whereas <code class="function">pgstattuple</code> always performs a174      full-table scan and returns an exact count of live and dead tuples175      (and their sizes) and free space, <code class="function">pgstattuple_approx</code>176      tries to avoid the full-table scan and returns exact dead tuple177      statistics along with an approximation of the number and178      size of live tuples and free space.179     </p><p>180      It does this by skipping pages that have only visible tuples181      according to the visibility map (if a page has the corresponding VM182      bit set, then it is assumed to contain no dead tuples). For such183      pages, it derives the free space value from the free space map, and184      assumes that the rest of the space on the page is taken up by live185      tuples.186     </p><p>187      For pages that cannot be skipped, it scans each tuple, recording its188      presence and size in the appropriate counters, and adding up the189      free space on the page. At the end, it estimates the total number of190      live tuples based on the number of pages and tuples scanned (in the191      same way that VACUUM estimates pg_class.reltuples).192     </p><div class="table" id="PGSTATAPPROX-COLUMNS"><p class="title"><strong>Table F.25. <code class="function">pgstattuple_approx</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pgstattuple_approx Output Columns" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">table_len</code></td><td><code class="type">bigint</code></td><td>Physical relation length in bytes (exact)</td></tr><tr><td><code class="structfield">scanned_percent</code></td><td><code class="type">float8</code></td><td>Percentage of table scanned</td></tr><tr><td><code class="structfield">approx_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of live tuples (estimated)</td></tr><tr><td><code class="structfield">approx_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of live tuples in bytes (estimated)</td></tr><tr><td><code class="structfield">approx_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of live tuples</td></tr><tr><td><code class="structfield">dead_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples (exact)</td></tr><tr><td><code class="structfield">dead_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of dead tuples in bytes (exact)</td></tr><tr><td><code class="structfield">dead_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of dead tuples</td></tr><tr><td><code class="structfield">approx_free_space</code></td><td><code class="type">bigint</code></td><td>Total free space in bytes (estimated)</td></tr><tr><td><code class="structfield">approx_free_percent</code></td><td><code class="type">float8</code></td><td>Percentage of free space</td></tr></tbody></table></div></div><br class="table-break" /><p>193      In the above output, the free space figures may not match the194      <code class="function">pgstattuple</code> output exactly, because the free195      space map gives us an exact figure, but is not guaranteed to be196      accurate to the byte.197     </p></dd></dl></div></div><div class="sect2" id="PGSTATTUPLE-AUTHORS"><div class="titlepage"><div><div><h3 class="title">F.33.2. Authors <a href="#PGSTATTUPLE-AUTHORS" class="id_link">#</a></h3></div></div></div><p>198   Tatsuo Ishii, Satoshi Nagayasu and Abhijit Menon-Sen199  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgstatstatements.html" title="F.32. pg_stat_statements — track statistics of SQL planning and execution">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="pgsurgery.html" title="F.34. pg_surgery — perform low-level surgery on relation data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.32. pg_stat_statements — track statistics of SQL planning and execution </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.34. pg_surgery — perform low-level surgery on relation data</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai