Home Explore Blog CI



postgresql

15th chunk of `doc/src/sgml/spgist.sgml`
3a2de0f39b1d2f85fd9adb933c0dae470ee9171b4b55b9b00000000100000faf
 <structfield>reconstructedValue</structfield> is the value reconstructed for the
       parent tuple; it is <literal>(Datum) 0</literal> at the root level or if the
       <function>inner_consistent</function> function did not provide a value at the
       parent level.
       <structfield>traversalValue</structfield> is a pointer to any traverse data
       passed down from the previous call of <function>inner_consistent</function>
       on the parent index tuple, or NULL at the root level.
       <structfield>level</structfield> is the current leaf tuple's level, starting at
       zero for the root level.
       <structfield>returnData</structfield> is <literal>true</literal> if reconstructed data is
       required for this query; this will only be so if the
       <function>config</function> function asserted <structfield>canReturnData</structfield>.
       <structfield>leafDatum</structfield> is the key value of
       <structname>spgConfigOut</structname>.<structfield>leafType</structfield>
       stored in the current leaf tuple.
      </para>

      <para>
       The function must return <literal>true</literal> if the leaf tuple matches the
       query, or <literal>false</literal> if not.  In the <literal>true</literal> case,
       if <structfield>returnData</structfield> is <literal>true</literal> then
       <structfield>leafValue</structfield> must be set to the value (of type
       <structname>spgConfigIn</structname>.<structfield>attType</structfield>)
       originally supplied to be indexed for this leaf tuple.  Also,
       <structfield>recheck</structfield> may be set to <literal>true</literal> if the match
       is uncertain and so the operator(s) must be re-applied to the actual
       heap tuple to verify the match.
       If ordered search is performed, set <structfield>distances</structfield>
       to an array of distance values according to <structfield>orderbys</structfield>
       array.  Leave it NULL otherwise.  If at least one of returned distances
       is not exact, set <structfield>recheckDistances</structfield> to true.
       In this case, the executor will calculate the exact distances after
       fetching the tuple from the heap, and will reorder the tuples if needed.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

 <para>
  The optional user-defined methods are:
 </para>

 <variablelist>
    <varlistentry>
     <term><function>Datum compress(Datum in)</function></term>
     <listitem>
      <para>
       Converts a data item into a format suitable for physical storage in
       a leaf tuple of the index.  It accepts a value of type
       <structname>spgConfigIn</structname>.<structfield>attType</structfield>
       and returns a value of type
       <structname>spgConfigOut</structname>.<structfield>leafType</structfield>.
       The output value must not contain an out-of-line TOAST pointer.
      </para>

      <para>
       Note: the <function>compress</function> method is only applied to
       values to be stored.  The consistent methods receive query
       <structfield>scankeys</structfield> unchanged, without transformation
       using <function>compress</function>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>options</function></term>
     <listitem>
      <para>
       Defines a set of user-visible parameters that control operator class
       behavior.
      </para>

      <para>
        The <acronym>SQL</acronym> declaration of the function must look like this:

<programlisting>
CREATE OR REPLACE FUNCTION my_options(internal)
RETURNS void
AS 'MODULE_PATHNAME'
LANGUAGE C STRICT;
</programlisting>
      </para>

      <para>
       The function is passed a pointer to a <structname>local_relopts</structname>
       struct, which needs to be filled with a set of operator class
       specific options.  The options can be accessed from other support
       functions using the <literal>PG_HAS_OPCLASS_OPTIONS()</literal>

Title: SP-GiST Optional User-Defined Methods
Summary
The SP-GiST interface provides optional user-defined methods, including the compress function, which converts data into a format suitable for physical storage, and the options function, which defines operator class behavior and user-visible parameters, allowing for customization and control over the indexing process.