本モジュールはキー、値の組み合わせの集合を単一のPostgreSQL値に格納するためのhstoreデータ型を実装します。
あまり厳密に検査されない属性を多く持つ行や半構造化データなど、多くの状況で有用になる可能性があります。
キーと値は単純なテキスト文字列です。
このモジュールは「trusted」と見なされます。つまり、現在のデータベースに対してCREATE権限を持つ非スーパーユーザがインストールできます。
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」として扱うためには二重引用符でくくってください。
入力として使用される場合hstoreテキスト書式は、前もって必要な引用符付けやエスケープ処理を適用することに注意してください。
パラメータとしてhstoreリテラルを渡す場合、追加処理は必要ありません。
しかし、引用符付けしたリテラル定数として渡す場合には、単一引用符および(standard_conforming_strings設定パラメータに依存しますが)バックスラッシュ文字をすべて正しくエスケープしなければなりません。
文字列定数の取り扱いについては4.1.2.1を参照してください。
出力の場合、厳密に必要がない場合であっても、常にキーと値は二重引用符でくくられます。
hstoreの演算子と関数
hstoreモジュールで提供される演算子を表 F.7に、関数を表 F.8に示します。
表F.7 hstoreの演算子
演算子 説明 例 |
|---|
与えられたキーに対応する値を、存在しなければ
|
与えられたキーに対応する値を、存在しなければ
|
2つの
|
|
|
|
左辺は右辺を含むか。
|
左辺は右辺に含まれるか。
|
左辺からキーを削除します。
|
左辺からキー(複数)を削除します。
|
右辺の組み合わせに一致する組み合わせを左辺から削除します。
|
左辺(複合型でなければなりません)のフィールドを
|
|
|
表F.8 hstoreの関数
この演算子や関数に加えて、hstore型の値は添字を付けることができ、その場合、連想配列のように振る舞います。
text型の単一の添字のみが指定可能です。添字はキーとして解釈され、対応する値が取り出されたり、保存されたりします。
以下に例を示します。
CREATE TABLE mytable (h hstore);
INSERT INTO mytable VALUES ('a=>b, c=>d');
SELECT h['a'] FROM mytable;
h
---
b
(1 row)
UPDATE mytable SET h['c'] = 'new';
SELECT h FROM mytable;
h
----------------------
"a"=>"b", "c"=>"new"
(1 row)
添字がNULLの場合や、そのキーがhstore内に存在しない場合には、添字による取り出しはNULLを返します。
(ですので、添字による取り出しは->演算子とそれほど異なりません。)
添字がNULLの場合には、添字による更新は失敗します。そうでなければ、そのキーに対応する値を置き換え、キーがまだ存在していなければhstoreにエントリを追加します。
hstoreは@>、?、?&および?|演算子向けのGiSTおよびGINインデックスをサポートします。
以下に例を示します。
CREATE INDEX hidx ON testhstore USING GIST (h); CREATE INDEX hidx ON testhstore USING GIN (h);
gist_hstore_ops GiST演算子クラスはキー/値の集合をビットマップ署名として近似します。
オプションの整数パラメータsiglenは、署名の長さをバイト単位で決定します。
デフォルトの署名の長さは16バイトです。
署名の長さの有効な値は1から2024バイトまでです。
長い署名では、インデックスはより大きくなってしまいますが、(インデックスのより小さな部分とより少ないヒープページを走査することで)検索がより正確になります。
署名の長さが32バイトのインデックスを作成する例
CREATE INDEX hidx ON testhstore USING GIST (h gist_hstore_ops(siglen=32));
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);
キーを追加、または、既存のキーを新しい値で更新します。
UPDATE tab SET h['c'] = '3';
同じことを行なう他の方法を以下に示します。
UPDATE tab SET h = h || hstore('c', '3');
1つの操作で複数のキーを追加したり変更したりする場合には、連結する方が添字を使うよりも効率的です。
UPDATE tab SET h = h || hstore(array['q', 'w'], array['11', '12']);
キーを削除します。
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)
内在する自由度のため、hstore型は異なるキーを多く含むことができます。
有効なキーを検査することはアプリケーション側の作業です。
以下の例では、キー検査および統計情報の入手に関する複数の技法を示します。
簡単な例を示します。
SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
テーブルを使用する例です。
CREATE TABLE stat AS SELECT (each(h)).key, (each(h)).value 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
...................
PostgreSQL 9.0からhstoreの内部表現はこれまでから変更されました。
(ダンプ内で使用される)テキスト表現には変更がありませんので、ダンプ/リストアによる更新の妨げにはなりません。
バイナリによる更新の際、新しいコードで古い書式のデータを認識させることにより、上位互換が保持されます。
これには、新しいコードによりまだ変更されていないデータを処理する際に、性能の劣化を多少伴います。
以下のようにUPDATE文を実行することによりテーブル列内のすべての値を強制的に更新することができます。
UPDATE tablename SET hstorecol = hstorecol || '';
上を行う他の方法を以下に示します。
ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
ALTER TABLEによる方法はテーブルに対してACCESS EXCLUSIVEロックを必要とします。
しかし、古いバージョンの行でテーブルが膨張することはありません。
PL/Perl言語やPL/Python言語向けにhstore型の変換を実装した追加の拡張が入手可能です。
PL/Perl向けの拡張は、信頼されたPL/Perlに対してはhstore_plperlという名前で、信頼されないものに対してはhstore_plperluという名前です。
関数を作成するときにこの変換をインストールして指定していれば、hstoreの値はPerlのハッシュにマップされます。
PL/Python向けの拡張はhstore_plpythonu、hstore_plpython2u、hstore_plpython3uという名前です(PL/Pythonの命名規約については46.1を参照してください)。
この拡張を使うとhstoreの値はPythonの辞書型にマップされます。
変換の拡張はhstoreと同じスキーマにインストールすることを強く勧めます。
さもないと、変換の拡張のスキーマが悪意のあるユーザにより定義されたオブジェクトを含んでいた場合に、インストール時のセキュリティ問題になります。
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によりなされました。