Doc updates for index-only scans.

Document that routine vacuuming is now also important for the purpose
of index-only scans; and mention in the section that describes the
visibility map that it is used to implement index-only scans.

Marti Raudsepp, with some changes by me.

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 03cc6c987a243d141b17c8a5957c37baf1085e17..93c3ff5f2bb004610c787713715f6db851e018c9 100644 (file)
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -101,6 +101,11 @@
       PostgreSQL query planner.
      
 
+     
+      To update the visibility map, which speeds up index-only
+      scans.
+     
+
      
       To protect against loss of very old data due to
       transaction ID wraparound.
@@ -329,6 +334,33 @@
    
   
 
+  
+   Updating The Visibility Map
+
+   
+    Vacuum maintains a visibility map for each
+    table to keep track of which pages contain only tuples that are known to be
+    visible to all active transactions (and all future transactions, until the
+    page is again modified).  This has two purposes.  First, vacuum
+    itself can skip such pages on the next run, since there is nothing to
+    clean up.
+   
+
+   
+    Second, it allows PostgreSQL to answer some
+    queries using only the index, without reference to the underlying table.
+    Since PostgreSQL indexes don't contain tuple
+    visibility information, a normal index scan fetches the heap tuple for each
+    matching index entry, to check whether it should be seen by the current
+    transaction.  An index-only scan, on the other hand, checks
+    the visibility map first.  If it's known that all tuples on the page are
+    visible, the heap fetch can be skipped.  This is most noticeable on
+    large data sets where the visibility map can prevent disk accesses.
+    The visibility map is vastly smaller than the heap, so it can easily be
+    cached even when the heap is very large.
+   
+  
+
   
    Preventing Transaction ID Wraparound Failures
 

diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 45223f563d77c1434ab11a99a814b6e594d02c54..bd2dca39fcbd229ea1c78952c8af1f9e45a51f3d 100644 (file)
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -494,11 +494,16 @@ Note that indexes do not have VMs.
 
 The visibility map simply stores one bit per heap page. A set bit means
 that all tuples on the page are known to be visible to all transactions.
-This means that the page does not contain any tuples that need to be vacuumed;
-in future it might also be used to avoid visiting the page for visibility
-checks. The map is conservative in the sense that we
-make sure that whenever a bit is set, we know the condition is true, but if
-a bit is not set, it might or might not be true.
+This means that the page does not contain any tuples that need to be vacuumed.
+This information can also be used by index-only scans to answer
+queries using only the index tuple.
+
+
+
+The map is conservative in the sense that we make sure that whenever a bit is
+set, we know the condition is true, but if a bit is not set, it might or
+might not be true. Visibility map bits are only set by vacuum, but are
+cleared by any data-modifying operations on a page.