head	1.6;
access;
symbols
	REL8_2_17:1.4.2.1
	REL8_2_16:1.4.2.1
	REL8_2_15:1.4.2.1
	REL8_2_14:1.4.2.1
	REL8_2_13:1.4
	REL8_2_12:1.4
	REL8_2_11:1.4
	REL8_2_10:1.4
	REL8_2_9:1.4
	REL8_2_8:1.4
	REL8_2_7:1.4
	REL8_2_6:1.4
	REL8_3_BETA2:1.5
	REL8_3_BETA1:1.5
	REL8_2_5:1.4
	REL8_2_4:1.4
	REL8_2_3:1.4
	REL8_2_2:1.4
	REL8_2_1:1.4
	REL8_2_STABLE:1.4.0.2
	REL8_2_0:1.4
	REL8_2_RC1:1.4
	REL8_2_BETA3:1.4
	REL8_2_BETA2:1.4
	REL8_2_BETA1:1.3;
locks; strict;
comment	@# @;


1.6
date	2007.11.10.23.30.45;	author momjian;	state dead;
branches;
next	1.5;

1.5
date	2007.03.14.14.21.52;	author teodor;	state Exp;
branches;
next	1.4;

1.4
date	2006.10.11.16.42.51;	author teodor;	state Exp;
branches
	1.4.2.1;
next	1.3;

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

1.2
date	2006.09.05.18.39.08;	author teodor;	state Exp;
branches;
next	1.1;

1.1
date	2006.09.05.18.00.57;	author teodor;	state Exp;
branches;
next	;

1.4.2.1
date	2009.03.15.22.05.44;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.6
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@Hstore - contrib module for storing (key,value) pairs

[Online version] (http://www.sai.msu.su/~megera/oddmuse/index.cgi?Hstore)

Motivation

Many attributes rarely searched, semistructural data, lazy DBA

Authors

    * Oleg Bartunov <oleg@@sai.msu.su>, Moscow, Moscow University, Russia
    * Teodor Sigaev <teodor@@sigaev.ru>, Moscow, Delta-Soft Ltd.,Russia

LEGAL NOTICES: This module is released under BSD license (as PostgreSQL
itself)

Operations

    * hstore -> text - get value , perl analogy $h{key} 

select 'a=>q, b=>g'->'a';
  ?
------
  q

    * hstore || hstore - concatenation, perl analogy %a=( %b, %c ); 

regression=# select 'a=>b'::hstore || 'c=>d'::hstore;
      ?column?      
--------------------
 "a"=>"b", "c"=>"d"
(1 row)

but, notice

regression=# select 'a=>b'::hstore || 'a=>d'::hstore;
 ?column? 
----------
 "a"=>"d"
(1 row)

    * text => text - creates hstore type from two text strings 

select 'a'=>'b';
  ?column?
----------
  "a"=>"b"

    * hstore @@> hstore - contains operation, check if left operand contains right. 

regression=# select 'a=>b, b=>1, c=>NULL'::hstore @@> 'a=>c';
 ?column? 
----------
 f
(1 row)

regression=# select 'a=>b, b=>1, c=>NULL'::hstore @@> 'b=>1';
 ?column? 
----------
 t
(1 row)

    * hstore <@@ hstore - contained operation, check if left operand is contained 
	 in right

(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!)

Functions

    * akeys(hstore) - returns all keys from hstore as array 

regression=# select akeys('a=>1,b=>2');
 akeys 
-------
 {a,b}

    * skeys(hstore) - returns all keys from hstore as strings 

regression=# select skeys('a=>1,b=>2');
 skeys 
-------
 a
 b

    * avals(hstore) - returns all values from hstore as array 

regression=# select avals('a=>1,b=>2');
 avals 
-------
 {1,2}

    * svals(hstore) - returns all values from hstore as strings 

regression=# select svals('a=>1,b=>2');
 svals 
-------
 1
 2

    * delete (hstore,text) - delete (key,value) from hstore if key matches 
	  argument. 

regression=# select delete('a=>1,b=>2','b');
  delete  
----------
 "a"=>"1"

    * each(hstore) return (key, value) pairs 

regression=# select * from each('a=>1,b=>2');
 key | value 
-----+-------
 a   | 1
 b   | 2

    * exist (hstore,text) 
	* hstore ? text 
	  - returns 'true if key is exists in hstore and false otherwise. 

regression=# select exist('a=>1','a'), 'a=>1' ? 'a';
 exist | ?column? 
-------+----------
 t     | t

    * defined (hstore,text) - returns true if key is exists in hstore and 
	  its value is not NULL. 

regression=# select defined('a=>NULL','a');
 defined 
---------
 f

Indices

Module provides index support for '@@>' and '?' operations.

create index hidx on testhstore using gist(h);
create index hidx on testhstore using gin(h);

Note

Use parenthesis in select below, because priority of 'is' is higher than that of '->'

select id from entrants where (info->'education_period') is not null;

Examples

    * add key 

update tt set h=h||'c=>3';

    * delete key 

update tt set h=delete(h,'k1');

    * Statistics

hstore type, because of its intrinsic liberality, could contain a lot of 
different keys. Checking for valid keys is the task of application. 
Examples below demonstrate several techniques how to check keys statistics.

          o simple example 

select * from each('aaa=>bq, b=>NULL, ""=>1 ');

          o using table 

select (each(h)).key, (each(h)).value into stat from testhstore ;

          o online stat 

select key, count(*) from (select (each(h)).key from testhstore) as stat group by key order by count desc, key;
    key    | count 
-----------+-------
 line      |   883
 query     |   207
 pos       |   203
 node      |   202
 space     |   197
 status    |   195
 public    |   194
 title     |   190
 org       |   189
...................
@


1.5
log
@Add GIN support for pg_trgm. From Guillaume Smet <guillaume.smet@@gmail.com>
with minor editorization by me.

Hstore improvements
* add operation hstore ? text - excat equivalent of exist()
* remove undocumented behaviour of contains operation with NULL value
* now 'key'::text=>NULL returns '"key"=>NULL' instead of NULL
* Add GIN support for contains and exist operations
* Add GiST support for exist operatiion
* improve regression tests
@
text
@@


1.4
log
@Rename function 'isexists' and 'isdefined' to
'exist' and 'defined' accordingly. Old names
are saved not mentioned in docs - for compatibility
with old applications.
Per discussion
http://archives.postgresql.org/pgsql-hackers/2006-10/msg00571.php
@
text
@d120 8
a127 7
    * exist (hstore,text) - returns 'true if key is exists in hstore and 
	false otherwise. 

regression=# select exist('a=>1','a');
 exist 
----------
 t
d139 1
a139 1
Module provides index support for '@@>' and '<@@' operations.
d142 1
@


1.4.2.1
log
@Fix contrib/hstore to throw an error for keys or values that don't fit in its
data structure, rather than silently truncating them.  Andrew Gierth
@
text
@a186 4

In the current implementation, neither the key nor the value
string can exceed 65535 bytes in length; an error will be thrown if this
limit is exceeded. These maximum lengths may change in future releases.
@


1.3
log
@Rename contrib contains/contained-by operators to @@> and <@@, per discussion.
@
text
@d120 1
a120 1
    * isexists (hstore,text) - returns 'true if key is exists in hstore and 
d123 2
a124 2
regression=# select isexists('a=>1','a');
 isexists 
d128 1
a128 1
    * isdefined (hstore,text) - returns true if key is exists in hstore and 
d131 3
a133 3
regression=# select isdefined('a=>NULL','a');
 isdefined 
-----------
@


1.2
log
@Fix markup and license.
@
text
@d49 1
a49 1
    * hstore @@ hstore - contains operation, check if left operand contains right. 
d51 1
a51 1
regression=# select 'a=>b, b=>1, c=>NULL'::hstore @@ 'a=>c';
d57 1
a57 1
regression=# select 'a=>b, b=>1, c=>NULL'::hstore @@ 'b=>1';
d63 1
a63 1
    * hstore ~ hstore - contained operation, check if left operand is contained 
d66 6
d138 1
a138 1
Module provides index support for '@@' and '~' operations.
@


1.1
log
@Add hstore contrib module.
Per discussion
http://archives.postgresql.org/pgsql-hackers/2006-08/msg01409.php
@
text
@d14 2
a15 3
License

Stable version, included into PostgreSQL distribution, released under BSD license. Development version, available from this site, released under the GNU General Public License, version 2 (June 1991).
d63 2
a64 1
    * hstore ~ hstore - contained operation, check if left operand is contained in right
d98 2
a99 1
    * delete (hstore,text) - delete (key,value) from hstore if key matches argument. 
d114 2
a115 1
    * isexists (hstore,text) - returns 'true if key is exists in hstore and false otherwise. 
d122 2
a123 1
    * isdefined (hstore,text) - returns true if key is exists in hstore and its value is not NULL. 
d154 3
a156 1
hstore type, because of its intrinsic liberality, could contain a lot of different keys. Checking for valid keys is the task of application. Examples below demonstrate several techniques how to check keys statistics.
d180 1
a180 1
...................@

