PostgreSQL：說明文件：17：F.10. cube — 多維立方體資料類型

支援的版本：目前 (17) / 16 / 15 / 14 / 13

開發版本：devel

不支援的版本：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 索引運算符類別。可以使用 =、&&、@> 和 <@ 運算符在 WHERE 子句中搜尋值，來使用 cube GiST 索引。

此外，可以使用度量運算符 <->、<#> 和 <=> 在 ORDER BY 子句中找到最近鄰居，來使用 cube GiST 索引。例如，可以使用以下方法有效地找到 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)');

以下包含謂詞使用點語法，但實際上第二個參數在內部由一個框表示。此語法使得無需定義單獨的點類型和用於 (框,點) 謂詞的函數。

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. <selkovjr@mcs.anl.gov>, Mathematics and Computer Science Division, Argonne National Laboratory.

我主要感謝 Joe Hellerstein 教授 (https://dsf.berkeley.edu/jmh/) 闡明了 GiST 的要點 (http://gist.cs.berkeley.edu/)，以及他的前學生 Andy Dong 為 Illustra 撰寫的範例。我也感謝所有 Postgres 開發人員，無論現在或過去，他們使我自己能夠創造自己的世界並不受干擾地生活在其中。我還要感謝 Argonne Lab 和美國能源部多年來對我的資料庫研究的忠實支持。

Bruno Wolff III <bruno@wolff.to> 在 2002 年 8 月/9 月對這個套件進行了小幅更新。這些更新包括將精度從單精度更改為雙精度，並新增了一些新函數。

Joshua Reich <josh@root.net> 在 2006 年 7 月進行了其他更新。這些更新包括 cube(float8[], float8[]) 並清理了程式碼，以使用 V1 呼叫協定而不是已棄用的 V0 協定。

上一頁	上層	下一頁
F.9. citext — 一種不區分大小寫的字元字串類型	首頁	F.11. dblink — 連線到其他 PostgreSQL 資料庫

提交更正

如果您在文件中發現任何不正確、與您使用特定功能的體驗不符或需要進一步澄清的地方，請使用此表格來報告文件問題。