begriffs open source - ai-pg/blob - full-docs/txt/pgstattuple.txt

   1
   2 F.33. pgstattuple — obtain tuple-level statistics #
   3
   4    F.33.1. Functions
   5    F.33.2. Authors
   6
   7    The pgstattuple module provides various functions to obtain tuple-level
   8    statistics.
   9
  10    Because these functions return detailed page-level information, access
  11    is restricted by default. By default, only the role pg_stat_scan_tables
  12    has EXECUTE privilege. Superusers of course bypass this restriction.
  13    After the extension has been installed, users may issue GRANT commands
  14    to change the privileges on the functions to allow others to execute
  15    them. However, it might be preferable to add those users to the
  16    pg_stat_scan_tables role instead.
  17
  18 F.33.1. Functions #
  19
  20    pgstattuple(regclass) returns record
  21           pgstattuple returns a relation's physical length, percentage of
  22           “dead” tuples, and other info. This may help users to determine
  23           whether vacuum is necessary or not. The argument is the target
  24           relation's name (optionally schema-qualified) or OID. For
  25           example:
  26
  27 test=> SELECT * FROM pgstattuple('pg_catalog.pg_proc');
  28 -[ RECORD 1 ]------+-------
  29 table_len          | 458752
  30 tuple_count        | 1470
  31 tuple_len          | 438896
  32 tuple_percent      | 95.67
  33 dead_tuple_count   | 11
  34 dead_tuple_len     | 3157
  35 dead_tuple_percent | 0.69
  36 free_space         | 8932
  37 free_percent       | 1.95
  38
  39           The output columns are described in Table F.24.
  40
  41           Table F.24. pgstattuple Output Columns
  42
  43                 Column        Type              Description
  44           table_len          bigint Physical relation length in bytes
  45           tuple_count        bigint Number of live tuples
  46           tuple_len          bigint Total length of live tuples in bytes
  47           tuple_percent      float8 Percentage of live tuples
  48           dead_tuple_count   bigint Number of dead tuples
  49           dead_tuple_len     bigint Total length of dead tuples in bytes
  50           dead_tuple_percent float8 Percentage of dead tuples
  51           free_space         bigint Total free space in bytes
  52           free_percent       float8 Percentage of free space
  53
  54 Note
  55
  56           The table_len will always be greater than the sum of the
  57           tuple_len, dead_tuple_len and free_space. The difference is
  58           accounted for by fixed page overhead, the per-page table of
  59           pointers to tuples, and padding to ensure that tuples are
  60           correctly aligned.
  61
  62           pgstattuple acquires only a read lock on the relation. So the
  63           results do not reflect an instantaneous snapshot; concurrent
  64           updates will affect them.
  65
  66           pgstattuple judges a tuple is “dead” if HeapTupleSatisfiesDirty
  67           returns false.
  68
  69    pgstattuple(text) returns record
  70           This is the same as pgstattuple(regclass), except that the
  71           target relation is specified as TEXT. This function is kept
  72           because of backward-compatibility so far, and will be deprecated
  73           in some future release.
  74
  75    pgstatindex(regclass) returns record
  76           pgstatindex returns a record showing information about a B-tree
  77           index. For example:
  78
  79 test=> SELECT * FROM pgstatindex('pg_cast_oid_index');
  80 -[ RECORD 1 ]------+------
  81 version            | 2
  82 tree_level         | 0
  83 index_size         | 16384
  84 root_block_no      | 1
  85 internal_pages     | 0
  86 leaf_pages         | 1
  87 empty_pages        | 0
  88 deleted_pages      | 0
  89 avg_leaf_density   | 54.27
  90 leaf_fragmentation | 0
  91
  92           The output columns are:
  93
  94                 Column        Type                 Description
  95           version            integer B-tree version number
  96           tree_level         integer Tree level of the root page
  97           index_size         bigint  Total index size in bytes
  98           root_block_no      bigint  Location of root page (zero if none)
  99           internal_pages     bigint  Number of “internal” (upper-level) pages
 100           leaf_pages         bigint  Number of leaf pages
 101           empty_pages        bigint  Number of empty pages
 102           deleted_pages      bigint  Number of deleted pages
 103           avg_leaf_density   float8  Average density of leaf pages
 104           leaf_fragmentation float8  Leaf page fragmentation
 105
 106           The reported index_size will normally correspond to one more
 107           page than is accounted for by internal_pages + leaf_pages +
 108           empty_pages + deleted_pages, because it also includes the
 109           index's metapage.
 110
 111           As with pgstattuple, the results are accumulated page-by-page,
 112           and should not be expected to represent an instantaneous
 113           snapshot of the whole index.
 114
 115    pgstatindex(text) returns record
 116           This is the same as pgstatindex(regclass), except that the
 117           target index is specified as TEXT. This function is kept because
 118           of backward-compatibility so far, and will be deprecated in some
 119           future release.
 120
 121    pgstatginindex(regclass) returns record
 122           pgstatginindex returns a record showing information about a GIN
 123           index. For example:
 124
 125 test=> SELECT * FROM pgstatginindex('test_gin_index');
 126 -[ RECORD 1 ]--+--
 127 version        | 1
 128 pending_pages  | 0
 129 pending_tuples | 0
 130
 131           The output columns are:
 132
 133               Column      Type               Description
 134           version        integer GIN version number
 135           pending_pages  integer Number of pages in the pending list
 136           pending_tuples bigint  Number of tuples in the pending list
 137
 138    pgstathashindex(regclass) returns record
 139           pgstathashindex returns a record showing information about a
 140           HASH index. For example:
 141
 142 test=> select * from pgstathashindex('con_hash_index');
 143 -[ RECORD 1 ]--+-----------------
 144 version        | 4
 145 bucket_pages   | 33081
 146 overflow_pages | 0
 147 bitmap_pages   | 1
 148 unused_pages   | 32455
 149 live_items     | 10204006
 150 dead_items     | 0
 151 free_percent   | 61.8005949100872
 152
 153           The output columns are:
 154
 155               Column      Type         Description
 156           version        integer HASH version number
 157           bucket_pages   bigint  Number of bucket pages
 158           overflow_pages bigint  Number of overflow pages
 159           bitmap_pages   bigint  Number of bitmap pages
 160           unused_pages   bigint  Number of unused pages
 161           live_items     bigint  Number of live tuples
 162           dead_tuples    bigint  Number of dead tuples
 163           free_percent   float   Percentage of free space
 164
 165    pg_relpages(regclass) returns bigint
 166           pg_relpages returns the number of pages in the relation.
 167
 168    pg_relpages(text) returns bigint
 169           This is the same as pg_relpages(regclass), except that the
 170           target relation is specified as TEXT. This function is kept
 171           because of backward-compatibility so far, and will be deprecated
 172           in some future release.
 173
 174    pgstattuple_approx(regclass) returns record
 175           pgstattuple_approx is a faster alternative to pgstattuple that
 176           returns approximate results. The argument is the target
 177           relation's name or OID. For example:
 178
 179 test=> SELECT * FROM pgstattuple_approx('pg_catalog.pg_proc'::regclass);
 180 -[ RECORD 1 ]--------+-------
 181 table_len            | 573440
 182 scanned_percent      | 2
 183 approx_tuple_count   | 2740
 184 approx_tuple_len     | 561210
 185 approx_tuple_percent | 97.87
 186 dead_tuple_count     | 0
 187 dead_tuple_len       | 0
 188 dead_tuple_percent   | 0
 189 approx_free_space    | 11996
 190 approx_free_percent  | 2.09
 191
 192           The output columns are described in Table F.25.
 193
 194           Whereas pgstattuple always performs a full-table scan and
 195           returns an exact count of live and dead tuples (and their sizes)
 196           and free space, pgstattuple_approx tries to avoid the full-table
 197           scan and returns exact dead tuple statistics along with an
 198           approximation of the number and size of live tuples and free
 199           space.
 200
 201           It does this by skipping pages that have only visible tuples
 202           according to the visibility map (if a page has the corresponding
 203           VM bit set, then it is assumed to contain no dead tuples). For
 204           such pages, it derives the free space value from the free space
 205           map, and assumes that the rest of the space on the page is taken
 206           up by live tuples.
 207
 208           For pages that cannot be skipped, it scans each tuple, recording
 209           its presence and size in the appropriate counters, and adding up
 210           the free space on the page. At the end, it estimates the total
 211           number of live tuples based on the number of pages and tuples
 212           scanned (in the same way that VACUUM estimates
 213           pg_class.reltuples).
 214
 215           Table F.25. pgstattuple_approx Output Columns
 216
 217    Column Type Description
 218    table_len bigint Physical relation length in bytes (exact)
 219    scanned_percent float8 Percentage of table scanned
 220    approx_tuple_count bigint Number of live tuples (estimated)
 221    approx_tuple_len bigint Total length of live tuples in bytes
 222    (estimated)
 223    approx_tuple_percent float8 Percentage of live tuples
 224    dead_tuple_count bigint Number of dead tuples (exact)
 225    dead_tuple_len bigint Total length of dead tuples in bytes (exact)
 226    dead_tuple_percent float8 Percentage of dead tuples
 227    approx_free_space bigint Total free space in bytes (estimated)
 228    approx_free_percent float8 Percentage of free space
 229
 230           In the above output, the free space figures may not match the
 231           pgstattuple output exactly, because the free space map gives us
 232           an exact figure, but is not guaranteed to be accurate to the
 233           byte.
 234
 235 F.33.2. Authors #
 236
 237    Tatsuo Ishii, Satoshi Nagayasu and Abhijit Menon-Sen