← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/btree-gist.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

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