Home Explore Blog CI



postgresql

15th chunk of `doc/src/sgml/gist.sgml`
a7cbd946deb56b48797d241cc106eb08487d52c0c580ee960000000100000fa3
                           &validate_my_string_relopt,
                               &fill_my_string_relopt,
                               offsetof(MyOptionsStruct, str_param));

    PG_RETURN_VOID();
}

PG_FUNCTION_INFO_V1(my_compress);

Datum
my_compress(PG_FUNCTION_ARGS)
{
    int     int_param = 100;
    double  real_param = 1.0;
    MyEnumType enum_param = MY_ENUM_ON;
    char   *str_param = str_param_default;

    /*
     * Normally, when opclass contains 'options' method, then options are always
     * passed to support functions.  However, if you add 'options' method to
     * existing opclass, previously defined indexes have no options, so the
     * check is required.
     */
    if (PG_HAS_OPCLASS_OPTIONS())
    {
        MyOptionsStruct *options = (MyOptionsStruct *) PG_GET_OPCLASS_OPTIONS();

        int_param = options->int_param;
        real_param = options->real_param;
        enum_param = options->enum_param;
        str_param = GET_STRING_RELOPTION(options, str_param);
    }

    /* the rest implementation of support function */
}

</programlisting>
      </para>

      <para>
       Since the representation of the key in <acronym>GiST</acronym> is
       flexible, it may depend on user-specified parameters.  For instance,
       the length of key signature may be specified.  See
       <literal>gtsvector_options()</literal> for example.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>sortsupport</function></term>
     <listitem>
      <para>
       Returns a comparator function to sort data in a way that preserves
       locality. It is used by <command>CREATE INDEX</command> and
       <command>REINDEX</command> commands. The quality of the created index
       depends on how well the sort order determined by the comparator function
       preserves locality of the inputs.
      </para>
      <para>
       The <function>sortsupport</function> method is optional. If it is not
       provided, <command>CREATE INDEX</command> builds the index by inserting
       each tuple to the tree using the <function>penalty</function> and
       <function>picksplit</function> functions, which is much slower.
      </para>

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

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

       The argument is a pointer to a <structname>SortSupport</structname>
       struct. At a minimum, the function must fill in its comparator field.
       The comparator takes three arguments: two Datums to compare, and
       a pointer to the <structname>SortSupport</structname> struct. The
       Datums are the two indexed values in the format that they are stored
       in the index; that is, in the format returned by the
       <function>compress</function> method. The full API is defined in
       <filename>src/include/utils/sortsupport.h</filename>.
       </para>

       <para>
        The matching code in the C module could then follow this skeleton:

<programlisting>
PG_FUNCTION_INFO_V1(my_sortsupport);

static int
my_fastcmp(Datum x, Datum y, SortSupport ssup)
{
  /* establish order between x and y by computing some sorting value z */

  int z1 = ComputeSpatialCode(x);
  int z2 = ComputeSpatialCode(y);

  return z1 == z2 ? 0 : z1 > z2 ? 1 : -1;
}

Datum
my_sortsupport(PG_FUNCTION_ARGS)
{
  SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);

  ssup->comparator = my_fastcmp;
  PG_RETURN_VOID();
}
</programlisting>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>translate_cmptype</function></term>
     <listitem>
      <para>
       Given a <literal>CompareType</literal> value from
       <filename>src/include/nodes/primnodes.h</filename>, returns a strategy
       number used by this operator class for matching functionality.  The
       function should

Title: Implementing GiST Index Operator Classes
Summary
This passage describes the implementation of GiST index operator classes, including the definition of support functions such as 'options', 'sortsupport', and 'translate_cmptype', and provides examples of how to declare and implement these functions in C, with details on the required function signatures, parameters, and return types.