← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/cube.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/cube.sgml
 
1
<!-- doc/src/sgml/cube.sgml -->
 
2
 
 
3
<sect1 id="cube">
 
4
 <title>cube</title>
 
5
 
 
6
 <indexterm zone="cube">
 
7
  <primary>cube</primary>
 
8
 </indexterm>
 
9
 
 
10
 <para>
 
11
  This module implements a data type <type>cube</> for
 
12
  representing multidimensional cubes.
 
13
 </para>
 
14
 
 
15
 <sect2>
 
16
  <title>Syntax</title>
 
17
 
 
18
  <para>
 
19
   <xref linkend="cube-repr-table"> shows the valid external
 
20
   representations for the <type>cube</>
 
21
   type.  <replaceable>x</>, <replaceable>y</>, etc. denote
 
22
   floating-point numbers.
 
23
  </para>
 
24
 
 
25
  <table id="cube-repr-table">
 
26
   <title>Cube External Representations</title>
 
27
   <tgroup cols="2">
 
28
    <tbody>
 
29
     <row>
 
30
      <entry><literal><replaceable>x</></literal></entry>
 
31
      <entry>A one-dimensional point
 
32
       (or, zero-length one-dimensional interval)
 
33
      </entry>
 
34
     </row>
 
35
     <row>
 
36
      <entry><literal>(<replaceable>x</>)</literal></entry>
 
37
      <entry>Same as above</entry>
 
38
     </row>
 
39
     <row>
 
40
      <entry><literal><replaceable>x1</>,<replaceable>x2</>,...,<replaceable>xn</></literal></entry>
 
41
      <entry>A point in n-dimensional space, represented internally as a
 
42
      zero-volume cube
 
43
      </entry>
 
44
     </row>
 
45
     <row>
 
46
      <entry><literal>(<replaceable>x1</>,<replaceable>x2</>,...,<replaceable>xn</>)</literal></entry>
 
47
      <entry>Same as above</entry>
 
48
     </row>
 
49
     <row>
 
50
      <entry><literal>(<replaceable>x</>),(<replaceable>y</>)</literal></entry>
 
51
      <entry>A one-dimensional interval starting at <replaceable>x</> and ending at <replaceable>y</> or vice versa; the
 
52
       order does not matter
 
53
      </entry>
 
54
     </row>
 
55
     <row>
 
56
      <entry><literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal></entry>
 
57
      <entry>Same as above</entry>
 
58
     </row>
 
59
     <row>
 
60
      <entry><literal>(<replaceable>x1</>,...,<replaceable>xn</>),(<replaceable>y1</>,...,<replaceable>yn</>)</literal></entry>
 
61
      <entry>An n-dimensional cube represented by a pair of its diagonally
 
62
       opposite corners
 
63
      </entry>
 
64
     </row>
 
65
     <row>
 
66
      <entry><literal>[(<replaceable>x1</>,...,<replaceable>xn</>),(<replaceable>y1</>,...,<replaceable>yn</>)]</literal></entry>
 
67
      <entry>Same as above</entry>
 
68
     </row>
 
69
    </tbody>
 
70
   </tgroup>
 
71
  </table>
 
72
 
 
73
  <para>
 
74
   It does not matter which order the opposite corners of a cube are
 
75
   entered in.  The <type>cube</> functions
 
76
   automatically swap values if needed to create a uniform
 
77
   <quote>lower left &mdash; upper right</> internal representation.
 
78
  </para>
 
79
 
 
80
  <para>
 
81
   White space is ignored, so <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
 
82
   <literal>[ ( <replaceable>x</> ), ( <replaceable>y</> ) ]</literal>.
 
83
  </para>
 
84
 </sect2>
 
85
 
 
86
 <sect2>
 
87
  <title>Precision</title>
 
88
 
 
89
  <para>
 
90
   Values are stored internally as 64-bit floating point numbers. This means
 
91
   that numbers with more than about 16 significant digits will be truncated.
 
92
  </para>
 
93
 </sect2>
 
94
 
 
95
 <sect2>
 
96
  <title>Usage</title>
 
97
 
 
98
  <para>
 
99
   The <filename>cube</> module includes a GiST index operator class for
 
100
   <type>cube</> values.
 
101
   The operators supported by the GiST operator class are shown in <xref linkend="cube-gist-operators">.
 
102
  </para>
 
103
 
 
104
  <table id="cube-gist-operators">
 
105
   <title>Cube GiST Operators</title>
 
106
   <tgroup cols="2">
 
107
    <thead>
 
108
     <row>
 
109
      <entry>Operator</entry>
 
110
      <entry>Description</entry>
 
111
     </row>
 
112
    </thead>
 
113
 
 
114
    <tbody>
 
115
     <row>
 
116
      <entry><literal>a = b</></entry>
 
117
      <entry>The cubes a and b are identical.</entry>
 
118
     </row>
 
119
 
 
120
     <row>
 
121
      <entry><literal>a &amp;&amp; b</></entry>
 
122
      <entry>The cubes a and b overlap.</entry>
 
123
     </row>
 
124
 
 
125
     <row>
 
126
      <entry><literal>a @&gt; b</></entry>
 
127
      <entry>The cube a contains the cube b.</entry>
 
128
     </row>
 
129
 
 
130
     <row>
 
131
      <entry><literal>a &lt;@ b</></entry>
 
132
      <entry>The cube a is contained in the cube b.</entry>
 
133
     </row>
 
134
    </tbody>
 
135
   </tgroup>
 
136
  </table>
 
137
 
 
138
  <para>
 
139
   (Before PostgreSQL 8.2, the containment operators <literal>@&gt;</> and <literal>&lt;@</> were
 
140
   respectively called <literal>@</> and <literal>~</>.  These names are still available, but are
 
141
   deprecated and will eventually be retired.  Notice that the old names
 
142
   are reversed from the convention formerly followed by the core geometric
 
143
   data types!)
 
144
  </para>
 
145
 
 
146
  <para>
 
147
   The standard B-tree operators are also provided, for example
 
148
 
 
149
   <informaltable>
 
150
    <tgroup cols="2">
 
151
     <thead>
 
152
      <row>
 
153
       <entry>Operator</entry>
 
154
       <entry>Description</entry>
 
155
      </row>
 
156
     </thead>
 
157
 
 
158
     <tbody>
 
159
      <row>
 
160
       <entry><literal>[a, b] &lt; [c, d]</literal></entry>
 
161
       <entry>Less than</entry>
 
162
      </row>
 
163
 
 
164
      <row>
 
165
       <entry><literal>[a, b] &gt; [c, d]</literal></entry>
 
166
       <entry>Greater than</entry>
 
167
      </row>
 
168
     </tbody>
 
169
    </tgroup>
 
170
   </informaltable>
 
171
 
 
172
   These operators do not make a lot of sense for any practical
 
173
   purpose but sorting. These operators first compare (a) to (c),
 
174
   and if these are equal, compare (b) to (d). That results in
 
175
   reasonably good sorting in most cases, which is useful if
 
176
   you want to use ORDER BY with this type.
 
177
  </para>
 
178
 
 
179
  <para>
 
180
   <xref linkend="cube-functions-table"> shows the available functions.
 
181
  </para>
 
182
 
 
183
  <table id="cube-functions-table">
 
184
   <title>Cube Functions</title>
 
185
   <tgroup cols="2">
 
186
    <tbody>
 
187
     <row>
 
188
      <entry><literal>cube(float8) returns cube</literal></entry>
 
189
      <entry>Makes a one dimensional cube with both coordinates the same.
 
190
       <literal>cube(1) == '(1)'</literal>
 
191
      </entry>
 
192
     </row>
 
193
 
 
194
     <row>
 
195
      <entry><literal>cube(float8, float8) returns cube</literal></entry>
 
196
      <entry>Makes a one dimensional cube.
 
197
       <literal>cube(1,2) == '(1),(2)'</literal>
 
198
      </entry>
 
199
     </row>
 
200
 
 
201
     <row>
 
202
      <entry><literal>cube(float8[]) returns cube</literal></entry>
 
203
      <entry>Makes a zero-volume cube using the coordinates
 
204
       defined by the array.
 
205
       <literal>cube(ARRAY[1,2]) == '(1,2)'</literal>
 
206
      </entry>
 
207
     </row>
 
208
 
 
209
     <row>
 
210
      <entry><literal>cube(float8[], float8[]) returns cube</literal></entry>
 
211
      <entry>Makes a cube with upper right and lower left
 
212
       coordinates as defined by the two arrays, which must be of the
 
213
       same length.
 
214
       <literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)'
 
215
       </literal>
 
216
      </entry>
 
217
     </row>
 
218
 
 
219
     <row>
 
220
      <entry><literal>cube(cube, float8) returns cube</literal></entry>
 
221
      <entry>Makes a new cube by adding a dimension on to an
 
222
       existing cube with the same values for both parts of the new coordinate.
 
223
       This is useful for building cubes piece by piece from calculated values.
 
224
       <literal>cube('(1)',2) == '(1,2),(1,2)'</literal>
 
225
      </entry>
 
226
     </row>
 
227
 
 
228
     <row>
 
229
      <entry><literal>cube(cube, float8, float8) returns cube</literal></entry>
 
230
      <entry>Makes a new cube by adding a dimension on to an
 
231
       existing cube. This is useful for building cubes piece by piece from
 
232
       calculated values. <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal>
 
233
      </entry>
 
234
     </row>
 
235
 
 
236
     <row>
 
237
      <entry><literal>cube_dim(cube) returns int</literal></entry>
 
238
      <entry>Returns the number of dimensions of the cube
 
239
      </entry>
 
240
     </row>
 
241
 
 
242
     <row>
 
243
      <entry><literal>cube_ll_coord(cube, int) returns double </literal></entry>
 
244
      <entry>Returns the n'th coordinate value for the lower left
 
245
       corner of a cube
 
246
      </entry>
 
247
     </row>
 
248
 
 
249
    <row>
 
250
      <entry><literal>cube_ur_coord(cube, int) returns double
 
251
      </literal></entry>
 
252
      <entry>Returns the n'th coordinate value for the
 
253
       upper right corner of a cube
 
254
      </entry>
 
255
     </row>
 
256
 
 
257
     <row>
 
258
      <entry><literal>cube_is_point(cube) returns bool</literal></entry>
 
259
      <entry>Returns true if a cube is a point, that is,
 
260
       the two defining corners are the same.</entry>
 
261
     </row>
 
262
 
 
263
     <row>
 
264
      <entry><literal>cube_distance(cube, cube) returns double</literal></entry>
 
265
      <entry>Returns the distance between two cubes. If both
 
266
       cubes are points, this is the normal distance function.
 
267
      </entry>
 
268
     </row>
 
269
 
 
270
     <row>
 
271
      <entry><literal>cube_subset(cube, int[]) returns cube
 
272
      </literal></entry>
 
273
      <entry>Makes a new cube from an existing cube, using a list of
 
274
       dimension indexes from an array. Can be used to find both the LL and UR
 
275
       coordinates of a single dimension, e.g.
 
276
       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'</>.
 
277
       Or can be used to drop dimensions, or reorder them as desired, e.g.
 
278
       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3,
 
279
       1, 1),(8, 7, 6, 6)'</>.
 
280
      </entry>
 
281
     </row>
 
282
 
 
283
     <row>
 
284
      <entry><literal>cube_union(cube, cube) returns cube</literal></entry>
 
285
      <entry>Produces the union of two cubes
 
286
      </entry>
 
287
     </row>
 
288
 
 
289
     <row>
 
290
      <entry><literal>cube_inter(cube, cube) returns cube</literal></entry>
 
291
      <entry>Produces the intersection of two cubes
 
292
      </entry>
 
293
     </row>
 
294
 
 
295
     <row>
 
296
      <entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry>
 
297
      <entry>Increases the size of a cube by a specified radius in at least
 
298
       n dimensions. If the radius is negative the cube is shrunk instead. This
 
299
       is useful for creating bounding boxes around a point for searching for
 
300
       nearby points. All defined dimensions are changed by the radius r.
 
301
       LL coordinates are decreased by r and UR coordinates are increased by r.
 
302
       If a LL coordinate is increased to larger than the corresponding UR
 
303
       coordinate (this can only happen when r &lt; 0) than both coordinates
 
304
       are set to their average.  If n is greater than the number of defined
 
305
       dimensions and the cube is being increased (r &gt;= 0) then 0 is used
 
306
       as the base for the extra coordinates.
 
307
      </entry>
 
308
     </row>
 
309
    </tbody>
 
310
   </tgroup>
 
311
  </table>
 
312
 </sect2>
 
313
 
 
314
 <sect2>
 
315
  <title>Defaults</title>
 
316
 
 
317
  <para>
 
318
   I believe this union:
 
319
  </para>
 
320
<programlisting>
 
321
select cube_union('(0,5,2),(2,3,1)', '0');
 
322
cube_union
 
323
-------------------
 
324
(0, 0, 0),(2, 5, 2)
 
325
(1 row)
 
326
</programlisting>
 
327
 
 
328
   <para>
 
329
    does not contradict common sense, neither does the intersection
 
330
   </para>
 
331
 
 
332
<programlisting>
 
333
select cube_inter('(0,-1),(1,1)', '(-2),(2)');
 
334
cube_inter
 
335
-------------
 
336
(0, 0),(1, 0)
 
337
(1 row)
 
338
</programlisting>
 
339
 
 
340
   <para>
 
341
    In all binary operations on differently-dimensioned cubes, I assume the
 
342
    lower-dimensional one to be a Cartesian projection, i. e., having zeroes
 
343
    in place of coordinates omitted in the string representation. The above
 
344
    examples are equivalent to:
 
345
   </para>
 
346
 
 
347
<programlisting>
 
348
cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
 
349
cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');
 
350
</programlisting>
 
351
 
 
352
   <para>
 
353
    The following containment predicate uses the point syntax,
 
354
    while in fact the second argument is internally represented by a box.
 
355
    This syntax makes it unnecessary to define a separate point type
 
356
    and functions for (box,point) predicates.
 
357
   </para>
 
358
 
 
359
<programlisting>
 
360
select cube_contains('(0,0),(1,1)', '0.5,0.5');
 
361
cube_contains
 
362
--------------
 
363
t
 
364
(1 row)
 
365
</programlisting>
 
366
 </sect2>
 
367
 
 
368
 <sect2>
 
369
  <title>Notes</title>
 
370
 
 
371
  <para>
 
372
   For examples of usage, see the regression test <filename>sql/cube.sql</>.
 
373
  </para>
 
374
 
 
375
  <para>
 
376
   To make it harder for people to break things, there
 
377
   is a limit of 100 on the number of dimensions of cubes. This is set
 
378
   in <filename>cubedata.h</> if you need something bigger.
 
379
  </para>
 
380
 </sect2>
 
381
 
 
382
 <sect2>
 
383
  <title>Credits</title>
 
384
 
 
385
  <para>
 
386
   Original author: Gene Selkov, Jr. <email>selkovjr@mcs.anl.gov</email>,
 
387
   Mathematics and Computer Science Division, Argonne National Laboratory.
 
388
  </para>
 
389
 
 
390
  <para>
 
391
   My thanks are primarily to Prof. Joe Hellerstein
 
392
   (<ulink url="http://db.cs.berkeley.edu/jmh/"></ulink>) for elucidating the
 
393
   gist of the GiST (<ulink url="http://gist.cs.berkeley.edu/"></ulink>), and
 
394
   to his former student, Andy Dong (<ulink
 
395
   url="http://best.me.berkeley.edu/~adong/"></ulink>), for his example
 
396
   written for Illustra,
 
397
   <ulink url="http://best.berkeley.edu/~adong/rtree/index.html"></ulink>.
 
398
   I am also grateful to all Postgres developers, present and past, for
 
399
   enabling myself to create my own world and live undisturbed in it. And I
 
400
   would like to acknowledge my gratitude to Argonne Lab and to the
 
401
   U.S. Department of Energy for the years of faithful support of my database
 
402
   research.
 
403
  </para>
 
404
 
 
405
  <para>
 
406
   Minor updates to this package were made by Bruno Wolff III
 
407
   <email>bruno@wolff.to</email> in August/September of 2002. These include
 
408
   changing the precision from single precision to double precision and adding
 
409
   some new functions.
 
410
  </para>
 
411
 
 
412
  <para>
 
413
   Additional updates were made by Joshua Reich <email>josh@root.net</email> in
 
414
   July 2006. These include <literal>cube(float8[], float8[])</literal> and
 
415
   cleaning up the code to use the V1 call protocol instead of the deprecated
 
416
   V0 protocol.
 
417
  </para>
 
418
 </sect2>
 
419
 
 
420
</sect1>