head	1.15;
access;
symbols
	REL7_4_29:1.10
	REL8_0_25:1.10.8.1
	REL8_1_21:1.12
	REL8_2_17:1.13.2.1
	REL7_4_28:1.10
	REL8_0_24:1.10.8.1
	REL8_1_20:1.12
	REL8_2_16:1.13.2.1
	REL7_4_27:1.10
	REL8_0_23:1.10.8.1
	REL8_1_19:1.12
	REL8_2_15:1.13.2.1
	REL7_4_26:1.10
	REL8_0_22:1.10.8.1
	REL8_1_18:1.12
	REL8_2_14:1.13.2.1
	REL7_4_25:1.10
	REL8_0_21:1.10.8.1
	REL8_1_17:1.12
	REL8_2_13:1.13.2.1
	REL7_4_24:1.10
	REL8_0_20:1.10.8.1
	REL8_1_16:1.12
	REL8_2_12:1.13.2.1
	REL7_4_23:1.10
	REL8_0_19:1.10.8.1
	REL8_1_15:1.12
	REL8_2_11:1.13.2.1
	REL7_4_22:1.10
	REL8_0_18:1.10.8.1
	REL8_1_14:1.12
	REL8_2_10:1.13.2.1
	REL7_4_21:1.10
	REL8_0_17:1.10.8.1
	REL8_1_13:1.12
	REL8_2_9:1.13.2.1
	REL7_4_20:1.10
	REL8_0_16:1.10.8.1
	REL8_1_12:1.12
	REL8_2_8:1.13.2.1
	REL8_2_7:1.13.2.1
	REL7_3_21:1.9.2.1
	REL7_4_19:1.10
	REL8_0_15:1.10.8.1
	REL8_1_11:1.12
	REL8_2_6:1.13.2.1
	REL8_3_BETA2:1.14
	REL8_3_BETA1:1.14
	REL7_3_20:1.9.2.1
	REL7_4_18:1.10
	REL8_0_14:1.10.8.1
	REL8_1_10:1.12
	REL8_2_5:1.13.2.1
	REL7_3_19:1.9.2.1
	REL7_4_17:1.10
	REL8_0_13:1.10.8.1
	REL8_1_9:1.12
	REL8_2_4:1.13
	REL8_0_12:1.10.8.1
	REL8_1_8:1.12
	REL8_2_3:1.13
	REL7_3_18:1.9.2.1
	REL7_4_16:1.10
	REL8_0_11:1.10.8.1
	REL8_1_7:1.12
	REL8_2_2:1.13
	REL8_0_10:1.10.8.1
	REL8_1_6:1.12
	REL8_2_1:1.13
	REL7_4_15:1.10
	REL7_3_17:1.9.2.1
	REL8_2_STABLE:1.13.0.2
	REL8_2_0:1.13
	REL8_2_RC1:1.13
	REL8_2_BETA3:1.13
	REL8_2_BETA2:1.13
	REL8_1_5:1.12
	REL8_0_9:1.10.8.1
	REL7_4_14:1.10
	REL7_3_16:1.9.2.1
	REL8_2_BETA1:1.13
	REL7_3_15:1.9.2.1
	REL7_4_13:1.10
	REL8_0_8:1.10.8.1
	REL8_1_4:1.12
	REL7_3_14:1.9.2.1
	REL7_4_12:1.10
	REL8_0_7:1.10.8.1
	REL8_1_3:1.12
	REL7_3_13:1.9.2.1
	REL7_4_11:1.10
	REL8_0_6:1.10.8.1
	REL8_1_2:1.12
	REL7_3_12:1.9.2.1
	REL7_4_10:1.10
	REL8_0_5:1.10.8.1
	REL8_1_1:1.12
	REL8_1_STABLE:1.12.0.2
	REL8_1_0:1.12
	REL8_1_0RC1:1.12
	REL8_1_0BETA4:1.12
	REL8_1_0BETA3:1.12
	REL7_3_11:1.9.2.1
	REL7_4_9:1.10
	REL8_0_4:1.10.8.1
	REL8_1_0BETA2:1.11
	REL8_1_0BETA1:1.11
	REL7_2_8:1.7
	REL7_3_10:1.9.2.1
	REL7_4_8:1.10
	REL8_0_3:1.10.8.1
	REL8_0_2:1.10.8.1
	REL7_2_7:1.7
	REL7_3_9:1.9.2.1
	REL7_4_7:1.10
	REL8_0_1:1.10.8.1
	REL8_0_STABLE:1.10.0.8
	REL8_0_0:1.10.0.6
	REL8_0_0RC5:1.10
	REL8_0_0RC4:1.10
	REL8_0_0RC3:1.10
	REL8_0_0RC2:1.10
	REL8_0_0RC1:1.10
	REL8_0_0BETA5:1.10
	REL8_0_0BETA4:1.10
	REL7_4_6:1.10
	REL7_3_8:1.9.2.1
	REL7_2_6:1.7
	REL8_0_0BETA3:1.10
	REL8_0_0BETA2:1.10
	REL7_2_5:1.7
	REL7_4_5:1.10
	REL7_3_7:1.9.2.1
	REL7_4_4:1.10
	REL8_0_0BETA1:1.10
	REL7_4_3:1.10
	REL7_4_2:1.10
	REL7_3_6:1.9.2.1
	REL7_4_1:1.10
	REL7_3_5:1.9.2.1
	REL7_4:1.10
	REL7_4_RC2:1.10
	REL7_4_STABLE:1.10.0.4
	REL7_4_RC1:1.10
	REL7_4_BETA5:1.10
	REL7_4_BETA4:1.10
	REL7_4_BETA3:1.10
	REL7_4_BETA2:1.10
	WIN32_DEV:1.10.0.2
	REL7_4_BETA1:1.10
	REL7_3_4:1.9.2.1
	REL7_3_2:1.9.2.1
	REL7_2_4:1.7
	REL7_3_STABLE:1.9.0.2
	REL7_2_3:1.7
	REL7_2_STABLE:1.7.0.2
	REL7_2:1.7
	REL7_2_RC2:1.7
	REL7_2_RC1:1.7
	REL7_2_BETA5:1.7
	REL7_2_BETA4:1.7
	REL7_2_BETA3:1.7
	REL7_2_BETA2:1.7
	REL7_2_BETA1:1.7
	REL7_1_2:1.3
	REL7_1_STABLE:1.3.0.2
	REL7_1:1.3;
locks; strict;
comment	@# @;


1.15
date	2007.11.10.23.30.45;	author momjian;	state dead;
branches;
next	1.14;

1.14
date	2007.09.14.03.25.31;	author tgl;	state Exp;
branches;
next	1.13;

1.13
date	2006.09.10.17.36.51;	author tgl;	state Exp;
branches
	1.13.2.1;
next	1.12;

1.12
date	2005.10.03.14.41.42;	author teodor;	state Exp;
branches;
next	1.11;

1.11
date	2005.01.27.14.14.01;	author teodor;	state Exp;
branches;
next	1.10;

1.10
date	2002.12.27.14.10.29;	author momjian;	state Exp;
branches
	1.10.8.1;
next	1.9;

1.9
date	2002.10.03.17.16.31;	author momjian;	state Exp;
branches
	1.9.2.1;
next	1.8;

1.8
date	2002.08.10.20.38.29;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2001.10.04.15.41.14;	author momjian;	state Exp;
branches;
next	1.6;

1.6
date	2001.09.30.16.16.44;	author tgl;	state Exp;
branches;
next	1.5;

1.5
date	2001.09.23.04.16.16;	author momjian;	state Exp;
branches;
next	1.4;

1.4
date	2001.08.21.16.35.57;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2001.03.20.03.08.12;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2001.03.17.21.59.42;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2001.01.12.00.16.23;	author scrappy;	state Exp;
branches;
next	;

1.9.2.1
date	2002.12.27.14.10.49;	author momjian;	state Exp;
branches;
next	;

1.10.8.1
date	2005.01.28.22.58.59;	author tgl;	state Exp;
branches;
next	;

1.13.2.1
date	2007.09.14.03.25.37;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.15
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@This is an implementation of RD-tree data structure using GiST interface
of PostgreSQL. It has built-in lossy compression.

Current implementation provides index support for one-dimensional array of
integers: gist__int_ops, suitable for small and medium size of arrays (used by
default), and gist__intbig_ops for indexing large arrays (we use superimposed
signature with length of 4096 bits to represent sets).  There is also a
non-default gin__int_ops for GIN indexes on integer arrays.

All work was done by Teodor Sigaev (teodor@@stack.net) and Oleg Bartunov
(oleg@@sai.msu.su). See http://www.sai.msu.su/~megera/postgres/gist
for additional information. Andrey Oktyabrski did a great work on 
adding new functions and operations.


FUNCTIONS:

  int   icount(int[]) - the number of elements in intarray

test=# select icount('{1,2,3}'::int[]);   
 icount 
--------
      3
(1 row)

  int[] sort(int[], 'asc' | 'desc') - sort intarray

test=# select sort('{1,2,3}'::int[],'desc');
  sort   
---------
 {3,2,1}
(1 row)

  int[] sort(int[]) - sort in ascending order
  int[] sort_asc(int[]),sort_desc(int[]) - shortcuts for sort 

  int[] uniq(int[]) - returns unique elements

test=# select uniq(sort('{1,2,3,2,1}'::int[]));
  uniq   
---------
 {1,2,3}
(1 row)

  int   idx(int[], int item) - returns index of first intarray matching element to item, or
                              '0' if matching failed.

test=# select idx('{1,2,3,2,1}'::int[],2);
 idx 
-----
   2
(1 row)


  int[] subarray(int[],int START [, int LEN]) - returns part of intarray starting from
                                                element number START (from 1) and length LEN. 

test=# select subarray('{1,2,3,2,1}'::int[],2,3);
 subarray 
----------
 {2,3,2}
(1 row)

  int[] intset(int4) - casting int4 to int[]

test=# select intset(1);
 intset 
--------
 {1}
(1 row)

OPERATIONS:

  int[] && int[]  - overlap - returns TRUE if arrays have at least one common element
  int[] @@> int[]  - contains - returns TRUE if left array contains right array
  int[] <@@ int[]  - contained - returns TRUE if left array is contained in right array
  # int[]         - returns the number of elements in array
  int[] + int     - push element to array ( add to end of array)
  int[] + int[]   - merge of arrays (right array added to the end of left one)
  int[] - int     - remove entries matched by right argument from array
  int[] - int[]   - remove right array from left
  int[] | int     - returns intarray - union of arguments
  int[] | int[]   - returns intarray as a union of two arrays
  int[] & int[]   - returns intersection of arrays
  int[] @@@@ query_int - returns TRUE if array satisfies query (like '1&(2|3)') 
  query_int ~~ int[] - returns TRUE if array satisfies query (commutator of @@@@)

(Before PostgreSQL 8.2, the containment operators @@> and <@@ were
respectively called @@ and ~.  These names are still available, but are
deprecated and will eventually be retired.  Notice that the old names
are reversed from the convention formerly followed by the core geometric
datatypes!)

CHANGES:

August 6, 2002
   1. Reworked patch from Andrey Oktyabrski (ano@@spider.ru) with
      functions: icount, sort, sort_asc, uniq, idx, subarray
      operations: #, +, -, |, &
October 1, 2001
   1. Change search method in array to binary
September 28, 2001
   1. gist__int_ops now is without lossy
   2. add sort entry in picksplit
September 21, 2001
   1. Added support for boolean query (indexable operator @@@@, looks like
      a @@@@ '1|(2&3)', perfomance is better in any case )
   2. Done some small optimizations
March 19, 2001
   1. Added support for toastable keys
   2. Improved split algorithm for intbig (selection speedup is about 30%)

INSTALLATION:

  gmake
  gmake install
  -- load functions
  psql <database> < _int.sql 

REGRESSION TEST:

   gmake installcheck

EXAMPLE USAGE:

  create table message (mid int not null,sections int[]);
  create table message_section_map (mid int not null,sid int not null);

  -- create indices
CREATE unique index message_key on message ( mid );
CREATE unique index message_section_map_key2 on message_section_map (sid, mid );
CREATE INDEX message_rdtree_idx on message using gist ( sections gist__int_ops);

  -- select some messages with section in 1 OR 2 - OVERLAP operator
  select message.mid from message where message.sections && '{1,2}';  

  -- select messages contains in sections 1 AND 2 - CONTAINS operator
  select message.mid from message where message.sections @@> '{1,2}';
  -- the same, CONTAINED operator
  select message.mid from message where '{1,2}' <@@ message.sections;

BENCHMARK:

  subdirectory bench contains benchmark suite.
  cd ./bench
  1. createdb TEST
  2. psql TEST < ../_int.sql
  3. ./create_test.pl | psql TEST
  4. ./bench.pl - perl script to benchmark queries, supports OR, AND queries
                  with/without RD-Tree. Run script without arguments to 
                  see availbale options.

     a)test without RD-Tree (OR)
       ./bench.pl -d TEST -c -s 1,2 -v
     b)test with RD-Tree 
       ./bench.pl -d TEST -c -s 1,2 -v -r

BENCHMARKS:

Size of table <message>: 200000
Size of table <message_section_map>: 269133 

Distribution of messages by sections:

section 0: 74377 messages
section 1: 16284 messages
section 50: 1229 messages
section 99: 683 messages

old - without RD-Tree support,
new - with RD-Tree

+----------+---------------+----------------+
|Search set|OR, time in sec|AND, time in sec|
|          +-------+-------+--------+-------+
|          |  old  |  new  |   old  |  new  |
+----------+-------+-------+--------+-------+
|         1|  0.625|  0.101|       -|      -|
+----------+-------+-------+--------+-------+
|        99|  0.018|  0.017|       -|      -|
+----------+-------+-------+--------+-------+
|       1,2|  0.766|  0.133|   0.628|  0.045|
+----------+-------+-------+--------+-------+
| 1,2,50,65|  0.794|  0.141|   0.030|  0.006|
+----------+-------+-------+--------+-------+
@


1.14
log
@Remove ill-considered (not to mention undocumented) attempt to make
contrib/intarray's GIN opclass override the built-in default.  Per bug #3048
and other complaints.
@
text
@@


1.13
log
@Rename contrib contains/contained-by operators to @@> and <@@, per discussion.
@
text
@d5 1
a5 1
int4's - gist__int_ops, suitable for small and medium size of arrays (used on
d7 2
a8 1
signature with length of 4096 bits to represent sets).
@


1.13.2.1
log
@Remove ill-considered (not to mention undocumented) attempt to make
contrib/intarray's GIN opclass override the built-in default.  Per bug #3048
and other complaints.
@
text
@d5 1
a5 1
integers: gist__int_ops, suitable for small and medium size of arrays (used by
d7 1
a7 2
signature with length of 4096 bits to represent sets).  There is also a
non-default gin__int_ops for GIN indexes on integer arrays.
@


1.12
log
@Optimize benchmark query and update benchmark's results.
@
text
@d73 4
a76 4
  int[] && int[]  - overlap - returns TRUE if arrays has at least one common elements.
  int[] @@  int[]  - contains - returns TRUE if left array contains right array
  int[] ~ int[]   - contained - returns TRUE if left array is contained in right array
  # int[]         - return the number of elements in array
d84 8
a91 2
  int[] @@@@ query_int  - returns TRUE if array satisfies query (like '1&(2|3)') 
  query_int ~~ int[]  - -/-
d137 1
a137 1
  select message.mid from message where message.sections @@ '{1,2}';
d139 1
a139 1
  select message.mid from message where '{1,2}' ~ message.sections;
@


1.11
log
@Add intset() to README
@
text
@d147 1
a147 1
       ./bench.pl -d TEST -s 1,2 -v
d149 1
a149 1
       ./bench.pl -d TEST -s 1,2 -v -r
d154 1
a154 1
Size of table <message_section_map>: 268538 
d158 4
a161 4
section 0: 73899 messages
section 1: 16298 messages
section 50: 1241 messages
section 99: 705 messages
d171 1
a171 1
|         1|  1.427|  0.215|       -|      -|
d173 1
a173 1
|        99|  1.029|  0.018|       -|      -|
d175 1
a175 1
|       1,2|  1.829|  0.334|   5.654|  0.042|
d177 1
a177 1
| 1,2,50,60|  2.057|  0.359|   5.044|  0.007|
@


1.10
log
@Small fix in documentation and some examples of usage. Please, apply to
7.3 and current CVS

Oleg Bartunov
@
text
@d63 7
@


1.10.8.1
log
@Add intset() to README (backpatch teodor's docs fix in HEAD).
@
text
@a62 7
  int[] intset(int4) - casting int4 to int[]

test=# select intset(1);
 intset 
--------
 {1}
(1 row)
@


1.9
log
@This is small README fix for contrib/intarray. Thank you.

Teodor Sigaev
@
text
@d11 1
a11 1
for additional information. Andrey Oktyabrski has done a great work on 
d18 7
d26 7
d35 1
d37 7
d46 8
d57 7
d73 1
a73 1
  int[] - int[]   - remove left array from right
@


1.9.2.1
log
@Small fix in documentation and some examples of usage. Please, apply to
7.3 and current CVS

Oleg Bartunov
@
text
@d11 1
a11 1
for additional information. Andrey Oktyabrski did a great work on 
a17 7

test=# select icount('{1,2,3}'::int[]);   
 icount 
--------
      3
(1 row)

a18 7

test=# select sort('{1,2,3}'::int[],'desc');
  sort   
---------
 {3,2,1}
(1 row)

a20 1

a21 7

test=# select uniq(sort('{1,2,3,2,1}'::int[]));
  uniq   
---------
 {1,2,3}
(1 row)

a23 8

test=# select idx('{1,2,3,2,1}'::int[],2);
 idx 
-----
   2
(1 row)


a26 7
test=# select subarray('{1,2,3,2,1}'::int[],2,3);
 subarray 
----------
 {2,3,2}
(1 row)


d36 1
a36 1
  int[] - int[]   - remove right array from left
@


1.8
log
@August 6, 2002
   1. Reworked patch from Andrey Oktyabrski (ano@@spider.ru) with
      functions: icount, sort, sort_asc, uniq, idx, subarray
      operations: #, +, -, |, &

FUNCTIONS:

  int   icount(int[]) - the number of elements in intarray
  int[] sort(int[], 'asc' | 'desc') - sort intarray
  int[] sort(int[]) - sort in ascending order
  int[] sort_asc(int[]),sort_desc(int[]) - shortcuts for sort
  int[] uniq(int[]) - returns unique elements
  int   idx(int[], int item) - returns index of first intarray matching element
                               to item, or '0' if matching failed.
  int[] subarray(int[],int START [, int LEN]) - returns part of intarray
                               starting from element number START (from 1)
                               and length LEN.
OPERATIONS:

  int[] && int[]  - overlap - returns TRUE if arrays has at least one common elements.
  int[] @@  int[]  - contains - returns TRUE if left array contains right array
  int[] ~ int[]   - contained - returns TRUE if left array is contained in right array
  # int[]         - return the number of elements in array
  int[] + int     - push element to array ( add to end of array)
  int[] + int[]   - merge of arrays (right array added to the end of left one)
  int[] - int     - remove entries matched by right argument from array
  int[] - int[]   - remove left array from right
  int[] | int     - returns intarray - union of arguments
  int[] | int[]   - returns intarray as a union of two arrays
  int[] & int[]   - returns intersection of arrays

Oleg Bartunov
@
text
@d40 2
@


1.7
log
@    1. Implemented binary search in array

Oleg Bartunov
@
text
@d11 29
a39 1
for additional information.
d43 4
@


1.6
log
@Changes:

 1. gist__int_ops is now without lossy
 2. added sort entry in picksplit

Oleg Bartunov
@
text
@d15 2
@


1.5
log
@please apply attached patch to current CVS.

Changes:

 1. Added support for boolean queries (indexable operator @@@@, looks like
       a @@@@ '1|(2&3)'
 2. Some code cleanup and optimization

        Regards,
                Oleg
@
text
@d15 3
@


1.4
log
@Restructure pg_opclass, pg_amop, and pg_amproc per previous discussions in
pgsql-hackers.  pg_opclass now has a row for each opclass supported by each
index AM, not a row for each opclass name.  This allows pg_opclass to show
directly whether an AM supports an opclass, and furthermore makes it possible
to store additional information about an opclass that might be AM-dependent.
pg_opclass and pg_amop now store "lossy" and "haskeytype" information that we
previously expected the user to remember to provide in CREATE INDEX commands.
Lossiness is no longer an index-level property, but is associated with the
use of a particular operator in a particular index opclass.

Along the way, IndexSupportInitialize now uses the syscaches to retrieve
pg_amop and pg_amproc entries.  I find this reduces backend launch time by
about ten percent, at the cost of a couple more special cases in catcache.c's
IndexScanOK.

Initial work by Oleg Bartunov and Teodor Sigaev, further hacking by Tom Lane.

initdb forced.
@
text
@d15 4
@


1.3
log
@Repair intarray's problems with TOASTed input, avoid scribbling on
source data, improve split algorithm for intbig_ops.  Oleg Bartunov
with some kibitzing from Tom Lane.
@
text
@d2 6
a7 6
of PostgreSQL. It has built-in lossy compression - must be declared
in index creation - with (islossy). Current implementation provides index 
support for one-dimensional array of int4's - gist__int_ops, suitable for
small and medium size of arrays (used on default), and gist__intbig_ops for 
indexing large arrays (we use superimposed signature with length of 4096 
bits to represent sets). 
d38 1
a38 1
CREATE INDEX message_rdtree_idx on message using gist ( sections gist__int_ops) with ( islossy );
@


1.2
log
@Update contrib intarray to Jan 25 version.
@
text
@d13 6
@


1.1
log
@
commit Oleg and Teodor's RD-tree implementation ... this provides the
regression tests for the GiST changes ... this should be integrated into
the regular regression tests similar to Vadim's SPI contrib stuff ...
@
text
@d3 6
a8 2
in index creation - with (islossy). Current implementation has index support 
for one-dimensional array of int4's.
d32 1
a32 1
CREATE INDEX message_rdtree_idx on message using gist ( sections ) with ( islossy );
@
