他のバージョンの文書 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

F.16. hstore

本モジュールはキー、値の組み合わせの集合を単一のPostgreSQL値に格納するためのhstoreデータ型を実装します。 あまり厳密に検査されない属性を多く持つ行や半構造化データなど、多くの状況で有用になる可能性があります。 キーと値は単純なテキスト文字列です。

このモジュールはtrustedと見なされます。つまり、現在のデータベースに対してCREATE権限を持つ非スーパーユーザがインストールできます。

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として扱うためには二重引用符でくくってください。

注記

入力として使用される場合hstoreテキスト書式は、前もって必要な引用符付けやエスケープ処理を適用することに注意してください。 パラメータとしてhstoreリテラルを渡す場合、追加処理は必要ありません。 しかし、引用符付けしたリテラル定数として渡す場合には、単一引用符および(standard_conforming_strings設定パラメータに依存しますが)バックスラッシュ文字をすべて正しくエスケープしなければなりません。 文字列定数の取り扱いについては4.1.2.1を参照してください。

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

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

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

表F.7 hstoreの演算子

演算子

説明

hstore -> texttext

与えられたキーに対応する値を、存在しなければNULLを返します。

'a=>x, b=>y'::hstore -> 'a'x

hstore -> text[]text[]

与えられたキーに対応する値を、存在しなければNULLを返します。

'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']{"z","x"}

hstore || hstorehstore

2つのhstoreを連結します。

'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore"a"=>"b", "c"=>"x", "d"=>"q"

hstore ? textboolean

hstoreがキーを含むか。

'a=>1'::hstore ? 'a't

hstore ?& text[]boolean

hstoreが指定したキーをすべて含むか。

'a=>1,b=>2'::hstore ?& ARRAY['a','b']t

hstore ?| text[]boolean

hstoreが指定したキーのいずれかを含むか。

'a=>1,b=>2'::hstore ?| ARRAY['b','c']t

hstore @> hstoreboolean

左辺は右辺を含むか。

'a=>b, b=>1, c=>NULL'::hstore @> 'b=>1't

hstore <@ hstoreboolean

左辺は右辺に含まれるか。

'a=>c'::hstore <@ 'a=>b, b=>1, c=>NULL'f

hstore - texthstore

左辺からキーを削除します。

'a=>1, b=>2, c=>3'::hstore - 'b'::text"a"=>"1", "c"=>"3"

hstore - text[]hstore

左辺からキー(複数)を削除します。

'a=>1, b=>2, c=>3'::hstore - ARRAY['a','b']"c"=>"3"

hstore - hstorehstore

右辺の組み合わせに一致する組み合わせを左辺から削除します。

'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore"a"=>"1", "c"=>"3"

anyelement #= hstoreanyelement

左辺(複合型でなければなりません)のフィールドをhstoreの対応する値で置換します。

ROW(1,3) #= 'f1=>11'::hstore(11,3)

%% hstoretext[]

hstoreをキーと値が交互に並んだ配列に変換します。

%% 'a=>foo, b=>bar'::hstore{a,foo,b,bar}

%# hstoretext[]

hstoreをキーと値の2次元配列に変換します。

%# 'a=>foo, b=>bar'::hstore{{a,foo},{b,bar}}


注記

PostgreSQL 8.2より前では、包含演算子@><@はそれぞれ@~と呼ばれていました。 これらの名前はまだ利用できますが、廃止予定であり、最終的にはなくなります。 古い名前がコアの幾何データ型が従う規約と反対であることに注意してください。

表F.8 hstoreの関数

関数

説明

hstore ( record ) → hstore

レコードまたは行からhstoreを生成します。

hstore(ROW(1,2))"f1"=>"1", "f2"=>"2"

hstore ( text[] ) → hstore

配列からhstoreを生成します。配列はキー、値の配列でも2次元の配列でも構いません。

hstore(ARRAY['a','1','b','2'])"a"=>"1", "b"=>"2"

hstore(ARRAY[['c','3'],['d','4']])"c"=>"3", "d"=>"4"

hstore ( text[], text[] ) → hstore

キー、値で分けた配列からhstoreを作成します。

hstore(ARRAY['a','b'], ARRAY['1','2'])"a"=>"1", "b"=>"2"

hstore ( text, text ) → hstore

hstore型の単一項目を作成します。

hstore('a', 'b')"a"=>"b"

akeys ( hstore ) → text[]

hstoreのキーを配列として取り出します。

akeys('a=>1,b=>2'){a,b}

skeys ( hstore ) → setof text

hstoreのキーを集合として取り出します。

skeys('a=>1,b=>2')

a
b

avals ( hstore ) → text[]

hstoreの値を配列として取り出します。

avals('a=>1,b=>2'){1,2}

svals ( hstore ) → setof text

hstoreの値を集合として取り出します。

svals('a=>1,b=>2')

1
2

hstore_to_array ( hstore ) → text[]

hstoreのキーと値を、キーと値が交互に並んだ配列として取り出します。

hstore_to_array('a=>1,b=>2'){a,1,b,2}

hstore_to_matrix ( hstore ) → text[]

hstoreのキーと値を、2次元の配列として取り出します。

hstore_to_matrix('a=>1,b=>2'){{a,1},{b,2}}

hstore_to_json ( hstore ) → json

非nullの値をすべてJSON文字列に変換しながら、hstorejson値に変換します。

この関数はhstore値がjsonにキャストされるときに暗黙的に使用されます。

hstore_to_json('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4'){"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}

hstore_to_jsonb ( hstore ) → jsonb

非nullの値をすべてJSON文字列に変換しながら、hstorejsonb値に変換します。

この関数はhstore値がjsonbにキャストされるときに暗黙的に使用されます。

hstore_to_jsonb('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4'){"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}

hstore_to_json_loose ( hstore ) → json

hstorejson値に変換します。ですが、数値およびブール値を識別しようとするため、その2つはJSON中では引用符が付きません。

hstore_to_json_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4'){"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}

hstore_to_jsonb_loose ( hstore ) → jsonb

hstorejsonb値に変換します。ですが、数値およびブール値を識別しようとするため、その2つはJSON中では引用符が付きません。

hstore_to_jsonb_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4'){"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}

slice ( hstore, text[] ) → hstore

指定されたキーだけを含むhstoreの部分集合を取り出します。

slice('a=>1,b=>2,c=>3'::hstore, ARRAY['b','c','x'])"b"=>"2", "c"=>"3"

each ( hstore ) → setof record ( key text, value text )

hstoreのキーと値をレコードの集合として取り出します。

select * from each('a=>1,b=>2')

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

exist ( hstore, text ) → boolean

hstoreがキーを含むか。

exist('a=>1', 'a')t

defined ( hstore, text ) → boolean

hstoreがキーに対して非NULLの値を含むか。

defined('a=>NULL', 'a')f

delete ( hstore, text ) → hstore

キーに一致する組み合わせを削除します。

delete('a=>1,b=>2', 'b')"a"=>"1"

delete ( hstore, text[] ) → hstore

キー(複数)に一致する組み合わせを削除します。

delete('a=>1,b=>2,c=>3', ARRAY['a','b'])"c"=>"3"

delete ( hstore, hstore ) → hstore

第2引数内の組み合わせと一致する組み合わせを削除します。

delete('a=>1,b=>2', 'a=>4,b=>2'::hstore)"a"=>"1"

populate_record ( anyelement, hstore ) → anyelement

左辺(複合型でなければなりません)のフィールドをhstoreの対応する値で置換します。

populate_record(ROW(1,2), 'f1=>42'::hstore)(42,2)


F.16.3. インデックス

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 BYORDER BYDISTINCTの式で使用することができます。 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 || hstore('c', '3');

キーを削除します。

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

recordhstoreに変換します。

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

PL/Perl言語やPL/Python言語向けにhstore型の変換を実装した追加の拡張が入手可能です。 PL/Perl向けの拡張は、信頼されたPL/Perlに対してはhstore_plperlという名前で、信頼されないものに対してはhstore_plperluという名前です。 関数を作成するときにこの変換をインストールして指定していれば、hstoreの値はPerlのハッシュにマップされます。 PL/Python向けの拡張はhstore_plpythonuhstore_plpython2uhstore_plpython3uという名前です(PL/Pythonの命名規約については45.1を参照してください)。 この拡張を使うとhstoreの値はPythonの辞書型にマップされます。

注意

変換の拡張はhstoreと同じスキーマにインストールすることを強く勧めます。 さもないと、変換の拡張のスキーマが悪意のあるユーザにより定義されたオブジェクトを含んでいた場合に、インストール時のセキュリティ問題になります。

F.16.8. 作者

Oleg Bartunov , Moscow, Moscow University, Russia

Teodor Sigaev , Moscow, Delta-Soft Ltd., Russia

追加の改良はAndrew Gierth ,United Kingdomによりなされました。