diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index f1a1baab..12d46e53 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -52,6 +52,7 @@ *** xref:5.9.adoc[pgrouting] *** xref:5.10.adoc[system_stats] *** xref:5.11.adoc[pgtt] +*** xref:5.12.adoc[hstore] * 监控运维 ** xref:3.2.adoc[日常监控] ** xref:3.3.adoc[日常维护] diff --git a/CN/modules/ROOT/pages/5.0.adoc b/CN/modules/ROOT/pages/5.0.adoc index d9a776d9..aa80e908 100644 --- a/CN/modules/ROOT/pages/5.0.adoc +++ b/CN/modules/ROOT/pages/5.0.adoc @@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库 | 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化 | 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控 | 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发 +| 12 | xref:5.12.adoc[hstore] | 1.8 | 存储文本键值对，支持索引、包含查询、更新和 JSON 转换 | 稀疏属性、应用配置、标签和元数据 |==== 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。 diff --git a/CN/modules/ROOT/pages/5.12.adoc b/CN/modules/ROOT/pages/5.12.adoc new file mode 100644 index 00000000..1d01698b --- /dev/null +++ b/CN/modules/ROOT/pages/5.12.adoc @@ -0,0 +1,155 @@ +:sectnums: +:sectnumlevels: 5 + += hstore + +== 概述 + +`hstore` 是 IvorySQL 内置提供的扩展，用于在单个字段中保存一组文本键值对。它适合存储稀疏属性、应用配置、标签等不需要嵌套 JSON 结构的半结构化数据。 + +本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 hstore 1.8 完成验证。 + +== 兼容性 + +[cols="1,1,3"] +|=== +|IvorySQL 模式 |状态 |已验证功能 + +|PostgreSQL +|支持 +|扩展安装、键查询、包含判断、更新、JSON 转换和 GIN 索引 + +|Oracle 兼容模式 +|支持 +|切换 `ivorysql.compatible_mode` 后可继续使用相同的 hstore 数据类型、函数、操作符和索引 +|=== + +[NOTE] +`hstore` 是 IvorySQL/PostgreSQL 扩展数据类型，不是 Oracle Database 原生数据类型。需要同时运行在 Oracle Database 上的应用应隔离 hstore 专用 SQL。 + +== 安装 + +IvorySQL 5.4 官方二进制包已包含 hstore。使用具有创建扩展权限的用户连接数据库并执行： + +[source,sql] +---- +CREATE EXTENSION hstore; + +SELECT extversion +FROM pg_extension +WHERE extname = 'hstore'; +---- + +IvorySQL 5.4 中预期的扩展版本为 `1.8`。 + +对于源码安装的 IvorySQL，在创建扩展前从同一源码树编译并安装 hstore： + +[source,shell] +---- +cd /path/to/IvorySQL +make -C contrib/hstore +make -C contrib/hstore install +---- + +== 使用 + +=== 保存和查询属性 + +[source,sql] +---- +CREATE TABLE application_settings ( + id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + attributes hstore NOT NULL +); + +INSERT INTO application_settings(attributes) +VALUES ('theme=>dark, region=>cn, notifications=>enabled'); + +-- 获取单个键的值。 +SELECT attributes -> 'theme' AS theme +FROM application_settings; + +-- 判断键是否存在。 +SELECT id +FROM application_settings +WHERE attributes ? 'region'; + +-- 判断是否包含给定键值对。 +SELECT id +FROM application_settings +WHERE attributes @> 'theme=>dark'::hstore; +---- + +=== 更新和删除键 + +当右侧 hstore 包含同名键时，连接操作符会替换已有值。 + +[source,sql] +---- +UPDATE application_settings +SET attributes = attributes || 'theme=>light, locale=>zh_CN'::hstore +WHERE id = 1; + +UPDATE application_settings +SET attributes = delete(attributes, 'notifications') +WHERE id = 1; +---- + +=== 创建 GIN 索引 + +GIN 索引可以加速 `?`、`?&`、`?|` 和 `@>` 等键存在及包含条件。 + +[source,sql] +---- +CREATE INDEX application_settings_attributes_gin +ON application_settings +USING gin (attributes); + +ANALYZE application_settings; +---- + +=== 转换为 JSON + +[source,sql] +---- +SELECT hstore_to_json(attributes) +FROM application_settings; +---- + +`hstore_to_json()` 会将 SQL NULL 保留为 JSON `null`，其他 hstore 值均转换为 JSON 字符串。 + +== Oracle 兼容模式 + +无需重复安装扩展。扩展在数据库范围内生效，切换会话兼容模式后仍然可用： + +[source,sql] +---- +SET ivorysql.compatible_mode = oracle; + +SELECT 'a=>1, b=>2'::hstore -> 'b' FROM dual; +SELECT exist('a=>1, b=>2'::hstore, 'a') FROM dual; +---- + +在 IvorySQL 5.4 上，两条语句均成功执行，分别返回 `2` 和 `true`。 + +== 验证 + +可以在 IvorySQL 源码树中对已安装实例运行内置回归测试： + +[source,shell] +---- +cd /path/to/IvorySQL/contrib/hstore +make installcheck +make oracle-installcheck +---- + +IvorySQL 5.4 验证中，两个 PostgreSQL 测试（`hstore`、`hstore_utf8`）以及两个 Oracle 兼容测试（`ivy_hstore`、`hstore_utf8`）均通过。 + +== 限制与建议 + +* 键和非 NULL 值均为文本；hstore 不支持嵌套对象或数组。 +* 一个 hstore 值中的键必须唯一；输入包含重复键时只会保留一个值，应用不应依赖具体保留哪一个。 +* 如果数据需要嵌套结构、JSON 数值/布尔类型或 JSONPath 查询，应使用 `jsonb`。 +* 安装扩展需要相应数据库权限；应用角色只需要其所用表和函数的权限。 + +完整的操作符和函数说明请参阅 https://www.postgresql.org/docs/18/hstore.html[PostgreSQL hstore 文档]。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 6b480fbd..178adee6 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -52,6 +52,7 @@ *** xref:5.9.adoc[pgrouting] *** xref:5.10.adoc[system_stats] *** xref:5.11.adoc[pgtt] +*** xref:5.12.adoc[hstore] * Monitor and O&M ** xref:3.2.adoc[Monitoring] ** xref:3.3.adoc[Maintenance] diff --git a/EN/modules/ROOT/pages/5.0.adoc b/EN/modules/ROOT/pages/5.0.adoc index 42144711..bce1eeab 100644 --- a/EN/modules/ROOT/pages/5.0.adoc +++ b/EN/modules/ROOT/pages/5.0.adoc @@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o |*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 |*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor |*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development +|*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 |==== 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. diff --git a/EN/modules/ROOT/pages/5.12.adoc b/EN/modules/ROOT/pages/5.12.adoc new file mode 100644 index 00000000..c8433d13 --- /dev/null +++ b/EN/modules/ROOT/pages/5.12.adoc @@ -0,0 +1,155 @@ +:sectnums: +:sectnumlevels: 5 + += hstore + +== Overview + +`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. + +This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and hstore 1.8 on Ubuntu 22.04 x86_64. + +== Compatibility + +[cols="1,1,3"] +|=== +|IvorySQL mode |Status |Verified operations + +|PostgreSQL +|Supported +|Extension installation, key lookup, containment, update, JSON conversion, and GIN indexing + +|Oracle compatible +|Supported +|The same hstore data type, functions, operators, and indexes are available after switching `ivorysql.compatible_mode` +|=== + +[NOTE] +`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. + +== Installation + +The official IvorySQL 5.4 binary package already contains hstore. Connect as a user allowed to create extensions and run: + +[source,sql] +---- +CREATE EXTENSION hstore; + +SELECT extversion +FROM pg_extension +WHERE extname = 'hstore'; +---- + +The expected extension version in IvorySQL 5.4 is `1.8`. + +For an IvorySQL installation built from source, install hstore from the same source tree before creating the extension: + +[source,shell] +---- +cd /path/to/IvorySQL +make -C contrib/hstore +make -C contrib/hstore install +---- + +== Usage + +=== Store and query attributes + +[source,sql] +---- +CREATE TABLE application_settings ( + id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + attributes hstore NOT NULL +); + +INSERT INTO application_settings(attributes) +VALUES ('theme=>dark, region=>cn, notifications=>enabled'); + +-- Fetch one value. +SELECT attributes -> 'theme' AS theme +FROM application_settings; + +-- Test whether a key exists. +SELECT id +FROM application_settings +WHERE attributes ? 'region'; + +-- Test whether all supplied pairs are present. +SELECT id +FROM application_settings +WHERE attributes @> 'theme=>dark'::hstore; +---- + +=== Update and remove keys + +The concatenation operator replaces an existing value when the right-hand hstore contains the same key. + +[source,sql] +---- +UPDATE application_settings +SET attributes = attributes || 'theme=>light, locale=>zh_CN'::hstore +WHERE id = 1; + +UPDATE application_settings +SET attributes = delete(attributes, 'notifications') +WHERE id = 1; +---- + +=== Add a GIN index + +GIN indexes accelerate key-existence and containment predicates such as `?`, `?&`, `?|`, and `@>`. + +[source,sql] +---- +CREATE INDEX application_settings_attributes_gin +ON application_settings +USING gin (attributes); + +ANALYZE application_settings; +---- + +=== Convert to JSON + +[source,sql] +---- +SELECT hstore_to_json(attributes) +FROM application_settings; +---- + +`hstore_to_json()` preserves SQL NULL values as JSON `null`, while all non-NULL hstore values are represented as JSON strings. + +== Oracle-compatible mode + +No separate extension installation is required. The extension is database-wide and remains available when the session changes mode: + +[source,sql] +---- +SET ivorysql.compatible_mode = oracle; + +SELECT 'a=>1, b=>2'::hstore -> 'b' FROM dual; +SELECT exist('a=>1, b=>2'::hstore, 'a') FROM dual; +---- + +Both statements return successfully (`2` and `true`, respectively) on IvorySQL 5.4. + +== Verification + +IvorySQL's bundled regression suites can be run from the source tree against an installed server: + +[source,shell] +---- +cd /path/to/IvorySQL/contrib/hstore +make installcheck +make oracle-installcheck +---- + +The IvorySQL 5.4 verification completed both PostgreSQL tests (`hstore`, `hstore_utf8`) and both Oracle-compatible tests (`ivy_hstore`, `hstore_utf8`) successfully. + +== Limitations and guidance + +* Keys and non-NULL values are text; hstore does not provide nested objects or arrays. +* 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. +* Use `jsonb` instead when the data needs nesting, JSON numeric/Boolean types, or JSONPath queries. +* Extension installation requires appropriate database privileges. Application roles only need privileges on the tables and functions they use. + +For the complete operator and function reference, see the https://www.postgresql.org/docs/18/hstore.html[PostgreSQL hstore documentation].