Add a note about the interpretation of amcanmulticol and amindexnulls:

a multicolumn-capable index AM *must* support nulls in index columns
after the first one.

diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index dcb5f9b65170e8f0cd8d7f3e1ca61691fbdf17e6..c6bfb0e19f37495617d005873dab4d31ed522cca 100644 (file)
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -1,5 +1,5 @@
 
 
@@ -105,6 +105,22 @@ PostgreSQL documentation
    
   
 
+  
+   
+    An index AM that supports multiple columns (has
+    amcanmulticol true) must
+    support indexing nulls in columns after the first, because the planner
+    will assume the index can be used for queries on just the first
+    column(s).  For example, consider an index on (a,b) and a query
+    WHERE a = 4.  The system will assume the index can be used to scan for
+    rows with a = 4, which is wrong if the index omits rows where b is null.
+    However it is okay to omit rows where the first indexed column is null.
+    (GiST currently does so.)
+    amindexnulls should be set true only if the
+    index AM indexes all rows, including arbitrary combinations of nulls.
+   
+  
+
   
    The OID of the row in
    pg_am is used as a foreign key in a lot of other