Skip to content

Commit 5b9c1e6

Browse files
committed
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.
1 parent f70f095 commit 5b9c1e6

File tree

2 files changed

+42
-5
lines changed

2 files changed

+42
-5
lines changed

doc/src/sgml/maintenance.sgml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,11 @@
101101
<productname>PostgreSQL</productname> query planner.</simpara>
102102
</listitem>
103103

104+
<listitem>
105+
<simpara>To update the visibility map, which speeds up index-only
106+
scans.</simpara>
107+
</listitem>
108+
104109
<listitem>
105110
<simpara>To protect against loss of very old data due to
106111
<firstterm>transaction ID wraparound</>.</simpara>
@@ -329,6 +334,33 @@
329334
</tip>
330335
</sect2>
331336

337+
<sect2 id="vacuum-for-visibility-map">
338+
<title>Updating The Visibility Map</title>
339+
340+
<para>
341+
Vacuum maintains a <link linkend="storage-vm">visibility map</> for each
342+
table to keep track of which pages contain only tuples that are known to be
343+
visible to all active transactions (and all future transactions, until the
344+
page is again modified). This has two purposes. First, vacuum
345+
itself can skip such pages on the next run, since there is nothing to
346+
clean up.
347+
</para>
348+
349+
<para>
350+
Second, it allows <productname>PostgreSQL</productname> to answer some
351+
queries using only the index, without reference to the underlying table.
352+
Since <productname>PostgreSQL</productname> indexes don't contain tuple
353+
visibility information, a normal index scan fetches the heap tuple for each
354+
matching index entry, to check whether it should be seen by the current
355+
transaction. An <firstterm>index-only scan</>, on the other hand, checks
356+
the visibility map first. If it's known that all tuples on the page are
357+
visible, the heap fetch can be skipped. This is most noticeable on
358+
large data sets where the visibility map can prevent disk accesses.
359+
The visibility map is vastly smaller than the heap, so it can easily be
360+
cached even when the heap is very large.
361+
</para>
362+
</sect2>
363+
332364
<sect2 id="vacuum-for-wraparound">
333365
<title>Preventing Transaction ID Wraparound Failures</title>
334366

doc/src/sgml/storage.sgml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -494,11 +494,16 @@ Note that indexes do not have VMs.
494494
<para>
495495
The visibility map simply stores one bit per heap page. A set bit means
496496
that all tuples on the page are known to be visible to all transactions.
497-
This means that the page does not contain any tuples that need to be vacuumed;
498-
in future it might also be used to avoid visiting the page for visibility
499-
checks. The map is conservative in the sense that we
500-
make sure that whenever a bit is set, we know the condition is true, but if
501-
a bit is not set, it might or might not be true.
497+
This means that the page does not contain any tuples that need to be vacuumed.
498+
This information can also be used by <firstterm>index-only scans</> to answer
499+
queries using only the index tuple.
500+
</para>
501+
502+
<para>
503+
The map is conservative in the sense that we make sure that whenever a bit is
504+
set, we know the condition is true, but if a bit is not set, it might or
505+
might not be true. Visibility map bits are only set by vacuum, but are
506+
cleared by any data-modifying operations on a page.
502507
</para>
503508

504509
</sect1>

0 commit comments

Comments
 (0)