F.18. intarray — PostgreSQL 13

支持中的版本：当前版本 (18) / 17 / 16 / 15 / 14

开发中的版本： 19 / 20devel

已结束支持的版本： 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3

历史版本。 PostgreSQL 13 已结束支持。 2025-11-13. 请参阅当前版本手册.

F.18. intarray
上一页	上一级	附录 F. 额外提供的模块	起始页	下一页

F.18. intarray #

F.18.1. intarray 函数和操作符
F.18.2. 索引支持
F.18.3. 示例
F.18.4. 基准测试
F.18.5. 作者

intarray 模块提供了一些有用的函数和操作符，用于操作不含 NULL 的整数数组。它还支持使用其中某些操作符进行索引搜索。

如果所提供的数组中包含任何 NULL 元素，所有这些操作都会抛出错误。

这些操作中有许多只对一维数组才有意义。尽管它们也接受更高维度的输入数组，但数据会被视为按存储顺序排列的线性数组。

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

F.18.1. `intarray` 函数和操作符

intarray 模块提供的函数列在表 F.9 中，操作符列在表 F.10 中。

表 F.9. intarray 函数

函数描述示例
`icount` ( `integer[]` ) → `integer` 返回数组中的元素个数。 `icount('{1,2,3}'::integer[])` → `3`
`sort` ( `integer[]`, `dir` `text` ) → `integer[]` 按升序或降序对数组排序。`dir` 必须为 `asc` 或 `desc`。 `sort('{1,3,2}'::integer[], 'desc')` → `{3,2,1}`
`sort` ( `integer[]` ) → `integer[]` `sort_asc` ( `integer[]` ) → `integer[]` 按升序排序。 `sort(array[11,77,44])` → `{11,44,77}`
`sort_desc` ( `integer[]` ) → `integer[]` 按降序排序。 `sort_desc(array[11,77,44])` → `{77,44,11}`
`uniq` ( `integer[]` ) → `integer[]` 移除相邻的重复项。常与 `sort` 一起使用，以移除所有重复项。 `uniq('{1,2,2,3,1,1}'::integer[])` → `{1,2,3,1}` `uniq(sort('{1,2,3,2,1}'::integer[]))` → `{1,2,3}`
`idx` ( `integer[]`, `item` `integer` ) → `integer` 返回第一个与 `item` 匹配的数组元素的索引，若无匹配则返回 0。 `idx(array[11,22,33,22,11], 22)` → `2`
`subarray` ( `integer[]`, `start` `integer`, `len` `integer` ) → `integer[]` 提取数组中从位置 `start` 开始、长度为 `len` 个元素的部分。 `subarray('{1,2,3,2,1}'::integer[], 2, 3)` → `{2,3,2}`
`subarray` ( `integer[]`, `start` `integer` ) → `integer[]` 提取数组中从位置 `start` 开始的部分。 `subarray('{1,2,3,2,1}'::integer[], 2)` → `{2,3,2,1}`
`intset` ( `integer` ) → `integer[]` 创建一个只含一个元素的数组。 `intset(42)` → `{42}`

函数

描述

示例

icount ( integer[] ) → integer

返回数组中的元素个数。

icount('{1,2,3}'::integer[]) → 3

sort ( integer[], dir text ) → integer[]

按升序或降序对数组排序。dir 必须为 asc 或 desc。

sort('{1,3,2}'::integer[], 'desc') → {3,2,1}

sort ( integer[] ) → integer[]

sort_asc ( integer[] ) → integer[]

按升序排序。

sort(array[11,77,44]) → {11,44,77}

sort_desc ( integer[] ) → integer[]

按降序排序。

sort_desc(array[11,77,44]) → {77,44,11}

uniq ( integer[] ) → integer[]

移除相邻的重复项。常与 sort 一起使用，以移除所有重复项。

uniq('{1,2,2,3,1,1}'::integer[]) → {1,2,3,1}

uniq(sort('{1,2,3,2,1}'::integer[])) → {1,2,3}

idx ( integer[], item integer ) → integer

返回第一个与 item 匹配的数组元素的索引，若无匹配则返回 0。

idx(array[11,22,33,22,11], 22) → 2

subarray ( integer[], start integer, len integer ) → integer[]

提取数组中从位置 start 开始、长度为 len 个元素的部分。

subarray('{1,2,3,2,1}'::integer[], 2, 3) → {2,3,2}

subarray ( integer[], start integer ) → integer[]

提取数组中从位置 start 开始的部分。

subarray('{1,2,3,2,1}'::integer[], 2) → {2,3,2,1}

intset ( integer ) → integer[]

创建一个只含一个元素的数组。

intset(42) → {42}

表 F.10. intarray 操作符

操作符描述
`integer[]` `&&` `integer[]` → `boolean` 数组是否重叠（至少有一个共同元素）？
`integer[]` `@>` `integer[]` → `boolean` 左数组是否包含右数组？
`integer[]` `<@` `integer[]` → `boolean` 左数组是否包含在右数组中？
`#` `integer[]` → `integer` 返回数组中的元素个数。
`integer[]` `#` `integer` → `integer` 返回第一个与右操作数匹配的数组元素的索引，若无匹配则返回 0。（与 `idx` 函数相同。）
`integer[]` `+` `integer` → `integer[]` 将元素添加到数组末尾。
`integer[]` `+` `integer[]` → `integer[]` 将这些数组连接起来。
`integer[]` `-` `integer` → `integer[]` 从数组中移除与右操作数匹配的项。
`integer[]` `-` `integer[]` → `integer[]` 从左数组中移除右数组中的元素。
`integer[]` `\|` `integer` → `integer[]` 计算参数的并集。
`integer[]` `\|` `integer[]` → `integer[]` 计算参数的并集。
`integer[]` `&` `integer[]` → `integer[]` 计算参数的交集。
`integer[]` `@@` `query_int` → `boolean` 数组是否满足查询？（见下文）
`query_int` `~~` `integer[]` → `boolean` 数组是否满足查询？（`@@`的交换子）

操作符

描述

integer[] && integer[] → boolean

数组是否重叠（至少有一个共同元素）？

integer[] @> integer[] → boolean

左数组是否包含右数组？

integer[] <@ integer[] → boolean

左数组是否包含在右数组中？

# integer[] → integer

返回数组中的元素个数。

integer[] # integer → integer

返回第一个与右操作数匹配的数组元素的索引，若无匹配则返回 0。（与 idx 函数相同。）

integer[] + integer → integer[]

将元素添加到数组末尾。

integer[] + integer[] → integer[]

将这些数组连接起来。

integer[] - integer → integer[]

从数组中移除与右操作数匹配的项。

integer[] - integer[] → integer[]

从左数组中移除右数组中的元素。

integer[] | integer → integer[]

计算参数的并集。

integer[] | integer[] → integer[]

计算参数的并集。

integer[] & integer[] → integer[]

计算参数的交集。

integer[] @@ query_int → boolean

数组是否满足查询？（见下文）

query_int ~~ integer[] → boolean

数组是否满足查询？（@@的交换子）

（在 PostgreSQL 8.2 之前，包含操作符 @> 和 <@ 分别称为 @ 和 ~。这些名称仍然可用，但已弃用，最终将被删除。请注意，旧名称与核心几何数据类型以前采用的约定正好相反！）

操作符&&、@> 和 <@等价于 PostgreSQL 内置的同名操作符，不同之处在于它们只适用于不包含 NULL 的整数数组，而内置操作符适用于任何数组类型。这一限制使它们在很多情况下比内置操作符更快。

@@和~~操作符用于测试数组是否满足某个查询，该查询表示为专用数据类型 query_int 的一个值。一个查询由若干整数值组成，这些值会与数组元素进行检查，并且可通过操作符&（AND）、|（OR）和!（NOT）组合起来。必要时可以使用括号。例如，查询 1&(2|3) 可匹配包含 1 且还包含 2 或 3 之一的数组。

F.18.2. 索引支持

intarray 为&&、@>、<@和@@操作符以及常规数组相等运算提供索引支持。

提供了两个带参数的 GiST 索引操作符类：默认使用的 gist__int_ops 适用于小到中等规模的数据集，而 gist__intbig_ops 使用较大的签名，更适合为大型数据集建立索引（即列中包含大量不同数组值的数据集）。该实现使用 RD-tree 数据结构，并带有内置的有损压缩。

gist__int_ops 将整数集近似表示为整数范围数组。其可选整数参数 numranges 决定单个索引键中的最大范围数。numranges 的默认值是 100，有效值在 1 到 253 之间。使用更大的数组作为 GiST 索引键会带来更精确的搜索（扫描索引的较小部分和较少的堆页），代价是索引会更大。

gist__intbig_ops 将整数集近似表示为位图签名。其可选整数参数 siglen 决定签名长度（以字节为单位）。默认签名长度为 16 字节，签名长度的有效值在 1 到 2024 字节之间。更长的签名会带来更精确的搜索（扫描索引的较小部分和较少的堆页），代价是索引会更大。

另有一个非默认的 GIN 操作符类 gin__int_ops，支持相同的操作符。

在 GiST 和 GIN 索引之间如何选择，取决于二者的相对性能特征，相关讨论见其他部分。

F.18.3. 示例

-- a message can be in one or more “sections”
CREATE TABLE message (mid INT PRIMARY KEY, sections INT[], ...);

-- create specialized index with signature length of 32 bytes
CREATE INDEX message_rdtree_idx ON message USING GIST (sections gist__intbig_ops (siglen = 32));

-- select messages in section 1 OR 2 - OVERLAP operator
SELECT message.mid FROM message WHERE message.sections && '{1,2}';

-- select messages in sections 1 AND 2 - CONTAINS operator
SELECT message.mid FROM message WHERE message.sections @> '{1,2}';

-- the same, using QUERY operator
SELECT message.mid FROM message WHERE message.sections @@ '1&2'::query_int;

F.18.4. 基准测试

源代码目录 contrib/intarray/bench 包含一个基准测试套件，可以针对一个已安装的 PostgreSQL 服务器运行。（还要求已安装 DBD::Pg。）运行方式如下：

cd .../contrib/intarray/bench
createdb TEST
psql -c "CREATE EXTENSION intarray" TEST
./create_test.pl | psql TEST
./bench.pl

bench.pl 脚本有很多选项，在不带任何参数运行时会显示这些选项。

F.18.5. 作者

所有工作都由 Teodor Sigaev（<teodor@sigaev.ru>）和 Oleg Bartunov（<oleg@sai.msu.su>）完成。更多信息请见 http://www.sai.msu.su/~megera/postgres/gist/。Andrey Oktyabrski 在添加新函数和操作方面也做出了很大贡献。

上一页	上一级	下一页
F.17. intagg	起始页	F.19. isn

报告文档问题

阅读上游文档. 反馈更正前请先核对当前版本手册.