Add knn support to btree indexes

This commit implements support for knn scans in btree indexes.  When knn search
is requested, btree index is traversed ascending and descending simultaneously.
At each step the closest tuple is returned.  Filtering operators can reduce
knn to regular ordered scan.

Ordering operators are added to opfamilies of scalar datatypes.  No extra
supporting functions are required: knn-btree algorithm works using comparison
function and ordering operator itself.

Distance operators are not leakproof, because they throw error on overflow.
Therefore we relax opr_sanity check for btree ordering operators.  It's OK for
them to be leaky while comparison function is leakproof.

Catversion is bumped.

Discussion: https://postgr.es/m/ce35e97b-cf34-3f5d-6b99-2c25bae49999%40postgrespro.ru
Author: Nikita Glukhov
Reviewed-by: Robert Haas, Tom Lane, Anastasia Lubennikova, Alexander Korotkov

Author: antamel

doc/src/sgml/btree.sgml

@@ -200,6 +200,53 @@
   planner relies on them for optimization purposes.
  </para>
 
+ <para>
+  In order to implement the distance ordered (nearest-neighbor) search,
+  one needs to define a distance operator (usually it's called
+  <literal>&lt;-&gt;</literal>) with a correpsonding operator family for
+  distance comparison in the operator class.  These operators must
+  satisfy the following assumptions for all non-null values
+  <replaceable>A</replaceable>, <replaceable>B</replaceable>,
+  <replaceable>C</replaceable> of the data type:
+
+  <itemizedlist>
+   <listitem>
+    <para>
+     <replaceable>A</replaceable> <literal>&lt;-&gt;</literal>
+     <replaceable>B</replaceable> <literal>=</literal>
+     <replaceable>B</replaceable> <literal>&lt;-&gt;</literal>
+     <replaceable>A</replaceable>
+     (<firstterm>symmetric law</firstterm>)
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     if <replaceable>A</replaceable> <literal>=</literal>
+     <replaceable>B</replaceable>, then <replaceable>A</replaceable>
+     <literal>&lt;-&gt;</literal> <replaceable>C</replaceable>
+     <literal>=</literal> <replaceable>B</replaceable>
+     <literal>&lt;-&gt;</literal> <replaceable>C</replaceable>
+     (<firstterm>distance equivalence</firstterm>)
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      if (<replaceable>A</replaceable> <literal>&lt;=</literal>
+      <replaceable>B</replaceable> and <replaceable>B</replaceable>
+      <literal>&lt;=</literal> <replaceable>C</replaceable>) or
+      (<replaceable>A</replaceable> <literal>&gt;=</literal>
+      <replaceable>B</replaceable> and <replaceable>B</replaceable>
+      <literal>&gt;=</literal> <replaceable>C</replaceable>),
+      then <replaceable>A</replaceable> <literal>&lt;-&gt;</literal>
+      <replaceable>B</replaceable> <literal>&lt;=</literal>
+      <replaceable>A</replaceable> <literal>&lt;-&gt;</literal>
+      <replaceable>C</replaceable>
+     (<firstterm>monotonicity</firstterm>)
+    </para>
+   </listitem>
+  </itemizedlist>
+ </para>
+
 </sect2>
 
 <sect2 id="btree-support-funcs">

doc/src/sgml/indices.sgml

@@ -1193,6 +1193,17 @@ SELECT x FROM tab WHERE x = 'key' AND z < 42;
    make this type of scan very useful in practice.
   </para>
 
+  <para>
+   B-tree indexes are also capable of optimizing <quote>nearest-neighbor</quote>
+   searches, such as
+<programlisting><![CDATA[
+SELECT * FROM events ORDER BY event_date <-> date '2017-05-05' LIMIT 10;
+]]>
+</programlisting>
+   which finds the ten events closest to a given target date.  The ability
+   to do this is again dependent on the particular operator class being used.
+  </para>
+
   <para>
    <indexterm>
     <primary><literal>INCLUDE</literal></primary>

doc/src/sgml/xindex.sgml

@@ -131,6 +131,10 @@
        <entry>greater than</entry>
        <entry>5</entry>
       </row>
+      <row>
+       <entry>distance</entry>
+       <entry>6</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
@@ -1320,7 +1324,8 @@ SELECT sum(x) OVER (ORDER BY x RANGE BETWEEN 5 PRECEDING AND 10 FOLLOWING)
   <title>Ordering Operators</title>
 
   <para>
-   Some index access methods (currently, only GiST and SP-GiST) support the concept of
+   Some index access methods (currently, B-tree, GiST and SP-GiST)
+   support the concept of
    <firstterm>ordering operators</firstterm>.  What we have been discussing so far
    are <firstterm>search operators</firstterm>.  A search operator is one for which
    the index can be searched to find all rows satisfying

src/backend/access/brin/brin_minmax.c

@@ -23,7 +23,7 @@
 typedef struct MinmaxOpaque
 {
 	Oid			cached_subtype;
-	FmgrInfo	strategy_procinfos[BTMaxStrategyNumber];
+	FmgrInfo	strategy_procinfos[BTMaxSearchStrategyNumber];
 } MinmaxOpaque;
 
 static FmgrInfo *minmax_get_strategy_procinfo(BrinDesc *bdesc, uint16 attno,
@@ -264,7 +264,7 @@ minmax_get_strategy_procinfo(BrinDesc *bdesc, uint16 attno, Oid subtype,
 	MinmaxOpaque *opaque;
 
 	Assert(strategynum >= 1 &&
-		   strategynum <= BTMaxStrategyNumber);
+		   strategynum <= BTMaxSearchStrategyNumber);
 
 	opaque = (MinmaxOpaque *) bdesc->bd_info[attno - 1]->oi_opaque;
 
@@ -277,7 +277,7 @@ minmax_get_strategy_procinfo(BrinDesc *bdesc, uint16 attno, Oid subtype,
 	{
 		uint16		i;
 
-		for (i = 1; i <= BTMaxStrategyNumber; i++)
+		for (i = 1; i <= BTMaxSearchStrategyNumber; i++)
 			opaque->strategy_procinfos[i - 1].fn_oid = InvalidOid;
 		opaque->cached_subtype = subtype;
 	}

src/backend/access/nbtree/README

@@ -1081,3 +1081,25 @@ item is irrelevant, and need not be stored at all.  This arrangement
 corresponds to the fact that an L&Y non-leaf page has one more pointer
 than key.  Suffix truncation's negative infinity attributes behave in
 the same way.
+
+Nearest-neighbor search
+-----------------------
+
+B-tree supports a special scan strategy for nearest-neighbor (kNN) search,
+which is used for queries with "ORDER BY indexed_column operator constant"
+clause.  See the following example.
+
+  SELECT * FROM tab WHERE col > const1 ORDER BY col <-> const2 LIMIT k
+
+Unlike GiST and SP-GiST, B-tree supports kNN by the only one ordering operator
+applied to the first indexed column.
+
+At the beginning of kNN scan, we determine the scan strategy to use: normal
+unidirectional or special bidirectional.  If the second distance operand falls
+into the scan range, then we use bidirectional scan, otherwise we use normal
+unidirectional scan.
+
+The bidirectional scan algorithm is quite simple.  We start both forward and
+backward scans starting from the tree location corresponding to the second
+distance operand.  Each time we need the next tuple, we return the nearest
+tuple from two directions and advance scan in corresponding direction.