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 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.24 2002/04/17 20:57:56 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.25 2002/05/29 17:36:40 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -105,6 +105,22 @@ PostgreSQL documentation
    </table>
   </para>
 
+  <note>
+   <para>
+    An index AM that supports multiple columns (has
+    <structfield>amcanmulticol</structfield> true) <emphasis>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.)
+    <structfield>amindexnulls</structfield> should be set true only if the
+    index AM indexes all rows, including arbitrary combinations of nulls.
+   </para>
+  </note>
+
   <para>
    The <acronym>OID</acronym> of the row in
    <filename>pg_am</filename> is used as a foreign key in a lot of other