2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/btree-gist.sgml -->
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2011-05-08 04:29:20 +02:00
|
|
|
<sect1 id="btree-gist" xreflabel="btree_gist">
|
2007-12-02 23:33:20 +01:00
|
|
|
<title>btree_gist</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<indexterm zone="btree-gist">
|
2007-12-02 23:33:20 +01:00
|
|
|
<primary>btree_gist</primary>
|
2007-11-11 00:30:46 +01:00
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<filename>btree_gist</filename> provides GiST index operator classes that
|
2010-08-17 06:37:21 +02:00
|
|
|
implement B-tree equivalent behavior for the data types
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>int2</type>, <type>int4</type>, <type>int8</type>, <type>float4</type>,
|
|
|
|
<type>float8</type>, <type>numeric</type>, <type>timestamp with time zone</type>,
|
|
|
|
<type>timestamp without time zone</type>, <type>time with time zone</type>,
|
|
|
|
<type>time without time zone</type>, <type>date</type>, <type>interval</type>,
|
|
|
|
<type>oid</type>, <type>money</type>, <type>char</type>,
|
|
|
|
<type>varchar</type>, <type>text</type>, <type>bytea</type>, <type>bit</type>,
|
|
|
|
<type>varbit</type>, <type>macaddr</type>, <type>macaddr8</type>, <type>inet</type>,
|
2021-12-11 04:59:15 +01:00
|
|
|
<type>cidr</type>, <type>uuid</type>, <type>bool</type> and all <type>enum</type> types.
|
2007-12-06 05:12:10 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In general, these operator classes will not outperform the equivalent
|
2010-08-17 06:37:21 +02:00
|
|
|
standard B-tree index methods, and they lack one major feature of the
|
|
|
|
standard B-tree code: the ability to enforce uniqueness. However,
|
2011-03-02 20:43:24 +01:00
|
|
|
they provide some other features that are not available with a B-tree
|
|
|
|
index, as described below. Also, these operator classes are useful
|
2011-05-19 00:14:45 +02:00
|
|
|
when a multicolumn GiST index is needed, wherein some of the columns
|
2011-03-02 20:43:24 +01:00
|
|
|
are of data types that are only indexable with GiST but other columns
|
|
|
|
are just simple data types. Lastly, these operator classes are useful for
|
|
|
|
GiST testing and as a base for developing other GiST operator classes.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
|
2010-08-02 18:26:48 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
In addition to the typical B-tree search operators, <filename>btree_gist</filename>
|
2011-03-02 20:43:24 +01:00
|
|
|
also provides index support for <literal><></literal> (<quote>not
|
2010-08-03 17:15:31 +02:00
|
|
|
equals</quote>). This may be useful in combination with an
|
2017-10-20 03:16:39 +02:00
|
|
|
<link linkend="sql-createtable-exclude">exclusion constraint</link>,
|
2010-08-03 17:15:31 +02:00
|
|
|
as described below.
|
2010-08-02 18:26:48 +02:00
|
|
|
</para>
|
|
|
|
|
2011-03-02 20:43:24 +01:00
|
|
|
<para>
|
|
|
|
Also, for data types for which there is a natural distance metric,
|
2017-10-09 03:44:17 +02:00
|
|
|
<filename>btree_gist</filename> defines a distance operator <literal><-></literal>,
|
2011-03-02 20:43:24 +01:00
|
|
|
and provides GiST index support for nearest-neighbor searches using
|
|
|
|
this operator. Distance operators are provided for
|
2017-10-09 03:44:17 +02:00
|
|
|
<type>int2</type>, <type>int4</type>, <type>int8</type>, <type>float4</type>,
|
|
|
|
<type>float8</type>, <type>timestamp with time zone</type>,
|
|
|
|
<type>timestamp without time zone</type>,
|
|
|
|
<type>time without time zone</type>, <type>date</type>, <type>interval</type>,
|
|
|
|
<type>oid</type>, and <type>money</type>.
|
2011-03-02 20:43:24 +01:00
|
|
|
</para>
|
|
|
|
|
2020-02-13 21:02:35 +01:00
|
|
|
<para>
|
|
|
|
This module is considered <quote>trusted</quote>, that is, it can be
|
|
|
|
installed by non-superusers who have <literal>CREATE</literal> privilege
|
|
|
|
on the current database.
|
|
|
|
</para>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<sect2>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Example Usage</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2010-08-02 18:26:48 +02:00
|
|
|
<para>
|
2011-05-19 00:14:45 +02:00
|
|
|
Simple example using <literal>btree_gist</literal> instead of <literal>btree</literal>:
|
2010-08-02 18:26:48 +02:00
|
|
|
</para>
|
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE test (a int4);
|
|
|
|
-- create index
|
2015-05-15 17:42:29 +02:00
|
|
|
CREATE INDEX testidx ON test USING GIST (a);
|
2007-12-06 05:12:10 +01:00
|
|
|
-- query
|
|
|
|
SELECT * FROM test WHERE a < 10;
|
2011-03-02 20:43:24 +01:00
|
|
|
-- nearest-neighbor search: find the ten entries closest to "42"
|
|
|
|
SELECT *, a <-> 42 AS dist FROM test ORDER BY a <-> 42 LIMIT 10;
|
2010-08-02 18:26:48 +02:00
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>
|
2017-10-20 03:16:39 +02:00
|
|
|
Use an <link linkend="sql-createtable-exclude">exclusion
|
2010-08-03 17:15:31 +02:00
|
|
|
constraint</link> to enforce the rule that a cage at a zoo
|
2010-08-02 18:26:48 +02:00
|
|
|
can contain only one kind of animal:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<programlisting>
|
2010-08-03 17:15:31 +02:00
|
|
|
=> CREATE TABLE zoo (
|
2010-08-02 18:26:48 +02:00
|
|
|
cage INTEGER,
|
|
|
|
animal TEXT,
|
2015-05-15 17:42:29 +02:00
|
|
|
EXCLUDE USING GIST (cage WITH =, animal WITH <>)
|
2010-08-02 18:26:48 +02:00
|
|
|
);
|
|
|
|
|
2010-08-03 17:15:31 +02:00
|
|
|
=> INSERT INTO zoo VALUES(123, 'zebra');
|
2010-08-02 18:26:48 +02:00
|
|
|
INSERT 0 1
|
2010-08-03 17:15:31 +02:00
|
|
|
=> INSERT INTO zoo VALUES(123, 'zebra');
|
2010-08-02 18:26:48 +02:00
|
|
|
INSERT 0 1
|
2010-08-03 17:15:31 +02:00
|
|
|
=> INSERT INTO zoo VALUES(123, 'lion');
|
2010-08-02 18:26:48 +02:00
|
|
|
ERROR: conflicting key value violates exclusion constraint "zoo_cage_animal_excl"
|
|
|
|
DETAIL: Key (cage, animal)=(123, lion) conflicts with existing key (cage, animal)=(123, zebra).
|
2010-08-03 17:15:31 +02:00
|
|
|
=> INSERT INTO zoo VALUES(124, 'lion');
|
2010-08-02 18:26:48 +02:00
|
|
|
INSERT 0 1
|
2007-12-06 05:12:10 +01:00
|
|
|
</programlisting>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<sect2>
|
|
|
|
<title>Authors</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2016-07-15 04:28:58 +02:00
|
|
|
Teodor Sigaev (<email>teodor@stack.net</email>),
|
2016-11-29 20:08:23 +01:00
|
|
|
Oleg Bartunov (<email>oleg@sai.msu.su</email>),
|
|
|
|
Janko Richter (<email>jankorichter@yahoo.de</email>), and
|
|
|
|
Paul Jungwirth (<email>pj@illuminatedcomputing.com</email>). See
|
2010-03-17 18:12:31 +01:00
|
|
|
<ulink url="http://www.sai.msu.su/~megera/postgres/gist/"></ulink>
|
2007-12-06 05:12:10 +01:00
|
|
|
for additional information.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|