★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 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 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

F.9. cube

本モジュールは、多次元立方体を表すためのcubeデータ型を実装します。 (訳注:以下cubeを立方体と訳しますが、ここでのcubeが指しているものは、厳密には「(超)立方体」ではありません。正確には、それぞれの「(超)面」がある座標軸に対して垂直な「(超)直方体」です。)

このモジュールはtrustedと見なされます。つまり、現在のデータベースに対してCREATE権限を持つ非スーパーユーザがインストールできます。

F.9.1. 構文

表 F.2cube型で有効な外部表現を示します。 xyなどは浮動小数点数を意味します。

表F.2 cubeの外部表現

外部構文意味
x 1次元の点。(すなわち、幅ゼロの一次元間隔)
(x)同上
x1,x2,...,xn n次元空間の点。 内部的には体積0の立方体として表されます。
(x1,x2,...,xn)同上
(x),(y) xからyまで(またはその逆)の1次元の間隔。 順序は関係ありません。
[(x),(y)]同上
(x1,...,xn),(y1,...,yn) 対角の組み合わせで表されるn次元の立方体。
[(x1,...,xn),(y1,...,yn)]同上

立方体の対角の入力順序は関係ありません。 統一的な左下 — 右上という内部表現を作成するために必要ならば、cube関数は自動的に値を交換します。 角が一致する場合、cube型には無駄を省くために、点であるフラグを加えた一つの角のみ格納されます。

空白文字は入力時に無視されます。 このため、[(x),(y)][ ( x ), ( y ) ]と同じです。

F.9.2. 精度

値は内部的に64ビットの浮動小数点数値として格納されます。 つまり、有効桁が16より大きい数値は切り詰められることを意味します。

F.9.3. 使用方法

表 F.3は、cube型に提供されている専用の演算子を示します。

表F.3 cubeの演算子

演算子

説明

cube && cubeboolean

立方体が重なるか。

cube @> cubeboolean

1番目の立方体は2番目のものを含むか。

cube <@ cubeboolean

1番目の立方体は2番目のものに含まれるか。

cube -> integerfloat8

立方体の(1から数えた)n次座標を取得します。

cube ~> integerfloat8

以下のように立方体のn次座標を取得します。 n = 2 * k - 1 はk次元の下界を、n = 2 * kk次元の上界を意味します。 負のnは、対応する正の座標の正負反転した値を示します。 この演算子はKNN-GiSTのサポートのために設計されています。

cube <-> cubefloat8

2つの立方体のユークリッド距離を計算します。

cube <#> cubefloat8

2つの立方体のタクシー(L-1計量)距離を計算します。

cube <=> cubefloat8

2つの立方体のチェビシェフ(L-無限大計量)距離を計算します。


(PostgreSQL 8.2以前では、包含演算子@><@はそれぞれ@~と呼ばれていました。 これらの名前はまだ利用できますが、廃止予定であり、最終的にはなくなります。 古い名前がコアの幾何データ型が従う規約と反対であることに注意してください。)

上記の演算子に加えて、cube型では表 9.1にある通常の比較演算子が利用可能です。 これらの演算子は、まず最初の座標を比較し、それらが同一の場合は2番目の座標を比較し、と続けます。 それらは、主にcube型のためのB-treeインデックス演算子クラスをサポートするために存在し、例えばcube型の列にUNIQUE制約をつけたい場合に便利です。

cubeモジュールは、cube型の値用にGiSTインデックス演算子クラスも提供します。 cube型GiSTインデックスは、WHERE句内にて=&&@><@演算子を用いて値を検索するために使用することができます。

加えて、cube型GiSTインデックスは、ORDER BY句内にて<-><#><=>のメトリック演算子を用いて近傍値を発見するために使用することができます。 例えば、3次元の点である(0.5, 0.5, 0.5)の最近傍点は、以下のように効率よく発見できます。

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

~>演算子でもこの方法で、選択された座標によってソートされた最初のいくつかの値を効率よく探査するために使用できます。 例えば、1番目の座標(左下隅)によって昇順に並べ替えられた最初のいくつかの立方体を取得するために、以下のような問い合わせを使用することができます。

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

そして、右上の1番目の座標によって昇順に並び替えられた2次元の立方体を取得するために、以下のような問い合わせを使用することができます。

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

表 F.4は有効な関数を示します。

表F.4 cubeの関数

関数

説明

cube ( float8 ) → cube

同じ座標をもつ、1次元の立方体を作成します。

cube(1)(1)

cube ( float8, float8 ) → cube

1次元の立方体を作成します。

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

cube ( float8[] ) → cube

配列で定義される座標を使用した体積0の立方体を作成します。

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

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

2つの配列で定義される右上および左下座標を持つ立方体を作成します。配列長は同じでなければなりません。

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

立方体が点、つまり立方体が定義する2つの隅が同一の場合真を返します。

cube_is_point(cube(1,1))t

cube_distance ( cube, cube ) → float8

2つの立方体間の距離を返します。 両方の立方体が点の場合、これは通常の距離測定関数です。

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

2つの立方体の和集合を作成します。

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

cube_inter ( cube, cube ) → cube

2つの立方体の共通部分を作成します。

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.9.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)

次元が異なる立方体の二項演算すべてにおいて、より低い次元の方がデカルト投影、つまり、文字列表現で省略された座標に0を持つものになると仮定します。 上の例は以下と同じです。

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

以下の包含の述部は点構文を使用しますが、実際内部的には第2引数は矩形として表されます。 この構文により、別の点用の型や(box,point)という述部用の関数を定義することが不要になります。

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

F.9.5. 注釈

使用例については、sql/cube.sqlリグレッションテストを参照してください。

破壊防止のために立方体の次元数に100までという制限を行いました。 これはcubedata.hで設定されており、必要に応じて多少大きくすることができます。

F.9.6. クレジット

原作者: Gene Selkov, Jr. , Mathematics and Computer Science Division, Argonne National Laboratory.

GiST (http://gist.cs.berkeley.edu/)の要点(gist)を説明してくださったJoe Hellerstein博士 (https://dsf.berkeley.edu/jmh/) に感謝します。 また、Illustra用の例の作者である彼の以前の生徒Andy Dongに感謝します。 また、自分の世界を作成できるようにし、静かに生活できるようにしてもらった、過去から現在までのすべてのPostgres開発者に感謝します。 データベース研究を長年誠実にサポートしてくれたArgonne LabとU.S. Department of Energyにも感謝します。

2002年8月/9月にBruno Wolff III による小規模な改修がこのパッケージになされました。 この改修には、単精度から倍精度への精度の変更といくつかの関数の追加が含まれます。

2006年7月にJoshua Reich による改修がさらになされました。 この改修にはcube(float8[], float8[])が含まれ、また、古いV0プロトコルからV1呼び出しプロトコルを使用するようコードが整理されました。