begriffs open source - ai-pg/blob - full-docs/txt/btree-gist.txt

   1
   2 F.8. btree_gist — GiST operator classes with B-tree behavior #
   3
   4    F.8.1. Example Usage
   5    F.8.2. Authors
   6
   7    btree_gist provides GiST index operator classes that implement B-tree
   8    equivalent behavior for the data types int2, int4, int8, float4,
   9    float8, numeric, timestamp with time zone, timestamp without time zone,
  10    time with time zone, time without time zone, date, interval, oid,
  11    money, char, varchar, text, bytea, bit, varbit, macaddr, macaddr8,
  12    inet, cidr, uuid, bool and all enum types.
  13
  14    In general, these operator classes will not outperform the equivalent
  15    standard B-tree index methods, and they lack one major feature of the
  16    standard B-tree code: the ability to enforce uniqueness. However, they
  17    provide some other features that are not available with a B-tree index,
  18    as described below. Also, these operator classes are useful when a
  19    multicolumn GiST index is needed, wherein some of the columns are of
  20    data types that are only indexable with GiST but other columns are just
  21    simple data types. Lastly, these operator classes are useful for GiST
  22    testing and as a base for developing other GiST operator classes.
  23
  24    In addition to the typical B-tree search operators, btree_gist also
  25    provides index support for <> (“not equals”). This may be useful in
  26    combination with an exclusion constraint, as described below.
  27
  28    Also, for data types for which there is a natural distance metric,
  29    btree_gist defines a distance operator <->, and provides GiST index
  30    support for nearest-neighbor searches using this operator. Distance
  31    operators are provided for int2, int4, int8, float4, float8, timestamp
  32    with time zone, timestamp without time zone, time without time zone,
  33    date, interval, oid, and money.
  34
  35    By default btree_gist builds GiST index with sortsupport in sorted
  36    mode. This usually results in much faster index built speed. It is
  37    still possible to revert to buffered built strategy by using the
  38    buffering parameter when creating the index.
  39
  40    This module is considered “trusted”, that is, it can be installed by
  41    non-superusers who have CREATE privilege on the current database.
  42
  43 F.8.1. Example Usage #
  44
  45    Simple example using btree_gist instead of btree:
  46 CREATE TABLE test (a int4);
  47 -- create index
  48 CREATE INDEX testidx ON test USING GIST (a);
  49 -- query
  50 SELECT * FROM test WHERE a < 10;
  51 -- nearest-neighbor search: find the ten entries closest to "42"
  52 SELECT *, a <-> 42 AS dist FROM test ORDER BY a <-> 42 LIMIT 10;
  53
  54    Use an exclusion constraint to enforce the rule that a cage at a zoo
  55    can contain only one kind of animal:
  56 => CREATE TABLE zoo (
  57   cage   INTEGER,
  58   animal TEXT,
  59   EXCLUDE USING GIST (cage WITH =, animal WITH <>)
  60 );
  61
  62 => INSERT INTO zoo VALUES(123, 'zebra');
  63 INSERT 0 1
  64 => INSERT INTO zoo VALUES(123, 'zebra');
  65 INSERT 0 1
  66 => INSERT INTO zoo VALUES(123, 'lion');
  67 ERROR:  conflicting key value violates exclusion constraint "zoo_cage_animal_exc
  68 l"
  69 DETAIL:  Key (cage, animal)=(123, lion) conflicts with existing key (cage, anima
  70 l)=(123, zebra).
  71 => INSERT INTO zoo VALUES(124, 'lion');
  72 INSERT 0 1
  73
  74 F.8.2. Authors #
  75
  76    Teodor Sigaev (<teodor@stack.net>), Oleg Bartunov (<oleg@sai.msu.su>),
  77    Janko Richter (<jankorichter@yahoo.de>), and Paul Jungwirth
  78    (<pj@illuminatedcomputing.com>). See
  79    http://www.sai.msu.su/~megera/postgres/gist/ for additional
  80    information.