From efe64c8d1ffbc0729de850c79a47c9d1ce62d54e Mon Sep 17 00:00:00 2001
From: Alexander Nestorov <alexandernst@gmail.com>
Date: Thu, 4 Jun 2026 00:09:08 +0200
Subject: [PATCH] doc: Document cross-type operator support in btree_gist

Note that as of btree_gist 1.10 the int2, int4 and int8 operator
classes accept cross-type query operators (the B-tree comparison
operators and the <-> distance operator) against the other two
integer types without an explicit cast, and that out-of-range query
constants are compared by normal integer semantics.

Also document that the integer <-> distance is computed in float8, so
for int8 distances beyond 2^53 the result loses precision and may
reorder nearly-equidistant matches; it never changes which rows match.
---
 doc/src/sgml/btree-gist.sgml | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml
index cc09ec83733..1b1dce707cf 100644
--- a/doc/src/sgml/btree-gist.sgml
+++ b/doc/src/sgml/btree-gist.sgml
@@ -49,12 +49,36 @@
   <type>float8</type>, <type>timestamp with time zone</type>,
   <type>timestamp without time zone</type>,
   <type>time without time zone</type>, <type>date</type>, <type>interval</type>,
   <type>oid</type>, and <type>money</type>.
  </para>
 
+ <para>
+  As of version 1.10, the operator classes for <type>int2</type>,
+  <type>int4</type> and <type>int8</type> additionally support cross-type
+  query operators. An index on any one of these integer types can be used
+  with a B-tree-style comparison (<literal>&lt;</literal>,
+  <literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal>,
+  <literal>&gt;</literal>, <literal>&lt;&gt;</literal>) or with the
+  distance operator (<literal>&lt;-&gt;</literal>) against a value of any
+  of the other two integer types, without an explicit cast. Query
+  constants outside the indexed column's range are compared according to
+  normal integer comparison semantics, without narrowing the query value
+  to the column type first.
+ </para>
+
+ <para>
+  The integer distance operator (<literal>&lt;-&gt;</literal>) used for
+  nearest-neighbor (<literal>ORDER BY</literal>) searches computes the
+  distance in <type>float8</type>. For <type>int8</type> values whose
+  distance from the query exceeds 2^53, the result loses precision and
+  may reorder results that are nearly equidistant; it never changes which
+  rows match. This applies equally to same-type and cross-type
+  <type>int8</type> distance searches.
+ </para>
+
  <para>
   By default <filename>btree_gist</filename> builds <acronym>GiST</acronym> index with
   <function>sortsupport</function> in <firstterm>sorted</firstterm> mode. This usually results in
   much faster index built speed. It is still possible to revert to buffered built strategy
   by using the <literal>buffering</literal> parameter when creating the index.
  </para>
-- 
2.51.0