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</filename> 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</literal>, 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)</literal>
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</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), 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>
84postgres=# 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
109postgres=# 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>
128