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

<chapter id="indexam">
 <title>Index Access Method Interface Definition</title>

 <indexterm>
  <primary>Index Access Method</primary>
 </indexterm>
 <indexterm>
  <primary>indexam</primary>
  <secondary>Index Access Method</secondary>
 </indexterm>

  <para>
   This chapter defines the interface between the core
   <productname>PostgreSQL</productname> system and <firstterm>index access
   methods</firstterm>, which manage individual index types.  The core system
   knows nothing about indexes beyond what is specified here, so it is
   possible to develop entirely new index types by writing add-on code.
  </para>

  <para>
   All indexes in <productname>PostgreSQL</productname> are what are known
   technically as <firstterm>secondary indexes</firstterm>; that is, the index is
   physically separate from the table file that it describes.  Each index
   is stored as its own physical <firstterm>relation</firstterm> and so is described
   by an entry in the <structname>pg_class</structname> catalog.  The contents of an
   index are entirely under the control of its index access method.  In
   practice, all index access methods divide indexes into standard-size
   pages so that they can use the regular storage manager and buffer manager
   to access the index contents.  (All the existing index access methods
   furthermore use the standard page layout described in <xref
   linkend="storage-page-layout"/>, and most use the same format for index
   tuple headers; but these decisions are not forced on an access method.)
  </para>

  <para>
   An index is effectively a mapping from some data key values to
   <firstterm>tuple identifiers</firstterm>, or <acronym>TIDs</acronym>, of row versions
   (tuples) in the index's parent table.  A TID consists of a
   block number and an item number within that block (see <xref
   linkend="storage-page-layout"/>).  This is sufficient
   information to fetch a particular row version from the table.
   Indexes are not directly aware that under MVCC, there might be multiple
   extant versions of the same logical row; to an index, each tuple is
   an independent object that needs its own index entry.  Thus, an
   update of a row always creates all-new index entries for the row, even if
   the key values did not change.  (<link linkend="storage-hot">HOT
   tuples</link> are an exception to this
   statement; but indexes do not deal with those, either.)  Index entries for
   dead tuples are reclaimed (by vacuuming) when the dead tuples themselves
   are reclaimed.
  </para>

 <sect1 id="index-api">
  <title>Basic API Structure for Indexes</title>

  <para>
   Each index access method is described by a row in the
   <link linkend="catalog-pg-am"><structname>pg_am</structname></link>
   system catalog.  The <structname>pg_am</structname> entry
   specifies a name and a <firstterm>handler function</firstterm> for the index
   access method.  These entries can be created and deleted using the
   <xref linkend="sql-create-access-method"/> and
   <xref linkend="sql-drop-access-method"/> SQL commands.
  </para>

  <para>
   An index access method handler function must be declared to accept a
   single argument of type <type>internal</type> and to return the
   pseudo-type <type>index_am_handler</type>.  The argument is a dummy value that
   simply serves to prevent handler functions from being called directly from
   SQL commands.  The result of the function must be a palloc'd struct of
   type <structname>IndexAmRoutine</structname>, which contains everything
   that the core code needs to know to make use of the index access method.
   The <structname>IndexAmRoutine</structname> struct, also called the access
   method's <firstterm>API struct</firstterm>, includes fields specifying assorted
   fixed properties of the access method, such as whether it can support
   multicolumn indexes.  More importantly, it contains pointers to support
   functions for the access method,