begriffs open source - ai-pg/blob - full-docs/txt/cube.txt

   1
   2 F.10. cube — a multi-dimensional cube data type #
   3
   4    F.10.1. Syntax
   5    F.10.2. Precision
   6    F.10.3. Usage
   7    F.10.4. Defaults
   8    F.10.5. Notes
   9    F.10.6. Credits
  10
  11    This module implements a data type cube for representing
  12    multidimensional cubes.
  13
  14    This module is considered “trusted”, that is, it can be installed by
  15    non-superusers who have CREATE privilege on the current database.
  16
  17 F.10.1. Syntax #
  18
  19    Table F.1 shows the valid external representations for the cube type.
  20    x, y, etc. denote floating-point numbers.
  21
  22    Table F.1. Cube External Representations
  23    External Syntax Meaning
  24    x A one-dimensional point (or, zero-length one-dimensional interval)
  25    (x) Same as above
  26    x1,x2,...,xn A point in n-dimensional space, represented internally as
  27    a zero-volume cube
  28    (x1,x2,...,xn) Same as above
  29    (x),(y) A one-dimensional interval starting at x and ending at y or
  30    vice versa; the order does not matter
  31    [(x),(y)] Same as above
  32    (x1,...,xn),(y1,...,yn) An n-dimensional cube represented by a pair of
  33    its diagonally opposite corners
  34    [(x1,...,xn),(y1,...,yn)] Same as above
  35
  36    It does not matter which order the opposite corners of a cube are
  37    entered in. The cube functions automatically swap values if needed to
  38    create a uniform “lower left — upper right” internal representation.
  39    When the corners coincide, cube stores only one corner along with an
  40    “is point” flag to avoid wasting space.
  41
  42    White space is ignored on input, so [(x),(y)] is the same as [ ( x ), (
  43    y ) ].
  44
  45 F.10.2. Precision #
  46
  47    Values are stored internally as 64-bit floating point numbers. This
  48    means that numbers with more than about 16 significant digits will be
  49    truncated.
  50
  51 F.10.3. Usage #
  52
  53    Table F.2 shows the specialized operators provided for type cube.
  54
  55    Table F.2. Cube Operators
  56
  57    Operator
  58
  59    Description
  60
  61    cube && cube → boolean
  62
  63    Do the cubes overlap?
  64
  65    cube @> cube → boolean
  66
  67    Does the first cube contain the second?
  68
  69    cube <@ cube → boolean
  70
  71    Is the first cube contained in the second?
  72
  73    cube -> integer → float8
  74
  75    Extracts the n-th coordinate of the cube (counting from 1).
  76
  77    cube ~> integer → float8
  78
  79    Extracts the n-th coordinate of the cube, counting in the following
  80    way: n = 2 * k - 1 means lower bound of k-th dimension, n = 2 * k means
  81    upper bound of k-th dimension. Negative n denotes the inverse value of
  82    the corresponding positive coordinate. This operator is designed for
  83    KNN-GiST support.
  84
  85    cube <-> cube → float8
  86
  87    Computes the Euclidean distance between the two cubes.
  88
  89    cube <#> cube → float8
  90
  91    Computes the taxicab (L-1 metric) distance between the two cubes.
  92
  93    cube <=> cube → float8
  94
  95    Computes the Chebyshev (L-inf metric) distance between the two cubes.
  96
  97    In addition to the above operators, the usual comparison operators
  98    shown in Table 9.1 are available for type cube. These operators first
  99    compare the first coordinates, and if those are equal, compare the
 100    second coordinates, etc. They exist mainly to support the b-tree index
 101    operator class for cube, which can be useful for example if you would
 102    like a UNIQUE constraint on a cube column. Otherwise, this ordering is
 103    not of much practical use.
 104
 105    The cube module also provides a GiST index operator class for cube
 106    values. A cube GiST index can be used to search for values using the =,
 107    &&, @>, and <@ operators in WHERE clauses.
 108
 109    In addition, a cube GiST index can be used to find nearest neighbors
 110    using the metric operators <->, <#>, and <=> in ORDER BY clauses. For
 111    example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5) could be
 112    found efficiently with:
 113 SELECT c FROM test ORDER BY c <-> cube(array[0.5,0.5,0.5]) LIMIT 1;
 114
 115    The ~> operator can also be used in this way to efficiently retrieve
 116    the first few values sorted by a selected coordinate. For example, to
 117    get the first few cubes ordered by the first coordinate (lower left
 118    corner) ascending one could use the following query:
 119 SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;
 120
 121    And to get 2-D cubes ordered by the first coordinate of the upper right
 122    corner descending:
 123 SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
 124
 125    Table F.3 shows the available functions.
 126
 127    Table F.3. Cube Functions
 128
 129    Function
 130
 131    Description
 132
 133    Example(s)
 134
 135    cube ( float8 ) → cube
 136
 137    Makes a one dimensional cube with both coordinates the same.
 138
 139    cube(1) → (1)
 140
 141    cube ( float8, float8 ) → cube
 142
 143    Makes a one dimensional cube.
 144
 145    cube(1, 2) → (1),(2)
 146
 147    cube ( float8[] ) → cube
 148
 149    Makes a zero-volume cube using the coordinates defined by the array.
 150
 151    cube(ARRAY[1,2,3]) → (1, 2, 3)
 152
 153    cube ( float8[], float8[] ) → cube
 154
 155    Makes a cube with upper right and lower left coordinates as defined by
 156    the two arrays, which must be of the same length.
 157
 158    cube(ARRAY[1,2], ARRAY[3,4]) → (1, 2),(3, 4)
 159
 160    cube ( cube, float8 ) → cube
 161
 162    Makes a new cube by adding a dimension on to an existing cube, with the
 163    same values for both endpoints of the new coordinate. This is useful
 164    for building cubes piece by piece from calculated values.
 165
 166    cube('(1,2),(3,4)'::cube, 5) → (1, 2, 5),(3, 4, 5)
 167
 168    cube ( cube, float8, float8 ) → cube
 169
 170    Makes a new cube by adding a dimension on to an existing cube. This is
 171    useful for building cubes piece by piece from calculated values.
 172
 173    cube('(1,2),(3,4)'::cube, 5, 6) → (1, 2, 5),(3, 4, 6)
 174
 175    cube_dim ( cube ) → integer
 176
 177    Returns the number of dimensions of the cube.
 178
 179    cube_dim('(1,2),(3,4)') → 2
 180
 181    cube_ll_coord ( cube, integer ) → float8
 182
 183    Returns the n-th coordinate value for the lower left corner of the
 184    cube.
 185
 186    cube_ll_coord('(1,2),(3,4)', 2) → 2
 187
 188    cube_ur_coord ( cube, integer ) → float8
 189
 190    Returns the n-th coordinate value for the upper right corner of the
 191    cube.
 192
 193    cube_ur_coord('(1,2),(3,4)', 2) → 4
 194
 195    cube_is_point ( cube ) → boolean
 196
 197    Returns true if the cube is a point, that is, the two defining corners
 198    are the same.
 199
 200    cube_is_point(cube(1,1)) → t
 201
 202    cube_distance ( cube, cube ) → float8
 203
 204    Returns the distance between two cubes. If both cubes are points, this
 205    is the normal distance function.
 206
 207    cube_distance('(1,2)', '(3,4)') → 2.8284271247461903
 208
 209    cube_subset ( cube, integer[] ) → cube
 210
 211    Makes a new cube from an existing cube, using a list of dimension
 212    indexes from an array. Can be used to extract the endpoints of a single
 213    dimension, or to drop dimensions, or to reorder them as desired.
 214
 215    cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) → (3),(7)
 216
 217    cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) → (5, 3, 1, 1),(8,
 218    7, 6, 6)
 219
 220    cube_union ( cube, cube ) → cube
 221
 222    Produces the union of two cubes.
 223
 224    cube_union('(1,2)', '(3,4)') → (1, 2),(3, 4)
 225
 226    cube_inter ( cube, cube ) → cube
 227
 228    Produces the intersection of two cubes.
 229
 230    cube_inter('(1,2)', '(3,4)') → (3, 4),(1, 2)
 231
 232    cube_enlarge ( c cube, r double, n integer ) → cube
 233
 234    Increases the size of the cube by the specified radius r in at least n
 235    dimensions. If the radius is negative the cube is shrunk instead. All
 236    defined dimensions are changed by the radius r. Lower-left coordinates
 237    are decreased by r and upper-right coordinates are increased by r. If a
 238    lower-left coordinate is increased to more than the corresponding
 239    upper-right coordinate (this can only happen when r < 0) than both
 240    coordinates are set to their average. If n is greater than the number
 241    of defined dimensions and the cube is being enlarged (r > 0), then
 242    extra dimensions are added to make n altogether; 0 is used as the
 243    initial value for the extra coordinates. This function is useful for
 244    creating bounding boxes around a point for searching for nearby points.
 245
 246    cube_enlarge('(1,2),(3,4)', 0.5, 3) → (0.5, 1.5, -0.5),(3.5, 4.5, 0.5)
 247
 248 F.10.4. Defaults #
 249
 250    This union:
 251 select cube_union('(0,5,2),(2,3,1)', '0');
 252 cube_union
 253 -------------------
 254 (0, 0, 0),(2, 5, 2)
 255 (1 row)
 256
 257    does not contradict common sense, neither does the intersection:
 258 select cube_inter('(0,-1),(1,1)', '(-2),(2)');
 259 cube_inter
 260 -------------
 261 (0, 0),(1, 0)
 262 (1 row)
 263
 264    In all binary operations on differently-dimensioned cubes, the
 265    lower-dimensional one is assumed to be a Cartesian projection, i. e.,
 266    having zeroes in place of coordinates omitted in the string
 267    representation. The above examples are equivalent to:
 268 cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
 269 cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');
 270
 271    The following containment predicate uses the point syntax, while in
 272    fact the second argument is internally represented by a box. This
 273    syntax makes it unnecessary to define a separate point type and
 274    functions for (box,point) predicates.
 275 select cube_contains('(0,0),(1,1)', '0.5,0.5');
 276 cube_contains
 277 --------------
 278 t
 279 (1 row)
 280
 281 F.10.5. Notes #
 282
 283    For examples of usage, see the regression test sql/cube.sql.
 284
 285    To make it harder for people to break things, there is a limit of 100
 286    on the number of dimensions of cubes. This is set in cubedata.h if you
 287    need something bigger.
 288
 289 F.10.6. Credits #
 290
 291    Original author: Gene Selkov, Jr. <selkovjr@mcs.anl.gov>, Mathematics
 292    and Computer Science Division, Argonne National Laboratory.
 293
 294    My thanks are primarily to Prof. Joe Hellerstein
 295    (https://dsf.berkeley.edu/jmh/) for elucidating the gist of the GiST
 296    (http://gist.cs.berkeley.edu/), and to his former student Andy Dong for
 297    his example written for Illustra. I am also grateful to all Postgres
 298    developers, present and past, for enabling myself to create my own
 299    world and live undisturbed in it. And I would like to acknowledge my
 300    gratitude to Argonne Lab and to the U.S. Department of Energy for the
 301    years of faithful support of my database research.
 302
 303    Minor updates to this package were made by Bruno Wolff III
 304    <bruno@wolff.to> in August/September of 2002. These include changing
 305    the precision from single precision to double precision and adding some
 306    new functions.
 307
 308    Additional updates were made by Joshua Reich <josh@root.net> in July
 309    2006. These include cube(float8[], float8[]) and cleaning up the code
 310    to use the V1 call protocol instead of the deprecated V0 protocol.