PostgreSQL：文档：17：F.10. cube — 多维立方体数据类型

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

开发版本：开发版

不支持的版本：12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3

F.10. cube — 多维立方体数据类型
上一页	向上	附录 F. 附加提供的模块和扩展	主页	下一页

F.10. cube — 多维立方体数据类型 #

F.10.1. 语法
F.10.2. 精度
F.10.3. 用法
F.10.4. 默认值
F.10.5. 注意事项
F.10.6. 贡献者

此模块实现了一个用于表示多维立方体的数据类型 cube。

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

F.10.1. 语法 #

表 F.1 显示了 cube 类型的有效外部表示。x、y 等表示浮点数。

表 F.1. 立方体外部表示

外部语法	含义
`x`	一维点（或零长度一维区间）
`(x)`	与上述相同
`x1,x2,...,xn`	n 维空间中的一个点，在内部表示为零体积立方体
`(x1,x2,...,xn)`	与上述相同
`(x),(y)`	一个一维区间，从 `x` 开始，到 `y` 结束，反之亦然；顺序无关紧要
`[(x),(y)]`	与上述相同
`(x1,...,xn),(y1,...,yn)`	一个 n 维立方体，由其对角相对的两个角表示
`[(x1,...,xn),(y1,...,yn)]`	与上述相同

输入立方体的对角相对角的顺序无关紧要。cube 函数会在需要时自动交换值，以创建统一的 “左下角 - 右上角” 内部表示。当角重合时，cube 只存储一个角以及一个 “是点” 标志，以避免浪费空间。

输入时会忽略空格，所以 [(x),(y)] 与 [ ( x ), ( y ) ] 相同。

F.10.2. 精度 #

值在内部存储为 64 位浮点数。这意味着超过约 16 位有效数字的数字将被截断。

F.10.3. 用法 #

表 F.2 显示了为 cube 类型提供的专用运算符。

表 F.2. 立方体运算符

运算符描述
`cube` `&&` `cube` → `boolean` 立方体是否重叠？
`cube` `@>` `cube` → `boolean` 第一个立方体是否包含第二个立方体？
`cube` `<@` `cube` → `boolean` 第一个立方体是否包含在第二个立方体中？
`cube` `->` `integer` → `float8` 提取立方体的第 `n` 个坐标（从 1 开始计数）。
`cube` `~>` `integer` → `float8` 提取立方体的第 `n` 个坐标，计数方式如下：`n` = 2 * `k` - 1 表示第 `k` 维的下界，`n` = 2 * `k` 表示第 `k` 维的上界。负数 `n` 表示相应正坐标的相反值。此运算符设计用于 KNN-GiST 支持。
`cube` `<->` `cube` → `float8` 计算两个立方体之间的欧几里得距离。
`cube` `<#>` `cube` → `float8` 计算两个立方体之间的出租车（L-1 度量）距离。
`cube` `<=>` `cube` → `float8` 计算两个立方体之间的切比雪夫（L-inf 度量）距离。

运算符

描述

cube && cube → boolean

立方体是否重叠？

cube @> cube → boolean

第一个立方体是否包含第二个立方体？

cube <@ cube → boolean

第一个立方体是否包含在第二个立方体中？

cube -> integer → float8

提取立方体的第 n 个坐标（从 1 开始计数）。

cube ~> integer → float8

提取立方体的第 n 个坐标，计数方式如下：n = 2 * k - 1 表示第 k 维的下界，n = 2 * k 表示第 k 维的上界。负数 n 表示相应正坐标的相反值。此运算符设计用于 KNN-GiST 支持。

cube <-> cube → float8

计算两个立方体之间的欧几里得距离。

cube <#> cube → float8

计算两个立方体之间的出租车（L-1 度量）距离。

cube <=> cube → float8

计算两个立方体之间的切比雪夫（L-inf 度量）距离。

除了上述运算符外，表 9.1 中显示的常用比较运算符也适用于 cube 类型。这些运算符首先比较第一个坐标，如果它们相等，则比较第二个坐标，依此类推。它们的存在主要是为了支持 cube 的 b-tree 索引运算符类，例如，如果您希望在 cube 列上使用 UNIQUE 约束，这可能会很有用。否则，此排序没有太多实际用途。

cube 模块还为 cube 值提供了一个 GiST 索引运算符类。cube GiST 索引可用于在 WHERE 子句中使用 =、&&、@> 和 <@ 运算符搜索值。

此外，cube GiST 索引可用于在 ORDER BY 子句中使用度量运算符 <->、<#> 和 <=> 查找最近邻。例如，可以使用以下方式高效地找到 3-D 点 (0.5, 0.5, 0.5) 的最近邻

SELECT c FROM test ORDER BY c <-> cube(array[0.5,0.5,0.5]) LIMIT 1;

~> 运算符也可以通过这种方式使用，以有效地检索按所选坐标排序的前几个值。例如，要获取按第一个坐标（左下角）升序排序的前几个立方体，可以使用以下查询

SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;

要获取按右上角的第一个坐标降序排序的 2-D 立方体

SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;

表 F.3 显示了可用的函数。

表 F.3. 立方体函数

函数描述示例
`cube` ( `float8` ) → `cube` 创建一个一维立方体，其两个坐标相同。 `cube(1)` → `(1)`
`cube` ( `float8`, `float8` ) → `cube` 创建一个一维立方体。 `cube(1, 2)` → `(1),(2)`
`cube` ( `float8[]` ) → `cube` 使用数组定义的坐标创建一个零体积立方体。 `cube(ARRAY[1,2,3])` → `(1, 2, 3)`
`cube` ( `float8[]`, `float8[]` ) → `cube` 创建一个立方体，其右上角和左下角坐标由两个数组定义，这两个数组的长度必须相同。 `cube(ARRAY[1,2], ARRAY[3,4])` → `(1, 2),(3, 4)`
`cube` ( `cube`, `float8` ) → `cube` 通过向现有立方体添加一个维度来创建一个新立方体，新坐标的两个端点的值相同。这对于从计算值逐段构建立方体很有用。 `cube('(1,2),(3,4)'::cube, 5)` → `(1, 2, 5),(3, 4, 5)`
`cube` ( `cube`, `float8`, `float8` ) → `cube` 通过向现有立方体添加一个维度来创建一个新立方体。这对于从计算值逐段构建立方体很有用。 `cube('(1,2),(3,4)'::cube, 5, 6)` → `(1, 2, 5),(3, 4, 6)`
`cube_dim` ( `cube` ) → `integer` 返回立方体的维度数。 `cube_dim('(1,2),(3,4)')` → `2`
`cube_ll_coord` ( `cube`, `integer` ) → `float8` 返回立方体左下角的第 `n` 个坐标值。 `cube_ll_coord('(1,2),(3,4)', 2)` → `2`
`cube_ur_coord` ( `cube`, `integer` ) → `float8` 返回立方体右上角的第 `n` 个坐标值。 `cube_ur_coord('(1,2),(3,4)', 2)` → `4`
`cube_is_point` ( `cube` ) → `boolean` 如果立方体是一个点（即，两个定义角相同），则返回 true。 `cube_is_point(cube(1,1))` → `t`
`cube_distance` ( `cube`, `cube` ) → `float8` 返回两个立方体之间的距离。如果两个立方体都是点，则这是正常的距离函数。 `cube_distance('(1,2)', '(3,4)')` → `2.8284271247461903`
`cube_subset` ( `cube`, `integer[]` ) → `cube` 使用数组中的维度索引列表从现有立方体创建一个新立方体。可用于提取单个维度的端点、删除维度或根据需要重新排序它们。 `cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2])` → `(3),(7)` `cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1])` → `(5, 3, 1, 1),(8, 7, 6, 6)`
`cube_union` ( `cube`, `cube` ) → `cube` 生成两个立方体的并集。 `cube_union('(1,2)', '(3,4)')` → `(1, 2),(3, 4)`
`cube_inter` ( `cube`, `cube` ) → `cube` 生成两个立方体的交集。 `cube_inter('(1,2)', '(3,4)')` → `(3, 4),(1, 2)`
`cube_enlarge` ( `c` `cube`, `r` `double`, `n` `integer` ) → `cube` 至少在 `n` 个维度上，将立方体的大小增加指定的半径 `r`。如果半径为负值，则会缩小立方体。所有定义的维度都会改变半径 `r`。左下角的坐标会减少 `r`，而右上角的坐标会增加 `r`。如果左下角坐标增加到大于相应的右上角坐标（仅当 `r` < 0 时才会发生），则将两个坐标都设置为它们的平均值。如果 `n` 大于定义的维度数并且立方体正在放大（`r` > 0），则会添加额外的维度以使 `n` 总共增加；0 用作额外坐标的初始值。此函数对于在点周围创建边界框以搜索附近的点非常有用。 `cube_enlarge('(1,2),(3,4)', 0.5, 3)` → `(0.5, 1.5, -0.5),(3.5, 4.5, 0.5)`

函数

描述

示例

cube ( float8 ) → cube

创建一个一维立方体，其两个坐标相同。

cube(1) → (1)

cube ( float8, float8 ) → cube

创建一个一维立方体。

cube(1, 2) → (1),(2)

cube ( float8[] ) → cube

使用数组定义的坐标创建一个零体积立方体。

cube(ARRAY[1,2,3]) → (1, 2, 3)

cube ( float8[], float8[] ) → cube

创建一个立方体，其右上角和左下角坐标由两个数组定义，这两个数组的长度必须相同。

cube(ARRAY[1,2], ARRAY[3,4]) → (1, 2),(3, 4)

cube ( cube, float8 ) → cube

通过向现有立方体添加一个维度来创建一个新立方体，新坐标的两个端点的值相同。这对于从计算值逐段构建立方体很有用。

cube('(1,2),(3,4)'::cube, 5) → (1, 2, 5),(3, 4, 5)

cube ( cube, float8, float8 ) → cube

通过向现有立方体添加一个维度来创建一个新立方体。这对于从计算值逐段构建立方体很有用。

cube('(1,2),(3,4)'::cube, 5, 6) → (1, 2, 5),(3, 4, 6)

cube_dim ( cube ) → integer

返回立方体的维度数。

cube_dim('(1,2),(3,4)') → 2

cube_ll_coord ( cube, integer ) → float8

返回立方体左下角的第 n 个坐标值。

cube_ll_coord('(1,2),(3,4)', 2) → 2

cube_ur_coord ( cube, integer ) → float8

返回立方体右上角的第 n 个坐标值。

cube_ur_coord('(1,2),(3,4)', 2) → 4

cube_is_point ( cube ) → boolean

如果立方体是一个点（即，两个定义角相同），则返回 true。

cube_is_point(cube(1,1)) → t

cube_distance ( cube, cube ) → float8

返回两个立方体之间的距离。如果两个立方体都是点，则这是正常的距离函数。

cube_distance('(1,2)', '(3,4)') → 2.8284271247461903

cube_subset ( cube, integer[] ) → cube

使用数组中的维度索引列表从现有立方体创建一个新立方体。可用于提取单个维度的端点、删除维度或根据需要重新排序它们。

cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) → (3),(7)

cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) → (5, 3, 1, 1),(8, 7, 6, 6)

cube_union ( cube, cube ) → cube

生成两个立方体的并集。

cube_union('(1,2)', '(3,4)') → (1, 2),(3, 4)

cube_inter ( cube, cube ) → cube

生成两个立方体的交集。

cube_inter('(1,2)', '(3,4)') → (3, 4),(1, 2)

cube_enlarge ( c cube, r double, n integer ) → cube

至少在 n 个维度上，将立方体的大小增加指定的半径 r。如果半径为负值，则会缩小立方体。所有定义的维度都会改变半径 r。左下角的坐标会减少 r，而右上角的坐标会增加 r。如果左下角坐标增加到大于相应的右上角坐标（仅当 r < 0 时才会发生），则将两个坐标都设置为它们的平均值。如果 n 大于定义的维度数并且立方体正在放大（r > 0），则会添加额外的维度以使 n 总共增加；0 用作额外坐标的初始值。此函数对于在点周围创建边界框以搜索附近的点非常有用。

cube_enlarge('(1,2),(3,4)', 0.5, 3) → (0.5, 1.5, -0.5),(3.5, 4.5, 0.5)

F.10.4. 默认值 #

此并集

select cube_union('(0,5,2),(2,3,1)', '0');
cube_union
-------------------
(0, 0, 0),(2, 5, 2)
(1 row)

并不与常识相悖，交集也是如此

select cube_inter('(0,-1),(1,1)', '(-2),(2)');
cube_inter
-------------
(0, 0),(1, 0)
(1 row)

在所有对不同维度的立方体进行的二进制运算中，维度较低的立方体被假定为笛卡尔投影，即，在字符串表示中省略的坐标位置上具有零。以上示例等效于

cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');

以下包含谓词使用点语法，而实际上第二个参数在内部由一个框表示。这种语法使得不必为（box，point）谓词定义单独的点类型和函数。

select cube_contains('(0,0),(1,1)', '0.5,0.5');
cube_contains
--------------
t
(1 row)

F.10.5. 注释 #

有关用法的示例，请参见回归测试 sql/cube.sql。

为了防止人们破坏东西，立方体的维度数限制为 100。如果需要更大的维度数，请在 cubedata.h 中设置。

F.10.6. 致谢 #

原始作者：Gene Selkov, Jr. <[email protected]>，阿贡国家实验室数学与计算机科学部。

我主要感谢 Joe Hellerstein 教授（https://dsf.berkeley.edu/jmh/）阐明了 GiST（http://gist.cs.berkeley.edu/）的要点，以及他的前学生 Andy Dong 为 Illustra 编写的示例。我也感谢所有 Postgres 的开发人员，无论过去还是现在，使我能够创造自己的世界并在其中不受干扰地生活。我要感谢阿贡实验室和美国能源部多年来对我数据库研究的忠实支持。

Bruno Wolff III <[email protected]> 在 2002 年 8 月/9 月对此软件包进行了小的更新。其中包括将精度从单精度更改为双精度，并添加了一些新函数。

Joshua Reich <[email protected]> 在 2006 年 7 月进行了其他更新。其中包括 cube(float8[], float8[]) 并清理了代码以使用 V1 调用协议而不是已弃用的 V0 协议。

上一页	向上	下一页
F.9. citext — 一个不区分大小写的字符串类型	主页	F.11. dblink — 连接到其他 PostgreSQL 数据库

提交更正

如果您在文档中发现任何不正确的内容，与您特定功能的使用体验不符，或需要进一步澄清，请使用此表格报告文档问题。