README.hstore

   1 Hstore - contrib module for storing (key,value) pairs
   2
   3 [Online version] (http://www.sai.msu.su/~megera/oddmuse/index.cgi?Hstore)
   4
   5 Motivation
   6
   7 Many attributes rarely searched, semistructural data, lazy DBA
   8
   9 Authors
  10
  11     * Oleg Bartunov <oleg@sai.msu.su>, Moscow, Moscow University, Russia
  12     * Teodor Sigaev <teodor@sigaev.ru>, Moscow, Delta-Soft Ltd.,Russia
  13
  14 License
  15
  16 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).
  17
  18 Operations
  19
  20     * hstore -> text - get value , perl analogy $h{key}
  21
  22 select 'a=>q, b=>g'->'a';
  23   ?
  24 ------
  25   q
  26
  27     * hstore || hstore - concatenation, perl analogy %a=( %b, %c );
  28
  29 regression=# select 'a=>b'::hstore || 'c=>d'::hstore;
  30       ?column?
  31 --------------------
  32  "a"=>"b", "c"=>"d"
  33 (1 row)
  34
  35 but, notice
  36
  37 regression=# select 'a=>b'::hstore || 'a=>d'::hstore;
  38  ?column?
  39 ----------
  40  "a"=>"d"
  41 (1 row)
  42
  43     * text => text - creates hstore type from two text strings
  44
  45 select 'a'=>'b';
  46   ?column?
  47 ----------
  48   "a"=>"b"
  49
  50     * hstore @ hstore - contains operation, check if left operand contains right.
  51
  52 regression=# select 'a=>b, b=>1, c=>NULL'::hstore @ 'a=>c';
  53  ?column?
  54 ----------
  55  f
  56 (1 row)
  57
  58 regression=# select 'a=>b, b=>1, c=>NULL'::hstore @ 'b=>1';
  59  ?column?
  60 ----------
  61  t
  62 (1 row)
  63
  64     * hstore ~ hstore - contained operation, check if left operand is contained in right
  65
  66 Functions
  67
  68     * akeys(hstore) - returns all keys from hstore as array
  69
  70 regression=# select akeys('a=>1,b=>2');
  71  akeys
  72 -------
  73  {a,b}
  74
  75     * skeys(hstore) - returns all keys from hstore as strings
  76
  77 regression=# select skeys('a=>1,b=>2');
  78  skeys
  79 -------
  80  a
  81  b
  82
  83     * avals(hstore) - returns all values from hstore as array
  84
  85 regression=# select avals('a=>1,b=>2');
  86  avals
  87 -------
  88  {1,2}
  89
  90     * svals(hstore) - returns all values from hstore as strings
  91
  92 regression=# select svals('a=>1,b=>2');
  93  svals
  94 -------
  95  1
  96  2
  97
  98     * delete (hstore,text) - delete (key,value) from hstore if key matches argument.
  99
 100 regression=# select delete('a=>1,b=>2','b');
 101   delete
 102 ----------
 103  "a"=>"1"
 104
 105     * each(hstore) return (key, value) pairs
 106
 107 regression=# select * from each('a=>1,b=>2');
 108  key | value
 109 -----+-------
 110  a   | 1
 111  b   | 2
 112
 113     * isexists (hstore,text) - returns 'true if key is exists in hstore and false otherwise.
 114
 115 regression=# select isexists('a=>1','a');
 116  isexists
 117 ----------
 118  t
 119
 120     * isdefined (hstore,text) - returns true if key is exists in hstore and its value is not NULL.
 121
 122 regression=# select isdefined('a=>NULL','a');
 123  isdefined
 124 -----------
 125  f
 126
 127 Indices
 128
 129 Module provides index support for '@' and '~' operations.
 130
 131 create index hidx on testhstore using gist(h);
 132
 133 Note
 134
 135 Use parenthesis in select below, because priority of 'is' is higher than that of '->'
 136
 137 select id from entrants where (info->'education_period') is not null;
 138
 139 Examples
 140
 141     * add key
 142
 143 update tt set h=h||'c=>3';
 144
 145     * delete key
 146
 147 update tt set h=delete(h,'k1');
 148
 149     * Statistics
 150
 151 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.
 152
 153           o simple example
 154
 155 select * from each('aaa=>bq, b=>NULL, ""=>1 ');
 156
 157           o using table
 158
 159 select (each(h)).key, (each(h)).value into stat from testhstore ;
 160
 161           o online stat
 162
 163 select key, count(*) from (select (each(h)).key from testhstore) as stat group by key order by count desc, key;
 164     key    | count
 165 -----------+-------
 166  line      |   883
 167  query     |   207
 168  pos       |   203
 169  node      |   202
 170  space     |   197
 171  status    |   195
 172  public    |   194
 173  title     |   190
 174  org       |   189
 175 ...................