<!-- doc/src/sgml/xindex.sgml -->

<sect1 id="xindex">
 <title>Interfacing Extensions to Indexes</title>

 <indexterm zone="xindex">
  <primary>index</primary>
  <secondary>for user-defined data type</secondary>
 </indexterm>

  <para>
   The procedures described thus far let you define new types, new
   functions, and new operators. However, we cannot yet define an
   index on a column of a new data type.  To do this, we must define an
   <firstterm>operator class</firstterm> for the new data type.  Later in this
   section, we will illustrate this concept in an example: a new
   operator class for the B-tree index method that stores and sorts
   complex numbers in ascending absolute value order.
  </para>

  <para>
   Operator classes can be grouped into <firstterm>operator families</firstterm>
   to show the relationships between semantically compatible classes.
   When only a single data type is involved, an operator class is sufficient,
   so we'll focus on that case first and then return to operator families.
  </para>

 <sect2 id="xindex-opclass">
  <title>Index Methods and Operator Classes</title>

  <para>
   Operator classes are associated with an index access method, such
   as <link linkend="btree">B-Tree</link>
   or <link linkend="gin">GIN</link>. Custom index access method may be
   defined with <xref linkend="sql-create-access-method"/>. See
   <xref linkend="indexam"/> for details.
  </para>

  <para>
   The routines for an index method do not directly know anything
   about the data types that the index method will operate on.
   Instead, an <firstterm>operator
   class</firstterm><indexterm><primary>operator class</primary></indexterm>
   identifies the set of operations that the index method needs to use
   to work with a particular data type.  Operator classes are so
   called because one thing they specify is the set of
   <literal>WHERE</literal>-clause operators that can be used with an index
   (i.e., can be converted into an index-scan qualification).  An
   operator class can also specify some <firstterm>support
   function</firstterm> that are needed by the internal operations of the
   index method, but do not directly correspond to any
   <literal>WHERE</literal>-clause operator that can be used with the index.
  </para>

  <para>
   It is possible to define multiple operator classes for the same
   data type and index method.  By doing this, multiple
   sets of indexing semantics can be defined for a single data type.
   For example, a B-tree index requires a sort ordering to be defined
   for each data type it works on.
   It might be useful for a complex-number data type
   to have one B-tree operator class that sorts the data by complex
   absolute value, another that sorts by real part, and so on.
   Typically, one of the operator classes will be deemed most commonly
   useful and will be marked as the default operator class for that
   data type and index method.
  </para>

  <para>
   The same operator class name
   can be used for several different index methods (for example, both B-tree
   and hash index methods have operator classes named
   <literal>int4_ops</literal>), but each such class is an independent
   entity and must be defined separately.
  </para>
 </sect2>

 <sect2 id="xindex-strategies">
  <title>Index Method Strategies</title>

  <para>
   The operators associated with an operator class are identified by
   <quote>strategy numbers</quote>, which serve to identify the semantics of
   each operator within the context of its operator class.
   For example, B-trees impose a strict ordering on keys, lesser to greater,
   and so operators like <quote>less than</quote> and <quote>greater than or equal
   to</quote> are interesting with respect to a B-tree.
   Because
   <productname>PostgreSQL</productname> allows the user to define operators,
   <productname>PostgreSQL</productname> cannot look at the name of an operator
   (e.g., <literal>&lt;</literal> or <literal>&gt;=</literal>)