2026年2月26日： PostgreSQL 18.3、17.9、16.13、15.17 和 14.22 发布！
受支持版本： 当前版本 (18) / 17 / 16 / 15 / 14
开发版本： devel
F.15. hstore
Prev  Up Appendix F. 额外提供的模块与扩展 Home  Next

F.15. hstore #

F.15.1. hstore 外部表示
F.15.2. hstore 操作符和函数
F.15.3. 索引
F.15.4. 示例
F.15.5. 统计信息
F.15.6. 兼容性
F.15.7. 转换
F.15.8. 作者

此模块实现了hstore数据类型，用于在单个 PostgreSQL值中存储一组键/值对。这在多种场景中 都很有用，例如属性很多但很少查看的行，或者半结构化数据。键和值都只是文 本字符串。

此模块被视为“受信任的”，也就是说，它可以由在当前数据库上具 有CREATE权限的非超级用户安装。

F.15.1. hstore 外部表示 #

用于输入和输出的hstore文本表示包含零个或多个以逗号分隔的 key => value 对。一些示例：

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

键/值对的顺序并不重要（而且在输出时可能不会按原样重现）。键/值对之间或 => 号周围的空白会被忽略。包含空白、逗号、 = 或 > 的键和值必须用双引号括起来。 要在键或值中包含双引号或反斜线，请用反斜线转义。

每个hstore中的键都是唯一的。如果声明的hstore 带有重复键，则在该hstore中只会存储其中一个，而且无法保证保 留的是哪一个：

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

值（但键不能）可以是 SQL NULL。例如：

key => NULL

NULL关键字不区分大小写。若要将NULL 视为普通字符串“NULL”，请用双引号括起来。

Note

请注意，当hstore文本格式用于输入时，它会在任何必需的加引号 或转义之前应用。如果通过参数传递一个 hstore字面量，则不需要额外处理。但如果将其作为带引号的字面 量常量传递，那么其中的单引号字符以及（取决于 standard_conforming_strings配置参数的设置）反斜线字 符都需要被正确转义。关于字符串常量的处理，见 Section 4.1.2.1。

在输出时，即使严格来说并非必需，键和值也总是带有双引号。

F.15.2. hstore 操作符和函数 #

hstore模块提供的操作符见Table F.6， 函数见Table F.7。

Table F.6. hstore 操作符

操作符

描述

示例

hstore -> text → text

返回与给定键关联的值，如果该键不存在则返回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 || hstore → hstore

串接两个hstore。

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

hstore ? text → boolean

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 @> hstore → boolean

左操作数是否包含右操作数？

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

hstore <@ hstore → boolean

左操作数是否被右操作数包含？

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

hstore - text → hstore

从左操作数中删除该键。

'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 - hstore → hstore

从左操作数中删除与右操作数中的键/值对相匹配的键/值对。

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

anyelement #= hstore → anyelement

用hstore中匹配的值替换左操作数（必须为复合类型）中的字段。

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

%% hstore → text[]

将hstore转换为键和值交替排列的数组。

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

%# hstore → text[]

将hstore转换为二维键/值数组。

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

Table F.7. hstore 函数

函数

描述

示例

hstore ( record ) → hstore

从记录或行构造一个hstore。

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

hstore ( text[] ) → hstore

从数组构造一个hstore，该数组既可以是键/值数组，也可以是 二维数组。

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的键和值提取为二维数组。

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

hstore_to_json ( hstore ) → json

将hstore转换为json值，并将所有非空值转换为 JSON 字符串。

当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

将hstore转换为jsonb值，并将所有非空值转换为 JSON 字符串。

当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

将hstore转换为json值，但会尝试区分数值和布尔 值，以便它们在 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

将hstore转换为jsonb值，但会尝试区分数值和布尔 值，以便它们在 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

删除与第二个参数中的键/值对匹配的键/值对。

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)

除了这些操作符和函数之外，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中添加一个条目。

F.15.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 BY、 ORDER BY或DISTINCT表达式。 hstore值的排序顺序本身并没有特别实用的意义，但这些索引可能适合 用于等值查找。可按如下方式为=比较创建索引：

CREATE INDEX hidx ON testhstore USING BTREE (h);

CREATE INDEX hidx ON testhstore USING HASH (h);

F.15.4. 示例 #

添加一个键，或者用新值更新现有键：

UPDATE tab SET h['c'] = '3';

完成同样操作的另一种方式是：

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

如果要在一次操作中添加或更改多个键，那么串接方式比使用下标更高效：

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)

F.15.5. 统计信息 #

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

F.15.6. 兼容性 #

自 PostgreSQL 9.0 起，hstore使用了与更早版本不同的内部表 示。这不会妨碍转储/恢复升级，因为文本表示（即转储中使用的表示）没有改变。

在进行二进制升级时，通过让新代码识别旧格式数据，维持了向上兼容性。这会在 处理尚未被新代码修改过的数据时带来轻微的性能损失。可以通过执行如下 UPDATE语句，强制升级表列中的所有值：

UPDATE tablename SET hstorecol = hstorecol || '';

另一种方式是：

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

使用ALTER TABLE方法需要对表加 ACCESS EXCLUSIVE锁，但不会因旧行版本而导致表膨胀。

F.15.7. 转换 #

另外还有一些扩展可用，它们为 PL/Perl 和 PL/Python 语言中的 hstore类型实现了转换。PL/Perl 的扩展分别名为 hstore_plperl和hstore_plperlu， 对应受信任的和不受信任的 PL/Perl。如果安装这些转换并在创建函数时指定它 们，则hstore值会映射为 Perl 哈希。PL/Python 的扩展分别名为hstore_plpythonu、hstore_plpython2u和hstore_plpython3u（关于 PL/Python 的命名约定请见Section 44.1）。如果使用它们，hstore值会映射为 Python 字典。

F.15.8. 作者 #

Oleg Bartunov ，俄罗斯莫斯科，莫斯科大学

Teodor Sigaev ，俄罗斯莫斯科，Delta-Soft Ltd.

Andrew Gierth ，英国，对本模块作 了额外增强

Prev  Up  Next
F.14. fuzzystrmatch — 确定字符串的相似性和距离  Home  F.16. intagg — 整数聚合器和枚举器

提交更正

如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明，请使用此表单来报告文档问题。