| 1 |
<!-- doc/src/sgml/pgfreespacemap.sgml --> |
| 2 |
|
| 3 |
<sect1 id="pgfreespacemap" xreflabel="pg_freespacemap"> |
| 4 |
<title>pg_freespacemap — 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 in-use 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>[email protected]</email>. |
| 116 |
Rewritten in version 8.4 to suit new <acronym>FSM</acronym> implementation |
| 117 |
by Heikki Linnakangas <email>[email protected]</email> |
| 118 |
</para> |
| 119 |
</sect2> |
| 120 |
|
| 121 |
</sect1> |