F.16. hstore

F.16.1. hstoreの外部表現

入力および出力で使用されるhstore値のテキスト表現はカンマで区切られた、ゼロ以上のkey => valueという組み合わせを含みます。 以下に例を示します。

k => v
foo => bar, baz => whatever
"1-a" => "anything at all"

組み合わせの順序は重要ではありません（出力時に再現されないこともあります）。 組み合わせ間や=>記号の前後の空白文字は無視されます。 キーや値が空白文字、カンマ、=、>を含む場合は二重引用符でくくります。 キーや値に二重引用符やバックスラッシュを含めるには、バックスラッシュでエスケープしてください。

hstore内の各キーは一意です。 重複するキーを持つhstoreを宣言すると、hstoreには1つしか保存されません。 またどちらが残るかは保証されません。

SELECT 'a=>1,a=>2'::hstore;
  hstore
----------
 "a"=>"1"

値はSQLのNULLを取ることができます（キーは不可）。 以下に例を示します。

key => NULL

NULLキーワードは大文字小文字の区別をしません。 nullを普通の文字列"NULL"として扱うためには二重引用符でくくってください。

出力の場合、厳密に必要がない場合であっても、常にキーと値は二重引用符でくくられます。

F.16.2. hstoreの演算子と関数

hstoreモジュールで提供される演算子を表F-6に、関数を表F-7に示します。

a
b

1
2

 key | value
-----+-------
 a   | 1
 b   | 2

F.16.3. インデックス

hstoreは@>、?、?&および?|演算子向けのGiSTおよびGINインデックスをサポートします。 以下に例を示します。

CREATE INDEX hidx ON testhstore USING GIST (h);

CREATE INDEX hidx ON testhstore USING GIN (h);

hstoreはまた、=演算子向けにbtreeまたはhashインデックスをサポートします。 これによりhstoreの列をUNIQUEと宣言すること、また、GROUP BY、ORDER BY、DISTINCTの式で使用することができます。 hstore値のソート順序付けはあまり有用ではありません。 しかしこれらのインデックスは等価値の検索の際に有用になるかもしれません。 =比較用のインデックスを以下のように作成します。

CREATE INDEX hidx ON testhstore USING BTREE (h);

CREATE INDEX hidx ON testhstore USING HASH (h);

F.16.4. 例

キーを追加、または、既存のキーを新しい値で更新します。

UPDATE tab SET h = h || ('c' => '3');

キーを削除します。

UPDATE tab SET h = delete(h, 'k1');

recordをhstoreに変換します。

CREATE TABLE test (col1 integer, col2 text, col3 text);
INSERT INTO test VALUES (123, 'foo', 'bar');

SELECT hstore(t) FROM test AS t;
                   hstore                    
---------------------------------------------
 "col1"=>"123", "col2"=>"foo", "col3"=>"bar"
(1 row)

hstoreを事前に定義されたrecord型に変換します。

CREATE TABLE test (col1 integer, col2 text, col3 text);

SELECT * FROM populate_record(null::test,
                              '"col1"=>"456", "col2"=>"zzz"');
 col1 | col2 | col3 
------+------+------
  456 | zzz  | 
(1 row)

hstoreの値を使用して既存のレコードを変更します。

CREATE TABLE test (col1 integer, col2 text, col3 text);
INSERT INTO test VALUES (123, 'foo', 'bar');

SELECT (r).* FROM (SELECT t #= '"col3"=>"baz"' AS r FROM test t) s;
 col1 | col2 | col3 
------+------+------
  123 | foo  | baz
(1 row)

F.16.5. 統計情報

内在する自由度のため、hstore型は異なるキーを多く含むことができます。 有効なキーを検査することはアプリケーション側の作業です。 以下の例では、キー検査および統計情報の入手に関する複数の技法を示します。

簡単な例を示します。

SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');

テーブルを使用する例です。

SELECT (each(h)).key, (each(h)).value INTO stat FROM testhstore;

オンライン統計値です。

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
...................

F.16.6. 互換性

より古いバージョンから更新する場合、ダンプをリストアする前に常に本モジュールの新しいバージョンをデータベースにロードしてください。 さもないと多くの新しい機能が使用できなくなります。

PostgreSQL 9.0からhstoreの内部表現はこれまでから変更されました。 (ダンプ内で使用される)テキスト表現には変更がありませんので、ダンプ/リストアによる更新の妨げにはなりません。

バイナリによる更新の際、新しいコードで古い書式のデータを認識させることにより、上位互換が保持されます。 これには、新しいコードによりまだ変更されていないデータを処理する際に、性能の劣化を多少伴います。 以下のようにUPDATE文を実行することによりテーブル列内のすべての値を強制的に更新することができます。

UPDATE tablename SET hstorecol = hstorecol || '';

上を行う他の方法を以下に示します。

ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';

ALTER TABLEによる方法はテーブルに対して排他ロックを必要とします。 しかし、古いバージョンの行でテーブルが膨張することはありません。

F.16.7. 作者

Oleg Bartunov <oleg@sai.msu.su>, Moscow, Moscow University, Russia

Teodor Sigaev <teodor@sigaev.ru>, Moscow, Delta-Soft Ltd., Russia

追加の改良はAndrew Gierth <andrew@tao11.riddles.org.uk>,United Kingdomによりなされました。