README.gevel

   1 Gevel contrib module provides several functions useful for analyzing GiST and GIN index.
   2
   3 [Online version] of this document (http://www.sai.msu.su/~megera/oddmuse/index.cgi/Gevel)
   4
   5 Caution: This module was designed for advanced users of GIN, GiST and SP-GiST indices !
   6
   7 Authors
   8
   9     * Oleg Bartunov <oleg@sai.msu.su>, Moscow, Moscow University, Russia
  10     * Teodor Sigaev <teodor@sigaev.ru>, Moscow, Moscow University, Russia
  11
  12 License
  13
  14 Stable version, included into PostgreSQL distribution, released under
  15 BSD license. Development version, available from this site, released under
  16 the GNU General Public License, version 2 (June 1991)
  17
  18 Install gevel module (requires 8.1+ version):
  19 % cd PGSQLSRC/contrib
  20 % tar xzvf gevel.tar.gz
  21 % make
  22 % make install
  23 % make installcheck
  24 % psql regression < gevel.sql
  25
  26     * gist_stat(INDEXNAME) - show some statistics about GiST tree
  27
  28 regression=# select gist_stat('pix');
  29  Number of levels:          2
  30 Number of pages:           30
  31 Number of leaf pages:      29
  32 Number of tuples:          3129
  33 Number of leaf tuples:     3100
  34 Total size of tuples:      137676 bytes
  35 Total size of leaf tuples: 136400 bytes
  36 Total size of index:       245760 bytes
  37
  38     * gist_tree(INDEXNAME[,MAXLEVEL]) - show GiST tree up to MAXLEVEL
  39
  40 regression=# select gist_tree('pix',0);
  41  0(l:0) blk: 0 numTuple: 29 free: 6888b(15.63%)
  42
  43 Designation (from left to right):
  44
  45           o 0 - page number
  46           o (l:0) - tree level
  47           o blk: 0 - block number
  48           o numTuple: 29 - the number of tuples
  49           o free: 6888b - free space in bytes
  50           o (15.63%) - occupied space in percents
  51
  52     * gist_tree(INDEXNAME) - show full GiST tree
  53
  54 regression=# select gist_tree('pix');
  55  0(l:0) blk: 0 numTuple: 29 free: 6888b(15.63%)
  56     1(l:1) blk: 13 numTuple: 180 free: 244b(97.01%)
  57     2(l:1) blk: 11 numTuple: 175 free: 464b(94.32%)
  58     3(l:1) blk: 2 numTuple: 101 free: 3720b(54.43%)
  59     4(l:1) blk: 17 numTuple: 111 free: 3280b(59.82%)
  60     5(l:1) blk: 18 numTuple: 101 free: 3720b(54.43%)
  61     6(l:1) blk: 10 numTuple: 98 free: 3852b(52.82%)
  62     7(l:1) blk: 19 numTuple: 111 free: 3280b(59.82%)
  63     8(l:1) blk: 9 numTuple: 97 free: 3896b(52.28%)
  64     9(l:1) blk: 20 numTuple: 104 free: 3588b(56.05%)
  65     10(l:1) blk: 14 numTuple: 96 free: 3940b(51.74%)
  66     11(l:1) blk: 21 numTuple: 106 free: 3500b(57.13%)
  67     12(l:1) blk: 7 numTuple: 103 free: 3632b(55.51%)
  68     13(l:1) blk: 1 numTuple: 101 free: 3720b(54.43%)
  69     14(l:1) blk: 16 numTuple: 97 free: 3896b(52.28%)
  70     15(l:1) blk: 24 numTuple: 103 free: 3632b(55.51%)
  71     16(l:1) blk: 4 numTuple: 98 free: 3852b(52.82%)
  72     17(l:1) blk: 25 numTuple: 98 free: 3852b(52.82%)
  73     18(l:1) blk: 3 numTuple: 97 free: 3896b(52.28%)
  74     19(l:1) blk: 26 numTuple: 96 free: 3940b(51.74%)
  75     20(l:1) blk: 6 numTuple: 103 free: 3632b(55.51%)
  76     21(l:1) blk: 8 numTuple: 162 free: 1036b(87.31%)
  77     22(l:1) blk: 23 numTuple: 94 free: 4028b(50.66%)
  78     23(l:1) blk: 12 numTuple: 82 free: 4556b(44.19%)
  79     24(l:1) blk: 27 numTuple: 105 free: 3544b(56.59%)
  80     25(l:1) blk: 5 numTuple: 90 free: 4204b(48.51%)
  81     26(l:1) blk: 28 numTuple: 100 free: 3764b(53.90%)
  82     27(l:1) blk: 22 numTuple: 101 free: 3720b(54.43%)
  83     28(l:1) blk: 15 numTuple: 95 free: 3984b(51.20%)
  84     29(l:1) blk: 29 numTuple: 95 free: 3984b(51.20%)
  85
  86     * gist_print(INDEXNAME) - prints objects stored in GiST tree,
  87      works only if objects in index have textual representation
  88      (type_out functions should be implemented for given object type).
  89      It's known to work with R-tree GiST based index.
  90      Note, in example below, objects are of type box.
  91
  92 # select * from gist_print('pix') as t(level int, valid bool, a box) where level =1;
  93  level | valid |              a
  94 -------+-------+-----------------------------
  95      1 | t     | (37357,50073),(34242,357)
  96      1 | t     | (43499,49770),(40358,43)
  97      1 | t     | (31193,24679),(25047,12410)
  98      1 | t     | (31018,12142),(25083,6)
  99      1 | t     | (49944,25174),(43471,12802)
 100      1 | t     | (12577,49757),(6302,37534)
 101      1 | t     | (12528,37333),(6171,24861)
 102      1 | t     | (50027,49751),(46817,25462)
 103      1 | t     | (46870,49912),(43664,25722)
 104      1 | t     | (24855,25574),(12447,19263)
 105      1 | t     | (25054,19126),(12403,12796)
 106      1 | t     | (32737,49923),(31178,1038)
 107      1 | t     | (3184,24465),(15,81)
 108      1 | t     | (24951,49983),(12740,44000)
 109      1 | t     | (24919,43956),(12617,37901)
 110      1 | t     | (40387,49852),(37338,25217)
 111      1 | t     | (40325,24963),(37375,491)
 112      1 | t     | (24919,12698),(12654,6518)
 113      1 | t     | (25002,6338),(12350,51)
 114      1 | t     | (49985,12554),(43447,222)
 115      1 | t     | (25003,37769),(12552,25573)
 116      1 | t     | (34270,49382),(32763,594)
 117      1 | t     | (6205,50012),(3,37527)
 118      1 | t     | (6163,37358),(120,25034)
 119      1 | t     | (12343,24542),(9295,294)
 120      1 | t     | (9308,24151),(6234,620)
 121      1 | t     | (6230,24629),(3169,108)
 122      1 | t     | (31179,50040),(28113,25556)
 123      1 | t     | (28048,49694),(25000,25000)
 124 (29 rows)
 125
 126     * spgist_stat(INDEXNAME) - show some statistics about SP-GiST tree
 127
 128 # SELECT spgist_stat('spgist_idx');
 129            spgist_stat
 130 ----------------------------------
 131  totalPages:        21           +
 132  deletedPages:      0            +
 133  innerPages:        3            +
 134  leafPages:         18           +
 135  emptyPages:        1            +
 136  usedSpace:         121.27 kbytes+
 137  freeSpace:         46.07 kbytes +
 138  fillRatio:         72.47%       +
 139  leafTuples:        3669         +
 140  innerTuples:       20           +
 141  innerAllTheSame:   0            +
 142  leafPlaceholders:  569          +
 143  innerPlaceholders: 0            +
 144  leafRedirects:     0            +
 145  innerRedirects:    0
 146
 147     * spgist_print(INDEXNAME) - prints objects stored in GiST tree,
 148      works only if objects in index have textual representation
 149      (type_out functions should be implemented for given object type).
 150          Note 1. in example below we used quad_point_ops which uses point
 151                 for leaf and prefix value, but doesn't use node_label at all.
 152                 Use type  'int' as dummy type for prefix or/and node_label.
 153          Note 2
 154                 quad_point_ops: prefix point, node_label int,  leaf_value point
 155                 kd_point_ops:   prefix float, node_label int,  leaf_value point
 156                 text_ops:       prefix text,  node_label char, leaf_value text
 157
 158 # SELECT * FROM spgist_print('spgist_idx') as t
 159                 (
 160                         tid tid,
 161                         allthesame bool,
 162                         node_n int,
 163                         level int,
 164                         tid_pointer tid,
 165                         prefix point,
 166                         node_label int,
 167                         leaf_value point
 168                 ) where level = 1;
 169   tid  | allthesame | node_n | level | tid_pointer |               prefix                | node_label | leaf_value
 170 -------+------------+--------+-------+-------------+-------------------------------------+------------+------------
 171  (1,1) | f          |      0 |     1 | (5,4)       | (24530.2070484581,23595.7092511013) |            |
 172  (1,1) | f          |      1 |     1 | (5,3)       | (24530.2070484581,23595.7092511013) |            |
 173  (1,1) | f          |      2 |     1 | (5,2)       | (24530.2070484581,23595.7092511013) |            |
 174  (1,1) | f          |      3 |     1 | (5,1)       | (24530.2070484581,23595.7092511013) |            |
 175
 176    * gin_stat(INDEXNAME) prints estimated counts for each indexed values
 177          Note: since 8.4 gin_stat function has gin_stat(INDEXNAME, COLNUMBER)
 178          prototype, single-argument function will return result for a first
 179          column of index
 180
 181 # SELECT * FROM gin_stat('gin_idx') as t(value int, nrow int) where nrow > 250;
 182  value | nrow
 183  -------+------
 184         31 |  254
 185         47 |  251
 186         52 |  257
 187         59 |  259
 188  (4 rows)
 189
 190    * bigint gin_count_estimate(INDEXNAME, TSQUERY) outputs number of indexed
 191          rows matched query. It doesn't touch heap at all.
 192
 193 # select gin_count_estimate('qq', 'star');
 194  gin_count_estimate
 195 --------------------
 196                                  790
 197 (1 row)
 198
 199    * text gin_statpage(INDEXNAME)
 200          Prints various stat about index internals.
 201
 202 # select gin_statpage('gin_idx');
 203          gin_statpage
 204 ------------------------------
 205  totalPages:            32   +
 206  dataPages:             1    +
 207  dataInnerPages:        0    +
 208  dataLeafPages:         1    +
 209  dataInnerFreeSpace:    0    +
 210  dataLeafFreeSpace:     4454 +
 211  dataInnerTuplesCount:  0    +
 212  dataLeafIptrsCount:    3600 +
 213  entryPages:            31   +
 214  entryInnerPages:       21   +
 215  entryLeafPages:        10   +
 216  entryInnerFreeSpace:   15160+
 217  entryLeafFreeSpace:    32788+
 218  entryInnerTuplesCount: 7810 +
 219  entryLeafTuplesCount:  305  +
 220  entryPostingSize:      42122+
 221  entryPostingCount:     96759+
 222  entryAttrSize:         64924+
 223