Doc: indexUnchanged is strictly a hint.

Clearly spell out the limitations of aminsert()'s indexUnchanged hinting
mechanism in the index AM documentation.

Oversight in commit 9dc718bd, which added the "logically unchanged
index" hint (which is used to trigger bottom-up index deletion).

Author: Peter Geoghegan <pg@bowt.ie>
Reported-By: Tom Lane <tgl@sss.pgh.pa.us>
Reviewed-By: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAH2-WzmU_BQ=-H9L+bxTSMQBqHMjp1DSwGypvL0gKs+dTOfkKg@mail.gmail.com
Backpatch: 14-, where indexUnchanged hinting was introduced.

diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 4f83970c85147e4e6f629df3a9469f121a48c59b..1a787179a3427cf150af74a7c781275016d2f147 100644 (file)
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -319,9 +319,13 @@ aminsert (Relation indexRelation,
    modify any columns covered by the index, but nevertheless requires a
    new version in the index.  The index AM may use this hint to decide
    to apply bottom-up index deletion in parts of the index where many
-   versions of the same logical row accumulate.  Note that updating a
-   non-key column does not affect the value of
-   <literal>indexUnchanged</literal>.
+   versions of the same logical row accumulate.  Note that updating a non-key
+   column or a column that only appears in a partial index predicate does not
+   affect the value of <literal>indexUnchanged</literal>.  The core code
+   determines each tuple's <literal>indexUnchanged</literal> value using a low
+   overhead approach that allows both false positives and false negatives.
+   Index AMs must not treat <literal>indexUnchanged</literal> as an
+   authoritative source of information about tuple visibility or versioning.
   </para>
 
   <para>