Doc: Update the documentation for FSM behavior for small tables.

In commit b0eaa4c51b, we have avoided the creation of FSM for small tables.
So the functions that use FSM to compute the free space can return zero for
such tables.  This was previously also possible for the cases where the
vacuum has not been triggered to update FSM.

This commit updates the comments in code and documentation to reflect this
behavior.

Author: John Naylor
Reviewed-by: Amit Kapila
Discussion: https://postgr.es/m/CACPNZCtba-3m1q3A8gxA_vxg=T7gQf7gMbpR4Ciy5LntY-j+0Q@mail.gmail.com

diff --git a/contrib/pgstattuple/pgstatapprox.c b/contrib/pgstattuple/pgstatapprox.c
index ff7c255a2de1fba9033ad8c88ac5cabc7f373c4d..d36758af9a6a6dccefa10d4149bceee6c04e9d7b 100644 (file)
--- a/contrib/pgstattuple/pgstatapprox.c
+++ b/contrib/pgstattuple/pgstatapprox.c
@@ -89,6 +89,9 @@ statapprox_heap(Relation rel, output_type *stat)
                /*
                 * If the page has only visible tuples, then we can find out the free
                 * space from the FSM and move on.
+                *
+                * Note: If a relation has no FSM, GetRecordedFreeSpace() will report
+                * zero free space.  This is fine for the purposes of approximation.
                 */
                if (VM_ALL_VISIBLE(rel, blkno, &vmbuffer))
                {

diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 0122d278e39e7b41b0b811f6cdeef8e45c6538c2..0bcf79b02b47132aa61cc3d4cfd83aa84d47b82f 100644 (file)
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -61,6 +61,8 @@
    The values stored in the free space map are not exact. They're rounded
    to precision of 1/256th of <symbol>BLCKSZ</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), and
    they're not kept fully up-to-date as tuples are inserted and updated.
+   In addition, small tables don't have a free space map, so these functions
+   will return zero even if free space is available.
   </para>
 
   <para>

diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
index b17b3c59e0d4ddbadd574e9f9458caeedde9c32e..8797131c6437eff1afd6dea243b413c858b8a056 100644 (file)
--- a/doc/src/sgml/pgstattuple.sgml
+++ b/doc/src/sgml/pgstattuple.sgml
@@ -527,7 +527,9 @@ approx_free_percent  | 2.09
       bit set, then it is assumed to contain no dead tuples). For such
       pages, it derives the free space value from the free space map, and
       assumes that the rest of the space on the page is taken up by live
-      tuples.
+      tuples. Small tables don't have a free space map, so in that case
+      this function will report zero free space, likewise inflating the
+      approximate tuple length.
      </para>
 
      <para>