From 970ff81e2f7b611c95e3be913e2b1169e9ec033d Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 29 May 2002 17:36:40 +0000
Subject: [PATCH] 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.

---
 doc/src/sgml/xindex.sgml | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index dcb5f9b6517..c6bfb0e19f3 100644
--- 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