Fix assorted inconsistencies in GIN opclass support function declarations.

GIN had some minor issues too, mostly using "internal" where something
else would be more appropriate.  I went with the same approach as in
9ff60273e35cad6e, namely preferring the opclass' indexed datatype for
arguments that receive an operator RHS value, even if that's not
necessarily what they really are.

Again, this is with an eye to having a uniform rule for ginvalidate()
to check support function signatures.

diff --git a/contrib/hstore/hstore--1.3.sql b/contrib/hstore/hstore--1.3.sql
index 07d6082c9e35de27c394163f4148df59ab161652..b9b478d03990da184f714825c160f55402130cee 100644 (file)
--- a/contrib/hstore/hstore--1.3.sql
+++ b/contrib/hstore/hstore--1.3.sql
@@ -521,17 +521,17 @@ AS
 
 -- GIN support
 
-CREATE FUNCTION gin_extract_hstore(internal, internal)
+CREATE FUNCTION gin_extract_hstore(hstore, internal)
 RETURNS internal
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE STRICT;
 
-CREATE FUNCTION gin_extract_hstore_query(internal, internal, int2, internal, internal)
+CREATE FUNCTION gin_extract_hstore_query(hstore, internal, int2, internal, internal)
 RETURNS internal
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE STRICT;
 
-CREATE FUNCTION gin_consistent_hstore(internal, int2, internal, int4, internal, internal)
+CREATE FUNCTION gin_consistent_hstore(internal, int2, hstore, int4, internal, internal)
 RETURNS bool
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE STRICT;
@@ -544,7 +544,7 @@ AS
        OPERATOR        10      ?|(hstore,text[]),
        OPERATOR        11      ?&(hstore,text[]),
        FUNCTION        1       bttextcmp(text,text),
-       FUNCTION        2       gin_extract_hstore(internal, internal),
-       FUNCTION        3       gin_extract_hstore_query(internal, internal, int2, internal, internal),
-       FUNCTION        4       gin_consistent_hstore(internal, int2, internal, int4, internal, internal),
+       FUNCTION        2       gin_extract_hstore(hstore, internal),
+       FUNCTION        3       gin_extract_hstore_query(hstore, internal, int2, internal, internal),
+       FUNCTION        4       gin_consistent_hstore(internal, int2, hstore, int4, internal, internal),
        STORAGE         text;

diff --git a/contrib/intarray/intarray--1.1.sql b/contrib/intarray/intarray--1.1.sql
index 3c45eacaee2badf79aaa609eb51a8053292e8ed2..6ee0d5a62598b67ee25ceca04dd1922c031a8abb 100644 (file)
--- a/contrib/intarray/intarray--1.1.sql
+++ b/contrib/intarray/intarray--1.1.sql
@@ -493,12 +493,12 @@ AS
 
 --GIN
 
-CREATE FUNCTION ginint4_queryextract(internal, internal, int2, internal, internal, internal, internal)
+CREATE FUNCTION ginint4_queryextract(_int4, internal, int2, internal, internal, internal, internal)
 RETURNS internal
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE STRICT;
 
-CREATE FUNCTION ginint4_consistent(internal, int2, internal, int4, internal, internal, internal, internal)
+CREATE FUNCTION ginint4_consistent(internal, int2, _int4, int4, internal, internal, internal, internal)
 RETURNS bool
 AS 'MODULE_PATHNAME'
 LANGUAGE C IMMUTABLE STRICT;
@@ -515,6 +515,6 @@ AS
        OPERATOR        20      @@ (_int4, query_int),
        FUNCTION        1       btint4cmp (int4, int4),
        FUNCTION        2       ginarrayextract (anyarray, internal, internal),
-       FUNCTION        3       ginint4_queryextract (internal, internal, int2, internal, internal, internal, internal),
-       FUNCTION        4       ginint4_consistent (internal, int2, internal, int4, internal, internal, internal, internal),
+       FUNCTION        3       ginint4_queryextract (_int4, internal, int2, internal, internal, internal, internal),
+       FUNCTION        4       ginint4_consistent (internal, int2, _int4, int4, internal, internal, internal, internal),
        STORAGE         int4;

diff --git a/contrib/tsearch2/tsearch2--1.0.sql b/contrib/tsearch2/tsearch2--1.0.sql
index 6f473871cdab11a4ed9e6bccf8e5ae186f703cfa..a32c5fe85b55601aba1b983083fd129eac857e30 100644 (file)
--- a/contrib/tsearch2/tsearch2--1.0.sql
+++ b/contrib/tsearch2/tsearch2--1.0.sql
@@ -552,8 +552,8 @@ AS
         OPERATOR        2       @@@ (tsvector, tsquery),
         FUNCTION        1       bttextcmp(text, text),
         FUNCTION        2       gin_extract_tsvector(tsvector,internal,internal),
-        FUNCTION        3       gin_extract_tsquery(tsquery,internal,smallint,internal,internal,internal,internal),
-        FUNCTION        4       gin_tsquery_consistent(internal,smallint,tsquery,int,internal,internal,internal,internal),
+        FUNCTION        3       gin_extract_tsquery(tsvector,internal,smallint,internal,internal,internal,internal),
+        FUNCTION        4       gin_tsquery_consistent(internal,smallint,tsvector,int,internal,internal,internal,internal),
         FUNCTION        5       gin_cmp_prefix(text,text,smallint,internal),
         STORAGE         text;
 

diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 262f1e452e5fd1efcff87a96b51268c99fcbd1a0..9eb0b5a957ffac2deeee30fd2342883230eb6650 100644 (file)
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -556,10 +556,11 @@
   matches the query. It comes in two flavors, a boolean <function>consistent</>
   function, and a ternary <function>triConsistent</> function.
   <function>triConsistent</> covers the functionality of both, so providing
-  triConsistent alone is sufficient. However, if the boolean variant is
-  significantly cheaper to calculate, it can be advantageous to provide both.
-  If only the boolean variant is provided, some optimizations that depend on
-  refuting index items before fetching all the keys are disabled.
+  <function>triConsistent</> alone is sufficient. However, if the boolean
+  variant is significantly cheaper to calculate, it can be advantageous to
+  provide both.  If only the boolean variant is provided, some optimizations
+  that depend on refuting index items before fetching all the keys are
+  disabled.
 
   <variablelist>
     <varlistentry>
@@ -620,23 +621,26 @@
      <listitem>
       <para>
        <function>triConsistent</> is similar to <function>consistent</>,
-       but instead of a boolean <literal>check[]</>, there are three possible
-       values for each key: <literal>GIN_TRUE</>, <literal>GIN_FALSE</> and
+       but instead of booleans in the <literal>check</> vector, there are
+       three possible values for each
+       key: <literal>GIN_TRUE</>, <literal>GIN_FALSE</> and
        <literal>GIN_MAYBE</>. <literal>GIN_FALSE</> and <literal>GIN_TRUE</>
-       have the same meaning as regular boolean values.
+       have the same meaning as regular boolean values, while
        <literal>GIN_MAYBE</> means that the presence of that key is not known.
        When <literal>GIN_MAYBE</> values are present, the function should only
-       return GIN_TRUE if the item matches whether or not the index item
-       contains the corresponding query keys. Likewise, the function must
-       return GIN_FALSE only if the item does not match, whether or not it
-       contains the GIN_MAYBE keys. If the result depends on the GIN_MAYBE
-       entries, i.e. the match cannot be confirmed or refuted based on the
-       known query keys, the function must return GIN_MAYBE.
+       return <literal>GIN_TRUE</> if the item certainly matches whether or
+       not the index item contains the corresponding query keys. Likewise, the
+       function must return <literal>GIN_FALSE</> only if the item certainly
+       does not match, whether or not it contains the <literal>GIN_MAYBE</>
+       keys. If the result depends on the <literal>GIN_MAYBE</> entries, i.e.,
+       the match cannot be confirmed or refuted based on the known query keys,
+       the function must return <literal>GIN_MAYBE</>.
       </para>
       <para>
-       When there are no GIN_MAYBE values in the <literal>check</> vector,
-       <literal>GIN_MAYBE</> return value is equivalent of setting
-       <literal>recheck</> flag in the boolean <function>consistent</> function.
+       When there are no <literal>GIN_MAYBE</> values in the <literal>check</>
+       vector, a <literal>GIN_MAYBE</> return value is the equivalent of
+       setting the <literal>recheck</> flag in the
+       boolean <function>consistent</> function.
       </para>
      </listitem>
     </varlistentry>
@@ -682,11 +686,13 @@
   <function>extractValue</> are always of the operator class's input type, and
   all key values must be of the class's <literal>STORAGE</> type.  The type of
   the <literal>query</> argument passed to <function>extractQuery</>,
-  <function>consistent</> and <function>triConsistent</> is whatever is
-  specified as the right-hand input
-  type of the class member operator identified by the strategy number.
-  This need not be the same as the item type, so long as key values of the
-  correct type can be extracted from it.
+  <function>consistent</> and <function>triConsistent</> is whatever is the
+  right-hand input type of the class member operator identified by the
+  strategy number.  This need not be the same as the indexed type, so long as
+  key values of the correct type can be extracted from it.  However, it is
+  recommended that the SQL declarations of these three support functions use
+  the opclass's indexed data type for the <literal>query</> argument, even
+  though the actual type might be something else depending on the operator.
  </para>
 
 </sect1>

diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index 58e866658eab613279495301f9f353589a53669d..548d49440aa3f5a24e2809dbfd57b4b0d396ee3f 100644 (file)
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -53,6 +53,6 @@
  */
 
 /*                                                     yyyymmddN */
-#define CATALOG_VERSION_NO     201601191
+#define CATALOG_VERSION_NO     201601192
 
 #endif

diff --git a/src/include/catalog/pg_proc.h b/src/include/catalog/pg_proc.h
index 6beefa2ccf0303b2c69f935015c1ffd3619741a1..244aa4d016a1a7f7633be9233675ce34fa9d352e 100644 (file)
--- a/src/include/catalog/pg_proc.h
+++ b/src/include/catalog/pg_proc.h
@@ -4483,11 +4483,11 @@ DESCR("GiST tsvector support");
 
 DATA(insert OID = 3656 (  gin_extract_tsvector PGNSP PGUID 12 1 0 0 0 f f f f t f i s 3 0 2281 "3614 2281 2281" _null_ _null_ _null_ _null_ _null_     gin_extract_tsvector _null_ _null_ _null_ ));
 DESCR("GIN tsvector support");
-DATA(insert OID = 3657 (  gin_extract_tsquery  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "3615 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_tsquery _null_ _null_ _null_ ));
+DATA(insert OID = 3657 (  gin_extract_tsquery  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "3614 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_tsquery _null_ _null_ _null_ ));
 DESCR("GIN tsvector support");
-DATA(insert OID = 3658 (  gin_tsquery_consistent PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 3615 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_        gin_tsquery_consistent _null_ _null_ _null_ ));
+DATA(insert OID = 3658 (  gin_tsquery_consistent PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 3614 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_        gin_tsquery_consistent _null_ _null_ _null_ ));
 DESCR("GIN tsvector support");
-DATA(insert OID = 3921 (  gin_tsquery_triconsistent PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 3615 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_tsquery_triconsistent _null_ _null_ _null_ ));
+DATA(insert OID = 3921 (  gin_tsquery_triconsistent PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 3614 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_tsquery_triconsistent _null_ _null_ _null_ ));
 DESCR("GIN tsvector support");
 DATA(insert OID = 3724 (  gin_cmp_tslexeme             PGNSP PGUID 12 1 0 0 0 f f f f t f i s 2 0 23 "25 25" _null_ _null_ _null_ _null_ _null_ gin_cmp_tslexeme _null_ _null_ _null_ ));
 DESCR("GIN tsvector support");
@@ -4752,21 +4752,21 @@ DATA(insert OID = 4050 (  jsonb_contained       PGNSP PGUID 12 1 0 0 0 f f f f t f i s
 DESCR("implementation of <@ operator");
 DATA(insert OID = 3480 (  gin_compare_jsonb  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 2 0 23 "25 25" _null_ _null_ _null_ _null_ _null_ gin_compare_jsonb _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3482 (  gin_extract_jsonb  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 3 0 2281 "2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb _null_ _null_ _null_ ));
+DATA(insert OID = 3482 (  gin_extract_jsonb  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 3 0 2281 "3802 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3483 (  gin_extract_jsonb_query  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "2277 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_query _null_ _null_ _null_ ));
+DATA(insert OID = 3483 (  gin_extract_jsonb_query  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "3802 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_query _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3484 (  gin_consistent_jsonb PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 2277 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_consistent_jsonb _null_ _null_ _null_ ));
+DATA(insert OID = 3484 (  gin_consistent_jsonb PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 3802 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_consistent_jsonb _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3488 (  gin_triconsistent_jsonb      PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 2277 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_triconsistent_jsonb _null_ _null_ _null_ ));
+DATA(insert OID = 3488 (  gin_triconsistent_jsonb      PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 3802 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_triconsistent_jsonb _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3485 (  gin_extract_jsonb_path  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 3 0 2281 "2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_path _null_ _null_ _null_ ));
+DATA(insert OID = 3485 (  gin_extract_jsonb_path  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 3 0 2281 "3802 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_path _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3486 (  gin_extract_jsonb_query_path PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "2277 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_query_path _null_ _null_ _null_ ));
+DATA(insert OID = 3486 (  gin_extract_jsonb_query_path PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 2281 "3802 2281 21 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_extract_jsonb_query_path _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3487 (  gin_consistent_jsonb_path  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 2277 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_consistent_jsonb_path _null_ _null_ _null_ ));
+DATA(insert OID = 3487 (  gin_consistent_jsonb_path  PGNSP PGUID 12 1 0 0 0 f f f f t f i s 8 0 16 "2281 21 3802 23 2281 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_consistent_jsonb_path _null_ _null_ _null_ ));
 DESCR("GIN support");
-DATA(insert OID = 3489 (  gin_triconsistent_jsonb_path PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 2277 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_triconsistent_jsonb_path _null_ _null_ _null_ ));
+DATA(insert OID = 3489 (  gin_triconsistent_jsonb_path PGNSP PGUID 12 1 0 0 0 f f f f t f i s 7 0 18 "2281 21 3802 23 2281 2281 2281" _null_ _null_ _null_ _null_ _null_ gin_triconsistent_jsonb_path _null_ _null_ _null_ ));
 DESCR("GIN support");
 DATA(insert OID = 3301 (  jsonb_concat    PGNSP PGUID 12 1 0 0 0 f f f f t f i s 2 0 3802 "3802 3802" _null_ _null_ _null_ _null_ _null_ jsonb_concat _null_ _null_ _null_ ));
 DATA(insert OID = 3302 (  jsonb_delete    PGNSP PGUID 12 1 0 0 0 f f f f t f i s 2 0 3802 "3802 25" _null_ _null_ _null_ _null_ _null_ jsonb_delete _null_ _null_ _null_ ));