1 files changed, 135 insertions, 0 deletions
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
new file mode 100644
index 0000000000..4420fcd0ab
--- /dev/null
+++ b/doc/src/sgml/gin.sgml
@@ -0,0 +1,135 @@
+<!-- $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>