Rename gist stratnum support function
authorPeter Eisentraut <peter@eisentraut.org>
Mon, 2 Jun 2025 06:33:04 +0000 (08:33 +0200)
committerPeter Eisentraut <peter@eisentraut.org>
Mon, 2 Jun 2025 06:41:27 +0000 (08:41 +0200)
Commit 7406ab623fe added a gist support function that we internally
refer to by the symbol GIST_STRATNUM_PROC.  This translated from
"well-known" strategy numbers to opfamily-specific strategy numbers.
However, we later (commit 630f9a43cec) changed this to fit into
index-AM-level compare type mapping, so this function actually now
maps from compare type to opfamily-specific strategy numbers.  So this
name is no longer fitting.

Moreover, the index AM level also supports the opposite, a function to
map from strategy number to compare type.  This is currently not
supported in gist, but one might wonder what this function is supposed
to be called when it is added.

This patch changes the naming of the gist-level functionality to be
more in line with the index-AM-level functionality.  This makes sense
because these are essentially the same thing on different levels.
This also changes the names of the externally visible functions that
are provided for use as such a support function.

Reviewed-by: Paul A Jungwirth <pj@illuminatedcomputing.com>
Discussion: https://www.postgresql.org/message-id/37ebb1d9-9036-485f-a215-e55435689917%40eisentraut.org

14 files changed:
contrib/btree_gist/btree_gist--1.7--1.8.sql
contrib/btree_gist/btree_gist.c
contrib/btree_gist/expected/stratnum.out
contrib/btree_gist/sql/stratnum.sql
doc/src/sgml/gist.sgml
doc/src/sgml/xindex.sgml
src/backend/access/gist/gistutil.c
src/backend/access/gist/gistvalidate.c
src/include/access/gist.h
src/include/catalog/catversion.h
src/include/catalog/pg_amproc.dat
src/include/catalog/pg_proc.dat
src/test/regress/expected/misc_functions.out
src/test/regress/sql/misc_functions.sql

index 4ff9c43a8ebe54f21f057453aa98340fb0f493e9..8f79365a461f806681e9dc9c1d505db663cdadd4 100644 (file)
@@ -3,85 +3,85 @@
 -- complain if script is sourced in psql, rather than via CREATE EXTENSION
 \echo Use "ALTER EXTENSION btree_gist UPDATE TO '1.8'" to load this file. \quit
 
-CREATE FUNCTION gist_stratnum_btree(int)
+CREATE FUNCTION gist_translate_cmptype_btree(int)
 RETURNS smallint
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE PARALLEL SAFE STRICT;
 
 ALTER OPERATOR FAMILY gist_oid_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_int2_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_int4_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_int8_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_float4_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_float8_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_timestamp_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_timestamptz_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_time_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_date_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_interval_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_cash_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_macaddr_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_text_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_bpchar_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_bytea_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_numeric_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_bit_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_vbit_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_inet_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_cidr_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_timetz_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_uuid_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_macaddr8_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_enum_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
 
 ALTER OPERATOR FAMILY gist_bool_ops USING gist ADD
-   FUNCTION 12 ("any", "any") gist_stratnum_btree (int) ;
+   FUNCTION 12 ("any", "any") gist_translate_cmptype_btree (int) ;
index 280ce808456b9021fa497c83abbe77717af76918..39fcbdad334f0d54a7c30ccf6c9a2789562dc940 100644 (file)
@@ -15,7 +15,7 @@ PG_MODULE_MAGIC_EXT(
 PG_FUNCTION_INFO_V1(gbt_decompress);
 PG_FUNCTION_INFO_V1(gbtreekey_in);
 PG_FUNCTION_INFO_V1(gbtreekey_out);
-PG_FUNCTION_INFO_V1(gist_stratnum_btree);
+PG_FUNCTION_INFO_V1(gist_translate_cmptype_btree);
 
 /**************************************************
  * In/Out for keys
@@ -62,7 +62,7 @@ gbt_decompress(PG_FUNCTION_ARGS)
  * Returns the btree number for supported operators, otherwise invalid.
  */
 Datum
-gist_stratnum_btree(PG_FUNCTION_ARGS)
+gist_translate_cmptype_btree(PG_FUNCTION_ARGS)
 {
    CompareType cmptype = PG_GETARG_INT32(0);
 
index dd0edaf4a206274ad3118f702f7d52d815e9d8bb..8222b66153833b407cdcc258fdf26557dd8543a6 100644 (file)
@@ -1,13 +1,13 @@
--- test stratnum support func
-SELECT gist_stratnum_btree(7);
- gist_stratnum_btree 
----------------------
-                   0
+-- test stratnum translation support func
+SELECT gist_translate_cmptype_btree(7);
+ gist_translate_cmptype_btree 
+------------------------------
+                            0
 (1 row)
 
-SELECT gist_stratnum_btree(3);
- gist_stratnum_btree 
----------------------
-                   3
+SELECT gist_translate_cmptype_btree(3);
+ gist_translate_cmptype_btree 
+------------------------------
+                            3
 (1 row)
 
index 75adddad8492583761418b9152b6afbe14531851..da8bbf883b0cce9ced4ba8449935fc8da5b11e1d 100644 (file)
@@ -1,3 +1,3 @@
--- test stratnum support func
-SELECT gist_stratnum_btree(7);
-SELECT gist_stratnum_btree(3);
+-- test stratnum translation support func
+SELECT gist_translate_cmptype_btree(7);
+SELECT gist_translate_cmptype_btree(3);
index a373a8aa4b2fc93a4b0712b26f532211c61c2ed5..ee86e1700552095816dae94ec23472e9a48c32b2 100644 (file)
@@ -1170,7 +1170,7 @@ my_sortsupport(PG_FUNCTION_ARGS)
     </varlistentry>
 
     <varlistentry>
-     <term><function>stratnum</function></term>
+     <term><function>translate_cmptype</function></term>
      <listitem>
       <para>
        Given a <literal>CompareType</literal> value from
@@ -1188,12 +1188,23 @@ my_sortsupport(PG_FUNCTION_ARGS)
        non-<literal>WITHOUT OVERLAPS</literal> part(s) of an index constraint.
       </para>
 
+      <para>
+       This support function corresponds to the index access method callback
+       function <structfield>amtranslatecmptype</structfield> (see <xref
+       linkend="index-functions"/>).  The
+       <structfield>amtranslatecmptype</structfield> callback function for
+       GiST indexes merely calls down to the
+       <function>translate_cmptype</function> support function of the
+       respective operator family, since the GiST index access method has no
+       fixed strategy numbers itself.
+      </para>
+
       <para>
        The <acronym>SQL</acronym> declaration of the function must look like
        this:
 
 <programlisting>
-CREATE OR REPLACE FUNCTION my_stratnum(integer)
+CREATE OR REPLACE FUNCTION my_translate_cmptype(integer)
 RETURNS smallint
 AS 'MODULE_PATHNAME'
 LANGUAGE C STRICT;
@@ -1202,7 +1213,7 @@ LANGUAGE C STRICT;
        And the operator family registration must look like this:
 <programlisting>
 ALTER OPERATOR FAMILY my_opfamily USING gist ADD
-    FUNCTION 12 ("any", "any") my_stratnum(int);
+    FUNCTION 12 ("any", "any") my_translate_cmptype(int);
 </programlisting>
       </para>
 
@@ -1210,10 +1221,10 @@ ALTER OPERATOR FAMILY my_opfamily USING gist ADD
         The matching code in the C module could then follow this skeleton:
 
 <programlisting>
-PG_FUNCTION_INFO_V1(my_stratnum);
+PG_FUNCTION_INFO_V1(my_translate_cmptype);
 
 Datum
-my_stratnum(PG_FUNCTION_ARGS)
+my_translate_cmptype(PG_FUNCTION_ARGS)
 {
     CompareType cmptype = PG_GETARG_INT32(0);
     StrategyNumber ret = InvalidStrategy;
@@ -1232,11 +1243,11 @@ my_stratnum(PG_FUNCTION_ARGS)
       <para>
        One translation function is provided by
        <productname>PostgreSQL</productname>:
-       <literal>gist_stratnum_common</literal> is for operator classes that
+       <literal>gist_translate_cmptype_common</literal> is for operator classes that
        use the <literal>RT*StrategyNumber</literal> constants.
        The <literal>btree_gist</literal>
        extension defines a second translation function,
-       <literal>gist_stratnum_btree</literal>, for operator classes that use
+       <literal>gist_translate_cmptype_btree</literal>, for operator classes that use
        the <literal>BT*StrategyNumber</literal> constants.
       </para>
      </listitem>
index 7e23a7b6e43230d1c3cddebbd41a32cecbb8893e..3d315df2f9803899213a43d92f374f3937da27b2 100644 (file)
        <entry>11</entry>
       </row>
       <row>
-       <entry><function>stratnum</function></entry>
+       <entry><function>translate_cmptype</function></entry>
        <entry>translate compare types to strategy numbers
         used by the operator class (optional)</entry>
        <entry>12</entry>
index a6b701943d3deb0e17fc01cb5d76ebed633fa627..c0aa7d0222f399ac3d4e9055fb98c10436f868d6 100644 (file)
@@ -1058,11 +1058,11 @@ gistGetFakeLSN(Relation rel)
 }
 
 /*
- * This is a stratnum support function for GiST opclasses that use the
- * RT*StrategyNumber constants.
+ * This is a stratnum translation support function for GiST opclasses that use
+ * the RT*StrategyNumber constants.
  */
 Datum
-gist_stratnum_common(PG_FUNCTION_ARGS)
+gist_translate_cmptype_common(PG_FUNCTION_ARGS)
 {
    CompareType cmptype = PG_GETARG_INT32(0);
 
@@ -1090,9 +1090,9 @@ gist_stratnum_common(PG_FUNCTION_ARGS)
 /*
  * Returns the opclass's private stratnum used for the given compare type.
  *
- * Calls the opclass's GIST_STRATNUM_PROC support function, if any,
- * and returns the result.
- * Returns InvalidStrategy if the function is not defined.
+ * Calls the opclass's GIST_TRANSLATE_CMPTYPE_PROC support function, if any,
+ * and returns the result.  Returns InvalidStrategy if the function is not
+ * defined.
  */
 StrategyNumber
 gisttranslatecmptype(CompareType cmptype, Oid opfamily)
@@ -1101,7 +1101,7 @@ gisttranslatecmptype(CompareType cmptype, Oid opfamily)
    Datum       result;
 
    /* Check whether the function is provided. */
-   funcid = get_opfamily_proc(opfamily, ANYOID, ANYOID, GIST_STRATNUM_PROC);
+   funcid = get_opfamily_proc(opfamily, ANYOID, ANYOID, GIST_TRANSLATE_CMPTYPE_PROC);
    if (!OidIsValid(funcid))
        return InvalidStrategy;
 
index 2a49e6d20f0492b2fb82608c2cdf8c6a2fb986fd..2ed6f74fce97ba0eeebbce2e3e03cbbf21ff7366 100644 (file)
@@ -138,7 +138,7 @@ gistvalidate(Oid opclassoid)
                ok = check_amproc_signature(procform->amproc, VOIDOID, true,
                                            1, 1, INTERNALOID);
                break;
-           case GIST_STRATNUM_PROC:
+           case GIST_TRANSLATE_CMPTYPE_PROC:
                ok = check_amproc_signature(procform->amproc, INT2OID, true,
                                            1, 1, INT4OID) &&
                    procform->amproclefttype == ANYOID &&
@@ -265,7 +265,7 @@ gistvalidate(Oid opclassoid)
        if (i == GIST_DISTANCE_PROC || i == GIST_FETCH_PROC ||
            i == GIST_COMPRESS_PROC || i == GIST_DECOMPRESS_PROC ||
            i == GIST_OPTIONS_PROC || i == GIST_SORTSUPPORT_PROC ||
-           i == GIST_STRATNUM_PROC)
+           i == GIST_TRANSLATE_CMPTYPE_PROC)
            continue;           /* optional methods */
        ereport(INFO,
                (errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
@@ -336,7 +336,7 @@ gistadjustmembers(Oid opfamilyoid,
            case GIST_FETCH_PROC:
            case GIST_OPTIONS_PROC:
            case GIST_SORTSUPPORT_PROC:
-           case GIST_STRATNUM_PROC:
+           case GIST_TRANSLATE_CMPTYPE_PROC:
                /* Optional, so force it to be a soft family dependency */
                op->ref_is_hard = false;
                op->ref_is_family = true;
index db78e60eeab0bce4df4b811ae431f799dcdf2b2f..b3f4e02cbfd210c164726d7fdc1c22e6f33b9b50 100644 (file)
@@ -40,7 +40,7 @@
 #define GIST_FETCH_PROC                    9
 #define GIST_OPTIONS_PROC              10
 #define GIST_SORTSUPPORT_PROC          11
-#define GIST_STRATNUM_PROC             12
+#define GIST_TRANSLATE_CMPTYPE_PROC        12
 #define GISTNProcs                 12
 
 /*
index 82988d244339049c4091c494d2f53e135a305074..f2971485d8ff62f58a85ee0497795e221b2a8beb 100644 (file)
@@ -57,6 +57,6 @@
  */
 
 /*                         yyyymmddN */
-#define CATALOG_VERSION_NO 202505071
+#define CATALOG_VERSION_NO 202506021
 
 #endif
index 92505148998440ecbf41cb4fac7abc0a656fe37e..e3477500baa7d431369dffc5807fcf88f01efae1 100644 (file)
   amprocrighttype => 'box', amprocnum => '8', amproc => 'gist_box_distance' },
 { amprocfamily => 'gist/box_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 { amprocfamily => 'gist/poly_ops', amproclefttype => 'polygon',
   amprocrighttype => 'polygon', amprocnum => '1',
   amproc => 'gist_poly_consistent' },
   amproc => 'gist_poly_distance' },
 { amprocfamily => 'gist/poly_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 { amprocfamily => 'gist/circle_ops', amproclefttype => 'circle',
   amprocrighttype => 'circle', amprocnum => '1',
   amproc => 'gist_circle_consistent' },
   amproc => 'gist_circle_distance' },
 { amprocfamily => 'gist/circle_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 { amprocfamily => 'gist/tsvector_ops', amproclefttype => 'tsvector',
   amprocrighttype => 'tsvector', amprocnum => '1',
   amproc => 'gtsvector_consistent(internal,tsvector,int2,oid,internal)' },
   amproc => 'range_sortsupport' },
 { amprocfamily => 'gist/range_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 { amprocfamily => 'gist/network_ops', amproclefttype => 'inet',
   amprocrighttype => 'inet', amprocnum => '1',
   amproc => 'inet_gist_consistent' },
   amprocrighttype => 'inet', amprocnum => '9', amproc => 'inet_gist_fetch' },
 { amprocfamily => 'gist/network_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 { amprocfamily => 'gist/multirange_ops', amproclefttype => 'anymultirange',
   amprocrighttype => 'anymultirange', amprocnum => '1',
   amproc => 'multirange_gist_consistent' },
   amproc => 'range_gist_same' },
 { amprocfamily => 'gist/multirange_ops', amproclefttype => 'any',
   amprocrighttype => 'any', amprocnum => '12',
-  amproc => 'gist_stratnum_common' },
+  amproc => 'gist_translate_cmptype_common' },
 
 # gin
 { amprocfamily => 'gin/array_ops', amproclefttype => 'anyarray',
index 37a484147a8f24f67c47ee74c0dac143028c5c9a..d3d28a263fa99be2c9fd4ef0eef4d38848c56038 100644 (file)
 
 # GiST stratnum implementations
 { oid => '8047', descr => 'GiST support',
-  proname => 'gist_stratnum_common', prorettype => 'int2',
+  proname => 'gist_translate_cmptype_common', prorettype => 'int2',
   proargtypes => 'int4',
-  prosrc => 'gist_stratnum_common' },
+  prosrc => 'gist_translate_cmptype_common' },
 
 # AIO related functions
 { oid => '9200', descr => 'information about in-progress asynchronous IOs',
index cc517ed5e90078efbab4f5e364108c290756a529..c3b2b9d860343e4fe8209669ff917fb022b336cc 100644 (file)
@@ -890,17 +890,17 @@ SELECT pg_column_toast_chunk_id(a) IS NULL,
 
 DROP TABLE test_chunk_id;
 DROP FUNCTION explain_mask_costs(text, bool, bool, bool, bool);
--- test stratnum support functions
-SELECT gist_stratnum_common(7);
- gist_stratnum_common 
-----------------------
-                    3
+-- test stratnum translation support functions
+SELECT gist_translate_cmptype_common(7);
+ gist_translate_cmptype_common 
+-------------------------------
+                             3
 (1 row)
 
-SELECT gist_stratnum_common(3);
- gist_stratnum_common 
-----------------------
-                   18
+SELECT gist_translate_cmptype_common(3);
+ gist_translate_cmptype_common 
+-------------------------------
+                            18
 (1 row)
 
 -- relpath tests
index 5f9c77512d160c30bd112f3b681a9207a73cc1d6..23792c4132a10e62b93084f3d48b970c97354714 100644 (file)
@@ -400,9 +400,9 @@ SELECT pg_column_toast_chunk_id(a) IS NULL,
 DROP TABLE test_chunk_id;
 DROP FUNCTION explain_mask_costs(text, bool, bool, bool, bool);
 
--- test stratnum support functions
-SELECT gist_stratnum_common(7);
-SELECT gist_stratnum_common(3);
+-- test stratnum translation support functions
+SELECT gist_translate_cmptype_common(7);
+SELECT gist_translate_cmptype_common(3);
 
 
 -- relpath tests