granicus.if.org Git - postgresql/blob - doc/src/sgml/pgfreespacemap.sgml

   1 <!-- doc/src/sgml/pgfreespacemap.sgml -->
   2
   3 <sect1 id="pgfreespacemap" xreflabel="pg_freespacemap">
   4  <title>pg_freespacemap</title>
   5
   6  <indexterm zone="pgfreespacemap">
   7   <primary>pg_freespacemap</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pg_freespacemap</> module provides a means for examining the
  12   free space map (FSM). It provides a function called
  13   <function>pg_freespace</function>, or two overloaded functions, to be
  14   precise. The functions show the value recorded in the free space map for
  15   a given page, or for all pages in the relation.
  16  </para>
  17
  18  <para>
  19   By default use is restricted to superusers and members of the
  20   <literal>pg_stat_scan_tables</literal> role. Access may be granted to others
  21   using <command>GRANT</command>.
  22  </para>
  23
  24  <sect2>
  25   <title>Functions</title>
  26
  27   <variablelist>
  28    <varlistentry>
  29     <term>
  30      <function>pg_freespace(rel regclass IN, blkno bigint IN) returns int2</function>
  31      <indexterm>
  32       <primary>pg_freespace</primary>
  33      </indexterm>
  34     </term>
  35
  36     <listitem>
  37      <para>
  38       Returns the amount of free space on the page of the relation, specified
  39       by <literal>blkno</>, according to the FSM.
  40      </para>
  41     </listitem>
  42    </varlistentry>
  43
  44
  45    <varlistentry>
  46     <term>
  47      <function>pg_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)</function>
  48     </term>
  49
  50     <listitem>
  51      <para>
  52       Displays the amount of free space on each page of the relation,
  53       according to the FSM. A set of <literal>(blkno bigint, avail int2)</>
  54       tuples is returned, one tuple for each page in the relation.
  55      </para>
  56     </listitem>
  57    </varlistentry>
  58   </variablelist>
  59
  60   <para>
  61    The values stored in the free space map are not exact. They're rounded
  62    to precision of 1/256th of <symbol>BLCKSZ</> (32 bytes with default <symbol>BLCKSZ</>), and
  63    they're not kept fully up-to-date as tuples are inserted and updated.
  64   </para>
  65
  66   <para>
  67    For indexes, what is tracked is entirely-unused pages, rather than free
  68    space within pages.  Therefore, the values are not meaningful, just
  69    whether a page is full or empty.
  70   </para>
  71
  72   <note>
  73    <para>
  74     The interface was changed in version 8.4, to reflect the new FSM
  75     implementation introduced in the same version.
  76    </para>
  77   </note>
  78  </sect2>
  79
  80  <sect2>
  81   <title>Sample Output</title>
  82
  83 <screen>
  84 postgres=# SELECT * FROM pg_freespace('foo');
  85  blkno | avail
  86 -------+-------
  87      0 |     0
  88      1 |     0
  89      2 |     0
  90      3 |    32
  91      4 |   704
  92      5 |   704
  93      6 |   704
  94      7 |  1216
  95      8 |   704
  96      9 |   704
  97     10 |   704
  98     11 |   704
  99     12 |   704
 100     13 |   704
 101     14 |   704
 102     15 |   704
 103     16 |   704
 104     17 |   704
 105     18 |   704
 106     19 |  3648
 107 (20 rows)
 108
 109 postgres=# SELECT * FROM pg_freespace('foo', 7);
 110  pg_freespace
 111 --------------
 112          1216
 113 (1 row)
 114 </screen>
 115  </sect2>
 116
 117  <sect2>
 118   <title>Author</title>
 119
 120   <para>
 121    Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
 122    Rewritten in version 8.4 to suit new FSM implementation by Heikki
 123    Linnakangas <email>heikki@enterprisedb.com</email>
 124   </para>
 125  </sect2>
 126
 127 </sect1>