Home Explore Blog CI



postgresql

5th chunk of `doc/src/sgml/gin.sgml`
a760e36090e629c03f07ca770831d3c5dccff1ddce1a6ad10000000100000fa1
 true if an indexed item satisfies the query operator with
       strategy number <literal>n</literal> (or might satisfy it, if the recheck
       indication is returned).  This function does not have direct access
       to the indexed item's value, since <acronym>GIN</acronym> does not
       store items explicitly.  Rather, what is available is knowledge
       about which key values extracted from the query appear in a given
       indexed item.  The <literal>check</literal> array has length
       <literal>nkeys</literal>, which is the same as the number of keys previously
       returned by <function>extractQuery</function> for this <literal>query</literal> datum.
       Each element of the
       <literal>check</literal> array is true if the indexed item contains the
       corresponding query key, i.e., if (check[i] == true) the i-th key of the
       <function>extractQuery</function> result array is present in the indexed item.
       The original <literal>query</literal> datum is
       passed in case the <function>consistent</function> method needs to consult it,
       and so are the <literal>queryKeys[]</literal> and <literal>nullFlags[]</literal>
       arrays previously returned by <function>extractQuery</function>.
       <literal>extra_data</literal> is the extra-data array returned by
       <function>extractQuery</function>, or <symbol>NULL</symbol> if none.
      </para>

      <para>
       When <function>extractQuery</function> returns a null key in
       <literal>queryKeys[]</literal>, the corresponding <literal>check[]</literal> element
       is true if the indexed item contains a null key; that is, the
       semantics of <literal>check[]</literal> are like <literal>IS NOT DISTINCT
       FROM</literal>.  The <function>consistent</function> function can examine the
       corresponding <literal>nullFlags[]</literal> element if it needs to tell
       the difference between a regular value match and a null match.
      </para>

      <para>
       On success, <literal>*recheck</literal> should be set to true if the heap
       tuple needs to be rechecked against the query operator, or false if
       the index test is exact.  That is, a false return value guarantees
       that the heap tuple does not match the query; a true return value with
       <literal>*recheck</literal> set to false guarantees that the heap tuple does
       match the query; and a true return value with
       <literal>*recheck</literal> set to true means that the heap tuple might match
       the query, so it needs to be fetched and rechecked by evaluating the
       query operator directly against the originally indexed item.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>GinTernaryValue triConsistent(GinTernaryValue check[], StrategyNumber n, Datum query,
        int32 nkeys, Pointer extra_data[],
        Datum queryKeys[], bool nullFlags[])</function></term>
     <listitem>
      <para>
       <function>triConsistent</function> is similar to <function>consistent</function>,
       but instead of Booleans in the <literal>check</literal> vector, there are
       three possible values for each
       key: <literal>GIN_TRUE</literal>, <literal>GIN_FALSE</literal> and
       <literal>GIN_MAYBE</literal>. <literal>GIN_FALSE</literal> and <literal>GIN_TRUE</literal>
       have the same meaning as regular Boolean values, while
       <literal>GIN_MAYBE</literal> means that the presence of that key is not known.
       When <literal>GIN_MAYBE</literal> values are present, the function should only
       return <literal>GIN_TRUE</literal> if the item certainly matches whether or
       not the index item contains the corresponding query keys. Likewise, the
       function must return <literal>GIN_FALSE</literal> only if the item certainly
       does not match, whether or not it contains the <literal>GIN_MAYBE</literal>
       keys. If the result depends on the <literal>GIN_MAYBE</literal>

Title: GIN Consistency Functions: consistent and triConsistent
Summary
The consistent and triConsistent functions are used to check if an indexed item matches a query, with consistent returning a Boolean value and triConsistent returning a ternary value, allowing for more nuanced results when dealing with unknown key presence.