From 42b7a0d4ea8f2857f0e40ac495c3e44524b091b2 Mon Sep 17 00:00:00 2001 From: Alexander Nestorov 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 nearest-neighbor index scans on these operator classes order rows by a distance computed internally in float8, while the <-> operator itself returns an exact integer. When an int8 value or distance exceeds 2^53, that internal distance may be inexact, so the index scan can return rows in a different order (and, with LIMIT, a different set of rows) than sorting by <->. This already applied to same-type int8 searches. --- doc/src/sgml/btree-gist.sgml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index cc09ec83733..e520106b7b0 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -49,12 +49,42 @@ float8, timestamp with time zone, timestamp without time zone, time without time zone, date, interval, oid, and money. + + As of version 1.10, the operator classes for int2, + int4 and int8 additionally support cross-type + query operators. An index on any one of these integer types can be used + with a B-tree-style comparison (<, + <=, =, >=, + >, <>) or with the + distance operator (<->) 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. + + + + When a nearest-neighbor search (ORDER BY with + <->) on the int2, int4 + or int8 operator classes is performed by an index scan, the + rows are ordered by a distance that the index computes internally in + float8, not by the result of the + <-> operator, which is an exact integer (and + raises an error on overflow). That internal distance may be inexact if + the indexed value, the query value, or the distance between them exceeds + 253 in absolute value, which can only happen + when int8 is involved. The index scan may then return rows + in a different order than sorting by <-> would, + and, with LIMIT, a different set of rows. This applies + equally to same-type and cross-type searches. + + By default btree_gist builds GiST index with sortsupport in sorted mode. This usually results in much faster index built speed. It is still possible to revert to buffered built strategy by using the buffering parameter when creating the index. -- 2.51.0