Support INCLUDE'd columns in SP-GiST.

Not much to say here: does what it says on the tin.
We steal a previously-always-zero bit from the nextOffset
field of leaf index tuples in order to track whether there
is a nulls bitmap.  Otherwise it works about like included
columns in other index types.

Pavel Borisov, reviewed by Andrey Borodin and Anastasia Lubennikova,
and rather heavily editorialized on by me

Discussion: https://postgr.es/m/CALT9ZEFi-vMp4faht9f9Junb1nO3NOSjhpxTmbm1UGLMsLqiEQ@mail.gmail.com

Author: tglsfdc

doc/src/sgml/indices.sgml

@@ -409,9 +409,11 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor);
   </para>
 
   <para>
-   Currently, only the B-tree, GiST, GIN, and BRIN
-   index types support multicolumn
-   indexes.  Up to 32 columns can be specified.  (This limit can be
+   Currently, only the B-tree, GiST, GIN, and BRIN index types support
+   multiple-key-column indexes.  Whether there can be multiple key
+   columns is independent of whether <literal>INCLUDE</literal> columns
+   can be added to the index.  Indexes can have up to 32 columns,
+   including <literal>INCLUDE</literal> columns.  (This limit can be
    altered when building <productname>PostgreSQL</productname>; see the
    file <filename>pg_config_manual.h</filename>.)
   </para>
@@ -1208,8 +1210,8 @@ CREATE UNIQUE INDEX tab_x_y ON tab(x) INCLUDE (y);
    likely to not need to access the heap.  If the heap tuple must be visited
    anyway, it costs nothing more to get the column's value from there.
    Other restrictions are that expressions are not currently supported as
-   included columns, and that only B-tree and GiST indexes currently support
-   included columns.
+   included columns, and that only B-tree, GiST and SP-GiST indexes currently
+   support included columns.
   </para>
 
   <para>

doc/src/sgml/ref/create_index.sgml

@@ -187,8 +187,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
        </para>
 
        <para>
-        Currently, the B-tree and the GiST index access methods support this
-        feature.  In B-tree and the GiST indexes, the values of columns listed
+        Currently, the B-tree, GiST and SP-GiST index access methods support
+        this feature.  In these indexes, the values of columns listed
         in the <literal>INCLUDE</literal> clause are included in leaf tuples
         which correspond to heap tuples, but are not included in upper-level
         index entries used for tree navigation.
@@ -695,7 +695,10 @@ Indexes:
 
   <para>
    Currently, only the B-tree, GiST, GIN, and BRIN index methods support
-   multicolumn indexes. Up to 32 fields can be specified by default.
+   multiple-key-column indexes.  Whether there can be multiple key
+   columns is independent of whether <literal>INCLUDE</literal> columns
+   can be added to the index.  Indexes can have up to 32 columns,
+   including <literal>INCLUDE</literal> columns.
    (This limit can be altered when building
    <productname>PostgreSQL</productname>.)  Only B-tree currently
    supports unique indexes.

doc/src/sgml/spgist.sgml

@@ -216,6 +216,14 @@
   inner tuples that are passed through to reach the leaf level.
  </para>
 
+ <para>
+  When an <acronym>SP-GiST</acronym> index is created with
+  <literal>INCLUDE</literal> columns, the values of those columns are also
+  stored in leaf tuples.  The <literal>INCLUDE</literal> columns are of no
+  concern to the <acronym>SP-GiST</acronym> operator class, so they are
+  not discussed further here.
+ </para>
+
  <para>
   Inner tuples are more complex, since they are branching points in the
   search tree.  Each inner tuple contains a set of one or more

doc/src/sgml/xindex.sgml

@@ -1426,11 +1426,15 @@ CREATE OPERATOR CLASS polygon_ops
         STORAGE box;
 </programlisting>
 
-   At present, only the GiST, GIN and BRIN index methods support a
+   At present, only the GiST, SP-GiST, GIN and BRIN index methods support a
    <literal>STORAGE</literal> type that's different from the column data type.
    The GiST <function>compress</function> and <function>decompress</function> support
    routines must deal with data-type conversion when <literal>STORAGE</literal>
-   is used.  In GIN, the <literal>STORAGE</literal> type identifies the type of
+   is used.  SP-GiST likewise requires a <function>compress</function>
+   support function to convert to the storage type, when that is different;
+   if an SP-GiST opclass also supports retrieving data, the reverse
+   conversion must be handled by the <function>consistent</function> function.
+   In GIN, the <literal>STORAGE</literal> type identifies the type of
    the <quote>key</quote> values, which normally is different from the type
    of the indexed column &mdash; for example, an operator class for
    integer-array columns might have keys that are just integers.  The

src/backend/access/common/indextuple.c

@@ -446,22 +446,37 @@ void
 index_deform_tuple(IndexTuple tup, TupleDesc tupleDescriptor,
 				   Datum *values, bool *isnull)
 {
-	int			hasnulls = IndexTupleHasNulls(tup);
-	int			natts = tupleDescriptor->natts; /* number of atts to extract */
-	int			attnum;
 	char	   *tp;				/* ptr to tuple data */
-	int			off;			/* offset in tuple data */
 	bits8	   *bp;				/* ptr to null bitmap in tuple */
-	bool		slow = false;	/* can we use/set attcacheoff? */
-
-	/* Assert to protect callers who allocate fixed-size arrays */
-	Assert(natts <= INDEX_MAX_KEYS);
 
 	/* XXX "knows" t_bits are just after fixed tuple header! */
 	bp = (bits8 *) ((char *) tup + sizeof(IndexTupleData));
 
 	tp = (char *) tup + IndexInfoFindDataOffset(tup->t_info);
-	off = 0;
+
+	index_deform_tuple_internal(tupleDescriptor, values, isnull,
+								tp, bp, IndexTupleHasNulls(tup));
+}
+
+/*
+ * Convert an index tuple into Datum/isnull arrays,
+ * without assuming any specific layout of the index tuple header.
+ *
+ * Caller must supply pointer to data area, pointer to nulls bitmap
+ * (which can be NULL if !hasnulls), and hasnulls flag.
+ */
+void
+index_deform_tuple_internal(TupleDesc tupleDescriptor,
+							Datum *values, bool *isnull,
+							char *tp, bits8 *bp, int hasnulls)
+{
+	int			natts = tupleDescriptor->natts; /* number of atts to extract */
+	int			attnum;
+	int			off = 0;		/* offset in tuple data */
+	bool		slow = false;	/* can we use/set attcacheoff? */
+
+	/* Assert to protect callers who allocate fixed-size arrays */
+	Assert(natts <= INDEX_MAX_KEYS);
 
 	for (attnum = 0; attnum < natts; attnum++)
 	{

src/backend/access/spgist/README

@@ -56,7 +56,7 @@ list and there is no free space on page, then SP-GiST creates a new inner
 tuple and distributes leaf tuples into a set of lists on, perhaps, several
 pages.
 
-Inner tuple consists of:
+An inner tuple consists of:
 
   optional prefix value - all successors must be consistent with it.
     Example:
@@ -67,14 +67,26 @@ Inner tuple consists of:
   list of nodes, where node is a (label, pointer) pair.
     Example of a label: a single character for radix tree
 
-Leaf tuple consists of:
+A leaf tuple consists of:
 
   a leaf value
     Example:
         radix tree - the rest of string (postfix)
         quad and k-d tree - the point itself
 
-  ItemPointer to the heap
+  ItemPointer to the corresponding heap tuple
+  nextOffset number of next leaf tuple in a chain on a leaf page
+
+  optional nulls bitmask
+  optional INCLUDE-column values
+
+For compatibility with pre-v14 indexes, a leaf tuple has a nulls bitmask
+only if there are null values (among the leaf value and the INCLUDE values)
+*and* there is at least one INCLUDE column.  The null-ness of the leaf
+value can be inferred from whether the tuple is on a "nulls page" (see below)
+so it is not necessary to represent it explicitly.  But we include it anyway
+in a bitmask used with INCLUDE values, so that standard tuple deconstruction
+code can be used.
 
 
 NULLS HANDLING