open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Split func.sgml into more manageable pieces

Browse Source 
func.sgml has grown over the years to the point where it is very
difficult to manage. This commit splits out each sect1 piece into its
own file, which is then included in the main file, so that the built
documentation should be identical to the pre-split documentation. All
these new files are placed in a new "func" subdirectory, and the
previous func.sgml is removed.

Done using scripts developed by:

Author: jian he <jian.universality@gmail.com>

Discussion: https://postgr.es/m/CACJufxFgAh1--EMwOjMuANe=VTmjkNaZjH+AzSe04-8ZCGiESA@mail.gmail.com
pull/239/head
Andrew Dunstan 1 month ago
parent 6ae268cf28
commit 4e23c9ef65
35 changed files with 32109 additions and 32076 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 5
      doc/src/sgml/filelist.sgml
  2. 32075
      doc/src/sgml/func.sgml
  3. 40
      doc/src/sgml/func/allfiles.sgml
  4. 2962
      doc/src/sgml/func/func-admin.sgml
  5. 1418
      doc/src/sgml/func/func-aggregate.sgml
  6. 646
      doc/src/sgml/func/func-array.sgml
  7. 854
      doc/src/sgml/func/func-binarystring.sgml
  8. 358
      doc/src/sgml/func/func-bitstring.sgml
  9. 638
      doc/src/sgml/func/func-comparison.sgml
  10. 336
      doc/src/sgml/func/func-comparisons.sgml
  11. 283
      doc/src/sgml/func/func-conditional.sgml
  12. 2200
      doc/src/sgml/func/func-datetime.sgml
  13. 121
      doc/src/sgml/func/func-enum.sgml
  14. 332
      doc/src/sgml/func/func-event-triggers.sgml
  15. 1193
      doc/src/sgml/func/func-formatting.sgml
  16. 1261
      doc/src/sgml/func/func-geometry.sgml
  17. 3790
      doc/src/sgml/func/func-info.sgml
  18. 3945
      doc/src/sgml/func/func-json.sgml
  19. 146
      doc/src/sgml/func/func-logical.sgml
  20. 2471
      doc/src/sgml/func/func-matching.sgml
  21. 1615
      doc/src/sgml/func/func-math.sgml
  22. 78
      doc/src/sgml/func/func-merge-support.sgml
  23. 592
      doc/src/sgml/func/func-net.sgml
  24. 1053
      doc/src/sgml/func/func-range.sgml
  25. 195
      doc/src/sgml/func/func-sequence.sgml
  26. 306
      doc/src/sgml/func/func-srf.sgml
  27. 85
      doc/src/sgml/func/func-statistics.sgml
  28. 1818
      doc/src/sgml/func/func-string.sgml
  29. 349
      doc/src/sgml/func/func-subquery.sgml
  30. 1046
      doc/src/sgml/func/func-textsearch.sgml
  31. 135
      doc/src/sgml/func/func-trigger.sgml
  32. 188
      doc/src/sgml/func/func-uuid.sgml
  33. 284
      doc/src/sgml/func/func-window.sgml
  34. 1283
      doc/src/sgml/func/func-xml.sgml
  35. 84
      doc/src/sgml/func/func.sgml

5
doc/src/sgml/filelist.sgml
Unescape View File

@ -17,7 +17,10 @@
<!ENTITY datatype SYSTEM "datatype.sgml">
<!ENTITY ddl SYSTEM "ddl.sgml">
<!ENTITY dml SYSTEM "dml.sgml">
<!ENTITY func SYSTEM "func.sgml">
<!ENTITY % allfiles_func SYSTEM "func/allfiles.sgml">
%allfiles_func;
<!ENTITY indices SYSTEM "indices.sgml">
<!ENTITY json SYSTEM "json.sgml">
<!ENTITY mvcc SYSTEM "mvcc.sgml">

32075
doc/src/sgml/func.sgml
View File

File diff suppressed because it is too large Load Diff

40
doc/src/sgml/func/allfiles.sgml
Unescape View File

@ -0,0 +1,40 @@
<!--
doc/src/sgml/func/allfiles.sgml
PostgreSQL documentation
Complete list of usable sgml source files in this directory.
-->
<!-- function references -->
<!ENTITY func SYSTEM "func.sgml">
<!ENTITY func-logical SYSTEM "func-logical.sgml">
<!ENTITY func-comparison SYSTEM "func-comparison.sgml">
<!ENTITY func-math SYSTEM "func-math.sgml">
<!ENTITY func-string SYSTEM "func-string.sgml">
<!ENTITY func-binarystring SYSTEM "func-binarystring.sgml">
<!ENTITY func-bitstring SYSTEM "func-bitstring.sgml">
<!ENTITY func-matching SYSTEM "func-matching.sgml">
<!ENTITY func-formatting SYSTEM "func-formatting.sgml">
<!ENTITY func-datetime SYSTEM "func-datetime.sgml">
<!ENTITY func-enum SYSTEM "func-enum.sgml">
<!ENTITY func-geometry SYSTEM "func-geometry.sgml">
<!ENTITY func-net SYSTEM "func-net.sgml">
<!ENTITY func-textsearch SYSTEM "func-textsearch.sgml">
<!ENTITY func-uuid SYSTEM "func-uuid.sgml">
<!ENTITY func-xml SYSTEM "func-xml.sgml">
<!ENTITY func-json SYSTEM "func-json.sgml">
<!ENTITY func-sequence SYSTEM "func-sequence.sgml">
<!ENTITY func-conditional SYSTEM "func-conditional.sgml">
<!ENTITY func-array SYSTEM "func-array.sgml">
<!ENTITY func-range SYSTEM "func-range.sgml">
<!ENTITY func-aggregate SYSTEM "func-aggregate.sgml">
<!ENTITY func-window SYSTEM "func-window.sgml">
<!ENTITY func-merge-support SYSTEM "func-merge-support.sgml">
<!ENTITY func-subquery SYSTEM "func-subquery.sgml">
<!ENTITY func-comparisons SYSTEM "func-comparisons.sgml">
<!ENTITY func-srf SYSTEM "func-srf.sgml">
<!ENTITY func-info SYSTEM "func-info.sgml">
<!ENTITY func-admin SYSTEM "func-admin.sgml">
<!ENTITY func-trigger SYSTEM "func-trigger.sgml">
<!ENTITY func-event-triggers SYSTEM "func-event-triggers.sgml">
<!ENTITY func-statistics SYSTEM "func-statistics.sgml">

2962
doc/src/sgml/func/func-admin.sgml
View File

File diff suppressed because it is too large Load Diff

1418
doc/src/sgml/func/func-aggregate.sgml
View File

File diff suppressed because it is too large Load Diff

646
doc/src/sgml/func/func-array.sgml
Unescape View File

@ -0,0 +1,646 @@
<sect1 id="functions-array">
<title>Array Functions and Operators</title>
<para>
<xref linkend="array-operators-table"/> shows the specialized operators
available for array types.
In addition to those, the usual comparison operators shown in <xref
linkend="functions-comparison-op-table"/> are available for
arrays. The comparison operators compare the array contents
element-by-element, using the default B-tree comparison function for
the element data type, and sort based on the first difference.
In multidimensional arrays the elements are visited in row-major order
(last subscript varies most rapidly).
If the contents of two arrays are equal but the dimensionality is
different, the first difference in the dimensionality information
determines the sort order.
</para>
<table id="array-operators-table">
<title>Array 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">
<type>anyarray</type> <literal>@&gt;</literal> <type>anyarray</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Does the first array contain the second, that is, does each element
appearing in the second array equal some element of the first array?
(Duplicates are not treated specially,
thus <literal>ARRAY[1]</literal> and <literal>ARRAY[1,1]</literal> are
each considered to contain the other.)
</para>
<para>
<literal>ARRAY[1,4,3] @&gt; ARRAY[3,1,3]</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>anyarray</type> <literal>&lt;@</literal> <type>anyarray</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Is the first array contained by the second?
</para>
<para>
<literal>ARRAY[2,2,7] &lt;@ ARRAY[1,7,4,2,6]</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>anyarray</type> <literal>&amp;&amp;</literal> <type>anyarray</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Do the arrays overlap, that is, have any elements in common?
</para>
<para>
<literal>ARRAY[1,4,3] &amp;&amp; ARRAY[2,1]</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>anycompatiblearray</type> <literal>||</literal> <type>anycompatiblearray</type>
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Concatenates the two arrays. Concatenating a null or empty array is a
no-op; otherwise the arrays must have the same number of dimensions
(as illustrated by the first example) or differ in number of
dimensions by one (as illustrated by the second).
If the arrays are not of identical element types, they will be coerced
to a common type (see <xref linkend="typeconv-union-case"/>).
</para>
<para>
<literal>ARRAY[1,2,3] || ARRAY[4,5,6,7]</literal>
<returnvalue>{1,2,3,4,5,6,7}</returnvalue>
</para>
<para>
<literal>ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9.9]]</literal>
<returnvalue>{{1,2,3},{4,5,6},{7,8,9.9}}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>anycompatible</type> <literal>||</literal> <type>anycompatiblearray</type>
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Concatenates an element onto the front of an array (which must be
empty or one-dimensional).
</para>
<para>
<literal>3 || ARRAY[4,5,6]</literal>
<returnvalue>{3,4,5,6}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>anycompatiblearray</type> <literal>||</literal> <type>anycompatible</type>
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Concatenates an element onto the end of an array (which must be
empty or one-dimensional).
</para>
<para>
<literal>ARRAY[4,5,6] || 7</literal>
<returnvalue>{4,5,6,7}</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
See <xref linkend="arrays"/> for more details about array operator
behavior. See <xref linkend="indexes-types"/> for more details about
which operators support indexed operations.
</para>
<para>
<xref linkend="array-functions-table"/> shows the functions
available for use with array types. See <xref linkend="arrays"/>
for more information and examples of the use of these functions.
</para>
<table id="array-functions-table">
<title>Array 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>array_append</primary>
</indexterm>
<function>array_append</function> ( <type>anycompatiblearray</type>, <type>anycompatible</type> )
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Appends an element to the end of an array (same as
the <type>anycompatiblearray</type> <literal>||</literal> <type>anycompatible</type>
operator).
</para>
<para>
<literal>array_append(ARRAY[1,2], 3)</literal>
<returnvalue>{1,2,3}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_cat</primary>
</indexterm>
<function>array_cat</function> ( <type>anycompatiblearray</type>, <type>anycompatiblearray</type> )
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Concatenates two arrays (same as
the <type>anycompatiblearray</type> <literal>||</literal> <type>anycompatiblearray</type>
operator).
</para>
<para>
<literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal>
<returnvalue>{1,2,3,4,5}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_dims</primary>
</indexterm>
<function>array_dims</function> ( <type>anyarray</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns a text representation of the array's dimensions.
</para>
<para>
<literal>array_dims(ARRAY[[1,2,3], [4,5,6]])</literal>
<returnvalue>[1:2][1:3]</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_fill</primary>
</indexterm>
<function>array_fill</function> ( <type>anyelement</type>, <type>integer[]</type>
<optional>, <type>integer[]</type> </optional> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Returns an array filled with copies of the given value, having
dimensions of the lengths specified by the second argument.
The optional third argument supplies lower-bound values for each
dimension (which default to all <literal>1</literal>).
</para>
<para>
<literal>array_fill(11, ARRAY[2,3])</literal>
<returnvalue>{{11,11,11},{11,11,11}}</returnvalue>
</para>
<para>
<literal>array_fill(7, ARRAY[3], ARRAY[2])</literal>
<returnvalue>[2:4]={7,7,7}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_length</primary>
</indexterm>
<function>array_length</function> ( <type>anyarray</type>, <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the length of the requested array dimension.
(Produces NULL instead of 0 for empty or missing array dimensions.)
</para>
<para>
<literal>array_length(array[1,2,3], 1)</literal>
<returnvalue>3</returnvalue>
</para>
<para>
<literal>array_length(array[]::int[], 1)</literal>
<returnvalue>NULL</returnvalue>
</para>
<para>
<literal>array_length(array['text'], 2)</literal>
<returnvalue>NULL</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_lower</primary>
</indexterm>
<function>array_lower</function> ( <type>anyarray</type>, <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the lower bound of the requested array dimension.
</para>
<para>
<literal>array_lower('[0:2]={1,2,3}'::integer[], 1)</literal>
<returnvalue>0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_ndims</primary>
</indexterm>
<function>array_ndims</function> ( <type>anyarray</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of dimensions of the array.
</para>
<para>
<literal>array_ndims(ARRAY[[1,2,3], [4,5,6]])</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_position</primary>
</indexterm>
<function>array_position</function> ( <type>anycompatiblearray</type>, <type>anycompatible</type> <optional>, <type>integer</type> </optional> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the subscript of the first occurrence of the second argument
in the array, or <literal>NULL</literal> if it's not present.
If the third argument is given, the search begins at that subscript.
The array must be one-dimensional.
Comparisons are done using <literal>IS NOT DISTINCT FROM</literal>
semantics, so it is possible to search for <literal>NULL</literal>.
</para>
<para>
<literal>array_position(ARRAY['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'], 'mon')</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_positions</primary>
</indexterm>
<function>array_positions</function> ( <type>anycompatiblearray</type>, <type>anycompatible</type> )
<returnvalue>integer[]</returnvalue>
</para>
<para>
Returns an array of the subscripts of all occurrences of the second
argument in the array given as first argument.
The array must be one-dimensional.
Comparisons are done using <literal>IS NOT DISTINCT FROM</literal>
semantics, so it is possible to search for <literal>NULL</literal>.
<literal>NULL</literal> is returned only if the array
is <literal>NULL</literal>; if the value is not found in the array, an
empty array is returned.
</para>
<para>
<literal>array_positions(ARRAY['A','A','B','A'], 'A')</literal>
<returnvalue>{1,2,4}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_prepend</primary>
</indexterm>
<function>array_prepend</function> ( <type>anycompatible</type>, <type>anycompatiblearray</type> )
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Prepends an element to the beginning of an array (same as
the <type>anycompatible</type> <literal>||</literal> <type>anycompatiblearray</type>
operator).
</para>
<para>
<literal>array_prepend(1, ARRAY[2,3])</literal>
<returnvalue>{1,2,3}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_remove</primary>
</indexterm>
<function>array_remove</function> ( <type>anycompatiblearray</type>, <type>anycompatible</type> )
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Removes all elements equal to the given value from the array.
The array must be one-dimensional.
Comparisons are done using <literal>IS NOT DISTINCT FROM</literal>
semantics, so it is possible to remove <literal>NULL</literal>s.
</para>
<para>
<literal>array_remove(ARRAY[1,2,3,2], 2)</literal>
<returnvalue>{1,3}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_replace</primary>
</indexterm>
<function>array_replace</function> ( <type>anycompatiblearray</type>, <type>anycompatible</type>, <type>anycompatible</type> )
<returnvalue>anycompatiblearray</returnvalue>
</para>
<para>
Replaces each array element equal to the second argument with the
third argument.
</para>
<para>
<literal>array_replace(ARRAY[1,2,5,4], 5, 3)</literal>
<returnvalue>{1,2,3,4}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_reverse</primary>
</indexterm>
<function>array_reverse</function> ( <type>anyarray</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Reverses the first dimension of the array.
</para>
<para>
<literal>array_reverse(ARRAY[[1,2],[3,4],[5,6]])</literal>
<returnvalue>{{5,6},{3,4},{1,2}}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_sample</primary>
</indexterm>
<function>array_sample</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>n</parameter> <type>integer</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Returns an array of <parameter>n</parameter> items randomly selected
from <parameter>array</parameter>. <parameter>n</parameter> may not
exceed the length of <parameter>array</parameter>'s first dimension.
If <parameter>array</parameter> is multi-dimensional,
an <quote>item</quote> is a slice having a given first subscript.
</para>
<para>
<literal>array_sample(ARRAY[1,2,3,4,5,6], 3)</literal>
<returnvalue>{2,6,1}</returnvalue>
</para>
<para>
<literal>array_sample(ARRAY[[1,2],[3,4],[5,6]], 2)</literal>
<returnvalue>{{5,6},{1,2}}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_shuffle</primary>
</indexterm>
<function>array_shuffle</function> ( <type>anyarray</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Randomly shuffles the first dimension of the array.
</para>
<para>
<literal>array_shuffle(ARRAY[[1,2],[3,4],[5,6]])</literal>
<returnvalue>{{5,6},{1,2},{3,4}}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_sort</primary>
</indexterm>
<function>array_sort</function> (
<parameter>array</parameter> <type>anyarray</type>
<optional>, <parameter>descending</parameter> <type>boolean</type>
<optional>, <parameter>nulls_first</parameter> <type>boolean</type>
</optional></optional> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Sorts the first dimension of the array.
The sort order is determined by the default sort ordering of the
array's element type; however, if the element type is collatable,
the collation to use can be specified by adding
a <literal>COLLATE</literal> clause to
the <parameter>array</parameter> argument.
</para>
<para>
If <parameter>descending</parameter> is true then sort in
descending order, otherwise ascending order. If omitted, the
default is ascending order.
If <parameter>nulls_first</parameter> is true then nulls appear
before non-null values, otherwise nulls appear after non-null
values.
If omitted, <parameter>nulls_first</parameter> is taken to have
the same value as <parameter>descending</parameter>.
</para>
<para>
<literal>array_sort(ARRAY[[2,4],[2,1],[6,5]])</literal>
<returnvalue>{{2,1},{2,4},{6,5}}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-array-to-string">
<primary>array_to_string</primary>
</indexterm>
<function>array_to_string</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts each array element to its text representation, and
concatenates those separated by
the <parameter>delimiter</parameter> string.
If <parameter>null_string</parameter> is given and is
not <literal>NULL</literal>, then <literal>NULL</literal> array
entries are represented by that string; otherwise, they are omitted.
See also <link linkend="function-string-to-array"><function>string_to_array</function></link>.
</para>
<para>
<literal>array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')</literal>
<returnvalue>1,2,3,*,5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>array_upper</primary>
</indexterm>
<function>array_upper</function> ( <type>anyarray</type>, <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the upper bound of the requested array dimension.
</para>
<para>
<literal>array_upper(ARRAY[1,8,3,7], 1)</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cardinality</primary>
</indexterm>
<function>cardinality</function> ( <type>anyarray</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the total number of elements in the array, or 0 if the array
is empty.
</para>
<para>
<literal>cardinality(ARRAY[[1,2],[3,4]])</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trim_array</primary>
</indexterm>
<function>trim_array</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>n</parameter> <type>integer</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Trims an array by removing the last <parameter>n</parameter> elements.
If the array is multidimensional, only the first dimension is trimmed.
</para>
<para>
<literal>trim_array(ARRAY[1,2,3,4,5,6], 2)</literal>
<returnvalue>{1,2,3,4}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>unnest</primary>
</indexterm>
<function>unnest</function> ( <type>anyarray</type> )
<returnvalue>setof anyelement</returnvalue>
</para>
<para>
Expands an array into a set of rows.
The array's elements are read out in storage order.
</para>
<para>
<literal>unnest(ARRAY[1,2])</literal>
<returnvalue></returnvalue>
<programlisting>
1
2
</programlisting>
</para>
<para>
<literal>unnest(ARRAY[['foo','bar'],['baz','quux']])</literal>
<returnvalue></returnvalue>
<programlisting>
foo
bar
baz
quux
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>unnest</function> ( <type>anyarray</type>, <type>anyarray</type> <optional>, ... </optional> )
<returnvalue>setof anyelement, anyelement [, ... ]</returnvalue>
</para>
<para>
Expands multiple arrays (possibly of different data types) into a set of
rows. If the arrays are not all the same length then the shorter ones
are padded with <literal>NULL</literal>s. This form is only allowed
in a query's FROM clause; see <xref linkend="queries-tablefunctions"/>.
</para>
<para>
<literal>select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)</literal>
<returnvalue></returnvalue>
<programlisting>
a | b
---+-----
1 | foo
2 | bar
| baz
</programlisting>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
See also <xref linkend="functions-aggregate"/> about the aggregate
function <function>array_agg</function> for use with arrays.
</para>
</sect1>

854
doc/src/sgml/func/func-binarystring.sgml
Unescape View File

@ -0,0 +1,854 @@
<sect1 id="functions-binarystring">
<title>Binary String Functions and Operators</title>
<indexterm zone="functions-binarystring">
<primary>binary data</primary>
<secondary>functions</secondary>
</indexterm>
<para>
This section describes functions and operators for examining and
manipulating binary strings, that is values of type <type>bytea</type>.
Many of these are equivalent, in purpose and syntax, to the
text-string functions described in the previous section.
</para>
<para>
<acronym>SQL</acronym> defines some string functions that use
key words, rather than commas, to separate
arguments. Details are in
<xref linkend="functions-binarystring-sql"/>.
<productname>PostgreSQL</productname> also provides versions of these functions
that use the regular function invocation syntax
(see <xref linkend="functions-binarystring-other"/>).
</para>
<table id="functions-binarystring-sql">
<title><acronym>SQL</acronym> Binary String Functions and Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function/Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>binary string</primary>
<secondary>concatenation</secondary>
</indexterm>
<type>bytea</type> <literal>||</literal> <type>bytea</type>
<returnvalue>bytea</returnvalue>
</para>
<para>
Concatenates the two binary strings.
</para>
<para>
<literal>'\x123456'::bytea || '\x789a00bcde'::bytea</literal>
<returnvalue>\x123456789a00bcde</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_length</primary>
</indexterm>
<function>bit_length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the binary string (8
times the <function>octet_length</function>).
</para>
<para>
<literal>bit_length('\x123456'::bytea)</literal>
<returnvalue>24</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>btrim</primary>
</indexterm>
<function>btrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start and end of
<parameter>bytes</parameter>.
</para>
<para>
<literal>btrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ltrim</primary>
</indexterm>
<function>ltrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start of
<parameter>bytes</parameter>.
</para>
<para>
<literal>ltrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x34567890</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the binary string.
</para>
<para>
<literal>octet_length('\x123456'::bytea)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>overlay</primary>
</indexterm>
<function>overlay</function> ( <parameter>bytes</parameter> <type>bytea</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>bytea</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Replaces the substring of <parameter>bytes</parameter> that starts at
the <parameter>start</parameter>'th byte and extends
for <parameter>count</parameter> bytes
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
</para>
<para>
<literal>overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)</literal>
<returnvalue>\x12020390</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>position</primary>
</indexterm>
<function>position</function> ( <parameter>substring</parameter> <type>bytea</type> <literal>IN</literal> <parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified
<parameter>substring</parameter> within
<parameter>bytes</parameter>, or zero if it's not present.
</para>
<para>
<literal>position('\x5678'::bytea in '\x1234567890'::bytea)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>rtrim</primary>
</indexterm>
<function>rtrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the end of
<parameter>bytes</parameter>.
</para>
<para>
<literal>rtrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x12345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substring</primary>
</indexterm>
<function>substring</function> ( <parameter>bytes</parameter> <type>bytea</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bytes</parameter> starting at
the <parameter>start</parameter>'th byte if that is specified,
and stopping after <parameter>count</parameter> bytes if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
</para>
<para>
<literal>substring('\x1234567890'::bytea from 3 for 2)</literal>
<returnvalue>\x5678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trim</primary>
</indexterm>
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional>
<parameter>bytesremoved</parameter> <type>bytea</type> <literal>FROM</literal>
<parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start,
end, or both ends (<literal>BOTH</literal> is the default)
of <parameter>bytes</parameter>.
</para>
<para>
<literal>trim('\x9012'::bytea from '\x1234567890'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional> <optional> <literal>FROM</literal> </optional>
<parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
This is a non-standard syntax for <function>trim()</function>.
</para>
<para>
<literal>trim(both from '\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Additional binary string manipulation functions are available and
are listed in <xref linkend="functions-binarystring-other"/>. Some
of them are used internally to implement the
<acronym>SQL</acronym>-standard string functions listed in <xref
linkend="functions-binarystring-sql"/>.
</para>
<table id="functions-binarystring-other">
<title>Other Binary String 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>bit_count</primary>
</indexterm>
<indexterm>
<primary>popcount</primary>
<see>bit_count</see>
</indexterm>
<function>bit_count</function> ( <parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the number of bits set in the binary string (also known as
<quote>popcount</quote>).
</para>
<para>
<literal>bit_count('\x1234567890'::bytea)</literal>
<returnvalue>15</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>crc32</primary>
</indexterm>
<function>crc32</function> ( <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Computes the CRC-32 value of the binary string.
</para>
<para>
<literal>crc32('abc'::bytea)</literal>
<returnvalue>891568578</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>crc32c</primary>
</indexterm>
<function>crc32c</function> ( <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Computes the CRC-32C value of the binary string.
</para>
<para>
<literal>crc32c('abc'::bytea)</literal>
<returnvalue>910901175</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_bit</primary>
</indexterm>
<function>get_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>bigint</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <link linkend="functions-zerobased-note">n'th</link> bit
from binary string.
</para>
<para>
<literal>get_bit('\x1234567890'::bytea, 30)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_byte</primary>
</indexterm>
<function>get_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <link linkend="functions-zerobased-note">n'th</link> byte
from binary string.
</para>
<para>
<literal>get_byte('\x1234567890'::bytea, 4)</literal>
<returnvalue>144</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>length</primary>
</indexterm>
<indexterm>
<primary>binary string</primary>
<secondary>length</secondary>
</indexterm>
<indexterm>
<primary>length</primary>
<secondary sortas="binary string">of a binary string</secondary>
<see>binary strings, length</see>
</indexterm>
<function>length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of bytes in the binary string.
</para>
<para>
<literal>length('\x1234567890'::bytea)</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>length</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>encoding</parameter> <type>name</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of characters in the binary string, assuming
that it is text in the given <parameter>encoding</parameter>.
</para>
<para>
<literal>length('jose'::bytea, 'UTF8')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>md5</primary>
</indexterm>
<function>md5</function> ( <type>bytea</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Computes the MD5 <link linkend="functions-hash-note">hash</link> of
the binary string, with the result written in hexadecimal.
</para>
<para>
<literal>md5('Th\000omas'::bytea)</literal>
<returnvalue>8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>reverse</primary>
</indexterm>
<function>reverse</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Reverses the order of the bytes in the binary string.
</para>
<para>
<literal>reverse('\xabcd'::bytea)</literal>
<returnvalue>\xcdab</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_bit</primary>
</indexterm>
<function>set_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>bigint</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Sets <link linkend="functions-zerobased-note">n'th</link> bit in
binary string to <parameter>newvalue</parameter>.
</para>
<para>
<literal>set_bit('\x1234567890'::bytea, 30, 0)</literal>
<returnvalue>\x1234563890</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_byte</primary>
</indexterm>
<function>set_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>integer</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Sets <link linkend="functions-zerobased-note">n'th</link> byte in
binary string to <parameter>newvalue</parameter>.
</para>
<para>
<literal>set_byte('\x1234567890'::bytea, 4, 64)</literal>
<returnvalue>\x1234567840</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha224</primary>
</indexterm>
<function>sha224</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-224 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha224('abc'::bytea)</literal>
<returnvalue>\x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha256</primary>
</indexterm>
<function>sha256</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-256 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha256('abc'::bytea)</literal>
<returnvalue>\xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha384</primary>
</indexterm>
<function>sha384</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-384 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha384('abc'::bytea)</literal>
<returnvalue>\xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha512</primary>
</indexterm>
<function>sha512</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-512 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha512('abc'::bytea)</literal>
<returnvalue>\xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substr</primary>
</indexterm>
<function>substr</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bytes</parameter> starting at
the <parameter>start</parameter>'th byte,
and extending for <parameter>count</parameter> bytes if that is
specified. (Same
as <literal>substring(<parameter>bytes</parameter>
from <parameter>start</parameter>
for <parameter>count</parameter>)</literal>.)
</para>
<para>
<literal>substr('\x1234567890'::bytea, 3, 2)</literal>
<returnvalue>\x5678</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para id="functions-zerobased-note">
Functions <function>get_byte</function> and <function>set_byte</function>
number the first byte of a binary string as byte 0.
Functions <function>get_bit</function> and <function>set_bit</function>
number bits from the right within each byte; for example bit 0 is the least
significant bit of the first byte, and bit 15 is the most significant bit
of the second byte.
</para>
<para id="functions-hash-note">
For historical reasons, the function <function>md5</function>
returns a hex-encoded value of type <type>text</type> whereas the SHA-2
functions return type <type>bytea</type>. Use the functions
<link linkend="function-encode"><function>encode</function></link>
and <link linkend="function-decode"><function>decode</function></link> to
convert between the two. For example write <literal>encode(sha256('abc'),
'hex')</literal> to get a hex-encoded text representation,
or <literal>decode(md5('abc'), 'hex')</literal> to get
a <type>bytea</type> value.
</para>
<para>
<indexterm>
<primary>character string</primary>
<secondary>converting to binary string</secondary>
</indexterm>
<indexterm>
<primary>binary string</primary>
<secondary>converting to character string</secondary>
</indexterm>
Functions for converting strings between different character sets
(encodings), and for representing arbitrary binary data in textual
form, are shown in
<xref linkend="functions-binarystring-conversions"/>. For these
functions, an argument or result of type <type>text</type> is expressed
in the database's default encoding, while arguments or results of
type <type>bytea</type> are in an encoding named by another argument.
</para>
<table id="functions-binarystring-conversions">
<title>Text/Binary String Conversion 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>convert</primary>
</indexterm>
<function>convert</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type>,
<parameter>dest_encoding</parameter> <type>name</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Converts a binary string representing text in
encoding <parameter>src_encoding</parameter>
to a binary string in encoding <parameter>dest_encoding</parameter>
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal>
<returnvalue>\x746578745f696e5f75746638</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>convert_from</primary>
</indexterm>
<function>convert_from</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts a binary string representing text in
encoding <parameter>src_encoding</parameter>
to <type>text</type> in the database encoding
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert_from('text_in_utf8', 'UTF8')</literal>
<returnvalue>text_in_utf8</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>convert_to</primary>
</indexterm>
<function>convert_to</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>dest_encoding</parameter> <type>name</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Converts a <type>text</type> string (in the database encoding) to a
binary string encoded in encoding <parameter>dest_encoding</parameter>
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert_to('some_text', 'UTF8')</literal>
<returnvalue>\x736f6d655f74657874</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-encode">
<primary>encode</primary>
</indexterm>
<function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>format</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Encodes binary data into a textual representation; supported
<parameter>format</parameter> values are:
<link linkend="encode-format-base64"><literal>base64</literal></link>,
<link linkend="encode-format-escape"><literal>escape</literal></link>,
<link linkend="encode-format-hex"><literal>hex</literal></link>.
</para>
<para>
<literal>encode('123\000\001', 'base64')</literal>
<returnvalue>MTIzAAE=</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-decode">
<primary>decode</primary>
</indexterm>
<function>decode</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>format</parameter> <type>text</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Decodes binary data from a textual representation; supported
<parameter>format</parameter> values are the same as
for <function>encode</function>.
</para>
<para>
<literal>decode('MTIzAAE=', 'base64')</literal>
<returnvalue>\x3132330001</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>encode</function> and <function>decode</function>
functions support the following textual formats:
<variablelist>
<varlistentry id="encode-format-base64">
<term>base64
<indexterm>
<primary>base64 format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>base64</literal> format is that
of <ulink url="https://datatracker.ietf.org/doc/html/rfc2045#section-6.8">RFC
2045 Section 6.8</ulink>. As per the <acronym>RFC</acronym>, encoded lines are
broken at 76 characters. However instead of the MIME CRLF
end-of-line marker, only a newline is used for end-of-line.
The <function>decode</function> function ignores carriage-return,
newline, space, and tab characters. Otherwise, an error is
raised when <function>decode</function> is supplied invalid
base64 data &mdash; including when trailing padding is incorrect.
</para>
</listitem>
</varlistentry>
<varlistentry id="encode-format-escape">
<term>escape
<indexterm>
<primary>escape format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>escape</literal> format converts zero bytes and
bytes with the high bit set into octal escape sequences
(<literal>\</literal><replaceable>nnn</replaceable>), and it doubles
backslashes. Other byte values are represented literally.
The <function>decode</function> function will raise an error if a
backslash is not followed by either a second backslash or three
octal digits; it accepts other byte values unchanged.
</para>
</listitem>
</varlistentry>
<varlistentry id="encode-format-hex">
<term>hex
<indexterm>
<primary>hex format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>hex</literal> format represents each 4 bits of
data as one hexadecimal digit, <literal>0</literal>
through <literal>f</literal>, writing the higher-order digit of
each byte first. The <function>encode</function> function outputs
the <literal>a</literal>-<literal>f</literal> hex digits in lower
case. Because the smallest unit of data is 8 bits, there are
always an even number of characters returned
by <function>encode</function>.
The <function>decode</function> function
accepts the <literal>a</literal>-<literal>f</literal> characters in
either upper or lower case. An error is raised
when <function>decode</function> is given invalid hex data
&mdash; including when given an odd number of characters.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
In addition, it is possible to cast integral values to and from type
<type>bytea</type>. Casting an integer to <type>bytea</type> produces
2, 4, or 8 bytes, depending on the width of the integer type. The result
is the two's complement representation of the integer, with the most
significant byte first. Some examples:
<programlisting>
1234::smallint::bytea <lineannotation>\x04d2</lineannotation>
cast(1234 as bytea) <lineannotation>\x000004d2</lineannotation>
cast(-1234 as bytea) <lineannotation>\xfffffb2e</lineannotation>
'\x8000'::bytea::smallint <lineannotation>-32768</lineannotation>
'\x8000'::bytea::integer <lineannotation>32768</lineannotation>
</programlisting>
Casting a <type>bytea</type> to an integer will raise an error if the
length of the <type>bytea</type> exceeds the width of the integer type.
</para>
<para>
See also the aggregate function <function>string_agg</function> in
<xref linkend="functions-aggregate"/> and the large object functions
in <xref linkend="lo-funcs"/>.
</para>
</sect1>

358
doc/src/sgml/func/func-bitstring.sgml
Unescape View File

@ -0,0 +1,358 @@
<sect1 id="functions-bitstring">
<title>Bit String Functions and Operators</title>
<indexterm zone="functions-bitstring">
<primary>bit strings</primary>
<secondary>functions</secondary>
</indexterm>
<para>
This section describes functions and operators for examining and
manipulating bit strings, that is values of the types
<type>bit</type> and <type>bit varying</type>. (While only
type <type>bit</type> is mentioned in these tables, values of
type <type>bit varying</type> can be used interchangeably.)
Bit strings support the usual comparison operators shown in
<xref linkend="functions-comparison-op-table"/>, as well as the
operators shown in <xref linkend="functions-bit-string-op-table"/>.
</para>
<table id="functions-bit-string-op-table">
<title>Bit String 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">
<type>bit</type> <literal>||</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Concatenation
</para>
<para>
<literal>B'10001' || B'011'</literal>
<returnvalue>10001011</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>&amp;</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise AND (inputs must be of equal length)
</para>
<para>
<literal>B'10001' &amp; B'01101'</literal>
<returnvalue>00001</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>|</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise OR (inputs must be of equal length)
</para>
<para>
<literal>B'10001' | B'01101'</literal>
<returnvalue>11101</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>#</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise exclusive OR (inputs must be of equal length)
</para>
<para>
<literal>B'10001' # B'01101'</literal>
<returnvalue>11100</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>~</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise NOT
</para>
<para>
<literal>~ B'10001'</literal>
<returnvalue>01110</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>&lt;&lt;</literal> <type>integer</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise shift left
(string length is preserved)
</para>
<para>
<literal>B'10001' &lt;&lt; 3</literal>
<returnvalue>01000</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>&gt;&gt;</literal> <type>integer</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise shift right
(string length is preserved)
</para>
<para>
<literal>B'10001' &gt;&gt; 2</literal>
<returnvalue>00100</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Some of the functions available for binary strings are also available
for bit strings, as shown in <xref linkend="functions-bit-string-table"/>.
</para>
<table id="functions-bit-string-table">
<title>Bit String 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>bit_count</primary>
</indexterm>
<function>bit_count</function> ( <type>bit</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the number of bits set in the bit string (also known as
<quote>popcount</quote>).
</para>
<para>
<literal>bit_count(B'10111')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_length</primary>
</indexterm>
<function>bit_length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the bit string.
</para>
<para>
<literal>bit_length(B'10111')</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>length</primary>
</indexterm>
<indexterm>
<primary>bit string</primary>
<secondary>length</secondary>
</indexterm>
<function>length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the bit string.
</para>
<para>
<literal>length(B'10111')</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the bit string.
</para>
<para>
<literal>octet_length(B'1011111011')</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>overlay</primary>
</indexterm>
<function>overlay</function> ( <parameter>bits</parameter> <type>bit</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>bit</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bit</returnvalue>
</para>
<para>
Replaces the substring of <parameter>bits</parameter> that starts at
the <parameter>start</parameter>'th bit and extends
for <parameter>count</parameter> bits
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
</para>
<para>
<literal>overlay(B'01010101010101010' placing B'11111' from 2 for 3)</literal>
<returnvalue>0111110101010101010</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>position</primary>
</indexterm>
<function>position</function> ( <parameter>substring</parameter> <type>bit</type> <literal>IN</literal> <parameter>bits</parameter> <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified <parameter>substring</parameter>
within <parameter>bits</parameter>, or zero if it's not present.
</para>
<para>
<literal>position(B'010' in B'000001101011')</literal>
<returnvalue>8</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substring</primary>
</indexterm>
<function>substring</function> ( <parameter>bits</parameter> <type>bit</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bit</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bits</parameter> starting at
the <parameter>start</parameter>'th bit if that is specified,
and stopping after <parameter>count</parameter> bits if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
</para>
<para>
<literal>substring(B'110010111111' from 3 for 2)</literal>
<returnvalue>00</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_bit</primary>
</indexterm>
<function>get_bit</function> ( <parameter>bits</parameter> <type>bit</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <parameter>n</parameter>'th bit
from bit string; the first (leftmost) bit is bit 0.
</para>
<para>
<literal>get_bit(B'101010101010101010', 6)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_bit</primary>
</indexterm>
<function>set_bit</function> ( <parameter>bits</parameter> <type>bit</type>,
<parameter>n</parameter> <type>integer</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bit</returnvalue>
</para>
<para>
Sets <parameter>n</parameter>'th bit in
bit string to <parameter>newvalue</parameter>;
the first (leftmost) bit is bit 0.
</para>
<para>
<literal>set_bit(B'101010101010101010', 6, 0)</literal>
<returnvalue>101010001010101010</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
In addition, it is possible to cast integral values to and from type
<type>bit</type>.
Casting an integer to <type>bit(n)</type> copies the rightmost
<literal>n</literal> bits. Casting an integer to a bit string width wider
than the integer itself will sign-extend on the left.
Some examples:
<programlisting>
44::bit(10) <lineannotation>0000101100</lineannotation>
44::bit(3) <lineannotation>100</lineannotation>
cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
'1110'::bit(4)::integer <lineannotation>14</lineannotation>
</programlisting>
Note that casting to just <quote>bit</quote> means casting to
<literal>bit(1)</literal>, and so will deliver only the least significant
bit of the integer.
</para>
</sect1>

638
doc/src/sgml/func/func-comparison.sgml
Unescape View File

@ -0,0 +1,638 @@
<sect1 id="functions-comparison">
<title>Comparison Functions and Operators</title>
<indexterm zone="functions-comparison">
<primary>comparison</primary>
<secondary>operators</secondary>
</indexterm>
<para>
The usual comparison operators are available, as shown in <xref
linkend="functions-comparison-op-table"/>.
</para>
<table id="functions-comparison-op-table">
<title>Comparison Operators</title>
<tgroup cols="2">
<thead>
<row>
<entry>Operator</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>&lt;</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Less than</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>&gt;</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Greater than</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>&lt;=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Less than or equal to</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>&gt;=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Greater than or equal to</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Equal</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>&lt;&gt;</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Not equal</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>!=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Not equal</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
<literal>&lt;&gt;</literal> is the standard SQL notation for <quote>not
equal</quote>. <literal>!=</literal> is an alias, which is converted
to <literal>&lt;&gt;</literal> at a very early stage of parsing.
Hence, it is not possible to implement <literal>!=</literal>
and <literal>&lt;&gt;</literal> operators that do different things.
</para>
</note>
<para>
These comparison operators are available for all built-in data types
that have a natural ordering, including numeric, string, and date/time
types. In addition, arrays, composite types, and ranges can be compared
if their component data types are comparable.
</para>
<para>
It is usually possible to compare values of related data
types as well; for example <type>integer</type> <literal>&gt;</literal>
<type>bigint</type> will work. Some cases of this sort are implemented
directly by <quote>cross-type</quote> comparison operators, but if no
such operator is available, the parser will coerce the less-general type
to the more-general type and apply the latter's comparison operator.
</para>
<para>
As shown above, all comparison operators are binary operators that
return values of type <type>boolean</type>. Thus, expressions like
<literal>1 &lt; 2 &lt; 3</literal> are not valid (because there is
no <literal>&lt;</literal> operator to compare a Boolean value with
<literal>3</literal>). Use the <literal>BETWEEN</literal> predicates
shown below to perform range tests.
</para>
<para>
There are also some comparison predicates, as shown in <xref
linkend="functions-comparison-pred-table"/>. These behave much like
operators, but have special syntax mandated by the SQL standard.
</para>
<table id="functions-comparison-pred-table">
<title>Comparison Predicates</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Predicate
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>BETWEEN</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Between (inclusive of the range endpoints).
</para>
<para>
<literal>2 BETWEEN 1 AND 3</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>2 BETWEEN 3 AND 1</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOT BETWEEN</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not between (the negation of <literal>BETWEEN</literal>).
</para>
<para>
<literal>2 NOT BETWEEN 1 AND 3</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>BETWEEN SYMMETRIC</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Between, after sorting the two endpoint values.
</para>
<para>
<literal>2 BETWEEN SYMMETRIC 3 AND 1</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOT BETWEEN SYMMETRIC</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not between, after sorting the two endpoint values.
</para>
<para>
<literal>2 NOT BETWEEN SYMMETRIC 3 AND 1</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS DISTINCT FROM</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not equal, treating null as a comparable value.
</para>
<para>
<literal>1 IS DISTINCT FROM NULL</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para>
<para>
<literal>NULL IS DISTINCT FROM NULL</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NOT DISTINCT FROM</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Equal, treating null as a comparable value.
</para>
<para>
<literal>1 IS NOT DISTINCT FROM NULL</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para>
<para>
<literal>NULL IS NOT DISTINCT FROM NULL</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is null.
</para>
<para>
<literal>1.5 IS NULL</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NOT NULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is not null.
</para>
<para>
<literal>'null' IS NOT NULL</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>ISNULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is null (nonstandard syntax).
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOTNULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is not null (nonstandard syntax).
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS TRUE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true.
</para>
<para>
<literal>true IS TRUE</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS TRUE</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT TRUE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields false or unknown.
</para>
<para>
<literal>true IS NOT TRUE</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT TRUE</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS FALSE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields false.
</para>
<para>
<literal>true IS FALSE</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS FALSE</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT FALSE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true or unknown.
</para>
<para>
<literal>true IS NOT FALSE</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT FALSE</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS UNKNOWN</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields unknown.
</para>
<para>
<literal>true IS UNKNOWN</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS UNKNOWN</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT UNKNOWN</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true or false.
</para>
<para>
<literal>true IS NOT UNKNOWN</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT UNKNOWN</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<indexterm>
<primary>BETWEEN</primary>
</indexterm>
<indexterm>
<primary>BETWEEN SYMMETRIC</primary>
</indexterm>
The <token>BETWEEN</token> predicate simplifies range tests:
<synopsis>
<replaceable>a</replaceable> BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
</synopsis>
is equivalent to
<synopsis>
<replaceable>a</replaceable> &gt;= <replaceable>x</replaceable> AND <replaceable>a</replaceable> &lt;= <replaceable>y</replaceable>
</synopsis>
Notice that <token>BETWEEN</token> treats the endpoint values as included
in the range.
<literal>BETWEEN SYMMETRIC</literal> is like <literal>BETWEEN</literal>
except there is no requirement that the argument to the left of
<literal>AND</literal> be less than or equal to the argument on the right.
If it is not, those two arguments are automatically swapped, so that
a nonempty range is always implied.
</para>
<para>
The various variants of <literal>BETWEEN</literal> are implemented in
terms of the ordinary comparison operators, and therefore will work for
any data type(s) that can be compared.
</para>
<note>
<para>
The use of <literal>AND</literal> in the <literal>BETWEEN</literal>
syntax creates an ambiguity with the use of <literal>AND</literal> as a
logical operator. To resolve this, only a limited set of expression
types are allowed as the second argument of a <literal>BETWEEN</literal>
clause. If you need to write a more complex sub-expression
in <literal>BETWEEN</literal>, write parentheses around the
sub-expression.
</para>
</note>
<para>
<indexterm>
<primary>IS DISTINCT FROM</primary>
</indexterm>
<indexterm>
<primary>IS NOT DISTINCT FROM</primary>
</indexterm>
Ordinary comparison operators yield null (signifying <quote>unknown</quote>),
not true or false, when either input is null. For example,
<literal>7 = NULL</literal> yields null, as does <literal>7 &lt;&gt; NULL</literal>. When
this behavior is not suitable, use the
<literal>IS <optional> NOT </optional> DISTINCT FROM</literal> predicates:
<synopsis>
<replaceable>a</replaceable> IS DISTINCT FROM <replaceable>b</replaceable>
<replaceable>a</replaceable> IS NOT DISTINCT FROM <replaceable>b</replaceable>
</synopsis>
For non-null inputs, <literal>IS DISTINCT FROM</literal> is
the same as the <literal>&lt;&gt;</literal> operator. However, if both
inputs are null it returns false, and if only one input is
null it returns true. Similarly, <literal>IS NOT DISTINCT
FROM</literal> is identical to <literal>=</literal> for non-null
inputs, but it returns true when both inputs are null, and false when only
one input is null. Thus, these predicates effectively act as though null
were a normal data value, rather than <quote>unknown</quote>.
</para>
<para>
<indexterm>
<primary>IS NULL</primary>
</indexterm>
<indexterm>
<primary>IS NOT NULL</primary>
</indexterm>
<indexterm>
<primary>ISNULL</primary>
</indexterm>
<indexterm>
<primary>NOTNULL</primary>
</indexterm>
To check whether a value is or is not null, use the predicates:
<synopsis>
<replaceable>expression</replaceable> IS NULL
<replaceable>expression</replaceable> IS NOT NULL
</synopsis>
or the equivalent, but nonstandard, predicates:
<synopsis>
<replaceable>expression</replaceable> ISNULL
<replaceable>expression</replaceable> NOTNULL
</synopsis>
<indexterm><primary>null value</primary><secondary>comparing</secondary></indexterm>
</para>
<para>
Do <emphasis>not</emphasis> write
<literal><replaceable>expression</replaceable> = NULL</literal>
because <literal>NULL</literal> is not <quote>equal to</quote>
<literal>NULL</literal>. (The null value represents an unknown value,
and it is not known whether two unknown values are equal.)
</para>
<tip>
<para>
Some applications might expect that
<literal><replaceable>expression</replaceable> = NULL</literal>
returns true if <replaceable>expression</replaceable> evaluates to
the null value. It is highly recommended that these applications
be modified to comply with the SQL standard. However, if that
cannot be done the <xref linkend="guc-transform-null-equals"/>
configuration variable is available. If it is enabled,
<productname>PostgreSQL</productname> will convert <literal>x =
NULL</literal> clauses to <literal>x IS NULL</literal>.
</para>
</tip>
<para>
If the <replaceable>expression</replaceable> is row-valued, then
<literal>IS NULL</literal> is true when the row expression itself is null
or when all the row's fields are null, while
<literal>IS NOT NULL</literal> is true when the row expression itself is non-null
and all the row's fields are non-null. Because of this behavior,
<literal>IS NULL</literal> and <literal>IS NOT NULL</literal> do not always return
inverse results for row-valued expressions; in particular, a row-valued
expression that contains both null and non-null fields will return false
for both tests. For example:
<programlisting>
SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
SELECT ROW(table.*) IS NULL FROM table; -- detect all-null rows
SELECT ROW(table.*) IS NOT NULL FROM table; -- detect all-non-null rows
SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows
</programlisting>
In some cases, it may be preferable to
write <replaceable>row</replaceable> <literal>IS DISTINCT FROM NULL</literal>
or <replaceable>row</replaceable> <literal>IS NOT DISTINCT FROM NULL</literal>,
which will simply check whether the overall row value is null without any
additional tests on the row fields.
</para>
<para>
<indexterm>
<primary>IS TRUE</primary>
</indexterm>
<indexterm>
<primary>IS NOT TRUE</primary>
</indexterm>
<indexterm>
<primary>IS FALSE</primary>
</indexterm>
<indexterm>
<primary>IS NOT FALSE</primary>
</indexterm>
<indexterm>
<primary>IS UNKNOWN</primary>
</indexterm>
<indexterm>
<primary>IS NOT UNKNOWN</primary>
</indexterm>
Boolean values can also be tested using the predicates
<synopsis>
<replaceable>boolean_expression</replaceable> IS TRUE
<replaceable>boolean_expression</replaceable> IS NOT TRUE
<replaceable>boolean_expression</replaceable> IS FALSE
<replaceable>boolean_expression</replaceable> IS NOT FALSE
<replaceable>boolean_expression</replaceable> IS UNKNOWN
<replaceable>boolean_expression</replaceable> IS NOT UNKNOWN
</synopsis>
These will always return true or false, never a null value, even when the
operand is null.
A null input is treated as the logical value <quote>unknown</quote>.
Notice that <literal>IS UNKNOWN</literal> and <literal>IS NOT UNKNOWN</literal> are
effectively the same as <literal>IS NULL</literal> and
<literal>IS NOT NULL</literal>, respectively, except that the input
expression must be of Boolean type.
</para>
<para>
Some comparison-related functions are also available, as shown in <xref
linkend="functions-comparison-func-table"/>.
</para>
<table id="functions-comparison-func-table">
<title>Comparison 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>num_nonnulls</primary>
</indexterm>
<function>num_nonnulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of non-null arguments.
</para>
<para>
<literal>num_nonnulls(1, NULL, 2)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>num_nulls</primary>
</indexterm>
<function>num_nulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of null arguments.
</para>
<para>
<literal>num_nulls(1, NULL, 2)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>

336
doc/src/sgml/func/func-comparisons.sgml
Unescape View File

@ -0,0 +1,336 @@
<sect1 id="functions-comparisons">
<title>Row and Array Comparisons</title>
<indexterm>
<primary>IN</primary>
</indexterm>
<indexterm>
<primary>NOT IN</primary>
</indexterm>
<indexterm>
<primary>ANY</primary>
</indexterm>
<indexterm>
<primary>ALL</primary>
</indexterm>
<indexterm>
<primary>SOME</primary>
</indexterm>
<indexterm>
<primary>composite type</primary>
<secondary>comparison</secondary>
</indexterm>
<indexterm>
<primary>row-wise comparison</primary>
</indexterm>
<indexterm>
<primary>comparison</primary>
<secondary>composite type</secondary>
</indexterm>
<indexterm>
<primary>comparison</primary>
<secondary>row constructor</secondary>
</indexterm>
<indexterm>
<primary>IS DISTINCT FROM</primary>
</indexterm>
<indexterm>
<primary>IS NOT DISTINCT FROM</primary>
</indexterm>
<para>
This section describes several specialized constructs for making
multiple comparisons between groups of values. These forms are
syntactically related to the subquery forms of the previous section,
but do not involve subqueries.
The forms involving array subexpressions are
<productname>PostgreSQL</productname> extensions; the rest are
<acronym>SQL</acronym>-compliant.
All of the expression forms documented in this section return
Boolean (true/false) results.
</para>
<sect2 id="functions-comparisons-in-scalar">
<title><literal>IN</literal></title>
<synopsis>
<replaceable>expression</replaceable> IN (<replaceable>value</replaceable> <optional>, ...</optional>)
</synopsis>
<para>
The right-hand side is a parenthesized list
of expressions. The result is <quote>true</quote> if the left-hand expression's
result is equal to any of the right-hand expressions. This is a shorthand
notation for
<synopsis>
<replaceable>expression</replaceable> = <replaceable>value1</replaceable>
OR
<replaceable>expression</replaceable> = <replaceable>value2</replaceable>
OR
...
</synopsis>
</para>
<para>
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand expression yields
null, the result of the <token>IN</token> construct will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
</sect2>
<sect2 id="functions-comparisons-not-in">
<title><literal>NOT IN</literal></title>
<synopsis>
<replaceable>expression</replaceable> NOT IN (<replaceable>value</replaceable> <optional>, ...</optional>)
</synopsis>
<para>
The right-hand side is a parenthesized list
of expressions. The result is <quote>true</quote> if the left-hand expression's
result is unequal to all of the right-hand expressions. This is a shorthand
notation for
<synopsis>
<replaceable>expression</replaceable> &lt;&gt; <replaceable>value1</replaceable>
AND
<replaceable>expression</replaceable> &lt;&gt; <replaceable>value2</replaceable>
AND
...
</synopsis>
</para>
<para>
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand expression yields
null, the result of the <token>NOT IN</token> construct will be null, not true
as one might naively expect.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
<tip>
<para>
<literal>x NOT IN y</literal> is equivalent to <literal>NOT (x IN y)</literal> in all
cases. However, null values are much more likely to trip up the novice when
working with <token>NOT IN</token> than when working with <token>IN</token>.
It is best to express your condition positively if possible.
</para>
</tip>
</sect2>
<sect2 id="functions-comparisons-any-some">
<title><literal>ANY</literal>/<literal>SOME</literal> (array)</title>
<synopsis>
<replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>array expression</replaceable>)
<replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>array expression</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized expression, which must yield an
array value.
The left-hand expression
is evaluated and compared to each element of the array using the
given <replaceable>operator</replaceable>, which must yield a Boolean
result.
The result of <token>ANY</token> is <quote>true</quote> if any true result is obtained.
The result is <quote>false</quote> if no true result is found (including the
case where the array has zero elements).
</para>
<para>
If the array expression yields a null array, the result of
<token>ANY</token> will be null. If the left-hand expression yields null,
the result of <token>ANY</token> is ordinarily null (though a non-strict
comparison operator could possibly yield a different result).
Also, if the right-hand array contains any null elements and no true
comparison result is obtained, the result of <token>ANY</token>
will be null, not false (again, assuming a strict comparison operator).
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
<para>
<token>SOME</token> is a synonym for <token>ANY</token>.
</para>
</sect2>
<sect2 id="functions-comparisons-all">
<title><literal>ALL</literal> (array)</title>
<synopsis>
<replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>array expression</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized expression, which must yield an
array value.
The left-hand expression
is evaluated and compared to each element of the array using the
given <replaceable>operator</replaceable>, which must yield a Boolean
result.
The result of <token>ALL</token> is <quote>true</quote> if all comparisons yield true
(including the case where the array has zero elements).
The result is <quote>false</quote> if any false result is found.
</para>
<para>
If the array expression yields a null array, the result of
<token>ALL</token> will be null. If the left-hand expression yields null,
the result of <token>ALL</token> is ordinarily null (though a non-strict
comparison operator could possibly yield a different result).
Also, if the right-hand array contains any null elements and no false
comparison result is obtained, the result of <token>ALL</token>
will be null, not true (again, assuming a strict comparison operator).
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
</sect2>
<sect2 id="row-wise-comparison">
<title>Row Constructor Comparison</title>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> <replaceable>row_constructor</replaceable>
</synopsis>
<para>
Each side is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The two row constructors must have the same number of fields.
The given <replaceable>operator</replaceable> is applied to each pair
of corresponding fields. (Since the fields could be of different
types, this means that a different specific operator could be selected
for each pair.)
All the selected operators must be members of some B-tree operator
class, or be the negator of an <literal>=</literal> member of a B-tree
operator class, meaning that row constructor comparison is only
possible when the <replaceable>operator</replaceable> is
<literal>=</literal>,
<literal>&lt;&gt;</literal>,
<literal>&lt;</literal>,
<literal>&lt;=</literal>,
<literal>&gt;</literal>, or
<literal>&gt;=</literal>,
or has semantics similar to one of these.
</para>
<para>
The <literal>=</literal> and <literal>&lt;&gt;</literal> cases work slightly differently
from the others. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of the row comparison is unknown (null).
</para>
<para>
For the <literal>&lt;</literal>, <literal>&lt;=</literal>, <literal>&gt;</literal> and
<literal>&gt;=</literal> cases, the row elements are compared left-to-right,
stopping as soon as an unequal or null pair of elements is found.
If either of this pair of elements is null, the result of the
row comparison is unknown (null); otherwise comparison of this pair
of elements determines the result. For example,
<literal>ROW(1,2,NULL) &lt; ROW(1,3,0)</literal>
yields true, not null, because the third pair of elements are not
considered.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> IS DISTINCT FROM <replaceable>row_constructor</replaceable>
</synopsis>
<para>
This construct is similar to a <literal>&lt;&gt;</literal> row comparison,
but it does not yield null for null inputs. Instead, any null value is
considered unequal to (distinct from) any non-null value, and any two
nulls are considered equal (not distinct). Thus the result will
either be true or false, never null.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> IS NOT DISTINCT FROM <replaceable>row_constructor</replaceable>
</synopsis>
<para>
This construct is similar to a <literal>=</literal> row comparison,
but it does not yield null for null inputs. Instead, any null value is
considered unequal to (distinct from) any non-null value, and any two
nulls are considered equal (not distinct). Thus the result will always
be either true or false, never null.
</para>
</sect2>
<sect2 id="composite-type-comparison">
<title>Composite Type Comparison</title>
<synopsis>
<replaceable>record</replaceable> <replaceable>operator</replaceable> <replaceable>record</replaceable>
</synopsis>
<para>
The SQL specification requires row-wise comparison to return NULL if the
result depends on comparing two NULL values or a NULL and a non-NULL.
<productname>PostgreSQL</productname> does this only when comparing the
results of two row constructors (as in
<xref linkend="row-wise-comparison"/>) or comparing a row constructor
to the output of a subquery (as in <xref linkend="functions-subquery"/>).
In other contexts where two composite-type values are compared, two
NULL field values are considered equal, and a NULL is considered larger
than a non-NULL. This is necessary in order to have consistent sorting
and indexing behavior for composite types.
</para>
<para>
Each side is evaluated and they are compared row-wise. Composite type
comparisons are allowed when the <replaceable>operator</replaceable> is
<literal>=</literal>,
<literal>&lt;&gt;</literal>,
<literal>&lt;</literal>,
<literal>&lt;=</literal>,
<literal>&gt;</literal> or
<literal>&gt;=</literal>,
or has semantics similar to one of these. (To be specific, an operator
can be a row comparison operator if it is a member of a B-tree operator
class, or is the negator of the <literal>=</literal> member of a B-tree operator
class.) The default behavior of the above operators is the same as for
<literal>IS [ NOT ] DISTINCT FROM</literal> for row constructors (see
<xref linkend="row-wise-comparison"/>).
</para>
<para>
To support matching of rows which include elements without a default
B-tree operator class, the following operators are defined for composite
type comparison:
<literal>*=</literal>,
<literal>*&lt;&gt;</literal>,
<literal>*&lt;</literal>,
<literal>*&lt;=</literal>,
<literal>*&gt;</literal>, and
<literal>*&gt;=</literal>.
These operators compare the internal binary representation of the two
rows. Two rows might have a different binary representation even
though comparisons of the two rows with the equality operator is true.
The ordering of rows under these comparison operators is deterministic
but not otherwise meaningful. These operators are used internally
for materialized views and might be useful for other specialized
purposes such as replication and B-Tree deduplication (see <xref
linkend="btree-deduplication"/>). They are not intended to be
generally useful for writing queries, though.
</para>
</sect2>
</sect1>

283
doc/src/sgml/func/func-conditional.sgml
Unescape View File

@ -0,0 +1,283 @@
<sect1 id="functions-conditional">
<title>Conditional Expressions</title>
<indexterm>
<primary>CASE</primary>
</indexterm>
<indexterm>
<primary>conditional expression</primary>
</indexterm>
<para>
This section describes the <acronym>SQL</acronym>-compliant conditional expressions
available in <productname>PostgreSQL</productname>.
</para>
<tip>
<para>
If your needs go beyond the capabilities of these conditional
expressions, you might want to consider writing a server-side function
in a more expressive programming language.
</para>
</tip>
<note>
<para>
Although <token>COALESCE</token>, <token>GREATEST</token>, and
<token>LEAST</token> are syntactically similar to functions, they are
not ordinary functions, and thus cannot be used with explicit
<token>VARIADIC</token> array arguments.
</para>
</note>
<sect2 id="functions-case">
<title><literal>CASE</literal></title>
<para>
The <acronym>SQL</acronym> <token>CASE</token> expression is a
generic conditional expression, similar to if/else statements in
other programming languages:
<synopsis>
CASE WHEN <replaceable>condition</replaceable> THEN <replaceable>result</replaceable>
<optional>WHEN ...</optional>
<optional>ELSE <replaceable>result</replaceable></optional>
END
</synopsis>
<token>CASE</token> clauses can be used wherever
an expression is valid. Each <replaceable>condition</replaceable> is an
expression that returns a <type>boolean</type> result. If the condition's
result is true, the value of the <token>CASE</token> expression is the
<replaceable>result</replaceable> that follows the condition, and the
remainder of the <token>CASE</token> expression is not processed. If the
condition's result is not true, any subsequent <token>WHEN</token> clauses
are examined in the same manner. If no <token>WHEN</token>
<replaceable>condition</replaceable> yields true, the value of the
<token>CASE</token> expression is the <replaceable>result</replaceable> of the
<token>ELSE</token> clause. If the <token>ELSE</token> clause is
omitted and no condition is true, the result is null.
</para>
<para>
An example:
<screen>
SELECT * FROM test;
a
---
1
2
3
SELECT a,
CASE WHEN a=1 THEN 'one'
WHEN a=2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
</screen>
</para>
<para>
The data types of all the <replaceable>result</replaceable>
expressions must be convertible to a single output type.
See <xref linkend="typeconv-union-case"/> for more details.
</para>
<para>
There is a <quote>simple</quote> form of <token>CASE</token> expression
that is a variant of the general form above:
<synopsis>
CASE <replaceable>expression</replaceable>
WHEN <replaceable>value</replaceable> THEN <replaceable>result</replaceable>
<optional>WHEN ...</optional>
<optional>ELSE <replaceable>result</replaceable></optional>
END
</synopsis>
The first
<replaceable>expression</replaceable> is computed, then compared to
each of the <replaceable>value</replaceable> expressions in the
<token>WHEN</token> clauses until one is found that is equal to it. If
no match is found, the <replaceable>result</replaceable> of the
<token>ELSE</token> clause (or a null value) is returned. This is similar
to the <function>switch</function> statement in C.
</para>
<para>
The example above can be written using the simple
<token>CASE</token> syntax:
<screen>
SELECT a,
CASE a WHEN 1 THEN 'one'
WHEN 2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
</screen>
</para>
<para>
A <token>CASE</token> expression does not evaluate any subexpressions
that are not needed to determine the result. For example, this is a
possible way of avoiding a division-by-zero failure:
<programlisting>
SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
</programlisting>
</para>
<note>
<para>
As described in <xref linkend="syntax-express-eval"/>, there are various
situations in which subexpressions of an expression are evaluated at
different times, so that the principle that <quote><token>CASE</token>
evaluates only necessary subexpressions</quote> is not ironclad. For
example a constant <literal>1/0</literal> subexpression will usually result in
a division-by-zero failure at planning time, even if it's within
a <token>CASE</token> arm that would never be entered at run time.
</para>
</note>
</sect2>
<sect2 id="functions-coalesce-nvl-ifnull">
<title><literal>COALESCE</literal></title>
<indexterm>
<primary>COALESCE</primary>
</indexterm>
<indexterm>
<primary>NVL</primary>
</indexterm>
<indexterm>
<primary>IFNULL</primary>
</indexterm>
<synopsis>
<function>COALESCE</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
</synopsis>
<para>
The <function>COALESCE</function> function returns the first of its
arguments that is not null. Null is returned only if all arguments
are null. It is often used to substitute a default value for
null values when data is retrieved for display, for example:
<programlisting>
SELECT COALESCE(description, short_description, '(none)') ...
</programlisting>
This returns <varname>description</varname> if it is not null, otherwise
<varname>short_description</varname> if it is not null, otherwise <literal>(none)</literal>.
</para>
<para>
The arguments must all be convertible to a common data type, which
will be the type of the result (see
<xref linkend="typeconv-union-case"/> for details).
</para>
<para>
Like a <token>CASE</token> expression, <function>COALESCE</function> only
evaluates the arguments that are needed to determine the result;
that is, arguments to the right of the first non-null argument are
not evaluated. This SQL-standard function provides capabilities similar
to <function>NVL</function> and <function>IFNULL</function>, which are used in some other
database systems.
</para>
</sect2>
<sect2 id="functions-nullif">
<title><literal>NULLIF</literal></title>
<indexterm>
<primary>NULLIF</primary>
</indexterm>
<synopsis>
<function>NULLIF</function>(<replaceable>value1</replaceable>, <replaceable>value2</replaceable>)
</synopsis>
<para>
The <function>NULLIF</function> function returns a null value if
<replaceable>value1</replaceable> equals <replaceable>value2</replaceable>;
otherwise it returns <replaceable>value1</replaceable>.
This can be used to perform the inverse operation of the
<function>COALESCE</function> example given above:
<programlisting>
SELECT NULLIF(value, '(none)') ...
</programlisting>
In this example, if <literal>value</literal> is <literal>(none)</literal>,
null is returned, otherwise the value of <literal>value</literal>
is returned.
</para>
<para>
The two arguments must be of comparable types.
To be specific, they are compared exactly as if you had
written <literal><replaceable>value1</replaceable>
= <replaceable>value2</replaceable></literal>, so there must be a
suitable <literal>=</literal> operator available.
</para>
<para>
The result has the same type as the first argument &mdash; but there is
a subtlety. What is actually returned is the first argument of the
implied <literal>=</literal> operator, and in some cases that will have
been promoted to match the second argument's type. For
example, <literal>NULLIF(1, 2.2)</literal> yields <type>numeric</type>,
because there is no <type>integer</type> <literal>=</literal>
<type>numeric</type> operator,
only <type>numeric</type> <literal>=</literal> <type>numeric</type>.
</para>
</sect2>
<sect2 id="functions-greatest-least">
<title><literal>GREATEST</literal> and <literal>LEAST</literal></title>
<indexterm>
<primary>GREATEST</primary>
</indexterm>
<indexterm>
<primary>LEAST</primary>
</indexterm>
<synopsis>
<function>GREATEST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
</synopsis>
<synopsis>
<function>LEAST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
</synopsis>
<para>
The <function>GREATEST</function> and <function>LEAST</function> functions select the
largest or smallest value from a list of any number of expressions.
The expressions must all be convertible to a common data type, which
will be the type of the result
(see <xref linkend="typeconv-union-case"/> for details).
</para>
<para>
NULL values in the argument list are ignored. The result will be NULL
only if all the expressions evaluate to NULL. (This is a deviation from
the SQL standard. According to the standard, the return value is NULL if
any argument is NULL. Some other databases behave this way.)
</para>
</sect2>
</sect1>

2200
doc/src/sgml/func/func-datetime.sgml
View File

File diff suppressed because it is too large Load Diff

121
doc/src/sgml/func/func-enum.sgml
Unescape View File

@ -0,0 +1,121 @@
<sect1 id="functions-enum">
<title>Enum Support Functions</title>
<para>
For enum types (described in <xref linkend="datatype-enum"/>),
there are several functions that allow cleaner programming without
hard-coding particular values of an enum type.
These are listed in <xref linkend="functions-enum-table"/>. The examples
assume an enum type created as:
<programlisting>
CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
</programlisting>
</para>
<table id="functions-enum-table">
<title>Enum Support 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>enum_first</primary>
</indexterm>
<function>enum_first</function> ( <type>anyenum</type> )
<returnvalue>anyenum</returnvalue>
</para>
<para>
Returns the first value of the input enum type.
</para>
<para>
<literal>enum_first(null::rainbow)</literal>
<returnvalue>red</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>enum_last</primary>
</indexterm>
<function>enum_last</function> ( <type>anyenum</type> )
<returnvalue>anyenum</returnvalue>
</para>
<para>
Returns the last value of the input enum type.
</para>
<para>
<literal>enum_last(null::rainbow)</literal>
<returnvalue>purple</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>enum_range</primary>
</indexterm>
<function>enum_range</function> ( <type>anyenum</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Returns all values of the input enum type in an ordered array.
</para>
<para>
<literal>enum_range(null::rainbow)</literal>
<returnvalue>{red,orange,yellow,&zwsp;green,blue,purple}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>enum_range</function> ( <type>anyenum</type>, <type>anyenum</type> )
<returnvalue>anyarray</returnvalue>
</para>
<para>
Returns the range between the two given enum values, as an ordered
array. The values must be from the same enum type. If the first
parameter is null, the result will start with the first value of
the enum type.
If the second parameter is null, the result will end with the last
value of the enum type.
</para>
<para>
<literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal>
<returnvalue>{orange,yellow,green}</returnvalue>
</para>
<para>
<literal>enum_range(NULL, 'green'::rainbow)</literal>
<returnvalue>{red,orange,&zwsp;yellow,green}</returnvalue>
</para>
<para>
<literal>enum_range('orange'::rainbow, NULL)</literal>
<returnvalue>{orange,yellow,green,&zwsp;blue,purple}</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Notice that except for the two-argument form of <function>enum_range</function>,
these functions disregard the specific value passed to them; they care
only about its declared data type. Either null or a specific value of
the type can be passed, with the same result. It is more common to
apply these functions to a table column or function argument than to
a hardwired type name as used in the examples.
</para>
</sect1>

332
doc/src/sgml/func/func-event-triggers.sgml
Unescape View File

@ -0,0 +1,332 @@
<sect1 id="functions-event-triggers">
<title>Event Trigger Functions</title>
<para>
<productname>PostgreSQL</productname> provides these helper functions
to retrieve information from event triggers.
</para>
<para>
For more information about event triggers,
see <xref linkend="event-triggers"/>.
</para>
<sect2 id="pg-event-trigger-ddl-command-end-functions">
<title>Capturing Changes at Command End</title>
<indexterm>
<primary>pg_event_trigger_ddl_commands</primary>
</indexterm>
<synopsis>
<function>pg_event_trigger_ddl_commands</function> () <returnvalue>setof record</returnvalue>
</synopsis>
<para>
<function>pg_event_trigger_ddl_commands</function> returns a list of
<acronym>DDL</acronym> commands executed by each user action,
when invoked in a function attached to a
<literal>ddl_command_end</literal> event trigger. If called in any other
context, an error is raised.
<function>pg_event_trigger_ddl_commands</function> returns one row for each
base command executed; some commands that are a single SQL sentence
may return more than one row. This function returns the following
columns:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>classid</literal></entry>
<entry><type>oid</type></entry>
<entry>OID of catalog the object belongs in</entry>
</row>
<row>
<entry><literal>objid</literal></entry>
<entry><type>oid</type></entry>
<entry>OID of the object itself</entry>
</row>
<row>
<entry><literal>objsubid</literal></entry>
<entry><type>integer</type></entry>
<entry>Sub-object ID (e.g., attribute number for a column)</entry>
</row>
<row>
<entry><literal>command_tag</literal></entry>
<entry><type>text</type></entry>
<entry>Command tag</entry>
</row>
<row>
<entry><literal>object_type</literal></entry>
<entry><type>text</type></entry>
<entry>Type of the object</entry>
</row>
<row>
<entry><literal>schema_name</literal></entry>
<entry><type>text</type></entry>
<entry>
Name of the schema the object belongs in, if any; otherwise <literal>NULL</literal>.
No quoting is applied.
</entry>
</row>
<row>
<entry><literal>object_identity</literal></entry>
<entry><type>text</type></entry>
<entry>
Text rendering of the object identity, schema-qualified. Each
identifier included in the identity is quoted if necessary.
</entry>
</row>
<row>
<entry><literal>in_extension</literal></entry>
<entry><type>boolean</type></entry>
<entry>True if the command is part of an extension script</entry>
</row>
<row>
<entry><literal>command</literal></entry>
<entry><type>pg_ddl_command</type></entry>
<entry>
A complete representation of the command, in internal format.
This cannot be output directly, but it can be passed to other
functions to obtain different pieces of information about the
command.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</sect2>
<sect2 id="pg-event-trigger-sql-drop-functions">
<title>Processing Objects Dropped by a DDL Command</title>
<indexterm>
<primary>pg_event_trigger_dropped_objects</primary>
</indexterm>
<synopsis>
<function>pg_event_trigger_dropped_objects</function> () <returnvalue>setof record</returnvalue>
</synopsis>
<para>
<function>pg_event_trigger_dropped_objects</function> returns a list of all objects
dropped by the command in whose <literal>sql_drop</literal> event it is called.
If called in any other context, an error is raised.
This function returns the following columns:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>classid</literal></entry>
<entry><type>oid</type></entry>
<entry>OID of catalog the object belonged in</entry>
</row>
<row>
<entry><literal>objid</literal></entry>
<entry><type>oid</type></entry>
<entry>OID of the object itself</entry>
</row>
<row>
<entry><literal>objsubid</literal></entry>
<entry><type>integer</type></entry>
<entry>Sub-object ID (e.g., attribute number for a column)</entry>
</row>
<row>
<entry><literal>original</literal></entry>
<entry><type>boolean</type></entry>
<entry>True if this was one of the root object(s) of the deletion</entry>
</row>
<row>
<entry><literal>normal</literal></entry>
<entry><type>boolean</type></entry>
<entry>
True if there was a normal dependency relationship
in the dependency graph leading to this object
</entry>
</row>
<row>
<entry><literal>is_temporary</literal></entry>
<entry><type>boolean</type></entry>
<entry>
True if this was a temporary object
</entry>
</row>
<row>
<entry><literal>object_type</literal></entry>
<entry><type>text</type></entry>
<entry>Type of the object</entry>
</row>
<row>
<entry><literal>schema_name</literal></entry>
<entry><type>text</type></entry>
<entry>
Name of the schema the object belonged in, if any; otherwise <literal>NULL</literal>.
No quoting is applied.
</entry>
</row>
<row>
<entry><literal>object_name</literal></entry>
<entry><type>text</type></entry>
<entry>
Name of the object, if the combination of schema and name can be
used as a unique identifier for the object; otherwise <literal>NULL</literal>.
No quoting is applied, and name is never schema-qualified.
</entry>
</row>
<row>
<entry><literal>object_identity</literal></entry>
<entry><type>text</type></entry>
<entry>
Text rendering of the object identity, schema-qualified. Each
identifier included in the identity is quoted if necessary.
</entry>
</row>
<row>
<entry><literal>address_names</literal></entry>
<entry><type>text[]</type></entry>
<entry>
An array that, together with <literal>object_type</literal> and
<literal>address_args</literal>, can be used by
the <function>pg_get_object_address</function> function to
recreate the object address in a remote server containing an
identically named object of the same kind.
</entry>
</row>
<row>
<entry><literal>address_args</literal></entry>
<entry><type>text[]</type></entry>
<entry>
Complement for <literal>address_names</literal>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The <function>pg_event_trigger_dropped_objects</function> function can be used
in an event trigger like this:
<programlisting>
CREATE FUNCTION test_event_trigger_for_drops()
RETURNS event_trigger LANGUAGE plpgsql AS $$
DECLARE
obj record;
BEGIN
FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects()
LOOP
RAISE NOTICE '% dropped object: % %.% %',
tg_tag,
obj.object_type,
obj.schema_name,
obj.object_name,
obj.object_identity;
END LOOP;
END;
$$;
CREATE EVENT TRIGGER test_event_trigger_for_drops
ON sql_drop
EXECUTE FUNCTION test_event_trigger_for_drops();
</programlisting>
</para>
</sect2>
<sect2 id="pg-event-trigger-table-rewrite-functions">
<title>Handling a Table Rewrite Event</title>
<para>
The functions shown in
<xref linkend="functions-event-trigger-table-rewrite"/>
provide information about a table for which a
<literal>table_rewrite</literal> event has just been called.
If called in any other context, an error is raised.
</para>
<table id="functions-event-trigger-table-rewrite">
<title>Table Rewrite Information 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">
<indexterm>
<primary>pg_event_trigger_table_rewrite_oid</primary>
</indexterm>
<function>pg_event_trigger_table_rewrite_oid</function> ()
<returnvalue>oid</returnvalue>
</para>
<para>
Returns the OID of the table about to be rewritten.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_event_trigger_table_rewrite_reason</primary>
</indexterm>
<function>pg_event_trigger_table_rewrite_reason</function> ()
<returnvalue>integer</returnvalue>
</para>
<para>
Returns a code explaining the reason(s) for rewriting. The value is
a bitmap built from the following values: <literal>1</literal>
(the table has changed its persistence), <literal>2</literal>
(default value of a column has changed), <literal>4</literal>
(a column has a new data type) and <literal>8</literal>
(the table access method has changed).
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
These functions can be used in an event trigger like this:
<programlisting>
CREATE FUNCTION test_event_trigger_table_rewrite_oid()
RETURNS event_trigger
LANGUAGE plpgsql AS
$$
BEGIN
RAISE NOTICE 'rewriting table % for reason %',
pg_event_trigger_table_rewrite_oid()::regclass,
pg_event_trigger_table_rewrite_reason();
END;
$$;
CREATE EVENT TRIGGER test_table_rewrite_oid
ON table_rewrite
EXECUTE FUNCTION test_event_trigger_table_rewrite_oid();
</programlisting>
</para>
</sect2>
</sect1>

1193
doc/src/sgml/func/func-formatting.sgml
View File

File diff suppressed because it is too large Load Diff

1261
doc/src/sgml/func/func-geometry.sgml
View File

File diff suppressed because it is too large Load Diff

3790
doc/src/sgml/func/func-info.sgml
View File

File diff suppressed because it is too large Load Diff

3945
doc/src/sgml/func/func-json.sgml
View File

File diff suppressed because it is too large Load Diff

146
doc/src/sgml/func/func-logical.sgml
Unescape View File

@ -0,0 +1,146 @@
<sect1 id="functions-logical">
<title>Logical Operators</title>
<indexterm zone="functions-logical">
<primary>operator</primary>
<secondary>logical</secondary>
</indexterm>
<indexterm>
<primary>Boolean</primary>
<secondary>operators</secondary>
<see>operators, logical</see>
</indexterm>
<para>
The usual logical operators are available:
<indexterm>
<primary>AND (operator)</primary>
</indexterm>
<indexterm>
<primary>OR (operator)</primary>
</indexterm>
<indexterm>
<primary>NOT (operator)</primary>
</indexterm>
<indexterm>
<primary>conjunction</primary>
</indexterm>
<indexterm>
<primary>disjunction</primary>
</indexterm>
<indexterm>
<primary>negation</primary>
</indexterm>
<synopsis>
<type>boolean</type> <literal>AND</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
<type>boolean</type> <literal>OR</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
<literal>NOT</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
</synopsis>
<acronym>SQL</acronym> uses a three-valued logic system with true,
false, and <literal>null</literal>, which represents <quote>unknown</quote>.
Observe the following truth tables:
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry><replaceable>a</replaceable></entry>
<entry><replaceable>b</replaceable></entry>
<entry><replaceable>a</replaceable> AND <replaceable>b</replaceable></entry>
<entry><replaceable>a</replaceable> OR <replaceable>b</replaceable></entry>
</row>
</thead>
<tbody>
<row>
<entry>TRUE</entry>
<entry>TRUE</entry>
<entry>TRUE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>TRUE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>TRUE</entry>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>NULL</entry>
<entry>FALSE</entry>
<entry>NULL</entry>
</row>
<row>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>NULL</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry><replaceable>a</replaceable></entry>
<entry>NOT <replaceable>a</replaceable></entry>
</row>
</thead>
<tbody>
<row>
<entry>TRUE</entry>
<entry>FALSE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>NULL</entry>
<entry>NULL</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The operators <literal>AND</literal> and <literal>OR</literal> are
commutative, that is, you can switch the left and right operands
without affecting the result. (However, it is not guaranteed that
the left operand is evaluated before the right operand. See <xref
linkend="syntax-express-eval"/> for more information about the
order of evaluation of subexpressions.)
</para>
</sect1>

2471
doc/src/sgml/func/func-matching.sgml
View File

File diff suppressed because it is too large Load Diff

1615
doc/src/sgml/func/func-math.sgml
View File

File diff suppressed because it is too large Load Diff

78
doc/src/sgml/func/func-merge-support.sgml
Unescape View File

@ -0,0 +1,78 @@
<sect1 id="functions-merge-support">
<title>Merge Support Functions</title>
<indexterm>
<primary>MERGE</primary>
<secondary>RETURNING</secondary>
</indexterm>
<para>
<productname>PostgreSQL</productname> includes one merge support function
that may be used in the <literal>RETURNING</literal> list of a
<xref linkend="sql-merge"/> command to identify the action taken for each
row; see <xref linkend="functions-merge-support-table"/>.
</para>
<table id="functions-merge-support-table">
<title>Merge Support 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 id="merge-action" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>merge_action</primary>
</indexterm>
<function>merge_action</function> ( )
<returnvalue>text</returnvalue>
</para>
<para>
Returns the merge action command executed for the current row. This
will be <literal>'INSERT'</literal>, <literal>'UPDATE'</literal>, or
<literal>'DELETE'</literal>.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Example:
<screen><![CDATA[
MERGE INTO products p
USING stock s ON p.product_id = s.product_id
WHEN MATCHED AND s.quantity > 0 THEN
UPDATE SET in_stock = true, quantity = s.quantity
WHEN MATCHED THEN
UPDATE SET in_stock = false, quantity = 0
WHEN NOT MATCHED THEN
INSERT (product_id, in_stock, quantity)
VALUES (s.product_id, true, s.quantity)
RETURNING merge_action(), p.*;
merge_action | product_id | in_stock | quantity
--------------+------------+----------+----------
UPDATE | 1001 | t | 50
UPDATE | 1002 | f | 0
INSERT | 1003 | t | 10
]]></screen>
</para>
<para>
Note that this function can only be used in the <literal>RETURNING</literal>
list of a <command>MERGE</command> command. It is an error to use it in any
other part of a query.
</para>
</sect1>

592
doc/src/sgml/func/func-net.sgml
Unescape View File

@ -0,0 +1,592 @@
<sect1 id="functions-net">
<title>Network Address Functions and Operators</title>
<para>
The IP network address types, <type>cidr</type> and <type>inet</type>,
support the usual comparison operators shown in
<xref linkend="functions-comparison-op-table"/>
as well as the specialized operators and functions shown in
<xref linkend="cidr-inet-operators-table"/> and
<xref linkend="cidr-inet-functions-table"/>.
</para>
<para>
Any <type>cidr</type> value can be cast to <type>inet</type> implicitly;
therefore, the operators and functions shown below as operating on
<type>inet</type> also work on <type>cidr</type> values. (Where there are
separate functions for <type>inet</type> and <type>cidr</type>, it is
because the behavior should be different for the two cases.)
Also, it is permitted to cast an <type>inet</type> value
to <type>cidr</type>. When this is done, any bits to the right of the
netmask are silently zeroed to create a valid <type>cidr</type> value.
</para>
<table id="cidr-inet-operators-table">
<title>IP Address 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">
<type>inet</type> <literal>&lt;&lt;</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Is subnet strictly contained by subnet?
This operator, and the next four, test for subnet inclusion. They
consider only the network parts of the two addresses (ignoring any
bits to the right of the netmasks) and determine whether one network
is identical to or a subnet of the other.
</para>
<para>
<literal>inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>inet '192.168.0.5' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>inet '192.168.1/24' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>&lt;&lt;=</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Is subnet contained by or equal to subnet?
</para>
<para>
<literal>inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>&gt;&gt;</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Does subnet strictly contain subnet?
</para>
<para>
<literal>inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>&gt;&gt;=</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Does subnet contain or equal subnet?
</para>
<para>
<literal>inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>&amp;&amp;</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Does either subnet contain or equal the other?
</para>
<para>
<literal>inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>inet '192.168.1/24' &amp;&amp; inet '192.168.2.0/28'</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>~</literal> <type>inet</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Computes bitwise NOT.
</para>
<para>
<literal>~ inet '192.168.1.6'</literal>
<returnvalue>63.87.254.249</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>&amp;</literal> <type>inet</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Computes bitwise AND.
</para>
<para>
<literal>inet '192.168.1.6' &amp; inet '0.0.0.255'</literal>
<returnvalue>0.0.0.6</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>|</literal> <type>inet</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Computes bitwise OR.
</para>
<para>
<literal>inet '192.168.1.6' | inet '0.0.0.255'</literal>
<returnvalue>192.168.1.255</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>+</literal> <type>bigint</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Adds an offset to an address.
</para>
<para>
<literal>inet '192.168.1.6' + 25</literal>
<returnvalue>192.168.1.31</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bigint</type> <literal>+</literal> <type>inet</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Adds an offset to an address.
</para>
<para>
<literal>200 + inet '::ffff:fff0:1'</literal>
<returnvalue>::ffff:255.240.0.201</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>-</literal> <type>bigint</type>
<returnvalue>inet</returnvalue>
</para>
<para>
Subtracts an offset from an address.
</para>
<para>
<literal>inet '192.168.1.43' - 36</literal>
<returnvalue>192.168.1.7</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>inet</type> <literal>-</literal> <type>inet</type>
<returnvalue>bigint</returnvalue>
</para>
<para>
Computes the difference of two addresses.
</para>
<para>
<literal>inet '192.168.1.43' - inet '192.168.1.19'</literal>
<returnvalue>24</returnvalue>
</para>
<para>
<literal>inet '::1' - inet '::ffff:1'</literal>
<returnvalue>-4294901760</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<table id="cidr-inet-functions-table">
<title>IP Address 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>abbrev</primary>
</indexterm>
<function>abbrev</function> ( <type>inet</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Creates an abbreviated display format as text.
(The result is the same as the <type>inet</type> output function
produces; it is <quote>abbreviated</quote> only in comparison to the
result of an explicit cast to <type>text</type>, which for historical
reasons will never suppress the netmask part.)
</para>
<para>
<literal>abbrev(inet '10.1.0.0/32')</literal>
<returnvalue>10.1.0.0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>abbrev</function> ( <type>cidr</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Creates an abbreviated display format as text.
(The abbreviation consists of dropping all-zero octets to the right
of the netmask; more examples are in
<xref linkend="datatype-net-cidr-table"/>.)
</para>
<para>
<literal>abbrev(cidr '10.1.0.0/16')</literal>
<returnvalue>10.1/16</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>broadcast</primary>
</indexterm>
<function>broadcast</function> ( <type>inet</type> )
<returnvalue>inet</returnvalue>
</para>
<para>
Computes the broadcast address for the address's network.
</para>
<para>
<literal>broadcast(inet '192.168.1.5/24')</literal>
<returnvalue>192.168.1.255/24</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>family</primary>
</indexterm>
<function>family</function> ( <type>inet</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the address's family: <literal>4</literal> for IPv4,
<literal>6</literal> for IPv6.
</para>
<para>
<literal>family(inet '::1')</literal>
<returnvalue>6</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>host</primary>
</indexterm>
<function>host</function> ( <type>inet</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns the IP address as text, ignoring the netmask.
</para>
<para>
<literal>host(inet '192.168.1.0/24')</literal>
<returnvalue>192.168.1.0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>hostmask</primary>
</indexterm>
<function>hostmask</function> ( <type>inet</type> )
<returnvalue>inet</returnvalue>
</para>
<para>
Computes the host mask for the address's network.
</para>
<para>
<literal>hostmask(inet '192.168.23.20/30')</literal>
<returnvalue>0.0.0.3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>inet_merge</primary>
</indexterm>
<function>inet_merge</function> ( <type>inet</type>, <type>inet</type> )
<returnvalue>cidr</returnvalue>
</para>
<para>
Computes the smallest network that includes both of the given networks.
</para>
<para>
<literal>inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')</literal>
<returnvalue>192.168.0.0/22</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>inet_same_family</primary>
</indexterm>
<function>inet_same_family</function> ( <type>inet</type>, <type>inet</type> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Tests whether the addresses belong to the same IP family.
</para>
<para>
<literal>inet_same_family(inet '192.168.1.5/24', inet '::1')</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>masklen</primary>
</indexterm>
<function>masklen</function> ( <type>inet</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the netmask length in bits.
</para>
<para>
<literal>masklen(inet '192.168.1.5/24')</literal>
<returnvalue>24</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>netmask</primary>
</indexterm>
<function>netmask</function> ( <type>inet</type> )
<returnvalue>inet</returnvalue>
</para>
<para>
Computes the network mask for the address's network.
</para>
<para>
<literal>netmask(inet '192.168.1.5/24')</literal>
<returnvalue>255.255.255.0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>network</primary>
</indexterm>
<function>network</function> ( <type>inet</type> )
<returnvalue>cidr</returnvalue>
</para>
<para>
Returns the network part of the address, zeroing out
whatever is to the right of the netmask.
(This is equivalent to casting the value to <type>cidr</type>.)
</para>
<para>
<literal>network(inet '192.168.1.5/24')</literal>
<returnvalue>192.168.1.0/24</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_masklen</primary>
</indexterm>
<function>set_masklen</function> ( <type>inet</type>, <type>integer</type> )
<returnvalue>inet</returnvalue>
</para>
<para>
Sets the netmask length for an <type>inet</type> value.
The address part does not change.
</para>
<para>
<literal>set_masklen(inet '192.168.1.5/24', 16)</literal>
<returnvalue>192.168.1.5/16</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>set_masklen</function> ( <type>cidr</type>, <type>integer</type> )
<returnvalue>cidr</returnvalue>
</para>
<para>
Sets the netmask length for a <type>cidr</type> value.
Address bits to the right of the new netmask are set to zero.
</para>
<para>
<literal>set_masklen(cidr '192.168.1.0/24', 16)</literal>
<returnvalue>192.168.0.0/16</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>text</primary>
</indexterm>
<function>text</function> ( <type>inet</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns the unabbreviated IP address and netmask length as text.
(This has the same result as an explicit cast to <type>text</type>.)
</para>
<para>
<literal>text(inet '192.168.1.5')</literal>
<returnvalue>192.168.1.5/32</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<tip>
<para>
The <function>abbrev</function>, <function>host</function>,
and <function>text</function> functions are primarily intended to offer
alternative display formats for IP addresses.
</para>
</tip>
<para>
The MAC address types, <type>macaddr</type> and <type>macaddr8</type>,
support the usual comparison operators shown in
<xref linkend="functions-comparison-op-table"/>
as well as the specialized functions shown in
<xref linkend="macaddr-functions-table"/>.
In addition, they support the bitwise logical operators
<literal>~</literal>, <literal>&amp;</literal> and <literal>|</literal>
(NOT, AND and OR), just as shown above for IP addresses.
</para>
<table id="macaddr-functions-table">
<title>MAC Address 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>trunc</primary>
</indexterm>
<function>trunc</function> ( <type>macaddr</type> )
<returnvalue>macaddr</returnvalue>
</para>
<para>
Sets the last 3 bytes of the address to zero. The remaining prefix
can be associated with a particular manufacturer (using data not
included in <productname>PostgreSQL</productname>).
</para>
<para>
<literal>trunc(macaddr '12:34:56:78:90:ab')</literal>
<returnvalue>12:34:56:00:00:00</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>trunc</function> ( <type>macaddr8</type> )
<returnvalue>macaddr8</returnvalue>
</para>
<para>
Sets the last 5 bytes of the address to zero. The remaining prefix
can be associated with a particular manufacturer (using data not
included in <productname>PostgreSQL</productname>).
</para>
<para>
<literal>trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</literal>
<returnvalue>12:34:56:00:00:00:00:00</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>macaddr8_set7bit</primary>
</indexterm>
<function>macaddr8_set7bit</function> ( <type>macaddr8</type> )
<returnvalue>macaddr8</returnvalue>
</para>
<para>
Sets the 7th bit of the address to one, creating what is known as
modified EUI-64, for inclusion in an IPv6 address.
</para>
<para>
<literal>macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</literal>
<returnvalue>02:34:56:ff:fe:ab:cd:ef</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>

1053
doc/src/sgml/func/func-range.sgml
View File

File diff suppressed because it is too large Load Diff

195
doc/src/sgml/func/func-sequence.sgml
Unescape View File

@ -0,0 +1,195 @@
<sect1 id="functions-sequence">
<title>Sequence Manipulation Functions</title>
<indexterm>
<primary>sequence</primary>
</indexterm>
<para>
This section describes functions for operating on <firstterm>sequence
objects</firstterm>, also called sequence generators or just sequences.
Sequence objects are special single-row tables created with <xref
linkend="sql-createsequence"/>.
Sequence objects are commonly used to generate unique identifiers
for rows of a table. The sequence functions, listed in <xref
linkend="functions-sequence-table"/>, provide simple, multiuser-safe
methods for obtaining successive sequence values from sequence
objects.
</para>
<table id="functions-sequence-table">
<title>Sequence 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">
<indexterm>
<primary>nextval</primary>
</indexterm>
<function>nextval</function> ( <type>regclass</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Advances the sequence object to its next value and returns that value.
This is done atomically: even if multiple sessions
execute <function>nextval</function> concurrently, each will safely
receive a distinct sequence value.
If the sequence object has been created with default parameters,
successive <function>nextval</function> calls will return successive
values beginning with 1. Other behaviors can be obtained by using
appropriate parameters in the <xref linkend="sql-createsequence"/>
command.
</para>
<para>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>setval</primary>
</indexterm>
<function>setval</function> ( <type>regclass</type>, <type>bigint</type> <optional>, <type>boolean</type> </optional> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Sets the sequence object's current value, and optionally
its <literal>is_called</literal> flag. The two-parameter
form sets the sequence's <literal>last_value</literal> field to the
specified value and sets its <literal>is_called</literal> field to
<literal>true</literal>, meaning that the next
<function>nextval</function> will advance the sequence before
returning a value. The value that will be reported
by <function>currval</function> is also set to the specified value.
In the three-parameter form, <literal>is_called</literal> can be set
to either <literal>true</literal>
or <literal>false</literal>. <literal>true</literal> has the same
effect as the two-parameter form. If it is set
to <literal>false</literal>, the next <function>nextval</function>
will return exactly the specified value, and sequence advancement
commences with the following <function>nextval</function>.
Furthermore, the value reported by <function>currval</function> is not
changed in this case. For example,
<programlisting>
SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation>
SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation>
SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation>
</programlisting>
The result returned by <function>setval</function> is just the value of its
second argument.
</para>
<para>
This function requires <literal>UPDATE</literal> privilege on the
sequence.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>currval</primary>
</indexterm>
<function>currval</function> ( <type>regclass</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the value most recently obtained
by <function>nextval</function> for this sequence in the current
session. (An error is reported if <function>nextval</function> has
never been called for this sequence in this session.) Because this is
returning a session-local value, it gives a predictable answer whether
or not other sessions have executed <function>nextval</function> since
the current session did.
</para>
<para>
This function requires <literal>USAGE</literal>
or <literal>SELECT</literal> privilege on the sequence.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lastval</primary>
</indexterm>
<function>lastval</function> ()
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the value most recently returned by
<function>nextval</function> in the current session. This function is
identical to <function>currval</function>, except that instead
of taking the sequence name as an argument it refers to whichever
sequence <function>nextval</function> was most recently applied to
in the current session. It is an error to call
<function>lastval</function> if <function>nextval</function>
has not yet been called in the current session.
</para>
<para>
This function requires <literal>USAGE</literal>
or <literal>SELECT</literal> privilege on the last used sequence.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
the same sequence, the value obtained by <function>nextval</function>
is not reclaimed for re-use if the calling transaction later aborts.
This means that transaction aborts or database crashes can result in
gaps in the sequence of assigned values. That can happen without a
transaction abort, too. For example an <command>INSERT</command> with
an <literal>ON CONFLICT</literal> clause will compute the to-be-inserted
tuple, including doing any required <function>nextval</function>
calls, before detecting any conflict that would cause it to follow
the <literal>ON CONFLICT</literal> rule instead.
Thus, <productname>PostgreSQL</productname> sequence
objects <emphasis>cannot be used to obtain <quote>gapless</quote>
sequences</emphasis>.
</para>
<para>
Likewise, sequence state changes made by <function>setval</function>
are immediately visible to other transactions, and are not undone if
the calling transaction rolls back.
</para>
<para>
If the database cluster crashes before committing a transaction
containing a <function>nextval</function>
or <function>setval</function> call, the sequence state change might
not have made its way to persistent storage, so that it is uncertain
whether the sequence will have its original or updated state after the
cluster restarts. This is harmless for usage of the sequence within
the database, since other effects of uncommitted transactions will not
be visible either. However, if you wish to use a sequence value for
persistent outside-the-database purposes, make sure that the
<function>nextval</function> call has been committed before doing so.
</para>
</caution>
<para>
The sequence to be operated on by a sequence function is specified by
a <type>regclass</type> argument, which is simply the OID of the sequence in the
<structname>pg_class</structname> system catalog. You do not have to look up the
OID by hand, however, since the <type>regclass</type> data type's input
converter will do the work for you. See <xref linkend="datatype-oid"/>
for details.
</para>
</sect1>

306
doc/src/sgml/func/func-srf.sgml
Unescape View File

@ -0,0 +1,306 @@
<sect1 id="functions-srf">
<title>Set Returning Functions</title>
<indexterm zone="functions-srf">
<primary>set returning functions</primary>
<secondary>functions</secondary>
</indexterm>
<para>
This section describes functions that possibly return more than one row.
The most widely used functions in this class are series generating
functions, as detailed in <xref linkend="functions-srf-series"/> and
<xref linkend="functions-srf-subscripts"/>. Other, more specialized
set-returning functions are described elsewhere in this manual.
See <xref linkend="queries-tablefunctions"/> for ways to combine multiple
set-returning functions.
</para>
<table id="functions-srf-series">
<title>Series Generating 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">
<indexterm>
<primary>generate_series</primary>
</indexterm>
<function>generate_series</function> ( <parameter>start</parameter> <type>integer</type>, <parameter>stop</parameter> <type>integer</type> <optional>, <parameter>step</parameter> <type>integer</type> </optional> )
<returnvalue>setof integer</returnvalue>
</para>
<para role="func_signature">
<function>generate_series</function> ( <parameter>start</parameter> <type>bigint</type>, <parameter>stop</parameter> <type>bigint</type> <optional>, <parameter>step</parameter> <type>bigint</type> </optional> )
<returnvalue>setof bigint</returnvalue>
</para>
<para role="func_signature">
<function>generate_series</function> ( <parameter>start</parameter> <type>numeric</type>, <parameter>stop</parameter> <type>numeric</type> <optional>, <parameter>step</parameter> <type>numeric</type> </optional> )
<returnvalue>setof numeric</returnvalue>
</para>
<para>
Generates a series of values from <parameter>start</parameter>
to <parameter>stop</parameter>, with a step size
of <parameter>step</parameter>. <parameter>step</parameter>
defaults to 1.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>generate_series</function> ( <parameter>start</parameter> <type>timestamp</type>, <parameter>stop</parameter> <type>timestamp</type>, <parameter>step</parameter> <type>interval</type> )
<returnvalue>setof timestamp</returnvalue>
</para>
<para role="func_signature">
<function>generate_series</function> ( <parameter>start</parameter> <type>timestamp with time zone</type>, <parameter>stop</parameter> <type>timestamp with time zone</type>, <parameter>step</parameter> <type>interval</type> <optional>, <parameter>timezone</parameter> <type>text</type> </optional> )
<returnvalue>setof timestamp with time zone</returnvalue>
</para>
<para>
Generates a series of values from <parameter>start</parameter>
to <parameter>stop</parameter>, with a step size
of <parameter>step</parameter>.
In the timezone-aware form, times of day and daylight-savings
adjustments are computed according to the time zone named by
the <parameter>timezone</parameter> argument, or the current
<xref linkend="guc-timezone"/> setting if that is omitted.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
When <parameter>step</parameter> is positive, zero rows are returned if
<parameter>start</parameter> is greater than <parameter>stop</parameter>.
Conversely, when <parameter>step</parameter> is negative, zero rows are
returned if <parameter>start</parameter> is less than <parameter>stop</parameter>.
Zero rows are also returned if any input is <literal>NULL</literal>.
It is an error
for <parameter>step</parameter> to be zero. Some examples follow:
<programlisting>
SELECT * FROM generate_series(2,4);
generate_series
-----------------
2
3
4
(3 rows)
SELECT * FROM generate_series(5,1,-2);
generate_series
-----------------
5
3
1
(3 rows)
SELECT * FROM generate_series(4,3);
generate_series
-----------------
(0 rows)
SELECT generate_series(1.1, 4, 1.3);
generate_series
-----------------
1.1
2.4
3.7
(3 rows)
-- this example relies on the date-plus-integer operator:
SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a);
dates
------------
2004-02-05
2004-02-12
2004-02-19
(3 rows)
SELECT * FROM generate_series('2008-03-01 00:00'::timestamp,
'2008-03-04 12:00', '10 hours');
generate_series
---------------------
2008-03-01 00:00:00
2008-03-01 10:00:00
2008-03-01 20:00:00
2008-03-02 06:00:00
2008-03-02 16:00:00
2008-03-03 02:00:00
2008-03-03 12:00:00
2008-03-03 22:00:00
2008-03-04 08:00:00
(9 rows)
-- this example assumes that TimeZone is set to UTC; note the DST transition:
SELECT * FROM generate_series('2001-10-22 00:00 -04:00'::timestamptz,
'2001-11-01 00:00 -05:00'::timestamptz,
'1 day'::interval, 'America/New_York');
generate_series
------------------------
2001-10-22 04:00:00+00
2001-10-23 04:00:00+00
2001-10-24 04:00:00+00
2001-10-25 04:00:00+00
2001-10-26 04:00:00+00
2001-10-27 04:00:00+00
2001-10-28 04:00:00+00
2001-10-29 05:00:00+00
2001-10-30 05:00:00+00
2001-10-31 05:00:00+00
2001-11-01 05:00:00+00
(11 rows)
</programlisting>
</para>
<table id="functions-srf-subscripts">
<title>Subscript Generating 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">
<indexterm>
<primary>generate_subscripts</primary>
</indexterm>
<function>generate_subscripts</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>dim</parameter> <type>integer</type> )
<returnvalue>setof integer</returnvalue>
</para>
<para>
Generates a series comprising the valid subscripts of
the <parameter>dim</parameter>'th dimension of the given array.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>generate_subscripts</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>dim</parameter> <type>integer</type>, <parameter>reverse</parameter> <type>boolean</type> )
<returnvalue>setof integer</returnvalue>
</para>
<para>
Generates a series comprising the valid subscripts of
the <parameter>dim</parameter>'th dimension of the given array.
When <parameter>reverse</parameter> is true, returns the series in
reverse order.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<function>generate_subscripts</function> is a convenience function that generates
the set of valid subscripts for the specified dimension of the given
array.
Zero rows are returned for arrays that do not have the requested dimension,
or if any input is <literal>NULL</literal>.
Some examples follow:
<programlisting>
-- basic usage:
SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s;
s
---
1
2
3
4
(4 rows)
-- presenting an array, the subscript and the subscripted
-- value requires a subquery:
SELECT * FROM arrays;
a
--------------------
{-1,-2}
{100,200,300}
(2 rows)
SELECT a AS array, s AS subscript, a[s] AS value
FROM (SELECT generate_subscripts(a, 1) AS s, a FROM arrays) foo;
array | subscript | value
---------------+-----------+-------
{-1,-2} | 1 | -1
{-1,-2} | 2 | -2
{100,200,300} | 1 | 100
{100,200,300} | 2 | 200
{100,200,300} | 3 | 300
(5 rows)
-- unnest a 2D array:
CREATE OR REPLACE FUNCTION unnest2(anyarray)
RETURNS SETOF anyelement AS $$
select $1[i][j]
from generate_subscripts($1,1) g1(i),
generate_subscripts($1,2) g2(j);
$$ LANGUAGE sql IMMUTABLE;
CREATE FUNCTION
SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]);
unnest2
---------
1
2
3
4
(4 rows)
</programlisting>
</para>
<indexterm>
<primary>ordinality</primary>
</indexterm>
<para>
When a function in the <literal>FROM</literal> clause is suffixed
by <literal>WITH ORDINALITY</literal>, a <type>bigint</type> column is
appended to the function's output column(s), which starts from 1 and
increments by 1 for each row of the function's output.
This is most useful in the case of set returning
functions such as <function>unnest()</function>.
<programlisting>
-- set returning function WITH ORDINALITY:
SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
ls | n
-----------------+----
pg_serial | 1
pg_twophase | 2
postmaster.opts | 3
pg_notify | 4
postgresql.conf | 5
pg_tblspc | 6
logfile | 7
base | 8
postmaster.pid | 9
pg_ident.conf | 10
global | 11
pg_xact | 12
pg_snapshots | 13
pg_multixact | 14
PG_VERSION | 15
pg_wal | 16
pg_hba.conf | 17
pg_stat_tmp | 18
pg_subtrans | 19
(19 rows)
</programlisting>
</para>
</sect1>

85
doc/src/sgml/func/func-statistics.sgml
Unescape View File

@ -0,0 +1,85 @@
<sect1 id="functions-statistics">
<title>Statistics Information Functions</title>
<indexterm zone="functions-statistics">
<primary>function</primary>
<secondary>statistics</secondary>
</indexterm>
<para>
<productname>PostgreSQL</productname> provides a function to inspect complex
statistics defined using the <command>CREATE STATISTICS</command> command.
</para>
<sect2 id="functions-statistics-mcv">
<title>Inspecting MCV Lists</title>
<indexterm>
<primary>pg_mcv_list_items</primary>
</indexterm>
<synopsis>
<function>pg_mcv_list_items</function> ( <type>pg_mcv_list</type> ) <returnvalue>setof record</returnvalue>
</synopsis>
<para>
<function>pg_mcv_list_items</function> returns a set of records describing
all items stored in a multi-column <acronym>MCV</acronym> list. It
returns the following columns:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>index</literal></entry>
<entry><type>integer</type></entry>
<entry>index of the item in the <acronym>MCV</acronym> list</entry>
</row>
<row>
<entry><literal>values</literal></entry>
<entry><type>text[]</type></entry>
<entry>values stored in the MCV item</entry>
</row>
<row>
<entry><literal>nulls</literal></entry>
<entry><type>boolean[]</type></entry>
<entry>flags identifying <literal>NULL</literal> values</entry>
</row>
<row>
<entry><literal>frequency</literal></entry>
<entry><type>double precision</type></entry>
<entry>frequency of this <acronym>MCV</acronym> item</entry>
</row>
<row>
<entry><literal>base_frequency</literal></entry>
<entry><type>double precision</type></entry>
<entry>base frequency of this <acronym>MCV</acronym> item</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The <function>pg_mcv_list_items</function> function can be used like this:
<programlisting>
SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts';
</programlisting>
Values of the <type>pg_mcv_list</type> type can be obtained only from the
<structname>pg_statistic_ext_data</structname>.<structfield>stxdmcv</structfield>
column.
</para>
</sect2>
</sect1>

1818
doc/src/sgml/func/func-string.sgml
View File

File diff suppressed because it is too large Load Diff

349
doc/src/sgml/func/func-subquery.sgml
Unescape View File

@ -0,0 +1,349 @@
<sect1 id="functions-subquery">
<title>Subquery Expressions</title>
<indexterm>
<primary>EXISTS</primary>
</indexterm>
<indexterm>
<primary>IN</primary>
</indexterm>
<indexterm>
<primary>NOT IN</primary>
</indexterm>
<indexterm>
<primary>ANY</primary>
</indexterm>
<indexterm>
<primary>ALL</primary>
</indexterm>
<indexterm>
<primary>SOME</primary>
</indexterm>
<indexterm>
<primary>subquery</primary>
</indexterm>
<para>
This section describes the <acronym>SQL</acronym>-compliant subquery
expressions available in <productname>PostgreSQL</productname>.
All of the expression forms documented in this section return
Boolean (true/false) results.
</para>
<sect2 id="functions-subquery-exists">
<title><literal>EXISTS</literal></title>
<synopsis>
EXISTS (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The argument of <token>EXISTS</token> is an arbitrary <command>SELECT</command> statement,
or <firstterm>subquery</firstterm>. The
subquery is evaluated to determine whether it returns any rows.
If it returns at least one row, the result of <token>EXISTS</token> is
<quote>true</quote>; if the subquery returns no rows, the result of <token>EXISTS</token>
is <quote>false</quote>.
</para>
<para>
The subquery can refer to variables from the surrounding query,
which will act as constants during any one evaluation of the subquery.
</para>
<para>
The subquery will generally only be executed long enough to determine
whether at least one row is returned, not all the way to completion.
It is unwise to write a subquery that has side effects (such as
calling sequence functions); whether the side effects occur
might be unpredictable.
</para>
<para>
Since the result depends only on whether any rows are returned,
and not on the contents of those rows, the output list of the
subquery is normally unimportant. A common coding convention is
to write all <literal>EXISTS</literal> tests in the form
<literal>EXISTS(SELECT 1 WHERE ...)</literal>. There are exceptions to
this rule however, such as subqueries that use <token>INTERSECT</token>.
</para>
<para>
This simple example is like an inner join on <literal>col2</literal>, but
it produces at most one output row for each <literal>tab1</literal> row,
even if there are several matching <literal>tab2</literal> rows:
<screen>
SELECT col1
FROM tab1
WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
</screen>
</para>
</sect2>
<sect2 id="functions-subquery-in">
<title><literal>IN</literal></title>
<synopsis>
<replaceable>expression</replaceable> IN (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result.
The result of <token>IN</token> is <quote>true</quote> if any equal subquery row is found.
The result is <quote>false</quote> if no equal row is found (including the
case where the subquery returns no rows).
</para>
<para>
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand row yields
null, the result of the <token>IN</token> construct will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
<para>
As with <token>EXISTS</token>, it's unwise to assume that the subquery will
be evaluated completely.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> IN (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The left-hand side of this form of <token>IN</token> is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The right-hand side is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand row. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result.
The result of <token>IN</token> is <quote>true</quote> if any equal subquery row is found.
The result is <quote>false</quote> if no equal row is found (including the
case where the subquery returns no rows).
</para>
<para>
As usual, null values in the rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If all the per-row results are either unequal or null, with at least one
null, then the result of <token>IN</token> is null.
</para>
</sect2>
<sect2 id="functions-subquery-notin">
<title><literal>NOT IN</literal></title>
<synopsis>
<replaceable>expression</replaceable> NOT IN (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result.
The result of <token>NOT IN</token> is <quote>true</quote> if only unequal subquery rows
are found (including the case where the subquery returns no rows).
The result is <quote>false</quote> if any equal row is found.
</para>
<para>
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand row yields
null, the result of the <token>NOT IN</token> construct will be null, not true.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
<para>
As with <token>EXISTS</token>, it's unwise to assume that the subquery will
be evaluated completely.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> NOT IN (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The left-hand side of this form of <token>NOT IN</token> is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The right-hand side is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand row. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result.
The result of <token>NOT IN</token> is <quote>true</quote> if only unequal subquery rows
are found (including the case where the subquery returns no rows).
The result is <quote>false</quote> if any equal row is found.
</para>
<para>
As usual, null values in the rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If all the per-row results are either unequal or null, with at least one
null, then the result of <token>NOT IN</token> is null.
</para>
</sect2>
<sect2 id="functions-subquery-any-some">
<title><literal>ANY</literal>/<literal>SOME</literal></title>
<synopsis>
<replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>subquery</replaceable>)
<replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result using the
given <replaceable>operator</replaceable>, which must yield a Boolean
result.
The result of <token>ANY</token> is <quote>true</quote> if any true result is obtained.
The result is <quote>false</quote> if no true result is found (including the
case where the subquery returns no rows).
</para>
<para>
<token>SOME</token> is a synonym for <token>ANY</token>.
<token>IN</token> is equivalent to <literal>= ANY</literal>.
</para>
<para>
Note that if there are no successes and at least one right-hand row yields
null for the operator's result, the result of the <token>ANY</token> construct
will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
</para>
<para>
As with <token>EXISTS</token>, it's unwise to assume that the subquery will
be evaluated completely.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>subquery</replaceable>)
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The left-hand side of this form of <token>ANY</token> is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The right-hand side is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand row. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result,
using the given <replaceable>operator</replaceable>.
The result of <token>ANY</token> is <quote>true</quote> if the comparison
returns true for any subquery row.
The result is <quote>false</quote> if the comparison returns false for every
subquery row (including the case where the subquery returns no
rows).
The result is NULL if no comparison with a subquery row returns true,
and at least one comparison returns NULL.
</para>
<para>
See <xref linkend="row-wise-comparison"/> for details about the meaning
of a row constructor comparison.
</para>
</sect2>
<sect2 id="functions-subquery-all">
<title><literal>ALL</literal></title>
<synopsis>
<replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The right-hand side is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result using the
given <replaceable>operator</replaceable>, which must yield a Boolean
result.
The result of <token>ALL</token> is <quote>true</quote> if all rows yield true
(including the case where the subquery returns no rows).
The result is <quote>false</quote> if any false result is found.
The result is NULL if no comparison with a subquery row returns false,
and at least one comparison returns NULL.
</para>
<para>
<token>NOT IN</token> is equivalent to <literal>&lt;&gt; ALL</literal>.
</para>
<para>
As with <token>EXISTS</token>, it's unwise to assume that the subquery will
be evaluated completely.
</para>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The left-hand side of this form of <token>ALL</token> is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The right-hand side is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand row. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result,
using the given <replaceable>operator</replaceable>.
The result of <token>ALL</token> is <quote>true</quote> if the comparison
returns true for all subquery rows (including the
case where the subquery returns no rows).
The result is <quote>false</quote> if the comparison returns false for any
subquery row.
The result is NULL if no comparison with a subquery row returns false,
and at least one comparison returns NULL.
</para>
<para>
See <xref linkend="row-wise-comparison"/> for details about the meaning
of a row constructor comparison.
</para>
</sect2>
<sect2 id="functions-subquery-single-row-comp">
<title>Single-Row Comparison</title>
<indexterm zone="functions-subquery">
<primary>comparison</primary>
<secondary>subquery result row</secondary>
</indexterm>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> (<replaceable>subquery</replaceable>)
</synopsis>
<para>
The left-hand side is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors"/>.
The right-hand side is a parenthesized subquery, which must return exactly
as many columns as there are expressions in the left-hand row. Furthermore,
the subquery cannot return more than one row. (If it returns zero rows,
the result is taken to be null.) The left-hand side is evaluated and
compared row-wise to the single subquery result row.
</para>
<para>
See <xref linkend="row-wise-comparison"/> for details about the meaning
of a row constructor comparison.
</para>
</sect2>
</sect1>

1046
doc/src/sgml/func/func-textsearch.sgml
View File

File diff suppressed because it is too large Load Diff

135
doc/src/sgml/func/func-trigger.sgml
Unescape View File

@ -0,0 +1,135 @@
<sect1 id="functions-trigger">
<title>Trigger Functions</title>
<para>
While many uses of triggers involve user-written trigger functions,
<productname>PostgreSQL</productname> provides a few built-in trigger
functions that can be used directly in user-defined triggers. These
are summarized in <xref linkend="builtin-triggers-table"/>.
(Additional built-in trigger functions exist, which implement foreign
key constraints and deferred index constraints. Those are not documented
here since users need not use them directly.)
</para>
<para>
For more information about creating triggers, see
<xref linkend="sql-createtrigger"/>.
</para>
<table id="builtin-triggers-table">
<title>Built-In Trigger Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example Usage
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>suppress_redundant_updates_trigger</primary>
</indexterm>
<function>suppress_redundant_updates_trigger</function> ( )
<returnvalue>trigger</returnvalue>
</para>
<para>
Suppresses do-nothing update operations. See below for details.
</para>
<para>
<literal>CREATE TRIGGER ... suppress_redundant_updates_trigger()</literal>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>tsvector_update_trigger</primary>
</indexterm>
<function>tsvector_update_trigger</function> ( )
<returnvalue>trigger</returnvalue>
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
plain-text document column(s). The text search configuration to use
is specified by name as a trigger argument. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
<para>
<literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>tsvector_update_trigger_column</primary>
</indexterm>
<function>tsvector_update_trigger_column</function> ( )
<returnvalue>trigger</returnvalue>
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
plain-text document column(s). The text search configuration to use
is taken from a <type>regconfig</type> column of the table. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
<para>
<literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)</literal>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>suppress_redundant_updates_trigger</function> function,
when applied as a row-level <literal>BEFORE UPDATE</literal> trigger,
will prevent any update that does not actually change the data in the
row from taking place. This overrides the normal behavior which always
performs a physical row update
regardless of whether or not the data has changed. (This normal behavior
makes updates run faster, since no checking is required, and is also
useful in certain cases.)
</para>
<para>
Ideally, you should avoid running updates that don't actually
change the data in the record. Redundant updates can cost considerable
unnecessary time, especially if there are lots of indexes to alter,
and space in dead rows that will eventually have to be vacuumed.
However, detecting such situations in client code is not
always easy, or even possible, and writing expressions to detect
them can be error-prone. An alternative is to use
<function>suppress_redundant_updates_trigger</function>, which will skip
updates that don't change the data. You should use this with care,
however. The trigger takes a small but non-trivial time for each record,
so if most of the records affected by updates do actually change,
use of this trigger will make updates run slower on average.
</para>
<para>
The <function>suppress_redundant_updates_trigger</function> function can be
added to a table like this:
<programlisting>
CREATE TRIGGER z_min_update
BEFORE UPDATE ON tablename
FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
</programlisting>
In most cases, you need to fire this trigger last for each row, so that
it does not override other triggers that might wish to alter the row.
Bearing in mind that triggers fire in name order, you would therefore
choose a trigger name that comes after the name of any other trigger
you might have on the table. (Hence the <quote>z</quote> prefix in the
example.)
</para>
</sect1>

188
doc/src/sgml/func/func-uuid.sgml
Unescape View File

@ -0,0 +1,188 @@
<sect1 id="functions-uuid">
<title>UUID Functions</title>
<indexterm zone="functions-uuid">
<primary>UUID</primary>
<secondary>generating</secondary>
</indexterm>
<indexterm>
<primary>gen_random_uuid</primary>
</indexterm>
<indexterm>
<primary>uuidv4</primary>
</indexterm>
<indexterm>
<primary>uuidv7</primary>
</indexterm>
<indexterm>
<primary>uuid_extract_timestamp</primary>
</indexterm>
<indexterm>
<primary>uuid_extract_version</primary>
</indexterm>
<para>
<xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname>
functions that can be used to generate UUIDs.
</para>
<table id="func_uuid_gen_table">
<title><acronym>UUID</acronym> Generation 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">
<type>gen_random_uuid</type>
<returnvalue>uuid</returnvalue>
</para>
<para role="func_signature">
<type>uuidv4</type>
<returnvalue>uuid</returnvalue>
</para>
<para>
Generate a version 4 (random) UUID.
</para>
<para>
<literal>gen_random_uuid()</literal>
<returnvalue>5b30857f-0bfa-48b5-ac0b-5c64e28078d1</returnvalue>
</para>
<para>
<literal>uuidv4()</literal>
<returnvalue>b42410ee-132f-42ee-9e4f-09a6485c95b8</returnvalue>
</para>
</entry>
</row>
<row>
<entry role="func_table_entry">
<para role="func_signature">
<type>uuidv7</type>
( <optional> <parameter>shift</parameter> <type>interval</type> </optional> )
<returnvalue>uuid</returnvalue>
</para>
<para>
Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp
with millisecond precision + sub-millisecond timestamp + random. The optional parameter
<parameter>shift</parameter> will shift the computed timestamp by the given <type>interval</type>.
</para>
<para>
<literal>uuidv7()</literal>
<returnvalue>019535d9-3df7-79fb-b466-fa907fa17f9e</returnvalue>
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
The <xref linkend="uuid-ossp"/> module provides additional functions that
implement other standard algorithms for generating UUIDs.
</para>
</note>
<para>
<xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname>
functions that can be used to extract information from UUIDs.
</para>
<table id="func_uuid_extract_table">
<title><acronym>UUID</acronym> Extraction 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">
<type>uuid_extract_timestamp</type>
( <type>uuid</type> )
<returnvalue>timestamp with time zone</returnvalue>
</para>
<para>
Extracts a <type>timestamp with time zone</type> from UUID
version 1 and 7. For other versions, this function returns null. Note that
the extracted timestamp is not necessarily exactly equal to the time the
UUID was generated; this depends on the implementation that generated the
UUID.
</para>
<para>
<literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
<returnvalue>2025-02-23 21:46:24.503-05</returnvalue>
</para>
</entry>
</row>
<row>
<entry role="func_table_entry">
<para role="func_signature">
<type>uuid_extract_version</type>
( <type>uuid</type> )
<returnvalue>smallint</returnvalue>
</para>
<para>
Extracts the version from a UUID of the variant described by
<ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For
other variants, this function returns null. For example, for a UUID
generated by <function>gen_random_uuid</function>, this function will
return 4.
</para>
<para>
<literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-&zwsp;885799a4af1d'::uuid)</literal>
<returnvalue>4</returnvalue>
</para>
<para>
<literal>uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
<returnvalue>7</returnvalue>
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<productname>PostgreSQL</productname> also provides the usual comparison
operators shown in <xref linkend="functions-comparison-op-table"/> for
UUIDs.
</para>
<para>
See <xref linkend="datatype-uuid"/> for details on the data type
<type>uuid</type> in <productname>PostgreSQL</productname>.
</para>
</sect1>

284
doc/src/sgml/func/func-window.sgml
Unescape View File

@ -0,0 +1,284 @@
<sect1 id="functions-window">
<title>Window Functions</title>
<indexterm zone="functions-window">
<primary>window function</primary>
<secondary>built-in</secondary>
</indexterm>
<para>
<firstterm>Window functions</firstterm> provide the ability to perform
calculations across sets of rows that are related to the current query
row. See <xref linkend="tutorial-window"/> for an introduction to this
feature, and <xref linkend="syntax-window-functions"/> for syntax
details.
</para>
<para>
The built-in window functions are listed in
<xref linkend="functions-window-table"/>. Note that these functions
<emphasis>must</emphasis> be invoked using window function syntax, i.e., an
<literal>OVER</literal> clause is required.
</para>
<para>
In addition to these functions, any built-in or user-defined
ordinary aggregate (i.e., not ordered-set or hypothetical-set aggregates)
can be used as a window function; see
<xref linkend="functions-aggregate"/> for a list of the built-in aggregates.
Aggregate functions act as window functions only when an <literal>OVER</literal>
clause follows the call; otherwise they act as plain aggregates
and return a single row for the entire set.
</para>
<table id="functions-window-table">
<title>General-Purpose Window 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">
<indexterm>
<primary>row_number</primary>
</indexterm>
<function>row_number</function> ()
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the number of the current row within its partition, counting
from 1.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>rank</primary>
</indexterm>
<function>rank</function> ()
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the rank of the current row, with gaps; that is,
the <function>row_number</function> of the first row in its peer
group.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>dense_rank</primary>
</indexterm>
<function>dense_rank</function> ()
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the rank of the current row, without gaps; this function
effectively counts peer groups.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>percent_rank</primary>
</indexterm>
<function>percent_rank</function> ()
<returnvalue>double precision</returnvalue>
</para>
<para>
Returns the relative rank of the current row, that is
(<function>rank</function> - 1) / (total partition rows - 1).
The value thus ranges from 0 to 1 inclusive.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cume_dist</primary>
</indexterm>
<function>cume_dist</function> ()
<returnvalue>double precision</returnvalue>
</para>
<para>
Returns the cumulative distribution, that is (number of partition rows
preceding or peers with current row) / (total partition rows).
The value thus ranges from 1/<parameter>N</parameter> to 1.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ntile</primary>
</indexterm>
<function>ntile</function> ( <parameter>num_buckets</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns an integer ranging from 1 to the argument value, dividing the
partition as equally as possible.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lag</primary>
</indexterm>
<function>lag</function> ( <parameter>value</parameter> <type>anycompatible</type>
<optional>, <parameter>offset</parameter> <type>integer</type>
<optional>, <parameter>default</parameter> <type>anycompatible</type> </optional></optional> )
<returnvalue>anycompatible</returnvalue>
</para>
<para>
Returns <parameter>value</parameter> evaluated at
the row that is <parameter>offset</parameter>
rows before the current row within the partition; if there is no such
row, instead returns <parameter>default</parameter>
(which must be of a type compatible with
<parameter>value</parameter>).
Both <parameter>offset</parameter> and
<parameter>default</parameter> are evaluated
with respect to the current row. If omitted,
<parameter>offset</parameter> defaults to 1 and
<parameter>default</parameter> to <literal>NULL</literal>.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lead</primary>
</indexterm>
<function>lead</function> ( <parameter>value</parameter> <type>anycompatible</type>
<optional>, <parameter>offset</parameter> <type>integer</type>
<optional>, <parameter>default</parameter> <type>anycompatible</type> </optional></optional> )
<returnvalue>anycompatible</returnvalue>
</para>
<para>
Returns <parameter>value</parameter> evaluated at
the row that is <parameter>offset</parameter>
rows after the current row within the partition; if there is no such
row, instead returns <parameter>default</parameter>
(which must be of a type compatible with
<parameter>value</parameter>).
Both <parameter>offset</parameter> and
<parameter>default</parameter> are evaluated
with respect to the current row. If omitted,
<parameter>offset</parameter> defaults to 1 and
<parameter>default</parameter> to <literal>NULL</literal>.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>first_value</primary>
</indexterm>
<function>first_value</function> ( <parameter>value</parameter> <type>anyelement</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Returns <parameter>value</parameter> evaluated
at the row that is the first row of the window frame.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>last_value</primary>
</indexterm>
<function>last_value</function> ( <parameter>value</parameter> <type>anyelement</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Returns <parameter>value</parameter> evaluated
at the row that is the last row of the window frame.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>nth_value</primary>
</indexterm>
<function>nth_value</function> ( <parameter>value</parameter> <type>anyelement</type>, <parameter>n</parameter> <type>integer</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Returns <parameter>value</parameter> evaluated
at the row that is the <parameter>n</parameter>'th
row of the window frame (counting from 1);
returns <literal>NULL</literal> if there is no such row.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
All of the functions listed in
<xref linkend="functions-window-table"/> depend on the sort ordering
specified by the <literal>ORDER BY</literal> clause of the associated window
definition. Rows that are not distinct when considering only the
<literal>ORDER BY</literal> columns are said to be <firstterm>peers</firstterm>.
The four ranking functions (including <function>cume_dist</function>) are
defined so that they give the same answer for all rows of a peer group.
</para>
<para>
Note that <function>first_value</function>, <function>last_value</function>, and
<function>nth_value</function> consider only the rows within the <quote>window
frame</quote>, which by default contains the rows from the start of the
partition through the last peer of the current row. This is
likely to give unhelpful results for <function>last_value</function> and
sometimes also <function>nth_value</function>. You can redefine the frame by
adding a suitable frame specification (<literal>RANGE</literal>,
<literal>ROWS</literal> or <literal>GROUPS</literal>) to
the <literal>OVER</literal> clause.
See <xref linkend="syntax-window-functions"/> for more information
about frame specifications.
</para>
<para>
When an aggregate function is used as a window function, it aggregates
over the rows within the current row's window frame.
An aggregate used with <literal>ORDER BY</literal> and the default window frame
definition produces a <quote>running sum</quote> type of behavior, which may or
may not be what's wanted. To obtain
aggregation over the whole partition, omit <literal>ORDER BY</literal> or use
<literal>ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</literal>.
Other frame specifications can be used to obtain other effects.
</para>
<note>
<para>
The SQL standard defines a <literal>RESPECT NULLS</literal> or
<literal>IGNORE NULLS</literal> option for <function>lead</function>, <function>lag</function>,
<function>first_value</function>, <function>last_value</function>, and
<function>nth_value</function>. This is not implemented in
<productname>PostgreSQL</productname>: the behavior is always the
same as the standard's default, namely <literal>RESPECT NULLS</literal>.
Likewise, the standard's <literal>FROM FIRST</literal> or <literal>FROM LAST</literal>
option for <function>nth_value</function> is not implemented: only the
default <literal>FROM FIRST</literal> behavior is supported. (You can achieve
the result of <literal>FROM LAST</literal> by reversing the <literal>ORDER BY</literal>
ordering.)
</para>
</note>
</sect1>

1283
doc/src/sgml/func/func-xml.sgml
View File

File diff suppressed because it is too large Load Diff

84
doc/src/sgml/func/func.sgml
Unescape View File

@ -0,0 +1,84 @@
<!-- doc/src/sgml/func.sgml -->
<chapter id="functions">
<title>Functions and Operators</title>
<indexterm zone="functions">
<primary>function</primary>
</indexterm>
<indexterm zone="functions">
<primary>operator</primary>
</indexterm>
<para>
<productname>PostgreSQL</productname> provides a large number of
functions and operators for the built-in data types. This chapter
describes most of them, although additional special-purpose functions
appear in relevant sections of the manual. Users can also
define their own functions and operators, as described in
<xref linkend="server-programming"/>. The
<application>psql</application> commands <command>\df</command> and
<command>\do</command> can be used to list all
available functions and operators, respectively.
</para>
<para>
The notation used throughout this chapter to describe the argument and
result data types of a function or operator is like this:
<synopsis>
<function>repeat</function> ( <type>text</type>, <type>integer</type> ) <returnvalue>text</returnvalue>
</synopsis>
which says that the function <function>repeat</function> takes one text and
one integer argument and returns a result of type text. The right arrow
is also used to indicate the result of an example, thus:
<programlisting>
repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</programlisting>
</para>
<para>
If you are concerned about portability then note that most of
the functions and operators described in this chapter, with the
exception of the most trivial arithmetic and comparison operators
and some explicitly marked functions, are not specified by the
<acronym>SQL</acronym> standard. Some of this extended functionality
is present in other <acronym>SQL</acronym> database management
systems, and in many cases this functionality is compatible and
consistent between the various implementations.
</para>
&func-logical;
&func-comparison;
&func-math;
&func-string;
&func-binarystring;
&func-bitstring;
&func-matching;
&func-formatting;
&func-datetime;
&func-enum;
&func-geometry;
&func-net;
&func-textsearch;
&func-uuid;
&func-xml;
&func-json;
&func-sequence;
&func-conditional;
&func-array;
&func-range;
&func-aggregate;
&func-window;
&func-merge-support;
&func-subquery;
&func-comparisons;
&func-srf;
&func-info;
&func-admin;
&func-trigger;
&func-event-triggers;
&func-statistics;
</chapter>
Write Preview
Loading…
Cancel
Save