Add GIN documentation.

Christopher Kings-Lynne

doc/src/sgml/filelist.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.44 2005/09/12 22:11:38 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.45 2006/09/04 20:10:53 momjian Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -78,6 +78,7 @@
 <!entity catalogs   SYSTEM "catalogs.sgml">
 <!entity geqo       SYSTEM "geqo.sgml">
 <!entity gist       SYSTEM "gist.sgml">
+<!entity gin        SYSTEM "gin.sgml">
 <!entity planstats    SYSTEM "planstats.sgml">
 <!entity indexam    SYSTEM "indexam.sgml">
 <!entity nls        SYSTEM "nls.sgml">

doc/src/sgml/gin.sgml

+<!-- $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>

doc/src/sgml/xindex.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.43 2006/03/10 19:10:49 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.44 2006/09/04 20:10:53 momjian Exp $ -->
 
 <sect1 id="xindex">
  <title>Interfacing Extensions To Indexes</title>
@@ -380,6 +380,41 @@
     </tgroup>
    </table>
 
+  <para>
+   GIN indexes require four support functions,
+   shown in <xref linkend="xindex-gin-support-table">.
+  </para>
+
+   <table tocentry="1" id="xindex-gin-support-table">
+    <title>GIN Support Functions</title>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>Function</entry>
+       <entry>Support Number</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>compare</entry>
+       <entry>1</entry>
+      </row>
+      <row>
+       <entry>extract value</entry>
+       <entry>2</entry>
+      </row>
+      <row>
+       <entry>extract query</entry>
+       <entry>3</entry>
+      </row>
+      <row>
+       <entry>consistent</entry>
+       <entry>4</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
   <para>
    Unlike strategy operators, support functions return whichever data
    type the particular index method expects; for example in the case