mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-01-24 18:55:04 +08:00
Minor hacking on contrib/cube documentation.
Improve markup, particularly of the table of functions; add or improve examples for some of the functions; wordsmith some of the function descriptions.
This commit is contained in:
Tom Lane
parent
efe4c9d704
commit
e5e5267a91
@ -25,6 +25,13 @@
|
||||
<table id="cube-repr-table">
|
||||
<title>Cube External Representations</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>External Syntax</entry>
|
||||
<entry>Meaning</entry>
|
||||
</row>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal><replaceable>x</></literal></entry>
|
||||
@ -80,7 +87,8 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
White space is ignored, so <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
|
||||
White space is ignored on input, so
|
||||
<literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
|
||||
<literal>[ ( <replaceable>x</> ), ( <replaceable>y</> ) ]</literal>.
|
||||
</para>
|
||||
</sect2>
|
||||
@ -98,11 +106,11 @@
|
||||
<title>Usage</title>
|
||||
|
||||
<para>
|
||||
<xref linkend="cube-operators"> shows the operators provided for type
|
||||
<type>cube</>.
|
||||
<xref linkend="cube-operators-table"> shows the operators provided for
|
||||
type <type>cube</>.
|
||||
</para>
|
||||
|
||||
<table id="cube-operators">
|
||||
<table id="cube-operators-table">
|
||||
<title>Cube Operators</title>
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
@ -240,9 +248,7 @@
|
||||
For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5)
|
||||
could be found efficiently with:
|
||||
<programlisting>
|
||||
SELECT c FROM test
|
||||
ORDER BY cube(array[0.5,0.5,0.5]) <-> c
|
||||
LIMIT 1;
|
||||
SELECT c FROM test ORDER BY c <-> cube(array[0.5,0.5,0.5]) LIMIT 1;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
@ -252,12 +258,12 @@ LIMIT 1;
|
||||
For example, to get the first few cubes ordered by the first coordinate
|
||||
(lower left corner) ascending one could use the following query:
|
||||
<programlisting>
|
||||
SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;
|
||||
SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;
|
||||
</programlisting>
|
||||
And to get 2-D cubes ordered by the first coordinate of the upper right
|
||||
corner descending:
|
||||
<programlisting>
|
||||
SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
|
||||
SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
@ -267,128 +273,191 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
|
||||
|
||||
<table id="cube-functions-table">
|
||||
<title>Cube Functions</title>
|
||||
<tgroup cols="2">
|
||||
<tgroup cols="4">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Function</entry>
|
||||
<entry>Result</entry>
|
||||
<entry>Description</entry>
|
||||
<entry>Example</entry>
|
||||
</row>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>cube(float8) returns cube</literal></entry>
|
||||
<entry><literal>cube(float8)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Makes a one dimensional cube with both coordinates the same.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube(1) == '(1)'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube(float8, float8) returns cube</literal></entry>
|
||||
<entry><literal>cube(float8, float8)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Makes a one dimensional cube.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube(1,2) == '(1),(2)'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube(float8[]) returns cube</literal></entry>
|
||||
<entry><literal>cube(float8[])</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Makes a zero-volume cube using the coordinates
|
||||
defined by the array.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube(ARRAY[1,2]) == '(1,2)'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube(float8[], float8[]) returns cube</literal></entry>
|
||||
<entry><literal>cube(float8[], float8[])</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Makes a cube with upper right and lower left
|
||||
coordinates as defined by the two arrays, which must be of the
|
||||
same length.
|
||||
<literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)'
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)'
|
||||
</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube(cube, float8) returns cube</literal></entry>
|
||||
<entry>Makes a new cube by adding a dimension on to an
|
||||
existing cube with the same values for both parts of the new coordinate.
|
||||
This is useful for building cubes piece by piece from calculated values.
|
||||
<literal>cube('(1)',2) == '(1,2),(1,2)'</literal>
|
||||
<entry><literal>cube(cube, float8)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>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.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube(cube, float8, float8) returns cube</literal></entry>
|
||||
<entry>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. <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal>
|
||||
<entry><literal>cube(cube, float8, float8)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>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.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_dim(cube) returns int</literal></entry>
|
||||
<entry>Returns the number of dimensions of the cube
|
||||
<entry><literal>cube_dim(cube)</literal></entry>
|
||||
<entry><type>integer</type></entry>
|
||||
<entry>Returns the number of dimensions of the cube.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube_dim('(1,2),(3,4)') == '2'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_ll_coord(cube, int) returns double </literal></entry>
|
||||
<entry>Returns the n'th coordinate value for the lower left
|
||||
corner of a cube
|
||||
<entry><literal>cube_ll_coord(cube, integer)</literal></entry>
|
||||
<entry><type>float8</type></entry>
|
||||
<entry>Returns the <replaceable>n</>-th coordinate value for the lower
|
||||
left corner of the cube.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube_ll_coord('(1,2),(3,4)', 2) == '2'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_ur_coord(cube, int) returns double
|
||||
</literal></entry>
|
||||
<entry>Returns the n'th coordinate value for the
|
||||
upper right corner of a cube
|
||||
<entry><literal>cube_ur_coord(cube, integer)</literal></entry>
|
||||
<entry><type>float8</type></entry>
|
||||
<entry>Returns the <replaceable>n</>-th coordinate value for the
|
||||
upper right corner of the cube.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube_ur_coord('(1,2),(3,4)', 2) == '4'</literal>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_is_point(cube) returns bool</literal></entry>
|
||||
<entry>Returns true if a cube is a point, that is,
|
||||
<entry><literal>cube_is_point(cube)</literal></entry>
|
||||
<entry><type>boolean</type></entry>
|
||||
<entry>Returns true if the cube is a point, that is,
|
||||
the two defining corners are the same.</entry>
|
||||
<entry>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_distance(cube, cube) returns double</literal></entry>
|
||||
<entry><literal>cube_distance(cube, cube)</literal></entry>
|
||||
<entry><type>float8</type></entry>
|
||||
<entry>Returns the distance between two cubes. If both
|
||||
cubes are points, this is the normal distance function.
|
||||
</entry>
|
||||
<entry>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_subset(cube, int[]) returns cube
|
||||
</literal></entry>
|
||||
<entry><literal>cube_subset(cube, integer[])</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Makes a new cube from an existing cube, using a list of
|
||||
dimension indexes from an array. Can be used to find both the LL and UR
|
||||
coordinates of a single dimension, e.g.
|
||||
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'</>.
|
||||
Or can be used to drop dimensions, or reorder them as desired, e.g.
|
||||
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3,
|
||||
1, 1),(8, 7, 6, 6)'</>.
|
||||
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.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)'</>
|
||||
<literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) ==
|
||||
'(5,3,1,1),(8,7,6,6)'</>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_union(cube, cube) returns cube</literal></entry>
|
||||
<entry>Produces the union of two cubes
|
||||
<entry><literal>cube_union(cube, cube)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Produces the union of two cubes.
|
||||
</entry>
|
||||
<entry>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_inter(cube, cube) returns cube</literal></entry>
|
||||
<entry>Produces the intersection of two cubes
|
||||
<entry><literal>cube_inter(cube, cube)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Produces the intersection of two cubes.
|
||||
</entry>
|
||||
<entry>
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry>
|
||||
<entry>Increases the size of a cube by a specified radius in at least
|
||||
n dimensions. If the radius is negative the cube is shrunk instead. This
|
||||
is useful for creating bounding boxes around a point for searching for
|
||||
nearby points. All defined dimensions are changed by the radius r.
|
||||
LL coordinates are decreased by r and UR coordinates are increased by r.
|
||||
If a LL coordinate is increased to larger than the corresponding UR
|
||||
coordinate (this can only happen when r < 0) than both coordinates
|
||||
are set to their average. If n is greater than the number of defined
|
||||
dimensions and the cube is being increased (r >= 0) then 0 is used
|
||||
as the base for the extra coordinates.
|
||||
<entry><literal>cube_enlarge(c cube, r double, n integer)</literal></entry>
|
||||
<entry><type>cube</type></entry>
|
||||
<entry>Increases the size of the cube by the specified
|
||||
radius <replaceable>r</> in at least <replaceable>n</> dimensions.
|
||||
If the radius is negative the cube is shrunk instead.
|
||||
All defined dimensions are changed by the radius <replaceable>r</>.
|
||||
Lower-left coordinates are decreased by <replaceable>r</> and
|
||||
upper-right coordinates are increased by <replaceable>r</>. If a
|
||||
lower-left coordinate is increased to more than the corresponding
|
||||
upper-right coordinate (this can only happen when <replaceable>r</>
|
||||
< 0) than both coordinates are set to their average.
|
||||
If <replaceable>n</> is greater than the number of defined dimensions
|
||||
and the cube is being enlarged (<replaceable>r</> > 0), then extra
|
||||
dimensions are added to make <replaceable>n</> 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.
|
||||
</entry>
|
||||
<entry>
|
||||
<literal>cube_enlarge('(1,2),(3,4)', 0.5, 3) ==
|
||||
'(0.5,1.5,-0.5),(3.5,4.5,0.5)'</>
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user