doc/src/sgml/pgfreespacemap.sgml

   1 <!-- doc/src/sgml/pgfreespacemap.sgml -->
   2
   3 <sect1 id="pgfreespacemap" xreflabel="pg_freespacemap">
   4  <title>pg_freespacemap &mdash; examine the free space map</title>
   5
   6  <indexterm zone="pgfreespacemap">
   7   <primary>pg_freespacemap</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pg_freespacemap</filename> module provides a means for examining the
  12   <link linkend="storage-fsm">free space map</link> (<acronym>FSM</acronym>).
  13   It provides a function called <function>pg_freespace</function>, or two
  14   overloaded functions, to be precise. The functions show the value recorded in
  15   the free space map for a given page, or for all pages in the relation.
  16  </para>
  17
  18  <para>
  19   By default use is restricted to superusers and roles with privileges 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 id="pgfreespacemap-funcs">
  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</literal>, according to the <acronym>FSM</acronym>.
  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 <acronym>FSM</acronym>. A set of
  54       <literal>(blkno bigint, avail int2)</literal>
  55       tuples is returned, one tuple for each page in the relation.
  56      </para>
  57     </listitem>
  58    </varlistentry>
  59   </variablelist>
  60
  61   <para>
  62    The values stored in the free space map are not exact. They're rounded
  63    to precision of 1/256th of <symbol>BLCKSZ</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), and
  64    they're not kept fully up-to-date as tuples are inserted and updated.
  65   </para>
  66
  67   <para>
  68    For indexes, what is tracked is entirely-unused pages, rather than free
  69    space within pages.  Therefore, the values are not meaningful, just
  70    whether a page is full or empty.
  71   </para>
  72  </sect2>
  73
  74  <sect2 id="pgfreespacemap-sample-output">
  75   <title>Sample Output</title>
  76
  77 <screen>
  78 postgres=# SELECT * FROM pg_freespace('foo');
  79  blkno | avail
  80 -------+-------
  81      0 |     0
  82      1 |     0
  83      2 |     0
  84      3 |    32
  85      4 |   704
  86      5 |   704
  87      6 |   704
  88      7 |  1216
  89      8 |   704
  90      9 |   704
  91     10 |   704
  92     11 |   704
  93     12 |   704
  94     13 |   704
  95     14 |   704
  96     15 |   704
  97     16 |   704
  98     17 |   704
  99     18 |   704
 100     19 |  3648
 101 (20 rows)
 102
 103 postgres=# SELECT * FROM pg_freespace('foo', 7);
 104  pg_freespace
 105 --------------
 106          1216
 107 (1 row)
 108 </screen>
 109  </sect2>
 110
 111  <sect2 id="pgfreespacemap-author">
 112   <title>Author</title>
 113
 114   <para>
 115    Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
 116    Rewritten in version 8.4 to suit new <acronym>FSM</acronym> implementation
 117    by Heikki Linnakangas <email>heikki@enterprisedb.com</email>
 118   </para>
 119  </sect2>
 120
 121 </sect1>