Home Explore Blog CI



postgresql

13th chunk of `doc/src/sgml/brin.sgml`
e00f49f6a534e0b880ee0061d1a3d9338ca5971de69a84d20000000100000fca
 </para>

 <para>
  All it takes to get a <acronym>BRIN</acronym> access method working is to
  implement a few user-defined methods, which define the behavior of
  summary values stored in the index and the way they interact with
  scan keys.
  In short, <acronym>BRIN</acronym> combines
  extensibility with generality, code reuse, and a clean interface.
 </para>

 <para>
  There are four methods that an operator class for <acronym>BRIN</acronym>
  must provide:

  <variablelist>
   <varlistentry>
    <term><function>BrinOpcInfo *opcInfo(Oid type_oid)</function></term>
    <listitem>
     <para>
      Returns internal information about the indexed columns' summary data.
      The return value must point to a palloc'd <structname>BrinOpcInfo</structname>,
      which has this definition:
<programlisting>
typedef struct BrinOpcInfo
{
    /* Number of columns stored in an index column of this opclass */
    uint16      oi_nstored;

    /* Opaque pointer for the opclass' private use */
    void       *oi_opaque;

    /* Type cache entries of the stored columns */
    TypeCacheEntry *oi_typcache[FLEXIBLE_ARRAY_MEMBER];
} BrinOpcInfo;
</programlisting>
      <structname>BrinOpcInfo</structname>.<structfield>oi_opaque</structfield> can be used by the
      operator class routines to pass information between support functions
      during an index scan.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><function>bool consistent(BrinDesc *bdesc, BrinValues *column,
       ScanKey *keys, int nkeys)</function></term>
    <listitem>
     <para>
      Returns whether all the ScanKey entries are consistent with the given
      indexed values for a range.
      The attribute number to use is passed as part of the scan key.
      Multiple scan keys for the same attribute may be passed at once; the
      number of entries is determined by the <literal>nkeys</literal> parameter.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><function>bool consistent(BrinDesc *bdesc, BrinValues *column,
       ScanKey key)</function></term>
    <listitem>
     <para>
      Returns whether the ScanKey is consistent with the given indexed
      values for a range.
      The attribute number to use is passed as part of the scan key.
      This is an older backward-compatible variant of the consistent function.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><function>bool addValue(BrinDesc *bdesc, BrinValues *column,
       Datum newval, bool isnull)</function></term>
    <listitem>
     <para>
      Given an index tuple and an indexed value, modifies the indicated
      attribute of the tuple so that it additionally represents the new value.
      If any modification was done to the tuple, <literal>true</literal> is
      returned.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><function>bool unionTuples(BrinDesc *bdesc, BrinValues *a,
       BrinValues *b)</function></term>
    <listitem>
     <para>
      Consolidates two index tuples. Given two index tuples, modifies the
      indicated attribute of the first of them so that it represents both tuples.
      The second tuple is not modified.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  An operator class for <acronym>BRIN</acronym> can optionally specify the
  following method:

  <variablelist>
    <varlistentry>
     <term><function>void options(local_relopts *relopts)</function></term>
     <listitem>
      <para>
       Defines a set of user-visible parameters that control operator class
       behavior.
      </para>

      <para>
       The <function>options</function> 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> and
       <literal>PG_GET_OPCLASS_OPTIONS()</literal>

Title: BRIN Operator Class Methods
Summary
To implement a BRIN access method, four main methods must be provided: opcInfo, consistent, addValue, and unionTuples, which define the behavior of summary values stored in the index and their interaction with scan keys. An optional method, options, can also be specified to define user-visible parameters that control operator class behavior, allowing for customization of the index's functionality.