<table id="functions-adminpack-table">
<title><filename>adminpack</filename> Functions</title>
- <tgroup cols="3">
- <thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>pg_catalog.pg_file_write(filename text, data text, append boolean)</function></entry>
- <entry><type>bigint</type></entry>
- <entry>
- Write, or append to, a text file
- </entry>
- </row>
- <row>
- <entry><function>pg_catalog.pg_file_sync(filename text)</function></entry>
- <entry><type>void</type></entry>
- <entry>
- Flush a file or directory to disk
- </entry>
- </row>
- <row>
- <entry><function>pg_catalog.pg_file_rename(oldname text, newname text <optional>, archivename text</optional>)</function></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Rename a file
- </entry>
- </row>
- <row>
- <entry><function>pg_catalog.pg_file_unlink(filename text)</function></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Remove a file
- </entry>
- </row>
- <row>
- <entry><function>pg_catalog.pg_logdir_ls()</function></entry>
- <entry><type>setof record</type></entry>
- <entry>
- List the log files in the <varname>log_directory</varname> directory
- </entry>
- </row>
- </tbody>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_catalog.pg_file_write</function> ( <parameter>filename</parameter> <type>text</type>, <parameter>data</parameter> <type>text</type>, <parameter>append</parameter> <type>boolean</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Writes, or appends to, a text file.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_catalog.pg_file_sync</function> ( <parameter>filename</parameter> <type>text</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Flushes a file or directory to disk.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_catalog.pg_file_rename</function> ( <parameter>oldname</parameter> <type>text</type>, <parameter>newname</parameter> <type>text</type> <optional>, <parameter>archivename</parameter> <type>text</type> </optional> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Renames a file.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_catalog.pg_file_unlink</function> ( <parameter>filename</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Removes a file.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_catalog.pg_logdir_ls</function> ()
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Lists the log files in the <varname>log_directory</varname> directory.
+ </para></entry>
+ </row>
+ </tbody>
</tgroup>
</table>
<title>Usage</title>
<para>
- <xref linkend="cube-operators-table"/> shows the operators provided for
- type <type>cube</type>.
+ <xref linkend="cube-operators-table"/> shows the specialized operators
+ provided for type <type>cube</type>.
</para>
<table id="cube-operators-table">
<title>Cube Operators</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Result</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>a = b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cubes a and b are identical.</entry>
- </row>
-
- <row>
- <entry><literal>a && b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cubes a and b overlap.</entry>
- </row>
-
- <row>
- <entry><literal>a @> b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a contains the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a <@ b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is contained in the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a < b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is less than the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a <= b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is less than or equal to the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a > b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is greater than the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a >= b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is greater than or equal to the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a <> b</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>The cube a is not equal to the cube b.</entry>
- </row>
-
- <row>
- <entry><literal>a -> n</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Get <replaceable>n</replaceable>-th coordinate of cube (counting from 1).</entry>
- </row>
-
- <row>
- <entry><literal>a ~> n</literal></entry>
- <entry><type>float8</type></entry>
- <entry>
- Get <replaceable>n</replaceable>-th coordinate of cube in following way:
- n = 2 * k - 1 means lower bound of <replaceable>k</replaceable>-th
- dimension, n = 2 * k means upper bound of
- <replaceable>k</replaceable>-th dimension. Negative
- <replaceable>n</replaceable> denotes the inverse value of the corresponding
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal>&&</literal> <type>cube</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Do the cubes overlap?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal>@></literal> <type>cube</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does the first cube contain the second?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal><@</literal> <type>cube</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is the first cube contained in the second?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal>-></literal> <type>integer</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Extracts the <parameter>n</parameter>-th coordinate of the cube
+ (counting from 1).
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal>~></literal> <type>integer</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ 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.
- </entry>
- </row>
-
- <row>
- <entry><literal>a <-> b</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Euclidean distance between a and b.</entry>
- </row>
-
- <row>
- <entry><literal>a <#> b</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Taxicab (L-1 metric) distance between a and b.</entry>
- </row>
-
- <row>
- <entry><literal>a <=> b</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Chebyshev (L-inf metric) distance between a and b.</entry>
- </row>
-
- </tbody>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal><-></literal> <type>cube</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Computes the Euclidean distance between the two cubes.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal><#></literal> <type>cube</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Computes the taxicab (L-1 metric) distance between the two cubes.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>cube</type> <literal><=></literal> <type>cube</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Computes the Chebyshev (L-inf metric) distance between the two cubes.
+ </para></entry>
+ </row>
+ </tbody>
</tgroup>
</table>
</para>
<para>
- The scalar ordering operators (<literal><</literal>, <literal>>=</literal>, etc)
- do not make a lot of sense for any practical purpose but sorting. These
+ 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.
</para>
<para>
<table id="cube-functions-table">
<title>Cube Functions</title>
- <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)</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)</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[])</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[])</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.
- </entry>
- <entry>
- <literal>cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)'
- </literal>
- </entry>
- </row>
-
- <row>
- <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)</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)</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, integer)</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the <replaceable>n</replaceable>-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, integer)</literal></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the <replaceable>n</replaceable>-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)</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)</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, 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 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>
- <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) ==
- '(5,3,1,1),(8,7,6,6)'</literal>
- </entry>
- </row>
-
- <row>
- <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)</literal></entry>
- <entry><type>cube</type></entry>
- <entry>Produces the intersection of two cubes.
- </entry>
- <entry>
- </entry>
- </row>
-
- <row>
- <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</replaceable> in at least <replaceable>n</replaceable> dimensions.
- If the radius is negative the cube is shrunk instead.
- All defined dimensions are changed by the radius <replaceable>r</replaceable>.
- Lower-left coordinates are decreased by <replaceable>r</replaceable> and
- upper-right coordinates are increased by <replaceable>r</replaceable>. If a
- lower-left coordinate is increased to more than the corresponding
- upper-right coordinate (this can only happen when <replaceable>r</replaceable>
- < 0) than both coordinates are set to their average.
- If <replaceable>n</replaceable> is greater than the number of defined dimensions
- and the cube is being enlarged (<replaceable>r</replaceable> > 0), then extra
- dimensions are added to make <replaceable>n</replaceable> 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)'</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>float8</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Makes a one dimensional cube with both coordinates the same.
+ </para>
+ <para>
+ <literal>cube(1)</literal>
+ <returnvalue>(1)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>float8</type>, <type>float8</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Makes a one dimensional cube.
+ </para>
+ <para>
+ <literal>cube(1,2)</literal>
+ <returnvalue>(1),(2)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>float8[]</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Makes a zero-volume cube using the coordinates defined by the array.
+ </para>
+ <para>
+ <literal>cube(ARRAY[1,2,3])</literal>
+ <returnvalue>(1, 2, 3)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>float8[]</type>, <type>float8[]</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Makes a cube with upper right and lower left coordinates as defined by
+ the two arrays, which must be of the same length.
+ </para>
+ <para>
+ <literal>cube(ARRAY[1,2], ARRAY[3,4])</literal>
+ <returnvalue>(1, 2),(3, 4)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>cube</type>, <type>float8</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ <literal>cube('(1,2),(3,4)'::cube, 5)</literal>
+ <returnvalue>(1, 2, 5),(3, 4, 5)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube</function> ( <type>cube</type>, <type>float8</type>, <type>float8</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ <literal>cube('(1,2),(3,4)'::cube, 5, 6)</literal>
+ <returnvalue>(1, 2, 5),(3, 4, 6)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_dim</function> ( <type>cube</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the number of dimensions of the cube.
+ </para>
+ <para>
+ <literal>cube_dim('(1,2),(3,4)')</literal>
+ <returnvalue>2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_ll_coord</function> ( <type>cube</type>, <type>integer</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the <parameter>n</parameter>-th coordinate value for the lower
+ left corner of the cube.
+ </para>
+ <para>
+ <literal>cube_ll_coord('(1,2),(3,4)', 2)</literal>
+ <returnvalue>2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_ur_coord</function> ( <type>cube</type>, <type>integer</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the <parameter>n</parameter>-th coordinate value for the
+ upper right corner of the cube.
+ </para>
+ <para>
+ <literal>cube_ur_coord('(1,2),(3,4)', 2)</literal>
+ <returnvalue>4</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_is_point</function> ( <type>cube</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if the cube is a point, that is,
+ the two defining corners are the same.
+ </para>
+ <para>
+ <literal>cube_is_point(cube(1,1))</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_distance</function> ( <type>cube</type>, <type>cube</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the distance between two cubes. If both
+ cubes are points, this is the normal distance function.
+ </para>
+ <para>
+ <literal>cube_distance('(1,2)', '(3,4)')</literal>
+ <returnvalue>2.8284271247461903</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_subset</function> ( <type>cube</type>, <type>integer[]</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2])</literal>
+ <returnvalue>(3),(7)</returnvalue>
+ </para>
+ <para>
+ <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1])</literal>
+ <returnvalue>(5, 3, 1, 1),(8, 7, 6, 6)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_union</function> ( <type>cube</type>, <type>cube</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Produces the union of two cubes.
+ </para>
+ <para>
+ <literal>cube_union('(1,2)', '(3,4)')</literal>
+ <returnvalue>(1, 2),(3, 4)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_inter</function> ( <type>cube</type>, <type>cube</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Produces the intersection of two cubes.
+ </para>
+ <para>
+ <literal>cube_inter('(1,2)', '(3,4)')</literal>
+ <returnvalue>(3, 4),(1, 2)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>cube_enlarge</function> ( <parameter>c</parameter> <type>cube</type>, <parameter>r</parameter> <type>double</type>, <parameter>n</parameter> <type>integer</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ 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> < 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> > 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.
+ </para>
+ <para>
+ <literal>cube_enlarge('(1,2),(3,4)', 0.5, 3)</literal>
+ <returnvalue>(0.5, 1.5, -0.5),(3.5, 4.5, 0.5)</returnvalue>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
<table id="earthdistance-cube-functions">
<title>Cube-Based Earthdistance Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><function>earth()</function><indexterm><primary>earth</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the assumed radius of the Earth.</entry>
- </row>
- <row>
- <entry><function>sec_to_gc(float8)</function><indexterm><primary>sec_to_gc</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Converts the normal straight line
- (secant) distance between two points on the surface of the Earth
- to the great circle distance between them.
- </entry>
- </row>
- <row>
- <entry><function>gc_to_sec(float8)</function><indexterm><primary>gc_to_sec</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Converts the great circle distance between two points on the
- surface of the Earth to the normal straight line (secant) distance
- between them.
- </entry>
- </row>
- <row>
- <entry><function>ll_to_earth(float8, float8)</function><indexterm><primary>ll_to_earth</primary></indexterm></entry>
- <entry><type>earth</type></entry>
- <entry>Returns the location of a point on the surface of the Earth given
- its latitude (argument 1) and longitude (argument 2) in degrees.
- </entry>
- </row>
- <row>
- <entry><function>latitude(earth)</function><indexterm><primary>latitude</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the latitude in degrees of a point on the surface of the
- Earth.
- </entry>
- </row>
- <row>
- <entry><function>longitude(earth)</function><indexterm><primary>longitude</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the longitude in degrees of a point on the surface of the
- Earth.
- </entry>
- </row>
- <row>
- <entry><function>earth_distance(earth, earth)</function><indexterm><primary>earth_distance</primary></indexterm></entry>
- <entry><type>float8</type></entry>
- <entry>Returns the great circle distance between two points on the
- surface of the Earth.
- </entry>
- </row>
- <row>
- <entry><function>earth_box(earth, float8)</function><indexterm><primary>earth_box</primary></indexterm></entry>
- <entry><type>cube</type></entry>
- <entry>Returns a box suitable for an indexed search using the cube
- <literal>@></literal>
- operator for points within a given great circle distance of a location.
- Some points in this box are further than the specified great circle
- distance from the location, so a second check using
- <function>earth_distance</function> should be included in the query.
- </entry>
- </row>
- </tbody>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>earth</primary></indexterm>
+ <function>earth</function> ()
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the assumed radius of the Earth.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>sec_to_gc</primary></indexterm>
+ <function>sec_to_gc</function> ( <type>float8</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Converts the normal straight line
+ (secant) distance between two points on the surface of the Earth
+ to the great circle distance between them.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>gc_to_sec</primary></indexterm>
+ <function>gc_to_sec</function> ( <type>float8</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Converts the great circle distance between two points on the
+ surface of the Earth to the normal straight line (secant) distance
+ between them.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>ll_to_earth</primary></indexterm>
+ <function>ll_to_earth</function> ( <type>float8</type>, <type>float8</type> )
+ <returnvalue>earth</returnvalue>
+ </para>
+ <para>
+ Returns the location of a point on the surface of the Earth given
+ its latitude (argument 1) and longitude (argument 2) in degrees.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>latitude</primary></indexterm>
+ <function>latitude</function> ( <type>earth</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the latitude in degrees of a point on the surface of the
+ Earth.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>longitude</primary></indexterm>
+ <function>longitude</function> ( <type>earth</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the longitude in degrees of a point on the surface of the
+ Earth.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>earth_distance</primary></indexterm>
+ <function>earth_distance</function> ( <type>earth</type>, <type>earth</type> )
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Returns the great circle distance between two points on the
+ surface of the Earth.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>earth_box</primary></indexterm>
+ <function>earth_box</function> ( <type>earth</type>, <type>float8</type> )
+ <returnvalue>cube</returnvalue>
+ </para>
+ <para>
+ Returns a box suitable for an indexed search using the <type>cube</type>
+ <literal>@></literal>
+ operator for points within a given great circle distance of a location.
+ Some points in this box are further than the specified great circle
+ distance from the location, so a second check using
+ <function>earth_distance</function> should be included in the query.
+ </para></entry>
+ </row>
+ </tbody>
</tgroup>
</table>
<table id="earthdistance-point-operators">
<title>Point-Based Earthdistance Operators</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><type>point</type> <literal><@></literal> <type>point</type></entry>
- <entry><type>float8</type></entry>
- <entry>Gives the distance in statute miles between
- two points on the Earth's surface.
- </entry>
- </row>
- </tbody>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>point</type> <literal><@></literal> <type>point</type>
+ <returnvalue>float8</returnvalue>
+ </para>
+ <para>
+ Computes the distance in statute miles between
+ two points on the Earth's surface.
+ </para></entry>
+ </row>
+ </tbody>
</tgroup>
</table>
<table id="hstore-op-table">
<title><type>hstore</type> Operators</title>
-
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><type>hstore</type> <literal>-></literal> <type>text</type></entry>
- <entry>get value for key (<literal>NULL</literal> if not present)</entry>
- <entry><literal>'a=>x, b=>y'::hstore -> 'a'</literal></entry>
- <entry><literal>x</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>-></literal> <type>text[]</type></entry>
- <entry>get values for keys (<literal>NULL</literal> if not present)</entry>
- <entry><literal>'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']</literal></entry>
- <entry><literal>{"z","x"}</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>||</literal> <type>hstore</type></entry>
- <entry>concatenate <type>hstore</type>s</entry>
- <entry><literal>'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore</literal></entry>
- <entry><literal>"a"=>"b", "c"=>"x", "d"=>"q"</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>?</literal> <type>text</type></entry>
- <entry>does <type>hstore</type> contain key?</entry>
- <entry><literal>'a=>1'::hstore ? 'a'</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>?&</literal> <type>text[]</type></entry>
- <entry>does <type>hstore</type> contain all specified keys?</entry>
- <entry><literal>'a=>1,b=>2'::hstore ?& ARRAY['a','b']</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>?|</literal> <type>text[]</type></entry>
- <entry>does <type>hstore</type> contain any of the specified keys?</entry>
- <entry><literal>'a=>1,b=>2'::hstore ?| ARRAY['b','c']</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>@></literal> <type>hstore</type></entry>
- <entry>does left operand contain right?</entry>
- <entry><literal>'a=>b, b=>1, c=>NULL'::hstore @> 'b=>1'</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal><@</literal> <type>hstore</type></entry>
- <entry>is left operand contained in right?</entry>
- <entry><literal>'a=>c'::hstore <@ 'a=>b, b=>1, c=>NULL'</literal></entry>
- <entry><literal>f</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>-</literal> <type>text</type></entry>
- <entry>delete key from left operand</entry>
- <entry><literal>'a=>1, b=>2, c=>3'::hstore - 'b'::text</literal></entry>
- <entry><literal>"a"=>"1", "c"=>"3"</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>-</literal> <type>text[]</type></entry>
- <entry>delete keys from left operand</entry>
- <entry><literal>'a=>1, b=>2, c=>3'::hstore - ARRAY['a','b']</literal></entry>
- <entry><literal>"c"=>"3"</literal></entry>
- </row>
-
- <row>
- <entry><type>hstore</type> <literal>-</literal> <type>hstore</type></entry>
- <entry>delete matching pairs from left operand</entry>
- <entry><literal>'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore</literal></entry>
- <entry><literal>"a"=>"1", "c"=>"3"</literal></entry>
- </row>
-
- <row>
- <entry><type>record</type> <literal>#=</literal> <type>hstore</type></entry>
- <entry>replace fields in <type>record</type> with matching values from <type>hstore</type></entry>
- <entry>see Examples section</entry>
- <entry></entry>
- </row>
-
- <row>
- <entry><literal>%%</literal> <type>hstore</type></entry>
- <entry>convert <type>hstore</type> to array of alternating keys and values</entry>
- <entry><literal>%% 'a=>foo, b=>bar'::hstore</literal></entry>
- <entry><literal>{a,foo,b,bar}</literal></entry>
- </row>
-
- <row>
- <entry><literal>%#</literal> <type>hstore</type></entry>
- <entry>convert <type>hstore</type> to two-dimensional key/value array</entry>
- <entry><literal>%# 'a=>foo, b=>bar'::hstore</literal></entry>
- <entry><literal>{{a,foo},{b,bar}}</literal></entry>
- </row>
-
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>-></literal> <type>text</type>
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns value associated with given key, or <literal>NULL</literal> if
+ not present.
+ </para>
+ <para>
+ <literal>'a=>x, b=>y'::hstore -> 'a'</literal>
+ <returnvalue>x</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>-></literal> <type>text[]</type>
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Returns values associated with given keys, or <literal>NULL</literal>
+ if not present.
+ </para>
+ <para>
+ <literal>'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']</literal>
+ <returnvalue>{"z","x"}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>||</literal> <type>hstore</type>
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Concatenates two <type>hstore</type>s.
+ </para>
+ <para>
+ <literal>'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore</literal>
+ <returnvalue>"a"=>"b", "c"=>"x", "d"=>"q"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>?</literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>hstore</type> contain key?
+ </para>
+ <para>
+ <literal>'a=>1'::hstore ? 'a'</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>?&</literal> <type>text[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>hstore</type> contain all the specified keys?
+ </para>
+ <para>
+ <literal>'a=>1,b=>2'::hstore ?& ARRAY['a','b']</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>?|</literal> <type>text[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>hstore</type> contain any of the specified keys?
+ </para>
+ <para>
+ <literal>'a=>1,b=>2'::hstore ?| ARRAY['b','c']</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>@></literal> <type>hstore</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does left operand contain right?
+ </para>
+ <para>
+ <literal>'a=>b, b=>1, c=>NULL'::hstore @> 'b=>1'</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal><@</literal> <type>hstore</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is left operand contained in right?
+ </para>
+ <para>
+ <literal>'a=>c'::hstore <@ 'a=>b, b=>1, c=>NULL'</literal>
+ <returnvalue>f</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>-</literal> <type>text</type>
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes key from left operand.
+ </para>
+ <para>
+ <literal>'a=>1, b=>2, c=>3'::hstore - 'b'::text</literal>
+ <returnvalue>"a"=>"1", "c"=>"3"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>-</literal> <type>text[]</type>
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes keys from left operand.
+ </para>
+ <para>
+ <literal>'a=>1, b=>2, c=>3'::hstore - ARRAY['a','b']</literal>
+ <returnvalue>"c"=>"3"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>hstore</type> <literal>-</literal> <type>hstore</type>
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes pairs from left operand that match pairs in the right operand.
+ </para>
+ <para>
+ <literal>'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore</literal>
+ <returnvalue>"a"=>"1", "c"=>"3"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>anyelement</type> <literal>#=</literal> <type>hstore</type>
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Replaces fields in the left operand (which must be a composite type)
+ with matching values from <type>hstore</type>.
+ </para>
+ <para>
+ <literal>ROW(1,3) #= 'f1=>11'::hstore</literal>
+ <returnvalue>(11,3)</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <literal>%%</literal> <type>hstore</type>
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Converts <type>hstore</type> to an array of alternating keys and
+ values.
+ </para>
+ <para>
+ <literal>%% 'a=>foo, b=>bar'::hstore</literal>
+ <returnvalue>{a,foo,b,bar}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <literal>%#</literal> <type>hstore</type>
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Converts <type>hstore</type> to a two-dimensional key/value array.
+ </para>
+ <para>
+ <literal>%# 'a=>foo, b=>bar'::hstore</literal>
+ <returnvalue>{{a,foo},{b,bar}}</returnvalue>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<note>
<table id="hstore-func-table">
<title><type>hstore</type> Functions</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>hstore(record)</function><indexterm><primary>hstore</primary></indexterm></entry>
- <entry><type>hstore</type></entry>
- <entry>construct an <type>hstore</type> from a record or row</entry>
- <entry><literal>hstore(ROW(1,2))</literal></entry>
- <entry><literal>f1=>1,f2=>2</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore(text[])</function></entry>
- <entry><type>hstore</type></entry>
- <entry>construct an <type>hstore</type> from an array, which may be either
- a key/value array, or a two-dimensional array</entry>
- <entry><literal>hstore(ARRAY['a','1','b','2']) || hstore(ARRAY[['c','3'],['d','4']])</literal></entry>
- <entry><literal>a=>1, b=>2, c=>3, d=>4</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore(text[], text[])</function></entry>
- <entry><type>hstore</type></entry>
- <entry>construct an <type>hstore</type> from separate key and value arrays</entry>
- <entry><literal>hstore(ARRAY['a','b'], ARRAY['1','2'])</literal></entry>
- <entry><literal>"a"=>"1","b"=>"2"</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore(text, text)</function></entry>
- <entry><type>hstore</type></entry>
- <entry>make single-item <type>hstore</type></entry>
- <entry><literal>hstore('a', 'b')</literal></entry>
- <entry><literal>"a"=>"b"</literal></entry>
- </row>
-
- <row>
- <entry><function>akeys(hstore)</function><indexterm><primary>akeys</primary></indexterm></entry>
- <entry><type>text[]</type></entry>
- <entry>get <type>hstore</type>'s keys as an array</entry>
- <entry><literal>akeys('a=>1,b=>2')</literal></entry>
- <entry><literal>{a,b}</literal></entry>
- </row>
-
- <row>
- <entry><function>skeys(hstore)</function><indexterm><primary>skeys</primary></indexterm></entry>
- <entry><type>setof text</type></entry>
- <entry>get <type>hstore</type>'s keys as a set</entry>
- <entry><literal>skeys('a=>1,b=>2')</literal></entry>
- <entry>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore</primary></indexterm>
+ <function>hstore</function> ( <type>record</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Constructs an <type>hstore</type> from a record or row.
+ </para>
+ <para>
+ <literal>hstore(ROW(1,2))</literal>
+ <returnvalue>"f1"=>"1", "f2"=>"2"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hstore</function> ( <type>text[]</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Constructs an <type>hstore</type> from an array, which may be either
+ a key/value array, or a two-dimensional array.
+ </para>
+ <para>
+ <literal>hstore(ARRAY['a','1','b','2'])</literal>
+ <returnvalue>"a"=>"1", "b"=>"2"</returnvalue>
+ </para>
+ <para>
+ <literal>hstore(ARRAY[['c','3'],['d','4']])</literal>
+ <returnvalue>"c"=>"3", "d"=>"4"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hstore</function> ( <type>text[]</type>, <type>text[]</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Constructs an <type>hstore</type> from separate key and value arrays.
+ </para>
+ <para>
+ <literal>hstore(ARRAY['a','b'], ARRAY['1','2'])</literal>
+ <returnvalue>"a"=>"1", "b"=>"2"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hstore</function> ( <type>text</type>, <type>text</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Makes a single-item <type>hstore</type>.
+ </para>
+ <para>
+ <literal>hstore('a', 'b')</literal>
+ <returnvalue>"a"=>"b"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>akeys</primary></indexterm>
+ <function>akeys</function> ( <type>hstore</type> )
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s keys as an array.
+ </para>
+ <para>
+ <literal>akeys('a=>1,b=>2')</literal>
+ <returnvalue>{a,b}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>skeys</primary></indexterm>
+ <function>skeys</function> ( <type>hstore</type> )
+ <returnvalue>setof text</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s keys as a set.
+ </para>
+ <para>
+ <literal>skeys('a=>1,b=>2')</literal>
+ <returnvalue></returnvalue>
<programlisting>
a
b
-</programlisting></entry>
- </row>
-
- <row>
- <entry><function>avals(hstore)</function><indexterm><primary>avals</primary></indexterm></entry>
- <entry><type>text[]</type></entry>
- <entry>get <type>hstore</type>'s values as an array</entry>
- <entry><literal>avals('a=>1,b=>2')</literal></entry>
- <entry><literal>{1,2}</literal></entry>
- </row>
-
- <row>
- <entry><function>svals(hstore)</function><indexterm><primary>svals</primary></indexterm></entry>
- <entry><type>setof text</type></entry>
- <entry>get <type>hstore</type>'s values as a set</entry>
- <entry><literal>svals('a=>1,b=>2')</literal></entry>
- <entry>
+</programlisting>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>avals</primary></indexterm>
+ <function>avals</function> ( <type>hstore</type> )
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s values as an array.
+ </para>
+ <para>
+ <literal>avals('a=>1,b=>2')</literal>
+ <returnvalue>{1,2}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>svals</primary></indexterm>
+ <function>svals</function> ( <type>hstore</type> )
+ <returnvalue>setof text</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s values as a set.
+ </para>
+ <para>
+ <literal>svals('a=>1,b=>2')</literal>
+ <returnvalue></returnvalue>
<programlisting>
1
2
-</programlisting></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_array(hstore)</function><indexterm><primary>hstore_to_array</primary></indexterm></entry>
- <entry><type>text[]</type></entry>
- <entry>get <type>hstore</type>'s keys and values as an array of alternating
- keys and values</entry>
- <entry><literal>hstore_to_array('a=>1,b=>2')</literal></entry>
- <entry><literal>{a,1,b,2}</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_matrix(hstore)</function><indexterm><primary>hstore_to_matrix</primary></indexterm></entry>
- <entry><type>text[]</type></entry>
- <entry>get <type>hstore</type>'s keys and values as a two-dimensional array</entry>
- <entry><literal>hstore_to_matrix('a=>1,b=>2')</literal></entry>
- <entry><literal>{{a,1},{b,2}}</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_json(hstore)</function><indexterm><primary>hstore_to_json</primary></indexterm></entry>
- <entry><type>json</type></entry>
- <entry>get <type>hstore</type> as a <type>json</type> value, converting
- all non-null values to JSON strings</entry>
- <entry><literal>hstore_to_json('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal></entry>
- <entry><literal>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_jsonb(hstore)</function><indexterm><primary>hstore_to_jsonb</primary></indexterm></entry>
- <entry><type>jsonb</type></entry>
- <entry>get <type>hstore</type> as a <type>jsonb</type> value, converting
- all non-null values to JSON strings</entry>
- <entry><literal>hstore_to_jsonb('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal></entry>
- <entry><literal>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_json_loose(hstore)</function><indexterm><primary>hstore_to_json_loose</primary></indexterm></entry>
- <entry><type>json</type></entry>
- <entry>get <type>hstore</type> as a <type>json</type> value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON</entry>
- <entry><literal>hstore_to_json_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal></entry>
- <entry><literal>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</literal></entry>
- </row>
-
- <row>
- <entry><function>hstore_to_jsonb_loose(hstore)</function><indexterm><primary>hstore_to_jsonb_loose</primary></indexterm></entry>
- <entry><type>jsonb</type></entry>
- <entry>get <type>hstore</type> as a <type>jsonb</type> value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON</entry>
- <entry><literal>hstore_to_jsonb_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal></entry>
- <entry><literal>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</literal></entry>
- </row>
-
- <row>
- <entry><function>slice(hstore, text[])</function><indexterm><primary>slice</primary></indexterm></entry>
- <entry><type>hstore</type></entry>
- <entry>extract a subset of an <type>hstore</type></entry>
- <entry><literal>slice('a=>1,b=>2,c=>3'::hstore, ARRAY['b','c','x'])</literal></entry>
- <entry><literal>"b"=>"2", "c"=>"3"</literal></entry>
- </row>
-
- <row>
- <entry><function>each(hstore)</function><indexterm><primary>each</primary></indexterm></entry>
- <entry><type>setof(key text, value text)</type></entry>
- <entry>get <type>hstore</type>'s keys and values as a set</entry>
- <entry><literal>select * from each('a=>1,b=>2')</literal></entry>
- <entry>
+</programlisting>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_array</primary></indexterm>
+ <function>hstore_to_array</function> ( <type>hstore</type> )
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s keys and values as an array of
+ alternating keys and values.
+ </para>
+ <para>
+ <literal>hstore_to_array('a=>1,b=>2')</literal>
+ <returnvalue>{a,1,b,2}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_matrix</primary></indexterm>
+ <function>hstore_to_matrix</function> ( <type>hstore</type> )
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s keys and values as a two-dimensional
+ array.
+ </para>
+ <para>
+ <literal>hstore_to_matrix('a=>1,b=>2')</literal>
+ <returnvalue>{{a,1},{b,2}}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_json</primary></indexterm>
+ <function>hstore_to_json</function> ( <type>hstore</type> )
+ <returnvalue>json</returnvalue>
+ </para>
+ <para>
+ Converts an <type>hstore</type> to a <type>json</type> value,
+ converting all non-null values to JSON strings.
+ </para>
+ <para>
+ This function is used implicitly when an <type>hstore</type> value is
+ cast to <type>json</type>.
+ </para>
+ <para>
+ <literal>hstore_to_json('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal>
+ <returnvalue>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_jsonb</primary></indexterm>
+ <function>hstore_to_jsonb</function> ( <type>hstore</type> )
+ <returnvalue>jsonb</returnvalue>
+ </para>
+ <para>
+ Converts an <type>hstore</type> to a <type>jsonb</type> value,
+ converting all non-null values to JSON strings.
+ </para>
+ <para>
+ This function is used implicitly when an <type>hstore</type> value is
+ cast to <type>jsonb</type>.
+ </para>
+ <para>
+ <literal>hstore_to_jsonb('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal>
+ <returnvalue>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_json_loose</primary></indexterm>
+ <function>hstore_to_json_loose</function> ( <type>hstore</type> )
+ <returnvalue>json</returnvalue>
+ </para>
+ <para>
+ Converts an <type>hstore</type> to a <type>json</type> value, but
+ attempts to distinguish numerical and Boolean values so they are
+ unquoted in the JSON.
+ </para>
+ <para>
+ <literal>hstore_to_json_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal>
+ <returnvalue>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>hstore_to_jsonb_loose</primary></indexterm>
+ <function>hstore_to_jsonb_loose</function> ( <type>hstore</type> )
+ <returnvalue>jsonb</returnvalue>
+ </para>
+ <para>
+ Converts an <type>hstore</type> to a <type>jsonb</type> value, but
+ attempts to distinguish numerical and Boolean values so they are
+ unquoted in the JSON.
+ </para>
+ <para>
+ <literal>hstore_to_jsonb_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4')</literal>
+ <returnvalue>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>slice</primary></indexterm>
+ <function>slice</function> ( <type>hstore</type>, <type>text[]</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Extracts a subset of an <type>hstore</type> containing only the
+ specified keys.
+ </para>
+ <para>
+ <literal>slice('a=>1,b=>2,c=>3'::hstore, ARRAY['b','c','x'])</literal>
+ <returnvalue>"b"=>"2", "c"=>"3"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>each</primary></indexterm>
+ <function>each</function> ( <type>hstore</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>key</parameter> <type>text</type>,
+ <parameter>value</parameter> <type>text</type> )
+ </para>
+ <para>
+ Extracts an <type>hstore</type>'s keys and values as a set of records.
+ </para>
+ <para>
+ <literal>select * from each('a=>1,b=>2')</literal>
+ <returnvalue></returnvalue>
<programlisting>
key | value
-----+-------
a | 1
b | 2
-</programlisting></entry>
- </row>
-
- <row>
- <entry><function>exist(hstore,text)</function><indexterm><primary>exist</primary></indexterm></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>hstore</type> contain key?</entry>
- <entry><literal>exist('a=>1','a')</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
-
- <row>
- <entry><function>defined(hstore,text)</function><indexterm><primary>defined</primary></indexterm></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>hstore</type> contain non-<literal>NULL</literal> value for key?</entry>
- <entry><literal>defined('a=>NULL','a')</literal></entry>
- <entry><literal>f</literal></entry>
- </row>
-
- <row>
- <entry><function>delete(hstore,text)</function><indexterm><primary>delete</primary></indexterm></entry>
- <entry><type>hstore</type></entry>
- <entry>delete pair with matching key</entry>
- <entry><literal>delete('a=>1,b=>2','b')</literal></entry>
- <entry><literal>"a"=>"1"</literal></entry>
- </row>
-
- <row>
- <entry><function>delete(hstore,text[])</function></entry>
- <entry><type>hstore</type></entry>
- <entry>delete pairs with matching keys</entry>
- <entry><literal>delete('a=>1,b=>2,c=>3',ARRAY['a','b'])</literal></entry>
- <entry><literal>"c"=>"3"</literal></entry>
- </row>
-
- <row>
- <entry><function>delete(hstore,hstore)</function></entry>
- <entry><type>hstore</type></entry>
- <entry>delete pairs matching those in the second argument</entry>
- <entry><literal>delete('a=>1,b=>2','a=>4,b=>2'::hstore)</literal></entry>
- <entry><literal>"a"=>"1"</literal></entry>
- </row>
-
- <row>
- <entry><function>populate_record(record,hstore)</function><indexterm><primary>populate_record</primary></indexterm></entry>
- <entry><type>record</type></entry>
- <entry>replace fields in <type>record</type> with matching values from <type>hstore</type></entry>
- <entry>see Examples section</entry>
- <entry></entry>
- </row>
-
+</programlisting>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>exist</primary></indexterm>
+ <function>exist</function> ( <type>hstore</type>, <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>hstore</type> contain key?
+ </para>
+ <para>
+ <literal>exist('a=>1','a')</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>defined</primary></indexterm>
+ <function>defined</function> ( <type>hstore</type>, <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>hstore</type> contain a non-<literal>NULL</literal> value
+ for key?
+ </para>
+ <para>
+ <literal>defined('a=>NULL','a')</literal>
+ <returnvalue>f</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>delete</primary></indexterm>
+ <function>delete</function> ( <type>hstore</type>, <type>text</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes pair with matching key.
+ </para>
+ <para>
+ <literal>delete('a=>1,b=>2','b')</literal>
+ <returnvalue>"a"=>"1"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>delete</function> ( <type>hstore</type>, <type>text[]</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes pairs with matching keys.
+ </para>
+ <para>
+ <literal>delete('a=>1,b=>2,c=>3',ARRAY['a','b'])</literal>
+ <returnvalue>"c"=>"3"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>delete</function> ( <type>hstore</type>, <type>hstore</type> )
+ <returnvalue>hstore</returnvalue>
+ </para>
+ <para>
+ Deletes pairs matching those in the second argument.
+ </para>
+ <para>
+ <literal>delete('a=>1,b=>2','a=>4,b=>2'::hstore)</literal>
+ <returnvalue>"a"=>"1"</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>populate_record</primary></indexterm>
+ <function>populate_record</function> ( <type>anyelement</type>, <type>hstore</type> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Replaces fields in the left operand (which must be a composite type)
+ with matching values from <type>hstore</type>.
+ </para>
+ <para>
+ <literal>populate_record(ROW(1,2), 'f1=>42'::hstore)</literal>
+ <returnvalue>(42,2)</returnvalue>
+ </para></entry>
+ </row>
</tbody>
</tgroup>
</table>
-
- <note>
- <para>
- The function <function>hstore_to_json</function> is used when
- an <type>hstore</type> value is cast to <type>json</type>.
- Likewise, <function>hstore_to_jsonb</function> is used when
- an <type>hstore</type> value is cast to <type>jsonb</type>.
- </para>
- </note>
-
- <note>
- <para>
- The function <function>populate_record</function> is actually declared
- with <type>anyelement</type>, not <type>record</type>, as its first argument,
- but it will reject non-record types with a run-time error.
- </para>
- </note>
</sect2>
<sect2>
<table id="intarray-func-table">
<title><filename>intarray</filename> Functions</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>icount(int[])</function><indexterm><primary>icount</primary></indexterm></entry>
- <entry><type>int</type></entry>
- <entry>number of elements in array</entry>
- <entry><literal>icount('{1,2,3}'::int[])</literal></entry>
- <entry><literal>3</literal></entry>
- </row>
-
- <row>
- <entry><function>sort(int[], text dir)</function><indexterm><primary>sort</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>sort array — <parameter>dir</parameter> must be <literal>asc</literal> or <literal>desc</literal></entry>
- <entry><literal>sort('{1,2,3}'::int[], 'desc')</literal></entry>
- <entry><literal>{3,2,1}</literal></entry>
- </row>
-
- <row>
- <entry><function>sort(int[])</function></entry>
- <entry><type>int[]</type></entry>
- <entry>sort in ascending order</entry>
- <entry><literal>sort(array[11,77,44])</literal></entry>
- <entry><literal>{11,44,77}</literal></entry>
- </row>
-
- <row>
- <entry><function>sort_asc(int[])</function><indexterm><primary>sort_asc</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>sort in ascending order</entry>
- <entry><literal></literal></entry>
- <entry><literal></literal></entry>
- </row>
-
- <row>
- <entry><function>sort_desc(int[])</function><indexterm><primary>sort_desc</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>sort in descending order</entry>
- <entry><literal></literal></entry>
- <entry><literal></literal></entry>
- </row>
-
- <row>
- <entry><function>uniq(int[])</function><indexterm><primary>uniq</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>remove adjacent duplicates</entry>
- <entry><literal>uniq(sort('{1,2,3,2,1}'::int[]))</literal></entry>
- <entry><literal>{1,2,3}</literal></entry>
- </row>
-
- <row>
- <entry><function>idx(int[], int item)</function><indexterm><primary>idx</primary></indexterm></entry>
- <entry><type>int</type></entry>
- <entry>index of first element matching <parameter>item</parameter> (0 if none)</entry>
- <entry><literal>idx(array[11,22,33,22,11], 22)</literal></entry>
- <entry><literal>2</literal></entry>
- </row>
-
- <row>
- <entry><function>subarray(int[], int start, int len)</function><indexterm><primary>subarray</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>portion of array starting at position <parameter>start</parameter>, <parameter>len</parameter> elements</entry>
- <entry><literal>subarray('{1,2,3,2,1}'::int[], 2, 3)</literal></entry>
- <entry><literal>{2,3,2}</literal></entry>
- </row>
-
- <row>
- <entry><function>subarray(int[], int start)</function></entry>
- <entry><type>int[]</type></entry>
- <entry>portion of array starting at position <parameter>start</parameter></entry>
- <entry><literal>subarray('{1,2,3,2,1}'::int[], 2)</literal></entry>
- <entry><literal>{2,3,2,1}</literal></entry>
- </row>
-
- <row>
- <entry><function>intset(int)</function><indexterm><primary>intset</primary></indexterm></entry>
- <entry><type>int[]</type></entry>
- <entry>make single-element array</entry>
- <entry><literal>intset(42)</literal></entry>
- <entry><literal>{42}</literal></entry>
- </row>
-
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>icount</primary></indexterm>
+ <function>icount</function> ( <type>integer[]</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the number of elements in the array.
+ </para>
+ <para>
+ <literal>icount('{1,2,3}'::integer[])</literal>
+ <returnvalue>3</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>sort</primary></indexterm>
+ <function>sort</function> ( <type>integer[]</type>, <parameter>dir</parameter> <type>text</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Sorts the array in either ascending or descending order.
+ <parameter>dir</parameter> must be <literal>asc</literal>
+ or <literal>desc</literal>.
+ </para>
+ <para>
+ <literal>sort('{1,3,2}'::integer[], 'desc')</literal>
+ <returnvalue>{3,2,1}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sort</function> ( <type>integer[]</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para role="func_signature">
+ <indexterm><primary>sort_asc</primary></indexterm>
+ <function>sort_asc</function> ( <type>integer[]</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Sorts in ascending order.
+ </para>
+ <para>
+ <literal>sort(array[11,77,44])</literal>
+ <returnvalue>{11,44,77}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>sort_desc</primary></indexterm>
+ <function>sort_desc</function> ( <type>integer[]</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Sorts in descending order.
+ </para>
+ <para>
+ <literal>sort_desc(array[11,77,44])</literal>
+ <returnvalue>{77,44,11}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>uniq</primary></indexterm>
+ <function>uniq</function> ( <type>integer[]</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Removes adjacent duplicates.
+ </para>
+ <para>
+ <literal>uniq(sort('{1,2,3,2,1}'::integer[]))</literal>
+ <returnvalue>{1,2,3}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>idx</primary></indexterm>
+ <function>idx</function> ( <type>integer[]</type>, <parameter>item</parameter> <type>integer</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns index of the first array element
+ matching <parameter>item</parameter>, or 0 if no match.
+ </para>
+ <para>
+ <literal>idx(array[11,22,33,22,11], 22)</literal>
+ <returnvalue>2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>subarray</primary></indexterm>
+ <function>subarray</function> ( <type>integer[]</type>, <parameter>start</parameter> <type>integer</type>, <parameter>len</parameter> <type>integer</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Extracts the portion of the array starting at
+ position <parameter>start</parameter>, with <parameter>len</parameter>
+ elements.
+ </para>
+ <para>
+ <literal>subarray('{1,2,3,2,1}'::integer[], 2, 3)</literal>
+ <returnvalue>{2,3,2}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>subarray</function> ( <type>integer[]</type>, <parameter>start</parameter> <type>integer</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Extracts the portion of the array starting at
+ position <parameter>start</parameter>.
+ </para>
+ <para>
+ <literal>subarray('{1,2,3,2,1}'::integer[], 2)</literal>
+ <returnvalue>{2,3,2,1}</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>intset</primary></indexterm>
+ <function>intset</function> ( <type>integer</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Makes a single-element array.
+ </para>
+ <para>
+ <literal>intset(42)</literal>
+ <returnvalue>{42}</returnvalue>
+ </para></entry>
+ </row>
</tbody>
</tgroup>
</table>
<table id="intarray-op-table">
<title><filename>intarray</filename> Operators</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>int[] && int[]</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>overlap — <literal>true</literal> if arrays have at least one common element</entry>
- </row>
- <row>
- <entry><literal>int[] @> int[]</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>contains — <literal>true</literal> if left array contains right array</entry>
- </row>
- <row>
- <entry><literal>int[] <@ int[]</literal></entry>
- <entry><type>boolean</type></entry>
- <entry>contained — <literal>true</literal> if left array is contained in right array</entry>
- </row>
- <row>
- <entry><literal># int[]</literal></entry>
- <entry><type>int</type></entry>
- <entry>number of elements in array</entry>
- </row>
- <row>
- <entry><literal>int[] # int</literal></entry>
- <entry><type>int</type></entry>
- <entry>index (same as <function>idx</function> function)</entry>
- </row>
- <row>
- <entry><literal>int[] + int</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>push element onto array (add it to end of array)</entry>
- </row>
- <row>
- <entry><literal>int[] + int[] </literal></entry>
- <entry><type>int[]</type></entry>
- <entry>array concatenation (right array added to the end of left one)</entry>
- </row>
- <row>
- <entry><literal>int[] - int</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>remove entries matching right argument from array</entry>
- </row>
- <row>
- <entry><literal>int[] - int[]</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>remove elements of right array from left</entry>
- </row>
- <row>
- <entry><literal>int[] | int</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>union of arguments</entry>
- </row>
- <row>
- <entry><literal>int[] | int[]</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>union of arrays</entry>
- </row>
- <row>
- <entry><literal>int[] & int[]</literal></entry>
- <entry><type>int[]</type></entry>
- <entry>intersection of arrays</entry>
- </row>
- <row>
- <entry><literal>int[] @@ query_int</literal></entry>
- <entry><type>boolean</type></entry>
- <entry><literal>true</literal> if array satisfies query (see below)</entry>
- </row>
- <row>
- <entry><literal>query_int ~~ int[]</literal></entry>
- <entry><type>boolean</type></entry>
- <entry><literal>true</literal> if array satisfies query (commutator of <literal>@@</literal>)</entry>
- </row>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>&&</literal> <type>integer[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Do arrays overlap (have at least one element in common)?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>@></literal> <type>integer[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does left array contain right array?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal><@</literal> <type>integer[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is left array contained in right array?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type></type> <literal>#</literal> <type>integer[]</type>
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the number of elements in the array.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>#</literal> <type>integer</type>
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns index of the first array element
+ matching the right argument, or 0 if no match.
+ (Same as <function>idx</function> function.)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>+</literal> <type>integer</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Adds element to end of array.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>+</literal> <type>integer[]</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Concatenates the arrays.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>-</literal> <type>integer</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Removes entries matching the right argument from the array.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>-</literal> <type>integer[]</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Removes elements of the right array from the left array.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>|</literal> <type>integer</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Computes the union of the arguments.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>|</literal> <type>integer[]</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Computes the union of the arguments.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>&</literal> <type>integer[]</type>
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Computes the intersection of the arguments.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>integer[]</type> <literal>@@</literal> <type>query_int</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array satisfy query? (see below)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>query_int</type> <literal>~~</literal> <type>integer[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array satisfy query? (commutator of <literal>@@</literal>)
+ </para></entry>
+ </row>
</tbody>
</tgroup>
</table>
The implementation uses an RD-tree data structure with
built-in lossy compression.
</para>
-
+
<para>
<literal>gist__int_ops</literal> approximates an integer set as an array of
integer ranges. Its optional integer parameter <literal>numranges</literal>
keys leads to a more precise search (scanning a smaller fraction of the index and
fewer heap pages), at the cost of a larger index.
</para>
-
+
<para>
<literal>gist__intbig_ops</literal> approximates an integer set as a bitmap
signature. Its optional integer parameter <literal>siglen</literal>
<table id="isn-datatypes">
<title><filename>isn</filename> Data Types</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>Data Type</entry>
<table id="isn-functions">
<title><filename>isn</filename> Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>isn_weak(boolean)</function><indexterm><primary>isn_weak</primary></indexterm></entry>
- <entry><type>boolean</type></entry>
- <entry>Sets the weak input mode (returns new setting)</entry>
- </row>
- <row>
- <entry><function>isn_weak()</function></entry>
- <entry><type>boolean</type></entry>
- <entry>Gets the current status of the weak mode</entry>
- </row>
- <row>
- <entry><function>make_valid(isn)</function><indexterm><primary>make_valid</primary></indexterm></entry>
- <entry><type>isn</type></entry>
- <entry>Validates an invalid number (clears the invalid flag)</entry>
- </row>
- <row>
- <entry><function>is_valid(isn)</function><indexterm><primary>is_valid</primary></indexterm></entry>
- <entry><type>boolean</type></entry>
- <entry>Checks for the presence of the invalid flag</entry>
- </row>
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>isn_weak</primary></indexterm>
+ <function>isn_weak</function> ( <type>boolean</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Sets the weak input mode, and returns new setting.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>isn_weak</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns the current status of the weak mode.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>make_valid</primary></indexterm>
+ <function>make_valid</function> ( <type>isn</type> )
+ <returnvalue>isn</returnvalue>
+ </para>
+ <para>
+ Validates an invalid number (clears the invalid flag).
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>is_valid</primary></indexterm>
+ <function>is_valid</function> ( <type>isn</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Checks for the presence of the invalid flag.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<para>
listed in <xref linkend="lo-funcs-table"/>.
</para>
- <table id="lo-funcs-table">
- <title>SQL-Oriented Large Object Functions</title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <indexterm>
- <primary>lo_from_bytea</primary>
- </indexterm>
- <literal><function>lo_from_bytea(<parameter>loid</parameter> <type>oid</type>, <parameter>string</parameter> <type>bytea</type>)</function></literal>
- </entry>
- <entry><type>oid</type></entry>
- <entry>
- Create a large object and store data there, returning its OID.
- Pass <literal>0</literal> to have the system choose an OID.
- </entry>
- <entry><literal>lo_from_bytea(0, '\xffffff00')</literal></entry>
- <entry><literal>24528</literal></entry>
- </row>
-
- <row>
- <entry>
- <indexterm>
- <primary>lo_put</primary>
- </indexterm>
- <literal><function>lo_put(<parameter>loid</parameter> <type>oid</type>, <parameter>offset</parameter> <type>bigint</type>, <parameter>str</parameter> <type>bytea</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>
- Write data at the given offset.
- </entry>
- <entry><literal>lo_put(24528, 1, '\xaa')</literal></entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>
- <indexterm>
- <primary>lo_get</primary>
- </indexterm>
- <literal><function>lo_get(<parameter>loid</parameter> <type>oid</type> <optional>, <parameter>from</parameter> <type>bigint</type>, <parameter>for</parameter> <type>int</type></optional>)</function></literal>
- </entry>
- <entry><type>bytea</type></entry>
- <entry>
- Extract contents or a substring thereof.
- </entry>
- <entry><literal>lo_get(24528, 0, 3)</literal></entry>
- <entry><literal>\xffaaff</literal></entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
+ <table id="lo-funcs-table">
+ <title>SQL-Oriented Large Object Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>lo_from_bytea</primary>
+ </indexterm>
+ <function>lo_from_bytea</function> ( <parameter>loid</parameter> <type>oid</type>, <parameter>data</parameter> <type>bytea</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Creates a large object and stores <parameter>data</parameter> in it.
+ If <parameter>loid</parameter> is zero then the system will choose a
+ free OID, otherwise that OID is used (with an error if some large
+ object already has that OID). On success, the large object's OID is
+ returned.
+ </para>
+ <para>
+ <literal>lo_from_bytea(0, '\xffffff00')</literal>
+ <returnvalue>24528</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>lo_put</primary>
+ </indexterm>
+ <function>lo_put</function> ( <parameter>loid</parameter> <type>oid</type>, <parameter>offset</parameter> <type>bigint</type>, <parameter>data</parameter> <type>bytea</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Writes <parameter>data</parameter> starting at the given offset within
+ the large object; the large object is enlarged if necessary.
+ </para>
+ <para>
+ <literal>lo_put(24528, 1, '\xaa')</literal>
+ <returnvalue></returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>lo_get</primary>
+ </indexterm>
+ <function>lo_get</function> ( <parameter>loid</parameter> <type>oid</type> <optional>, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>integer</type> </optional> )
+ <returnvalue>bytea</returnvalue>
+ </para>
+ <para>
+ Extracts the large object's contents, or a substring thereof.
+ </para>
+ <para>
+ <literal>lo_get(24528, 0, 3)</literal>
+ <returnvalue>\xffaaff</returnvalue>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
There are additional server-side functions corresponding to each of the
<table id="ltree-op-table">
<title><type>ltree</type> Operators</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><type>ltree</type> <literal>@></literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>is left argument an ancestor of right (or equal)?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal><@</literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>is left argument a descendant of right (or equal)?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>~</literal> <type>lquery</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>lquery</type> <literal>~</literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>?</literal> <type>lquery[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match any <type>lquery</type> in array?</entry>
- </row>
-
- <row>
- <entry><type>lquery[]</type> <literal>?</literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match any <type>lquery</type> in array?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>@</literal> <type>ltxtquery</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match <type>ltxtquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltxtquery</type> <literal>@</literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> match <type>ltxtquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>||</literal> <type>ltree</type></entry>
- <entry><type>ltree</type></entry>
- <entry>concatenate <type>ltree</type> paths</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>||</literal> <type>text</type></entry>
- <entry><type>ltree</type></entry>
- <entry>convert text to <type>ltree</type> and concatenate</entry>
- </row>
-
- <row>
- <entry><type>text</type> <literal>||</literal> <type>ltree</type></entry>
- <entry><type>ltree</type></entry>
- <entry>convert text to <type>ltree</type> and concatenate</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>@></literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain an ancestor of <type>ltree</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal><@</literal> <type>ltree[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain an ancestor of <type>ltree</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal><@</literal> <type>ltree</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain a descendant of <type>ltree</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree</type> <literal>@></literal> <type>ltree[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain a descendant of <type>ltree</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>~</literal> <type>lquery</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain any path matching <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>lquery</type> <literal>~</literal> <type>ltree[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain any path matching <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>?</literal> <type>lquery[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> array contain any path matching any <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>lquery[]</type> <literal>?</literal> <type>ltree[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does <type>ltree</type> array contain any path matching any <type>lquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>@</literal> <type>ltxtquery</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain any path matching <type>ltxtquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltxtquery</type> <literal>@</literal> <type>ltree[]</type></entry>
- <entry><type>boolean</type></entry>
- <entry>does array contain any path matching <type>ltxtquery</type>?</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>?@></literal> <type>ltree</type></entry>
- <entry><type>ltree</type></entry>
- <entry>first array entry that is an ancestor of <type>ltree</type>; NULL if none</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>?<@</literal> <type>ltree</type></entry>
- <entry><type>ltree</type></entry>
- <entry>first array entry that is a descendant of <type>ltree</type>; NULL if none</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>?~</literal> <type>lquery</type></entry>
- <entry><type>ltree</type></entry>
- <entry>first array entry that matches <type>lquery</type>; NULL if none</entry>
- </row>
-
- <row>
- <entry><type>ltree[]</type> <literal>?@</literal> <type>ltxtquery</type></entry>
- <entry><type>ltree</type></entry>
- <entry>first array entry that matches <type>ltxtquery</type>; NULL if none</entry>
- </row>
-
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>@></literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is left argument an ancestor of right (or equal)?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal><@</literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is left argument a descendant of right (or equal)?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>~</literal> <type>lquery</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>lquery</type> <literal>~</literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>ltree</type> match <type>lquery</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>?</literal> <type>lquery[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>lquery[]</type> <literal>?</literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>ltree</type> match any <type>lquery</type> in array?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>@</literal> <type>ltxtquery</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>ltxtquery</type> <literal>@</literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>ltree</type> match <type>ltxtquery</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>||</literal> <type>ltree</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Concatenates <type>ltree</type> paths.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree</type> <literal>||</literal> <type>text</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>text</type> <literal>||</literal> <type>ltree</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Converts text to <type>ltree</type> and concatenates.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>@></literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>ltree</type> <literal><@</literal> <type>ltree[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array contain an ancestor of <type>ltree</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal><@</literal> <type>ltree</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>ltree</type> <literal>@></literal> <type>ltree[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array contain a descendant of <type>ltree</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>~</literal> <type>lquery</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>lquery</type> <literal>~</literal> <type>ltree[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array contain any path matching <type>lquery</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>?</literal> <type>lquery[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>lquery[]</type> <literal>?</literal> <type>ltree[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does <type>ltree</type> array contain any path matching
+ any <type>lquery</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>@</literal> <type>ltxtquery</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <type>ltxtquery</type> <literal>@</literal> <type>ltree[]</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array contain any path matching <type>ltxtquery</type>?
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>?@></literal> <type>ltree</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns first array entry that is an ancestor of <type>ltree</type>,
+ or <literal>NULL</literal> if none.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>?<@</literal> <type>ltree</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns first array entry that is a descendant of <type>ltree</type>,
+ or <literal>NULL</literal> if none.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>?~</literal> <type>lquery</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns first array entry that matches <type>lquery</type>,
+ or <literal>NULL</literal> if none.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>ltree[]</type> <literal>?@</literal> <type>ltxtquery</type>
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns first array entry that matches <type>ltxtquery</type>,
+ or <literal>NULL</literal> if none.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<para>
<table id="ltree-func-table">
<title><type>ltree</type> Functions</title>
-
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>subltree(ltree, int start, int end)</function><indexterm><primary>subltree</primary></indexterm></entry>
- <entry><type>ltree</type></entry>
- <entry>subpath of <type>ltree</type> from position <parameter>start</parameter> to
- position <parameter>end</parameter>-1 (counting from 0)</entry>
- <entry><literal>subltree('Top.Child1.Child2',1,2)</literal></entry>
- <entry><literal>Child1</literal></entry>
- </row>
-
- <row>
- <entry><function>subpath(ltree, int offset, int len)</function><indexterm><primary>subpath</primary></indexterm></entry>
- <entry><type>ltree</type></entry>
- <entry>subpath of <type>ltree</type> starting at position
- <parameter>offset</parameter>, length <parameter>len</parameter>.
- If <parameter>offset</parameter> is negative, subpath starts that far from the
- end of the path. If <parameter>len</parameter> is negative, leaves that many
- labels off the end of the path.</entry>
- <entry><literal>subpath('Top.Child1.Child2',0,2)</literal></entry>
- <entry><literal>Top.Child1</literal></entry>
- </row>
-
- <row>
- <entry><function>subpath(ltree, int offset)</function></entry>
- <entry><type>ltree</type></entry>
- <entry>subpath of <type>ltree</type> starting at position
- <parameter>offset</parameter>, extending to end of path.
- If <parameter>offset</parameter> is negative, subpath starts that far from the
- end of the path.</entry>
- <entry><literal>subpath('Top.Child1.Child2',1)</literal></entry>
- <entry><literal>Child1.Child2</literal></entry>
- </row>
-
- <row>
- <entry><function>nlevel(ltree)</function><indexterm><primary>nlevel</primary></indexterm></entry>
- <entry><type>integer</type></entry>
- <entry>number of labels in path</entry>
- <entry><literal>nlevel('Top.Child1.Child2')</literal></entry>
- <entry><literal>3</literal></entry>
- </row>
-
- <row>
- <entry><function>index(ltree a, ltree b)</function><indexterm><primary>index</primary></indexterm></entry>
- <entry><type>integer</type></entry>
- <entry>position of first occurrence of <parameter>b</parameter> in
- <parameter>a</parameter>; -1 if not found</entry>
- <entry><literal>index('0.1.2.3.5.4.5.6.8.5.6.8','5.6')</literal></entry>
- <entry><literal>6</literal></entry>
- </row>
-
- <row>
- <entry><function>index(ltree a, ltree b, int offset)</function></entry>
- <entry><type>integer</type></entry>
- <entry>position of first occurrence of <parameter>b</parameter> in
- <parameter>a</parameter>, searching starting at <parameter>offset</parameter>;
- negative <parameter>offset</parameter> means start <parameter>-offset</parameter>
- labels from the end of the path</entry>
- <entry><literal>index('0.1.2.3.5.4.5.6.8.5.6.8','5.6',-4)</literal></entry>
- <entry><literal>9</literal></entry>
- </row>
-
- <row>
- <entry><function>text2ltree(text)</function><indexterm><primary>text2ltree</primary></indexterm></entry>
- <entry><type>ltree</type></entry>
- <entry>cast <type>text</type> to <type>ltree</type></entry>
- <entry><literal></literal></entry>
- <entry><literal></literal></entry>
- </row>
-
- <row>
- <entry><function>ltree2text(ltree)</function><indexterm><primary>ltree2text</primary></indexterm></entry>
- <entry><type>text</type></entry>
- <entry>cast <type>ltree</type> to <type>text</type></entry>
- <entry><literal></literal></entry>
- <entry><literal></literal></entry>
- </row>
-
- <row>
- <entry><function>lca(ltree, ltree, ...)</function><indexterm><primary>lca</primary></indexterm></entry>
- <entry><type>ltree</type></entry>
- <entry>longest common ancestor of paths
- (up to 8 arguments supported)</entry>
- <entry><literal>lca('1.2.3','1.2.3.4.5.6')</literal></entry>
- <entry><literal>1.2</literal></entry>
- </row>
-
- <row>
- <entry><function>lca(ltree[])</function></entry>
- <entry><type>ltree</type></entry>
- <entry>longest common ancestor of paths in array</entry>
- <entry><literal>lca(array['1.2.3'::ltree,'1.2.3.4'])</literal></entry>
- <entry><literal>1.2</literal></entry>
- </row>
-
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>subltree</primary></indexterm>
+ <function>subltree</function> ( <type>ltree</type>, <parameter>start</parameter> <type>integer</type>, <parameter>end</parameter> <type>integer</type> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns subpath of <type>ltree</type> from
+ position <parameter>start</parameter> to
+ position <parameter>end</parameter>-1 (counting from 0).
+ </para>
+ <para>
+ <literal>subltree('Top.Child1.Child2',1,2)</literal>
+ <returnvalue>Child1</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>subpath</primary></indexterm>
+ <function>subpath</function> ( <type>ltree</type>, <parameter>offset</parameter> <type>integer</type>, <parameter>len</parameter> <type>integer</type> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns subpath of <type>ltree</type> starting at
+ position <parameter>offset</parameter>, with
+ length <parameter>len</parameter>. If <parameter>offset</parameter>
+ is negative, subpath starts that far from the end of the path.
+ If <parameter>len</parameter> is negative, leaves that many labels off
+ the end of the path.
+ </para>
+ <para>
+ <literal>subpath('Top.Child1.Child2',0,2)</literal>
+ <returnvalue>Top.Child1</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>subpath</function> ( <type>ltree</type>, <parameter>offset</parameter> <type>integer</type> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Returns subpath of <type>ltree</type> starting at
+ position <parameter>offset</parameter>, extending to end of path.
+ If <parameter>offset</parameter> is negative, subpath starts that far
+ from the end of the path.
+ </para>
+ <para>
+ <literal>subpath('Top.Child1.Child2',1)</literal>
+ <returnvalue>Child1.Child2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>nlevel</primary></indexterm>
+ <function>nlevel</function> ( <type>ltree</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns number of labels in path.
+ </para>
+ <para>
+ <literal>nlevel('Top.Child1.Child2')</literal>
+ <returnvalue>3</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>index</primary></indexterm>
+ <function>index</function> ( <parameter>a</parameter> <type>ltree</type>, <parameter>b</parameter> <type>ltree</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns position of first occurrence of <parameter>b</parameter> in
+ <parameter>a</parameter>, or -1 if not found.
+ </para>
+ <para>
+ <literal>index('0.1.2.3.5.4.5.6.8.5.6.8','5.6')</literal>
+ <returnvalue>6</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>index</function> ( <parameter>a</parameter> <type>ltree</type>, <parameter>b</parameter> <type>ltree</type>, <parameter>offset</parameter> <type>integer</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns position of first occurrence of <parameter>b</parameter>
+ in <parameter>a</parameter>, or -1 if not found. The search starts at
+ position <parameter>offset</parameter>;
+ negative <parameter>offset</parameter> means
+ start <parameter>-offset</parameter> labels from the end of the path.
+ </para>
+ <para>
+ <literal>index('0.1.2.3.5.4.5.6.8.5.6.8','5.6',-4)</literal>
+ <returnvalue>9</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>text2ltree</primary></indexterm>
+ <function>text2ltree</function> ( <type>text</type> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Casts <type>text</type> to <type>ltree</type>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>ltree2text</primary></indexterm>
+ <function>ltree2text</function> ( <type>ltree</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Casts <type>ltree</type> to <type>text</type>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>lca</primary></indexterm>
+ <function>lca</function> ( <type>ltree</type> <optional>, <type>ltree</type> <optional>, ... </optional></optional> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Computes longest common ancestor of paths
+ (up to 8 arguments are supported).
+ </para>
+ <para>
+ <literal>lca('1.2.3','1.2.3.4.5.6')</literal>
+ <returnvalue>1.2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>lca</function> ( <type>ltree[]</type> )
+ <returnvalue>ltree</returnvalue>
+ </para>
+ <para>
+ Computes longest common ancestor of paths in array.
+ </para>
+ <para>
+ <literal>lca(array['1.2.3'::ltree,'1.2.3.4'])</literal>
+ <returnvalue>1.2</returnvalue>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
linkend="monitoring-stats-funcs-table"/>.
</para>
- <table id="monitoring-stats-funcs-table">
- <title>Additional Statistics Functions</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
+
<table id="monitoring-stats-funcs-table">
+ <title>Additional Statistics Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- <row>
+ <tbody>
+ <row>
<!-- See also the entry for this in func.sgml -->
- <entry><literal><function>pg_backend_pid()</function></literal></entry>
- <entry><type>integer</type></entry>
- <entry>
- Process ID of the server process handling the current session
- </entry>
- </row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_backend_pid</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the process ID of the server process attached to the current
+ session.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_activity</function>(<type>integer</type>)</literal><indexterm><primary>pg_stat_get_activity</primary></indexterm></entry>
- <entry><type>setof record</type></entry>
- <entry>
- Returns a record of information about the backend with the specified PID, or
- one record for each active backend in the system if <symbol>NULL</symbol> is
- specified. The fields returned are a subset of those in the
- <structname>pg_stat_activity</structname> view.
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_activity</primary>
+ </indexterm>
+ <function>pg_stat_get_activity</function> ( <type>integer</type> )
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Returns a record of information about the backend with the specified
+ process ID, or one record for each active backend in the system
+ if <literal>NULL</literal> is specified. The fields returned are a
+ subset of those in the <structname>pg_stat_activity</structname> view.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_snapshot_timestamp()</function></literal><indexterm><primary>pg_stat_get_snapshot_timestamp</primary></indexterm></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>
- Returns the timestamp of the current statistics snapshot
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_snapshot_timestamp</primary>
+ </indexterm>
+ <function>pg_stat_get_snapshot_timestamp</function> ()
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the timestamp of the current statistics snapshot.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_clear_snapshot()</function></literal><indexterm><primary>pg_stat_clear_snapshot</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Discard the current statistics snapshot
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_clear_snapshot</primary>
+ </indexterm>
+ <function>pg_stat_clear_snapshot</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Discards the current statistics snapshot.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_reset()</function></literal><indexterm><primary>pg_stat_reset</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Reset all statistics counters for the current database to zero
- (requires superuser privileges by default, but EXECUTE for this
- function can be granted to others.)
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_reset</primary>
+ </indexterm>
+ <function>pg_stat_reset</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Resets all statistics counters for the current database to zero.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_reset_shared</function>(text)</literal><indexterm><primary>pg_stat_reset_shared</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Reset some cluster-wide statistics counters to zero, depending on the
- argument (requires superuser privileges by default, but EXECUTE for
- this function can be granted to others).
- Calling <literal>pg_stat_reset_shared('bgwriter')</literal> will zero all the
- counters shown in the <structname>pg_stat_bgwriter</structname> view.
- Calling <literal>pg_stat_reset_shared('archiver')</literal> will zero all the
- counters shown in the <structname>pg_stat_archiver</structname> view.
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_reset_shared</primary>
+ </indexterm>
+ <function>pg_stat_reset_shared</function> ( <type>text</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Resets some cluster-wide statistics counters to zero, depending on the
+ argument. The argument can be <literal>bgwriter</literal> to reset
+ all the counters shown in
+ the <structname>pg_stat_bgwriter</structname>
+ view,or <literal>archiver</literal> to reset all the counters shown in
+ the <structname>pg_stat_archiver</structname> view.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_reset_single_table_counters</function>(oid)</literal><indexterm><primary>pg_stat_reset_single_table_counters</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Reset statistics for a single table or index in the current database to
- zero (requires superuser privileges by default, but EXECUTE for this
- function can be granted to others)
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_reset_single_table_counters</primary>
+ </indexterm>
+ <function>pg_stat_reset_single_table_counters</function> ( <type>oid</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Resets statistics for a single table or index in the current database
+ to zero.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_reset_single_function_counters</function>(oid)</literal><indexterm><primary>pg_stat_reset_single_function_counters</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Reset statistics for a single function in the current database to
- zero (requires superuser privileges by default, but EXECUTE for this
- function can be granted to others)
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_reset_single_function_counters</primary>
+ </indexterm>
+ <function>pg_stat_reset_single_function_counters</function> ( <type>oid</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Resets statistics for a single function in the current database to
+ zero.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_reset_slru</function>(text)</literal><indexterm><primary>pg_stat_reset_slru</primary></indexterm></entry>
- <entry><type>void</type></entry>
- <entry>
- Reset statistics either for a single SLRU or all SLRUs in the cluster
- to zero (requires superuser privileges by default, but EXECUTE for this
- function can be granted to others).
- Calling <literal>pg_stat_reset_slru(NULL)</literal> will zero all the
- counters shown in the <structname>pg_stat_slru</structname> view for
- all SLRU caches.
- Calling <literal>pg_stat_reset_slru(name)</literal> with names from a
- predefined list (<literal>async</literal>, <literal>clog</literal>,
- <literal>commit_timestamp</literal>, <literal>multixact_offset</literal>,
- <literal>multixact_member</literal>, <literal>oldserxid</literal>,
- <literal>subtrans</literal> and <literal>other</literal>) resets counters
- for only that entry. Names not included in this list are treated as
- <literal>other</literal>.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_reset_slru</primary>
+ </indexterm>
+ <function>pg_stat_reset_slru</function> ( <type>text</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Resets statistics to zero for a single SLRU cache, or for all SLRUs in
+ the cluster. If the argument is NULL, all counters shown in
+ the <structname>pg_stat_slru</structname> view for all SLRU caches are
+ reset. The argument can be one of <literal>async</literal>,
+ <literal>clog</literal>, <literal>commit_timestamp</literal>,
+ <literal>multixact_offset</literal>,
+ <literal>multixact_member</literal>, <literal>oldserxid</literal>, or
+ <literal>subtrans</literal> to reset the counters for only that entry.
+ If the argument is <literal>other</literal> (or indeed, any
+ unrecognized name), then the counters for all other SLRU caches, such
+ as extension-defined caches, are reset.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
<function>pg_stat_get_activity</function>, the underlying function of
</programlisting>
</para>
- <table id="monitoring-stats-backend-funcs-table">
- <title>Per-Backend Statistics Functions</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry><literal><function>pg_stat_get_backend_idset()</function></literal></entry>
- <entry><type>setof integer</type></entry>
- <entry>Set of currently active backend ID numbers (from 1 to the
- number of active backends)</entry>
- </row>
+ <table id="monitoring-stats-backend-funcs-table">
+ <title>Per-Backend Statistics Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- <row>
- <entry><literal><function>pg_stat_get_backend_activity(integer)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>Text of this backend's most recent query</entry>
- </row>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_idset</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_idset</function> ()
+ <returnvalue>setof integer</returnvalue>
+ </para>
+ <para>
+ Returns the set of currently active backend ID numbers (from 1 to the
+ number of active backends).
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_activity_start(integer)</function></literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Time when the most recent query was started</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_activity</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_activity</function> ( <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the text of this backend's most recent query.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_client_addr(integer)</function></literal></entry>
- <entry><type>inet</type></entry>
- <entry>IP address of the client connected to this backend</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_activity_start</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_activity_start</function> ( <type>integer</type> )
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time when the backend's most recent query was started.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_client_port(integer)</function></literal></entry>
- <entry><type>integer</type></entry>
- <entry>TCP port number that the client is using for communication</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_client_addr</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_client_addr</function> ( <type>integer</type> )
+ <returnvalue>inet</returnvalue>
+ </para>
+ <para>
+ Returns the IP address of the client connected to this backend.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_dbid(integer)</function></literal></entry>
- <entry><type>oid</type></entry>
- <entry>OID of the database this backend is connected to</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_client_port</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_client_port</function> ( <type>integer</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the TCP port number that the client is using for communication.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_pid(integer)</function></literal></entry>
- <entry><type>integer</type></entry>
- <entry>Process ID of this backend</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_dbid</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_dbid</function> ( <type>integer</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Returns the OID of the database this backend is connected to.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_start(integer)</function></literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Time when this process was started</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_pid</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_pid</function> ( <type>integer</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the process ID of this backend.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_userid(integer)</function></literal></entry>
- <entry><type>oid</type></entry>
- <entry>OID of the user logged into this backend</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_start</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_start</function> ( <type>integer</type> )
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time when this process was started.
+ </para></entry>
+ </row>
<row>
- <entry><literal><function>pg_stat_get_backend_wait_event_type(integer)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>Wait event type name if backend is currently waiting, otherwise NULL.
- See <xref linkend="wait-event-table"/> for details.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_userid</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_userid</function> ( <type>integer</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Returns the OID of the user logged into this backend.
+ </para></entry>
</row>
- <row>
- <entry><literal><function>pg_stat_get_backend_wait_event(integer)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>Wait event name if backend is currently waiting, otherwise NULL.
- See <xref linkend="wait-event-table"/> for details.
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_wait_event_type</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_wait_event_type</function> ( <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the wait event type name if this backend is currently waiting,
+ otherwise NULL. See <xref linkend="wait-event-table"/> for details.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>pg_stat_get_backend_xact_start(integer)</function></literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Time when the current transaction was started</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_wait_event</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_wait_event</function> ( <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the wait event name if this backend is currently waiting,
+ otherwise NULL. See <xref linkend="wait-event-table"/> for details.
+ </para></entry>
+ </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_get_backend_xact_start</primary>
+ </indexterm>
+ <function>pg_stat_get_backend_xact_start</function> ( <type>integer</type> )
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time when the backend's current transaction was started.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</sect2>
</sect1>
<row>
<entry><literal>finalizing analyze</literal></entry>
<entry>
- The command is updating pg_class. When this phase is completed,
+ The command is updating pg_class. When this phase is completed,
<command>ANALYZE</command> will end.
</entry>
</row>
<table id="pgtrgm-func-table">
<title><filename>pg_trgm</filename> Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><function>similarity(text, text)</function><indexterm><primary>similarity</primary></indexterm></entry>
- <entry><type>real</type></entry>
- <entry>
- Returns a number that indicates how similar the two arguments are.
- The range of the result is zero (indicating that the two strings are
- completely dissimilar) to one (indicating that the two strings are
- identical).
- </entry>
- </row>
- <row>
- <entry><function>show_trgm(text)</function><indexterm><primary>show_trgm</primary></indexterm></entry>
- <entry><type>text[]</type></entry>
- <entry>
- Returns an array of all the trigrams in the given string.
- (In practice this is seldom useful except for debugging.)
- </entry>
- </row>
- <row>
- <entry>
- <function>word_similarity(text, text)</function>
- <indexterm><primary>word_similarity</primary></indexterm>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Returns a number that indicates the greatest similarity between
- the set of trigrams in the first string and any continuous extent
- of an ordered set of trigrams in the second string. For details, see
- the explanation below.
- </entry>
- </row>
- <row>
- <entry>
- <function>strict_word_similarity(text, text)</function>
- <indexterm><primary>strict_word_similarity</primary></indexterm>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Same as <function>word_similarity(text, text)</function>, but forces
- extent boundaries to match word boundaries. Since we don't have
- cross-word trigrams, this function actually returns greatest similarity
- between first string and any continuous extent of words of the second
- string.
- </entry>
- </row>
- <row>
- <entry><function>show_limit()</function><indexterm><primary>show_limit</primary></indexterm></entry>
- <entry><type>real</type></entry>
- <entry>
- Returns the current similarity threshold used by the <literal>%</literal>
- operator. This sets the minimum similarity between
- two words for them to be considered similar enough to
- be misspellings of each other, for example
- (<emphasis>deprecated</emphasis>).
- </entry>
- </row>
- <row>
- <entry><function>set_limit(real)</function><indexterm><primary>set_limit</primary></indexterm></entry>
- <entry><type>real</type></entry>
- <entry>
- Sets the current similarity threshold that is used by the <literal>%</literal>
- operator. The threshold must be between 0 and 1 (default is 0.3).
- Returns the same value passed in (<emphasis>deprecated</emphasis>).
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>similarity</primary></indexterm>
+ <function>similarity</function> ( <type>text</type>, <type>text</type> )
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns a number that indicates how similar the two arguments are.
+ The range of the result is zero (indicating that the two strings are
+ completely dissimilar) to one (indicating that the two strings are
+ identical).
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>show_trgm</primary></indexterm>
+ <function>show_trgm</function> ( <type>text</type> )
+ <returnvalue>text[]</returnvalue>
+ </para>
+ <para>
+ Returns an array of all the trigrams in the given string.
+ (In practice this is seldom useful except for debugging.)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>word_similarity</primary></indexterm>
+ <function>word_similarity</function> ( <type>text</type>, <type>text</type> )
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns a number that indicates the greatest similarity between
+ the set of trigrams in the first string and any continuous extent
+ of an ordered set of trigrams in the second string. For details, see
+ the explanation below.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>strict_word_similarity</primary></indexterm>
+ <function>strict_word_similarity</function> ( <type>text</type>, <type>text</type> )
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Same as <function>word_similarity</function>, but forces
+ extent boundaries to match word boundaries. Since we don't have
+ cross-word trigrams, this function actually returns greatest similarity
+ between first string and any continuous extent of words of the second
+ string.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>show_limit</primary></indexterm>
+ <function>show_limit</function> ()
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns the current similarity threshold used by the <literal>%</literal>
+ operator. This sets the minimum similarity between
+ two words for them to be considered similar enough to
+ be misspellings of each other, for example.
+ (<emphasis>Deprecated</emphasis>; instead use <command>SHOW</command>
+ <varname>pg_trgm.similarity_threshold</varname>.)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>set_limit</primary></indexterm>
+ <function>set_limit</function> ( <type>real</type> )
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Sets the current similarity threshold that is used by the <literal>%</literal>
+ operator. The threshold must be between 0 and 1 (default is 0.3).
+ Returns the same value passed in.
+ (<emphasis>Deprecated</emphasis>; instead use <command>SET</command>
+ <varname>pg_trgm.similarity_threshold</varname>.)
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<para>
</para>
<para>
- At the same time, <function>strict_word_similarity(text, text)</function>
+ At the same time, <function>strict_word_similarity</function>
selects an extent of words in the second string. In the example above,
- <function>strict_word_similarity(text, text)</function> would select the
+ <function>strict_word_similarity</function> would select the
extent of a single word <literal>'words'</literal>, whose set of trigrams is
<literal>{" w"," wo","wor","ord","rds","ds "}</literal>.
</para>
<para>
- Thus, the <function>strict_word_similarity(text, text)</function> function
+ Thus, the <function>strict_word_similarity</function> function
is useful for finding the similarity to whole words, while
- <function>word_similarity(text, text)</function> is more suitable for
+ <function>word_similarity</function> is more suitable for
finding the similarity for parts of words.
</para>
<table id="pgtrgm-op-table">
<title><filename>pg_trgm</filename> Operators</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><type>text</type> <literal>%</literal> <type>text</type></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Returns <literal>true</literal> if its arguments have a similarity that is
- greater than the current similarity threshold set by
- <varname>pg_trgm.similarity_threshold</varname>.
- </entry>
- </row>
- <row>
- <entry><type>text</type> <literal><%</literal> <type>text</type></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Returns <literal>true</literal> if the similarity between the trigram
- set in the first argument and a continuous extent of an ordered trigram
- set in the second argument is greater than the current word similarity
- threshold set by <varname>pg_trgm.word_similarity_threshold</varname>
- parameter.
- </entry>
- </row>
- <row>
- <entry><type>text</type> <literal>%></literal> <type>text</type></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Commutator of the <literal><%</literal> operator.
- </entry>
- </row>
- <row>
- <entry><type>text</type> <literal><<%</literal> <type>text</type></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Returns <literal>true</literal> if its second argument has a continuous
- extent of an ordered trigram set that matches word boundaries,
- and its similarity to the trigram set of the first argument is greater
- than the current strict word similarity threshold set by the
- <varname>pg_trgm.strict_word_similarity_threshold</varname> parameter.
- </entry>
- </row>
- <row>
- <entry><type>text</type> <literal>%>></literal> <type>text</type></entry>
- <entry><type>boolean</type></entry>
- <entry>
- Commutator of the <literal><<%</literal> operator.
- </entry>
- </row>
- <row>
- <entry><type>text</type> <literal><-></literal> <type>text</type></entry>
- <entry><type>real</type></entry>
- <entry>
- Returns the <quote>distance</quote> between the arguments, that is
- one minus the <function>similarity()</function> value.
- </entry>
- </row>
- <row>
- <entry>
- <type>text</type> <literal><<-></literal> <type>text</type>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Returns the <quote>distance</quote> between the arguments, that is
- one minus the <function>word_similarity()</function> value.
- </entry>
- </row>
- <row>
- <entry>
- <type>text</type> <literal><->></literal> <type>text</type>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Commutator of the <literal><<-></literal> operator.
- </entry>
- </row>
- <row>
- <entry>
- <type>text</type> <literal><<<-></literal> <type>text</type>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Returns the <quote>distance</quote> between the arguments, that is
- one minus the <function>strict_word_similarity()</function> value.
- </entry>
- </row>
- <row>
- <entry>
- <type>text</type> <literal><->>></literal> <type>text</type>
- </entry>
- <entry><type>real</type></entry>
- <entry>
- Commutator of the <literal><<<-></literal> operator.
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal>%</literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns <literal>true</literal> if its arguments have a similarity
+ that is greater than the current similarity threshold set by
+ <varname>pg_trgm.similarity_threshold</varname>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><%</literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns <literal>true</literal> if the similarity between the trigram
+ set in the first argument and a continuous extent of an ordered trigram
+ set in the second argument is greater than the current word similarity
+ threshold set by <varname>pg_trgm.word_similarity_threshold</varname>
+ parameter.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal>%></literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Commutator of the <literal><%</literal> operator.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><<%</literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns <literal>true</literal> if its second argument has a continuous
+ extent of an ordered trigram set that matches word boundaries,
+ and its similarity to the trigram set of the first argument is greater
+ than the current strict word similarity threshold set by the
+ <varname>pg_trgm.strict_word_similarity_threshold</varname> parameter.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal>%>></literal> <type>text</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Commutator of the <literal><<%</literal> operator.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><-></literal> <type>text</type>
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns the <quote>distance</quote> between the arguments, that is
+ one minus the <function>similarity()</function> value.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><<-></literal> <type>text</type>
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns the <quote>distance</quote> between the arguments, that is
+ one minus the <function>word_similarity()</function> value.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><->></literal> <type>text</type>
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Commutator of the <literal><<-></literal> operator.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><<<-></literal> <type>text</type>
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Returns the <quote>distance</quote> between the arguments, that is
+ one minus the <function>strict_word_similarity()</function> value.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>text</type> <literal><->>></literal> <type>text</type>
+ <returnvalue>real</returnvalue>
+ </para>
+ <para>
+ Commutator of the <literal><<<-></literal> operator.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
<para>
Generate data and load it into the standard tables,
replacing any data already present.
- The default is to generate data client-side (<literal>g</literal>)
- and transmit it over the connection.
</para>
<para>
With <literal>g</literal> (client-side data generation),
sent to the server. This uses the client/server bandwidth
extensively through a <command>COPY</command>.
Using <literal>g</literal> causes logging to print one message
- every 100,000 rows when generating data into
+ every 100,000 rows while generating data for the
<structname>pgbench_accounts</structname> table.
</para>
<para>
With <literal>G</literal> (server-side data generation),
- only limited queries are sent from <command>pgbench</command>
+ only small queries are sent from the <command>pgbench</command>
client and then data is actually generated in the server.
No significant bandwidth is required for this variant, but
the server will do more work.
Using <literal>G</literal> causes logging not to print any progress
- message when generating data into
- <structname>pgbench_accounts</structname> table.
+ message while generating data.
+ </para>
+ <para>
+ The default initialization behavior uses client-side data
+ generation (equivalent to <literal>g</literal>).
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
<para>
This utility, like most other <productname>PostgreSQL</productname> utilities,
uses the environment variables supported by <application>libpq</application>
(see <xref linkend="libpq-envars"/>).
</para>
-
+
<para>
The environment variable <envar>PG_COLOR</envar> specifies whether to use
color in diagnostic messages. Possible values are
<literal>never</literal>.
</para>
</refsect1>
-
+
<refsect1>
<title>Notes</title>
</para>
<table id="pgbench-automatic-variables">
- <title>Automatic Variables</title>
+ <title>pgbench Automatic Variables</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>Variable</entry>
<xref linkend="pgbench-operators"/> are built into <application>pgbench</application>
and may be used in expressions appearing in
<link linkend="pgbench-metacommand-set"><literal>\set</literal></link>.
+ The operators are listed in increasing precedence order.
+ Except as noted, operators taking two numeric inputs will produce
+ a double value if either input is double, otherwise they produce
+ an integer result.
</para>
- <table id="pgbench-operators">
- <title>pgbench Operators by Increasing Precedence</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>OR</literal></entry>
- <entry>logical or</entry>
- <entry><literal>5 or 0</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>AND</literal></entry>
- <entry>logical and</entry>
- <entry><literal>3 and 0</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal>NOT</literal></entry>
- <entry>logical not</entry>
- <entry><literal>not false</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>IS [NOT] (NULL|TRUE|FALSE)</literal></entry>
- <entry>value tests</entry>
- <entry><literal>1 is null</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal>ISNULL|NOTNULL</literal></entry>
- <entry>null tests</entry>
- <entry><literal>1 notnull</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>=</literal></entry>
- <entry>is equal</entry>
- <entry><literal>5 = 4</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal><></literal></entry>
- <entry>is not equal</entry>
- <entry><literal>5 <> 4</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>!=</literal></entry>
- <entry>is not equal</entry>
- <entry><literal>5 != 5</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal><</literal></entry>
- <entry>lower than</entry>
- <entry><literal>5 < 4</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal><=</literal></entry>
- <entry>lower or equal</entry>
- <entry><literal>5 <= 4</literal></entry>
- <entry><literal>FALSE</literal></entry>
- </row>
- <row>
- <entry><literal>></literal></entry>
- <entry>greater than</entry>
- <entry><literal>5 > 4</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>>=</literal></entry>
- <entry>greater or equal</entry>
- <entry><literal>5 >= 4</literal></entry>
- <entry><literal>TRUE</literal></entry>
- </row>
- <row>
- <entry><literal>|</literal></entry>
- <entry>integer bitwise OR</entry>
- <entry><literal>1 | 2</literal></entry>
- <entry><literal>3</literal></entry>
- </row>
- <row>
- <entry><literal>#</literal></entry>
- <entry>integer bitwise XOR</entry>
- <entry><literal>1 # 3</literal></entry>
- <entry><literal>2</literal></entry>
- </row>
- <row>
- <entry><literal>&</literal></entry>
- <entry>integer bitwise AND</entry>
- <entry><literal>1 & 3</literal></entry>
- <entry><literal>1</literal></entry>
- </row>
- <row>
- <entry><literal>~</literal></entry>
- <entry>integer bitwise NOT</entry>
- <entry><literal>~ 1</literal></entry>
- <entry><literal>-2</literal></entry>
- </row>
- <row>
- <entry><literal><<</literal></entry>
- <entry>integer bitwise shift left</entry>
- <entry><literal>1 << 2</literal></entry>
- <entry><literal>4</literal></entry>
- </row>
- <row>
- <entry><literal>>></literal></entry>
- <entry>integer bitwise shift right</entry>
- <entry><literal>8 >> 2</literal></entry>
- <entry><literal>2</literal></entry>
- </row>
- <row>
- <entry><literal>+</literal></entry>
- <entry>addition</entry>
- <entry><literal>5 + 4</literal></entry>
- <entry><literal>9</literal></entry>
- </row>
- <row>
- <entry><literal>-</literal></entry>
- <entry>subtraction</entry>
- <entry><literal>3 - 2.0</literal></entry>
- <entry><literal>1.0</literal></entry>
- </row>
- <row>
- <entry><literal>*</literal></entry>
- <entry>multiplication</entry>
- <entry><literal>5 * 4</literal></entry>
- <entry><literal>20</literal></entry>
- </row>
- <row>
- <entry><literal>/</literal></entry>
- <entry>division (integer truncates the results)</entry>
- <entry><literal>5 / 3</literal></entry>
- <entry><literal>1</literal></entry>
- </row>
- <row>
- <entry><literal>%</literal></entry>
- <entry>modulo</entry>
- <entry><literal>3 % 2</literal></entry>
- <entry><literal>1</literal></entry>
- </row>
- <row>
- <entry><literal>-</literal></entry>
- <entry>opposite</entry>
- <entry><literal>- 2.0</literal></entry>
- <entry><literal>-2.0</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <table id="pgbench-operators">
+ <title>pgbench Operators</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>boolean</replaceable> <literal>OR</literal> <replaceable>boolean</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Logical OR
+ </para>
+ <para>
+ <literal>5 or 0</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>boolean</replaceable> <literal>AND</literal> <replaceable>boolean</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Logical AND
+ </para>
+ <para>
+ <literal>3 and 0</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <literal>NOT</literal> <replaceable>boolean</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Logical NOT
+ </para>
+ <para>
+ <literal>not false</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>boolean</replaceable> <literal>IS [NOT] (NULL|TRUE|FALSE)</literal>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Boolean value tests
+ </para>
+ <para>
+ <literal>1 is null</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>value</replaceable> <literal>ISNULL|NOTNULL</literal>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Nullness tests
+ </para>
+ <para>
+ <literal>1 notnull</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>=</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Equal
+ </para>
+ <para>
+ <literal>5 = 4</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal><></literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Not equal
+ </para>
+ <para>
+ <literal>5 <> 4</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>!=</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Not equal
+ </para>
+ <para>
+ <literal>5 != 5</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal><</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Less than
+ </para>
+ <para>
+ <literal>5 < 4</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal><=</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Less than or equal to
+ </para>
+ <para>
+ <literal>5 <= 4</literal>
+ <returnvalue>FALSE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>></literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Greater than
+ </para>
+ <para>
+ <literal>5 > 4</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>>=</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>boolean</replaceable></returnvalue>
+ </para>
+ <para>
+ Greater than or equal to
+ </para>
+ <para>
+ <literal>5 >= 4</literal>
+ <returnvalue>TRUE</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal>|</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise OR
+ </para>
+ <para>
+ <literal>1 | 2</literal>
+ <returnvalue>3</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal>#</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise XOR
+ </para>
+ <para>
+ <literal>1 # 3</literal>
+ <returnvalue>2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal>&</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise AND
+ </para>
+ <para>
+ <literal>1 & 3</literal>
+ <returnvalue>1</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <literal>~</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise NOT
+ </para>
+ <para>
+ <literal>~ 1</literal>
+ <returnvalue>-2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal><<</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise shift left
+ </para>
+ <para>
+ <literal>1 << 2</literal>
+ <returnvalue>4</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal>>></literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Bitwise shift right
+ </para>
+ <para>
+ <literal>8 >> 2</literal>
+ <returnvalue>2</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>+</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>number</replaceable></returnvalue>
+ </para>
+ <para>
+ Addition
+ </para>
+ <para>
+ <literal>5 + 4</literal>
+ <returnvalue>9</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>-</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>number</replaceable></returnvalue>
+ </para>
+ <para>
+ Subtraction
+ </para>
+ <para>
+ <literal>3 - 2.0</literal>
+ <returnvalue>1.0</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>*</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>number</replaceable></returnvalue>
+ </para>
+ <para>
+ Multiplication
+ </para>
+ <para>
+ <literal>5 * 4</literal>
+ <returnvalue>20</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>number</replaceable> <literal>/</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>number</replaceable></returnvalue>
+ </para>
+ <para>
+ Division (truncates the result towards zero if both inputs are integers)
+ </para>
+ <para>
+ <literal>5 / 3</literal>
+ <returnvalue>1</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <replaceable>integer</replaceable> <literal>%</literal> <replaceable>integer</replaceable>
+ <returnvalue><replaceable>integer</replaceable></returnvalue>
+ </para>
+ <para>
+ Modulo (remainder)
+ </para>
+ <para>
+ <literal>3 % 2</literal>
+ <returnvalue>1</returnvalue>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <literal>-</literal> <replaceable>number</replaceable>
+ <returnvalue><replaceable>number</replaceable></returnvalue>
+ </para>
+ <para>
+ Negation
+ </para>
+ <para>
+ <literal>- 2.0</literal>
+ <returnvalue>-2.0</returnvalue>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</refsect2>
<refsect2 id="pgbench-builtin-functions">
<!-- list pgbench functions in alphabetical order -->
<table id="pgbench-functions">
<title>pgbench Functions</title>
- <tgroup cols="5">
+ <tgroup cols="1">
<thead>
<row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
</row>
</thead>
+
<tbody>
<row>
- <entry><literal><function>abs(<replaceable>a</replaceable>)</function></literal></entry>
- <entry>same as <replaceable>a</replaceable></entry>
- <entry>absolute value</entry>
- <entry><literal>abs(-17)</literal></entry>
- <entry><literal>17</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>abs</function> ( <replaceable>number</replaceable> )
+ <returnvalue></returnvalue> same type as input
+ </para>
+ <para>
+ Absolute value
+ </para>
+ <para>
+ <literal>abs(-17)</literal>
+ <returnvalue>17</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>debug(<replaceable>a</replaceable>)</function></literal></entry>
- <entry>same as <replaceable>a</replaceable> </entry>
- <entry>print <replaceable>a</replaceable> to <systemitem>stderr</systemitem>,
- and return <replaceable>a</replaceable></entry>
- <entry><literal>debug(5432.1)</literal></entry>
- <entry><literal>5432.1</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>debug</function> ( <replaceable>number</replaceable> )
+ <returnvalue></returnvalue> same type as input
+ </para>
+ <para>
+ Prints the argument to <systemitem>stderr</systemitem>,
+ and returns the argument.
+ </para>
+ <para>
+ <literal>debug(5432.1)</literal>
+ <returnvalue>5432.1</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>double(<replaceable>i</replaceable>)</function></literal></entry>
- <entry>double</entry>
- <entry>cast to double</entry>
- <entry><literal>double(5432)</literal></entry>
- <entry><literal>5432.0</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>double</function> ( <replaceable>number</replaceable> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ Casts to double.
+ </para>
+ <para>
+ <literal>double(5432)</literal>
+ <returnvalue>5432.0</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>exp(<replaceable>x</replaceable>)</function></literal></entry>
- <entry>double</entry>
- <entry>exponential</entry>
- <entry><literal>exp(1.0)</literal></entry>
- <entry><literal>2.718281828459045</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>exp</function> ( <replaceable>number</replaceable> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ Exponential (<literal>e</literal> raised to the given power)
+ </para>
+ <para>
+ <literal>exp(1.0)</literal>
+ <returnvalue>2.718281828459045</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>greatest(<replaceable>a</replaceable> [, <replaceable>...</replaceable> ] )</function></literal></entry>
- <entry>double if any <replaceable>a</replaceable> is double, else integer</entry>
- <entry>largest value among arguments</entry>
- <entry><literal>greatest(5, 4, 3, 2)</literal></entry>
- <entry><literal>5</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>greatest</function> ( <replaceable>number</replaceable> <optional>, <literal>...</literal> </optional> )
+ <returnvalue></returnvalue> <type>double</type> if any argument is double, else <type>integer</type>
+ </para>
+ <para>
+ Selects the largest value among the arguments.
+ </para>
+ <para>
+ <literal>greatest(5, 4, 3, 2)</literal>
+ <returnvalue>5</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>hash(<replaceable>a</replaceable> [, <replaceable>seed</replaceable> ] )</function></literal></entry>
- <entry>integer</entry>
- <entry>alias for <literal>hash_murmur2()</literal></entry>
- <entry><literal>hash(10, 5432)</literal></entry>
- <entry><literal>-5817877081768721676</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hash</function> ( <parameter>value</parameter> <optional>, <parameter>seed</parameter> </optional> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ This is an alias for <function>hash_murmur2</function>.
+ </para>
+ <para>
+ <literal>hash(10, 5432)</literal>
+ <returnvalue>-5817877081768721676</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>hash_fnv1a(<replaceable>a</replaceable> [, <replaceable>seed</replaceable> ] )</function></literal></entry>
- <entry>integer</entry>
- <entry><ulink url="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function">FNV-1a hash</ulink></entry>
- <entry><literal>hash_fnv1a(10, 5432)</literal></entry>
- <entry><literal>-7793829335365542153</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hash_fnv1a</function> ( <parameter>value</parameter> <optional>, <parameter>seed</parameter> </optional> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes <ulink url="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function">FNV-1a hash</ulink>.
+ </para>
+ <para>
+ <literal>hash_fnv1a(10, 5432)</literal>
+ <returnvalue>-7793829335365542153</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>hash_murmur2(<replaceable>a</replaceable> [, <replaceable>seed</replaceable> ] )</function></literal></entry>
- <entry>integer</entry>
- <entry><ulink url="https://en.wikipedia.org/wiki/MurmurHash">MurmurHash2 hash</ulink></entry>
- <entry><literal>hash_murmur2(10, 5432)</literal></entry>
- <entry><literal>-5817877081768721676</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>hash_murmur2</function> ( <parameter>value</parameter> <optional>, <parameter>seed</parameter> </optional> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes <ulink url="https://en.wikipedia.org/wiki/MurmurHash">MurmurHash2 hash</ulink>.
+ </para>
+ <para>
+ <literal>hash_murmur2(10, 5432)</literal>
+ <returnvalue>-5817877081768721676</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>int(<replaceable>x</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>cast to int</entry>
- <entry><literal>int(5.4 + 3.8)</literal></entry>
- <entry><literal>9</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>int</function> ( <replaceable>number</replaceable> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Casts to integer.
+ </para>
+ <para>
+ <literal>int(5.4 + 3.8)</literal>
+ <returnvalue>9</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>least(<replaceable>a</replaceable> [, <replaceable>...</replaceable> ] )</function></literal></entry>
- <entry>double if any <replaceable>a</replaceable> is double, else integer</entry>
- <entry>smallest value among arguments</entry>
- <entry><literal>least(5, 4, 3, 2.1)</literal></entry>
- <entry><literal>2.1</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>least</function> ( <replaceable>number</replaceable> <optional>, <literal>...</literal> </optional> )
+ <returnvalue></returnvalue> <type>double</type> if any argument is double, else <type>integer</type>
+ </para>
+ <para>
+ Selects the smallest value among the arguments.
+ </para>
+ <para>
+ <literal>least(5, 4, 3, 2.1)</literal>
+ <returnvalue>2.1</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>ln(<replaceable>x</replaceable>)</function></literal></entry>
- <entry>double</entry>
- <entry>natural logarithm</entry>
- <entry><literal>ln(2.718281828459045)</literal></entry>
- <entry><literal>1.0</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>ln</function> ( <replaceable>number</replaceable> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ Natural logarithm
+ </para>
+ <para>
+ <literal>ln(2.718281828459045)</literal>
+ <returnvalue>1.0</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>mod(<replaceable>i</replaceable>, <replaceable>j</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>modulo</entry>
- <entry><literal>mod(54, 32)</literal></entry>
- <entry><literal>22</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+<function>mod</function> ( <replaceable>integer</replaceable>, <replaceable>integer</replaceable> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Modulo (remainder)
+ </para>
+ <para>
+ <literal>mod(54, 32)</literal>
+ <returnvalue>22</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pi()</function></literal></entry>
- <entry>double</entry>
- <entry>value of the constant <phrase role="symbol_font">π</phrase></entry>
- <entry><literal>pi()</literal></entry>
- <entry><literal>3.14159265358979323846</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pi</function> ()
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ Approximate value of <phrase role="symbol_font">π</phrase>
+ </para>
+ <para>
+ <literal>pi()</literal>
+ <returnvalue>3.14159265358979323846</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pow(<replaceable>x</replaceable>, <replaceable>y</replaceable>)</function>, <function>power(<replaceable>x</replaceable>, <replaceable>y</replaceable>)</function></literal></entry>
- <entry>double</entry>
- <entry>exponentiation</entry>
- <entry><literal>pow(2.0, 10)</literal>, <literal>power(2.0, 10)</literal></entry>
- <entry><literal>1024.0</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pow</function> ( <parameter>x</parameter>, <parameter>y</parameter> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>power</function> ( <parameter>x</parameter>, <parameter>y</parameter> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ <parameter>x</parameter> raised to the power of <parameter>y</parameter>
+ </para>
+ <para>
+ <literal>pow(2.0, 10)</literal>
+ <returnvalue>1024.0</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>random(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>uniformly-distributed random integer in <literal>[lb, ub]</literal></entry>
- <entry><literal>random(1, 10)</literal></entry>
- <entry>an integer between <literal>1</literal> and <literal>10</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>random</function> ( <parameter>lb</parameter>, <parameter>ub</parameter> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes a uniformly-distributed random integer in <literal>[lb,
+ ub]</literal>.
+ </para>
+ <para>
+ <literal>random(1, 10)</literal>
+ <returnvalue>an integer between 1 and 10</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>random_exponential(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>, <replaceable>parameter</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>exponentially-distributed random integer in <literal>[lb, ub]</literal>,
- see below</entry>
- <entry><literal>random_exponential(1, 10, 3.0)</literal></entry>
- <entry>an integer between <literal>1</literal> and <literal>10</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>random_exponential</function> ( <parameter>lb</parameter>, <parameter>ub</parameter>, <parameter>parameter</parameter> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes an exponentially-distributed random integer in <literal>[lb,
+ ub]</literal>, see below.
+ </para>
+ <para>
+ <literal>random_exponential(1, 10, 3.0)</literal>
+ <returnvalue>an integer between 1 and 10</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>random_gaussian(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>, <replaceable>parameter</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>Gaussian-distributed random integer in <literal>[lb, ub]</literal>,
- see below</entry>
- <entry><literal>random_gaussian(1, 10, 2.5)</literal></entry>
- <entry>an integer between <literal>1</literal> and <literal>10</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>random_gaussian</function> ( <parameter>lb</parameter>, <parameter>ub</parameter>, <parameter>parameter</parameter> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes a gaussian-distributed random integer in <literal>[lb,
+ ub]</literal>, see below.
+ </para>
+ <para>
+ <literal>random_gaussian(1, 10, 2.5)</literal>
+ <returnvalue>an integer between 1 and 10</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>random_zipfian(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>, <replaceable>parameter</replaceable>)</function></literal></entry>
- <entry>integer</entry>
- <entry>Zipfian-distributed random integer in <literal>[lb, ub]</literal>,
- see below</entry>
- <entry><literal>random_zipfian(1, 10, 1.5)</literal></entry>
- <entry>an integer between <literal>1</literal> and <literal>10</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>random_zipfian</function> ( <parameter>lb</parameter>, <parameter>ub</parameter>, <parameter>parameter</parameter> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Computes a Zipfian-distributed random integer in <literal>[lb,
+ ub]</literal>, see below.
+ </para>
+ <para>
+ <literal>random_zipfian(1, 10, 1.5)</literal>
+ <returnvalue>an integer between 1 and 10</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>sqrt(<replaceable>x</replaceable>)</function></literal></entry>
- <entry>double</entry>
- <entry>square root</entry>
- <entry><literal>sqrt(2.0)</literal></entry>
- <entry><literal>1.414213562</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sqrt</function> ( <replaceable>number</replaceable> )
+ <returnvalue>double</returnvalue>
+ </para>
+ <para>
+ Square root
+ </para>
+ <para>
+ <literal>sqrt(2.0)</literal>
+ <returnvalue>1.414213562</returnvalue>
+ </para></entry>
</row>
</tbody>
- </tgroup>
+ </tgroup>
</table>
<para>
format is used for the log files:
<synopsis>
-<replaceable>interval_start</replaceable> <replaceable>num_transactions</replaceable> <replaceable>sum_latency</replaceable> <replaceable>sum_latency_2</replaceable> <replaceable>min_latency</replaceable> <replaceable>max_latency</replaceable> <optional> <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable> <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable> <optional> <replaceable>skipped</replaceable> </optional> </optional>
+<replaceable>interval_start</replaceable> <replaceable>num_transactions</replaceable>&zwsp; <replaceable>sum_latency</replaceable> <replaceable>sum_latency_2</replaceable> <replaceable>min_latency</replaceable> <replaceable>max_latency</replaceable>&zwsp; <optional> <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable> <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable> <optional> <replaceable>skipped</replaceable> </optional> </optional>
</synopsis>
where
<table id="seg-input-examples">
<title>Examples of Valid <type>seg</type> Input</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<tbody>
<row>
<entry><literal>5.0</literal></entry>
<table id="seg-gist-operators">
<title>Seg GiST Operators</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry><literal>[a, b] << [c, d]</literal></entry>
- <entry>[a, b] is entirely to the left of [c, d]. That is, [a,
- b] << [c, d] is true if b < c and false otherwise.</entry>
- </row>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal><<</literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is the first <type>seg</type> entirely to the left of the second?
+ [a, b] << [c, d] is true if b < c.
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] >> [c, d]</literal></entry>
- <entry>[a, b] is entirely to the right of [c, d]. That is, [a,
- b] >> [c, d] is true if a > d and false otherwise.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>>></literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is the first <type>seg</type> entirely to the right of the second?
+ [a, b] >> [c, d] is true if a > d.
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] &< [c, d]</literal></entry>
- <entry>Overlaps or is left of — This might be better read
- as <quote>does not extend to right of</quote>. It is true when
- b <= d.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>&<</literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does the first <type>seg</type> not extend to the right of the
+ second?
+ [a, b] &< [c, d] is true if b <= d.
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] &> [c, d]</literal></entry>
- <entry>Overlaps or is right of — This might be better read
- as <quote>does not extend to left of</quote>. It is true when
- a >= c.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>&></literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does the first <type>seg</type> not extend to the left of the
+ second?
+ [a, b] &> [c, d] is true if a >= c.
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] = [c, d]</literal></entry>
- <entry>Same as — The segments [a, b] and [c, d] are
- identical, that is, a = c and b = d.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>=</literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Are the two <type>seg</type>s equal?
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] && [c, d]</literal></entry>
- <entry>The segments [a, b] and [c, d] overlap.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>&&</literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Do the two <type>seg</type>s overlap?
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] @> [c, d]</literal></entry>
- <entry>The segment [a, b] contains the segment [c, d], that is,
- a <= c and b >= d.</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal>@></literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does the first <type>seg</type> contain the second?
+ </para></entry>
+ </row>
- <row>
- <entry><literal>[a, b] <@ [c, d]</literal></entry>
- <entry>The segment [a, b] is contained in [c, d], that is, a
- >= c and b <= d.</entry>
- </row>
- </tbody>
- </tgroup>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>seg</type> <literal><@</literal> <type>seg</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is the first <type>seg</type> contained in the second?
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<para>
</para>
<para>
- The standard B-tree operators are also provided, for example
-
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>[a, b] < [c, d]</literal></entry>
- <entry>Less than</entry>
- </row>
-
- <row>
- <entry><literal>[a, b] > [c, d]</literal></entry>
- <entry>Greater than</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- These operators do not make a lot of sense for any practical
- purpose but sorting. These operators first compare (a) to (c),
+ In addition to the above operators, the usual comparison
+ operators shown in <xref linkend="functions-comparison-op-table"/> are
+ available for type <type>seg</type>. These operators
+ first compare (a) to (c),
and if these are equal, compare (b) to (d). That results in
reasonably good sorting in most cases, which is useful if
you want to use ORDER BY with this type.
(1 row)
regression=# SELECT sepgsql_setcon('unconfined_u:unconfined_r:unconfined_t:s0-s0:c1.c4');
- sepgsql_setcon
+ sepgsql_setcon
----------------
t
(1 row)
<table id="sepgsql-functions-table">
<title>Sepgsql Functions</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><literal>sepgsql_getcon() returns text</literal></entry>
- <entry>
- Returns the client domain, the current security label of the client.
- </entry>
- </row>
- <row>
- <entry><literal>sepgsql_setcon(text) returns bool</literal></entry>
- <entry>
- Switches the client domain of the current session to the new domain,
- if allowed by the security policy.
- It also accepts <literal>NULL</literal> input as a request to transition
- to the client's original domain.
- </entry>
- </row>
- <row>
- <entry><literal>sepgsql_mcstrans_in(text) returns text</literal></entry>
- <entry>Translates the given qualified MLS/MCS range into raw format if
- the mcstrans daemon is running.
- </entry>
- </row>
- <row>
- <entry><literal>sepgsql_mcstrans_out(text) returns text</literal></entry>
- <entry>Translates the given raw MLS/MCS range into qualified format if
- the mcstrans daemon is running.
- </entry>
- </row>
- <row>
- <entry><literal>sepgsql_restorecon(text) returns bool</literal></entry>
- <entry>
- Sets up initial security labels for all objects within the
- current database. The argument may be NULL, or the name of a specfile
- to be used as alternative of the system default.
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sepgsql_getcon</function> ()
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the client domain, the current security label of the client.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sepgsql_setcon</function> ( <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Switches the client domain of the current session to the new domain,
+ if allowed by the security policy.
+ It also accepts <literal>NULL</literal> input as a request to transition
+ to the client's original domain.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sepgsql_mcstrans_in</function> ( <type>text</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Translates the given qualified MLS/MCS range into raw format if
+ the mcstrans daemon is running.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sepgsql_mcstrans_out</function> ( <type>text</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Translates the given raw MLS/MCS range into qualified format if
+ the mcstrans daemon is running.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>sepgsql_restorecon</function> ( <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Sets up initial security labels for all objects within the
+ current database. The argument may be <literal>NULL</literal>, or the
+ name of a specfile to be used as alternative of the system default.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
<title>Functions Provided</title>
<para>
- <xref linkend="tablefunc-functions"/> shows the functions provided
+ <xref linkend="tablefunc-functions"/> summarizes the functions provided
by the <filename>tablefunc</filename> module.
</para>
<table id="tablefunc-functions">
<title><filename>tablefunc</filename> Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><function>normal_rand(int numvals, float8 mean, float8 stddev)</function></entry>
- <entry><type>setof float8</type></entry>
- <entry>
- Produces a set of normally distributed random values
- </entry>
- </row>
- <row>
- <entry><function>crosstab(text sql)</function></entry>
- <entry><type>setof record</type></entry>
- <entry>
- Produces a <quote>pivot table</quote> containing
- row names plus <replaceable>N</replaceable> value columns, where
- <replaceable>N</replaceable> is determined by the row type specified in the calling
- query
- </entry>
- </row>
- <row>
- <entry><function>crosstab<replaceable>N</replaceable>(text sql)</function></entry>
- <entry><type>setof table_crosstab_<replaceable>N</replaceable></type></entry>
- <entry>
- Produces a <quote>pivot table</quote> containing
- row names plus <replaceable>N</replaceable> value columns.
- <function>crosstab2</function>, <function>crosstab3</function>, and
- <function>crosstab4</function> are predefined, but you can create additional
- <function>crosstab<replaceable>N</replaceable></function> functions as described below
- </entry>
- </row>
- <row>
- <entry><function>crosstab(text source_sql, text category_sql)</function></entry>
- <entry><type>setof record</type></entry>
- <entry>
- Produces a <quote>pivot table</quote>
- with the value columns specified by a second query
- </entry>
- </row>
- <row>
- <entry><function>crosstab(text sql, int N)</function></entry>
- <entry><type>setof record</type></entry>
- <entry>
- <para>Obsolete version of <function>crosstab(text)</function>.
- The parameter <replaceable>N</replaceable> is now ignored, since the number of
- value columns is always determined by the calling query
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>normal_rand</function> ( <parameter>numvals</parameter> <type>integer</type>, <parameter>mean</parameter> <type>float8</type>, <parameter>stddev</parameter> <type>float8</type> )
+ <returnvalue>setof float8</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- connectby(text relname, text keyid_fld, text parent_keyid_fld
- [, text orderby_fld ], text start_with, int max_depth
- [, text branch_delim ])
- </function>
- <indexterm><primary>connectby</primary></indexterm>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- Produces a representation of a hierarchical tree structure
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <para>
+ Produces a set of normally distributed random values.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>crosstab</function> ( <parameter>sql</parameter> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Produces a <quote>pivot table</quote> containing
+ row names plus <replaceable>N</replaceable> value columns, where
+ <replaceable>N</replaceable> is determined by the row type specified
+ in the calling query.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>crosstab<replaceable>N</replaceable></function> ( <parameter>sql</parameter> <type>text</type> )
+ <returnvalue>setof table_crosstab_<replaceable>N</replaceable></returnvalue>
+ </para>
+ <para>
+ Produces a <quote>pivot table</quote> containing
+ row names plus <replaceable>N</replaceable> value columns.
+ <function>crosstab2</function>, <function>crosstab3</function>, and
+ <function>crosstab4</function> are predefined, but you can create additional
+ <function>crosstab<replaceable>N</replaceable></function> functions as described below.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>crosstab</function> ( <parameter>source_sql</parameter> <type>text</type>, <parameter>category_sql</parameter> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Produces a <quote>pivot table</quote>
+ with the value columns specified by a second query.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>crosstab</function> ( <parameter>sql</parameter> <type>text</type>, <parameter>N</parameter> <type>integer</type> )
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Obsolete version of <function>crosstab(text)</function>.
+ The parameter <parameter>N</parameter> is now ignored, since the
+ number of value columns is always determined by the calling query.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>connectby</primary></indexterm>
+ <function>connectby</function> ( <parameter>relname</parameter> <type>text</type>, <parameter>keyid_fld</parameter> <type>text</type>, <parameter>parent_keyid_fld</parameter> <type>text</type>
+ <optional>, <parameter>orderby_fld</parameter> <type>text</type> </optional>, <parameter>start_with</parameter> <type>text</type>, <parameter>max_depth</parameter> <type>integer</type>
+ <optional>, <parameter>branch_delim</parameter> <type>text</type> </optional> )
+ <returnvalue>setof record</returnvalue>
+ </para>
+ <para>
+ Produces a representation of a hierarchical tree structure.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<sect3>
<table id="uuid-ossp-functions">
<title>Functions for UUID Generation</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><function>uuid_generate_v1()</function><indexterm><primary>uuid_generate_v1</primary></indexterm></entry>
- <entry>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>uuid_generate_v1</primary></indexterm>
+ <function>uuid_generate_v1</function> ()
+ <returnvalue>uuid</returnvalue>
+ </para>
<para>
- This function generates a version 1 UUID. This involves the MAC
+ Generates a version 1 UUID. This involves the MAC
address of the computer and a time stamp. Note that UUIDs of this
kind reveal the identity of the computer that created the identifier
and the time at which it did so, which might make it unsuitable for
certain security-sensitive applications.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>uuid_generate_v1mc</primary></indexterm>
+ <function>uuid_generate_v1mc</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><function>uuid_generate_v1mc()</function><indexterm><primary>uuid_generate_v1mc</primary></indexterm></entry>
- <entry>
<para>
- This function generates a version 1 UUID but uses a random multicast
+ Generates a version 1 UUID, but uses a random multicast
MAC address instead of the real MAC address of the computer.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>uuid_generate_v3</primary></indexterm>
+ <function>uuid_generate_v3</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> )
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><function>uuid_generate_v3(namespace uuid, name text)</function><indexterm><primary>uuid_generate_v3</primary></indexterm></entry>
- <entry>
<para>
- This function generates a version 3 UUID in the given namespace using
+ Generates a version 3 UUID in the given namespace using
the specified input name. The namespace should be one of the special
- constants produced by the <function>uuid_ns_*()</function> functions shown
- in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID in theory.) The name is an identifier
- in the selected namespace.
+ constants produced by the <function>uuid_ns_*()</function> functions
+ shown in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID
+ in theory.) The name is an identifier in the selected namespace.
</para>
-
<para>
For example:
derived from the generated UUID.
The generation of UUIDs by this method has no random or
environment-dependent element and is therefore reproducible.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_generate_v4</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_generate_v4()</literal></entry>
- <entry>
<para>
- This function generates a version 4 UUID, which is derived entirely
+ Generates a version 4 UUID, which is derived entirely
from random numbers.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_generate_v5</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> )
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_generate_v5(namespace uuid, name text)</literal></entry>
- <entry>
<para>
- This function generates a version 5 UUID, which works like a version 3
+ Generates a version 5 UUID, which works like a version 3
UUID except that SHA-1 is used as a hashing method. Version 5 should
be preferred over version 3 because SHA-1 is thought to be more secure
than MD5.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
<table id="uuid-ossp-constants">
<title>Functions Returning UUID Constants</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><literal>uuid_nil()</literal></entry>
- <entry>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_nil</function> ()
+ <returnvalue>uuid</returnvalue>
+ </para>
<para>
- A <quote>nil</quote> UUID constant, which does not occur as a real UUID.
+ Returns a <quote>nil</quote> UUID constant, which does not occur as a
+ real UUID.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_ns_dns</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_ns_dns()</literal></entry>
- <entry>
<para>
- Constant designating the DNS namespace for UUIDs.
+ Returns a constant designating the DNS namespace for UUIDs.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_ns_url</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_ns_url()</literal></entry>
- <entry>
<para>
- Constant designating the URL namespace for UUIDs.
+ Returns a constant designating the URL namespace for UUIDs.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_ns_oid</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_ns_oid()</literal></entry>
- <entry>
<para>
- Constant designating the ISO object identifier (OID) namespace for
+ Returns a constant designating the ISO object identifier (OID) namespace for
UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs
used in <productname>PostgreSQL</productname>.)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>uuid_ns_x500</function> ()
+ <returnvalue>uuid</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry><literal>uuid_ns_x500()</literal></entry>
- <entry>
<para>
- Constant designating the X.500 distinguished name (DN) namespace for
- UUIDs.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
+ Returns a constant designating the X.500 distinguished name (DN)
+ namespace for UUIDs.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
<para>
<xref linkend="xml2-functions-table"/> shows the functions provided by this module.
These functions provide straightforward XML parsing and XPath queries.
- All arguments are of type <type>text</type>, so for brevity that is not shown.
</para>
<table id="xml2-functions-table">
- <title>Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Returns</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <function>
- xml_valid(document)
- </function>
- </entry>
- <entry>
- <type>bool</type>
- </entry>
- <entry>
+ <title><filename>xml2</filename> Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xml_valid</function> ( <parameter>document</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
<para>
- This parses the document text in its parameter and returns true if the
+ Parses the given document and returns true if the
document is well-formed XML. (Note: this is an alias for the standard
PostgreSQL function <function>xml_is_well_formed()</function>. The
name <function>xml_valid()</function> is technically incorrect since validity
and well-formedness have different meanings in XML.)
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_string</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_string(document, query)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry morerows="2">
<para>
- These functions evaluate the XPath query on the supplied document, and
- cast the result to the specified type.
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <type>text</type>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_number</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
+ <returnvalue>real</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_number(document, query)
- </function>
- </entry>
- <entry>
- <type>float4</type>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_bool(document, query)
- </function>
- </entry>
- <entry>
- <type>bool</type>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_nodeset(document, query, toptag, itemtag)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry>
<para>
- This evaluates query on document and wraps the result in XML tags. If
- the result is multivalued, the output will look like:
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <type>real</type>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_bool</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <type>boolean</type>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_nodeset</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type>, <parameter>toptag</parameter> <type>text</type>, <parameter>itemtag</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Evaluates the query on the document and wraps the result in XML
+ tags. If the result is multivalued, the output will look like:
<synopsis>
<toptag>
<itemtag>Value 1 which could be an XML fragment</itemtag>
<itemtag>Value 2....</itemtag>
</toptag>
</synopsis>
- If either <literal>toptag</literal> or <literal>itemtag</literal> is an empty string, the relevant tag is omitted.
+ If either <parameter>toptag</parameter>
+ or <parameter>itemtag</parameter> is an empty string, the relevant tag
+ is omitted.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_nodeset</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type>, <parameter>itemtag</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_nodeset(document, query)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry>
<para>
- Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits both tags.
+ Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits <parameter>toptag</parameter>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_nodeset</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_nodeset(document, query, itemtag)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry>
<para>
- Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits <literal>toptag</literal>.
+ Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits both tags.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_list</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type>, <parameter>separator</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_list(document, query, separator)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry>
<para>
- This function returns multiple values separated by the specified
- separator, for example <literal>Value 1,Value 2,Value 3</literal> if
- separator is <literal>,</literal>.
+ Evaluates the query on the document and returns multiple values
+ separated by the specified separator, for example <literal>Value
+ 1,Value 2,Value 3</literal> if <parameter>separator</parameter>
+ is <literal>,</literal>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>xpath_list</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
</para>
- </entry>
- </row>
- <row>
- <entry>
- <function>
- xpath_list(document, query)
- </function>
- </entry>
- <entry>
- <type>text</type>
- </entry>
- <entry>
- This is a wrapper for the above function that uses <literal>,</literal>
- as the separator.
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <para>
+ This is a wrapper for the above function that uses <literal>,</literal>
+ as the separator.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</sect2>
<table id="xml2-xpath-table-parameters">
<title><function>xpath_table</function> Parameters</title>
<tgroup cols="2">
+ <colspec colname="col1" colwidth="1*"/>
+ <colspec colname="col2" colwidth="2*"/>
<thead>
<row>
<entry>Parameter</entry>
projects / users / rhaas / postgres.git / commitdiff