add .gitignore
[hstore.git] / 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 ...................