Home Explore Blog CI



postgresql

9th chunk of `doc/src/sgml/indexam.sgml`
0b97026580552f213d4a205fcea413149d495df2b113ba1e0000000100000fa5
 data (that fits into
   an integer) about the index that the cost estimation function might want to
   know.  If the computation is expensive, it could be useful to cache the
   result as part of <literal>RelationData.rd_amcache</literal>.
  </para>

  <para>
<programlisting>
bytea *
amoptions (ArrayType *reloptions,
           bool validate);
</programlisting>
   Parse and validate the reloptions array for an index.  This is called only
   when a non-null reloptions array exists for the index.
   <parameter>reloptions</parameter> is a <type>text</type> array containing entries of the
   form <replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable>.
   The function should construct a <type>bytea</type> value, which will be copied
   into the <structfield>rd_options</structfield> field of the index's relcache entry.
   The data contents of the <type>bytea</type> value are open for the access
   method to define; most of the standard access methods use struct
   <structname>StdRdOptions</structname>.
   When <parameter>validate</parameter> is true, the function should report a suitable
   error message if any of the options are unrecognized or have invalid
   values; when <parameter>validate</parameter> is false, invalid entries should be
   silently ignored.  (<parameter>validate</parameter> is false when loading options
   already stored in <structname>pg_catalog</structname>; an invalid entry could only
   be found if the access method has changed its rules for options, and in
   that case ignoring obsolete entries is appropriate.)
   It is OK to return NULL if default behavior is wanted.
  </para>

  <para>
<programlisting>
bool
amproperty (Oid index_oid, int attno,
            IndexAMProperty prop, const char *propname,
            bool *res, bool *isnull);
</programlisting>
   The <function>amproperty</function> method allows index access methods to override
   the default behavior of <function>pg_index_column_has_property</function>
   and related functions.
   If the access method does not have any special behavior for index property
   inquiries, the <structfield>amproperty</structfield> field in
   its <structname>IndexAmRoutine</structname> struct can be set to NULL.
   Otherwise, the <function>amproperty</function> method will be called with
   <parameter>index_oid</parameter> and <parameter>attno</parameter> both zero for
   <function>pg_indexam_has_property</function> calls,
   or with <parameter>index_oid</parameter> valid and <parameter>attno</parameter> zero for
   <function>pg_index_has_property</function> calls,
   or with <parameter>index_oid</parameter> valid and <parameter>attno</parameter> greater than
   zero for <function>pg_index_column_has_property</function> calls.
   <parameter>prop</parameter> is an enum value identifying the property being tested,
   while <parameter>propname</parameter> is the original property name string.
   If the core code does not recognize the property name
   then <parameter>prop</parameter> is <literal>AMPROP_UNKNOWN</literal>.
   Access methods can define custom property names by
   checking <parameter>propname</parameter> for a match (use <function>pg_strcasecmp</function>
   to match, for consistency with the core code); for names known to the core
   code, it's better to inspect <parameter>prop</parameter>.
   If the <structfield>amproperty</structfield> method returns <literal>true</literal> then
   it has determined the property test result: it must set <literal>*res</literal>
   to the Boolean value to return, or set <literal>*isnull</literal>
   to <literal>true</literal> to return a NULL.  (Both of the referenced variables
   are initialized to <literal>false</literal> before the call.)
   If the <structfield>amproperty</structfield> method returns <literal>false</literal> then
   the core code will proceed with its normal logic for determining the
   property test result.
  </para>

  <para>
   Access methods that support ordering operators

Title: Index Access Method Functions: amoptions and amproperty
Summary
amoptions parses and validates the reloptions array for an index, creating a bytea value for the index's relcache entry and reporting errors for invalid options during validation. amproperty allows index access methods to override the default behavior of pg_index_column_has_property and related functions, enabling custom property name checks and setting the Boolean result or NULL value.