Teach the planner to support index access methods that only implement

amgettuple or only implement amgetbitmap, instead of the former assumption
that every AM supports both APIs.  Extracted with minor editorialization
from Teodor's fast-GIN-insert patch; whatever becomes of that, this seems
like a simple and reasonable generalization of the index AM interface spec.

doc/src/sgml/catalogs.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.198 2009/02/24 10:06:31 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.199 2009/03/05 23:06:45 tgl Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -493,14 +493,14 @@
       <entry><structfield>amgettuple</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry><quote>Next valid tuple</quote> function</entry>
+      <entry><quote>Next valid tuple</quote> function, or zero if none</entry>
      </row>
 
      <row>
       <entry><structfield>amgetbitmap</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry><quote>Fetch all valid tuples</quote> function</entry>
+      <entry><quote>Fetch all valid tuples</quote> function, or zero if none</entry>
      </row>
 
      <row>

doc/src/sgml/indexam.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.28 2008/10/17 22:10:29 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.29 2009/03/05 23:06:45 tgl Exp $ -->
 
 <chapter id="indexam">
  <title>Index Access Method Interface Definition</title>
@@ -37,8 +37,10 @@
    extant versions of the same logical row; to an index, each tuple is
    an independent object that needs its own index entry.  Thus, an
    update of a row always creates all-new index entries for the row, even if
-   the key values did not change.  Index entries for dead tuples are
-   reclaimed (by vacuuming) when the dead tuples themselves are reclaimed.
+   the key values did not change.  (HOT tuples are an exception to this
+   statement; but indexes do not deal with those, either.)  Index entries for
+   dead tuples are reclaimed (by vacuuming) when the dead tuples themselves
+   are reclaimed.
   </para>
 
  <sect1 id="index-catalog">
@@ -266,7 +268,7 @@ amoptions (ArrayType *reloptions,
    The function should construct a <type>bytea</> value, which will be copied
    into the <structfield>rd_options</> field of the index's relcache entry.
    The data contents of the <type>bytea</> value are open for the access
-   method to define, but the standard access methods currently all use struct
+   method to define; most of the standard access methods use struct
    <structname>StdRdOptions</>.
    When <parameter>validate</> is true, the function should report a suitable
    error message if any of the options are unrecognized or have invalid
@@ -283,8 +285,9 @@ amoptions (ArrayType *reloptions,
    an indexable <literal>WHERE</> condition, often called a
    <firstterm>qualifier</> or <firstterm>scan key</>.  The semantics of
    index scanning are described more fully in <xref linkend="index-scanning">,
-   below.  The scan-related functions that an index access method must provide
-   are:
+   below.  An index access method can support <quote>plain</> index scans,
+   <quote>bitmap</> index scans, or both.  The scan-related functions that an
+   index access method must or may provide are:
   </para>
 
   <para>
@@ -326,6 +329,13 @@ amgettuple (IndexScanDesc scan,
    callers.
   </para>
 
+  <para>
+   The <function>amgettuple</> function need only be provided if the access
+   method supports <quote>plain</> index scans.  If it doesn't, the
+   <structfield>amgettuple</> field in its <structname>pg_am</> row must
+   be set to zero.
+  </para>
+
   <para>
 <programlisting>
 int64
@@ -349,6 +359,13 @@ amgetbitmap (IndexScanDesc scan,
    in <xref linkend="index-scanning">.
   </para>
 
+  <para>
+   The <function>amgetbitmap</> function need only be provided if the access
+   method supports <quote>bitmap</> index scans.  If it doesn't, the
+   <structfield>amgetbitmap</> field in its <structname>pg_am</> row must
+   be set to zero.
+  </para>
+
   <para>
 <programlisting>
 void
@@ -519,6 +536,12 @@ amrestrpos (IndexScanDesc scan);
    spelled out in <xref linkend="index-locking">.
   </para>
 
+  <para>
+   Note that it is permitted for an access method to implement only
+   <function>amgetbitmap</> and not <function>amgettuple</>, or vice versa,
+   if its internal implementation is unsuited to one API or the other.
+  </para>
+
  </sect1>
 
  <sect1 id="index-locking">