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         * Daria Lepikhova <d.lepikhova@postgrespro.ru>, Postgres Pro
  12
  13 License
  14
  15 Stable version, included into PostgreSQL distribution, released under
  16 BSD license. Development version, available from this site, released under
  17 the GNU General Public License, version 2 (June 1991)
  18
  19 Install gevel module (requires 8.1+ version):
  20 % cd PGSQLSRC/contrib
  21 % tar xzvf gevel.tar.gz
  22 % make
  23 % make install
  24 % make installcheck
  25 % psql regression < gevel.sql
  26
  27     * gist_stat(INDEXNAME) - show some statistics about GiST tree
  28
  29 regression=# select gist_stat('pix');
  30  Number of levels:          2
  31 Number of pages:           30
  32 Number of leaf pages:      29
  33 Number of tuples:          3129
  34 Number of leaf tuples:     3100
  35 Total size of tuples:      137676 bytes
  36 Total size of leaf tuples: 136400 bytes
  37 Total size of index:       245760 bytes
  38
  39     * gist_tree(INDEXNAME[,MAXLEVEL]) - show GiST tree up to MAXLEVEL
  40
  41 regression=# select gist_tree('pix',0);
  42  0(l:0) blk: 0 numTuple: 29 free: 6888b(15.63%)
  43
  44 Designation (from left to right):
  45
  46           o 0 - page number
  47           o (l:0) - tree level
  48           o blk: 0 - block number
  49           o numTuple: 29 - the number of tuples
  50           o free: 6888b - free space in bytes
  51           o (15.63%) - occupied space in percents
  52
  53     * gist_tree(INDEXNAME) - show full GiST tree
  54
  55 regression=# select gist_tree('pix');
  56  0(l:0) blk: 0 numTuple: 29 free: 6888b(15.63%)
  57     1(l:1) blk: 13 numTuple: 180 free: 244b(97.01%)
  58     2(l:1) blk: 11 numTuple: 175 free: 464b(94.32%)
  59     3(l:1) blk: 2 numTuple: 101 free: 3720b(54.43%)
  60     4(l:1) blk: 17 numTuple: 111 free: 3280b(59.82%)
  61     5(l:1) blk: 18 numTuple: 101 free: 3720b(54.43%)
  62     6(l:1) blk: 10 numTuple: 98 free: 3852b(52.82%)
  63     7(l:1) blk: 19 numTuple: 111 free: 3280b(59.82%)
  64     8(l:1) blk: 9 numTuple: 97 free: 3896b(52.28%)
  65     9(l:1) blk: 20 numTuple: 104 free: 3588b(56.05%)
  66     10(l:1) blk: 14 numTuple: 96 free: 3940b(51.74%)
  67     11(l:1) blk: 21 numTuple: 106 free: 3500b(57.13%)
  68     12(l:1) blk: 7 numTuple: 103 free: 3632b(55.51%)
  69     13(l:1) blk: 1 numTuple: 101 free: 3720b(54.43%)
  70     14(l:1) blk: 16 numTuple: 97 free: 3896b(52.28%)
  71     15(l:1) blk: 24 numTuple: 103 free: 3632b(55.51%)
  72     16(l:1) blk: 4 numTuple: 98 free: 3852b(52.82%)
  73     17(l:1) blk: 25 numTuple: 98 free: 3852b(52.82%)
  74     18(l:1) blk: 3 numTuple: 97 free: 3896b(52.28%)
  75     19(l:1) blk: 26 numTuple: 96 free: 3940b(51.74%)
  76     20(l:1) blk: 6 numTuple: 103 free: 3632b(55.51%)
  77     21(l:1) blk: 8 numTuple: 162 free: 1036b(87.31%)
  78     22(l:1) blk: 23 numTuple: 94 free: 4028b(50.66%)
  79     23(l:1) blk: 12 numTuple: 82 free: 4556b(44.19%)
  80     24(l:1) blk: 27 numTuple: 105 free: 3544b(56.59%)
  81     25(l:1) blk: 5 numTuple: 90 free: 4204b(48.51%)
  82     26(l:1) blk: 28 numTuple: 100 free: 3764b(53.90%)
  83     27(l:1) blk: 22 numTuple: 101 free: 3720b(54.43%)
  84     28(l:1) blk: 15 numTuple: 95 free: 3984b(51.20%)
  85     29(l:1) blk: 29 numTuple: 95 free: 3984b(51.20%)
  86
  87     * gist_print(INDEXNAME) - prints objects stored in GiST tree,
  88      works only if objects in index have textual representation
  89      (type_out functions should be implemented for given object type).
  90      It's known to work with R-tree GiST based index.
  91      Note, in example below, objects are of type box.
  92
  93 # select * from gist_print('pix') as t(level int, valid bool, a box) where level =1;
  94  level | valid |              a
  95 -------+-------+-----------------------------
  96      1 | t     | (37357,50073),(34242,357)
  97      1 | t     | (43499,49770),(40358,43)
  98      1 | t     | (31193,24679),(25047,12410)
  99      1 | t     | (31018,12142),(25083,6)
 100      1 | t     | (49944,25174),(43471,12802)
 101      1 | t     | (12577,49757),(6302,37534)
 102      1 | t     | (12528,37333),(6171,24861)
 103      1 | t     | (50027,49751),(46817,25462)
 104      1 | t     | (46870,49912),(43664,25722)
 105      1 | t     | (24855,25574),(12447,19263)
 106      1 | t     | (25054,19126),(12403,12796)
 107      1 | t     | (32737,49923),(31178,1038)
 108      1 | t     | (3184,24465),(15,81)
 109      1 | t     | (24951,49983),(12740,44000)
 110      1 | t     | (24919,43956),(12617,37901)
 111      1 | t     | (40387,49852),(37338,25217)
 112      1 | t     | (40325,24963),(37375,491)
 113      1 | t     | (24919,12698),(12654,6518)
 114      1 | t     | (25002,6338),(12350,51)
 115      1 | t     | (49985,12554),(43447,222)
 116      1 | t     | (25003,37769),(12552,25573)
 117      1 | t     | (34270,49382),(32763,594)
 118      1 | t     | (6205,50012),(3,37527)
 119      1 | t     | (6163,37358),(120,25034)
 120      1 | t     | (12343,24542),(9295,294)
 121      1 | t     | (9308,24151),(6234,620)
 122      1 | t     | (6230,24629),(3169,108)
 123      1 | t     | (31179,50040),(28113,25556)
 124      1 | t     | (28048,49694),(25000,25000)
 125 (29 rows)
 126
 127     * spgist_stat(INDEXNAME) - show some statistics about SP-GiST tree
 128
 129 # SELECT spgist_stat('spgist_idx');
 130            spgist_stat
 131 ----------------------------------
 132  totalPages:        21           +
 133  deletedPages:      0            +
 134  innerPages:        3            +
 135  leafPages:         18           +
 136  emptyPages:        1            +
 137  usedSpace:         121.27 kbytes+
 138  freeSpace:         46.07 kbytes +
 139  fillRatio:         72.47%       +
 140  leafTuples:        3669         +
 141  innerTuples:       20           +
 142  innerAllTheSame:   0            +
 143  leafPlaceholders:  569          +
 144  innerPlaceholders: 0            +
 145  leafRedirects:     0            +
 146  innerRedirects:    0
 147
 148     * spgist_print(INDEXNAME) - prints objects stored in GiST tree,
 149      works only if objects in index have textual representation
 150      (type_out functions should be implemented for given object type).
 151          Note 1. in example below we used quad_point_ops which uses point
 152                 for leaf and prefix value, but doesn't use node_label at all.
 153                 Use type  'int' as dummy type for prefix or/and node_label.
 154          Note 2
 155                 quad_point_ops: prefix point, node_label int,  leaf_value point
 156                 kd_point_ops:   prefix float, node_label int,  leaf_value point
 157                 text_ops:       prefix text,  node_label char, leaf_value text
 158
 159 # SELECT * FROM spgist_print('spgist_idx') as t
 160                 (
 161                         tid tid,
 162                         allthesame bool,
 163                         node_n int,
 164                         level int,
 165                         tid_pointer tid,
 166                         prefix point,
 167                         node_label int,
 168                         leaf_value point
 169                 ) where level = 1;
 170   tid  | allthesame | node_n | level | tid_pointer |               prefix                | node_label | leaf_value
 171 -------+------------+--------+-------+-------------+-------------------------------------+------------+------------
 172  (1,1) | f          |      0 |     1 | (5,4)       | (24530.2070484581,23595.7092511013) |            |
 173  (1,1) | f          |      1 |     1 | (5,3)       | (24530.2070484581,23595.7092511013) |            |
 174  (1,1) | f          |      2 |     1 | (5,2)       | (24530.2070484581,23595.7092511013) |            |
 175  (1,1) | f          |      3 |     1 | (5,1)       | (24530.2070484581,23595.7092511013) |            |
 176
 177    * gin_stat(INDEXNAME) prints estimated counts for each indexed values
 178          Note: since 8.4 gin_stat function has gin_stat(INDEXNAME, COLNUMBER)
 179          prototype, single-argument function will return result for a first
 180          column of index
 181
 182 # SELECT * FROM gin_stat('gin_idx') as t(value int, nrow int) where nrow > 250;
 183  value | nrow
 184  -------+------
 185         31 |  254
 186         47 |  251
 187         52 |  257
 188         59 |  259
 189  (4 rows)
 190
 191    * bigint gin_count_estimate(INDEXNAME, TSQUERY) outputs number of indexed
 192          rows matched query. It doesn't touch heap at all.
 193
 194 # select gin_count_estimate('qq', 'star');
 195  gin_count_estimate
 196 --------------------
 197                                  790
 198 (1 row)
 199
 200    * text gin_statpage(INDEXNAME)
 201          Prints various stat about index internals.
 202
 203 # select gin_statpage('gin_idx');
 204          gin_statpage
 205 ------------------------------
 206  totalPages:            32   +
 207  dataPages:             1    +
 208  dataInnerPages:        0    +
 209  dataLeafPages:         1    +
 210  dataInnerFreeSpace:    0    +
 211  dataLeafFreeSpace:     4454 +
 212  dataInnerTuplesCount:  0    +
 213  dataLeafIptrsCount:    3600 +
 214  entryPages:            31   +
 215  entryInnerPages:       21   +
 216  entryLeafPages:        10   +
 217  entryInnerFreeSpace:   15160+
 218  entryLeafFreeSpace:    32788+
 219  entryInnerTuplesCount: 7810 +
 220  entryLeafTuplesCount:  305  +
 221  entryPostingSize:      42122+
 222  entryPostingCount:     96759+
 223  entryAttrSize:         64924+
 224
 225    * btree_stat(INDEXNAME) - show some statistics about btree index
 226
 227 # SELECT btree_stat('btree_idx');
 228          btree_stat
 229 -----------------------------------------
 230  Number of levels:          2           +
 231  Number of pages:           75          +
 232  Number of leaf pages:      74          +
 233  Number of tuples:          11047       +
 234  Number of invalid tuples:  0           +
 235  Number of leaf tuples:     10973       +
 236  Total size of tuples:      547824 bytes+
 237  Total size of leaf tuples: 543948 bytes+
 238  Total size of index:       614400 bytes+
 239
 240  (1 row)
 241
 242    * btree_tree(INDEXNAME[, MAXLEVEL]) - show btree elements from root up to MAXLEVEL
 243
 244 # SELECT btree_tree('btree_idx');
 245                          btree_tree
 246 ---------------------------------
 247  lvl: 0, blk: 3, numTuples: 74  +
 248  lvl: 1, blk: 1, numTuples: 139 +
 249  lvl: 1, blk: 2, numTuples: 139 +
 250  lvl: 1, blk: 4, numTuples: 139 +
 251  lvl: 1, blk: 5, numTuples: 136 +
 252  lvl: 1, blk: 6, numTuples: 141 +
 253  lvl: 1, blk: 7, numTuples: 139 +
 254  lvl: 1, blk: 8, numTuples: 140 +
 255  lvl: 1, blk: 9, numTuples: 136 +
 256  lvl: 1, blk: 10, numTuples: 140+
 257  lvl: 1, blk: 11, numTuples: 138+
 258  lvl: 1, blk: 12, numTuples: 143+
 259  lvl: 1, blk: 13, numTuples: 137+
 260  lvl: 1, blk: 14, numTuples: 138+
 261  lvl: 1, blk: 15, numTuples: 140+
 262  lvl: 1, blk: 16, numTuples: 141+
 263  lvl: 1, blk: 17, numTuples: 138+
 264  lvl: 1, blk: 18, numTuples: 141+
 265  lvl: 1, blk: 19, numTuples: 141+
 266  lvl: 1, blk: 20, numTuples: 138+
 267  lvl: 1, blk: 21, numTuples: 141+
 268  lvl: 1, blk: 22, numTuples: 141+
 269  lvl: 1, blk: 23, numTuples: 141+
 270  lvl: 1, blk: 24, numTuples: 138+
 271  lvl: 1, blk: 25, numTuples: 140+
 272  lvl: 1, blk: 26, numTuples: 142+
 273  lvl: 1, blk: 27, numTuples: 141+
 274  lvl: 1, blk: 28, numTuples: 142+
 275  lvl: 1, blk: 29, numTuples: 140+
 276  lvl: 1, blk: 30, numTuples: 141+
 277  lvl: 1, blk: 31, numTuples: 140+
 278  lvl: 1, blk: 32, numTuples: 142+
 279  lvl: 1, blk: 33, numTuples: 143+
 280  lvl: 1, blk: 34, numTuples: 141+
 281  lvl: 1, blk: 35, numTuples: 140+
 282  lvl: 1, blk: 36, numTuples: 142+
 283  lvl: 1, blk: 37, numTuples: 142+
 284  lvl: 1, blk: 38, numTuples: 141+
 285  lvl: 1, blk: 39, numTuples: 143+
 286  lvl: 1, blk: 40, numTuples: 142+
 287  lvl: 1, blk: 41, numTuples: 143+
 288  lvl: 1, blk: 42, numTuples: 143+
 289  lvl: 1, blk: 43, numTuples: 142+
 290  lvl: 1, blk: 44, numTuples: 143+
 291  lvl: 1, blk: 45, numTuples: 142+
 292  lvl: 1, blk: 46, numTuples: 142+
 293  lvl: 1, blk: 47, numTuples: 141+
 294  lvl: 1, blk: 48, numTuples: 144+
 295  lvl: 1, blk: 49, numTuples: 141+
 296  lvl: 1, blk: 50, numTuples: 142+
 297  lvl: 1, blk: 51, numTuples: 143+
 298  lvl: 1, blk: 52, numTuples: 142+
 299  lvl: 1, blk: 53, numTuples: 143+
 300  lvl: 1, blk: 54, numTuples: 141+
 301  lvl: 1, blk: 55, numTuples: 142+
 302  lvl: 1, blk: 56, numTuples: 141+
 303  lvl: 1, blk: 57, numTuples: 156+
 304  lvl: 1, blk: 58, numTuples: 159+
 305  lvl: 1, blk: 59, numTuples: 160+
 306  lvl: 1, blk: 60, numTuples: 161+
 307  lvl: 1, blk: 61, numTuples: 163+
 308  lvl: 1, blk: 62, numTuples: 163+
 309  lvl: 1, blk: 63, numTuples: 164+
 310  lvl: 1, blk: 64, numTuples: 165+
 311  lvl: 1, blk: 65, numTuples: 165+
 312  lvl: 1, blk: 66, numTuples: 166+
 313  lvl: 1, blk: 67, numTuples: 166+
 314  lvl: 1, blk: 68, numTuples: 167+
 315  lvl: 1, blk: 69, numTuples: 167+
 316  lvl: 1, blk: 70, numTuples: 167+
 317  lvl: 1, blk: 71, numTuples: 167+
 318  lvl: 1, blk: 72, numTuples: 167+
 319  lvl: 1, blk: 73, numTuples: 167+
 320  lvl: 1, blk: 74, numTuples: 167+
 321  lvl: 1, blk: 75, numTuples: 274+
 322
 323 (1 row)
 324
 325 test1=# SELECT btree_tree('btree_idx', 0);
 326               btree_tree
 327 --------------------------------------
 328  lvl: 0, coff: 0, blk: 3, numTuples: +
 329
 330 (1 row)
 331
 332   * btree_print() - print objects stored in btree
 333   works only if objects in index have textual representation
 334      (type_out functions should be implemented for given object type).
 335 # SELECT * FROM btree_print('btree_idx') as t(level int, val bool, a int[]) where level = 1;
 336  level | val |            a
 337 -------+-----+-------------------------
 338      1 | t   |
 339      1 | t   | {1,1001}
 340      1 | t   | {3,52,31,62,98}
 341      1 | t   | {5,3,25}
 342      1 | t   | {6,70,15}
 343      1 | t   | {8,1}
 344      1 | t   | {9,96}
 345      1 | t   | {11,37,55}
 346      1 | t   | {12,96,72,23,83,56}
 347      1 | t   | {14,30,132,144,174}
 348      1 | t   | {15,87}
 349      1 | t   | {17,36,97,77}
 350      1 | t   | {18,171,283}
 351      1 | t   | {20,66,81}
 352      1 | t   | {22,31,38,77,21}
 353      1 | t   | {24,2,96}
 354      1 | t   | {25,218,241,241}
 355      1 | t   | {27,87,61,54,41}
 356      1 | t   | {29,53,109,128,129,195}
 357      1 | t   | {30,183,215}
 358      1 | t   | {32,41,4}
 359      1 | t   | {34,44,47,81,124,135}
 360      1 | t   | {35,1001}
 361      1 | t   | {37,81,85}
 362      1 | t   | {39,74,47,71,63,80}
 363      1 | t   | {41,60,71}
 364      1 | t   | {43,41,12,44,75,91}
 365      1 | t   | {45,26,61,15}
 366      1 | t   | {47,22,65}
 367      1 | t   | {49,16,63,56}
 368      1 | t   | {50,98,71,10}
 369      1 | t   | {52,53,81}
 370      1 | t   | {54,46,31,87,13,8}
 371      1 | t   | {55,1001}
 372      1 | t   | {57,99,66,93}
 373      1 | t   | {59,103,180,196}
 374      1 | t   | {61,63,59,62}
 375      1 | t   | {63,66}
 376      1 | t   | {65,30,39,82,89,34}
 377      1 | t   | {67,25}
 378      1 | t   | {69,8,75}
 379      1 | t   | {71,23,89}
 380      1 | t   | {73,24,81,58,22}
 381      1 | t   | {75,54,93,39,18}
 382      1 | t   | {77,31,77}
 383      1 | t   | {79,59}
 384      1 | t   | {81,61,86,96,47,67}
 385      1 | t   | {83,79,46,37,99}
 386      1 | t   | {85,72}
 387      1 | t   | {87,93,19}
 388      1 | t   | {89,161}
 389      1 | t   | {91,1001}
 390      1 | t   | {94,8}
 391      1 | t   | {96,33,86,28,19}
 392      1 | t   | {98,53,58,58,61}
 393      1 | t   | {100,80,23,24,17}
 394      1 | t   | {107,1001}
 395      1 | t   | {115,1001}
 396      1 | t   | {124,1001}
 397      1 | t   | {133,1001}
 398      1 | t   | {143,1001}
 399      1 | t   | {154,1000}
 400      1 | t   | {164,1001}
 401      1 | t   | {175,1001}
 402      1 | t   | {186,1001}
 403      1 | t   | {198,1001}
 404      1 | t   | {210,1001}
 405      1 | t   | {222,1001}
 406      1 | t   | {235,1001}
 407      1 | t   | {248,266}
 408      1 | t   | {260,1001}
 409      1 | t   | {273,1001}
 410      1 | t   | {285,1001}
 411      1 | t   | {298,1001}
 412 (74 rows)
 413
 414  * brin_stat(INDEXNAME) - show some statistics about brin index
 415  # SELECT brin_stat('brin_idx');
 416              brin_stat
 417 ------------------------------------
 418  Number of revmap pages:         1 +
 419  Number of empty revmap pages:   0 +
 420  Number of regular pages:        1 +
 421  Number of tuples:               1 +
 422  Used space              56 bytes  +
 423  Free space              8104 bytes+
 424
 425 (1 row)
 426
 427  * brin_print() - print values for pages stored in brin index
 428  # SELECT brin_print('brin_idx')
 429                       brin_print
 430 -------------------------------------------------------
 431  Start block: 0; end block: 48; offset: 86, free: 3292+
 432
 433 (1 row)
 434