doc/src/sgml/pageinspect.sgml

   1 <!-- doc/src/sgml/pageinspect.sgml -->
   2
   3 <sect1 id="pageinspect" xreflabel="pageinspect">
   4  <title>pageinspect &mdash; low-level inspection of database pages</title>
   5
   6  <indexterm zone="pageinspect">
   7   <primary>pageinspect</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pageinspect</filename> module provides functions that allow you to
  12   inspect the contents of database pages at a low level, which is useful for
  13   debugging purposes.  All of these functions may be used only by superusers.
  14  </para>
  15
  16  <sect2 id="pageinspect-general-funcs">
  17   <title>General Functions</title>
  18
  19   <variablelist>
  20    <varlistentry>
  21     <term>
  22      <function>get_raw_page(relname text, fork text, blkno bigint) returns bytea</function>
  23      <indexterm>
  24       <primary>get_raw_page</primary>
  25      </indexterm>
  26     </term>
  27
  28     <listitem>
  29      <para>
  30       <function>get_raw_page</function> reads the specified block of the named
  31       relation and returns a copy as a <type>bytea</type> value.  This allows a
  32       single time-consistent copy of the block to be obtained.
  33       <replaceable>fork</replaceable> should be <literal>'main'</literal> for
  34       the main data fork, <literal>'fsm'</literal> for the
  35       <link linkend="storage-fsm">free space map</link>,
  36       <literal>'vm'</literal> for the
  37       <link linkend="storage-vm">visibility map</link>, or
  38       <literal>'init'</literal> for the initialization fork.
  39      </para>
  40     </listitem>
  41    </varlistentry>
  42
  43    <varlistentry>
  44     <term>
  45      <function>get_raw_page(relname text, blkno bigint) returns bytea</function>
  46     </term>
  47
  48     <listitem>
  49      <para>
  50       A shorthand version of <function>get_raw_page</function>, for reading
  51       from the main fork.  Equivalent to
  52       <literal>get_raw_page(relname, 'main', blkno)</literal>
  53      </para>
  54     </listitem>
  55    </varlistentry>
  56
  57    <varlistentry>
  58     <term>
  59      <function>page_header(page bytea) returns record</function>
  60      <indexterm>
  61       <primary>page_header</primary>
  62      </indexterm>
  63     </term>
  64
  65     <listitem>
  66      <para>
  67       <function>page_header</function> shows fields that are common to all
  68       <productname>PostgreSQL</productname> heap and index pages.
  69      </para>
  70
  71      <para>
  72       A page image obtained with <function>get_raw_page</function> should be
  73       passed as argument.  For example:
  74 <screen>
  75 test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
  76     lsn    | checksum | flags  | lower | upper | special | pagesize | version | prune_xid
  77 -----------+----------+--------+-------+-------+---------+----------+---------+-----------
  78  0/24A1B50 |        0 |      1 |   232 |   368 |    8192 |     8192 |       4 |         0
  79 </screen>
  80       The returned columns correspond to the fields in the
  81       <structname>PageHeaderData</structname> struct.
  82       See <filename>src/include/storage/bufpage.h</filename> for details.
  83      </para>
  84
  85      <para>
  86       The <structfield>checksum</structfield> field is the checksum stored in
  87       the page, which might be incorrect if the page is somehow corrupted.  If
  88       data checksums are not enabled for this instance, then the value stored
  89       is meaningless.
  90      </para>
  91     </listitem>
  92    </varlistentry>
  93
  94    <varlistentry>
  95     <term>
  96      <function>page_checksum(page bytea, blkno bigint) returns smallint</function>
  97      <indexterm>
  98       <primary>page_checksum</primary>
  99      </indexterm>
 100     </term>
 101
 102     <listitem>
 103      <para>
 104       <function>page_checksum</function> computes the checksum for the page, as if
 105       it was located at the given block.
 106      </para>
 107
 108      <para>
 109       A page image obtained with <function>get_raw_page</function> should be
 110       passed as argument.  For example:
 111 <screen>
 112 test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
 113  page_checksum
 114 ---------------
 115          13443
 116 </screen>
 117       Note that the checksum depends on the block number, so matching block
 118       numbers should be passed (except when doing esoteric debugging).
 119      </para>
 120
 121      <para>
 122       The checksum computed with this function can be compared with
 123       the <structfield>checksum</structfield> result field of the
 124       function <function>page_header</function>.  If data checksums are
 125       enabled for this instance, then the two values should be equal.
 126      </para>
 127     </listitem>
 128    </varlistentry>
 129
 130    <varlistentry>
 131     <term>
 132      <function>fsm_page_contents(page bytea) returns text</function>
 133      <indexterm>
 134       <primary>fsm_page_contents</primary>
 135      </indexterm>
 136     </term>
 137
 138     <listitem>
 139      <para>
 140       <function>fsm_page_contents</function> shows the internal node structure
 141       of an <acronym>FSM</acronym> page.  For example:
 142 <screen>
 143 test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
 144 </screen>
 145       The output is a multiline string, with one line per node in the binary
 146       tree within the page.  Only those nodes that are not zero are printed.
 147       The so-called "next" pointer, which points to the next slot to be
 148       returned from the page, is also printed.
 149      </para>
 150      <para>
 151       See <filename>src/backend/storage/freespace/README</filename> for more
 152       information on the structure of an <acronym>FSM</acronym> page.
 153      </para>
 154     </listitem>
 155    </varlistentry>
 156   </variablelist>
 157  </sect2>
 158
 159  <sect2 id="pageinspect-heap-funcs">
 160   <title>Heap Functions</title>
 161
 162   <variablelist>
 163    <varlistentry>
 164     <term>
 165      <function>heap_page_items(page bytea) returns setof record</function>
 166      <indexterm>
 167       <primary>heap_page_items</primary>
 168      </indexterm>
 169     </term>
 170
 171     <listitem>
 172      <para>
 173       <function>heap_page_items</function> shows all line pointers on a heap
 174       page.  For those line pointers that are in use, tuple headers as well
 175       as tuple raw data are also shown. All tuples are shown, whether or not
 176       the tuples were visible to an MVCC snapshot at the time the raw page
 177       was copied.
 178      </para>
 179      <para>
 180       A heap page image obtained with <function>get_raw_page</function> should
 181       be passed as argument.  For example:
 182 <screen>
 183 test=# SELECT * FROM heap_page_items(get_raw_page('pg_class', 0));
 184 </screen>
 185       See <filename>src/include/storage/itemid.h</filename> and
 186       <filename>src/include/access/htup_details.h</filename> for explanations of the fields
 187       returned.
 188      </para>
 189      <para>
 190       The <function>heap_tuple_infomask_flags</function> function can be
 191       used to unpack the flag bits of <structfield>t_infomask</structfield>
 192       and <structfield>t_infomask2</structfield> for heap tuples.
 193      </para>
 194     </listitem>
 195    </varlistentry>
 196
 197    <varlistentry>
 198     <term>
 199      <function>tuple_data_split(rel_oid oid, t_data bytea, t_infomask integer, t_infomask2 integer, t_bits text [, do_detoast bool]) returns bytea[]</function>
 200      <indexterm>
 201       <primary>tuple_data_split</primary>
 202      </indexterm>
 203     </term>
 204     <listitem>
 205      <para>
 206       <function>tuple_data_split</function> splits tuple data into attributes
 207       in the same way as backend internals.
 208 <screen>
 209 test=# SELECT tuple_data_split('pg_class'::regclass, t_data, t_infomask, t_infomask2, t_bits) FROM heap_page_items(get_raw_page('pg_class', 0));
 210 </screen>
 211       This function should be called with the same arguments as the return
 212       attributes of <function>heap_page_items</function>.
 213      </para>
 214      <para>
 215       If <parameter>do_detoast</parameter> is <literal>true</literal>,
 216       attributes will be detoasted as needed. Default value is
 217       <literal>false</literal>.
 218      </para>
 219     </listitem>
 220    </varlistentry>
 221
 222    <varlistentry>
 223     <term>
 224      <function>heap_page_item_attrs(page bytea, rel_oid regclass [, do_detoast bool]) returns setof record</function>
 225      <indexterm>
 226       <primary>heap_page_item_attrs</primary>
 227      </indexterm>
 228     </term>
 229     <listitem>
 230      <para>
 231       <function>heap_page_item_attrs</function> is equivalent to
 232       <function>heap_page_items</function> except that it returns
 233       tuple raw data as an array of attributes that can optionally
 234       be detoasted by <parameter>do_detoast</parameter> which is
 235       <literal>false</literal> by default.
 236      </para>
 237      <para>
 238       A heap page image obtained with <function>get_raw_page</function> should
 239       be passed as argument.  For example:
 240 <screen>
 241 test=# SELECT * FROM heap_page_item_attrs(get_raw_page('pg_class', 0), 'pg_class'::regclass);
 242 </screen>
 243      </para>
 244     </listitem>
 245    </varlistentry>
 246
 247    <varlistentry>
 248     <term>
 249      <function>heap_tuple_infomask_flags(t_infomask integer, t_infomask2 integer) returns record</function>
 250      <indexterm>
 251       <primary>heap_tuple_infomask_flags</primary>
 252      </indexterm>
 253     </term>
 254     <listitem>
 255      <para>
 256       <function>heap_tuple_infomask_flags</function> decodes the
 257       <structfield>t_infomask</structfield> and
 258       <structfield>t_infomask2</structfield> returned by
 259       <function>heap_page_items</function> into a human-readable
 260       set of arrays made of flag names, with one column for all
 261       the flags and one column for combined flags. For example:
 262 <screen>
 263 test=# SELECT t_ctid, raw_flags, combined_flags
 264          FROM heap_page_items(get_raw_page('pg_class', 0)),
 265            LATERAL heap_tuple_infomask_flags(t_infomask, t_infomask2)
 266          WHERE t_infomask IS NOT NULL OR t_infomask2 IS NOT NULL;
 267 </screen>
 268       This function should be called with the same arguments as the return
 269       attributes of <function>heap_page_items</function>.
 270      </para>
 271      <para>
 272       Combined flags are displayed for source-level macros that take into
 273       account the value of more than one raw bit, such as
 274       <literal>HEAP_XMIN_FROZEN</literal>.
 275      </para>
 276      <para>
 277       See <filename>src/include/access/htup_details.h</filename> for
 278       explanations of the flag names returned.
 279      </para>
 280     </listitem>
 281    </varlistentry>
 282   </variablelist>
 283  </sect2>
 284
 285  <sect2 id="pageinspect-b-tree-funcs">
 286   <title>B-Tree Functions</title>
 287
 288   <variablelist>
 289    <varlistentry>
 290     <term>
 291      <function>bt_metap(relname text) returns record</function>
 292      <indexterm>
 293       <primary>bt_metap</primary>
 294      </indexterm>
 295     </term>
 296
 297     <listitem>
 298      <para>
 299       <function>bt_metap</function> returns information about a B-tree
 300       index's metapage.  For example:
 301 <screen>
 302 test=# SELECT * FROM bt_metap('pg_cast_oid_index');
 303 -[ RECORD 1 ]-------------+-------
 304 magic                     | 340322
 305 version                   | 4
 306 root                      | 1
 307 level                     | 0
 308 fastroot                  | 1
 309 fastlevel                 | 0
 310 last_cleanup_num_delpages | 0
 311 last_cleanup_num_tuples   | 230
 312 allequalimage             | f
 313 </screen>
 314      </para>
 315     </listitem>
 316    </varlistentry>
 317
 318    <varlistentry>
 319     <term>
 320      <function>bt_page_stats(relname text, blkno bigint) returns record</function>
 321      <indexterm>
 322       <primary>bt_page_stats</primary>
 323      </indexterm>
 324     </term>
 325
 326     <listitem>
 327      <para>
 328       <function>bt_page_stats</function> returns summary information about
 329       a data page of a B-tree index.  For example:
 330 <screen>
 331 test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
 332 -[ RECORD 1 ]-+-----
 333 blkno         | 1
 334 type          | l
 335 live_items    | 224
 336 dead_items    | 0
 337 avg_item_size | 16
 338 page_size     | 8192
 339 free_size     | 3668
 340 btpo_prev     | 0
 341 btpo_next     | 0
 342 btpo_level    | 0
 343 btpo_flags    | 3
 344 </screen>
 345      </para>
 346     </listitem>
 347    </varlistentry>
 348
 349    <varlistentry>
 350     <term>
 351      <function>bt_multi_page_stats(relname text, blkno bigint, blk_count bigint) returns setof record</function>
 352      <indexterm>
 353       <primary>bt_multi_page_stats</primary>
 354      </indexterm>
 355     </term>
 356
 357     <listitem>
 358      <para>
 359       <function>bt_multi_page_stats</function> returns the same information
 360       as <function>bt_page_stats</function>, but does so for each page of the
 361       range of pages beginning at <parameter>blkno</parameter> and extending
 362       for <parameter>blk_count</parameter> pages.
 363       If <parameter>blk_count</parameter> is negative, all pages
 364       from <parameter>blkno</parameter> to the end of the index are reported
 365       on.  For example:
 366 <screen>
 367 test=# SELECT * FROM bt_multi_page_stats('pg_proc_oid_index', 5, 2);
 368 -[ RECORD 1 ]-+-----
 369 blkno         | 5
 370 type          | l
 371 live_items    | 367
 372 dead_items    | 0
 373 avg_item_size | 16
 374 page_size     | 8192
 375 free_size     | 808
 376 btpo_prev     | 4
 377 btpo_next     | 6
 378 btpo_level    | 0
 379 btpo_flags    | 1
 380 -[ RECORD 2 ]-+-----
 381 blkno         | 6
 382 type          | l
 383 live_items    | 367
 384 dead_items    | 0
 385 avg_item_size | 16
 386 page_size     | 8192
 387 free_size     | 808
 388 btpo_prev     | 5
 389 btpo_next     | 7
 390 btpo_level    | 0
 391 btpo_flags    | 1
 392 </screen>
 393      </para>
 394     </listitem>
 395    </varlistentry>
 396
 397    <varlistentry>
 398     <term>
 399      <function>bt_page_items(relname text, blkno bigint) returns setof record</function>
 400      <indexterm>
 401       <primary>bt_page_items</primary>
 402      </indexterm>
 403     </term>
 404
 405     <listitem>
 406      <para>
 407       <function>bt_page_items</function> returns detailed information about
 408       all of the items on a B-tree index page.  For example:
 409 <screen>
 410 test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
 411         FROM bt_page_items('tenk2_hundred', 5);
 412  itemoffset |   ctid    | itemlen | nulls | vars |          data           | dead |  htid  |      some_tids
 413 ------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
 414           1 | (16,1)    |      16 | f     | f    | 30 00 00 00 00 00 00 00 |      |        |
 415           2 | (16,8292) |     616 | f     | f    | 24 00 00 00 00 00 00 00 | f    | (1,6)  | {"(1,6)","(10,22)"}
 416           3 | (16,8292) |     616 | f     | f    | 25 00 00 00 00 00 00 00 | f    | (1,18) | {"(1,18)","(4,22)"}
 417           4 | (16,8292) |     616 | f     | f    | 26 00 00 00 00 00 00 00 | f    | (4,18) | {"(4,18)","(6,17)"}
 418           5 | (16,8292) |     616 | f     | f    | 27 00 00 00 00 00 00 00 | f    | (1,2)  | {"(1,2)","(1,19)"}
 419           6 | (16,8292) |     616 | f     | f    | 28 00 00 00 00 00 00 00 | f    | (2,24) | {"(2,24)","(4,11)"}
 420           7 | (16,8292) |     616 | f     | f    | 29 00 00 00 00 00 00 00 | f    | (2,17) | {"(2,17)","(11,2)"}
 421           8 | (16,8292) |     616 | f     | f    | 2a 00 00 00 00 00 00 00 | f    | (0,25) | {"(0,25)","(3,20)"}
 422           9 | (16,8292) |     616 | f     | f    | 2b 00 00 00 00 00 00 00 | f    | (0,10) | {"(0,10)","(0,14)"}
 423          10 | (16,8292) |     616 | f     | f    | 2c 00 00 00 00 00 00 00 | f    | (1,3)  | {"(1,3)","(3,9)"}
 424          11 | (16,8292) |     616 | f     | f    | 2d 00 00 00 00 00 00 00 | f    | (6,28) | {"(6,28)","(11,1)"}
 425          12 | (16,8292) |     616 | f     | f    | 2e 00 00 00 00 00 00 00 | f    | (0,27) | {"(0,27)","(1,13)"}
 426          13 | (16,8292) |     616 | f     | f    | 2f 00 00 00 00 00 00 00 | f    | (4,17) | {"(4,17)","(4,21)"}
 427 (13 rows)
 428 </screen>
 429       This is a B-tree leaf page.  All tuples that point to the table
 430       happen to be posting list tuples (all of which store a total of
 431       100 6 byte TIDs).  There is also a <quote>high key</quote> tuple
 432       at <literal>itemoffset</literal> number 1.
 433       <structfield>ctid</structfield> is used to store encoded
 434       information about each tuple in this example, though leaf page
 435       tuples often store a heap TID directly in the
 436       <structfield>ctid</structfield> field instead.
 437       <structfield>tids</structfield> is the list of TIDs stored as a
 438       posting list.
 439      </para>
 440      <para>
 441       In an internal page (not shown), the block number part of
 442       <structfield>ctid</structfield> is a <quote>downlink</quote>,
 443       which is a block number of another page in the index itself.
 444       The offset part (the second number) of
 445       <structfield>ctid</structfield> stores encoded information about
 446       the tuple, such as the number of columns present (suffix
 447       truncation may have removed unneeded suffix columns).  Truncated
 448       columns are treated as having the value <quote>minus
 449        infinity</quote>.
 450      </para>
 451      <para>
 452       <structfield>htid</structfield> shows a heap TID for the tuple,
 453       regardless of the underlying tuple representation.  This value
 454       may match <structfield>ctid</structfield>, or may be decoded
 455       from the alternative representations used by posting list tuples
 456       and tuples from internal pages.  Tuples in internal pages
 457       usually have the implementation level heap TID column truncated
 458       away, which is represented as a NULL
 459       <structfield>htid</structfield> value.
 460      </para>
 461      <para>
 462       Note that the first item on any non-rightmost page (any page with
 463       a non-zero value in the <structfield>btpo_next</structfield> field) is the
 464       page's <quote>high key</quote>, meaning its <structfield>data</structfield>
 465       serves as an upper bound on all items appearing on the page, while
 466       its <structfield>ctid</structfield> field does not point to
 467       another block.  Also, on internal pages, the first real data
 468       item (the first item that is not a high key) reliably has every
 469       column truncated away, leaving no actual value in its
 470       <structfield>data</structfield> field.  Such an item does have a
 471       valid downlink in its <structfield>ctid</structfield> field,
 472       however.
 473      </para>
 474      <para>
 475       For more details about the structure of B-tree indexes, see
 476       <xref linkend="btree-structure"/>.  For more details about
 477       deduplication and posting lists, see <xref
 478        linkend="btree-deduplication"/>.
 479      </para>
 480     </listitem>
 481    </varlistentry>
 482
 483    <varlistentry>
 484     <term>
 485      <function>bt_page_items(page bytea) returns setof record</function>
 486      <indexterm>
 487       <primary>bt_page_items</primary>
 488      </indexterm>
 489     </term>
 490
 491     <listitem>
 492      <para>
 493       It is also possible to pass a page to <function>bt_page_items</function>
 494       as a <type>bytea</type> value.  A page image obtained
 495       with <function>get_raw_page</function> should be passed as argument.  So
 496       the last example could also be rewritten like this:
 497 <screen>
 498 test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
 499         FROM bt_page_items(get_raw_page('tenk2_hundred', 5));
 500  itemoffset |   ctid    | itemlen | nulls | vars |          data           | dead |  htid  |      some_tids
 501 ------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
 502           1 | (16,1)    |      16 | f     | f    | 30 00 00 00 00 00 00 00 |      |        |
 503           2 | (16,8292) |     616 | f     | f    | 24 00 00 00 00 00 00 00 | f    | (1,6)  | {"(1,6)","(10,22)"}
 504           3 | (16,8292) |     616 | f     | f    | 25 00 00 00 00 00 00 00 | f    | (1,18) | {"(1,18)","(4,22)"}
 505           4 | (16,8292) |     616 | f     | f    | 26 00 00 00 00 00 00 00 | f    | (4,18) | {"(4,18)","(6,17)"}
 506           5 | (16,8292) |     616 | f     | f    | 27 00 00 00 00 00 00 00 | f    | (1,2)  | {"(1,2)","(1,19)"}
 507           6 | (16,8292) |     616 | f     | f    | 28 00 00 00 00 00 00 00 | f    | (2,24) | {"(2,24)","(4,11)"}
 508           7 | (16,8292) |     616 | f     | f    | 29 00 00 00 00 00 00 00 | f    | (2,17) | {"(2,17)","(11,2)"}
 509           8 | (16,8292) |     616 | f     | f    | 2a 00 00 00 00 00 00 00 | f    | (0,25) | {"(0,25)","(3,20)"}
 510           9 | (16,8292) |     616 | f     | f    | 2b 00 00 00 00 00 00 00 | f    | (0,10) | {"(0,10)","(0,14)"}
 511          10 | (16,8292) |     616 | f     | f    | 2c 00 00 00 00 00 00 00 | f    | (1,3)  | {"(1,3)","(3,9)"}
 512          11 | (16,8292) |     616 | f     | f    | 2d 00 00 00 00 00 00 00 | f    | (6,28) | {"(6,28)","(11,1)"}
 513          12 | (16,8292) |     616 | f     | f    | 2e 00 00 00 00 00 00 00 | f    | (0,27) | {"(0,27)","(1,13)"}
 514          13 | (16,8292) |     616 | f     | f    | 2f 00 00 00 00 00 00 00 | f    | (4,17) | {"(4,17)","(4,21)"}
 515 (13 rows)
 516 </screen>
 517       All the other details are the same as explained in the previous item.
 518      </para>
 519     </listitem>
 520    </varlistentry>
 521   </variablelist>
 522  </sect2>
 523
 524  <sect2 id="pageinspect-brin-funcs">
 525   <title>BRIN Functions</title>
 526
 527   <variablelist>
 528    <varlistentry>
 529     <term>
 530      <function>brin_page_type(page bytea) returns text</function>
 531      <indexterm>
 532       <primary>brin_page_type</primary>
 533      </indexterm>
 534     </term>
 535
 536     <listitem>
 537      <para>
 538       <function>brin_page_type</function> returns the page type of the given
 539       <acronym>BRIN</acronym> index page, or throws an error if the page is
 540       not a valid <acronym>BRIN</acronym> page.  For example:
 541 <screen>
 542 test=# SELECT brin_page_type(get_raw_page('brinidx', 0));
 543  brin_page_type
 544 ----------------
 545  meta
 546 </screen>
 547      </para>
 548     </listitem>
 549    </varlistentry>
 550
 551    <varlistentry>
 552     <term>
 553      <function>brin_metapage_info(page bytea) returns record</function>
 554      <indexterm>
 555       <primary>brin_metapage_info</primary>
 556      </indexterm>
 557     </term>
 558
 559     <listitem>
 560      <para>
 561       <function>brin_metapage_info</function> returns assorted information
 562       about a <acronym>BRIN</acronym> index metapage.  For example:
 563 <screen>
 564 test=# SELECT * FROM brin_metapage_info(get_raw_page('brinidx', 0));
 565    magic    | version | pagesperrange | lastrevmappage
 566 ------------+---------+---------------+----------------
 567  0xA8109CFA |       1 |             4 |              2
 568 </screen>
 569      </para>
 570     </listitem>
 571    </varlistentry>
 572
 573    <varlistentry>
 574     <term>
 575      <function>brin_revmap_data(page bytea) returns setof tid</function>
 576      <indexterm>
 577       <primary>brin_revmap_data</primary>
 578      </indexterm>
 579     </term>
 580
 581     <listitem>
 582      <para>
 583       <function>brin_revmap_data</function> returns the list of tuple
 584       identifiers in a <acronym>BRIN</acronym> index range map page.
 585       For example:
 586 <screen>
 587 test=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) LIMIT 5;
 588   pages
 589 ---------
 590  (6,137)
 591  (6,138)
 592  (6,139)
 593  (6,140)
 594  (6,141)
 595 </screen>
 596      </para>
 597     </listitem>
 598    </varlistentry>
 599
 600    <varlistentry>
 601     <term>
 602      <function>brin_page_items(page bytea, index oid) returns setof record</function>
 603      <indexterm>
 604       <primary>brin_page_items</primary>
 605      </indexterm>
 606     </term>
 607
 608     <listitem>
 609      <para>
 610       <function>brin_page_items</function> returns the data stored in the
 611       <acronym>BRIN</acronym> data page.  For example:
 612 <screen>
 613 test=# SELECT * FROM brin_page_items(get_raw_page('brinidx', 5),
 614                                      'brinidx')
 615        ORDER BY blknum, attnum LIMIT 6;
 616  itemoffset | blknum | attnum | allnulls | hasnulls | placeholder | empty |    value
 617 ------------+--------+--------+----------+----------+-------------+-------+--------------
 618         137 |      0 |      1 | t        | f        | f           | f     |
 619         137 |      0 |      2 | f        | f        | f           | f     | {1 .. 88}
 620         138 |      4 |      1 | t        | f        | f           | f     |
 621         138 |      4 |      2 | f        | f        | f           | f     | {89 .. 176}
 622         139 |      8 |      1 | t        | f        | f           | f     |
 623         139 |      8 |      2 | f        | f        | f           | f     | {177 .. 264}
 624 </screen>
 625       The returned columns correspond to the fields in the
 626       <structname>BrinMemTuple</structname> and <structname>BrinValues</structname> structs.
 627       See <filename>src/include/access/brin_tuple.h</filename> for details.
 628      </para>
 629     </listitem>
 630    </varlistentry>
 631   </variablelist>
 632  </sect2>
 633
 634  <sect2 id="pageinspect-gin-funcs">
 635   <title>GIN Functions</title>
 636
 637   <variablelist>
 638    <varlistentry>
 639     <term>
 640      <function>gin_metapage_info(page bytea) returns record</function>
 641      <indexterm>
 642       <primary>gin_metapage_info</primary>
 643      </indexterm>
 644     </term>
 645
 646     <listitem>
 647      <para>
 648       <function>gin_metapage_info</function> returns information about
 649       a <acronym>GIN</acronym> index metapage.  For example:
 650 <screen>
 651 test=# SELECT * FROM gin_metapage_info(get_raw_page('gin_index', 0));
 652 -[ RECORD 1 ]----+-----------
 653 pending_head     | 4294967295
 654 pending_tail     | 4294967295
 655 tail_free_size   | 0
 656 n_pending_pages  | 0
 657 n_pending_tuples | 0
 658 n_total_pages    | 7
 659 n_entry_pages    | 6
 660 n_data_pages     | 0
 661 n_entries        | 693
 662 version          | 2
 663 </screen>
 664      </para>
 665     </listitem>
 666    </varlistentry>
 667
 668    <varlistentry>
 669     <term>
 670      <function>gin_page_opaque_info(page bytea) returns record</function>
 671      <indexterm>
 672       <primary>gin_page_opaque_info</primary>
 673      </indexterm>
 674     </term>
 675
 676     <listitem>
 677      <para>
 678       <function>gin_page_opaque_info</function> returns information about
 679       a <acronym>GIN</acronym> index opaque area, like the page type.
 680       For example:
 681 <screen>
 682 test=# SELECT * FROM gin_page_opaque_info(get_raw_page('gin_index', 2));
 683  rightlink | maxoff |         flags
 684 -----------+--------+------------------------
 685          5 |      0 | {data,leaf,compressed}
 686 (1 row)
 687 </screen>
 688      </para>
 689     </listitem>
 690    </varlistentry>
 691
 692    <varlistentry>
 693     <term>
 694      <function>gin_leafpage_items(page bytea) returns setof record</function>
 695      <indexterm>
 696       <primary>gin_leafpage_items</primary>
 697      </indexterm>
 698     </term>
 699
 700     <listitem>
 701      <para>
 702       <function>gin_leafpage_items</function> returns information about
 703       the data stored in a <acronym>GIN</acronym> leaf page.  For example:
 704 <screen>
 705 test=# SELECT first_tid, nbytes, tids[0:5] AS some_tids
 706         FROM gin_leafpage_items(get_raw_page('gin_test_idx', 2));
 707  first_tid | nbytes |                        some_tids
 708 -----------+--------+----------------------------------------------------------
 709  (8,41)    |    244 | {"(8,41)","(8,43)","(8,44)","(8,45)","(8,46)"}
 710  (10,45)   |    248 | {"(10,45)","(10,46)","(10,47)","(10,48)","(10,49)"}
 711  (12,52)   |    248 | {"(12,52)","(12,53)","(12,54)","(12,55)","(12,56)"}
 712  (14,59)   |    320 | {"(14,59)","(14,60)","(14,61)","(14,62)","(14,63)"}
 713  (167,16)  |    376 | {"(167,16)","(167,17)","(167,18)","(167,19)","(167,20)"}
 714  (170,30)  |    376 | {"(170,30)","(170,31)","(170,32)","(170,33)","(170,34)"}
 715  (173,44)  |    197 | {"(173,44)","(173,45)","(173,46)","(173,47)","(173,48)"}
 716 (7 rows)
 717 </screen>
 718      </para>
 719     </listitem>
 720    </varlistentry>
 721   </variablelist>
 722  </sect2>
 723
 724  <sect2 id="pageinspect-gist-funcs">
 725   <title>GiST Functions</title>
 726
 727   <variablelist>
 728    <varlistentry>
 729     <term>
 730      <function>gist_page_opaque_info(page bytea) returns record</function>
 731      <indexterm>
 732       <primary>gist_page_opaque_info</primary>
 733      </indexterm>
 734     </term>
 735
 736     <listitem>
 737      <para>
 738       <function>gist_page_opaque_info</function> returns information from
 739       a <acronym>GiST</acronym> index page's opaque area, such as the NSN,
 740       rightlink and page type.
 741       For example:
 742 <screen>
 743 test=# SELECT * FROM gist_page_opaque_info(get_raw_page('test_gist_idx', 2));
 744  lsn | nsn | rightlink | flags
 745 -----+-----+-----------+--------
 746  0/1 | 0/0 |         1 | {leaf}
 747 (1 row)
 748 </screen>
 749      </para>
 750     </listitem>
 751    </varlistentry>
 752
 753    <varlistentry>
 754     <term>
 755      <function>gist_page_items(page bytea, index_oid regclass) returns setof record</function>
 756      <indexterm>
 757       <primary>gist_page_items</primary>
 758      </indexterm>
 759     </term>
 760
 761     <listitem>
 762      <para>
 763       <function>gist_page_items</function> returns information about
 764       the data stored in a page of a <acronym>GiST</acronym> index.  For example:
 765 <screen>
 766 test=# SELECT * FROM gist_page_items(get_raw_page('test_gist_idx', 0), 'test_gist_idx');
 767  itemoffset |   ctid    | itemlen | dead |             keys
 768 ------------+-----------+---------+------+-------------------------------
 769           1 | (1,65535) |      40 | f    | (p)=("(185,185),(1,1)")
 770           2 | (2,65535) |      40 | f    | (p)=("(370,370),(186,186)")
 771           3 | (3,65535) |      40 | f    | (p)=("(555,555),(371,371)")
 772           4 | (4,65535) |      40 | f    | (p)=("(740,740),(556,556)")
 773           5 | (5,65535) |      40 | f    | (p)=("(870,870),(741,741)")
 774           6 | (6,65535) |      40 | f    | (p)=("(1000,1000),(871,871)")
 775 (6 rows)
 776 </screen>
 777      </para>
 778     </listitem>
 779    </varlistentry>
 780
 781    <varlistentry>
 782     <term>
 783      <function>gist_page_items_bytea(page bytea) returns setof record</function>
 784      <indexterm>
 785       <primary>gist_page_items_bytea</primary>
 786      </indexterm>
 787     </term>
 788
 789     <listitem>
 790      <para>
 791       Same as <function>gist_page_items</function>, but returns the key data
 792       as a raw <type>bytea</type> blob.  Since it does not attempt to decode
 793       the key, it does not need to know which index is involved.  For
 794       example:
 795 <screen>
 796 test=# SELECT * FROM gist_page_items_bytea(get_raw_page('test_gist_idx', 0));
 797  itemoffset |   ctid    | itemlen | dead |                                      key_data
 798 ------------+-----------+---------+------+-----------------------------------------&zwsp;-------------------------------------------
 799           1 | (1,65535) |      40 | f    | \x00000100ffff28000000000000c0644000000000&zwsp;00c06440000000000000f03f000000000000f03f
 800           2 | (2,65535) |      40 | f    | \x00000200ffff28000000000000c0744000000000&zwsp;00c074400000000000e064400000000000e06440
 801           3 | (3,65535) |      40 | f    | \x00000300ffff28000000000000207f4000000000&zwsp;00207f400000000000d074400000000000d07440
 802           4 | (4,65535) |      40 | f    | \x00000400ffff28000000000000c0844000000000&zwsp;00c084400000000000307f400000000000307f40
 803           5 | (5,65535) |      40 | f    | \x00000500ffff28000000000000f0894000000000&zwsp;00f089400000000000c884400000000000c88440
 804           6 | (6,65535) |      40 | f    | \x00000600ffff28000000000000208f4000000000&zwsp;00208f400000000000f889400000000000f88940
 805           7 | (7,65535) |      40 | f    | \x00000700ffff28000000000000408f4000000000&zwsp;00408f400000000000288f400000000000288f40
 806 (7 rows)
 807 </screen>
 808      </para>
 809     </listitem>
 810    </varlistentry>
 811   </variablelist>
 812  </sect2>
 813
 814  <sect2 id="pageinspect-hash-funcs">
 815   <title>Hash Functions</title>
 816
 817   <variablelist>
 818    <varlistentry>
 819     <term>
 820      <function>hash_page_type(page bytea) returns text</function>
 821      <indexterm>
 822       <primary>hash_page_type</primary>
 823      </indexterm>
 824     </term>
 825
 826     <listitem>
 827      <para>
 828       <function>hash_page_type</function> returns page type of
 829       the given <acronym>HASH</acronym> index page.  For example:
 830 <screen>
 831 test=# SELECT hash_page_type(get_raw_page('con_hash_index', 0));
 832  hash_page_type
 833 ----------------
 834  metapage
 835 </screen>
 836      </para>
 837     </listitem>
 838    </varlistentry>
 839
 840    <varlistentry>
 841     <term>
 842      <function>hash_page_stats(page bytea) returns setof record</function>
 843      <indexterm>
 844       <primary>hash_page_stats</primary>
 845      </indexterm>
 846     </term>
 847
 848     <listitem>
 849      <para>
 850       <function>hash_page_stats</function> returns information about
 851       a bucket or overflow page of a <acronym>HASH</acronym> index.
 852       For example:
 853 <screen>
 854 test=# SELECT * FROM hash_page_stats(get_raw_page('con_hash_index', 1));
 855 -[ RECORD 1 ]---+-----------
 856 live_items      | 407
 857 dead_items      | 0
 858 page_size       | 8192
 859 free_size       | 8
 860 hasho_prevblkno | 4096
 861 hasho_nextblkno | 8474
 862 hasho_bucket    | 0
 863 hasho_flag      | 66
 864 hasho_page_id   | 65408
 865 </screen>
 866      </para>
 867     </listitem>
 868    </varlistentry>
 869
 870    <varlistentry>
 871     <term>
 872      <function>hash_page_items(page bytea) returns setof record</function>
 873      <indexterm>
 874       <primary>hash_page_items</primary>
 875      </indexterm>
 876     </term>
 877
 878     <listitem>
 879      <para>
 880       <function>hash_page_items</function> returns information about
 881       the data stored in a bucket or overflow page of a <acronym>HASH</acronym>
 882       index page.  For example:
 883 <screen>
 884 test=# SELECT * FROM hash_page_items(get_raw_page('con_hash_index', 1)) LIMIT 5;
 885  itemoffset |   ctid    |    data
 886 ------------+-----------+------------
 887           1 | (899,77)  | 1053474816
 888           2 | (897,29)  | 1053474816
 889           3 | (894,207) | 1053474816
 890           4 | (892,159) | 1053474816
 891           5 | (890,111) | 1053474816
 892 </screen>
 893      </para>
 894     </listitem>
 895    </varlistentry>
 896
 897    <varlistentry>
 898     <term>
 899      <function>hash_bitmap_info(index oid, blkno bigint) returns record</function>
 900      <indexterm>
 901       <primary>hash_bitmap_info</primary>
 902      </indexterm>
 903     </term>
 904
 905     <listitem>
 906      <para>
 907       <function>hash_bitmap_info</function> shows the status of a bit
 908       in the bitmap page for a particular overflow page of <acronym>HASH</acronym>
 909       index. For example:
 910 <screen>
 911 test=# SELECT * FROM hash_bitmap_info('con_hash_index', 2052);
 912  bitmapblkno | bitmapbit | bitstatus
 913 -------------+-----------+-----------
 914           65 |         3 | t
 915 </screen>
 916      </para>
 917     </listitem>
 918    </varlistentry>
 919
 920    <varlistentry>
 921     <term>
 922      <function>hash_metapage_info(page bytea) returns record</function>
 923      <indexterm>
 924       <primary>hash_metapage_info</primary>
 925      </indexterm>
 926     </term>
 927
 928     <listitem>
 929      <para>
 930       <function>hash_metapage_info</function> returns information stored
 931       in the meta page of a <acronym>HASH</acronym> index.  For example:
 932 <screen>
 933 test=# SELECT magic, version, ntuples, ffactor, bsize, bmsize, bmshift,
 934 test-#     maxbucket, highmask, lowmask, ovflpoint, firstfree, nmaps, procid,
 935 test-#     regexp_replace(spares::text, '(,0)*}', '}') as spares,
 936 test-#     regexp_replace(mapp::text, '(,0)*}', '}') as mapp
 937 test-# FROM hash_metapage_info(get_raw_page('con_hash_index', 0));
 938 -[ RECORD 1 ]-------------------------------------------------&zwsp;------------------------------
 939 magic     | 105121344
 940 version   | 4
 941 ntuples   | 500500
 942 ffactor   | 40
 943 bsize     | 8152
 944 bmsize    | 4096
 945 bmshift   | 15
 946 maxbucket | 12512
 947 highmask  | 16383
 948 lowmask   | 8191
 949 ovflpoint | 28
 950 firstfree | 1204
 951 nmaps     | 1
 952 procid    | 450
 953 spares    | {0,0,0,0,0,0,1,1,1,1,1,1,1,1,3,4,4,4,45,55,58,59,&zwsp;508,567,628,704,1193,1202,1204}
 954 mapp      | {65}
 955 </screen>
 956      </para>
 957     </listitem>
 958    </varlistentry>
 959   </variablelist>
 960  </sect2>
 961
 962 </sect1>