Skip to content

Commit d73b7c5

Browse files
messere1messere1
committed
docs: add hstore integration guide
Assisted-by: OpenAI:gpt-5
1 parent daefd13 commit d73b7c5

6 files changed

Lines changed: 314 additions & 0 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.12.adoc[hstore]
5556
* 监控运维
5657
** xref:3.2.adoc[日常监控]
5758
** xref:3.3.adoc[日常维护]

‎CN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
2222
| 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化
2323
| 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控
2424
| 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发
25+
| 12 | xref:5.12.adoc[hstore] | 1.8 | 存储文本键值对，支持索引、包含查询、更新和 JSON 转换 | 稀疏属性、应用配置、标签和元数据
2526
|====
2627

2728
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

‎CN/modules/ROOT/pages/5.12.adoc‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= hstore
5+
6+
== 概述
7+
8+
`hstore` 是 IvorySQL 内置提供的扩展，用于在单个字段中保存一组文本键值对。它适合存储稀疏属性、应用配置、标签等不需要嵌套 JSON 结构的半结构化数据。
9+
10+
本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 hstore 1.8 完成验证。
11+
12+
== 兼容性
13+
14+
[cols="1,1,3"]
15+
|===
16+
|IvorySQL 模式 |状态 |已验证功能
17+
18+
|PostgreSQL
19+
|支持
20+
|扩展安装、键查询、包含判断、更新、JSON 转换和 GIN 索引
21+
22+
|Oracle 兼容模式
23+
|支持
24+
|切换 `ivorysql.compatible_mode` 后可继续使用相同的 hstore 数据类型、函数、操作符和索引
25+
|===
26+
27+
[NOTE]
28+
`hstore` 是 IvorySQL/PostgreSQL 扩展数据类型，不是 Oracle Database 原生数据类型。需要同时运行在 Oracle Database 上的应用应隔离 hstore 专用 SQL。
29+
30+
== 安装
31+
32+
IvorySQL 5.4 官方二进制包已包含 hstore。使用具有创建扩展权限的用户连接数据库并执行：
33+
34+
[source,sql]
35+
----
36+
CREATE EXTENSION hstore;
37+
38+
SELECT extversion
39+
FROM pg_extension
40+
WHERE extname = 'hstore';
41+
----
42+
43+
IvorySQL 5.4 中预期的扩展版本为 `1.8`。
44+
45+
对于源码安装的 IvorySQL，在创建扩展前从同一源码树编译并安装 hstore：
46+
47+
[source,shell]
48+
----
49+
cd /path/to/IvorySQL
50+
make -C contrib/hstore
51+
make -C contrib/hstore install
52+
----
53+
54+
== 使用
55+
56+
=== 保存和查询属性
57+
58+
[source,sql]
59+
----
60+
CREATE TABLE application_settings (
61+
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
62+
attributes hstore NOT NULL
63+
);
64+
65+
INSERT INTO application_settings(attributes)
66+
VALUES ('theme=>dark, region=>cn, notifications=>enabled');
67+
68+
-- 获取单个键的值。
69+
SELECT attributes -> 'theme' AS theme
70+
FROM application_settings;
71+
72+
-- 判断键是否存在。
73+
SELECT id
74+
FROM application_settings
75+
WHERE attributes ? 'region';
76+
77+
-- 判断是否包含给定键值对。
78+
SELECT id
79+
FROM application_settings
80+
WHERE attributes @> 'theme=>dark'::hstore;
81+
----
82+
83+
=== 更新和删除键
84+
85+
当右侧 hstore 包含同名键时，连接操作符会替换已有值。
86+
87+
[source,sql]
88+
----
89+
UPDATE application_settings
90+
SET attributes = attributes || 'theme=>light, locale=>zh_CN'::hstore
91+
WHERE id = 1;
92+
93+
UPDATE application_settings
94+
SET attributes = delete(attributes, 'notifications')
95+
WHERE id = 1;
96+
----
97+
98+
=== 创建 GIN 索引
99+
100+
GIN 索引可以加速 `?`、`?&`、`?|` 和 `@>` 等键存在及包含条件。
101+
102+
[source,sql]
103+
----
104+
CREATE INDEX application_settings_attributes_gin
105+
ON application_settings
106+
USING gin (attributes);
107+
108+
ANALYZE application_settings;
109+
----
110+
111+
=== 转换为 JSON
112+
113+
[source,sql]
114+
----
115+
SELECT hstore_to_json(attributes)
116+
FROM application_settings;
117+
----
118+
119+
`hstore_to_json()` 会将 SQL NULL 保留为 JSON `null`，其他 hstore 值均转换为 JSON 字符串。
120+
121+
== Oracle 兼容模式
122+
123+
无需重复安装扩展。扩展在数据库范围内生效，切换会话兼容模式后仍然可用：
124+
125+
[source,sql]
126+
----
127+
SET ivorysql.compatible_mode = oracle;
128+
129+
SELECT 'a=>1, b=>2'::hstore -> 'b' FROM dual;
130+
SELECT exist('a=>1, b=>2'::hstore, 'a') FROM dual;
131+
----
132+
133+
在 IvorySQL 5.4 上，两条语句均成功执行，分别返回 `2` 和 `true`。
134+
135+
== 验证
136+
137+
可以在 IvorySQL 源码树中对已安装实例运行内置回归测试：
138+
139+
[source,shell]
140+
----
141+
cd /path/to/IvorySQL/contrib/hstore
142+
make installcheck
143+
make oracle-installcheck
144+
----
145+
146+
IvorySQL 5.4 验证中，两个 PostgreSQL 测试（`hstore`、`hstore_utf8`）以及两个 Oracle 兼容测试（`ivy_hstore`、`hstore_utf8`）均通过。
147+
148+
== 限制与建议
149+
150+
* 键和非 NULL 值均为文本；hstore 不支持嵌套对象或数组。
151+
* 一个 hstore 值中的键必须唯一；输入包含重复键时只会保留一个值，应用不应依赖具体保留哪一个。
152+
* 如果数据需要嵌套结构、JSON 数值/布尔类型或 JSONPath 查询，应使用 `jsonb`。
153+
* 安装扩展需要相应数据库权限；应用角色只需要其所用表和函数的权限。
154+
155+
完整的操作符和函数说明请参阅 https://www.postgresql.org/docs/18/hstore.html[PostgreSQL hstore 文档]。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.12.adoc[hstore]
5556
* Monitor and O&M
5657
** xref:3.2.adoc[Monitoring]
5758
** xref:3.3.adoc[Maintenance]

‎EN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
2323
|*9*| xref:5.9.adoc[pgrouting] | 3.8.0 | Provides routing computation for geospatial data, supporting multiple algorithms and data formats | Geospatial analysis, route planning, logistics optimization
2424
|*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor
2525
|*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development
26+
|*12*| xref:5.12.adoc[hstore] | 1.8 | Stores text key/value pairs with indexing, containment queries, updates, and JSON conversion | Sparse attributes, application settings, labels, and metadata
2627
|====
2728

2829
These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system.

‎EN/modules/ROOT/pages/5.12.adoc‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= hstore
5+
6+
== Overview
7+
8+
`hstore` is an extension included with IvorySQL that stores sets of text key/value pairs in a single column. It is useful for sparse attributes, application settings, labels, and other semi-structured data that does not require nested JSON documents.
9+
10+
This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and hstore 1.8 on Ubuntu 22.04 x86_64.
11+
12+
== Compatibility
13+
14+
[cols="1,1,3"]
15+
|===
16+
|IvorySQL mode |Status |Verified operations
17+
18+
|PostgreSQL
19+
|Supported
20+
|Extension installation, key lookup, containment, update, JSON conversion, and GIN indexing
21+
22+
|Oracle compatible
23+
|Supported
24+
|The same hstore data type, functions, operators, and indexes are available after switching `ivorysql.compatible_mode`
25+
|===
26+
27+
[NOTE]
28+
`hstore` is an IvorySQL/PostgreSQL extension data type, not an Oracle Database native data type. Applications that must also run on Oracle Database should isolate hstore-specific SQL.
29+
30+
== Installation
31+
32+
The official IvorySQL 5.4 binary package already contains hstore. Connect as a user allowed to create extensions and run:
33+
34+
[source,sql]
35+
----
36+
CREATE EXTENSION hstore;
37+
38+
SELECT extversion
39+
FROM pg_extension
40+
WHERE extname = 'hstore';
41+
----
42+
43+
The expected extension version in IvorySQL 5.4 is `1.8`.
44+
45+
For an IvorySQL installation built from source, install hstore from the same source tree before creating the extension:
46+
47+
[source,shell]
48+
----
49+
cd /path/to/IvorySQL
50+
make -C contrib/hstore
51+
make -C contrib/hstore install
52+
----
53+
54+
== Usage
55+
56+
=== Store and query attributes
57+
58+
[source,sql]
59+
----
60+
CREATE TABLE application_settings (
61+
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
62+
attributes hstore NOT NULL
63+
);
64+
65+
INSERT INTO application_settings(attributes)
66+
VALUES ('theme=>dark, region=>cn, notifications=>enabled');
67+
68+
-- Fetch one value.
69+
SELECT attributes -> 'theme' AS theme
70+
FROM application_settings;
71+
72+
-- Test whether a key exists.
73+
SELECT id
74+
FROM application_settings
75+
WHERE attributes ? 'region';
76+
77+
-- Test whether all supplied pairs are present.
78+
SELECT id
79+
FROM application_settings
80+
WHERE attributes @> 'theme=>dark'::hstore;
81+
----
82+
83+
=== Update and remove keys
84+
85+
The concatenation operator replaces an existing value when the right-hand hstore contains the same key.
86+
87+
[source,sql]
88+
----
89+
UPDATE application_settings
90+
SET attributes = attributes || 'theme=>light, locale=>zh_CN'::hstore
91+
WHERE id = 1;
92+
93+
UPDATE application_settings
94+
SET attributes = delete(attributes, 'notifications')
95+
WHERE id = 1;
96+
----
97+
98+
=== Add a GIN index
99+
100+
GIN indexes accelerate key-existence and containment predicates such as `?`, `?&`, `?|`, and `@>`.
101+
102+
[source,sql]
103+
----
104+
CREATE INDEX application_settings_attributes_gin
105+
ON application_settings
106+
USING gin (attributes);
107+
108+
ANALYZE application_settings;
109+
----
110+
111+
=== Convert to JSON
112+
113+
[source,sql]
114+
----
115+
SELECT hstore_to_json(attributes)
116+
FROM application_settings;
117+
----
118+
119+
`hstore_to_json()` preserves SQL NULL values as JSON `null`, while all non-NULL hstore values are represented as JSON strings.
120+
121+
== Oracle-compatible mode
122+
123+
No separate extension installation is required. The extension is database-wide and remains available when the session changes mode:
124+
125+
[source,sql]
126+
----
127+
SET ivorysql.compatible_mode = oracle;
128+
129+
SELECT 'a=>1, b=>2'::hstore -> 'b' FROM dual;
130+
SELECT exist('a=>1, b=>2'::hstore, 'a') FROM dual;
131+
----
132+
133+
Both statements return successfully (`2` and `true`, respectively) on IvorySQL 5.4.
134+
135+
== Verification
136+
137+
IvorySQL's bundled regression suites can be run from the source tree against an installed server:
138+
139+
[source,shell]
140+
----
141+
cd /path/to/IvorySQL/contrib/hstore
142+
make installcheck
143+
make oracle-installcheck
144+
----
145+
146+
The IvorySQL 5.4 verification completed both PostgreSQL tests (`hstore`, `hstore_utf8`) and both Oracle-compatible tests (`ivy_hstore`, `hstore_utf8`) successfully.
147+
148+
== Limitations and guidance
149+
150+
* Keys and non-NULL values are text; hstore does not provide nested objects or arrays.
151+
* Each key is unique within an hstore value. If input contains duplicate keys, only one value is retained and applications must not rely on which duplicate is kept.
152+
* Use `jsonb` instead when the data needs nesting, JSON numeric/Boolean types, or JSONPath queries.
153+
* Extension installation requires appropriate database privileges. Application roles only need privileges on the tables and functions they use.
154+
155+
For the complete operator and function reference, see the https://www.postgresql.org/docs/18/hstore.html[PostgreSQL hstore documentation].

0 commit comments

Comments
 (0)