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

<sect1 id="gin">
<title>GIN Indexes</title>

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

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

 <para>
  <acronym>GIN</acronym> stands for Generalized Inverted Index.
  <acronym>GIN</acronym> is designed for handling cases where the items
  to be indexed are composite values, and the queries to be handled by
  the index need to search for element values that appear within
  the composite items.  For example, the items could be documents,
  and the queries could be searches for documents containing specific words.
 </para>

 <para>
  We use the word <firstterm>item</firstterm> to refer to a composite value that
  is to be indexed, and the word <firstterm>key</firstterm> to refer to an element
  value.  <acronym>GIN</acronym> always stores and searches for keys,
  not item values per se.
 </para>

 <para>
  A <acronym>GIN</acronym> index stores a set of (key, posting list) pairs,
  where a <firstterm>posting list</firstterm> is a set of row IDs in which the key
  occurs.  The same row ID can appear in multiple posting lists, since
  an item can contain more than one key.  Each key value is stored only
  once, so a <acronym>GIN</acronym> index is very compact for cases
  where the same key appears many times.
 </para>

 <para>
  <acronym>GIN</acronym> is generalized in the sense that the
  <acronym>GIN</acronym> access method code does not need to know the
  specific operations that it accelerates.
  Instead, it uses custom strategies defined for particular data types.
  The strategy defines how keys are extracted from indexed items and
  query conditions, and how to determine whether a row that contains
  some of the key values in a query actually satisfies the query.
 </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. There is more
  information about <acronym>GIN</acronym> on their
  <ulink url="http://www.sai.msu.su/~megera/wiki/Gin">website</ulink>.
 </para>
</sect2>

<sect2 id="gin-builtin-opclasses">
 <title>Built-in Operator Classes</title>

 <para>
  The core <productname>PostgreSQL</productname> distribution
  includes the <acronym>GIN</acronym> operator classes shown in
  <xref linkend="gin-builtin-opclasses-table"/>.
  (Some of the optional modules described in <xref linkend="contrib"/>
  provide additional <acronym>GIN</acronym> operator classes.)
 </para>

  <table id="gin-builtin-opclasses-table">
   <title>Built-in <acronym>GIN</acronym> Operator Classes</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Name</entry>
      <entry>Indexable Operators</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry morerows="3" valign="middle"><literal>array_ops</literal></entry>
      <entry><literal>&amp;&amp; (anyarray,anyarray)</literal></entry>
     </row>
     <row>
      <entry><literal>@&gt; (anyarray,anyarray)</literal></entry>
     </row>
     <row>
      <entry><literal>&lt;@ (anyarray,anyarray)</literal></entry>
     </row>
     <row>
      <entry><literal>= (anyarray,anyarray)</literal></entry>
     </row>
     <row>
      <entry morerows="5" valign="middle"><literal>jsonb_ops</literal></entry>
      <entry><literal>@&gt; (jsonb,jsonb)</literal></entry>
     </row>
     <row>
      <entry><literal>@? (jsonb,jsonpath)</literal></entry>
     </row>
     <row>
      <entry><literal>@@ (jsonb,jsonpath)</literal></entry>
     </row>
     <row>
      <entry><literal>? (jsonb,text)</literal></entry>
     </row>
     <row>
      <entry><literal>?| (jsonb,text[])</literal></entry>