バージョンごとのドキュメント一覧

F.10. cube — 多次元立方体データ型 #

<title>cube &mdash; a multi-dimensional cube data type</title>

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

This module is considered <quote>trusted</quote>, that is, it can be installed by non-superusers who have <literal>CREATE</literal> privilege on the current database. このモジュールはtrustedと見なされます。つまり、現在のデータベースに対してCREATE権限を持つ非スーパーユーザがインストールできます。

F.10.1. 構文 #

<title>Syntax</title>

<xref linkend="cube-repr-table"/> shows the valid external representations for the <type>cube</type> type. <replaceable>x</replaceable>, <replaceable>y</replaceable>, etc. denote floating-point numbers. 表 F.1cube型で有効な外部表現を示します。 xyなどは浮動小数点数を意味します。

表F.1 cubeの外部表現

<title>Cube External Representations</title>
外部構文意味
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)]同上

It does not matter which order the opposite corners of a cube are entered in. The <type>cube</type> functions automatically swap values if needed to create a uniform <quote>lower left &mdash; upper right</quote> internal representation. When the corners coincide, <type>cube</type> stores only one corner along with an <quote>is point</quote> flag to avoid wasting space. 立方体の対角の入力順序は関係ありません。 統一的な左下 — 右上という内部表現を作成するために必要ならば、cube関数は自動的に値を交換します。 角が一致する場合、cube型には無駄を省くために、点であるフラグを加えた一つの角のみ格納されます。

White space is ignored on input, so <literal>[(<replaceable>x</replaceable>),(<replaceable>y</replaceable>)]</literal> is the same as <literal>[ ( <replaceable>x</replaceable> ), ( <replaceable>y</replaceable> ) ]</literal>. 空白文字は入力時に無視されます。 このため、[(x),(y)][ ( x ), ( y ) ]と同じです。

F.10.2. 精度 #

<title>Precision</title>

Values are stored internally as 64-bit floating point numbers. This means that numbers with more than about 16 significant digits will be truncated. 値は内部的に64ビットの浮動小数点数値として格納されます。 つまり、有効桁が16より大きい数値は切り詰められることを意味します。

F.10.3. 使用方法 #

<title>Usage</title>

<xref linkend="cube-operators-table"/> shows the specialized operators provided for type <type>cube</type>. 表 F.2は、cube型に提供されている専用の演算子を示します。

表F.2 cubeの演算子

<title>Cube Operators</title>

Operator 演算子

Description 説明

cube && cubeboolean

Do the cubes overlap? 立方体が重なるか。

cube @> cubeboolean

Does the first cube contain the second? 1番目の立方体は2番目のものを含むか。

cube <@ cubeboolean

Is the first cube contained in the second? 1番目の立方体は2番目のものに含まれるか。

cube -> integerfloat8

Extracts the <parameter>n</parameter>-th coordinate of the cube (counting from 1). 立方体の(1から数えた)n次座標を取得します。

cube ~> integerfloat8

Extracts the <parameter>n</parameter>-th coordinate of the cube, counting in the following way: <parameter>n</parameter> = 2 * <parameter>k</parameter> - 1 means lower bound of <parameter>k</parameter>-th dimension, <parameter>n</parameter> = 2 * <parameter>k</parameter> means upper bound of <parameter>k</parameter>-th dimension. Negative <parameter>n</parameter> denotes the inverse value of the corresponding positive coordinate. This operator is designed for KNN-GiST support. 以下のように立方体のn次座標を取得します。 n = 2 * k - 1 はk次元の下界を、n = 2 * kk次元の上界を意味します。 負のnは、対応する正の座標の正負反転した値を示します。 この演算子はKNN-GiSTのサポートのために設計されています。

cube <-> cubefloat8

Computes the Euclidean distance between the two cubes. 2つの立方体のユークリッド距離を計算します。

cube <#> cubefloat8

Computes the taxicab (L-1 metric) distance between the two cubes. 2つの立方体のタクシー(L-1計量)距離を計算します。

cube <=> cubefloat8

Computes the Chebyshev (L-inf metric) distance between the two cubes. 2つの立方体のチェビシェフ(L-無限大計量)距離を計算します。


In addition to the above operators, the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> are available for type <type>cube</type>. These operators first compare the first coordinates, and if those are equal, compare the second coordinates, etc. They exist mainly to support the b-tree index operator class for <type>cube</type>, which can be useful for example if you would like a UNIQUE constraint on a <type>cube</type> column. Otherwise, this ordering is not of much practical use. 上記の演算子に加えて、cube型では表 9.1にある通常の比較演算子が利用可能です。 これらの演算子は、まず最初の座標を比較し、それらが同一の場合は2番目の座標を比較し、と続けます。 それらは、主にcube型のためのB-treeインデックス演算子クラスをサポートするために存在し、例えばcube型の列にUNIQUE制約をつけたい場合に便利です。

The <filename>cube</filename> module also provides a GiST index operator class for <type>cube</type> values. A <type>cube</type> GiST index can be used to search for values using the <literal>=</literal>, <literal>&amp;&amp;</literal>, <literal>@&gt;</literal>, and <literal>&lt;@</literal> operators in <literal>WHERE</literal> clauses. cubeモジュールは、cube型の値用にGiSTインデックス演算子クラスも提供します。 cube型GiSTインデックスは、WHERE句内にて=&&@><@演算子を用いて値を検索するために使用することができます。

In addition, a <type>cube</type> GiST index can be used to find nearest neighbors using the metric operators <literal>&lt;-&gt;</literal>, <literal>&lt;#&gt;</literal>, and <literal>&lt;=&gt;</literal> in <literal>ORDER BY</literal> clauses. For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5) could be found efficiently with: 加えて、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;

The <literal>~&gt;</literal> operator can also be used in this way to efficiently retrieve the first few values sorted by a selected coordinate. For example, to get the first few cubes ordered by the first coordinate (lower left corner) ascending one could use the following query: ~>演算子でもこの方法で、選択された座標によってソートされた最初のいくつかの値を効率よく探査するために使用できます。 例えば、1番目の座標(左下隅)によって昇順に並べ替えられた最初のいくつかの立方体を取得するために、以下のような問い合わせを使用することができます。

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

And to get 2-D cubes ordered by the first coordinate of the upper right corner descending: そして、右上の1番目の座標によって昇順に並べ替えられた2次元の立方体を取得するために、以下のような問い合わせを使用することができます。

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

<xref linkend="cube-functions-table"/> shows the available functions. 表 F.3は有効な関数を示します。

表F.3 cubeの関数

<title>Cube Functions</title>

Function 関数

Description 説明

Example(s)

cube ( float8 ) → cube

Makes a one dimensional cube with both coordinates the same. 同じ座標をもつ、1次元の立方体を作成します。

cube(1)(1)

cube ( float8, float8 ) → cube

Makes a one dimensional cube. 1次元の立方体を作成します。

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

cube ( float8[] ) → cube

Makes a zero-volume cube using the coordinates defined by the array. 配列で定義される座標を使用した体積0の立方体を作成します。

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

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

Makes a cube with upper right and lower left coordinates as defined by the two arrays, which must be of the same length. 2つの配列で定義される右上および左下座標を持つ立方体を作成します。配列長は同じでなければなりません。

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

cube ( cube, float8 ) → cube

Makes a new cube by adding a dimension on to an existing cube, with the same values for both endpoints of the new coordinate. This is useful for building cubes piece by piece from calculated values. 既存の立方体に次元を加え、新しい座標の同じ値の端点をもつ立方体を新しく作成します。 これは計算した値で部品を追加しながら立方体を構築する場合に有用です。

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

cube ( cube, float8, float8 ) → cube

Makes a new cube by adding a dimension on to an existing cube. This is useful for building cubes piece by piece from calculated values. 既存の立方体に次元を加えた立方体を新しく作成します。 これは計算した値で部品を追加しながら立方体を構築する場合に有用です。

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

cube_dim ( cube ) → integer

Returns the number of dimensions of the cube. 立方体の次元数を返します。

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

cube_ll_coord ( cube, integer ) → float8

Returns the <parameter>n</parameter>-th coordinate value for the lower left corner of the cube. 立方体の左下隅のn次座標の値を返します。

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

cube_ur_coord ( cube, integer ) → float8

Returns the <parameter>n</parameter>-th coordinate value for the upper right corner of the cube. 立方体の右上隅のn次座標の値を返します。

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

cube_is_point ( cube ) → boolean

Returns true if the cube is a point, that is, the two defining corners are the same. 立方体が点、つまり立方体が定義する2つの隅が同一の場合真を返します。

cube_is_point(cube(1,1))t

cube_distance ( cube, cube ) → float8

Returns the distance between two cubes. If both cubes are points, this is the normal distance function. 2つの立方体間の距離を返します。 両方の立方体が点の場合、これは通常の距離測定関数です。

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

cube_subset ( cube, integer[] ) → cube

Makes a new cube from an existing cube, using a list of dimension indexes from an array. Can be used to extract the endpoints of a single dimension, or to drop dimensions, or to reorder them as desired. 配列内の次元インデックスの一覧を使用して、既存の立方体から新しい立方体を作成します。 単一次元の端点を展開するために使用したり、次元を除去したり、希望通りの順序に並べ替えたりすることができます。

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

Produces the union of two cubes. 2つの立方体の和集合を作成します。

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

cube_inter ( cube, cube ) → cube

Produces the intersection of two cubes. 2つの立方体の共通部分を作成します。

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

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

Increases the size of the cube by the specified radius <parameter>r</parameter> in at least <parameter>n</parameter> dimensions. If the radius is negative the cube is shrunk instead. All defined dimensions are changed by the radius <parameter>r</parameter>. Lower-left coordinates are decreased by <parameter>r</parameter> and upper-right coordinates are increased by <parameter>r</parameter>. If a lower-left coordinate is increased to more than the corresponding upper-right coordinate (this can only happen when <parameter>r</parameter> &lt; 0) than both coordinates are set to their average. If <parameter>n</parameter> is greater than the number of defined dimensions and the cube is being enlarged (<parameter>r</parameter> &gt; 0), then extra dimensions are added to make <parameter>n</parameter> altogether; 0 is used as the initial value for the extra coordinates. This function is useful for creating bounding boxes around a point for searching for nearby points. 最小で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. デフォルト #

<title>Defaults</title>

This union:

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

does not contradict common sense, neither does the intersection: この和集合および以下の共通集合は一般常識と矛盾しません。

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

In all binary operations on differently-dimensioned cubes, the lower-dimensional one is assumed to be a Cartesian projection, i. e., having zeroes in place of coordinates omitted in the string representation. The above examples are equivalent to: 次元が異なる立方体の二項演算すべてにおいて、より低い次元の方がデカルト投影、つまり、文字列表現で省略された座標に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)');

The following containment predicate uses the point syntax, while in fact the second argument is internally represented by a box. This syntax makes it unnecessary to define a separate point type and functions for (box,point) predicates. 以下の包含の述部は点構文を使用しますが、実際内部的には第2引数は矩形として表されます。 この構文により、別の点用の型や(box,point)という述部用の関数を定義することが不要になります。

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

F.10.5. 注釈 #

<title>Notes</title>

For examples of usage, see the regression test <filename>sql/cube.sql</filename>. 使用例については、sql/cube.sqlリグレッションテストを参照してください。

To make it harder for people to break things, there is a limit of 100 on the number of dimensions of cubes. This is set in <filename>cubedata.h</filename> if you need something bigger. 破壊防止のために立方体の次元数に100までという制限を行いました。 これはcubedata.hで設定されており、必要に応じて多少大きくすることができます。

F.10.6. クレジット #

<title>Credits</title>

Original author: Gene Selkov, Jr. <email>selkovjr@mcs.anl.gov</email>, Mathematics and Computer Science Division, Argonne National Laboratory. 原作者: Gene Selkov, Jr. , Mathematics and Computer Science Division, Argonne National Laboratory.

My thanks are primarily to Prof. Joe Hellerstein (<ulink url="https://dsf.berkeley.edu/jmh/"></ulink>) for elucidating the gist of the GiST (<ulink url="http://gist.cs.berkeley.edu/"></ulink>), and to his former student Andy Dong for his example written for Illustra. I am also grateful to all Postgres developers, present and past, for enabling myself to create my own world and live undisturbed in it. And I would like to acknowledge my gratitude to Argonne Lab and to the U.S. Department of Energy for the years of faithful support of my database research. 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にも感謝します。

Minor updates to this package were made by Bruno Wolff III <email>bruno@wolff.to</email> in August/September of 2002. These include changing the precision from single precision to double precision and adding some new functions. 2002年8月/9月にBruno Wolff III による小規模な改修がこのパッケージになされました。 この改修には、単精度から倍精度への精度の変更といくつかの関数の追加が含まれます。

Additional updates were made by Joshua Reich <email>josh@root.net</email> in July 2006. These include <literal>cube(float8[], float8[])</literal> and cleaning up the code to use the V1 call protocol instead of the deprecated V0 protocol. 2006年7月にJoshua Reich による改修がさらになされました。 この改修にはcube(float8[], float8[])が含まれ、また、古いV0プロトコルからV1呼び出しプロトコルを使用するようコードが整理されました。