doc/src/sgml/btree-gist.sgml

   1 <!-- doc/src/sgml/btree-gist.sgml -->
   2
   3 <sect1 id="btree-gist" xreflabel="btree_gist">
   4  <title>btree_gist &mdash; GiST operator classes with B-tree behavior</title>
   5
   6  <indexterm zone="btree-gist">
   7   <primary>btree_gist</primary>
   8  </indexterm>
   9
  10  <para>
  11   <filename>btree_gist</filename> provides GiST index operator classes that
  12   implement B-tree equivalent behavior for the data types
  13   <type>int2</type>, <type>int4</type>, <type>int8</type>, <type>float4</type>,
  14   <type>float8</type>, <type>numeric</type>, <type>timestamp with time zone</type>,
  15   <type>timestamp without time zone</type>, <type>time with time zone</type>,
  16   <type>time without time zone</type>, <type>date</type>, <type>interval</type>,
  17   <type>oid</type>, <type>money</type>, <type>char</type>,
  18   <type>varchar</type>, <type>text</type>, <type>bytea</type>, <type>bit</type>,
  19   <type>varbit</type>, <type>macaddr</type>, <type>macaddr8</type>, <type>inet</type>,
  20   <type>cidr</type>, <type>uuid</type>, <type>bool</type> and all <type>enum</type> types.
  21  </para>
  22
  23  <para>
  24   In general, these operator classes will not outperform the equivalent
  25   standard B-tree index methods, and they lack one major feature of the
  26   standard B-tree code: the ability to enforce uniqueness.  However,
  27   they provide some other features that are not available with a B-tree
  28   index, as described below.  Also, these operator classes are useful
  29   when a multicolumn GiST index is needed, wherein some of the columns
  30   are of data types that are only indexable with GiST but other columns
  31   are just simple data types.  Lastly, these operator classes are useful for
  32   GiST testing and as a base for developing other GiST operator classes.
  33  </para>
  34
  35  <para>
  36   In addition to the typical B-tree search operators, <filename>btree_gist</filename>
  37   also provides index support for <literal>&lt;&gt;</literal> (<quote>not
  38   equals</quote>). This may be useful in combination with an
  39   <link linkend="sql-createtable-exclude">exclusion constraint</link>,
  40   as described below.
  41  </para>
  42
  43  <para>
  44   Also, for data types for which there is a natural distance metric,
  45   <filename>btree_gist</filename> defines a distance operator <literal>&lt;-&gt;</literal>,
  46   and provides GiST index support for nearest-neighbor searches using
  47   this operator.  Distance operators are provided for
  48   <type>int2</type>, <type>int4</type>, <type>int8</type>, <type>float4</type>,
  49   <type>float8</type>, <type>timestamp with time zone</type>,
  50   <type>timestamp without time zone</type>,
  51   <type>time without time zone</type>, <type>date</type>, <type>interval</type>,
  52   <type>oid</type>, and <type>money</type>.
  53  </para>
  54
  55  <para>
  56   This module is considered <quote>trusted</quote>, that is, it can be
  57   installed by non-superusers who have <literal>CREATE</literal> privilege
  58   on the current database.
  59  </para>
  60
  61  <sect2 id="btree-gist-example-usage">
  62   <title>Example Usage</title>
  63
  64   <para>
  65    Simple example using <literal>btree_gist</literal> instead of <literal>btree</literal>:
  66   </para>
  67
  68 <programlisting>
  69 CREATE TABLE test (a int4);
  70 -- create index
  71 CREATE INDEX testidx ON test USING GIST (a);
  72 -- query
  73 SELECT * FROM test WHERE a &lt; 10;
  74 -- nearest-neighbor search: find the ten entries closest to "42"
  75 SELECT *, a &lt;-&gt; 42 AS dist FROM test ORDER BY a &lt;-&gt; 42 LIMIT 10;
  76 </programlisting>
  77
  78   <para>
  79    Use an <link linkend="sql-createtable-exclude">exclusion
  80    constraint</link> to enforce the rule that a cage at a zoo
  81    can contain only one kind of animal:
  82   </para>
  83
  84 <programlisting>
  85 =&gt; CREATE TABLE zoo (
  86   cage   INTEGER,
  87   animal TEXT,
  88   EXCLUDE USING GIST (cage WITH =, animal WITH &lt;&gt;)
  89 );
  90
  91 =&gt; INSERT INTO zoo VALUES(123, 'zebra');
  92 INSERT 0 1
  93 =&gt; INSERT INTO zoo VALUES(123, 'zebra');
  94 INSERT 0 1
  95 =&gt; INSERT INTO zoo VALUES(123, 'lion');
  96 ERROR:  conflicting key value violates exclusion constraint "zoo_cage_animal_excl"
  97 DETAIL:  Key (cage, animal)=(123, lion) conflicts with existing key (cage, animal)=(123, zebra).
  98 =&gt; INSERT INTO zoo VALUES(124, 'lion');
  99 INSERT 0 1
 100 </programlisting>
 101
 102  </sect2>
 103
 104  <sect2 id="btree-gist-authors">
 105   <title>Authors</title>
 106
 107   <para>
 108    Teodor Sigaev (<email>teodor@stack.net</email>),
 109    Oleg Bartunov (<email>oleg@sai.msu.su</email>),
 110    Janko Richter (<email>jankorichter@yahoo.de</email>), and
 111    Paul Jungwirth (<email>pj@illuminatedcomputing.com</email>).  See
 112    <ulink url="http://www.sai.msu.su/~megera/postgres/gist/"></ulink>
 113    for additional information.
 114   </para>
 115
 116  </sect2>
 117
 118 </sect1>