<!-- $PostgreSQL: pgsql/doc/src/sgml/gin.sgml,v 1.1 2006/09/04 20:10:53 momjian Exp $ -->

<chapter id="GIN">
<title>GIN Indexes</title>

   <indexterm>
    <primary>index</primary>
    <secondary>GIN</secondary>
   </indexterm>

<sect1 id="gin-intro">
 <title>Introduction</title>

 <para>
   <acronym>GIN</acronym> stands for Generalized Inverted Index.  It is
   an index structure storing a set of (key, posting list) pairs, where
   'posting list' is a set of documents in which the key occurs.
 </para>

 <para>
   It is generalized in the sense that a <acronym>GIN</acronym> index
   does not need to be aware of the operation that it accelerates.
   Instead, it uses custom strategies defined for particular data types.
 </para>

 <para>
  One advantage of <acronym>GIN</acronym> is that it allows the development
  of custom data types with the appropriate access methods, by
  an expert in the domain of the data type, rather than a database expert.
  This is much the same advantage as using <acronym>GiST</acronym>.
 </para>

  <para>
   The <acronym>GIN</acronym>
    implementation in <productname>PostgreSQL</productname> is primarily
    maintained by Teodor Sigaev and Oleg Bartunov, and there is more
    information on their
    <ulink url="http://www.sai.msu.su/~megera/oddmuse/index.cgi/Gin">website</ulink>.
  </para>

</sect1>

<sect1 id="gin-extensibility">
 <title>Extensibility</title>

 <para>
   The <acronym>GIN</acronym> interface has a high level of abstraction,
   requiring the access method implementer to only implement the semantics of
   the data type being accessed.  The <acronym>GIN</acronym> layer itself
   takes care of concurrency, logging and searching the tree structure.
 </para>

 <para>
   All it takes to get a <acronym>GIN</acronym> access method working
   is to implement four user-defined methods, which define the behavior of
   keys in the tree. In short, <acronym>GIN</acronym> combines extensibility
   along with generality, code reuse, and a clean interface.
 </para>

</sect1>

<sect1 id="gin-implementation">
 <title>Implementation</title>
 
 <para>
   There are four methods that an index operator class for
   <acronym>GIN</acronym> must provide:
 </para>

 <variablelist>
    <varlistentry>
     <term>compare</term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>extract value</term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>extract query</term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>consistent</term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>

  </variablelist>

</sect1>

<sect1 id="gin-examples">
 <title>Examples</title>

 <para>
  The <productname>PostgreSQL</productname> source distribution includes
  <acronym>GIN</acronym> classes for one-dimensional arrays of all internal 
  types.  The following
  <filename>contrib</> modules also contain <acronym>GIN</acronym>
  operator classes: 
 </para>
 
 <variablelist>
  <varlistentry>
   <term>intarray</term>
   <listitem>
    <para>Enhanced support for int4[]</para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>tsearch2</term>
   <listitem>
    <para>Support for inverted text indexing.  This is much faster for very
     large, mostly-static sets of documents.
    </para>
   </listitem>
  </varlistentry>

</chapter>
