F.9. cube

PostgreSQL 11.4文書
		付録F 追加で提供されるモジュール
前へ	上へ	F.9. cube	次へ

本モジュールは、多次元立体を表すためのcubeデータ型を実装します。

F.9.1. 構文

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

表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の演算子

演算子	戻り値	説明
`a = b`	`boolean`	立体aと立体bは同じです。
`a && b`	`boolean`	立体aと立体bには重なりがあります。
`a @> b`	`boolean`	立体aは立体bを含みます。
`a <@ b`	`boolean`	立体aは立体bに含まれます。
`a < b`	`boolean`	立体aは立体bより小さいです。
`a <= b`	`boolean`	立体aは立体bより小さいか同じです。
`a > b`	`boolean`	立体aは立体bより大きいです。
`a >= b`	`boolean`	立体aは立体bより大きいか同じです。
`a <> b`	`boolean`	立体aは立体bと同じではありません。
`a -> n`	`float8`	立体の（1から数えた）`n`次座標を取得します。
`a ~> n`	`float8`	以下のように立体の`n`次座標を取得します。 n = 2 * k - 1 は`k`次元の下界を、n = 2 * k は`k`次元の上界を意味します。負の`n`は、対応する正の座標の正負反転した値を示します。この演算子はKNN-GiSTのサポートのために設計されています。
`a <-> b`	`float8`	aとbのユークリッド距離。
`a <#> b`	`float8`	aとbのタクシー（L-1メトリック）距離。
`a <=> b`	`float8`	aとbのチェビシェフ（L-無限大メトリック）距離。

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

スカラー順序演算子（<、>=など）は、ソート以外では事実上意味を成しません。これらの演算子は、まず最初の座標を比較し、それらが同一の場合は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]) == '(1,2)'`
`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_distance(cube, cube)`	`float8`	2つの立体間の距離を返します。両方の立体が点の場合、これは通常の距離測定関数です。
`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_inter(cube, cube)`	`cube`	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. <selkovjr@mcs.anl.gov>, Mathematics and Computer Science Division, Argonne National Laboratory.

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

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

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

前へ	上へ	次へ
F.8. citext	ホーム	F.10. dblink