1 <!-- doc/src/sgml/func.sgml -->
3 <chapter id="functions">
4 <title>Functions and Operators</title>
6 <indexterm zone="functions">
7 <primary>function</primary>
10 <indexterm zone="functions">
11 <primary>operator</primary>
15 <productname>PostgreSQL</productname> provides a large number of
16 functions and operators for the built-in data types. Users can also
17 define their own functions and operators, as described in
18 <xref linkend="server-programming">. The
19 <application>psql</application> commands <command>\df</command> and
20 <command>\do</command> can be used to list all
21 available functions and operators, respectively.
25 If you are concerned about portability then note that most of
26 the functions and operators described in this chapter, with the
27 exception of the most trivial arithmetic and comparison operators
28 and some explicitly marked functions, are not specified by the
29 <acronym>SQL</acronym> standard. Some of this extended functionality
30 is present in other <acronym>SQL</acronym> database management
31 systems, and in many cases this functionality is compatible and
32 consistent between the various implementations. This chapter is also
33 not exhaustive; additional functions appear in relevant sections of
38 <sect1 id="functions-logical">
39 <title>Logical Operators</title>
41 <indexterm zone="functions-logical">
42 <primary>operator</primary>
43 <secondary>logical</secondary>
47 <primary>Boolean</primary>
48 <secondary>operators</secondary>
49 <see>operators, logical</see>
53 The usual logical operators are available:
56 <primary>AND (operator)</primary>
60 <primary>OR (operator)</primary>
64 <primary>NOT (operator)</primary>
68 <primary>conjunction</primary>
72 <primary>disjunction</primary>
76 <primary>negation</primary>
80 <member><literal>AND</></member>
81 <member><literal>OR</></member>
82 <member><literal>NOT</></member>
85 <acronym>SQL</acronym> uses a three-valued logic system with true,
86 false, and <literal>null</>, which represents <quote>unknown</quote>.
87 Observe the following truth tables:
93 <entry><replaceable>a</replaceable></entry>
94 <entry><replaceable>b</replaceable></entry>
95 <entry><replaceable>a</replaceable> AND <replaceable>b</replaceable></entry>
96 <entry><replaceable>a</replaceable> OR <replaceable>b</replaceable></entry>
150 <entry><replaceable>a</replaceable></entry>
151 <entry>NOT <replaceable>a</replaceable></entry>
176 The operators <literal>AND</literal> and <literal>OR</literal> are
177 commutative, that is, you can switch the left and right operand
178 without affecting the result. But see <xref
179 linkend="syntax-express-eval"> for more information about the
180 order of evaluation of subexpressions.
184 <sect1 id="functions-comparison">
185 <title>Comparison Operators</title>
187 <indexterm zone="functions-comparison">
188 <primary>comparison</primary>
189 <secondary>operators</secondary>
193 The usual comparison operators are available, shown in <xref
194 linkend="functions-comparison-table">.
197 <table id="functions-comparison-table">
198 <title>Comparison Operators</title>
202 <entry>Operator</entry>
203 <entry>Description</entry>
209 <entry> <literal><</literal> </entry>
210 <entry>less than</entry>
214 <entry> <literal>></literal> </entry>
215 <entry>greater than</entry>
219 <entry> <literal><=</literal> </entry>
220 <entry>less than or equal to</entry>
224 <entry> <literal>>=</literal> </entry>
225 <entry>greater than or equal to</entry>
229 <entry> <literal>=</literal> </entry>
234 <entry> <literal><></literal> or <literal>!=</literal> </entry>
235 <entry>not equal</entry>
243 The <literal>!=</literal> operator is converted to
244 <literal><></literal> in the parser stage. It is not
245 possible to implement <literal>!=</literal> and
246 <literal><></literal> operators that do different things.
251 Comparison operators are available for all relevant data types.
252 All comparison operators are binary operators that
253 return values of type <type>boolean</type>; expressions like
254 <literal>1 < 2 < 3</literal> are not valid (because there is
255 no <literal><</literal> operator to compare a Boolean value with
256 <literal>3</literal>).
261 <primary>BETWEEN</primary>
263 In addition to the comparison operators, the special
264 <token>BETWEEN</token> construct is available:
266 <replaceable>a</replaceable> BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
270 <replaceable>a</replaceable> >= <replaceable>x</replaceable> AND <replaceable>a</replaceable> <= <replaceable>y</replaceable>
272 Notice that <token>BETWEEN</token> treats the endpoint values as included
274 <literal>NOT BETWEEN</literal> does the opposite comparison:
276 <replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
280 <replaceable>a</replaceable> < <replaceable>x</replaceable> OR <replaceable>a</replaceable> > <replaceable>y</replaceable>
283 <primary>BETWEEN SYMMETRIC</primary>
285 <literal>BETWEEN SYMMETRIC</> is the same as <literal>BETWEEN</>
286 except there is no requirement that the argument to the left of
287 <literal>AND</> be less than or equal to the argument on the right.
288 If it is not, those two arguments are automatically swapped, so that
289 a nonempty range is always implied.
294 <primary>IS NULL</primary>
297 <primary>IS NOT NULL</primary>
300 <primary>ISNULL</primary>
303 <primary>NOTNULL</primary>
305 To check whether a value is or is not null, use the constructs:
307 <replaceable>expression</replaceable> IS NULL
308 <replaceable>expression</replaceable> IS NOT NULL
310 or the equivalent, but nonstandard, constructs:
312 <replaceable>expression</replaceable> ISNULL
313 <replaceable>expression</replaceable> NOTNULL
315 <indexterm><primary>null value</primary><secondary>comparing</secondary></indexterm>
319 Do <emphasis>not</emphasis> write
320 <literal><replaceable>expression</replaceable> = NULL</literal>
321 because <literal>NULL</> is not <quote>equal to</quote>
322 <literal>NULL</>. (The null value represents an unknown value,
323 and it is not known whether two unknown values are equal.) This
324 behavior conforms to the SQL standard.
329 Some applications might expect that
330 <literal><replaceable>expression</replaceable> = NULL</literal>
331 returns true if <replaceable>expression</replaceable> evaluates to
332 the null value. It is highly recommended that these applications
333 be modified to comply with the SQL standard. However, if that
334 cannot be done the <xref linkend="guc-transform-null-equals">
335 configuration variable is available. If it is enabled,
336 <productname>PostgreSQL</productname> will convert <literal>x =
337 NULL</literal> clauses to <literal>x IS NULL</literal>.
343 If the <replaceable>expression</replaceable> is row-valued, then
344 <literal>IS NULL</> is true when the row expression itself is null
345 or when all the row's fields are null, while
346 <literal>IS NOT NULL</> is true when the row expression itself is non-null
347 and all the row's fields are non-null. Because of this behavior,
348 <literal>IS NULL</> and <literal>IS NOT NULL</> do not always return
349 inverse results for row-valued expressions, i.e., a row-valued
350 expression that contains both NULL and non-null values will return false
352 This definition conforms to the SQL standard, and is a change from the
353 inconsistent behavior exhibited by <productname>PostgreSQL</productname>
354 versions prior to 8.2.
360 <primary>IS DISTINCT FROM</primary>
363 <primary>IS NOT DISTINCT FROM</primary>
365 Ordinary comparison operators yield null (signifying <quote>unknown</>),
366 not true or false, when either input is null. For example,
367 <literal>7 = NULL</> yields null. When this behavior is not suitable,
369 <literal>IS <optional> NOT </> DISTINCT FROM</literal> constructs:
371 <replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
372 <replaceable>expression</replaceable> IS NOT DISTINCT FROM <replaceable>expression</replaceable>
374 For non-null inputs, <literal>IS DISTINCT FROM</literal> is
375 the same as the <literal><></> operator. However, if both
376 inputs are null it returns false, and if only one input is
377 null it returns true. Similarly, <literal>IS NOT DISTINCT
378 FROM</literal> is identical to <literal>=</literal> for non-null
379 inputs, but it returns true when both inputs are null, and false when only
380 one input is null. Thus, these constructs effectively act as though null
381 were a normal data value, rather than <quote>unknown</>.
386 <primary>IS TRUE</primary>
389 <primary>IS NOT TRUE</primary>
392 <primary>IS FALSE</primary>
395 <primary>IS NOT FALSE</primary>
398 <primary>IS UNKNOWN</primary>
401 <primary>IS NOT UNKNOWN</primary>
403 Boolean values can also be tested using the constructs
405 <replaceable>expression</replaceable> IS TRUE
406 <replaceable>expression</replaceable> IS NOT TRUE
407 <replaceable>expression</replaceable> IS FALSE
408 <replaceable>expression</replaceable> IS NOT FALSE
409 <replaceable>expression</replaceable> IS UNKNOWN
410 <replaceable>expression</replaceable> IS NOT UNKNOWN
412 These will always return true or false, never a null value, even when the
414 A null input is treated as the logical value <quote>unknown</>.
415 Notice that <literal>IS UNKNOWN</> and <literal>IS NOT UNKNOWN</> are
416 effectively the same as <literal>IS NULL</literal> and
417 <literal>IS NOT NULL</literal>, respectively, except that the input
418 expression must be of Boolean type.
421 <!-- IS OF does not conform to the ISO SQL behavior, so it is undocumented here
424 <primary>IS OF</primary>
427 <primary>IS NOT OF</primary>
429 It is possible to check the data type of an expression using the
432 <replaceable>expression</replaceable> IS OF (typename, ...)
433 <replaceable>expression</replaceable> IS NOT OF (typename, ...)
435 They return a boolean value based on whether the expression's data
436 type is one of the listed data types.
442 <sect1 id="functions-math">
443 <title>Mathematical Functions and Operators</title>
446 Mathematical operators are provided for many
447 <productname>PostgreSQL</productname> types. For types without
448 standard mathematical conventions
449 (e.g., date/time types) we
450 describe the actual behavior in subsequent sections.
454 <xref linkend="functions-math-op-table"> shows the available mathematical operators.
457 <table id="functions-math-op-table">
458 <title>Mathematical Operators</title>
463 <entry>Operator</entry>
464 <entry>Description</entry>
465 <entry>Example</entry>
466 <entry>Result</entry>
472 <entry> <literal>+</literal> </entry>
473 <entry>addition</entry>
474 <entry><literal>2 + 3</literal></entry>
475 <entry><literal>5</literal></entry>
479 <entry> <literal>-</literal> </entry>
480 <entry>subtraction</entry>
481 <entry><literal>2 - 3</literal></entry>
482 <entry><literal>-1</literal></entry>
486 <entry> <literal>*</literal> </entry>
487 <entry>multiplication</entry>
488 <entry><literal>2 * 3</literal></entry>
489 <entry><literal>6</literal></entry>
493 <entry> <literal>/</literal> </entry>
494 <entry>division (integer division truncates the result)</entry>
495 <entry><literal>4 / 2</literal></entry>
496 <entry><literal>2</literal></entry>
500 <entry> <literal>%</literal> </entry>
501 <entry>modulo (remainder)</entry>
502 <entry><literal>5 % 4</literal></entry>
503 <entry><literal>1</literal></entry>
507 <entry> <literal>^</literal> </entry>
508 <entry>exponentiation</entry>
509 <entry><literal>2.0 ^ 3.0</literal></entry>
510 <entry><literal>8</literal></entry>
514 <entry> <literal>|/</literal> </entry>
515 <entry>square root</entry>
516 <entry><literal>|/ 25.0</literal></entry>
517 <entry><literal>5</literal></entry>
521 <entry> <literal>||/</literal> </entry>
522 <entry>cube root</entry>
523 <entry><literal>||/ 27.0</literal></entry>
524 <entry><literal>3</literal></entry>
528 <entry> <literal>!</literal> </entry>
529 <entry>factorial</entry>
530 <entry><literal>5 !</literal></entry>
531 <entry><literal>120</literal></entry>
535 <entry> <literal>!!</literal> </entry>
536 <entry>factorial (prefix operator)</entry>
537 <entry><literal>!! 5</literal></entry>
538 <entry><literal>120</literal></entry>
542 <entry> <literal>@</literal> </entry>
543 <entry>absolute value</entry>
544 <entry><literal>@ -5.0</literal></entry>
545 <entry><literal>5</literal></entry>
549 <entry> <literal>&</literal> </entry>
550 <entry>bitwise AND</entry>
551 <entry><literal>91 & 15</literal></entry>
552 <entry><literal>11</literal></entry>
556 <entry> <literal>|</literal> </entry>
557 <entry>bitwise OR</entry>
558 <entry><literal>32 | 3</literal></entry>
559 <entry><literal>35</literal></entry>
563 <entry> <literal>#</literal> </entry>
564 <entry>bitwise XOR</entry>
565 <entry><literal>17 # 5</literal></entry>
566 <entry><literal>20</literal></entry>
570 <entry> <literal>~</literal> </entry>
571 <entry>bitwise NOT</entry>
572 <entry><literal>~1</literal></entry>
573 <entry><literal>-2</literal></entry>
577 <entry> <literal><<</literal> </entry>
578 <entry>bitwise shift left</entry>
579 <entry><literal>1 << 4</literal></entry>
580 <entry><literal>16</literal></entry>
584 <entry> <literal>>></literal> </entry>
585 <entry>bitwise shift right</entry>
586 <entry><literal>8 >> 2</literal></entry>
587 <entry><literal>2</literal></entry>
595 The bitwise operators work only on integral data types, whereas
596 the others are available for all numeric data types. The bitwise
597 operators are also available for the bit
598 string types <type>bit</type> and <type>bit varying</type>, as
599 shown in <xref linkend="functions-bit-string-op-table">.
603 <xref linkend="functions-math-func-table"> shows the available
604 mathematical functions. In the table, <literal>dp</literal>
605 indicates <type>double precision</type>. Many of these functions
606 are provided in multiple forms with different argument types.
607 Except where noted, any given form of a function returns the same
608 data type as its argument.
609 The functions working with <type>double precision</type> data are mostly
610 implemented on top of the host system's C library; accuracy and behavior in
611 boundary cases can therefore vary depending on the host system.
614 <table id="functions-math-func-table">
615 <title>Mathematical Functions</title>
619 <entry>Function</entry>
620 <entry>Return Type</entry>
621 <entry>Description</entry>
622 <entry>Example</entry>
623 <entry>Result</entry>
631 <primary>abs</primary>
633 <literal><function>abs(<replaceable>x</replaceable>)</function></literal>
635 <entry>(same as input)</entry>
636 <entry>absolute value</entry>
637 <entry><literal>abs(-17.4)</literal></entry>
638 <entry><literal>17.4</literal></entry>
644 <primary>cbrt</primary>
646 <literal><function>cbrt(<type>dp</type>)</function></literal>
648 <entry><type>dp</type></entry>
649 <entry>cube root</entry>
650 <entry><literal>cbrt(27.0)</literal></entry>
651 <entry><literal>3</literal></entry>
657 <primary>ceil</primary>
659 <literal><function>ceil(<type>dp</type> or <type>numeric</type>)</function></literal>
661 <entry>(same as input)</entry>
662 <entry>smallest integer not less than argument</entry>
663 <entry><literal>ceil(-42.8)</literal></entry>
664 <entry><literal>-42</literal></entry>
670 <primary>ceiling</primary>
672 <literal><function>ceiling(<type>dp</type> or <type>numeric</type>)</function></literal>
674 <entry>(same as input)</entry>
675 <entry>smallest integer not less than argument (alias for <function>ceil</function>)</entry>
676 <entry><literal>ceiling(-95.3)</literal></entry>
677 <entry><literal>-95</literal></entry>
683 <primary>degrees</primary>
685 <literal><function>degrees(<type>dp</type>)</function></literal>
687 <entry><type>dp</type></entry>
688 <entry>radians to degrees</entry>
689 <entry><literal>degrees(0.5)</literal></entry>
690 <entry><literal>28.6478897565412</literal></entry>
696 <primary>div</primary>
698 <literal><function>div(<parameter>y</parameter> <type>numeric</>,
699 <parameter>x</parameter> <type>numeric</>)</function></literal>
701 <entry><type>numeric</></entry>
702 <entry>integer quotient of <parameter>y</parameter>/<parameter>x</parameter></entry>
703 <entry><literal>div(9,4)</literal></entry>
704 <entry><literal>2</literal></entry>
710 <primary>exp</primary>
712 <literal><function>exp(<type>dp</type> or <type>numeric</type>)</function></literal>
714 <entry>(same as input)</entry>
715 <entry>exponential</entry>
716 <entry><literal>exp(1.0)</literal></entry>
717 <entry><literal>2.71828182845905</literal></entry>
723 <primary>floor</primary>
725 <literal><function>floor(<type>dp</type> or <type>numeric</type>)</function></literal>
727 <entry>(same as input)</entry>
728 <entry>largest integer not greater than argument</entry>
729 <entry><literal>floor(-42.8)</literal></entry>
730 <entry><literal>-43</literal></entry>
736 <primary>ln</primary>
738 <literal><function>ln(<type>dp</type> or <type>numeric</type>)</function></literal>
740 <entry>(same as input)</entry>
741 <entry>natural logarithm</entry>
742 <entry><literal>ln(2.0)</literal></entry>
743 <entry><literal>0.693147180559945</literal></entry>
749 <primary>log</primary>
751 <literal><function>log(<type>dp</type> or <type>numeric</type>)</function></literal>
753 <entry>(same as input)</entry>
754 <entry>base 10 logarithm</entry>
755 <entry><literal>log(100.0)</literal></entry>
756 <entry><literal>2</literal></entry>
760 <entry><literal><function>log(<parameter>b</parameter> <type>numeric</type>,
761 <parameter>x</parameter> <type>numeric</type>)</function></literal></entry>
762 <entry><type>numeric</type></entry>
763 <entry>logarithm to base <parameter>b</parameter></entry>
764 <entry><literal>log(2.0, 64.0)</literal></entry>
765 <entry><literal>6.0000000000</literal></entry>
771 <primary>mod</primary>
773 <literal><function>mod(<parameter>y</parameter>,
774 <parameter>x</parameter>)</function></literal>
776 <entry>(same as argument types)</entry>
777 <entry>remainder of <parameter>y</parameter>/<parameter>x</parameter></entry>
778 <entry><literal>mod(9,4)</literal></entry>
779 <entry><literal>1</literal></entry>
785 <primary>pi</primary>
787 <literal><function>pi()</function></literal>
789 <entry><type>dp</type></entry>
790 <entry><quote>π</quote> constant</entry>
791 <entry><literal>pi()</literal></entry>
792 <entry><literal>3.14159265358979</literal></entry>
798 <primary>power</primary>
800 <literal><function>power(<parameter>a</parameter> <type>dp</type>,
801 <parameter>b</parameter> <type>dp</type>)</function></literal>
803 <entry><type>dp</type></entry>
804 <entry><parameter>a</> raised to the power of <parameter>b</parameter></entry>
805 <entry><literal>power(9.0, 3.0)</literal></entry>
806 <entry><literal>729</literal></entry>
810 <entry><literal><function>power(<parameter>a</parameter> <type>numeric</type>,
811 <parameter>b</parameter> <type>numeric</type>)</function></literal></entry>
812 <entry><type>numeric</type></entry>
813 <entry><parameter>a</> raised to the power of <parameter>b</parameter></entry>
814 <entry><literal>power(9.0, 3.0)</literal></entry>
815 <entry><literal>729</literal></entry>
821 <primary>radians</primary>
823 <literal><function>radians(<type>dp</type>)</function></literal>
825 <entry><type>dp</type></entry>
826 <entry>degrees to radians</entry>
827 <entry><literal>radians(45.0)</literal></entry>
828 <entry><literal>0.785398163397448</literal></entry>
834 <primary>random</primary>
836 <literal><function>random()</function></literal>
838 <entry><type>dp</type></entry>
839 <entry>random value in the range 0.0 <= x < 1.0</entry>
840 <entry><literal>random()</literal></entry>
847 <primary>round</primary>
849 <literal><function>round(<type>dp</type> or <type>numeric</type>)</function></literal>
851 <entry>(same as input)</entry>
852 <entry>round to nearest integer</entry>
853 <entry><literal>round(42.4)</literal></entry>
854 <entry><literal>42</literal></entry>
858 <entry><literal><function>round(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</function></literal></entry>
859 <entry><type>numeric</type></entry>
860 <entry>round to <parameter>s</parameter> decimal places</entry>
861 <entry><literal>round(42.4382, 2)</literal></entry>
862 <entry><literal>42.44</literal></entry>
868 <primary>setseed</primary>
870 <literal><function>setseed(<type>dp</type>)</function></literal>
872 <entry><type>void</type></entry>
873 <entry>set seed for subsequent <literal>random()</literal> calls (value between -1.0 and
874 1.0, inclusive)</entry>
875 <entry><literal>setseed(0.54823)</literal></entry>
882 <primary>sign</primary>
884 <literal><function>sign(<type>dp</type> or <type>numeric</type>)</function></literal>
886 <entry>(same as input)</entry>
887 <entry>sign of the argument (-1, 0, +1)</entry>
888 <entry><literal>sign(-8.4)</literal></entry>
889 <entry><literal>-1</literal></entry>
895 <primary>sqrt</primary>
897 <literal><function>sqrt(<type>dp</type> or <type>numeric</type>)</function></literal>
899 <entry>(same as input)</entry>
900 <entry>square root</entry>
901 <entry><literal>sqrt(2.0)</literal></entry>
902 <entry><literal>1.4142135623731</literal></entry>
908 <primary>trunc</primary>
910 <literal><function>trunc(<type>dp</type> or <type>numeric</type>)</function></literal>
912 <entry>(same as input)</entry>
913 <entry>truncate toward zero</entry>
914 <entry><literal>trunc(42.8)</literal></entry>
915 <entry><literal>42</literal></entry>
919 <entry><literal><function>trunc(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</function></literal></entry>
920 <entry><type>numeric</type></entry>
921 <entry>truncate to <parameter>s</parameter> decimal places</entry>
922 <entry><literal>trunc(42.4382, 2)</literal></entry>
923 <entry><literal>42.43</literal></entry>
929 <primary>width_bucket</primary>
931 <literal><function>width_bucket(<parameter>op</parameter> <type>numeric</type>, <parameter>b1</parameter> <type>numeric</type>, <parameter>b2</parameter> <type>numeric</type>, <parameter>count</parameter> <type>int</type>)</function></literal>
933 <entry><type>int</type></entry>
934 <entry>return the bucket to which <parameter>operand</> would
935 be assigned in an equidepth histogram with <parameter>count</>
936 buckets, in the range <parameter>b1</> to <parameter>b2</></entry>
937 <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
938 <entry><literal>3</literal></entry>
942 <entry><literal><function>width_bucket(<parameter>op</parameter> <type>dp</type>, <parameter>b1</parameter> <type>dp</type>, <parameter>b2</parameter> <type>dp</type>, <parameter>count</parameter> <type>int</type>)</function></literal></entry>
943 <entry><type>int</type></entry>
944 <entry>return the bucket to which <parameter>operand</> would
945 be assigned in an equidepth histogram with <parameter>count</>
946 buckets, in the range <parameter>b1</> to <parameter>b2</></entry>
947 <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
948 <entry><literal>3</literal></entry>
955 Finally, <xref linkend="functions-math-trig-table"> shows the
956 available trigonometric functions. All trigonometric functions
957 take arguments and return values of type <type>double
958 precision</type>. Trigonometric functions arguments are expressed
959 in radians. Inverse functions return values are expressed in
960 radians. See unit transformation functions
961 <literal><function>radians()</function></literal> and
962 <literal><function>degrees()</function></literal> above.
965 <table id="functions-math-trig-table">
966 <title>Trigonometric Functions</title>
971 <entry>Function</entry>
972 <entry>Description</entry>
980 <primary>acos</primary>
981 </indexterm><literal><function>acos(<replaceable>x</replaceable>)</function></literal>
983 <entry>inverse cosine</entry>
989 <primary>asin</primary>
991 <literal><function>asin(<replaceable>x</replaceable>)</function></literal>
993 <entry>inverse sine</entry>
999 <primary>atan</primary>
1001 <literal><function>atan(<replaceable>x</replaceable>)</function></literal>
1003 <entry>inverse tangent</entry>
1009 <primary>atan2</primary>
1011 <literal><function>atan2(<replaceable>y</replaceable>,
1012 <replaceable>x</replaceable>)</function></literal>
1014 <entry>inverse tangent of
1015 <literal><replaceable>y</replaceable>/<replaceable>x</replaceable></literal></entry>
1021 <primary>cos</primary>
1023 <literal><function>cos(<replaceable>x</replaceable>)</function></literal>
1025 <entry>cosine</entry>
1031 <primary>cot</primary>
1033 <literal><function>cot(<replaceable>x</replaceable>)</function></literal>
1035 <entry>cotangent</entry>
1041 <primary>sin</primary>
1043 <literal><function>sin(<replaceable>x</replaceable>)</function></literal>
1051 <primary>tan</primary>
1053 <literal><function>tan(<replaceable>x</replaceable>)</function></literal>
1055 <entry>tangent</entry>
1064 <sect1 id="functions-string">
1065 <title>String Functions and Operators</title>
1068 This section describes functions and operators for examining and
1069 manipulating string values. Strings in this context include values
1070 of the types <type>character</type>, <type>character varying</type>,
1071 and <type>text</type>. Unless otherwise noted, all
1072 of the functions listed below work on all of these types, but be
1073 wary of potential effects of automatic space-padding when using the
1074 <type>character</type> type. Some functions also exist
1075 natively for the bit-string types.
1079 <acronym>SQL</acronym> defines some string functions that use
1080 key words, rather than commas, to separate
1081 arguments. Details are in
1082 <xref linkend="functions-string-sql">.
1083 <productname>PostgreSQL</> also provides versions of these functions
1084 that use the regular function invocation syntax
1085 (see <xref linkend="functions-string-other">).
1090 Before <productname>PostgreSQL</productname> 8.3, these functions would
1091 silently accept values of several non-string data types as well, due to
1092 the presence of implicit coercions from those data types to
1093 <type>text</>. Those coercions have been removed because they frequently
1094 caused surprising behaviors. However, the string concatenation operator
1095 (<literal>||</>) still accepts non-string input, so long as at least one
1096 input is of a string type, as shown in <xref
1097 linkend="functions-string-sql">. For other cases, insert an explicit
1098 coercion to <type>text</> if you need to duplicate the previous behavior.
1102 <table id="functions-string-sql">
1103 <title><acronym>SQL</acronym> String Functions and Operators</title>
1107 <entry>Function</entry>
1108 <entry>Return Type</entry>
1109 <entry>Description</entry>
1110 <entry>Example</entry>
1111 <entry>Result</entry>
1117 <entry><literal><parameter>string</parameter> <literal>||</literal>
1118 <parameter>string</parameter></literal></entry>
1119 <entry> <type>text</type> </entry>
1121 String concatenation
1123 <primary>character string</primary>
1124 <secondary>concatenation</secondary>
1127 <entry><literal>'Post' || 'greSQL'</literal></entry>
1128 <entry><literal>PostgreSQL</literal></entry>
1133 <literal><parameter>string</parameter> <literal>||</literal>
1134 <parameter>non-string</parameter></literal>
1136 <literal><parameter>non-string</parameter> <literal>||</literal>
1137 <parameter>string</parameter></literal>
1139 <entry> <type>text</type> </entry>
1141 String concatenation with one non-string input
1143 <entry><literal>'Value: ' || 42</literal></entry>
1144 <entry><literal>Value: 42</literal></entry>
1150 <primary>bit_length</primary>
1152 <literal><function>bit_length(<parameter>string</parameter>)</function></literal>
1154 <entry><type>int</type></entry>
1155 <entry>Number of bits in string</entry>
1156 <entry><literal>bit_length('jose')</literal></entry>
1157 <entry><literal>32</literal></entry>
1163 <primary>char_length</primary>
1165 <literal><function>char_length(<parameter>string</parameter>)</function></literal> or <literal><function>character_length(<parameter>string</parameter>)</function></literal>
1167 <entry><type>int</type></entry>
1169 Number of characters in string
1171 <primary>character string</primary>
1172 <secondary>length</secondary>
1175 <primary>length</primary>
1176 <secondary sortas="character string">of a character string</secondary>
1177 <see>character string, length</see>
1180 <entry><literal>char_length('jose')</literal></entry>
1181 <entry><literal>4</literal></entry>
1187 <primary>lower</primary>
1189 <literal><function>lower(<parameter>string</parameter>)</function></literal>
1191 <entry><type>text</type></entry>
1192 <entry>Convert string to lower case</entry>
1193 <entry><literal>lower('TOM')</literal></entry>
1194 <entry><literal>tom</literal></entry>
1200 <primary>octet_length</primary>
1202 <literal><function>octet_length(<parameter>string</parameter>)</function></literal>
1204 <entry><type>int</type></entry>
1205 <entry>Number of bytes in string</entry>
1206 <entry><literal>octet_length('jose')</literal></entry>
1207 <entry><literal>4</literal></entry>
1213 <primary>overlay</primary>
1215 <literal><function>overlay(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int</type> <optional>for <type>int</type></optional>)</function></literal>
1217 <entry><type>text</type></entry>
1221 <entry><literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal></entry>
1222 <entry><literal>Thomas</literal></entry>
1228 <primary>position</primary>
1230 <literal><function>position(<parameter>substring</parameter> in <parameter>string</parameter>)</function></literal>
1232 <entry><type>int</type></entry>
1233 <entry>Location of specified substring</entry>
1234 <entry><literal>position('om' in 'Thomas')</literal></entry>
1235 <entry><literal>3</literal></entry>
1241 <primary>substring</primary>
1243 <literal><function>substring(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</function></literal>
1245 <entry><type>text</type></entry>
1249 <entry><literal>substring('Thomas' from 2 for 3)</literal></entry>
1250 <entry><literal>hom</literal></entry>
1254 <entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable>)</function></literal></entry>
1255 <entry><type>text</type></entry>
1257 Extract substring matching POSIX regular expression. See
1258 <xref linkend="functions-matching"> for more information on pattern
1261 <entry><literal>substring('Thomas' from '...$')</literal></entry>
1262 <entry><literal>mas</literal></entry>
1266 <entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable> for <replaceable>escape</replaceable>)</function></literal></entry>
1267 <entry><type>text</type></entry>
1269 Extract substring matching <acronym>SQL</acronym> regular expression.
1270 See <xref linkend="functions-matching"> for more information on
1273 <entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry>
1274 <entry><literal>oma</literal></entry>
1280 <primary>trim</primary>
1282 <literal><function>trim(<optional>leading | trailing | both</optional>
1283 <optional><parameter>characters</parameter></optional> from
1284 <parameter>string</parameter>)</function></literal>
1286 <entry><type>text</type></entry>
1288 Remove the longest string containing only the
1289 <parameter>characters</parameter> (a space by default) from the
1290 start/end/both ends of the <parameter>string</parameter>
1292 <entry><literal>trim(both 'x' from 'xTomxx')</literal></entry>
1293 <entry><literal>Tom</literal></entry>
1299 <primary>upper</primary>
1301 <literal><function>upper(<parameter>string</parameter>)</function></literal>
1303 <entry><type>text</type></entry>
1304 <entry>Convert string to upper case</entry>
1305 <entry><literal>upper('tom')</literal></entry>
1306 <entry><literal>TOM</literal></entry>
1313 Additional string manipulation functions are available and are
1314 listed in <xref linkend="functions-string-other">. Some of them are used internally to implement the
1315 <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql">.
1318 <table id="functions-string-other">
1319 <title>Other String Functions</title>
1323 <entry>Function</entry>
1324 <entry>Return Type</entry>
1325 <entry>Description</entry>
1326 <entry>Example</entry>
1327 <entry>Result</entry>
1335 <primary>ascii</primary>
1337 <literal><function>ascii(<parameter>string</parameter>)</function></literal>
1339 <entry><type>int</type></entry>
1341 <acronym>ASCII</acronym> code of the first character of the
1342 argument. For <acronym>UTF8</acronym> returns the Unicode code
1343 point of the character. For other multibyte encodings, the
1344 argument must be an <acronym>ASCII</acronym> character.
1346 <entry><literal>ascii('x')</literal></entry>
1347 <entry><literal>120</literal></entry>
1353 <primary>btrim</primary>
1355 <literal><function>btrim(<parameter>string</parameter> <type>text</type>
1356 <optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
1358 <entry><type>text</type></entry>
1360 Remove the longest string consisting only of characters
1361 in <parameter>characters</parameter> (a space by default)
1362 from the start and end of <parameter>string</parameter>
1364 <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry>
1365 <entry><literal>trim</literal></entry>
1371 <primary>chr</primary>
1373 <literal><function>chr(<type>int</type>)</function></literal>
1375 <entry><type>text</type></entry>
1377 Character with the given code. For <acronym>UTF8</acronym> the
1378 argument is treated as a Unicode code point. For other multibyte
1379 encodings the argument must designate an
1380 <acronym>ASCII</acronym> character. The NULL (0) character is not
1381 allowed because text data types cannot store such bytes.
1383 <entry><literal>chr(65)</literal></entry>
1384 <entry><literal>A</literal></entry>
1390 <primary>concat</primary>
1392 <literal><function>concat(<parameter>str</parameter> <type>"any"</type>
1393 [, <parameter>str</parameter> <type>"any"</type> [, ...] ])</function></literal>
1395 <entry><type>text</type></entry>
1397 Concatenate all arguments. NULL arguments are ignored.
1399 <entry><literal>concat('abcde', 2, NULL, 22)</literal></entry>
1400 <entry><literal>abcde222</literal></entry>
1406 <primary>concat_ws</primary>
1408 <literal><function>concat_ws(<parameter>sep</parameter> <type>text</type>,
1409 <parameter>str</parameter> <type>"any"</type>
1410 [, <parameter>str</parameter> <type>"any"</type> [, ...] ])</function></literal>
1412 <entry><type>text</type></entry>
1414 Concatenate all but first arguments with separators. The first
1415 parameter is used as a separator. NULL arguments are ignored.
1417 <entry><literal>concat_ws(',', 'abcde', 2, NULL, 22)</literal></entry>
1418 <entry><literal>abcde,2,22</literal></entry>
1424 <primary>convert</primary>
1426 <literal><function>convert(<parameter>string</parameter> <type>bytea</type>,
1427 <parameter>src_encoding</parameter> <type>name</type>,
1428 <parameter>dest_encoding</parameter> <type>name</type>)</function></literal>
1430 <entry><type>bytea</type></entry>
1432 Convert string to <parameter>dest_encoding</parameter>. The
1433 original encoding is specified by
1434 <parameter>src_encoding</parameter>. The
1435 <parameter>string</parameter> must be valid in this encoding.
1436 Conversions can be defined by <command>CREATE CONVERSION</command>.
1437 Also there are some predefined conversions. See <xref
1438 linkend="conversion-names"> for available conversions.
1440 <entry><literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal></entry>
1441 <entry><literal>text_in_utf8</literal> represented in Latin-1
1442 encoding (ISO 8859-1)</entry>
1448 <primary>convert_from</primary>
1450 <literal><function>convert_from(<parameter>string</parameter> <type>bytea</type>,
1451 <parameter>src_encoding</parameter> <type>name</type>)</function></literal>
1453 <entry><type>text</type></entry>
1455 Convert string to the database encoding. The original encoding
1456 is specified by <parameter>src_encoding</parameter>. The
1457 <parameter>string</parameter> must be valid in this encoding.
1459 <entry><literal>convert_from('text_in_utf8', 'UTF8')</literal></entry>
1460 <entry><literal>text_in_utf8</literal> represented in the current database encoding</entry>
1466 <primary>convert_to</primary>
1468 <literal><function>convert_to(<parameter>string</parameter> <type>text</type>,
1469 <parameter>dest_encoding</parameter> <type>name</type>)</function></literal>
1471 <entry><type>bytea</type></entry>
1473 Convert string to <parameter>dest_encoding</parameter>.
1475 <entry><literal>convert_to('some text', 'UTF8')</literal></entry>
1476 <entry><literal>some text</literal> represented in the UTF8 encoding</entry>
1482 <primary>decode</primary>
1484 <literal><function>decode(<parameter>string</parameter> <type>text</type>,
1485 <parameter>format</parameter> <type>text</type>)</function></literal>
1487 <entry><type>bytea</type></entry>
1489 Decode binary data from textual representation in <parameter>string</>.
1490 Options for <parameter>format</> are same as in <function>encode</>.
1492 <entry><literal>decode('MTIzAAE=', 'base64')</literal></entry>
1493 <entry><literal>\x3132330001</literal></entry>
1499 <primary>encode</primary>
1501 <literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
1502 <parameter>format</parameter> <type>text</type>)</function></literal>
1504 <entry><type>text</type></entry>
1506 Encode binary data into a textual representation. Supported
1507 formats are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
1508 <literal>escape</> merely outputs null bytes as <literal>\000</> and
1509 doubles backslashes.
1511 <entry><literal>encode(E'123\\000\\001', 'base64')</literal></entry>
1512 <entry><literal>MTIzAAE=</literal></entry>
1518 <primary>format</primary>
1520 <literal><function>format</function>(<parameter>formatstr</parameter> <type>text</type>
1521 [, <parameter>str</parameter> <type>"any"</type> [, ...] ])</literal>
1523 <entry><type>text</type></entry>
1525 Format a string. This function is similar to the C function
1526 <function>sprintf</>; but only the following conversion specifications
1527 are recognized: <literal>%s</literal> interpolates the corresponding
1528 argument as a string; <literal>%I</literal> escapes its argument as
1529 an SQL identifier; <literal>%L</literal> escapes its argument as an
1530 SQL literal; <literal>%%</literal> outputs a literal <literal>%</>.
1531 A conversion can reference an explicit parameter position by preceding
1532 the conversion specifier with <literal><replaceable>n</>$</>, where
1533 <replaceable>n</replaceable> is the argument position.
1534 See also <xref linkend="plpgsql-quote-literal-example">.
1536 <entry><literal>format('Hello %s, %1$s', 'World')</literal></entry>
1537 <entry><literal>Hello World, World</literal></entry>
1543 <primary>initcap</primary>
1545 <literal><function>initcap(<parameter>string</parameter>)</function></literal>
1547 <entry><type>text</type></entry>
1549 Convert the first letter of each word to upper case and the
1550 rest to lower case. Words are sequences of alphanumeric
1551 characters separated by non-alphanumeric characters.
1553 <entry><literal>initcap('hi THOMAS')</literal></entry>
1554 <entry><literal>Hi Thomas</literal></entry>
1560 <primary>left</primary>
1562 <literal><function>left(<parameter>str</parameter> <type>text</type>,
1563 <parameter>n</parameter> <type>int</type>)</function></literal>
1565 <entry><type>text</type></entry>
1567 Return first <replaceable>n</> characters in the string. When <replaceable>n</>
1568 is negative, return all but last |<replaceable>n</>| characters.
1570 <entry><literal>left('abcde', 2)</literal></entry>
1571 <entry><literal>ab</literal></entry>
1577 <primary>length</primary>
1579 <literal><function>length(<parameter>string</parameter>)</function></literal>
1581 <entry><type>int</type></entry>
1583 Number of characters in <parameter>string</parameter>
1585 <entry><literal>length('jose')</literal></entry>
1586 <entry><literal>4</literal></entry>
1590 <entry><literal><function>length(<parameter>string</parameter><type>bytea</type>,
1591 <parameter>encoding</parameter> <type>name</type> )</function></literal></entry>
1592 <entry><type>int</type></entry>
1594 Number of characters in <parameter>string</parameter> in the given
1595 <parameter>encoding</parameter>. The <parameter>string</parameter>
1596 must be valid in this encoding.
1598 <entry><literal>length('jose', 'UTF8')</literal></entry>
1599 <entry><literal>4</literal></entry>
1605 <primary>lpad</primary>
1607 <literal><function>lpad(<parameter>string</parameter> <type>text</type>,
1608 <parameter>length</parameter> <type>int</type>
1609 <optional>, <parameter>fill</parameter> <type>text</type></optional>)</function></literal>
1611 <entry><type>text</type></entry>
1613 Fill up the <parameter>string</parameter> to length
1614 <parameter>length</parameter> by prepending the characters
1615 <parameter>fill</parameter> (a space by default). If the
1616 <parameter>string</parameter> is already longer than
1617 <parameter>length</parameter> then it is truncated (on the
1620 <entry><literal>lpad('hi', 5, 'xy')</literal></entry>
1621 <entry><literal>xyxhi</literal></entry>
1627 <primary>ltrim</primary>
1629 <literal><function>ltrim(<parameter>string</parameter> <type>text</type>
1630 <optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
1632 <entry><type>text</type></entry>
1634 Remove the longest string containing only characters from
1635 <parameter>characters</parameter> (a space by default) from the start of
1636 <parameter>string</parameter>
1638 <entry><literal>ltrim('zzzytrim', 'xyz')</literal></entry>
1639 <entry><literal>trim</literal></entry>
1645 <primary>md5</primary>
1647 <literal><function>md5(<parameter>string</parameter>)</function></literal>
1649 <entry><type>text</type></entry>
1651 Calculates the MD5 hash of <parameter>string</parameter>,
1652 returning the result in hexadecimal
1654 <entry><literal>md5('abc')</literal></entry>
1655 <entry><literal>900150983cd24fb0 d6963f7d28e17f72</literal></entry>
1661 <primary>pg_client_encoding</primary>
1663 <literal><function>pg_client_encoding()</function></literal>
1665 <entry><type>name</type></entry>
1667 Current client encoding name
1669 <entry><literal>pg_client_encoding()</literal></entry>
1670 <entry><literal>SQL_ASCII</literal></entry>
1676 <primary>quote_ident</primary>
1678 <literal><function>quote_ident(<parameter>string</parameter> <type>text</type>)</function></literal>
1680 <entry><type>text</type></entry>
1682 Return the given string suitably quoted to be used as an identifier
1683 in an <acronym>SQL</acronym> statement string.
1684 Quotes are added only if necessary (i.e., if the string contains
1685 non-identifier characters or would be case-folded).
1686 Embedded quotes are properly doubled.
1687 See also <xref linkend="plpgsql-quote-literal-example">.
1689 <entry><literal>quote_ident('Foo bar')</literal></entry>
1690 <entry><literal>"Foo bar"</literal></entry>
1696 <primary>quote_literal</primary>
1698 <literal><function>quote_literal(<parameter>string</parameter> <type>text</type>)</function></literal>
1700 <entry><type>text</type></entry>
1702 Return the given string suitably quoted to be used as a string literal
1703 in an <acronym>SQL</acronym> statement string.
1704 Embedded single-quotes and backslashes are properly doubled.
1705 Note that <function>quote_literal</function> returns null on null
1706 input; if the argument might be null,
1707 <function>quote_nullable</function> is often more suitable.
1708 See also <xref linkend="plpgsql-quote-literal-example">.
1710 <entry><literal>quote_literal(E'O\'Reilly')</literal></entry>
1711 <entry><literal>'O''Reilly'</literal></entry>
1715 <entry><literal><function>quote_literal(<parameter>value</parameter> <type>anyelement</type>)</function></literal></entry>
1716 <entry><type>text</type></entry>
1718 Coerce the given value to text and then quote it as a literal.
1719 Embedded single-quotes and backslashes are properly doubled.
1721 <entry><literal>quote_literal(42.5)</literal></entry>
1722 <entry><literal>'42.5'</literal></entry>
1728 <primary>quote_nullable</primary>
1730 <literal><function>quote_nullable(<parameter>string</parameter> <type>text</type>)</function></literal>
1732 <entry><type>text</type></entry>
1734 Return the given string suitably quoted to be used as a string literal
1735 in an <acronym>SQL</acronym> statement string; or, if the argument
1736 is null, return <literal>NULL</>.
1737 Embedded single-quotes and backslashes are properly doubled.
1738 See also <xref linkend="plpgsql-quote-literal-example">.
1740 <entry><literal>quote_nullable(NULL)</literal></entry>
1741 <entry><literal>NULL</literal></entry>
1745 <entry><literal><function>quote_nullable(<parameter>value</parameter> <type>anyelement</type>)</function></literal></entry>
1746 <entry><type>text</type></entry>
1748 Coerce the given value to text and then quote it as a literal;
1749 or, if the argument is null, return <literal>NULL</>.
1750 Embedded single-quotes and backslashes are properly doubled.
1752 <entry><literal>quote_nullable(42.5)</literal></entry>
1753 <entry><literal>'42.5'</literal></entry>
1759 <primary>regexp_matches</primary>
1761 <literal><function>regexp_matches(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
1763 <entry><type>setof text[]</type></entry>
1765 Return all captured substrings resulting from matching a POSIX regular
1766 expression against the <parameter>string</parameter>. See
1767 <xref linkend="functions-posix-regexp"> for more information.
1769 <entry><literal>regexp_matches('foobarbequebaz', '(bar)(beque)')</literal></entry>
1770 <entry><literal>{bar,beque}</literal></entry>
1776 <primary>regexp_replace</primary>
1778 <literal><function>regexp_replace(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
1780 <entry><type>text</type></entry>
1782 Replace substring(s) matching a POSIX regular expression. See
1783 <xref linkend="functions-posix-regexp"> for more information.
1785 <entry><literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal></entry>
1786 <entry><literal>ThM</literal></entry>
1792 <primary>regexp_split_to_array</primary>
1794 <literal><function>regexp_split_to_array(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type> ])</function></literal>
1796 <entry><type>text[]</type></entry>
1798 Split <parameter>string</parameter> using a POSIX regular expression as
1799 the delimiter. See <xref linkend="functions-posix-regexp"> for more
1802 <entry><literal>regexp_split_to_array('hello world', E'\\s+')</literal></entry>
1803 <entry><literal>{hello,world}</literal></entry>
1809 <primary>regexp_split_to_table</primary>
1811 <literal><function>regexp_split_to_table(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
1813 <entry><type>setof text</type></entry>
1815 Split <parameter>string</parameter> using a POSIX regular expression as
1816 the delimiter. See <xref linkend="functions-posix-regexp"> for more
1819 <entry><literal>regexp_split_to_table('hello world', E'\\s+')</literal></entry>
1820 <entry><literal>hello</literal><para><literal>world</literal></para> (2 rows)</entry>
1826 <primary>repeat</primary>
1828 <literal><function>repeat(<parameter>string</parameter> <type>text</type>, <parameter>number</parameter> <type>int</type>)</function></literal>
1830 <entry><type>text</type></entry>
1831 <entry>Repeat <parameter>string</parameter> the specified
1832 <parameter>number</parameter> of times</entry>
1833 <entry><literal>repeat('Pg', 4)</literal></entry>
1834 <entry><literal>PgPgPgPg</literal></entry>
1840 <primary>replace</primary>
1842 <literal><function>replace(<parameter>string</parameter> <type>text</type>,
1843 <parameter>from</parameter> <type>text</type>,
1844 <parameter>to</parameter> <type>text</type>)</function></literal>
1846 <entry><type>text</type></entry>
1847 <entry>Replace all occurrences in <parameter>string</parameter> of substring
1848 <parameter>from</parameter> with substring <parameter>to</parameter>
1850 <entry><literal>replace('abcdefabcdef', 'cd', 'XX')</literal></entry>
1851 <entry><literal>abXXefabXXef</literal></entry>
1857 <primary>reverse</primary>
1859 <literal><function>reverse(<parameter>str</parameter>)</function></literal>
1861 <entry><type>text</type></entry>
1863 Return reversed string.
1865 <entry><literal>reverse('abcde')</literal></entry>
1866 <entry><literal>edcba</literal></entry>
1872 <primary>right</primary>
1874 <literal><function>right(<parameter>str</parameter> <type>text</type>,
1875 <parameter>n</parameter> <type>int</type>)</function></literal>
1877 <entry><type>text</type></entry>
1879 Return last <replaceable>n</> characters in the string. When <replaceable>n</>
1880 is negative, return all but first |<replaceable>n</>| characters.
1882 <entry><literal>right('abcde', 2)</literal></entry>
1883 <entry><literal>de</literal></entry>
1889 <primary>rpad</primary>
1891 <literal><function>rpad(<parameter>string</parameter> <type>text</type>,
1892 <parameter>length</parameter> <type>int</type>
1893 <optional>, <parameter>fill</parameter> <type>text</type></optional>)</function></literal>
1895 <entry><type>text</type></entry>
1897 Fill up the <parameter>string</parameter> to length
1898 <parameter>length</parameter> by appending the characters
1899 <parameter>fill</parameter> (a space by default). If the
1900 <parameter>string</parameter> is already longer than
1901 <parameter>length</parameter> then it is truncated.
1903 <entry><literal>rpad('hi', 5, 'xy')</literal></entry>
1904 <entry><literal>hixyx</literal></entry>
1910 <primary>rtrim</primary>
1912 <literal><function>rtrim(<parameter>string</parameter> <type>text</type>
1913 <optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
1915 <entry><type>text</type></entry>
1917 Remove the longest string containing only characters from
1918 <parameter>characters</parameter> (a space by default) from the end of
1919 <parameter>string</parameter>
1921 <entry><literal>rtrim('trimxxxx', 'x')</literal></entry>
1922 <entry><literal>trim</literal></entry>
1928 <primary>split_part</primary>
1930 <literal><function>split_part(<parameter>string</parameter> <type>text</type>,
1931 <parameter>delimiter</parameter> <type>text</type>,
1932 <parameter>field</parameter> <type>int</type>)</function></literal>
1934 <entry><type>text</type></entry>
1935 <entry>Split <parameter>string</parameter> on <parameter>delimiter</parameter>
1936 and return the given field (counting from one)
1938 <entry><literal>split_part('abc~@~def~@~ghi', '~@~', 2)</literal></entry>
1939 <entry><literal>def</literal></entry>
1945 <primary>strpos</primary>
1947 <literal><function>strpos(<parameter>string</parameter>, <parameter>substring</parameter>)</function></literal>
1949 <entry><type>int</type></entry>
1951 Location of specified substring (same as
1952 <literal>position(<parameter>substring</parameter> in
1953 <parameter>string</parameter>)</literal>, but note the reversed
1956 <entry><literal>strpos('high', 'ig')</literal></entry>
1957 <entry><literal>2</literal></entry>
1963 <primary>substr</primary>
1965 <literal><function>substr(<parameter>string</parameter>, <parameter>from</parameter> <optional>, <parameter>count</parameter></optional>)</function></literal>
1967 <entry><type>text</type></entry>
1969 Extract substring (same as
1970 <literal>substring(<parameter>string</parameter> from <parameter>from</parameter> for <parameter>count</parameter>)</literal>)
1972 <entry><literal>substr('alphabet', 3, 2)</literal></entry>
1973 <entry><literal>ph</literal></entry>
1979 <primary>to_ascii</primary>
1981 <literal><function>to_ascii(<parameter>string</parameter> <type>text</type>
1982 <optional>, <parameter>encoding</parameter> <type>text</type></optional>)</function></literal>
1984 <entry><type>text</type></entry>
1986 Convert <parameter>string</parameter> to <acronym>ASCII</acronym> from another encoding
1987 (only supports conversion from <literal>LATIN1</>, <literal>LATIN2</>, <literal>LATIN9</>,
1988 and <literal>WIN1250</> encodings)
1990 <entry><literal>to_ascii('Karel')</literal></entry>
1991 <entry><literal>Karel</literal></entry>
1997 <primary>to_hex</primary>
1999 <literal><function>to_hex(<parameter>number</parameter> <type>int</type>
2000 or <type>bigint</type>)</function></literal>
2002 <entry><type>text</type></entry>
2003 <entry>Convert <parameter>number</parameter> to its equivalent hexadecimal
2006 <entry><literal>to_hex(2147483647)</literal></entry>
2007 <entry><literal>7fffffff</literal></entry>
2013 <primary>translate</primary>
2015 <literal><function>translate(<parameter>string</parameter> <type>text</type>,
2016 <parameter>from</parameter> <type>text</type>,
2017 <parameter>to</parameter> <type>text</type>)</function></literal>
2019 <entry><type>text</type></entry>
2021 Any character in <parameter>string</parameter> that matches a
2022 character in the <parameter>from</parameter> set is replaced by
2023 the corresponding character in the <parameter>to</parameter>
2024 set. If <parameter>from</parameter> is longer than
2025 <parameter>to</parameter>, occurrences of the extra characters in
2026 <parameter>from</parameter> are removed.
2028 <entry><literal>translate('12345', '143', 'ax')</literal></entry>
2029 <entry><literal>a2x5</literal></entry>
2037 See also the aggregate function <function>string_agg</function> in
2038 <xref linkend="functions-aggregate">.
2041 <table id="conversion-names">
2042 <title>Built-in Conversions</title>
2046 <entry>Conversion Name
2049 The conversion names follow a standard naming scheme: The
2050 official name of the source encoding with all
2051 non-alphanumeric characters replaced by underscores, followed
2052 by <literal>_to_</literal>, followed by the similarly processed
2053 destination encoding name. Therefore, the names might deviate
2054 from the customary encoding names.
2058 <entry>Source Encoding</entry>
2059 <entry>Destination Encoding</entry>
2065 <entry><literal>ascii_to_mic</literal></entry>
2066 <entry><literal>SQL_ASCII</literal></entry>
2067 <entry><literal>MULE_INTERNAL</literal></entry>
2071 <entry><literal>ascii_to_utf8</literal></entry>
2072 <entry><literal>SQL_ASCII</literal></entry>
2073 <entry><literal>UTF8</literal></entry>
2077 <entry><literal>big5_to_euc_tw</literal></entry>
2078 <entry><literal>BIG5</literal></entry>
2079 <entry><literal>EUC_TW</literal></entry>
2083 <entry><literal>big5_to_mic</literal></entry>
2084 <entry><literal>BIG5</literal></entry>
2085 <entry><literal>MULE_INTERNAL</literal></entry>
2089 <entry><literal>big5_to_utf8</literal></entry>
2090 <entry><literal>BIG5</literal></entry>
2091 <entry><literal>UTF8</literal></entry>
2095 <entry><literal>euc_cn_to_mic</literal></entry>
2096 <entry><literal>EUC_CN</literal></entry>
2097 <entry><literal>MULE_INTERNAL</literal></entry>
2101 <entry><literal>euc_cn_to_utf8</literal></entry>
2102 <entry><literal>EUC_CN</literal></entry>
2103 <entry><literal>UTF8</literal></entry>
2107 <entry><literal>euc_jp_to_mic</literal></entry>
2108 <entry><literal>EUC_JP</literal></entry>
2109 <entry><literal>MULE_INTERNAL</literal></entry>
2113 <entry><literal>euc_jp_to_sjis</literal></entry>
2114 <entry><literal>EUC_JP</literal></entry>
2115 <entry><literal>SJIS</literal></entry>
2119 <entry><literal>euc_jp_to_utf8</literal></entry>
2120 <entry><literal>EUC_JP</literal></entry>
2121 <entry><literal>UTF8</literal></entry>
2125 <entry><literal>euc_kr_to_mic</literal></entry>
2126 <entry><literal>EUC_KR</literal></entry>
2127 <entry><literal>MULE_INTERNAL</literal></entry>
2131 <entry><literal>euc_kr_to_utf8</literal></entry>
2132 <entry><literal>EUC_KR</literal></entry>
2133 <entry><literal>UTF8</literal></entry>
2137 <entry><literal>euc_tw_to_big5</literal></entry>
2138 <entry><literal>EUC_TW</literal></entry>
2139 <entry><literal>BIG5</literal></entry>
2143 <entry><literal>euc_tw_to_mic</literal></entry>
2144 <entry><literal>EUC_TW</literal></entry>
2145 <entry><literal>MULE_INTERNAL</literal></entry>
2149 <entry><literal>euc_tw_to_utf8</literal></entry>
2150 <entry><literal>EUC_TW</literal></entry>
2151 <entry><literal>UTF8</literal></entry>
2155 <entry><literal>gb18030_to_utf8</literal></entry>
2156 <entry><literal>GB18030</literal></entry>
2157 <entry><literal>UTF8</literal></entry>
2161 <entry><literal>gbk_to_utf8</literal></entry>
2162 <entry><literal>GBK</literal></entry>
2163 <entry><literal>UTF8</literal></entry>
2167 <entry><literal>iso_8859_10_to_utf8</literal></entry>
2168 <entry><literal>LATIN6</literal></entry>
2169 <entry><literal>UTF8</literal></entry>
2173 <entry><literal>iso_8859_13_to_utf8</literal></entry>
2174 <entry><literal>LATIN7</literal></entry>
2175 <entry><literal>UTF8</literal></entry>
2179 <entry><literal>iso_8859_14_to_utf8</literal></entry>
2180 <entry><literal>LATIN8</literal></entry>
2181 <entry><literal>UTF8</literal></entry>
2185 <entry><literal>iso_8859_15_to_utf8</literal></entry>
2186 <entry><literal>LATIN9</literal></entry>
2187 <entry><literal>UTF8</literal></entry>
2191 <entry><literal>iso_8859_16_to_utf8</literal></entry>
2192 <entry><literal>LATIN10</literal></entry>
2193 <entry><literal>UTF8</literal></entry>
2197 <entry><literal>iso_8859_1_to_mic</literal></entry>
2198 <entry><literal>LATIN1</literal></entry>
2199 <entry><literal>MULE_INTERNAL</literal></entry>
2203 <entry><literal>iso_8859_1_to_utf8</literal></entry>
2204 <entry><literal>LATIN1</literal></entry>
2205 <entry><literal>UTF8</literal></entry>
2209 <entry><literal>iso_8859_2_to_mic</literal></entry>
2210 <entry><literal>LATIN2</literal></entry>
2211 <entry><literal>MULE_INTERNAL</literal></entry>
2215 <entry><literal>iso_8859_2_to_utf8</literal></entry>
2216 <entry><literal>LATIN2</literal></entry>
2217 <entry><literal>UTF8</literal></entry>
2221 <entry><literal>iso_8859_2_to_windows_1250</literal></entry>
2222 <entry><literal>LATIN2</literal></entry>
2223 <entry><literal>WIN1250</literal></entry>
2227 <entry><literal>iso_8859_3_to_mic</literal></entry>
2228 <entry><literal>LATIN3</literal></entry>
2229 <entry><literal>MULE_INTERNAL</literal></entry>
2233 <entry><literal>iso_8859_3_to_utf8</literal></entry>
2234 <entry><literal>LATIN3</literal></entry>
2235 <entry><literal>UTF8</literal></entry>
2239 <entry><literal>iso_8859_4_to_mic</literal></entry>
2240 <entry><literal>LATIN4</literal></entry>
2241 <entry><literal>MULE_INTERNAL</literal></entry>
2245 <entry><literal>iso_8859_4_to_utf8</literal></entry>
2246 <entry><literal>LATIN4</literal></entry>
2247 <entry><literal>UTF8</literal></entry>
2251 <entry><literal>iso_8859_5_to_koi8_r</literal></entry>
2252 <entry><literal>ISO_8859_5</literal></entry>
2253 <entry><literal>KOI8R</literal></entry>
2257 <entry><literal>iso_8859_5_to_mic</literal></entry>
2258 <entry><literal>ISO_8859_5</literal></entry>
2259 <entry><literal>MULE_INTERNAL</literal></entry>
2263 <entry><literal>iso_8859_5_to_utf8</literal></entry>
2264 <entry><literal>ISO_8859_5</literal></entry>
2265 <entry><literal>UTF8</literal></entry>
2269 <entry><literal>iso_8859_5_to_windows_1251</literal></entry>
2270 <entry><literal>ISO_8859_5</literal></entry>
2271 <entry><literal>WIN1251</literal></entry>
2275 <entry><literal>iso_8859_5_to_windows_866</literal></entry>
2276 <entry><literal>ISO_8859_5</literal></entry>
2277 <entry><literal>WIN866</literal></entry>
2281 <entry><literal>iso_8859_6_to_utf8</literal></entry>
2282 <entry><literal>ISO_8859_6</literal></entry>
2283 <entry><literal>UTF8</literal></entry>
2287 <entry><literal>iso_8859_7_to_utf8</literal></entry>
2288 <entry><literal>ISO_8859_7</literal></entry>
2289 <entry><literal>UTF8</literal></entry>
2293 <entry><literal>iso_8859_8_to_utf8</literal></entry>
2294 <entry><literal>ISO_8859_8</literal></entry>
2295 <entry><literal>UTF8</literal></entry>
2299 <entry><literal>iso_8859_9_to_utf8</literal></entry>
2300 <entry><literal>LATIN5</literal></entry>
2301 <entry><literal>UTF8</literal></entry>
2305 <entry><literal>johab_to_utf8</literal></entry>
2306 <entry><literal>JOHAB</literal></entry>
2307 <entry><literal>UTF8</literal></entry>
2311 <entry><literal>koi8_r_to_iso_8859_5</literal></entry>
2312 <entry><literal>KOI8R</literal></entry>
2313 <entry><literal>ISO_8859_5</literal></entry>
2317 <entry><literal>koi8_r_to_mic</literal></entry>
2318 <entry><literal>KOI8R</literal></entry>
2319 <entry><literal>MULE_INTERNAL</literal></entry>
2323 <entry><literal>koi8_r_to_utf8</literal></entry>
2324 <entry><literal>KOI8R</literal></entry>
2325 <entry><literal>UTF8</literal></entry>
2329 <entry><literal>koi8_r_to_windows_1251</literal></entry>
2330 <entry><literal>KOI8R</literal></entry>
2331 <entry><literal>WIN1251</literal></entry>
2335 <entry><literal>koi8_r_to_windows_866</literal></entry>
2336 <entry><literal>KOI8R</literal></entry>
2337 <entry><literal>WIN866</literal></entry>
2341 <entry><literal>koi8_u_to_utf8</literal></entry>
2342 <entry><literal>KOI8U</literal></entry>
2343 <entry><literal>UTF8</literal></entry>
2347 <entry><literal>mic_to_ascii</literal></entry>
2348 <entry><literal>MULE_INTERNAL</literal></entry>
2349 <entry><literal>SQL_ASCII</literal></entry>
2353 <entry><literal>mic_to_big5</literal></entry>
2354 <entry><literal>MULE_INTERNAL</literal></entry>
2355 <entry><literal>BIG5</literal></entry>
2359 <entry><literal>mic_to_euc_cn</literal></entry>
2360 <entry><literal>MULE_INTERNAL</literal></entry>
2361 <entry><literal>EUC_CN</literal></entry>
2365 <entry><literal>mic_to_euc_jp</literal></entry>
2366 <entry><literal>MULE_INTERNAL</literal></entry>
2367 <entry><literal>EUC_JP</literal></entry>
2371 <entry><literal>mic_to_euc_kr</literal></entry>
2372 <entry><literal>MULE_INTERNAL</literal></entry>
2373 <entry><literal>EUC_KR</literal></entry>
2377 <entry><literal>mic_to_euc_tw</literal></entry>
2378 <entry><literal>MULE_INTERNAL</literal></entry>
2379 <entry><literal>EUC_TW</literal></entry>
2383 <entry><literal>mic_to_iso_8859_1</literal></entry>
2384 <entry><literal>MULE_INTERNAL</literal></entry>
2385 <entry><literal>LATIN1</literal></entry>
2389 <entry><literal>mic_to_iso_8859_2</literal></entry>
2390 <entry><literal>MULE_INTERNAL</literal></entry>
2391 <entry><literal>LATIN2</literal></entry>
2395 <entry><literal>mic_to_iso_8859_3</literal></entry>
2396 <entry><literal>MULE_INTERNAL</literal></entry>
2397 <entry><literal>LATIN3</literal></entry>
2401 <entry><literal>mic_to_iso_8859_4</literal></entry>
2402 <entry><literal>MULE_INTERNAL</literal></entry>
2403 <entry><literal>LATIN4</literal></entry>
2407 <entry><literal>mic_to_iso_8859_5</literal></entry>
2408 <entry><literal>MULE_INTERNAL</literal></entry>
2409 <entry><literal>ISO_8859_5</literal></entry>
2413 <entry><literal>mic_to_koi8_r</literal></entry>
2414 <entry><literal>MULE_INTERNAL</literal></entry>
2415 <entry><literal>KOI8R</literal></entry>
2419 <entry><literal>mic_to_sjis</literal></entry>
2420 <entry><literal>MULE_INTERNAL</literal></entry>
2421 <entry><literal>SJIS</literal></entry>
2425 <entry><literal>mic_to_windows_1250</literal></entry>
2426 <entry><literal>MULE_INTERNAL</literal></entry>
2427 <entry><literal>WIN1250</literal></entry>
2431 <entry><literal>mic_to_windows_1251</literal></entry>
2432 <entry><literal>MULE_INTERNAL</literal></entry>
2433 <entry><literal>WIN1251</literal></entry>
2437 <entry><literal>mic_to_windows_866</literal></entry>
2438 <entry><literal>MULE_INTERNAL</literal></entry>
2439 <entry><literal>WIN866</literal></entry>
2443 <entry><literal>sjis_to_euc_jp</literal></entry>
2444 <entry><literal>SJIS</literal></entry>
2445 <entry><literal>EUC_JP</literal></entry>
2449 <entry><literal>sjis_to_mic</literal></entry>
2450 <entry><literal>SJIS</literal></entry>
2451 <entry><literal>MULE_INTERNAL</literal></entry>
2455 <entry><literal>sjis_to_utf8</literal></entry>
2456 <entry><literal>SJIS</literal></entry>
2457 <entry><literal>UTF8</literal></entry>
2461 <entry><literal>tcvn_to_utf8</literal></entry>
2462 <entry><literal>WIN1258</literal></entry>
2463 <entry><literal>UTF8</literal></entry>
2467 <entry><literal>uhc_to_utf8</literal></entry>
2468 <entry><literal>UHC</literal></entry>
2469 <entry><literal>UTF8</literal></entry>
2473 <entry><literal>utf8_to_ascii</literal></entry>
2474 <entry><literal>UTF8</literal></entry>
2475 <entry><literal>SQL_ASCII</literal></entry>
2479 <entry><literal>utf8_to_big5</literal></entry>
2480 <entry><literal>UTF8</literal></entry>
2481 <entry><literal>BIG5</literal></entry>
2485 <entry><literal>utf8_to_euc_cn</literal></entry>
2486 <entry><literal>UTF8</literal></entry>
2487 <entry><literal>EUC_CN</literal></entry>
2491 <entry><literal>utf8_to_euc_jp</literal></entry>
2492 <entry><literal>UTF8</literal></entry>
2493 <entry><literal>EUC_JP</literal></entry>
2497 <entry><literal>utf8_to_euc_kr</literal></entry>
2498 <entry><literal>UTF8</literal></entry>
2499 <entry><literal>EUC_KR</literal></entry>
2503 <entry><literal>utf8_to_euc_tw</literal></entry>
2504 <entry><literal>UTF8</literal></entry>
2505 <entry><literal>EUC_TW</literal></entry>
2509 <entry><literal>utf8_to_gb18030</literal></entry>
2510 <entry><literal>UTF8</literal></entry>
2511 <entry><literal>GB18030</literal></entry>
2515 <entry><literal>utf8_to_gbk</literal></entry>
2516 <entry><literal>UTF8</literal></entry>
2517 <entry><literal>GBK</literal></entry>
2521 <entry><literal>utf8_to_iso_8859_1</literal></entry>
2522 <entry><literal>UTF8</literal></entry>
2523 <entry><literal>LATIN1</literal></entry>
2527 <entry><literal>utf8_to_iso_8859_10</literal></entry>
2528 <entry><literal>UTF8</literal></entry>
2529 <entry><literal>LATIN6</literal></entry>
2533 <entry><literal>utf8_to_iso_8859_13</literal></entry>
2534 <entry><literal>UTF8</literal></entry>
2535 <entry><literal>LATIN7</literal></entry>
2539 <entry><literal>utf8_to_iso_8859_14</literal></entry>
2540 <entry><literal>UTF8</literal></entry>
2541 <entry><literal>LATIN8</literal></entry>
2545 <entry><literal>utf8_to_iso_8859_15</literal></entry>
2546 <entry><literal>UTF8</literal></entry>
2547 <entry><literal>LATIN9</literal></entry>
2551 <entry><literal>utf8_to_iso_8859_16</literal></entry>
2552 <entry><literal>UTF8</literal></entry>
2553 <entry><literal>LATIN10</literal></entry>
2557 <entry><literal>utf8_to_iso_8859_2</literal></entry>
2558 <entry><literal>UTF8</literal></entry>
2559 <entry><literal>LATIN2</literal></entry>
2563 <entry><literal>utf8_to_iso_8859_3</literal></entry>
2564 <entry><literal>UTF8</literal></entry>
2565 <entry><literal>LATIN3</literal></entry>
2569 <entry><literal>utf8_to_iso_8859_4</literal></entry>
2570 <entry><literal>UTF8</literal></entry>
2571 <entry><literal>LATIN4</literal></entry>
2575 <entry><literal>utf8_to_iso_8859_5</literal></entry>
2576 <entry><literal>UTF8</literal></entry>
2577 <entry><literal>ISO_8859_5</literal></entry>
2581 <entry><literal>utf8_to_iso_8859_6</literal></entry>
2582 <entry><literal>UTF8</literal></entry>
2583 <entry><literal>ISO_8859_6</literal></entry>
2587 <entry><literal>utf8_to_iso_8859_7</literal></entry>
2588 <entry><literal>UTF8</literal></entry>
2589 <entry><literal>ISO_8859_7</literal></entry>
2593 <entry><literal>utf8_to_iso_8859_8</literal></entry>
2594 <entry><literal>UTF8</literal></entry>
2595 <entry><literal>ISO_8859_8</literal></entry>
2599 <entry><literal>utf8_to_iso_8859_9</literal></entry>
2600 <entry><literal>UTF8</literal></entry>
2601 <entry><literal>LATIN5</literal></entry>
2605 <entry><literal>utf8_to_johab</literal></entry>
2606 <entry><literal>UTF8</literal></entry>
2607 <entry><literal>JOHAB</literal></entry>
2611 <entry><literal>utf8_to_koi8_r</literal></entry>
2612 <entry><literal>UTF8</literal></entry>
2613 <entry><literal>KOI8R</literal></entry>
2617 <entry><literal>utf8_to_koi8_u</literal></entry>
2618 <entry><literal>UTF8</literal></entry>
2619 <entry><literal>KOI8U</literal></entry>
2623 <entry><literal>utf8_to_sjis</literal></entry>
2624 <entry><literal>UTF8</literal></entry>
2625 <entry><literal>SJIS</literal></entry>
2629 <entry><literal>utf8_to_tcvn</literal></entry>
2630 <entry><literal>UTF8</literal></entry>
2631 <entry><literal>WIN1258</literal></entry>
2635 <entry><literal>utf8_to_uhc</literal></entry>
2636 <entry><literal>UTF8</literal></entry>
2637 <entry><literal>UHC</literal></entry>
2641 <entry><literal>utf8_to_windows_1250</literal></entry>
2642 <entry><literal>UTF8</literal></entry>
2643 <entry><literal>WIN1250</literal></entry>
2647 <entry><literal>utf8_to_windows_1251</literal></entry>
2648 <entry><literal>UTF8</literal></entry>
2649 <entry><literal>WIN1251</literal></entry>
2653 <entry><literal>utf8_to_windows_1252</literal></entry>
2654 <entry><literal>UTF8</literal></entry>
2655 <entry><literal>WIN1252</literal></entry>
2659 <entry><literal>utf8_to_windows_1253</literal></entry>
2660 <entry><literal>UTF8</literal></entry>
2661 <entry><literal>WIN1253</literal></entry>
2665 <entry><literal>utf8_to_windows_1254</literal></entry>
2666 <entry><literal>UTF8</literal></entry>
2667 <entry><literal>WIN1254</literal></entry>
2671 <entry><literal>utf8_to_windows_1255</literal></entry>
2672 <entry><literal>UTF8</literal></entry>
2673 <entry><literal>WIN1255</literal></entry>
2677 <entry><literal>utf8_to_windows_1256</literal></entry>
2678 <entry><literal>UTF8</literal></entry>
2679 <entry><literal>WIN1256</literal></entry>
2683 <entry><literal>utf8_to_windows_1257</literal></entry>
2684 <entry><literal>UTF8</literal></entry>
2685 <entry><literal>WIN1257</literal></entry>
2689 <entry><literal>utf8_to_windows_866</literal></entry>
2690 <entry><literal>UTF8</literal></entry>
2691 <entry><literal>WIN866</literal></entry>
2695 <entry><literal>utf8_to_windows_874</literal></entry>
2696 <entry><literal>UTF8</literal></entry>
2697 <entry><literal>WIN874</literal></entry>
2701 <entry><literal>windows_1250_to_iso_8859_2</literal></entry>
2702 <entry><literal>WIN1250</literal></entry>
2703 <entry><literal>LATIN2</literal></entry>
2707 <entry><literal>windows_1250_to_mic</literal></entry>
2708 <entry><literal>WIN1250</literal></entry>
2709 <entry><literal>MULE_INTERNAL</literal></entry>
2713 <entry><literal>windows_1250_to_utf8</literal></entry>
2714 <entry><literal>WIN1250</literal></entry>
2715 <entry><literal>UTF8</literal></entry>
2719 <entry><literal>windows_1251_to_iso_8859_5</literal></entry>
2720 <entry><literal>WIN1251</literal></entry>
2721 <entry><literal>ISO_8859_5</literal></entry>
2725 <entry><literal>windows_1251_to_koi8_r</literal></entry>
2726 <entry><literal>WIN1251</literal></entry>
2727 <entry><literal>KOI8R</literal></entry>
2731 <entry><literal>windows_1251_to_mic</literal></entry>
2732 <entry><literal>WIN1251</literal></entry>
2733 <entry><literal>MULE_INTERNAL</literal></entry>
2737 <entry><literal>windows_1251_to_utf8</literal></entry>
2738 <entry><literal>WIN1251</literal></entry>
2739 <entry><literal>UTF8</literal></entry>
2743 <entry><literal>windows_1251_to_windows_866</literal></entry>
2744 <entry><literal>WIN1251</literal></entry>
2745 <entry><literal>WIN866</literal></entry>
2749 <entry><literal>windows_1252_to_utf8</literal></entry>
2750 <entry><literal>WIN1252</literal></entry>
2751 <entry><literal>UTF8</literal></entry>
2755 <entry><literal>windows_1256_to_utf8</literal></entry>
2756 <entry><literal>WIN1256</literal></entry>
2757 <entry><literal>UTF8</literal></entry>
2761 <entry><literal>windows_866_to_iso_8859_5</literal></entry>
2762 <entry><literal>WIN866</literal></entry>
2763 <entry><literal>ISO_8859_5</literal></entry>
2767 <entry><literal>windows_866_to_koi8_r</literal></entry>
2768 <entry><literal>WIN866</literal></entry>
2769 <entry><literal>KOI8R</literal></entry>
2773 <entry><literal>windows_866_to_mic</literal></entry>
2774 <entry><literal>WIN866</literal></entry>
2775 <entry><literal>MULE_INTERNAL</literal></entry>
2779 <entry><literal>windows_866_to_utf8</literal></entry>
2780 <entry><literal>WIN866</literal></entry>
2781 <entry><literal>UTF8</literal></entry>
2785 <entry><literal>windows_866_to_windows_1251</literal></entry>
2786 <entry><literal>WIN866</literal></entry>
2787 <entry><literal>WIN</literal></entry>
2791 <entry><literal>windows_874_to_utf8</literal></entry>
2792 <entry><literal>WIN874</literal></entry>
2793 <entry><literal>UTF8</literal></entry>
2797 <entry><literal>euc_jis_2004_to_utf8</literal></entry>
2798 <entry><literal>EUC_JIS_2004</literal></entry>
2799 <entry><literal>UTF8</literal></entry>
2803 <entry><literal>ut8_to_euc_jis_2004</literal></entry>
2804 <entry><literal>UTF8</literal></entry>
2805 <entry><literal>EUC_JIS_2004</literal></entry>
2809 <entry><literal>shift_jis_2004_to_utf8</literal></entry>
2810 <entry><literal>SHIFT_JIS_2004</literal></entry>
2811 <entry><literal>UTF8</literal></entry>
2815 <entry><literal>ut8_to_shift_jis_2004</literal></entry>
2816 <entry><literal>UTF8</literal></entry>
2817 <entry><literal>SHIFT_JIS_2004</literal></entry>
2821 <entry><literal>euc_jis_2004_to_shift_jis_2004</literal></entry>
2822 <entry><literal>EUC_JIS_2004</literal></entry>
2823 <entry><literal>SHIFT_JIS_2004</literal></entry>
2827 <entry><literal>shift_jis_2004_to_euc_jis_2004</literal></entry>
2828 <entry><literal>SHIFT_JIS_2004</literal></entry>
2829 <entry><literal>EUC_JIS_2004</literal></entry>
2839 <sect1 id="functions-binarystring">
2840 <title>Binary String Functions and Operators</title>
2842 <indexterm zone="functions-binarystring">
2843 <primary>binary data</primary>
2844 <secondary>functions</secondary>
2848 This section describes functions and operators for examining and
2849 manipulating values of type <type>bytea</type>.
2853 <acronym>SQL</acronym> defines some string functions that use
2854 key words, rather than commas, to separate
2855 arguments. Details are in
2856 <xref linkend="functions-binarystring-sql">.
2857 <productname>PostgreSQL</> also provides versions of these functions
2858 that use the regular function invocation syntax
2859 (see <xref linkend="functions-binarystring-other">).
2864 The sample results shown on this page assume that the server parameter
2865 <link linkend="guc-bytea-output"><varname>bytea_output</></link> is set
2866 to <literal>escape</literal> (the traditional PostgreSQL format).
2870 <table id="functions-binarystring-sql">
2871 <title><acronym>SQL</acronym> Binary String Functions and Operators</title>
2875 <entry>Function</entry>
2876 <entry>Return Type</entry>
2877 <entry>Description</entry>
2878 <entry>Example</entry>
2879 <entry>Result</entry>
2885 <entry><literal><parameter>string</parameter> <literal>||</literal>
2886 <parameter>string</parameter></literal></entry>
2887 <entry> <type>bytea</type> </entry>
2889 String concatenation
2891 <primary>binary string</primary>
2892 <secondary>concatenation</secondary>
2895 <entry><literal>E'\\\\Post'::bytea || E'\\047gres\\000'::bytea</literal></entry>
2896 <entry><literal>\\Post'gres\000</literal></entry>
2902 <primary>octet_length</primary>
2904 <literal><function>octet_length(<parameter>string</parameter>)</function></literal>
2906 <entry><type>int</type></entry>
2907 <entry>Number of bytes in binary string</entry>
2908 <entry><literal>octet_length(E'jo\\000se'::bytea)</literal></entry>
2909 <entry><literal>5</literal></entry>
2915 <primary>overlay</primary>
2917 <literal><function>overlay(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int</type> <optional>for <type>int</type></optional>)</function></literal>
2919 <entry><type>bytea</type></entry>
2923 <entry><literal>overlay(E'Th\\000omas'::bytea placing E'\\002\\003'::bytea from 2 for 3)</literal></entry>
2924 <entry><literal>T\\002\\003mas</literal></entry>
2930 <primary>position</primary>
2932 <literal><function>position(<parameter>substring</parameter> in <parameter>string</parameter>)</function></literal>
2934 <entry><type>int</type></entry>
2935 <entry>Location of specified substring</entry>
2936 <entry><literal>position(E'\\000om'::bytea in E'Th\\000omas'::bytea)</literal></entry>
2937 <entry><literal>3</literal></entry>
2943 <primary>substring</primary>
2945 <literal><function>substring(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</function></literal>
2947 <entry><type>bytea</type></entry>
2951 <entry><literal>substring(E'Th\\000omas'::bytea from 2 for 3)</literal></entry>
2952 <entry><literal>h\000o</literal></entry>
2958 <primary>trim</primary>
2960 <literal><function>trim(<optional>both</optional>
2961 <parameter>bytes</parameter> from
2962 <parameter>string</parameter>)</function></literal>
2964 <entry><type>bytea</type></entry>
2966 Remove the longest string containing only the bytes in
2967 <parameter>bytes</parameter> from the start
2968 and end of <parameter>string</parameter>
2970 <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry>
2971 <entry><literal>Tom</literal></entry>
2978 Additional binary string manipulation functions are available and
2979 are listed in <xref linkend="functions-binarystring-other">. Some
2980 of them are used internally to implement the
2981 <acronym>SQL</acronym>-standard string functions listed in <xref
2982 linkend="functions-binarystring-sql">.
2985 <table id="functions-binarystring-other">
2986 <title>Other Binary String Functions</title>
2990 <entry>Function</entry>
2991 <entry>Return Type</entry>
2992 <entry>Description</entry>
2993 <entry>Example</entry>
2994 <entry>Result</entry>
3002 <primary>btrim</primary>
3004 <literal><function>btrim(<parameter>string</parameter>
3005 <type>bytea</type>, <parameter>bytes</parameter> <type>bytea</type>)</function></literal>
3007 <entry><type>bytea</type></entry>
3009 Remove the longest string consisting only of bytes
3010 in <parameter>bytes</parameter> from the start and end of
3011 <parameter>string</parameter>
3013 <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry>
3014 <entry><literal>trim</literal></entry>
3020 <primary>decode</primary>
3022 <literal><function>decode(<parameter>string</parameter> <type>text</type>,
3023 <parameter>type</parameter> <type>text</type>)</function></literal>
3025 <entry><type>bytea</type></entry>
3027 Decode binary string from <parameter>string</parameter> previously
3028 encoded with <function>encode</>. Parameter type is same as in <function>encode</>.
3030 <entry><literal>decode(E'123\\000456', 'escape')</literal></entry>
3031 <entry><literal>123\000456</literal></entry>
3037 <primary>encode</primary>
3039 <literal><function>encode(<parameter>string</parameter> <type>bytea</type>,
3040 <parameter>type</parameter> <type>text</type>)</function></literal>
3042 <entry><type>text</type></entry>
3044 Encode binary string to <acronym>ASCII</acronym>-only representation. Supported
3045 types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
3047 <entry><literal>encode(E'123\\000456'::bytea, 'escape')</literal></entry>
3048 <entry><literal>123\000456</literal></entry>
3054 <primary>get_bit</primary>
3056 <literal><function>get_bit(<parameter>string</parameter>, <parameter>offset</parameter>)</function></literal>
3058 <entry><type>int</type></entry>
3060 Extract bit from string
3062 <entry><literal>get_bit(E'Th\\000omas'::bytea, 45)</literal></entry>
3063 <entry><literal>1</literal></entry>
3069 <primary>get_byte</primary>
3071 <literal><function>get_byte(<parameter>string</parameter>, <parameter>offset</parameter>)</function></literal>
3073 <entry><type>int</type></entry>
3075 Extract byte from string
3077 <entry><literal>get_byte(E'Th\\000omas'::bytea, 4)</literal></entry>
3078 <entry><literal>109</literal></entry>
3084 <primary>length</primary>
3086 <literal><function>length(<parameter>string</parameter>)</function></literal>
3088 <entry><type>int</type></entry>
3090 Length of binary string
3092 <primary>binary string</primary>
3093 <secondary>length</secondary>
3096 <primary>length</primary>
3097 <secondary sortas="binary string">of a binary string</secondary>
3098 <see>binary strings, length</see>
3101 <entry><literal>length(E'jo\\000se'::bytea)</literal></entry>
3102 <entry><literal>5</literal></entry>
3108 <primary>md5</primary>
3110 <literal><function>md5(<parameter>string</parameter>)</function></literal>
3112 <entry><type>text</type></entry>
3114 Calculates the MD5 hash of <parameter>string</parameter>,
3115 returning the result in hexadecimal
3117 <entry><literal>md5(E'Th\\000omas'::bytea)</literal></entry>
3118 <entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
3124 <primary>set_bit</primary>
3126 <literal><function>set_bit(<parameter>string</parameter>,
3127 <parameter>offset</parameter>, <parameter>newvalue</>)</function></literal>
3129 <entry><type>bytea</type></entry>
3133 <entry><literal>set_bit(E'Th\\000omas'::bytea, 45, 0)</literal></entry>
3134 <entry><literal>Th\000omAs</literal></entry>
3140 <primary>set_byte</primary>
3142 <literal><function>set_byte(<parameter>string</parameter>,
3143 <parameter>offset</parameter>, <parameter>newvalue</>)</function></literal>
3145 <entry><type>bytea</type></entry>
3149 <entry><literal>set_byte(E'Th\\000omas'::bytea, 4, 64)</literal></entry>
3150 <entry><literal>Th\000o@as</literal></entry>
3157 <function>get_byte</> and <function>set_byte</> number the first byte
3158 of a binary string as byte 0.
3159 <function>get_bit</> and <function>set_bit</> number bits from the
3160 right within each byte; for example bit 0 is the least significant bit of
3161 the first byte, and bit 15 is the most significant bit of the second byte.
3166 <sect1 id="functions-bitstring">
3167 <title>Bit String Functions and Operators</title>
3169 <indexterm zone="functions-bitstring">
3170 <primary>bit strings</primary>
3171 <secondary>functions</secondary>
3175 This section describes functions and operators for examining and
3176 manipulating bit strings, that is values of the types
3177 <type>bit</type> and <type>bit varying</type>. Aside from the
3178 usual comparison operators, the operators
3179 shown in <xref linkend="functions-bit-string-op-table"> can be used.
3180 Bit string operands of <literal>&</literal>, <literal>|</literal>,
3181 and <literal>#</literal> must be of equal length. When bit
3182 shifting, the original length of the string is preserved, as shown
3186 <table id="functions-bit-string-op-table">
3187 <title>Bit String Operators</title>
3192 <entry>Operator</entry>
3193 <entry>Description</entry>
3194 <entry>Example</entry>
3195 <entry>Result</entry>
3201 <entry> <literal>||</literal> </entry>
3202 <entry>concatenation</entry>
3203 <entry><literal>B'10001' || B'011'</literal></entry>
3204 <entry><literal>10001011</literal></entry>
3208 <entry> <literal>&</literal> </entry>
3209 <entry>bitwise AND</entry>
3210 <entry><literal>B'10001' & B'01101'</literal></entry>
3211 <entry><literal>00001</literal></entry>
3215 <entry> <literal>|</literal> </entry>
3216 <entry>bitwise OR</entry>
3217 <entry><literal>B'10001' | B'01101'</literal></entry>
3218 <entry><literal>11101</literal></entry>
3222 <entry> <literal>#</literal> </entry>
3223 <entry>bitwise XOR</entry>
3224 <entry><literal>B'10001' # B'01101'</literal></entry>
3225 <entry><literal>11100</literal></entry>
3229 <entry> <literal>~</literal> </entry>
3230 <entry>bitwise NOT</entry>
3231 <entry><literal>~ B'10001'</literal></entry>
3232 <entry><literal>01110</literal></entry>
3236 <entry> <literal><<</literal> </entry>
3237 <entry>bitwise shift left</entry>
3238 <entry><literal>B'10001' << 3</literal></entry>
3239 <entry><literal>01000</literal></entry>
3243 <entry> <literal>>></literal> </entry>
3244 <entry>bitwise shift right</entry>
3245 <entry><literal>B'10001' >> 2</literal></entry>
3246 <entry><literal>00100</literal></entry>
3253 The following <acronym>SQL</acronym>-standard functions work on bit
3254 strings as well as character strings:
3255 <literal><function>length</function></literal>,
3256 <literal><function>bit_length</function></literal>,
3257 <literal><function>octet_length</function></literal>,
3258 <literal><function>position</function></literal>,
3259 <literal><function>substring</function></literal>,
3260 <literal><function>overlay</function></literal>.
3264 The following functions work on bit strings as well as binary
3266 <literal><function>get_bit</function></literal>,
3267 <literal><function>set_bit</function></literal>.
3268 When working with a bit string, these functions number the first
3269 (leftmost) bit of the string as bit 0.
3273 In addition, it is possible to cast integral values to and from type
3277 44::bit(10) <lineannotation>0000101100</lineannotation>
3278 44::bit(3) <lineannotation>100</lineannotation>
3279 cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
3280 '1110'::bit(4)::integer <lineannotation>14</lineannotation>
3282 Note that casting to just <quote>bit</> means casting to
3283 <literal>bit(1)</>, and so will deliver only the least significant
3289 Prior to <productname>PostgreSQL</productname> 8.0, casting an
3290 integer to <type>bit(n)</> would copy the leftmost <literal>n</>
3291 bits of the integer, whereas now it copies the rightmost <literal>n</>
3292 bits. Also, casting an integer to a bit string width wider than
3293 the integer itself will sign-extend on the left.
3300 <sect1 id="functions-matching">
3301 <title>Pattern Matching</title>
3303 <indexterm zone="functions-matching">
3304 <primary>pattern matching</primary>
3308 There are three separate approaches to pattern matching provided
3309 by <productname>PostgreSQL</productname>: the traditional
3310 <acronym>SQL</acronym> <function>LIKE</function> operator, the
3311 more recent <function>SIMILAR TO</function> operator (added in
3312 SQL:1999), and <acronym>POSIX</acronym>-style regular
3313 expressions. Aside from the basic <quote>does this string match
3314 this pattern?</> operators, functions are available to extract
3315 or replace matching substrings and to split a string at matching
3321 If you have pattern matching needs that go beyond this,
3322 consider writing a user-defined function in Perl or Tcl.
3326 <sect2 id="functions-like">
3327 <title><function>LIKE</function></title>
3330 <primary>LIKE</primary>
3334 <replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3335 <replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3339 The <function>LIKE</function> expression returns true if the
3340 <replaceable>string</replaceable> matches the supplied
3341 <replaceable>pattern</replaceable>. (As
3342 expected, the <function>NOT LIKE</function> expression returns
3343 false if <function>LIKE</function> returns true, and vice versa.
3344 An equivalent expression is
3345 <literal>NOT (<replaceable>string</replaceable> LIKE
3346 <replaceable>pattern</replaceable>)</literal>.)
3350 If <replaceable>pattern</replaceable> does not contain percent
3351 signs or underscores, then the pattern only represents the string
3352 itself; in that case <function>LIKE</function> acts like the
3353 equals operator. An underscore (<literal>_</literal>) in
3354 <replaceable>pattern</replaceable> stands for (matches) any single
3355 character; a percent sign (<literal>%</literal>) matches any sequence
3356 of zero or more characters.
3362 'abc' LIKE 'abc' <lineannotation>true</lineannotation>
3363 'abc' LIKE 'a%' <lineannotation>true</lineannotation>
3364 'abc' LIKE '_b_' <lineannotation>true</lineannotation>
3365 'abc' LIKE 'c' <lineannotation>false</lineannotation>
3370 <function>LIKE</function> pattern matching always covers the entire
3371 string. Therefore, to match a sequence anywhere within a string, the
3372 pattern must start and end with a percent sign.
3376 To match a literal underscore or percent sign without matching
3377 other characters, the respective character in
3378 <replaceable>pattern</replaceable> must be
3379 preceded by the escape character. The default escape
3380 character is the backslash but a different one can be selected by
3381 using the <literal>ESCAPE</literal> clause. To match the escape
3382 character itself, write two escape characters.
3386 Note that the backslash already has a special meaning in string literals,
3387 so to write a pattern constant that contains a backslash you must write two
3388 backslashes in an SQL statement (assuming escape string syntax is used, see
3389 <xref linkend="sql-syntax-strings">). Thus, writing a pattern that
3390 actually matches a literal backslash means writing four backslashes in the
3391 statement. You can avoid this by selecting a different escape character
3392 with <literal>ESCAPE</literal>; then a backslash is not special to
3393 <function>LIKE</function> anymore. (But backslash is still special to the
3394 string literal parser, so you still need two of them to match a backslash.)
3398 It's also possible to select no escape character by writing
3399 <literal>ESCAPE ''</literal>. This effectively disables the
3400 escape mechanism, which makes it impossible to turn off the
3401 special meaning of underscore and percent signs in the pattern.
3405 The key word <token>ILIKE</token> can be used instead of
3406 <token>LIKE</token> to make the match case-insensitive according
3407 to the active locale. This is not in the <acronym>SQL</acronym> standard but is a
3408 <productname>PostgreSQL</productname> extension.
3412 The operator <literal>~~</literal> is equivalent to
3413 <function>LIKE</function>, and <literal>~~*</literal> corresponds to
3414 <function>ILIKE</function>. There are also
3415 <literal>!~~</literal> and <literal>!~~*</literal> operators that
3416 represent <function>NOT LIKE</function> and <function>NOT
3417 ILIKE</function>, respectively. All of these operators are
3418 <productname>PostgreSQL</productname>-specific.
3423 <sect2 id="functions-similarto-regexp">
3424 <title><function>SIMILAR TO</function> Regular Expressions</title>
3427 <primary>regular expression</primary>
3428 <!-- <seealso>pattern matching</seealso> breaks index build -->
3432 <primary>SIMILAR TO</primary>
3435 <primary>substring</primary>
3439 <replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3440 <replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3444 The <function>SIMILAR TO</function> operator returns true or
3445 false depending on whether its pattern matches the given string.
3446 It is similar to <function>LIKE</function>, except that it
3447 interprets the pattern using the SQL standard's definition of a
3448 regular expression. SQL regular expressions are a curious cross
3449 between <function>LIKE</function> notation and common regular
3450 expression notation.
3454 Like <function>LIKE</function>, the <function>SIMILAR TO</function>
3455 operator succeeds only if its pattern matches the entire string;
3456 this is unlike common regular expression behavior where the pattern
3457 can match any part of the string.
3459 <function>LIKE</function>, <function>SIMILAR TO</function> uses
3460 <literal>_</> and <literal>%</> as wildcard characters denoting
3461 any single character and any string, respectively (these are
3462 comparable to <literal>.</> and <literal>.*</> in POSIX regular
3467 In addition to these facilities borrowed from <function>LIKE</function>,
3468 <function>SIMILAR TO</function> supports these pattern-matching
3469 metacharacters borrowed from POSIX regular expressions:
3474 <literal>|</literal> denotes alternation (either of two alternatives).
3479 <literal>*</literal> denotes repetition of the previous item zero
3485 <literal>+</literal> denotes repetition of the previous item one
3491 <literal>?</literal> denotes repetition of the previous item zero
3497 <literal>{</><replaceable>m</><literal>}</literal> denotes repetition
3498 of the previous item exactly <replaceable>m</> times.
3503 <literal>{</><replaceable>m</><literal>,}</literal> denotes repetition
3504 of the previous item <replaceable>m</> or more times.
3509 <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</>
3510 denotes repetition of the previous item at least <replaceable>m</> and
3511 not more than <replaceable>n</> times.
3516 Parentheses <literal>()</literal> can be used to group items into
3517 a single logical item.
3522 A bracket expression <literal>[...]</literal> specifies a character
3523 class, just as in POSIX regular expressions.
3528 Notice that the period (<literal>.</>) is not a metacharacter
3529 for <function>SIMILAR TO</>.
3533 As with <function>LIKE</>, a backslash disables the special meaning
3534 of any of these metacharacters; or a different escape character can
3535 be specified with <literal>ESCAPE</>.
3541 'abc' SIMILAR TO 'abc' <lineannotation>true</lineannotation>
3542 'abc' SIMILAR TO 'a' <lineannotation>false</lineannotation>
3543 'abc' SIMILAR TO '%(b|d)%' <lineannotation>true</lineannotation>
3544 'abc' SIMILAR TO '(b|c)%' <lineannotation>false</lineannotation>
3549 The <function>substring</> function with three parameters,
3550 <function>substring(<replaceable>string</replaceable> from
3551 <replaceable>pattern</replaceable> for
3552 <replaceable>escape-character</replaceable>)</function>, provides
3553 extraction of a substring that matches an SQL
3554 regular expression pattern. As with <literal>SIMILAR TO</>, the
3555 specified pattern must match the entire data string, or else the
3556 function fails and returns null. To indicate the part of the
3557 pattern that should be returned on success, the pattern must contain
3558 two occurrences of the escape character followed by a double quote
3559 (<literal>"</>). <!-- " font-lock sanity -->
3560 The text matching the portion of the pattern
3561 between these markers is returned.
3565 Some examples, with <literal>#"</> delimiting the return string:
3567 substring('foobar' from '%#"o_b#"%' for '#') <lineannotation>oob</lineannotation>
3568 substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotation>
3573 <sect2 id="functions-posix-regexp">
3574 <title><acronym>POSIX</acronym> Regular Expressions</title>
3576 <indexterm zone="functions-posix-regexp">
3577 <primary>regular expression</primary>
3578 <seealso>pattern matching</seealso>
3581 <primary>substring</primary>
3584 <primary>regexp_replace</primary>
3587 <primary>regexp_matches</primary>
3590 <primary>regexp_split_to_table</primary>
3593 <primary>regexp_split_to_array</primary>
3597 <xref linkend="functions-posix-table"> lists the available
3598 operators for pattern matching using POSIX regular expressions.
3601 <table id="functions-posix-table">
3602 <title>Regular Expression Match Operators</title>
3607 <entry>Operator</entry>
3608 <entry>Description</entry>
3609 <entry>Example</entry>
3615 <entry> <literal>~</literal> </entry>
3616 <entry>Matches regular expression, case sensitive</entry>
3617 <entry><literal>'thomas' ~ '.*thomas.*'</literal></entry>
3621 <entry> <literal>~*</literal> </entry>
3622 <entry>Matches regular expression, case insensitive</entry>
3623 <entry><literal>'thomas' ~* '.*Thomas.*'</literal></entry>
3627 <entry> <literal>!~</literal> </entry>
3628 <entry>Does not match regular expression, case sensitive</entry>
3629 <entry><literal>'thomas' !~ '.*Thomas.*'</literal></entry>
3633 <entry> <literal>!~*</literal> </entry>
3634 <entry>Does not match regular expression, case insensitive</entry>
3635 <entry><literal>'thomas' !~* '.*vadim.*'</literal></entry>
3642 <acronym>POSIX</acronym> regular expressions provide a more
3643 powerful means for pattern matching than the <function>LIKE</function> and
3644 <function>SIMILAR TO</> operators.
3645 Many Unix tools such as <command>egrep</command>,
3646 <command>sed</command>, or <command>awk</command> use a pattern
3647 matching language that is similar to the one described here.
3651 A regular expression is a character sequence that is an
3652 abbreviated definition of a set of strings (a <firstterm>regular
3653 set</firstterm>). A string is said to match a regular expression
3654 if it is a member of the regular set described by the regular
3655 expression. As with <function>LIKE</function>, pattern characters
3656 match string characters exactly unless they are special characters
3657 in the regular expression language — but regular expressions use
3658 different special characters than <function>LIKE</function> does.
3659 Unlike <function>LIKE</function> patterns, a
3660 regular expression is allowed to match anywhere within a string, unless
3661 the regular expression is explicitly anchored to the beginning or
3668 'abc' ~ 'abc' <lineannotation>true</lineannotation>
3669 'abc' ~ '^a' <lineannotation>true</lineannotation>
3670 'abc' ~ '(b|d)' <lineannotation>true</lineannotation>
3671 'abc' ~ '^(b|c)' <lineannotation>false</lineannotation>
3676 The <acronym>POSIX</acronym> pattern language is described in much
3677 greater detail below.
3681 The <function>substring</> function with two parameters,
3682 <function>substring(<replaceable>string</replaceable> from
3683 <replaceable>pattern</replaceable>)</function>, provides extraction of a
3685 that matches a POSIX regular expression pattern. It returns null if
3686 there is no match, otherwise the portion of the text that matched the
3687 pattern. But if the pattern contains any parentheses, the portion
3688 of the text that matched the first parenthesized subexpression (the
3689 one whose left parenthesis comes first) is
3690 returned. You can put parentheses around the whole expression
3691 if you want to use parentheses within it without triggering this
3692 exception. If you need parentheses in the pattern before the
3693 subexpression you want to extract, see the non-capturing parentheses
3700 substring('foobar' from 'o.b') <lineannotation>oob</lineannotation>
3701 substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
3706 The <function>regexp_replace</> function provides substitution of
3707 new text for substrings that match POSIX regular expression patterns.
3709 <function>regexp_replace</function>(<replaceable>source</>,
3710 <replaceable>pattern</>, <replaceable>replacement</>
3711 <optional>, <replaceable>flags</> </optional>).
3712 The <replaceable>source</> string is returned unchanged if
3713 there is no match to the <replaceable>pattern</>. If there is a
3714 match, the <replaceable>source</> string is returned with the
3715 <replaceable>replacement</> string substituted for the matching
3716 substring. The <replaceable>replacement</> string can contain
3717 <literal>\</><replaceable>n</>, where <replaceable>n</> is 1
3718 through 9, to indicate that the source substring matching the
3719 <replaceable>n</>'th parenthesized subexpression of the pattern should be
3720 inserted, and it can contain <literal>\&</> to indicate that the
3721 substring matching the entire pattern should be inserted. Write
3722 <literal>\\</> if you need to put a literal backslash in the replacement
3723 text. (As always, remember to double backslashes written in literal
3724 constant strings, assuming escape string syntax is used.)
3725 The <replaceable>flags</> parameter is an optional text
3726 string containing zero or more single-letter flags that change the
3727 function's behavior. Flag <literal>i</> specifies case-insensitive
3728 matching, while flag <literal>g</> specifies replacement of each matching
3729 substring rather than only the first one. Other supported flags are
3730 described in <xref linkend="posix-embedded-options-table">.
3736 regexp_replace('foobarbaz', 'b..', 'X')
3737 <lineannotation>fooXbaz</lineannotation>
3738 regexp_replace('foobarbaz', 'b..', 'X', 'g')
3739 <lineannotation>fooXX</lineannotation>
3740 regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
3741 <lineannotation>fooXarYXazY</lineannotation>
3746 The <function>regexp_matches</> function returns a text array of
3747 all of the captured substrings resulting from matching a POSIX
3748 regular expression pattern. It has the syntax
3749 <function>regexp_matches</function>(<replaceable>string</>, <replaceable>pattern</>
3750 <optional>, <replaceable>flags</> </optional>).
3751 The function can return no rows, one row, or multiple rows (see
3752 the <literal>g</> flag below). If the <replaceable>pattern</>
3753 does not match, the function returns no rows. If the pattern
3754 contains no parenthesized subexpressions, then each row
3755 returned is a single-element text array containing the substring
3756 matching the whole pattern. If the pattern contains parenthesized
3757 subexpressions, the function returns a text array whose
3758 <replaceable>n</>'th element is the substring matching the
3759 <replaceable>n</>'th parenthesized subexpression of the pattern
3760 (not counting <quote>non-capturing</> parentheses; see below for
3762 The <replaceable>flags</> parameter is an optional text
3763 string containing zero or more single-letter flags that change the
3764 function's behavior. Flag <literal>g</> causes the function to find
3765 each match in the string, not only the first one, and return a row for
3766 each such match. Other supported
3767 flags are described in <xref linkend="posix-embedded-options-table">.
3773 SELECT regexp_matches('foobarbequebaz', '(bar)(beque)');
3779 SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
3786 SELECT regexp_matches('foobarbequebaz', 'barbeque');
3795 It is possible to force <function>regexp_matches()</> to always
3796 return one row by using a sub-select; this is particularly useful
3797 in a <literal>SELECT</> target list when you want all rows
3798 returned, even non-matching ones:
3800 SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
3805 The <function>regexp_split_to_table</> function splits a string using a POSIX
3806 regular expression pattern as a delimiter. It has the syntax
3807 <function>regexp_split_to_table</function>(<replaceable>string</>, <replaceable>pattern</>
3808 <optional>, <replaceable>flags</> </optional>).
3809 If there is no match to the <replaceable>pattern</>, the function returns the
3810 <replaceable>string</>. If there is at least one match, for each match it returns
3811 the text from the end of the last match (or the beginning of the string)
3812 to the beginning of the match. When there are no more matches, it
3813 returns the text from the end of the last match to the end of the string.
3814 The <replaceable>flags</> parameter is an optional text string containing
3815 zero or more single-letter flags that change the function's behavior.
3816 <function>regexp_split_to_table</function> supports the flags described in
3817 <xref linkend="posix-embedded-options-table">.
3821 The <function>regexp_split_to_array</> function behaves the same as
3822 <function>regexp_split_to_table</>, except that <function>regexp_split_to_array</>
3823 returns its result as an array of <type>text</>. It has the syntax
3824 <function>regexp_split_to_array</function>(<replaceable>string</>, <replaceable>pattern</>
3825 <optional>, <replaceable>flags</> </optional>).
3826 The parameters are the same as for <function>regexp_split_to_table</>.
3833 SELECT foo FROM regexp_split_to_table('the quick brown fox jumped over the lazy dog', E'\\s+') AS foo;
3847 SELECT regexp_split_to_array('the quick brown fox jumped over the lazy dog', E'\\s+');
3848 regexp_split_to_array
3849 ------------------------------------------------
3850 {the,quick,brown,fox,jumped,over,the,lazy,dog}
3853 SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
3877 As the last example demonstrates, the regexp split functions ignore
3878 zero-length matches that occur at the start or end of the string
3879 or immediately after a previous match. This is contrary to the strict
3880 definition of regexp matching that is implemented by
3881 <function>regexp_matches</>, but is usually the most convenient behavior
3882 in practice. Other software systems such as Perl use similar definitions.
3885 <!-- derived from the re_syntax.n man page -->
3887 <sect3 id="posix-syntax-details">
3888 <title>Regular Expression Details</title>
3891 <productname>PostgreSQL</productname>'s regular expressions are implemented
3892 using a software package written by Henry Spencer. Much of
3893 the description of regular expressions below is copied verbatim from his
3898 Regular expressions (<acronym>RE</acronym>s), as defined in
3899 <acronym>POSIX</acronym> 1003.2, come in two forms:
3900 <firstterm>extended</> <acronym>RE</acronym>s or <acronym>ERE</>s
3901 (roughly those of <command>egrep</command>), and
3902 <firstterm>basic</> <acronym>RE</acronym>s or <acronym>BRE</>s
3903 (roughly those of <command>ed</command>).
3904 <productname>PostgreSQL</productname> supports both forms, and
3905 also implements some extensions
3906 that are not in the POSIX standard, but have become widely used
3907 due to their availability in programming languages such as Perl and Tcl.
3908 <acronym>RE</acronym>s using these non-POSIX extensions are called
3909 <firstterm>advanced</> <acronym>RE</acronym>s or <acronym>ARE</>s
3910 in this documentation. AREs are almost an exact superset of EREs,
3911 but BREs have several notational incompatibilities (as well as being
3913 We first describe the ARE and ERE forms, noting features that apply
3914 only to AREs, and then describe how BREs differ.
3919 <productname>PostgreSQL</> always initially presumes that a regular
3920 expression follows the ARE rules. However, the more limited ERE or
3921 BRE rules can be chosen by prepending an <firstterm>embedded option</>
3922 to the RE pattern, as described in <xref linkend="posix-metasyntax">.
3923 This can be useful for compatibility with applications that expect
3924 exactly the <acronym>POSIX</acronym> 1003.2 rules.
3929 A regular expression is defined as one or more
3930 <firstterm>branches</firstterm>, separated by
3931 <literal>|</literal>. It matches anything that matches one of the
3936 A branch is zero or more <firstterm>quantified atoms</> or
3937 <firstterm>constraints</>, concatenated.
3938 It matches a match for the first, followed by a match for the second, etc;
3939 an empty branch matches the empty string.
3943 A quantified atom is an <firstterm>atom</> possibly followed
3944 by a single <firstterm>quantifier</>.
3945 Without a quantifier, it matches a match for the atom.
3946 With a quantifier, it can match some number of matches of the atom.
3947 An <firstterm>atom</firstterm> can be any of the possibilities
3948 shown in <xref linkend="posix-atoms-table">.
3949 The possible quantifiers and their meanings are shown in
3950 <xref linkend="posix-quantifiers-table">.
3954 A <firstterm>constraint</> matches an empty string, but matches only when
3955 specific conditions are met. A constraint can be used where an atom
3956 could be used, except it cannot be followed by a quantifier.
3957 The simple constraints are shown in
3958 <xref linkend="posix-constraints-table">;
3959 some more constraints are described later.
3963 <table id="posix-atoms-table">
3964 <title>Regular Expression Atoms</title>
3970 <entry>Description</entry>
3976 <entry> <literal>(</><replaceable>re</><literal>)</> </entry>
3977 <entry> (where <replaceable>re</> is any regular expression)
3979 <replaceable>re</>, with the match noted for possible reporting </entry>
3983 <entry> <literal>(?:</><replaceable>re</><literal>)</> </entry>
3984 <entry> as above, but the match is not noted for reporting
3985 (a <quote>non-capturing</> set of parentheses)
3986 (AREs only) </entry>
3990 <entry> <literal>.</> </entry>
3991 <entry> matches any single character </entry>
3995 <entry> <literal>[</><replaceable>chars</><literal>]</> </entry>
3996 <entry> a <firstterm>bracket expression</>,
3997 matching any one of the <replaceable>chars</> (see
3998 <xref linkend="posix-bracket-expressions"> for more detail) </entry>
4002 <entry> <literal>\</><replaceable>k</> </entry>
4003 <entry> (where <replaceable>k</> is a non-alphanumeric character)
4004 matches that character taken as an ordinary character,
4005 e.g., <literal>\\</> matches a backslash character </entry>
4009 <entry> <literal>\</><replaceable>c</> </entry>
4010 <entry> where <replaceable>c</> is alphanumeric
4011 (possibly followed by other characters)
4012 is an <firstterm>escape</>, see <xref linkend="posix-escape-sequences">
4013 (AREs only; in EREs and BREs, this matches <replaceable>c</>) </entry>
4017 <entry> <literal>{</> </entry>
4018 <entry> when followed by a character other than a digit,
4019 matches the left-brace character <literal>{</>;
4020 when followed by a digit, it is the beginning of a
4021 <replaceable>bound</> (see below) </entry>
4025 <entry> <replaceable>x</> </entry>
4026 <entry> where <replaceable>x</> is a single character with no other
4027 significance, matches that character </entry>
4034 An RE cannot end with <literal>\</>.
4039 Remember that the backslash (<literal>\</literal>) already has a special
4040 meaning in <productname>PostgreSQL</> string literals.
4041 To write a pattern constant that contains a backslash,
4042 you must write two backslashes in the statement, assuming escape
4043 string syntax is used (see <xref linkend="sql-syntax-strings">).
4047 <table id="posix-quantifiers-table">
4048 <title>Regular Expression Quantifiers</title>
4053 <entry>Quantifier</entry>
4054 <entry>Matches</entry>
4060 <entry> <literal>*</> </entry>
4061 <entry> a sequence of 0 or more matches of the atom </entry>
4065 <entry> <literal>+</> </entry>
4066 <entry> a sequence of 1 or more matches of the atom </entry>
4070 <entry> <literal>?</> </entry>
4071 <entry> a sequence of 0 or 1 matches of the atom </entry>
4075 <entry> <literal>{</><replaceable>m</><literal>}</> </entry>
4076 <entry> a sequence of exactly <replaceable>m</> matches of the atom </entry>
4080 <entry> <literal>{</><replaceable>m</><literal>,}</> </entry>
4081 <entry> a sequence of <replaceable>m</> or more matches of the atom </entry>
4086 <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</> </entry>
4087 <entry> a sequence of <replaceable>m</> through <replaceable>n</>
4088 (inclusive) matches of the atom; <replaceable>m</> cannot exceed
4089 <replaceable>n</> </entry>
4093 <entry> <literal>*?</> </entry>
4094 <entry> non-greedy version of <literal>*</> </entry>
4098 <entry> <literal>+?</> </entry>
4099 <entry> non-greedy version of <literal>+</> </entry>
4103 <entry> <literal>??</> </entry>
4104 <entry> non-greedy version of <literal>?</> </entry>
4108 <entry> <literal>{</><replaceable>m</><literal>}?</> </entry>
4109 <entry> non-greedy version of <literal>{</><replaceable>m</><literal>}</> </entry>
4113 <entry> <literal>{</><replaceable>m</><literal>,}?</> </entry>
4114 <entry> non-greedy version of <literal>{</><replaceable>m</><literal>,}</> </entry>
4119 <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}?</> </entry>
4120 <entry> non-greedy version of <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</> </entry>
4127 The forms using <literal>{</><replaceable>...</><literal>}</>
4128 are known as <firstterm>bounds</>.
4129 The numbers <replaceable>m</> and <replaceable>n</> within a bound are
4130 unsigned decimal integers with permissible values from 0 to 255 inclusive.
4134 <firstterm>Non-greedy</> quantifiers (available in AREs only) match the
4135 same possibilities as their corresponding normal (<firstterm>greedy</>)
4136 counterparts, but prefer the smallest number rather than the largest
4138 See <xref linkend="posix-matching-rules"> for more detail.
4143 A quantifier cannot immediately follow another quantifier, e.g.,
4144 <literal>**</> is invalid.
4146 begin an expression or subexpression or follow
4147 <literal>^</literal> or <literal>|</literal>.
4151 <table id="posix-constraints-table">
4152 <title>Regular Expression Constraints</title>
4157 <entry>Constraint</entry>
4158 <entry>Description</entry>
4164 <entry> <literal>^</> </entry>
4165 <entry> matches at the beginning of the string </entry>
4169 <entry> <literal>$</> </entry>
4170 <entry> matches at the end of the string </entry>
4174 <entry> <literal>(?=</><replaceable>re</><literal>)</> </entry>
4175 <entry> <firstterm>positive lookahead</> matches at any point
4176 where a substring matching <replaceable>re</> begins
4177 (AREs only) </entry>
4181 <entry> <literal>(?!</><replaceable>re</><literal>)</> </entry>
4182 <entry> <firstterm>negative lookahead</> matches at any point
4183 where no substring matching <replaceable>re</> begins
4184 (AREs only) </entry>
4191 Lookahead constraints cannot contain <firstterm>back references</>
4192 (see <xref linkend="posix-escape-sequences">),
4193 and all parentheses within them are considered non-capturing.
4197 <sect3 id="posix-bracket-expressions">
4198 <title>Bracket Expressions</title>
4201 A <firstterm>bracket expression</firstterm> is a list of
4202 characters enclosed in <literal>[]</literal>. It normally matches
4203 any single character from the list (but see below). If the list
4204 begins with <literal>^</literal>, it matches any single character
4205 <emphasis>not</> from the rest of the list.
4207 in the list are separated by <literal>-</literal>, this is
4208 shorthand for the full range of characters between those two
4209 (inclusive) in the collating sequence,
4210 e.g., <literal>[0-9]</literal> in <acronym>ASCII</acronym> matches
4211 any decimal digit. It is illegal for two ranges to share an
4212 endpoint, e.g., <literal>a-c-e</literal>. Ranges are very
4213 collating-sequence-dependent, so portable programs should avoid
4218 To include a literal <literal>]</literal> in the list, make it the
4219 first character (after <literal>^</literal>, if that is used). To
4220 include a literal <literal>-</literal>, make it the first or last
4221 character, or the second endpoint of a range. To use a literal
4222 <literal>-</literal> as the first endpoint of a range, enclose it
4223 in <literal>[.</literal> and <literal>.]</literal> to make it a
4224 collating element (see below). With the exception of these characters,
4225 some combinations using <literal>[</literal>
4226 (see next paragraphs), and escapes (AREs only), all other special
4227 characters lose their special significance within a bracket expression.
4228 In particular, <literal>\</literal> is not special when following
4229 ERE or BRE rules, though it is special (as introducing an escape)
4234 Within a bracket expression, a collating element (a character, a
4235 multiple-character sequence that collates as if it were a single
4236 character, or a collating-sequence name for either) enclosed in
4237 <literal>[.</literal> and <literal>.]</literal> stands for the
4238 sequence of characters of that collating element. The sequence is
4239 treated as a single element of the bracket expression's list. This
4241 expression containing a multiple-character collating element to
4242 match more than one character, e.g., if the collating sequence
4243 includes a <literal>ch</literal> collating element, then the RE
4244 <literal>[[.ch.]]*c</literal> matches the first five characters of
4245 <literal>chchcc</literal>.
4250 <productname>PostgreSQL</> currently does not support multi-character collating
4251 elements. This information describes possible future behavior.
4256 Within a bracket expression, a collating element enclosed in
4257 <literal>[=</literal> and <literal>=]</literal> is an <firstterm>equivalence
4258 class</>, standing for the sequences of characters of all collating
4259 elements equivalent to that one, including itself. (If there are
4260 no other equivalent collating elements, the treatment is as if the
4261 enclosing delimiters were <literal>[.</literal> and
4262 <literal>.]</literal>.) For example, if <literal>o</literal> and
4263 <literal>^</literal> are the members of an equivalence class, then
4264 <literal>[[=o=]]</literal>, <literal>[[=^=]]</literal>, and
4265 <literal>[o^]</literal> are all synonymous. An equivalence class
4266 cannot be an endpoint of a range.
4270 Within a bracket expression, the name of a character class
4271 enclosed in <literal>[:</literal> and <literal>:]</literal> stands
4272 for the list of all characters belonging to that class. Standard
4273 character class names are: <literal>alnum</literal>,
4274 <literal>alpha</literal>, <literal>blank</literal>,
4275 <literal>cntrl</literal>, <literal>digit</literal>,
4276 <literal>graph</literal>, <literal>lower</literal>,
4277 <literal>print</literal>, <literal>punct</literal>,
4278 <literal>space</literal>, <literal>upper</literal>,
4279 <literal>xdigit</literal>. These stand for the character classes
4281 <citerefentry><refentrytitle>ctype</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
4282 A locale can provide others. A character class cannot be used as
4283 an endpoint of a range.
4287 There are two special cases of bracket expressions: the bracket
4288 expressions <literal>[[:<:]]</literal> and
4289 <literal>[[:>:]]</literal> are constraints,
4290 matching empty strings at the beginning
4291 and end of a word respectively. A word is defined as a sequence
4292 of word characters that is neither preceded nor followed by word
4293 characters. A word character is an <literal>alnum</> character (as
4295 <citerefentry><refentrytitle>ctype</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
4296 or an underscore. This is an extension, compatible with but not
4297 specified by <acronym>POSIX</acronym> 1003.2, and should be used with
4298 caution in software intended to be portable to other systems.
4299 The constraint escapes described below are usually preferable; they
4300 are no more standard, but are easier to type.
4304 <sect3 id="posix-escape-sequences">
4305 <title>Regular Expression Escapes</title>
4308 <firstterm>Escapes</> are special sequences beginning with <literal>\</>
4309 followed by an alphanumeric character. Escapes come in several varieties:
4310 character entry, class shorthands, constraint escapes, and back references.
4311 A <literal>\</> followed by an alphanumeric character but not constituting
4312 a valid escape is illegal in AREs.
4313 In EREs, there are no escapes: outside a bracket expression,
4314 a <literal>\</> followed by an alphanumeric character merely stands for
4315 that character as an ordinary character, and inside a bracket expression,
4316 <literal>\</> is an ordinary character.
4317 (The latter is the one actual incompatibility between EREs and AREs.)
4321 <firstterm>Character-entry escapes</> exist to make it easier to specify
4322 non-printing and other inconvenient characters in REs. They are
4323 shown in <xref linkend="posix-character-entry-escapes-table">.
4327 <firstterm>Class-shorthand escapes</> provide shorthands for certain
4328 commonly-used character classes. They are
4329 shown in <xref linkend="posix-class-shorthand-escapes-table">.
4333 A <firstterm>constraint escape</> is a constraint,
4334 matching the empty string if specific conditions are met,
4335 written as an escape. They are
4336 shown in <xref linkend="posix-constraint-escapes-table">.
4340 A <firstterm>back reference</> (<literal>\</><replaceable>n</>) matches the
4341 same string matched by the previous parenthesized subexpression specified
4342 by the number <replaceable>n</>
4343 (see <xref linkend="posix-constraint-backref-table">). For example,
4344 <literal>([bc])\1</> matches <literal>bb</> or <literal>cc</>
4345 but not <literal>bc</> or <literal>cb</>.
4346 The subexpression must entirely precede the back reference in the RE.
4347 Subexpressions are numbered in the order of their leading parentheses.
4348 Non-capturing parentheses do not define subexpressions.
4353 Keep in mind that an escape's leading <literal>\</> will need to be
4354 doubled when entering the pattern as an SQL string constant. For example:
4356 '123' ~ E'^\\d{3}' <lineannotation>true</lineannotation>
4361 <table id="posix-character-entry-escapes-table">
4362 <title>Regular Expression Character-entry Escapes</title>
4367 <entry>Escape</entry>
4368 <entry>Description</entry>
4374 <entry> <literal>\a</> </entry>
4375 <entry> alert (bell) character, as in C </entry>
4379 <entry> <literal>\b</> </entry>
4380 <entry> backspace, as in C </entry>
4384 <entry> <literal>\B</> </entry>
4385 <entry> synonym for backslash (<literal>\</>) to help reduce the need for backslash
4390 <entry> <literal>\c</><replaceable>X</> </entry>
4391 <entry> (where <replaceable>X</> is any character) the character whose
4392 low-order 5 bits are the same as those of
4393 <replaceable>X</>, and whose other bits are all zero </entry>
4397 <entry> <literal>\e</> </entry>
4398 <entry> the character whose collating-sequence name
4400 or failing that, the character with octal value 033 </entry>
4404 <entry> <literal>\f</> </entry>
4405 <entry> form feed, as in C </entry>
4409 <entry> <literal>\n</> </entry>
4410 <entry> newline, as in C </entry>
4414 <entry> <literal>\r</> </entry>
4415 <entry> carriage return, as in C </entry>
4419 <entry> <literal>\t</> </entry>
4420 <entry> horizontal tab, as in C </entry>
4424 <entry> <literal>\u</><replaceable>wxyz</> </entry>
4425 <entry> (where <replaceable>wxyz</> is exactly four hexadecimal digits)
4426 the UTF16 (Unicode, 16-bit) character <literal>U+</><replaceable>wxyz</>
4427 in the local byte ordering </entry>
4431 <entry> <literal>\U</><replaceable>stuvwxyz</> </entry>
4432 <entry> (where <replaceable>stuvwxyz</> is exactly eight hexadecimal
4434 reserved for a hypothetical Unicode extension to 32 bits
4439 <entry> <literal>\v</> </entry>
4440 <entry> vertical tab, as in C </entry>
4444 <entry> <literal>\x</><replaceable>hhh</> </entry>
4445 <entry> (where <replaceable>hhh</> is any sequence of hexadecimal
4447 the character whose hexadecimal value is
4448 <literal>0x</><replaceable>hhh</>
4449 (a single character no matter how many hexadecimal digits are used)
4454 <entry> <literal>\0</> </entry>
4455 <entry> the character whose value is <literal>0</> (the null byte)</entry>
4459 <entry> <literal>\</><replaceable>xy</> </entry>
4460 <entry> (where <replaceable>xy</> is exactly two octal digits,
4461 and is not a <firstterm>back reference</>)
4462 the character whose octal value is
4463 <literal>0</><replaceable>xy</> </entry>
4467 <entry> <literal>\</><replaceable>xyz</> </entry>
4468 <entry> (where <replaceable>xyz</> is exactly three octal digits,
4469 and is not a <firstterm>back reference</>)
4470 the character whose octal value is
4471 <literal>0</><replaceable>xyz</> </entry>
4478 Hexadecimal digits are <literal>0</>-<literal>9</>,
4479 <literal>a</>-<literal>f</>, and <literal>A</>-<literal>F</>.
4480 Octal digits are <literal>0</>-<literal>7</>.
4484 The character-entry escapes are always taken as ordinary characters.
4485 For example, <literal>\135</> is <literal>]</> in ASCII, but
4486 <literal>\135</> does not terminate a bracket expression.
4489 <table id="posix-class-shorthand-escapes-table">
4490 <title>Regular Expression Class-shorthand Escapes</title>
4495 <entry>Escape</entry>
4496 <entry>Description</entry>
4502 <entry> <literal>\d</> </entry>
4503 <entry> <literal>[[:digit:]]</> </entry>
4507 <entry> <literal>\s</> </entry>
4508 <entry> <literal>[[:space:]]</> </entry>
4512 <entry> <literal>\w</> </entry>
4513 <entry> <literal>[[:alnum:]_]</>
4514 (note underscore is included) </entry>
4518 <entry> <literal>\D</> </entry>
4519 <entry> <literal>[^[:digit:]]</> </entry>
4523 <entry> <literal>\S</> </entry>
4524 <entry> <literal>[^[:space:]]</> </entry>
4528 <entry> <literal>\W</> </entry>
4529 <entry> <literal>[^[:alnum:]_]</>
4530 (note underscore is included) </entry>
4537 Within bracket expressions, <literal>\d</>, <literal>\s</>,
4538 and <literal>\w</> lose their outer brackets,
4539 and <literal>\D</>, <literal>\S</>, and <literal>\W</> are illegal.
4540 (So, for example, <literal>[a-c\d]</> is equivalent to
4541 <literal>[a-c[:digit:]]</>.
4542 Also, <literal>[a-c\D]</>, which is equivalent to
4543 <literal>[a-c^[:digit:]]</>, is illegal.)
4546 <table id="posix-constraint-escapes-table">
4547 <title>Regular Expression Constraint Escapes</title>
4552 <entry>Escape</entry>
4553 <entry>Description</entry>
4559 <entry> <literal>\A</> </entry>
4560 <entry> matches only at the beginning of the string
4561 (see <xref linkend="posix-matching-rules"> for how this differs from
4562 <literal>^</>) </entry>
4566 <entry> <literal>\m</> </entry>
4567 <entry> matches only at the beginning of a word </entry>
4571 <entry> <literal>\M</> </entry>
4572 <entry> matches only at the end of a word </entry>
4576 <entry> <literal>\y</> </entry>
4577 <entry> matches only at the beginning or end of a word </entry>
4581 <entry> <literal>\Y</> </entry>
4582 <entry> matches only at a point that is not the beginning or end of a
4587 <entry> <literal>\Z</> </entry>
4588 <entry> matches only at the end of the string
4589 (see <xref linkend="posix-matching-rules"> for how this differs from
4590 <literal>$</>) </entry>
4597 A word is defined as in the specification of
4598 <literal>[[:<:]]</> and <literal>[[:>:]]</> above.
4599 Constraint escapes are illegal within bracket expressions.
4602 <table id="posix-constraint-backref-table">
4603 <title>Regular Expression Back References</title>
4608 <entry>Escape</entry>
4609 <entry>Description</entry>
4615 <entry> <literal>\</><replaceable>m</> </entry>
4616 <entry> (where <replaceable>m</> is a nonzero digit)
4617 a back reference to the <replaceable>m</>'th subexpression </entry>
4621 <entry> <literal>\</><replaceable>mnn</> </entry>
4622 <entry> (where <replaceable>m</> is a nonzero digit, and
4623 <replaceable>nn</> is some more digits, and the decimal value
4624 <replaceable>mnn</> is not greater than the number of closing capturing
4625 parentheses seen so far)
4626 a back reference to the <replaceable>mnn</>'th subexpression </entry>
4634 There is an inherent ambiguity between octal character-entry
4635 escapes and back references, which is resolved by the following heuristics,
4637 A leading zero always indicates an octal escape.
4638 A single non-zero digit, not followed by another digit,
4639 is always taken as a back reference.
4640 A multi-digit sequence not starting with a zero is taken as a back
4641 reference if it comes after a suitable subexpression
4642 (i.e., the number is in the legal range for a back reference),
4643 and otherwise is taken as octal.
4648 <sect3 id="posix-metasyntax">
4649 <title>Regular Expression Metasyntax</title>
4652 In addition to the main syntax described above, there are some special
4653 forms and miscellaneous syntactic facilities available.
4657 An RE can begin with one of two special <firstterm>director</> prefixes.
4658 If an RE begins with <literal>***:</>,
4659 the rest of the RE is taken as an ARE. (This normally has no effect in
4660 <productname>PostgreSQL</>, since REs are assumed to be AREs;
4661 but it does have an effect if ERE or BRE mode had been specified by
4662 the <replaceable>flags</> parameter to a regex function.)
4663 If an RE begins with <literal>***=</>,
4664 the rest of the RE is taken to be a literal string,
4665 with all characters considered ordinary characters.
4669 An ARE can begin with <firstterm>embedded options</>:
4670 a sequence <literal>(?</><replaceable>xyz</><literal>)</>
4671 (where <replaceable>xyz</> is one or more alphabetic characters)
4672 specifies options affecting the rest of the RE.
4673 These options override any previously determined options —
4674 in particular, they can override the case-sensitivity behavior implied by
4675 a regex operator, or the <replaceable>flags</> parameter to a regex
4677 The available option letters are
4678 shown in <xref linkend="posix-embedded-options-table">.
4679 Note that these same option letters are used in the <replaceable>flags</>
4680 parameters of regex functions.
4683 <table id="posix-embedded-options-table">
4684 <title>ARE Embedded-option Letters</title>
4689 <entry>Option</entry>
4690 <entry>Description</entry>
4696 <entry> <literal>b</> </entry>
4697 <entry> rest of RE is a BRE </entry>
4701 <entry> <literal>c</> </entry>
4702 <entry> case-sensitive matching (overrides operator type) </entry>
4706 <entry> <literal>e</> </entry>
4707 <entry> rest of RE is an ERE </entry>
4711 <entry> <literal>i</> </entry>
4712 <entry> case-insensitive matching (see
4713 <xref linkend="posix-matching-rules">) (overrides operator type) </entry>
4717 <entry> <literal>m</> </entry>
4718 <entry> historical synonym for <literal>n</> </entry>
4722 <entry> <literal>n</> </entry>
4723 <entry> newline-sensitive matching (see
4724 <xref linkend="posix-matching-rules">) </entry>
4728 <entry> <literal>p</> </entry>
4729 <entry> partial newline-sensitive matching (see
4730 <xref linkend="posix-matching-rules">) </entry>
4734 <entry> <literal>q</> </entry>
4735 <entry> rest of RE is a literal (<quote>quoted</>) string, all ordinary
4740 <entry> <literal>s</> </entry>
4741 <entry> non-newline-sensitive matching (default) </entry>
4745 <entry> <literal>t</> </entry>
4746 <entry> tight syntax (default; see below) </entry>
4750 <entry> <literal>w</> </entry>
4751 <entry> inverse partial newline-sensitive (<quote>weird</>) matching
4752 (see <xref linkend="posix-matching-rules">) </entry>
4756 <entry> <literal>x</> </entry>
4757 <entry> expanded syntax (see below) </entry>
4764 Embedded options take effect at the <literal>)</> terminating the sequence.
4765 They can appear only at the start of an ARE (after the
4766 <literal>***:</> director if any).
4770 In addition to the usual (<firstterm>tight</>) RE syntax, in which all
4771 characters are significant, there is an <firstterm>expanded</> syntax,
4772 available by specifying the embedded <literal>x</> option.
4773 In the expanded syntax,
4774 white-space characters in the RE are ignored, as are
4775 all characters between a <literal>#</>
4776 and the following newline (or the end of the RE). This
4777 permits paragraphing and commenting a complex RE.
4778 There are three exceptions to that basic rule:
4783 a white-space character or <literal>#</> preceded by <literal>\</> is
4789 white space or <literal>#</> within a bracket expression is retained
4794 white space and comments cannot appear within multi-character symbols,
4795 such as <literal>(?:</>
4800 For this purpose, white-space characters are blank, tab, newline, and
4801 any character that belongs to the <replaceable>space</> character class.
4805 Finally, in an ARE, outside bracket expressions, the sequence
4806 <literal>(?#</><replaceable>ttt</><literal>)</>
4807 (where <replaceable>ttt</> is any text not containing a <literal>)</>)
4808 is a comment, completely ignored.
4809 Again, this is not allowed between the characters of
4810 multi-character symbols, like <literal>(?:</>.
4811 Such comments are more a historical artifact than a useful facility,
4812 and their use is deprecated; use the expanded syntax instead.
4816 <emphasis>None</> of these metasyntax extensions is available if
4817 an initial <literal>***=</> director
4818 has specified that the user's input be treated as a literal string
4819 rather than as an RE.
4823 <sect3 id="posix-matching-rules">
4824 <title>Regular Expression Matching Rules</title>
4827 In the event that an RE could match more than one substring of a given
4828 string, the RE matches the one starting earliest in the string.
4829 If the RE could match more than one substring starting at that point,
4830 either the longest possible match or the shortest possible match will
4831 be taken, depending on whether the RE is <firstterm>greedy</> or
4832 <firstterm>non-greedy</>.
4836 Whether an RE is greedy or not is determined by the following rules:
4840 Most atoms, and all constraints, have no greediness attribute (because
4841 they cannot match variable amounts of text anyway).
4846 Adding parentheses around an RE does not change its greediness.
4851 A quantified atom with a fixed-repetition quantifier
4852 (<literal>{</><replaceable>m</><literal>}</>
4854 <literal>{</><replaceable>m</><literal>}?</>)
4855 has the same greediness (possibly none) as the atom itself.
4860 A quantified atom with other normal quantifiers (including
4861 <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</>
4862 with <replaceable>m</> equal to <replaceable>n</>)
4863 is greedy (prefers longest match).
4868 A quantified atom with a non-greedy quantifier (including
4869 <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}?</>
4870 with <replaceable>m</> equal to <replaceable>n</>)
4871 is non-greedy (prefers shortest match).
4876 A branch — that is, an RE that has no top-level
4877 <literal>|</> operator — has the same greediness as the first
4878 quantified atom in it that has a greediness attribute.
4883 An RE consisting of two or more branches connected by the
4884 <literal>|</> operator is always greedy.
4891 The above rules associate greediness attributes not only with individual
4892 quantified atoms, but with branches and entire REs that contain quantified
4893 atoms. What that means is that the matching is done in such a way that
4894 the branch, or whole RE, matches the longest or shortest possible
4895 substring <emphasis>as a whole</>. Once the length of the entire match
4896 is determined, the part of it that matches any particular subexpression
4897 is determined on the basis of the greediness attribute of that
4898 subexpression, with subexpressions starting earlier in the RE taking
4899 priority over ones starting later.
4903 An example of what this means:
4905 SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
4906 <lineannotation>Result: </lineannotation><computeroutput>123</computeroutput>
4907 SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
4908 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
4910 In the first case, the RE as a whole is greedy because <literal>Y*</>
4911 is greedy. It can match beginning at the <literal>Y</>, and it matches
4912 the longest possible string starting there, i.e., <literal>Y123</>.
4913 The output is the parenthesized part of that, or <literal>123</>.
4914 In the second case, the RE as a whole is non-greedy because <literal>Y*?</>
4915 is non-greedy. It can match beginning at the <literal>Y</>, and it matches
4916 the shortest possible string starting there, i.e., <literal>Y1</>.
4917 The subexpression <literal>[0-9]{1,3}</> is greedy but it cannot change
4918 the decision as to the overall match length; so it is forced to match
4923 In short, when an RE contains both greedy and non-greedy subexpressions,
4924 the total match length is either as long as possible or as short as
4925 possible, according to the attribute assigned to the whole RE. The
4926 attributes assigned to the subexpressions only affect how much of that
4927 match they are allowed to <quote>eat</> relative to each other.
4931 The quantifiers <literal>{1,1}</> and <literal>{1,1}?</>
4932 can be used to force greediness or non-greediness, respectively,
4933 on a subexpression or a whole RE.
4937 Match lengths are measured in characters, not collating elements.
4938 An empty string is considered longer than no match at all.
4941 matches the three middle characters of <literal>abbbc</>;
4942 <literal>(week|wee)(night|knights)</>
4943 matches all ten characters of <literal>weeknights</>;
4944 when <literal>(.*).*</>
4945 is matched against <literal>abc</> the parenthesized subexpression
4946 matches all three characters; and when
4947 <literal>(a*)*</> is matched against <literal>bc</>
4948 both the whole RE and the parenthesized
4949 subexpression match an empty string.
4953 If case-independent matching is specified,
4954 the effect is much as if all case distinctions had vanished from the
4956 When an alphabetic that exists in multiple cases appears as an
4957 ordinary character outside a bracket expression, it is effectively
4958 transformed into a bracket expression containing both cases,
4959 e.g., <literal>x</> becomes <literal>[xX]</>.
4960 When it appears inside a bracket expression, all case counterparts
4961 of it are added to the bracket expression, e.g.,
4962 <literal>[x]</> becomes <literal>[xX]</>
4963 and <literal>[^x]</> becomes <literal>[^xX]</>.
4967 If newline-sensitive matching is specified, <literal>.</>
4968 and bracket expressions using <literal>^</>
4969 will never match the newline character
4970 (so that matches will never cross newlines unless the RE
4971 explicitly arranges it)
4972 and <literal>^</>and <literal>$</>
4973 will match the empty string after and before a newline
4974 respectively, in addition to matching at beginning and end of string
4976 But the ARE escapes <literal>\A</> and <literal>\Z</>
4977 continue to match beginning or end of string <emphasis>only</>.
4981 If partial newline-sensitive matching is specified,
4982 this affects <literal>.</> and bracket expressions
4983 as with newline-sensitive matching, but not <literal>^</>
4988 If inverse partial newline-sensitive matching is specified,
4989 this affects <literal>^</> and <literal>$</>
4990 as with newline-sensitive matching, but not <literal>.</>
4991 and bracket expressions.
4992 This isn't very useful but is provided for symmetry.
4996 <sect3 id="posix-limits-compatibility">
4997 <title>Limits and Compatibility</title>
5000 No particular limit is imposed on the length of REs in this
5001 implementation. However,
5002 programs intended to be highly portable should not employ REs longer
5004 as a POSIX-compliant implementation can refuse to accept such REs.
5008 The only feature of AREs that is actually incompatible with
5009 POSIX EREs is that <literal>\</> does not lose its special
5010 significance inside bracket expressions.
5011 All other ARE features use syntax which is illegal or has
5012 undefined or unspecified effects in POSIX EREs;
5013 the <literal>***</> syntax of directors likewise is outside the POSIX
5014 syntax for both BREs and EREs.
5018 Many of the ARE extensions are borrowed from Perl, but some have
5019 been changed to clean them up, and a few Perl extensions are not present.
5020 Incompatibilities of note include <literal>\b</>, <literal>\B</>,
5021 the lack of special treatment for a trailing newline,
5022 the addition of complemented bracket expressions to the things
5023 affected by newline-sensitive matching,
5024 the restrictions on parentheses and back references in lookahead
5025 constraints, and the longest/shortest-match (rather than first-match)
5030 Two significant incompatibilities exist between AREs and the ERE syntax
5031 recognized by pre-7.4 releases of <productname>PostgreSQL</>:
5036 In AREs, <literal>\</> followed by an alphanumeric character is either
5037 an escape or an error, while in previous releases, it was just another
5038 way of writing the alphanumeric.
5039 This should not be much of a problem because there was no reason to
5040 write such a sequence in earlier releases.
5045 In AREs, <literal>\</> remains a special character within
5046 <literal>[]</>, so a literal <literal>\</> within a bracket
5047 expression must be written <literal>\\</>.
5054 <sect3 id="posix-basic-regexes">
5055 <title>Basic Regular Expressions</title>
5058 BREs differ from EREs in several respects.
5059 In BREs, <literal>|</>, <literal>+</>, and <literal>?</>
5060 are ordinary characters and there is no equivalent
5061 for their functionality.
5062 The delimiters for bounds are
5063 <literal>\{</> and <literal>\}</>,
5064 with <literal>{</> and <literal>}</>
5065 by themselves ordinary characters.
5066 The parentheses for nested subexpressions are
5067 <literal>\(</> and <literal>\)</>,
5068 with <literal>(</> and <literal>)</> by themselves ordinary characters.
5069 <literal>^</> is an ordinary character except at the beginning of the
5070 RE or the beginning of a parenthesized subexpression,
5071 <literal>$</> is an ordinary character except at the end of the
5072 RE or the end of a parenthesized subexpression,
5073 and <literal>*</> is an ordinary character if it appears at the beginning
5074 of the RE or the beginning of a parenthesized subexpression
5075 (after a possible leading <literal>^</>).
5076 Finally, single-digit back references are available, and
5077 <literal>\<</> and <literal>\></>
5079 <literal>[[:<:]]</> and <literal>[[:>:]]</>
5080 respectively; no other escapes are available in BREs.
5084 <!-- end re_syntax.n man page -->
5090 <sect1 id="functions-formatting">
5091 <title>Data Type Formatting Functions</title>
5094 <primary>formatting</primary>
5098 The <productname>PostgreSQL</productname> formatting functions
5099 provide a powerful set of tools for converting various data types
5100 (date/time, integer, floating point, numeric) to formatted strings
5101 and for converting from formatted strings to specific data types.
5102 <xref linkend="functions-formatting-table"> lists them.
5103 These functions all follow a common calling convention: the first
5104 argument is the value to be formatted and the second argument is a
5105 template that defines the output or input format.
5108 A single-argument <function>to_timestamp</function> function is also
5109 available; it accepts a
5110 <type>double precision</type> argument and converts from Unix epoch
5111 (seconds since 1970-01-01 00:00:00+00) to
5112 <type>timestamp with time zone</type>.
5113 (<type>Integer</type> Unix epochs are implicitly cast to
5114 <type>double precision</type>.)
5117 <table id="functions-formatting-table">
5118 <title>Formatting Functions</title>
5122 <entry>Function</entry>
5123 <entry>Return Type</entry>
5124 <entry>Description</entry>
5125 <entry>Example</entry>
5132 <primary>to_char</primary>
5134 <literal><function>to_char(<type>timestamp</type>, <type>text</type>)</function></literal>
5136 <entry><type>text</type></entry>
5137 <entry>convert time stamp to string</entry>
5138 <entry><literal>to_char(current_timestamp, 'HH12:MI:SS')</literal></entry>
5141 <entry><literal><function>to_char(<type>interval</type>, <type>text</type>)</function></literal></entry>
5142 <entry><type>text</type></entry>
5143 <entry>convert interval to string</entry>
5144 <entry><literal>to_char(interval '15h 2m 12s', 'HH24:MI:SS')</literal></entry>
5147 <entry><literal><function>to_char(<type>int</type>, <type>text</type>)</function></literal></entry>
5148 <entry><type>text</type></entry>
5149 <entry>convert integer to string</entry>
5150 <entry><literal>to_char(125, '999')</literal></entry>
5153 <entry><literal><function>to_char</function>(<type>double precision</type>,
5154 <type>text</type>)</literal></entry>
5155 <entry><type>text</type></entry>
5156 <entry>convert real/double precision to string</entry>
5157 <entry><literal>to_char(125.8::real, '999D9')</literal></entry>
5160 <entry><literal><function>to_char(<type>numeric</type>, <type>text</type>)</function></literal></entry>
5161 <entry><type>text</type></entry>
5162 <entry>convert numeric to string</entry>
5163 <entry><literal>to_char(-125.8, '999D99S')</literal></entry>
5168 <primary>to_date</primary>
5170 <literal><function>to_date(<type>text</type>, <type>text</type>)</function></literal>
5172 <entry><type>date</type></entry>
5173 <entry>convert string to date</entry>
5174 <entry><literal>to_date('05 Dec 2000', 'DD Mon YYYY')</literal></entry>
5179 <primary>to_number</primary>
5181 <literal><function>to_number(<type>text</type>, <type>text</type>)</function></literal>
5183 <entry><type>numeric</type></entry>
5184 <entry>convert string to numeric</entry>
5185 <entry><literal>to_number('12,454.8-', '99G999D9S')</literal></entry>
5190 <primary>to_timestamp</primary>
5192 <literal><function>to_timestamp(<type>text</type>, <type>text</type>)</function></literal>
5194 <entry><type>timestamp with time zone</type></entry>
5195 <entry>convert string to time stamp</entry>
5196 <entry><literal>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</literal></entry>
5199 <entry><literal><function>to_timestamp(<type>double precision</type>)</function></literal></entry>
5200 <entry><type>timestamp with time zone</type></entry>
5201 <entry>convert Unix epoch to time stamp</entry>
5202 <entry><literal>to_timestamp(1284352323)</literal></entry>
5209 In a <function>to_char</> output template string, there are certain
5210 patterns that are recognized and replaced with appropriately-formatted
5211 data based on the given value. Any text that is not a template pattern is
5212 simply copied verbatim. Similarly, in an input template string (for the
5213 other functions), template patterns identify the values to be supplied by
5214 the input data string.
5218 <xref linkend="functions-formatting-datetime-table"> shows the
5219 template patterns available for formatting date and time values.
5222 <table id="functions-formatting-datetime-table">
5223 <title>Template Patterns for Date/Time Formatting</title>
5227 <entry>Pattern</entry>
5228 <entry>Description</entry>
5233 <entry><literal>HH</literal></entry>
5234 <entry>hour of day (01-12)</entry>
5237 <entry><literal>HH12</literal></entry>
5238 <entry>hour of day (01-12)</entry>
5241 <entry><literal>HH24</literal></entry>
5242 <entry>hour of day (00-23)</entry>
5245 <entry><literal>MI</literal></entry>
5246 <entry>minute (00-59)</entry>
5249 <entry><literal>SS</literal></entry>
5250 <entry>second (00-59)</entry>
5253 <entry><literal>MS</literal></entry>
5254 <entry>millisecond (000-999)</entry>
5257 <entry><literal>US</literal></entry>
5258 <entry>microsecond (000000-999999)</entry>
5261 <entry><literal>SSSS</literal></entry>
5262 <entry>seconds past midnight (0-86399)</entry>
5265 <entry><literal>AM</literal>, <literal>am</literal>,
5266 <literal>PM</literal> or <literal>pm</literal></entry>
5267 <entry>meridiem indicator (without periods)</entry>
5270 <entry><literal>A.M.</literal>, <literal>a.m.</literal>,
5271 <literal>P.M.</literal> or <literal>p.m.</literal></entry>
5272 <entry>meridiem indicator (with periods)</entry>
5275 <entry><literal>Y,YYY</literal></entry>
5276 <entry>year (4 and more digits) with comma</entry>
5279 <entry><literal>YYYY</literal></entry>
5280 <entry>year (4 and more digits)</entry>
5283 <entry><literal>YYY</literal></entry>
5284 <entry>last 3 digits of year</entry>
5287 <entry><literal>YY</literal></entry>
5288 <entry>last 2 digits of year</entry>
5291 <entry><literal>Y</literal></entry>
5292 <entry>last digit of year</entry>
5295 <entry><literal>IYYY</literal></entry>
5296 <entry>ISO year (4 and more digits)</entry>
5299 <entry><literal>IYY</literal></entry>
5300 <entry>last 3 digits of ISO year</entry>
5303 <entry><literal>IY</literal></entry>
5304 <entry>last 2 digits of ISO year</entry>
5307 <entry><literal>I</literal></entry>
5308 <entry>last digit of ISO year</entry>
5311 <entry><literal>BC</literal>, <literal>bc</literal>,
5312 <literal>AD</literal> or <literal>ad</literal></entry>
5313 <entry>era indicator (without periods)</entry>
5316 <entry><literal>B.C.</literal>, <literal>b.c.</literal>,
5317 <literal>A.D.</literal> or <literal>a.d.</literal></entry>
5318 <entry>era indicator (with periods)</entry>
5321 <entry><literal>MONTH</literal></entry>
5322 <entry>full upper case month name (blank-padded to 9 chars)</entry>
5325 <entry><literal>Month</literal></entry>
5326 <entry>full capitalized month name (blank-padded to 9 chars)</entry>
5329 <entry><literal>month</literal></entry>
5330 <entry>full lower case month name (blank-padded to 9 chars)</entry>
5333 <entry><literal>MON</literal></entry>
5334 <entry>abbreviated upper case month name (3 chars in English, localized lengths vary)</entry>
5337 <entry><literal>Mon</literal></entry>
5338 <entry>abbreviated capitalized month name (3 chars in English, localized lengths vary)</entry>
5341 <entry><literal>mon</literal></entry>
5342 <entry>abbreviated lower case month name (3 chars in English, localized lengths vary)</entry>
5345 <entry><literal>MM</literal></entry>
5346 <entry>month number (01-12)</entry>
5349 <entry><literal>DAY</literal></entry>
5350 <entry>full upper case day name (blank-padded to 9 chars)</entry>
5353 <entry><literal>Day</literal></entry>
5354 <entry>full capitalized day name (blank-padded to 9 chars)</entry>
5357 <entry><literal>day</literal></entry>
5358 <entry>full lower case day name (blank-padded to 9 chars)</entry>
5361 <entry><literal>DY</literal></entry>
5362 <entry>abbreviated upper case day name (3 chars in English, localized lengths vary)</entry>
5365 <entry><literal>Dy</literal></entry>
5366 <entry>abbreviated capitalized day name (3 chars in English, localized lengths vary)</entry>
5369 <entry><literal>dy</literal></entry>
5370 <entry>abbreviated lower case day name (3 chars in English, localized lengths vary)</entry>
5373 <entry><literal>DDD</literal></entry>
5374 <entry>day of year (001-366)</entry>
5377 <entry><literal>IDDD</literal></entry>
5378 <entry>ISO day of year (001-371; day 1 of the year is Monday of the first ISO week.)</entry>
5381 <entry><literal>DD</literal></entry>
5382 <entry>day of month (01-31)</entry>
5385 <entry><literal>D</literal></entry>
5386 <entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry>
5389 <entry><literal>ID</literal></entry>
5390 <entry>ISO day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry>
5393 <entry><literal>W</literal></entry>
5394 <entry>week of month (1-5) (The first week starts on the first day of the month.)</entry>
5397 <entry><literal>WW</literal></entry>
5398 <entry>week number of year (1-53) (The first week starts on the first day of the year.)</entry>
5401 <entry><literal>IW</literal></entry>
5402 <entry>ISO week number of year (01 - 53; the first Thursday of the new year is in week 1.)</entry>
5405 <entry><literal>CC</literal></entry>
5406 <entry>century (2 digits) (The twenty-first century starts on 2001-01-01.)</entry>
5409 <entry><literal>J</literal></entry>
5410 <entry>Julian Day (days since November 24, 4714 BC at midnight)</entry>
5413 <entry><literal>Q</literal></entry>
5414 <entry>quarter (ignored by <function>to_date</> and <function>to_timestamp</>)</entry>
5417 <entry><literal>RM</literal></entry>
5418 <entry>month in upper case Roman numerals (I-XII; I=January)</entry>
5421 <entry><literal>rm</literal></entry>
5422 <entry>month in lower case Roman numerals (i-xii; i=January)</entry>
5425 <entry><literal>TZ</literal></entry>
5426 <entry>upper case time-zone name</entry>
5429 <entry><literal>tz</literal></entry>
5430 <entry>lower case time-zone name</entry>
5437 Modifiers can be applied to any template pattern to alter its
5438 behavior. For example, <literal>FMMonth</literal>
5439 is the <literal>Month</literal> pattern with the
5440 <literal>FM</literal> modifier.
5441 <xref linkend="functions-formatting-datetimemod-table"> shows the
5442 modifier patterns for date/time formatting.
5445 <table id="functions-formatting-datetimemod-table">
5446 <title>Template Pattern Modifiers for Date/Time Formatting</title>
5450 <entry>Modifier</entry>
5451 <entry>Description</entry>
5452 <entry>Example</entry>
5457 <entry><literal>FM</literal> prefix</entry>
5458 <entry>fill mode (suppress padding blanks and trailing zeroes)</entry>
5459 <entry><literal>FMMonth</literal></entry>
5462 <entry><literal>TH</literal> suffix</entry>
5463 <entry>upper case ordinal number suffix</entry>
5464 <entry><literal>DDTH</literal>, e.g., <literal>12TH</></entry>
5467 <entry><literal>th</literal> suffix</entry>
5468 <entry>lower case ordinal number suffix</entry>
5469 <entry><literal>DDth</literal>, e.g., <literal>12th</></entry>
5472 <entry><literal>FX</literal> prefix</entry>
5473 <entry>fixed format global option (see usage notes)</entry>
5474 <entry><literal>FX Month DD Day</literal></entry>
5477 <entry><literal>TM</literal> prefix</entry>
5478 <entry>translation mode (print localized day and month names based on
5479 <xref linkend="guc-lc-time">)</entry>
5480 <entry><literal>TMMonth</literal></entry>
5483 <entry><literal>SP</literal> suffix</entry>
5484 <entry>spell mode (not implemented)</entry>
5485 <entry><literal>DDSP</literal></entry>
5492 Usage notes for date/time formatting:
5497 <literal>FM</literal> suppresses leading zeroes and trailing blanks
5498 that would otherwise be added to make the output of a pattern be
5499 fixed-width. In <productname>PostgreSQL</productname>,
5500 <literal>FM</literal> modifies only the next specification, while in
5501 Oracle <literal>FM</literal> affects all subsequent
5502 specifications, and repeated <literal>FM</literal> modifiers
5503 toggle fill mode on and off.
5509 <literal>TM</literal> does not include trailing blanks.
5515 <function>to_timestamp</function> and <function>to_date</function>
5516 skip multiple blank spaces in the input string unless the
5517 <literal>FX</literal> option is used. For example,
5518 <literal>to_timestamp('2000 JUN', 'YYYY MON')</literal> works, but
5519 <literal>to_timestamp('2000 JUN', 'FXYYYY MON')</literal> returns an error
5520 because <function>to_timestamp</function> expects one space only.
5521 <literal>FX</literal> must be specified as the first item in
5528 Ordinary text is allowed in <function>to_char</function>
5529 templates and will be output literally. You can put a substring
5530 in double quotes to force it to be interpreted as literal text
5531 even if it contains pattern key words. For example, in
5532 <literal>'"Hello Year "YYYY'</literal>, the <literal>YYYY</literal>
5533 will be replaced by the year data, but the single <literal>Y</literal> in <literal>Year</literal>
5534 will not be. In <function>to_date</>, <function>to_number</>,
5535 and <function>to_timestamp</>, double-quoted strings skip the number of
5536 input characters contained in the string, e.g. <literal>"XX"</>
5537 skips two input characters.
5543 If you want to have a double quote in the output you must
5544 precede it with a backslash, for example <literal>E'\\"YYYY
5545 Month\\"'</literal>. <!-- "" font-lock sanity :-) -->
5546 (Two backslashes are necessary because the backslash
5547 has special meaning when using the escape string syntax.)
5553 If the year format specification is less than four digits, e.g.
5554 <literal>YYY</>, and the supplied year is less than four digits,
5555 the year will be adjusted to be nearest to the year 2020, e.g.
5556 <literal>95</> becomes 1995.
5562 The <literal>YYYY</literal> conversion from string to <type>timestamp</type> or
5563 <type>date</type> has a restriction when processing years with more than 4 digits. You must
5564 use some non-digit character or template after <literal>YYYY</literal>,
5565 otherwise the year is always interpreted as 4 digits. For example
5566 (with the year 20000):
5567 <literal>to_date('200001131', 'YYYYMMDD')</literal> will be
5568 interpreted as a 4-digit year; instead use a non-digit
5569 separator after the year, like
5570 <literal>to_date('20000-1131', 'YYYY-MMDD')</literal> or
5571 <literal>to_date('20000Nov31', 'YYYYMonDD')</literal>.
5577 In conversions from string to <type>timestamp</type> or
5578 <type>date</type>, the <literal>CC</literal> (century) field is ignored
5579 if there is a <literal>YYY</literal>, <literal>YYYY</literal> or
5580 <literal>Y,YYY</literal> field. If <literal>CC</literal> is used with
5581 <literal>YY</literal> or <literal>Y</literal> then the year is computed
5582 as <literal>(CC-1)*100+YY</literal>.
5588 An ISO week date (as distinct from a Gregorian date) can be
5589 specified to <function>to_timestamp</function> and
5590 <function>to_date</function> in one of two ways:
5594 Year, week, and weekday: for example <literal>to_date('2006-42-4',
5595 'IYYY-IW-ID')</literal> returns the date
5596 <literal>2006-10-19</literal>. If you omit the weekday it
5597 is assumed to be 1 (Monday).
5602 Year and day of year: for example <literal>to_date('2006-291',
5603 'IYYY-IDDD')</literal> also returns <literal>2006-10-19</literal>.
5609 Attempting to construct a date using a mixture of ISO week and
5610 Gregorian date fields is nonsensical, and will cause an error. In the
5611 context of an ISO year, the concept of a <quote>month</> or <quote>day
5612 of month</> has no meaning. In the context of a Gregorian year, the
5613 ISO week has no meaning. Users should avoid mixing Gregorian and
5614 ISO date specifications.
5620 In a conversion from string to <type>timestamp</type>, millisecond
5621 (<literal>MS</literal>) or microsecond (<literal>US</literal>)
5622 values are used as the
5623 seconds digits after the decimal point. For example
5624 <literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds,
5625 but 300, because the conversion counts it as 12 + 0.3 seconds.
5626 This means for the format <literal>SS:MS</literal>, the input values
5627 <literal>12:3</literal>, <literal>12:30</literal>, and <literal>12:300</literal> specify the
5628 same number of milliseconds. To get three milliseconds, one must use
5629 <literal>12:003</literal>, which the conversion counts as
5630 12 + 0.003 = 12.003 seconds.
5636 <literal>to_timestamp('15:12:02.020.001230', 'HH:MI:SS.MS.US')</literal>
5637 is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
5638 1230 microseconds = 2.021230 seconds.
5644 <function>to_char(..., 'ID')</function>'s day of the week numbering
5645 matches the <function>extract(isodow from ...)</function> function, but
5646 <function>to_char(..., 'D')</function>'s does not match
5647 <function>extract(dow from ...)</function>'s day numbering.
5653 <function>to_char(interval)</function> formats <literal>HH</> and
5654 <literal>HH12</> as shown on a 12-hour clock, i.e. zero hours
5655 and 36 hours output as <literal>12</>, while <literal>HH24</>
5656 outputs the full hour value, which can exceed 23 for intervals.
5664 <xref linkend="functions-formatting-numeric-table"> shows the
5665 template patterns available for formatting numeric values.
5668 <table id="functions-formatting-numeric-table">
5669 <title>Template Patterns for Numeric Formatting</title>
5673 <entry>Pattern</entry>
5674 <entry>Description</entry>
5679 <entry><literal>9</literal></entry>
5680 <entry>value with the specified number of digits</entry>
5683 <entry><literal>0</literal></entry>
5684 <entry>value with leading zeros</entry>
5687 <entry><literal>.</literal> (period)</entry>
5688 <entry>decimal point</entry>
5691 <entry><literal>,</literal> (comma)</entry>
5692 <entry>group (thousand) separator</entry>
5695 <entry><literal>PR</literal></entry>
5696 <entry>negative value in angle brackets</entry>
5699 <entry><literal>S</literal></entry>
5700 <entry>sign anchored to number (uses locale)</entry>
5703 <entry><literal>L</literal></entry>
5704 <entry>currency symbol (uses locale)</entry>
5707 <entry><literal>D</literal></entry>
5708 <entry>decimal point (uses locale)</entry>
5711 <entry><literal>G</literal></entry>
5712 <entry>group separator (uses locale)</entry>
5715 <entry><literal>MI</literal></entry>
5716 <entry>minus sign in specified position (if number < 0)</entry>
5719 <entry><literal>PL</literal></entry>
5720 <entry>plus sign in specified position (if number > 0)</entry>
5723 <entry><literal>SG</literal></entry>
5724 <entry>plus/minus sign in specified position</entry>
5727 <entry><literal>RN</literal></entry>
5728 <entry>Roman numeral (input between 1 and 3999)</entry>
5731 <entry><literal>TH</literal> or <literal>th</literal></entry>
5732 <entry>ordinal number suffix</entry>
5735 <entry><literal>V</literal></entry>
5736 <entry>shift specified number of digits (see notes)</entry>
5739 <entry><literal>EEEE</literal></entry>
5740 <entry>exponent for scientific notation</entry>
5747 Usage notes for numeric formatting:
5752 A sign formatted using <literal>SG</literal>, <literal>PL</literal>, or
5753 <literal>MI</literal> is not anchored to
5754 the number; for example,
5755 <literal>to_char(-12, 'MI9999')</literal> produces <literal>'- 12'</literal>
5756 but <literal>to_char(-12, 'S9999')</literal> produces <literal>' -12'</literal>.
5757 The Oracle implementation does not allow the use of
5758 <literal>MI</literal> before <literal>9</literal>, but rather
5759 requires that <literal>9</literal> precede
5760 <literal>MI</literal>.
5766 <literal>9</literal> results in a value with the same number of
5767 digits as there are <literal>9</literal>s. If a digit is
5768 not available it outputs a space.
5774 <literal>TH</literal> does not convert values less than zero
5775 and does not convert fractional numbers.
5781 <literal>PL</literal>, <literal>SG</literal>, and
5782 <literal>TH</literal> are <productname>PostgreSQL</productname>
5789 <literal>V</literal> effectively
5790 multiplies the input values by
5791 <literal>10^<replaceable>n</replaceable></literal>, where
5792 <replaceable>n</replaceable> is the number of digits following
5793 <literal>V</literal>.
5794 <function>to_char</function> does not support the use of
5795 <literal>V</literal> combined with a decimal point
5796 (e.g., <literal>99.9V99</literal> is not allowed).
5802 <literal>EEEE</literal> (scientific notation) cannot be used in
5803 combination with any of the other formatting patterns or
5804 modifiers other than digit and decimal point patterns, and must be at the end of the format string
5805 (e.g., <literal>9.99EEEE</literal> is a valid pattern).
5812 Certain modifiers can be applied to any template pattern to alter its
5813 behavior. For example, <literal>FM9999</literal>
5814 is the <literal>9999</literal> pattern with the
5815 <literal>FM</literal> modifier.
5816 <xref linkend="functions-formatting-numericmod-table"> shows the
5817 modifier patterns for numeric formatting.
5820 <table id="functions-formatting-numericmod-table">
5821 <title>Template Pattern Modifiers for Numeric Formatting</title>
5825 <entry>Modifier</entry>
5826 <entry>Description</entry>
5827 <entry>Example</entry>
5832 <entry><literal>FM</literal> prefix</entry>
5833 <entry>fill mode (suppress padding blanks and trailing zeroes)</entry>
5834 <entry><literal>FM9999</literal></entry>
5837 <entry><literal>TH</literal> suffix</entry>
5838 <entry>upper case ordinal number suffix</entry>
5839 <entry><literal>999TH</literal></entry>
5842 <entry><literal>th</literal> suffix</entry>
5843 <entry>lower case ordinal number suffix</entry>
5844 <entry><literal>999th</literal></entry>
5851 <xref linkend="functions-formatting-examples-table"> shows some
5852 examples of the use of the <function>to_char</function> function.
5855 <table id="functions-formatting-examples-table">
5856 <title><function>to_char</function> Examples</title>
5860 <entry>Expression</entry>
5861 <entry>Result</entry>
5866 <entry><literal>to_char(current_timestamp, 'Day, DD HH12:MI:SS')</literal></entry>
5867 <entry><literal>'Tuesday , 06 05:39:18'</literal></entry>
5870 <entry><literal>to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS')</literal></entry>
5871 <entry><literal>'Tuesday, 6 05:39:18'</literal></entry>
5874 <entry><literal>to_char(-0.1, '99.99')</literal></entry>
5875 <entry><literal>' -.10'</literal></entry>
5878 <entry><literal>to_char(-0.1, 'FM9.99')</literal></entry>
5879 <entry><literal>'-.1'</literal></entry>
5882 <entry><literal>to_char(0.1, '0.9')</literal></entry>
5883 <entry><literal>' 0.1'</literal></entry>
5886 <entry><literal>to_char(12, '9990999.9')</literal></entry>
5887 <entry><literal>' 0012.0'</literal></entry>
5890 <entry><literal>to_char(12, 'FM9990999.9')</literal></entry>
5891 <entry><literal>'0012.'</literal></entry>
5894 <entry><literal>to_char(485, '999')</literal></entry>
5895 <entry><literal>' 485'</literal></entry>
5898 <entry><literal>to_char(-485, '999')</literal></entry>
5899 <entry><literal>'-485'</literal></entry>
5902 <entry><literal>to_char(485, '9 9 9')</literal></entry>
5903 <entry><literal>' 4 8 5'</literal></entry>
5906 <entry><literal>to_char(1485, '9,999')</literal></entry>
5907 <entry><literal>' 1,485'</literal></entry>
5910 <entry><literal>to_char(1485, '9G999')</literal></entry>
5911 <entry><literal>' 1 485'</literal></entry>
5914 <entry><literal>to_char(148.5, '999.999')</literal></entry>
5915 <entry><literal>' 148.500'</literal></entry>
5918 <entry><literal>to_char(148.5, 'FM999.999')</literal></entry>
5919 <entry><literal>'148.5'</literal></entry>
5922 <entry><literal>to_char(148.5, 'FM999.990')</literal></entry>
5923 <entry><literal>'148.500'</literal></entry>
5926 <entry><literal>to_char(148.5, '999D999')</literal></entry>
5927 <entry><literal>' 148,500'</literal></entry>
5930 <entry><literal>to_char(3148.5, '9G999D999')</literal></entry>
5931 <entry><literal>' 3 148,500'</literal></entry>
5934 <entry><literal>to_char(-485, '999S')</literal></entry>
5935 <entry><literal>'485-'</literal></entry>
5938 <entry><literal>to_char(-485, '999MI')</literal></entry>
5939 <entry><literal>'485-'</literal></entry>
5942 <entry><literal>to_char(485, '999MI')</literal></entry>
5943 <entry><literal>'485 '</literal></entry>
5946 <entry><literal>to_char(485, 'FM999MI')</literal></entry>
5947 <entry><literal>'485'</literal></entry>
5950 <entry><literal>to_char(485, 'PL999')</literal></entry>
5951 <entry><literal>'+485'</literal></entry>
5954 <entry><literal>to_char(485, 'SG999')</literal></entry>
5955 <entry><literal>'+485'</literal></entry>
5958 <entry><literal>to_char(-485, 'SG999')</literal></entry>
5959 <entry><literal>'-485'</literal></entry>
5962 <entry><literal>to_char(-485, '9SG99')</literal></entry>
5963 <entry><literal>'4-85'</literal></entry>
5966 <entry><literal>to_char(-485, '999PR')</literal></entry>
5967 <entry><literal>'<485>'</literal></entry>
5970 <entry><literal>to_char(485, 'L999')</literal></entry>
5971 <entry><literal>'DM 485</literal></entry>
5974 <entry><literal>to_char(485, 'RN')</literal></entry>
5975 <entry><literal>' CDLXXXV'</literal></entry>
5978 <entry><literal>to_char(485, 'FMRN')</literal></entry>
5979 <entry><literal>'CDLXXXV'</literal></entry>
5982 <entry><literal>to_char(5.2, 'FMRN')</literal></entry>
5983 <entry><literal>'V'</literal></entry>
5986 <entry><literal>to_char(482, '999th')</literal></entry>
5987 <entry><literal>' 482nd'</literal></entry>
5990 <entry><literal>to_char(485, '"Good number:"999')</literal></entry>
5991 <entry><literal>'Good number: 485'</literal></entry>
5994 <entry><literal>to_char(485.8, '"Pre:"999" Post:" .999')</literal></entry>
5995 <entry><literal>'Pre: 485 Post: .800'</literal></entry>
5998 <entry><literal>to_char(12, '99V999')</literal></entry>
5999 <entry><literal>' 12000'</literal></entry>
6002 <entry><literal>to_char(12.4, '99V999')</literal></entry>
6003 <entry><literal>' 12400'</literal></entry>
6006 <entry><literal>to_char(12.45, '99V9')</literal></entry>
6007 <entry><literal>' 125'</literal></entry>
6010 <entry><literal>to_char(0.0004859, '9.99EEEE')</literal></entry>
6011 <entry><literal>' 4.86e-04'</literal></entry>
6020 <sect1 id="functions-datetime">
6021 <title>Date/Time Functions and Operators</title>
6024 <xref linkend="functions-datetime-table"> shows the available
6025 functions for date/time value processing, with details appearing in
6026 the following subsections. <xref
6027 linkend="operators-datetime-table"> illustrates the behaviors of
6028 the basic arithmetic operators (<literal>+</literal>,
6029 <literal>*</literal>, etc.). For formatting functions, refer to
6030 <xref linkend="functions-formatting">. You should be familiar with
6031 the background information on date/time data types from <xref
6032 linkend="datatype-datetime">.
6036 All the functions and operators described below that take <type>time</type> or <type>timestamp</type>
6037 inputs actually come in two variants: one that takes <type>time with time zone</type> or <type>timestamp
6038 with time zone</type>, and one that takes <type>time without time zone</type> or <type>timestamp without time zone</type>.
6039 For brevity, these variants are not shown separately. Also, the
6040 <literal>+</> and <literal>*</> operators come in commutative pairs (for
6041 example both date + integer and integer + date); we show only one of each
6045 <table id="operators-datetime-table">
6046 <title>Date/Time Operators</title>
6051 <entry>Operator</entry>
6052 <entry>Example</entry>
6053 <entry>Result</entry>
6059 <entry> <literal>+</literal> </entry>
6060 <entry><literal>date '2001-09-28' + integer '7'</literal></entry>
6061 <entry><literal>date '2001-10-05'</literal></entry>
6065 <entry> <literal>+</literal> </entry>
6066 <entry><literal>date '2001-09-28' + interval '1 hour'</literal></entry>
6067 <entry><literal>timestamp '2001-09-28 01:00:00'</literal></entry>
6071 <entry> <literal>+</literal> </entry>
6072 <entry><literal>date '2001-09-28' + time '03:00'</literal></entry>
6073 <entry><literal>timestamp '2001-09-28 03:00:00'</literal></entry>
6077 <entry> <literal>+</literal> </entry>
6078 <entry><literal>interval '1 day' + interval '1 hour'</literal></entry>
6079 <entry><literal>interval '1 day 01:00:00'</literal></entry>
6083 <entry> <literal>+</literal> </entry>
6084 <entry><literal>timestamp '2001-09-28 01:00' + interval '23 hours'</literal></entry>
6085 <entry><literal>timestamp '2001-09-29 00:00:00'</literal></entry>
6089 <entry> <literal>+</literal> </entry>
6090 <entry><literal>time '01:00' + interval '3 hours'</literal></entry>
6091 <entry><literal>time '04:00:00'</literal></entry>
6095 <entry> <literal>-</literal> </entry>
6096 <entry><literal>- interval '23 hours'</literal></entry>
6097 <entry><literal>interval '-23:00:00'</literal></entry>
6101 <entry> <literal>-</literal> </entry>
6102 <entry><literal>date '2001-10-01' - date '2001-09-28'</literal></entry>
6103 <entry><literal>integer '3'</literal> (days)</entry>
6107 <entry> <literal>-</literal> </entry>
6108 <entry><literal>date '2001-10-01' - integer '7'</literal></entry>
6109 <entry><literal>date '2001-09-24'</literal></entry>
6113 <entry> <literal>-</literal> </entry>
6114 <entry><literal>date '2001-09-28' - interval '1 hour'</literal></entry>
6115 <entry><literal>timestamp '2001-09-27 23:00:00'</literal></entry>
6119 <entry> <literal>-</literal> </entry>
6120 <entry><literal>time '05:00' - time '03:00'</literal></entry>
6121 <entry><literal>interval '02:00:00'</literal></entry>
6125 <entry> <literal>-</literal> </entry>
6126 <entry><literal>time '05:00' - interval '2 hours'</literal></entry>
6127 <entry><literal>time '03:00:00'</literal></entry>
6131 <entry> <literal>-</literal> </entry>
6132 <entry><literal>timestamp '2001-09-28 23:00' - interval '23 hours'</literal></entry>
6133 <entry><literal>timestamp '2001-09-28 00:00:00'</literal></entry>
6137 <entry> <literal>-</literal> </entry>
6138 <entry><literal>interval '1 day' - interval '1 hour'</literal></entry>
6139 <entry><literal>interval '1 day -01:00:00'</literal></entry>
6143 <entry> <literal>-</literal> </entry>
6144 <entry><literal>timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00'</literal></entry>
6145 <entry><literal>interval '1 day 15:00:00'</literal></entry>
6149 <entry> <literal>*</literal> </entry>
6150 <entry><literal>900 * interval '1 second'</literal></entry>
6151 <entry><literal>interval '00:15:00'</literal></entry>
6155 <entry> <literal>*</literal> </entry>
6156 <entry><literal>21 * interval '1 day'</literal></entry>
6157 <entry><literal>interval '21 days'</literal></entry>
6161 <entry> <literal>*</literal> </entry>
6162 <entry><literal>double precision '3.5' * interval '1 hour'</literal></entry>
6163 <entry><literal>interval '03:30:00'</literal></entry>
6167 <entry> <literal>/</literal> </entry>
6168 <entry><literal>interval '1 hour' / double precision '1.5'</literal></entry>
6169 <entry><literal>interval '00:40:00'</literal></entry>
6175 <table id="functions-datetime-table">
6176 <title>Date/Time Functions</title>
6180 <entry>Function</entry>
6181 <entry>Return Type</entry>
6182 <entry>Description</entry>
6183 <entry>Example</entry>
6184 <entry>Result</entry>
6192 <primary>age</primary>
6194 <literal><function>age(<type>timestamp</type>, <type>timestamp</type>)</function></literal>
6196 <entry><type>interval</type></entry>
6197 <entry>Subtract arguments, producing a <quote>symbolic</> result that
6198 uses years and months</entry>
6199 <entry><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
6200 <entry><literal>43 years 9 mons 27 days</literal></entry>
6204 <entry><literal><function>age(<type>timestamp</type>)</function></literal></entry>
6205 <entry><type>interval</type></entry>
6206 <entry>Subtract from <function>current_date</function> (at midnight)</entry>
6207 <entry><literal>age(timestamp '1957-06-13')</literal></entry>
6208 <entry><literal>43 years 8 mons 3 days</literal></entry>
6214 <primary>clock_timestamp</primary>
6216 <literal><function>clock_timestamp()</function></literal>
6218 <entry><type>timestamp with time zone</type></entry>
6219 <entry>Current date and time (changes during statement execution);
6220 see <xref linkend="functions-datetime-current">
6229 <primary>current_date</primary>
6231 <literal><function>current_date</function></literal>
6233 <entry><type>date</type></entry>
6234 <entry>Current date;
6235 see <xref linkend="functions-datetime-current">
6244 <primary>current_time</primary>
6246 <literal><function>current_time</function></literal>
6248 <entry><type>time with time zone</type></entry>
6249 <entry>Current time of day;
6250 see <xref linkend="functions-datetime-current">
6259 <primary>current_timestamp</primary>
6261 <literal><function>current_timestamp</function></literal>
6263 <entry><type>timestamp with time zone</type></entry>
6264 <entry>Current date and time (start of current transaction);
6265 see <xref linkend="functions-datetime-current">
6274 <primary>date_part</primary>
6276 <literal><function>date_part(<type>text</type>, <type>timestamp</type>)</function></literal>
6278 <entry><type>double precision</type></entry>
6279 <entry>Get subfield (equivalent to <function>extract</function>);
6280 see <xref linkend="functions-datetime-extract">
6282 <entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
6283 <entry><literal>20</literal></entry>
6287 <entry><literal><function>date_part(<type>text</type>, <type>interval</type>)</function></literal></entry>
6288 <entry><type>double precision</type></entry>
6289 <entry>Get subfield (equivalent to
6290 <function>extract</function>); see <xref linkend="functions-datetime-extract">
6292 <entry><literal>date_part('month', interval '2 years 3 months')</literal></entry>
6293 <entry><literal>3</literal></entry>
6299 <primary>date_trunc</primary>
6301 <literal><function>date_trunc(<type>text</type>, <type>timestamp</type>)</function></literal>
6303 <entry><type>timestamp</type></entry>
6304 <entry>Truncate to specified precision; see also <xref linkend="functions-datetime-trunc">
6306 <entry><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
6307 <entry><literal>2001-02-16 20:00:00</literal></entry>
6313 <primary>extract</primary>
6315 <literal><function>extract</function>(<parameter>field</parameter> from
6316 <type>timestamp</type>)</literal>
6318 <entry><type>double precision</type></entry>
6319 <entry>Get subfield; see <xref linkend="functions-datetime-extract">
6321 <entry><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
6322 <entry><literal>20</literal></entry>
6326 <entry><literal><function>extract</function>(<parameter>field</parameter> from
6327 <type>interval</type>)</literal></entry>
6328 <entry><type>double precision</type></entry>
6329 <entry>Get subfield; see <xref linkend="functions-datetime-extract">
6331 <entry><literal>extract(month from interval '2 years 3 months')</literal></entry>
6332 <entry><literal>3</literal></entry>
6338 <primary>isfinite</primary>
6340 <literal><function>isfinite(<type>date</type>)</function></literal>
6342 <entry><type>boolean</type></entry>
6343 <entry>Test for finite date (not +/-infinity)</entry>
6344 <entry><literal>isfinite(date '2001-02-16')</literal></entry>
6345 <entry><literal>true</literal></entry>
6349 <entry><literal><function>isfinite(<type>timestamp</type>)</function></literal></entry>
6350 <entry><type>boolean</type></entry>
6351 <entry>Test for finite time stamp (not +/-infinity)</entry>
6352 <entry><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
6353 <entry><literal>true</literal></entry>
6357 <entry><literal><function>isfinite(<type>interval</type>)</function></literal></entry>
6358 <entry><type>boolean</type></entry>
6359 <entry>Test for finite interval</entry>
6360 <entry><literal>isfinite(interval '4 hours')</literal></entry>
6361 <entry><literal>true</literal></entry>
6367 <primary>justify_days</primary>
6369 <literal><function>justify_days(<type>interval</type>)</function></literal>
6371 <entry><type>interval</type></entry>
6372 <entry>Adjust interval so 30-day time periods are represented as months</entry>
6373 <entry><literal>justify_days(interval '35 days')</literal></entry>
6374 <entry><literal>1 mon 5 days</literal></entry>
6380 <primary>justify_hours</primary>
6382 <literal><function>justify_hours(<type>interval</type>)</function></literal>
6384 <entry><type>interval</type></entry>
6385 <entry>Adjust interval so 24-hour time periods are represented as days</entry>
6386 <entry><literal>justify_hours(interval '27 hours')</literal></entry>
6387 <entry><literal>1 day 03:00:00</literal></entry>
6393 <primary>justify_interval</primary>
6395 <literal><function>justify_interval(<type>interval</type>)</function></literal>
6397 <entry><type>interval</type></entry>
6398 <entry>Adjust interval using <function>justify_days</> and <function>justify_hours</>, with additional sign adjustments</entry>
6399 <entry><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
6400 <entry><literal>29 days 23:00:00</literal></entry>
6406 <primary>localtime</primary>
6408 <literal><function>localtime</function></literal>
6410 <entry><type>time</type></entry>
6411 <entry>Current time of day;
6412 see <xref linkend="functions-datetime-current">
6421 <primary>localtimestamp</primary>
6423 <literal><function>localtimestamp</function></literal>
6425 <entry><type>timestamp</type></entry>
6426 <entry>Current date and time (start of current transaction);
6427 see <xref linkend="functions-datetime-current">
6436 <primary>now</primary>
6438 <literal><function>now()</function></literal>
6440 <entry><type>timestamp with time zone</type></entry>
6441 <entry>Current date and time (start of current transaction);
6442 see <xref linkend="functions-datetime-current">
6451 <primary>statement_timestamp</primary>
6453 <literal><function>statement_timestamp()</function></literal>
6455 <entry><type>timestamp with time zone</type></entry>
6456 <entry>Current date and time (start of current statement);
6457 see <xref linkend="functions-datetime-current">
6466 <primary>timeofday</primary>
6468 <literal><function>timeofday()</function></literal>
6470 <entry><type>text</type></entry>
6471 <entry>Current date and time
6472 (like <function>clock_timestamp</>, but as a <type>text</> string);
6473 see <xref linkend="functions-datetime-current">
6482 <primary>transaction_timestamp</primary>
6484 <literal><function>transaction_timestamp()</function></literal>
6486 <entry><type>timestamp with time zone</type></entry>
6487 <entry>Current date and time (start of current transaction);
6488 see <xref linkend="functions-datetime-current">
6498 In addition to these functions, the SQL <literal>OVERLAPS</> operator is
6501 (<replaceable>start1</replaceable>, <replaceable>end1</replaceable>) OVERLAPS (<replaceable>start2</replaceable>, <replaceable>end2</replaceable>)
6502 (<replaceable>start1</replaceable>, <replaceable>length1</replaceable>) OVERLAPS (<replaceable>start2</replaceable>, <replaceable>length2</replaceable>)
6504 This expression yields true when two time periods (defined by their
6505 endpoints) overlap, false when they do not overlap. The endpoints
6506 can be specified as pairs of dates, times, or time stamps; or as
6507 a date, time, or time stamp followed by an interval. When a pair
6508 of values is provided, either the start or the end can be written
6509 first; <literal>OVERLAPS</> automatically takes the earlier value
6510 of the pair as the start. Each time period is considered to
6511 represent the half-open interval <replaceable>start</> <literal><=</>
6512 <replaceable>time</> <literal><</> <replaceable>end</>, unless
6513 <replaceable>start</> and <replaceable>end</> are equal in which case it
6514 represents that single time instant. This means for instance that two
6515 time periods with only an endpoint in common do not overlap.
6519 SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
6520 (DATE '2001-10-30', DATE '2002-10-30');
6521 <lineannotation>Result: </lineannotation><computeroutput>true</computeroutput>
6522 SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
6523 (DATE '2001-10-30', DATE '2002-10-30');
6524 <lineannotation>Result: </lineannotation><computeroutput>false</computeroutput>
6525 SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS
6526 (DATE '2001-10-30', DATE '2001-10-31');
6527 <lineannotation>Result: </lineannotation><computeroutput>false</computeroutput>
6528 SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
6529 (DATE '2001-10-30', DATE '2001-10-31');
6530 <lineannotation>Result: </lineannotation><computeroutput>true</computeroutput>
6534 When adding an <type>interval</type> value to (or subtracting an
6535 <type>interval</type> value from) a <type>timestamp with time zone</type>
6536 value, the days component advances (or decrements) the date of the
6537 <type>timestamp with time zone</type> by the indicated number of days.
6538 Across daylight saving time changes (with the session time zone set to a
6539 time zone that recognizes DST), this means <literal>interval '1 day'</literal>
6540 does not necessarily equal <literal>interval '24 hours'</literal>.
6541 For example, with the session time zone set to <literal>CST7CDT</literal>,
6542 <literal>timestamp with time zone '2005-04-02 12:00-07' + interval '1 day' </literal>
6543 will produce <literal>timestamp with time zone '2005-04-03 12:00-06'</literal>,
6544 while adding <literal>interval '24 hours'</literal> to the same initial
6545 <type>timestamp with time zone</type> produces
6546 <literal>timestamp with time zone '2005-04-03 13:00-06'</literal>, as there is
6547 a change in daylight saving time at <literal>2005-04-03 02:00</literal> in time zone
6548 <literal>CST7CDT</literal>.
6552 Note there can be ambiguity in the <literal>months</> returned by
6553 <function>age</> because different months have a different number of
6554 days. <productname>PostgreSQL</>'s approach uses the month from the
6555 earlier of the two dates when calculating partial months. For example,
6556 <literal>age('2004-06-01', '2004-04-30')</> uses April to yield
6557 <literal>1 mon 1 day</>, while using May would yield <literal>1 mon 2
6558 days</> because May has 31 days, while April has only 30.
6561 <sect2 id="functions-datetime-extract">
6562 <title><function>EXTRACT</function>, <function>date_part</function></title>
6565 <primary>date_part</primary>
6568 <primary>extract</primary>
6572 EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>)
6576 The <function>extract</function> function retrieves subfields
6577 such as year or hour from date/time values.
6578 <replaceable>source</replaceable> must be a value expression of
6579 type <type>timestamp</type>, <type>time</type>, or <type>interval</type>.
6580 (Expressions of type <type>date</type> are
6581 cast to <type>timestamp</type> and can therefore be used as
6582 well.) <replaceable>field</replaceable> is an identifier or
6583 string that selects what field to extract from the source value.
6584 The <function>extract</function> function returns values of type
6585 <type>double precision</type>.
6586 The following are valid field names:
6588 <!-- alphabetical -->
6591 <term><literal>century</literal></term>
6598 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
6599 <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput>
6600 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
6601 <lineannotation>Result: </lineannotation><computeroutput>21</computeroutput>
6605 The first century starts at 0001-01-01 00:00:00 AD, although
6606 they did not know it at the time. This definition applies to all
6607 Gregorian calendar countries. There is no century number 0,
6608 you go from -1 century to 1 century.
6610 If you disagree with this, please write your complaint to:
6611 Pope, Cathedral Saint-Peter of Roma, Vatican.
6615 <productname>PostgreSQL</productname> releases before 8.0 did not
6616 follow the conventional numbering of centuries, but just returned
6617 the year field divided by 100.
6623 <term><literal>day</literal></term>
6626 For <type>timestamp</type> values, the day (of the month) field
6627 (1 - 31) ; for <type>interval</type> values, the number of days
6631 SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
6632 <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput>
6634 SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute');
6635 <lineannotation>Result: </lineannotation><computeroutput>40</computeroutput>
6644 <term><literal>decade</literal></term>
6647 The year field divided by 10
6651 SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
6652 <lineannotation>Result: </lineannotation><computeroutput>200</computeroutput>
6658 <term><literal>dow</literal></term>
6661 The day of the week as Sunday(<literal>0</>) to
6662 Saturday(<literal>6</>)
6666 SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
6667 <lineannotation>Result: </lineannotation><computeroutput>5</computeroutput>
6670 Note that <function>extract</function>'s day of the week numbering
6671 differs from that of the <function>to_char(...,
6672 'D')</function> function.
6679 <term><literal>doy</literal></term>
6682 The day of the year (1 - 365/366)
6686 SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
6687 <lineannotation>Result: </lineannotation><computeroutput>47</computeroutput>
6693 <term><literal>epoch</literal></term>
6696 For <type>date</type> and <type>timestamp</type> values, the
6697 number of seconds since 1970-01-01 00:00:00 UTC (can be negative);
6698 for <type>interval</type> values, the total number
6699 of seconds in the interval
6703 SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
6704 <lineannotation>Result: </lineannotation><computeroutput>982384720.12</computeroutput>
6706 SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
6707 <lineannotation>Result: </lineannotation><computeroutput>442800</computeroutput>
6711 Here is how you can convert an epoch value back to a time
6715 SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720.12 * INTERVAL '1 second';
6718 (The <function>to_timestamp</> function encapsulates the above
6725 <term><literal>hour</literal></term>
6728 The hour field (0 - 23)
6732 SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
6733 <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput>
6739 <term><literal>isodow</literal></term>
6742 The day of the week as Monday(<literal>1</>) to
6743 Sunday(<literal>7</>)
6747 SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
6748 <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput>
6751 This is identical to <literal>dow</> except for Sunday. This
6752 matches the <acronym>ISO</> 8601 day of the week numbering.
6759 <term><literal>isoyear</literal></term>
6762 The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals)
6766 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
6767 <lineannotation>Result: </lineannotation><computeroutput>2005</computeroutput>
6768 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
6769 <lineannotation>Result: </lineannotation><computeroutput>2006</computeroutput>
6773 Each <acronym>ISO</acronym> year begins with the Monday of the week containing the 4th of January, so in early January or late December the <acronym>ISO</acronym> year may be different from the Gregorian year. See the <literal>week</literal> field for more information.
6776 This field is not available in PostgreSQL releases prior to 8.3.
6782 <term><literal>microseconds</literal></term>
6785 The seconds field, including fractional parts, multiplied by 1
6786 000 000; note that this includes full seconds
6790 SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
6791 <lineannotation>Result: </lineannotation><computeroutput>28500000</computeroutput>
6797 <term><literal>millennium</literal></term>
6804 SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
6805 <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput>
6809 Years in the 1900s are in the second millennium.
6810 The third millennium started January 1, 2001.
6814 <productname>PostgreSQL</productname> releases before 8.0 did not
6815 follow the conventional numbering of millennia, but just returned
6816 the year field divided by 1000.
6822 <term><literal>milliseconds</literal></term>
6825 The seconds field, including fractional parts, multiplied by
6826 1000. Note that this includes full seconds.
6830 SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
6831 <lineannotation>Result: </lineannotation><computeroutput>28500</computeroutput>
6837 <term><literal>minute</literal></term>
6840 The minutes field (0 - 59)
6844 SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
6845 <lineannotation>Result: </lineannotation><computeroutput>38</computeroutput>
6851 <term><literal>month</literal></term>
6854 For <type>timestamp</type> values, the number of the month
6855 within the year (1 - 12) ; for <type>interval</type> values,
6856 the number of months, modulo 12 (0 - 11)
6860 SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
6861 <lineannotation>Result: </lineannotation><computeroutput>2</computeroutput>
6863 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
6864 <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput>
6866 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
6867 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
6873 <term><literal>quarter</literal></term>
6876 The quarter of the year (1 - 4) that the date is in
6880 SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
6881 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
6887 <term><literal>second</literal></term>
6890 The seconds field, including fractional parts (0 -
6891 59<footnote><simpara>60 if leap seconds are
6892 implemented by the operating system</simpara></footnote>)
6896 SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
6897 <lineannotation>Result: </lineannotation><computeroutput>40</computeroutput>
6899 SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
6900 <lineannotation>Result: </lineannotation><computeroutput>28.5</computeroutput>
6905 <term><literal>timezone</literal></term>
6908 The time zone offset from UTC, measured in seconds. Positive values
6909 correspond to time zones east of UTC, negative values to
6910 zones west of UTC. (Technically,
6911 <productname>PostgreSQL</productname> uses <acronym>UT1</> because
6912 leap seconds are not handled.)
6918 <term><literal>timezone_hour</literal></term>
6921 The hour component of the time zone offset
6927 <term><literal>timezone_minute</literal></term>
6930 The minute component of the time zone offset
6936 <term><literal>week</literal></term>
6939 The number of the week of the year that the day is in. By definition
6940 (<acronym>ISO</acronym> 8601), the first week of a year
6941 contains January 4 of that year. (The <acronym>ISO</acronym>-8601
6942 week starts on Monday.) In other words, the first Thursday of
6943 a year is in week 1 of that year.
6946 Because of this, it is possible for early January dates to be part of the
6947 52nd or 53rd week of the previous year. For example, <literal>2005-01-01</>
6948 is part of the 53rd week of year 2004, and <literal>2006-01-01</> is part of
6949 the 52nd week of year 2005.
6953 SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
6954 <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput>
6960 <term><literal>year</literal></term>
6963 The year field. Keep in mind there is no <literal>0 AD</>, so subtracting
6964 <literal>BC</> years from <literal>AD</> years should be done with care.
6968 SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
6969 <lineannotation>Result: </lineannotation><computeroutput>2001</computeroutput>
6978 The <function>extract</function> function is primarily intended
6979 for computational processing. For formatting date/time values for
6980 display, see <xref linkend="functions-formatting">.
6984 The <function>date_part</function> function is modeled on the traditional
6985 <productname>Ingres</productname> equivalent to the
6986 <acronym>SQL</acronym>-standard function <function>extract</function>:
6988 date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
6990 Note that here the <replaceable>field</replaceable> parameter needs to
6991 be a string value, not a name. The valid field names for
6992 <function>date_part</function> are the same as for
6993 <function>extract</function>.
6997 SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
6998 <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput>
7000 SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
7001 <lineannotation>Result: </lineannotation><computeroutput>4</computeroutput>
7006 <sect2 id="functions-datetime-trunc">
7007 <title><function>date_trunc</function></title>
7010 <primary>date_trunc</primary>
7014 The function <function>date_trunc</function> is conceptually
7015 similar to the <function>trunc</function> function for numbers.
7020 date_trunc('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
7022 <replaceable>source</replaceable> is a value expression of type
7023 <type>timestamp</type> or <type>interval</>.
7024 (Values of type <type>date</type> and
7025 <type>time</type> are cast automatically to <type>timestamp</type> or
7026 <type>interval</>, respectively.)
7027 <replaceable>field</replaceable> selects to which precision to
7028 truncate the input value. The return value is of type
7029 <type>timestamp</type> or <type>interval</>
7030 with all fields that are less significant than the
7031 selected one set to zero (or one, for day and month).
7035 Valid values for <replaceable>field</replaceable> are:
7037 <member><literal>microseconds</literal></member>
7038 <member><literal>milliseconds</literal></member>
7039 <member><literal>second</literal></member>
7040 <member><literal>minute</literal></member>
7041 <member><literal>hour</literal></member>
7042 <member><literal>day</literal></member>
7043 <member><literal>week</literal></member>
7044 <member><literal>month</literal></member>
7045 <member><literal>quarter</literal></member>
7046 <member><literal>year</literal></member>
7047 <member><literal>decade</literal></member>
7048 <member><literal>century</literal></member>
7049 <member><literal>millennium</literal></member>
7056 SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
7057 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:00:00</computeroutput>
7059 SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
7060 <lineannotation>Result: </lineannotation><computeroutput>2001-01-01 00:00:00</computeroutput>
7065 <sect2 id="functions-datetime-zoneconvert">
7066 <title><literal>AT TIME ZONE</literal></title>
7069 <primary>time zone</primary>
7070 <secondary>conversion</secondary>
7074 <primary>AT TIME ZONE</primary>
7078 The <literal>AT TIME ZONE</literal> construct allows conversions
7079 of time stamps to different time zones. <xref
7080 linkend="functions-datetime-zoneconvert-table"> shows its
7084 <table id="functions-datetime-zoneconvert-table">
7085 <title><literal>AT TIME ZONE</literal> Variants</title>
7089 <entry>Expression</entry>
7090 <entry>Return Type</entry>
7091 <entry>Description</entry>
7098 <literal><type>timestamp without time zone</type> AT TIME ZONE <replaceable>zone</></literal>
7100 <entry><type>timestamp with time zone</type></entry>
7101 <entry>Treat given time stamp <emphasis>without time zone</> as located in the specified time zone</entry>
7106 <literal><type>timestamp with time zone</type> AT TIME ZONE <replaceable>zone</></literal>
7108 <entry><type>timestamp without time zone</type></entry>
7109 <entry>Convert given time stamp <emphasis>with time zone</> to the new time
7110 zone, with no time zone designation</entry>
7115 <literal><type>time with time zone</type> AT TIME ZONE <replaceable>zone</></literal>
7117 <entry><type>time with time zone</type></entry>
7118 <entry>Convert given time <emphasis>with time zone</> to the new time zone</entry>
7125 In these expressions, the desired time zone <replaceable>zone</> can be
7126 specified either as a text string (e.g., <literal>'PST'</literal>)
7127 or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>).
7128 In the text case, a time zone name can be specified in any of the ways
7129 described in <xref linkend="datatype-timezones">.
7133 Examples (assuming the local time zone is <literal>PST8PDT</>):
7135 SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
7136 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computeroutput>
7138 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
7139 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computeroutput>
7141 The first example takes a time stamp without time zone and interprets it as MST time
7142 (UTC-7), which is then converted to PST (UTC-8) for display. The second example takes
7143 a time stamp specified in EST (UTC-5) and converts it to local time in MST (UTC-7).
7147 The function <literal><function>timezone</function>(<replaceable>zone</>,
7148 <replaceable>timestamp</>)</literal> is equivalent to the SQL-conforming construct
7149 <literal><replaceable>timestamp</> AT TIME ZONE
7150 <replaceable>zone</></literal>.
7154 <sect2 id="functions-datetime-current">
7155 <title>Current Date/Time</title>
7158 <primary>date</primary>
7159 <secondary>current</secondary>
7163 <primary>time</primary>
7164 <secondary>current</secondary>
7168 <productname>PostgreSQL</productname> provides a number of functions
7169 that return values related to the current date and time. These
7170 SQL-standard functions all return values based on the start time of
7171 the current transaction:
7176 CURRENT_TIME(<replaceable>precision</replaceable>)
7177 CURRENT_TIMESTAMP(<replaceable>precision</replaceable>)
7180 LOCALTIME(<replaceable>precision</replaceable>)
7181 LOCALTIMESTAMP(<replaceable>precision</replaceable>)
7186 <function>CURRENT_TIME</function> and
7187 <function>CURRENT_TIMESTAMP</function> deliver values with time zone;
7188 <function>LOCALTIME</function> and
7189 <function>LOCALTIMESTAMP</function> deliver values without time zone.
7193 <function>CURRENT_TIME</function>,
7194 <function>CURRENT_TIMESTAMP</function>,
7195 <function>LOCALTIME</function>, and
7196 <function>LOCALTIMESTAMP</function>
7198 a precision parameter, which causes the result to be rounded
7199 to that many fractional digits in the seconds field. Without a precision parameter,
7200 the result is given to the full available precision.
7206 SELECT CURRENT_TIME;
7207 <lineannotation>Result: </lineannotation><computeroutput>14:39:53.662522-05</computeroutput>
7209 SELECT CURRENT_DATE;
7210 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23</computeroutput>
7212 SELECT CURRENT_TIMESTAMP;
7213 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522-05</computeroutput>
7215 SELECT CURRENT_TIMESTAMP(2);
7216 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.66-05</computeroutput>
7218 SELECT LOCALTIMESTAMP;
7219 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522</computeroutput>
7224 Since these functions return
7225 the start time of the current transaction, their values do not
7226 change during the transaction. This is considered a feature:
7227 the intent is to allow a single transaction to have a consistent
7228 notion of the <quote>current</quote> time, so that multiple
7229 modifications within the same transaction bear the same
7235 Other database systems might advance these values more
7241 <productname>PostgreSQL</productname> also provides functions that
7242 return the start time of the current statement, as well as the actual
7243 current time at the instant the function is called. The complete list
7244 of non-SQL-standard time functions is:
7246 transaction_timestamp()
7247 statement_timestamp()
7255 <function>transaction_timestamp()</> is equivalent to
7256 <function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
7258 <function>statement_timestamp()</> returns the start time of the current
7259 statement (more specifically, the time of receipt of the latest command
7260 message from the client).
7261 <function>statement_timestamp()</> and <function>transaction_timestamp()</>
7262 return the same value during the first command of a transaction, but might
7263 differ during subsequent commands.
7264 <function>clock_timestamp()</> returns the actual current time, and
7265 therefore its value changes even within a single SQL command.
7266 <function>timeofday()</> is a historical
7267 <productname>PostgreSQL</productname> function. Like
7268 <function>clock_timestamp()</>, it returns the actual current time,
7269 but as a formatted <type>text</> string rather than a <type>timestamp
7270 with time zone</> value.
7271 <function>now()</> is a traditional <productname>PostgreSQL</productname>
7272 equivalent to <function>transaction_timestamp()</function>.
7276 All the date/time data types also accept the special literal value
7277 <literal>now</literal> to specify the current date and time (again,
7278 interpreted as the transaction start time). Thus,
7279 the following three all return the same result:
7281 SELECT CURRENT_TIMESTAMP;
7283 SELECT TIMESTAMP 'now'; -- incorrect for use with DEFAULT
7289 You do not want to use the third form when specifying a <literal>DEFAULT</>
7290 clause while creating a table. The system will convert <literal>now</literal>
7291 to a <type>timestamp</type> as soon as the constant is parsed, so that when
7292 the default value is needed,
7293 the time of the table creation would be used! The first two
7294 forms will not be evaluated until the default value is used,
7295 because they are function calls. Thus they will give the desired
7296 behavior of defaulting to the time of row insertion.
7301 <sect2 id="functions-datetime-delay">
7302 <title>Delaying Execution</title>
7305 <primary>pg_sleep</primary>
7308 <primary>sleep</primary>
7311 <primary>delay</primary>
7315 The following function is available to delay execution of the server
7318 pg_sleep(<replaceable>seconds</replaceable>)
7321 <function>pg_sleep</function> makes the current session's process
7322 sleep until <replaceable>seconds</replaceable> seconds have
7323 elapsed. <replaceable>seconds</replaceable> is a value of type
7324 <type>double precision</>, so fractional-second delays can be specified.
7328 SELECT pg_sleep(1.5);
7334 The effective resolution of the sleep interval is platform-specific;
7335 0.01 seconds is a common value. The sleep delay will be at least as long
7336 as specified. It might be longer depending on factors such as server load.
7342 Make sure that your session does not hold more locks than necessary
7343 when calling <function>pg_sleep</function>. Otherwise other sessions
7344 might have to wait for your sleeping process, slowing down the entire
7353 <sect1 id="functions-enum">
7354 <title>Enum Support Functions</title>
7357 For enum types (described in <xref linkend="datatype-enum">),
7358 there are several functions that allow cleaner programming without
7359 hard-coding particular values of an enum type.
7360 These are listed in <xref linkend="functions-enum-table">. The examples
7361 assume an enum type created as:
7364 CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
7369 <table id="functions-enum-table">
7370 <title>Enum Support Functions</title>
7374 <entry>Function</entry>
7375 <entry>Description</entry>
7376 <entry>Example</entry>
7377 <entry>Example Result</entry>
7384 <primary>enum_first</primary>
7386 <literal>enum_first(anyenum)</literal>
7388 <entry>Returns the first value of the input enum type</entry>
7389 <entry><literal>enum_first(null::rainbow)</literal></entry>
7390 <entry><literal>red</literal></entry>
7395 <primary>enum_last</primary>
7397 <literal>enum_last(anyenum)</literal>
7399 <entry>Returns the last value of the input enum type</entry>
7400 <entry><literal>enum_last(null::rainbow)</literal></entry>
7401 <entry><literal>purple</literal></entry>
7406 <primary>enum_range</primary>
7408 <literal>enum_range(anyenum)</literal>
7410 <entry>Returns all values of the input enum type in an ordered array</entry>
7411 <entry><literal>enum_range(null::rainbow)</literal></entry>
7412 <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
7415 <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry>
7416 <entry morerows="2">
7417 Returns the range between the two given enum values, as an ordered
7418 array. The values must be from the same enum type. If the first
7419 parameter is null, the result will start with the first value of
7421 If the second parameter is null, the result will end with the last
7422 value of the enum type.
7424 <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
7425 <entry><literal>{orange,yellow,green}</literal></entry>
7428 <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
7429 <entry><literal>{red,orange,yellow,green}</literal></entry>
7432 <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
7433 <entry><literal>{orange,yellow,green,blue,purple}</literal></entry>
7440 Notice that except for the two-argument form of <function>enum_range</>,
7441 these functions disregard the specific value passed to them; they care
7442 only about its declared data type. Either null or a specific value of
7443 the type can be passed, with the same result. It is more common to
7444 apply these functions to a table column or function argument than to
7445 a hardwired type name as suggested by the examples.
7449 <sect1 id="functions-geometry">
7450 <title>Geometric Functions and Operators</title>
7453 The geometric types <type>point</type>, <type>box</type>,
7454 <type>lseg</type>, <type>line</type>, <type>path</type>,
7455 <type>polygon</type>, and <type>circle</type> have a large set of
7456 native support functions and operators, shown in <xref
7457 linkend="functions-geometry-op-table">, <xref
7458 linkend="functions-geometry-func-table">, and <xref
7459 linkend="functions-geometry-conv-table">.
7464 Note that the <quote>same as</> operator, <literal>~=</>, represents
7465 the usual notion of equality for the <type>point</type>,
7466 <type>box</type>, <type>polygon</type>, and <type>circle</type> types.
7467 Some of these types also have an <literal>=</> operator, but
7468 <literal>=</> compares
7469 for equal <emphasis>areas</> only. The other scalar comparison operators
7470 (<literal><=</> and so on) likewise compare areas for these types.
7474 <table id="functions-geometry-op-table">
7475 <title>Geometric Operators</title>
7479 <entry>Operator</entry>
7480 <entry>Description</entry>
7481 <entry>Example</entry>
7486 <entry> <literal>+</literal> </entry>
7487 <entry>Translation</entry>
7488 <entry><literal>box '((0,0),(1,1))' + point '(2.0,0)'</literal></entry>
7491 <entry> <literal>-</literal> </entry>
7492 <entry>Translation</entry>
7493 <entry><literal>box '((0,0),(1,1))' - point '(2.0,0)'</literal></entry>
7496 <entry> <literal>*</literal> </entry>
7497 <entry>Scaling/rotation</entry>
7498 <entry><literal>box '((0,0),(1,1))' * point '(2.0,0)'</literal></entry>
7501 <entry> <literal>/</literal> </entry>
7502 <entry>Scaling/rotation</entry>
7503 <entry><literal>box '((0,0),(2,2))' / point '(2.0,0)'</literal></entry>
7506 <entry> <literal>#</literal> </entry>
7507 <entry>Point or box of intersection</entry>
7508 <entry><literal>'((1,-1),(-1,1))' # '((1,1),(-1,-1))'</literal></entry>
7511 <entry> <literal>#</literal> </entry>
7512 <entry>Number of points in path or polygon</entry>
7513 <entry><literal># '((1,0),(0,1),(-1,0))'</literal></entry>
7516 <entry> <literal>@-@</literal> </entry>
7517 <entry>Length or circumference</entry>
7518 <entry><literal>@-@ path '((0,0),(1,0))'</literal></entry>
7521 <entry> <literal>@@</literal> </entry>
7522 <entry>Center</entry>
7523 <entry><literal>@@ circle '((0,0),10)'</literal></entry>
7526 <entry> <literal>##</literal> </entry>
7527 <entry>Closest point to first operand on second operand</entry>
7528 <entry><literal>point '(0,0)' ## lseg '((2,0),(0,2))'</literal></entry>
7531 <entry> <literal><-></literal> </entry>
7532 <entry>Distance between</entry>
7533 <entry><literal>circle '((0,0),1)' <-> circle '((5,0),1)'</literal></entry>
7536 <entry> <literal>&&</literal> </entry>
7537 <entry>Overlaps? (One point in common makes this true.)</entry>
7538 <entry><literal>box '((0,0),(1,1))' && box '((0,0),(2,2))'</literal></entry>
7541 <entry> <literal><<</literal> </entry>
7542 <entry>Is strictly left of?</entry>
7543 <entry><literal>circle '((0,0),1)' << circle '((5,0),1)'</literal></entry>
7546 <entry> <literal>>></literal> </entry>
7547 <entry>Is strictly right of?</entry>
7548 <entry><literal>circle '((5,0),1)' >> circle '((0,0),1)'</literal></entry>
7551 <entry> <literal>&<</literal> </entry>
7552 <entry>Does not extend to the right of?</entry>
7553 <entry><literal>box '((0,0),(1,1))' &< box '((0,0),(2,2))'</literal></entry>
7556 <entry> <literal>&></literal> </entry>
7557 <entry>Does not extend to the left of?</entry>
7558 <entry><literal>box '((0,0),(3,3))' &> box '((0,0),(2,2))'</literal></entry>
7561 <entry> <literal><<|</literal> </entry>
7562 <entry>Is strictly below?</entry>
7563 <entry><literal>box '((0,0),(3,3))' <<| box '((3,4),(5,5))'</literal></entry>
7566 <entry> <literal>|>></literal> </entry>
7567 <entry>Is strictly above?</entry>
7568 <entry><literal>box '((3,4),(5,5))' |>> box '((0,0),(3,3))'</literal></entry>
7571 <entry> <literal>&<|</literal> </entry>
7572 <entry>Does not extend above?</entry>
7573 <entry><literal>box '((0,0),(1,1))' &<| box '((0,0),(2,2))'</literal></entry>
7576 <entry> <literal>|&></literal> </entry>
7577 <entry>Does not extend below?</entry>
7578 <entry><literal>box '((0,0),(3,3))' |&> box '((0,0),(2,2))'</literal></entry>
7581 <entry> <literal><^</literal> </entry>
7582 <entry>Is below (allows touching)?</entry>
7583 <entry><literal>circle '((0,0),1)' <^ circle '((0,5),1)'</literal></entry>
7586 <entry> <literal>>^</literal> </entry>
7587 <entry>Is above (allows touching)?</entry>
7588 <entry><literal>circle '((0,5),1)' >^ circle '((0,0),1)'</literal></entry>
7591 <entry> <literal>?#</literal> </entry>
7592 <entry>Intersects?</entry>
7593 <entry><literal>lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))'</literal></entry>
7596 <entry> <literal>?-</literal> </entry>
7597 <entry>Is horizontal?</entry>
7598 <entry><literal>?- lseg '((-1,0),(1,0))'</literal></entry>
7601 <entry> <literal>?-</literal> </entry>
7602 <entry>Are horizontally aligned?</entry>
7603 <entry><literal>point '(1,0)' ?- point '(0,0)'</literal></entry>
7606 <entry> <literal>?|</literal> </entry>
7607 <entry>Is vertical?</entry>
7608 <entry><literal>?| lseg '((-1,0),(1,0))'</literal></entry>
7611 <entry> <literal>?|</literal> </entry>
7612 <entry>Are vertically aligned?</entry>
7613 <entry><literal>point '(0,1)' ?| point '(0,0)'</literal></entry>
7616 <entry> <literal>?-|</literal> </entry>
7617 <entry>Is perpendicular?</entry>
7618 <entry><literal>lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))'</literal></entry>
7621 <entry> <literal>?||</literal> </entry>
7622 <entry>Are parallel?</entry>
7623 <entry><literal>lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))'</literal></entry>
7626 <entry> <literal>@></literal> </entry>
7627 <entry>Contains?</entry>
7628 <entry><literal>circle '((0,0),2)' @> point '(1,1)'</literal></entry>
7631 <entry> <literal><@</literal> </entry>
7632 <entry>Contained in or on?</entry>
7633 <entry><literal>point '(1,1)' <@ circle '((0,0),2)'</literal></entry>
7636 <entry> <literal>~=</literal> </entry>
7637 <entry>Same as?</entry>
7638 <entry><literal>polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'</literal></entry>
7646 Before <productname>PostgreSQL</productname> 8.2, the containment
7647 operators <literal>@></> and <literal><@</> were respectively
7648 called <literal>~</> and <literal>@</>. These names are still
7649 available, but are deprecated and will eventually be removed.
7654 <primary>area</primary>
7657 <primary>center</primary>
7660 <primary>diameter</primary>
7663 <primary>height</primary>
7666 <primary>isclosed</primary>
7669 <primary>isopen</primary>
7672 <primary>length</primary>
7675 <primary>npoints</primary>
7678 <primary>pclose</primary>
7681 <primary>popen</primary>
7684 <primary>radius</primary>
7687 <primary>width</primary>
7690 <table id="functions-geometry-func-table">
7691 <title>Geometric Functions</title>
7695 <entry>Function</entry>
7696 <entry>Return Type</entry>
7697 <entry>Description</entry>
7698 <entry>Example</entry>
7703 <entry><literal><function>area(<replaceable>object</>)</function></literal></entry>
7704 <entry><type>double precision</type></entry>
7706 <entry><literal>area(box '((0,0),(1,1))')</literal></entry>
7709 <entry><literal><function>center(<replaceable>object</>)</function></literal></entry>
7710 <entry><type>point</type></entry>
7711 <entry>center</entry>
7712 <entry><literal>center(box '((0,0),(1,2))')</literal></entry>
7715 <entry><literal><function>diameter(<type>circle</>)</function></literal></entry>
7716 <entry><type>double precision</type></entry>
7717 <entry>diameter of circle</entry>
7718 <entry><literal>diameter(circle '((0,0),2.0)')</literal></entry>
7721 <entry><literal><function>height(<type>box</>)</function></literal></entry>
7722 <entry><type>double precision</type></entry>
7723 <entry>vertical size of box</entry>
7724 <entry><literal>height(box '((0,0),(1,1))')</literal></entry>
7727 <entry><literal><function>isclosed(<type>path</>)</function></literal></entry>
7728 <entry><type>boolean</type></entry>
7729 <entry>a closed path?</entry>
7730 <entry><literal>isclosed(path '((0,0),(1,1),(2,0))')</literal></entry>
7733 <entry><literal><function>isopen(<type>path</>)</function></literal></entry>
7734 <entry><type>boolean</type></entry>
7735 <entry>an open path?</entry>
7736 <entry><literal>isopen(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7739 <entry><literal><function>length(<replaceable>object</>)</function></literal></entry>
7740 <entry><type>double precision</type></entry>
7741 <entry>length</entry>
7742 <entry><literal>length(path '((-1,0),(1,0))')</literal></entry>
7745 <entry><literal><function>npoints(<type>path</>)</function></literal></entry>
7746 <entry><type>int</type></entry>
7747 <entry>number of points</entry>
7748 <entry><literal>npoints(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7751 <entry><literal><function>npoints(<type>polygon</>)</function></literal></entry>
7752 <entry><type>int</type></entry>
7753 <entry>number of points</entry>
7754 <entry><literal>npoints(polygon '((1,1),(0,0))')</literal></entry>
7757 <entry><literal><function>pclose(<type>path</>)</function></literal></entry>
7758 <entry><type>path</type></entry>
7759 <entry>convert path to closed</entry>
7760 <entry><literal>pclose(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7763 <!-- Not defined by this name. Implements the intersection operator '#' -->
7765 <entry><literal><function>point(<type>lseg</>, <type>lseg</>)</function></literal></entry>
7766 <entry><type>point</type></entry>
7767 <entry>intersection</entry>
7768 <entry><literal>point(lseg '((-1,0),(1,0))',lseg '((-2,-2),(2,2))')</literal></entry>
7772 <entry><literal><function>popen(<type>path</>)</function></literal></entry>
7773 <entry><type>path</type></entry>
7774 <entry>convert path to open</entry>
7775 <entry><literal>popen(path '((0,0),(1,1),(2,0))')</literal></entry>
7778 <entry><literal><function>radius(<type>circle</type>)</function></literal></entry>
7779 <entry><type>double precision</type></entry>
7780 <entry>radius of circle</entry>
7781 <entry><literal>radius(circle '((0,0),2.0)')</literal></entry>
7784 <entry><literal><function>width(<type>box</>)</function></literal></entry>
7785 <entry><type>double precision</type></entry>
7786 <entry>horizontal size of box</entry>
7787 <entry><literal>width(box '((0,0),(1,1))')</literal></entry>
7793 <table id="functions-geometry-conv-table">
7794 <title>Geometric Type Conversion Functions</title>
7798 <entry>Function</entry>
7799 <entry>Return Type</entry>
7800 <entry>Description</entry>
7801 <entry>Example</entry>
7808 <primary>box</primary>
7810 <literal><function>box(<type>circle</type>)</function></literal>
7812 <entry><type>box</type></entry>
7813 <entry>circle to box</entry>
7814 <entry><literal>box(circle '((0,0),2.0)')</literal></entry>
7817 <entry><literal><function>box(<type>point</type>, <type>point</type>)</function></literal></entry>
7818 <entry><type>box</type></entry>
7819 <entry>points to box</entry>
7820 <entry><literal>box(point '(0,0)', point '(1,1)')</literal></entry>
7823 <entry><literal><function>box(<type>polygon</type>)</function></literal></entry>
7824 <entry><type>box</type></entry>
7825 <entry>polygon to box</entry>
7826 <entry><literal>box(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7831 <primary>circle</primary>
7833 <literal><function>circle(<type>box</type>)</function></literal>
7835 <entry><type>circle</type></entry>
7836 <entry>box to circle</entry>
7837 <entry><literal>circle(box '((0,0),(1,1))')</literal></entry>
7840 <entry><literal><function>circle(<type>point</type>, <type>double precision</type>)</function></literal></entry>
7841 <entry><type>circle</type></entry>
7842 <entry>center and radius to circle</entry>
7843 <entry><literal>circle(point '(0,0)', 2.0)</literal></entry>
7846 <entry><literal><function>circle(<type>polygon</type>)</function></literal></entry>
7847 <entry><type>circle</type></entry>
7848 <entry>polygon to circle</entry>
7849 <entry><literal>circle(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7854 <primary>lseg</primary>
7856 <literal><function>lseg(<type>box</type>)</function></literal>
7858 <entry><type>lseg</type></entry>
7859 <entry>box diagonal to line segment</entry>
7860 <entry><literal>lseg(box '((-1,0),(1,0))')</literal></entry>
7863 <entry><literal><function>lseg(<type>point</type>, <type>point</type>)</function></literal></entry>
7864 <entry><type>lseg</type></entry>
7865 <entry>points to line segment</entry>
7866 <entry><literal>lseg(point '(-1,0)', point '(1,0)')</literal></entry>
7871 <primary>path</primary>
7873 <literal><function>path(<type>polygon</type>)</function></literal>
7875 <entry><type>point</type></entry>
7876 <entry>polygon to path</entry>
7877 <entry><literal>path(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7882 <primary>point</primary>
7884 <literal><function>point</function>(<type>double
7885 precision</type>, <type>double precision</type>)</literal>
7887 <entry><type>point</type></entry>
7888 <entry>construct point</entry>
7889 <entry><literal>point(23.4, -44.5)</literal></entry>
7892 <entry><literal><function>point(<type>box</type>)</function></literal></entry>
7893 <entry><type>point</type></entry>
7894 <entry>center of box</entry>
7895 <entry><literal>point(box '((-1,0),(1,0))')</literal></entry>
7898 <entry><literal><function>point(<type>circle</type>)</function></literal></entry>
7899 <entry><type>point</type></entry>
7900 <entry>center of circle</entry>
7901 <entry><literal>point(circle '((0,0),2.0)')</literal></entry>
7904 <entry><literal><function>point(<type>lseg</type>)</function></literal></entry>
7905 <entry><type>point</type></entry>
7906 <entry>center of line segment</entry>
7907 <entry><literal>point(lseg '((-1,0),(1,0))')</literal></entry>
7910 <entry><literal><function>point(<type>polygon</type>)</function></literal></entry>
7911 <entry><type>point</type></entry>
7912 <entry>center of polygon</entry>
7913 <entry><literal>point(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7918 <primary>polygon</primary>
7920 <literal><function>polygon(<type>box</type>)</function></literal>
7922 <entry><type>polygon</type></entry>
7923 <entry>box to 4-point polygon</entry>
7924 <entry><literal>polygon(box '((0,0),(1,1))')</literal></entry>
7927 <entry><literal><function>polygon(<type>circle</type>)</function></literal></entry>
7928 <entry><type>polygon</type></entry>
7929 <entry>circle to 12-point polygon</entry>
7930 <entry><literal>polygon(circle '((0,0),2.0)')</literal></entry>
7933 <entry><literal><function>polygon(<replaceable class="parameter">npts</replaceable>, <type>circle</type>)</function></literal></entry>
7934 <entry><type>polygon</type></entry>
7935 <entry>circle to <replaceable class="parameter">npts</replaceable>-point polygon</entry>
7936 <entry><literal>polygon(12, circle '((0,0),2.0)')</literal></entry>
7939 <entry><literal><function>polygon(<type>path</type>)</function></literal></entry>
7940 <entry><type>polygon</type></entry>
7941 <entry>path to polygon</entry>
7942 <entry><literal>polygon(path '((0,0),(1,1),(2,0))')</literal></entry>
7949 It is possible to access the two component numbers of a <type>point</>
7950 as though the point were an array with indexes 0 and 1. For example, if
7951 <literal>t.p</> is a <type>point</> column then
7952 <literal>SELECT p[0] FROM t</> retrieves the X coordinate and
7953 <literal>UPDATE t SET p[1] = ...</> changes the Y coordinate.
7954 In the same way, a value of type <type>box</> or <type>lseg</> can be treated
7955 as an array of two <type>point</> values.
7959 The <function>area</function> function works for the types
7960 <type>box</type>, <type>circle</type>, and <type>path</type>.
7961 The <function>area</function> function only works on the
7962 <type>path</type> data type if the points in the
7963 <type>path</type> are non-intersecting. For example, the
7965 <literal>'((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH</literal>
7966 will not work; however, the following visually identical
7968 <literal>'((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH</literal>
7969 will work. If the concept of an intersecting versus
7970 non-intersecting <type>path</type> is confusing, draw both of the
7971 above <type>path</type>s side by side on a piece of graph paper.
7977 <sect1 id="functions-net">
7978 <title>Network Address Functions and Operators</title>
7981 <xref linkend="cidr-inet-operators-table"> shows the operators
7982 available for the <type>cidr</type> and <type>inet</type> types.
7983 The operators <literal><<</literal>,
7984 <literal><<=</literal>, <literal>>></literal>, and
7985 <literal>>>=</literal> test for subnet inclusion. They
7986 consider only the network parts of the two addresses (ignoring any
7987 host part) and determine whether one network is identical to
7988 or a subnet of the other.
7991 <table id="cidr-inet-operators-table">
7992 <title><type>cidr</type> and <type>inet</type> Operators</title>
7996 <entry>Operator</entry>
7997 <entry>Description</entry>
7998 <entry>Example</entry>
8003 <entry> <literal><</literal> </entry>
8004 <entry>is less than</entry>
8005 <entry><literal>inet '192.168.1.5' < inet '192.168.1.6'</literal></entry>
8008 <entry> <literal><=</literal> </entry>
8009 <entry>is less than or equal</entry>
8010 <entry><literal>inet '192.168.1.5' <= inet '192.168.1.5'</literal></entry>
8013 <entry> <literal>=</literal> </entry>
8014 <entry>equals</entry>
8015 <entry><literal>inet '192.168.1.5' = inet '192.168.1.5'</literal></entry>
8018 <entry> <literal>>=</literal> </entry>
8019 <entry>is greater or equal</entry>
8020 <entry><literal>inet '192.168.1.5' >= inet '192.168.1.5'</literal></entry>
8023 <entry> <literal>></literal> </entry>
8024 <entry>is greater than</entry>
8025 <entry><literal>inet '192.168.1.5' > inet '192.168.1.4'</literal></entry>
8028 <entry> <literal><></literal> </entry>
8029 <entry>is not equal</entry>
8030 <entry><literal>inet '192.168.1.5' <> inet '192.168.1.4'</literal></entry>
8033 <entry> <literal><<</literal> </entry>
8034 <entry>is contained within</entry>
8035 <entry><literal>inet '192.168.1.5' << inet '192.168.1/24'</literal></entry>
8038 <entry> <literal><<=</literal> </entry>
8039 <entry>is contained within or equals</entry>
8040 <entry><literal>inet '192.168.1/24' <<= inet '192.168.1/24'</literal></entry>
8043 <entry> <literal>>></literal> </entry>
8044 <entry>contains</entry>
8045 <entry><literal>inet '192.168.1/24' >> inet '192.168.1.5'</literal></entry>
8048 <entry> <literal>>>=</literal> </entry>
8049 <entry>contains or equals</entry>
8050 <entry><literal>inet '192.168.1/24' >>= inet '192.168.1/24'</literal></entry>
8053 <entry> <literal>~</literal> </entry>
8054 <entry>bitwise NOT</entry>
8055 <entry><literal>~ inet '192.168.1.6'</literal></entry>
8058 <entry> <literal>&</literal> </entry>
8059 <entry>bitwise AND</entry>
8060 <entry><literal>inet '192.168.1.6' & inet '0.0.0.255'</literal></entry>
8063 <entry> <literal>|</literal> </entry>
8064 <entry>bitwise OR</entry>
8065 <entry><literal>inet '192.168.1.6' | inet '0.0.0.255'</literal></entry>
8068 <entry> <literal>+</literal> </entry>
8069 <entry>addition</entry>
8070 <entry><literal>inet '192.168.1.6' + 25</literal></entry>
8073 <entry> <literal>-</literal> </entry>
8074 <entry>subtraction</entry>
8075 <entry><literal>inet '192.168.1.43' - 36</literal></entry>
8078 <entry> <literal>-</literal> </entry>
8079 <entry>subtraction</entry>
8080 <entry><literal>inet '192.168.1.43' - inet '192.168.1.19'</literal></entry>
8087 <xref linkend="cidr-inet-functions-table"> shows the functions
8088 available for use with the <type>cidr</type> and <type>inet</type>
8089 types. The <function>abbrev</function>, <function>host</function>,
8090 and <function>text</function>
8091 functions are primarily intended to offer alternative display
8095 <table id="cidr-inet-functions-table">
8096 <title><type>cidr</type> and <type>inet</type> Functions</title>
8100 <entry>Function</entry>
8101 <entry>Return Type</entry>
8102 <entry>Description</entry>
8103 <entry>Example</entry>
8104 <entry>Result</entry>
8111 <primary>abbrev</primary>
8113 <literal><function>abbrev(<type>inet</type>)</function></literal>
8115 <entry><type>text</type></entry>
8116 <entry>abbreviated display format as text</entry>
8117 <entry><literal>abbrev(inet '10.1.0.0/16')</literal></entry>
8118 <entry><literal>10.1.0.0/16</literal></entry>
8121 <entry><literal><function>abbrev(<type>cidr</type>)</function></literal></entry>
8122 <entry><type>text</type></entry>
8123 <entry>abbreviated display format as text</entry>
8124 <entry><literal>abbrev(cidr '10.1.0.0/16')</literal></entry>
8125 <entry><literal>10.1/16</literal></entry>
8130 <primary>broadcast</primary>
8132 <literal><function>broadcast(<type>inet</type>)</function></literal>
8134 <entry><type>inet</type></entry>
8135 <entry>broadcast address for network</entry>
8136 <entry><literal>broadcast('192.168.1.5/24')</literal></entry>
8137 <entry><literal>192.168.1.255/24</literal></entry>
8142 <primary>family</primary>
8144 <literal><function>family(<type>inet</type>)</function></literal>
8146 <entry><type>int</type></entry>
8147 <entry>extract family of address; <literal>4</literal> for IPv4,
8148 <literal>6</literal> for IPv6</entry>
8149 <entry><literal>family('::1')</literal></entry>
8150 <entry><literal>6</literal></entry>
8155 <primary>host</primary>
8157 <literal><function>host(<type>inet</type>)</function></literal>
8159 <entry><type>text</type></entry>
8160 <entry>extract IP address as text</entry>
8161 <entry><literal>host('192.168.1.5/24')</literal></entry>
8162 <entry><literal>192.168.1.5</literal></entry>
8167 <primary>hostmask</primary>
8169 <literal><function>hostmask(<type>inet</type>)</function></literal>
8171 <entry><type>inet</type></entry>
8172 <entry>construct host mask for network</entry>
8173 <entry><literal>hostmask('192.168.23.20/30')</literal></entry>
8174 <entry><literal>0.0.0.3</literal></entry>
8179 <primary>masklen</primary>
8181 <literal><function>masklen(<type>inet</type>)</function></literal>
8183 <entry><type>int</type></entry>
8184 <entry>extract netmask length</entry>
8185 <entry><literal>masklen('192.168.1.5/24')</literal></entry>
8186 <entry><literal>24</literal></entry>
8191 <primary>netmask</primary>
8193 <literal><function>netmask(<type>inet</type>)</function></literal>
8195 <entry><type>inet</type></entry>
8196 <entry>construct netmask for network</entry>
8197 <entry><literal>netmask('192.168.1.5/24')</literal></entry>
8198 <entry><literal>255.255.255.0</literal></entry>
8203 <primary>network</primary>
8205 <literal><function>network(<type>inet</type>)</function></literal>
8207 <entry><type>cidr</type></entry>
8208 <entry>extract network part of address</entry>
8209 <entry><literal>network('192.168.1.5/24')</literal></entry>
8210 <entry><literal>192.168.1.0/24</literal></entry>
8215 <primary>set_masklen</primary>
8217 <literal><function>set_masklen(<type>inet</type>, <type>int</type>)</function></literal>
8219 <entry><type>inet</type></entry>
8220 <entry>set netmask length for <type>inet</type> value</entry>
8221 <entry><literal>set_masklen('192.168.1.5/24', 16)</literal></entry>
8222 <entry><literal>192.168.1.5/16</literal></entry>
8225 <entry><literal><function>set_masklen(<type>cidr</type>, <type>int</type>)</function></literal></entry>
8226 <entry><type>cidr</type></entry>
8227 <entry>set netmask length for <type>cidr</type> value</entry>
8228 <entry><literal>set_masklen('192.168.1.0/24'::cidr, 16)</literal></entry>
8229 <entry><literal>192.168.0.0/16</literal></entry>
8234 <primary>text</primary>
8236 <literal><function>text(<type>inet</type>)</function></literal>
8238 <entry><type>text</type></entry>
8239 <entry>extract IP address and netmask length as text</entry>
8240 <entry><literal>text(inet '192.168.1.5')</literal></entry>
8241 <entry><literal>192.168.1.5/32</literal></entry>
8248 Any <type>cidr</> value can be cast to <type>inet</> implicitly
8249 or explicitly; therefore, the functions shown above as operating on
8250 <type>inet</> also work on <type>cidr</> values. (Where there are
8251 separate functions for <type>inet</> and <type>cidr</>, it is because
8252 the behavior should be different for the two cases.)
8253 Also, it is permitted to cast an <type>inet</> value to <type>cidr</>.
8254 When this is done, any bits to the right of the netmask are silently zeroed
8255 to create a valid <type>cidr</> value.
8257 you can cast a text value to <type>inet</> or <type>cidr</>
8258 using normal casting syntax: for example,
8259 <literal>inet(<replaceable>expression</>)</literal> or
8260 <literal><replaceable>colname</>::cidr</literal>.
8264 <xref linkend="macaddr-functions-table"> shows the functions
8265 available for use with the <type>macaddr</type> type. The function
8266 <literal><function>trunc(<type>macaddr</type>)</function></literal> returns a MAC
8267 address with the last 3 bytes set to zero. This can be used to
8268 associate the remaining prefix with a manufacturer.
8271 <table id="macaddr-functions-table">
8272 <title><type>macaddr</type> Functions</title>
8276 <entry>Function</entry>
8277 <entry>Return Type</entry>
8278 <entry>Description</entry>
8279 <entry>Example</entry>
8280 <entry>Result</entry>
8287 <primary>trunc</primary>
8289 <literal><function>trunc(<type>macaddr</type>)</function></literal>
8291 <entry><type>macaddr</type></entry>
8292 <entry>set last 3 bytes to zero</entry>
8293 <entry><literal>trunc(macaddr '12:34:56:78:90:ab')</literal></entry>
8294 <entry><literal>12:34:56:00:00:00</literal></entry>
8301 The <type>macaddr</type> type also supports the standard relational
8302 operators (<literal>></literal>, <literal><=</literal>, etc.) for
8303 lexicographical ordering.
8309 <sect1 id="functions-textsearch">
8310 <title>Text Search Functions and Operators</title>
8312 <indexterm zone="datatype-textsearch">
8313 <primary>full text search</primary>
8314 <secondary>functions and operators</secondary>
8317 <indexterm zone="datatype-textsearch">
8318 <primary>text search</primary>
8319 <secondary>functions and operators</secondary>
8323 <xref linkend="textsearch-operators-table">,
8324 <xref linkend="textsearch-functions-table"> and
8325 <xref linkend="textsearch-functions-debug-table">
8326 summarize the functions and operators that are provided
8327 for full text searching. See <xref linkend="textsearch"> for a detailed
8328 explanation of <productname>PostgreSQL</productname>'s text search
8332 <table id="textsearch-operators-table">
8333 <title>Text Search Operators</title>
8337 <entry>Operator</entry>
8338 <entry>Description</entry>
8339 <entry>Example</entry>
8340 <entry>Result</entry>
8345 <entry> <literal>@@</literal> </entry>
8346 <entry><type>tsvector</> matches <type>tsquery</> ?</entry>
8347 <entry><literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')</literal></entry>
8348 <entry><literal>t</literal></entry>
8351 <entry> <literal>@@@</literal> </entry>
8352 <entry>deprecated synonym for <literal>@@</></entry>
8353 <entry><literal>to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat')</literal></entry>
8354 <entry><literal>t</literal></entry>
8357 <entry> <literal>||</literal> </entry>
8358 <entry>concatenate <type>tsvector</>s</entry>
8359 <entry><literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal></entry>
8360 <entry><literal>'a':1 'b':2,5 'c':3 'd':4</literal></entry>
8363 <entry> <literal>&&</literal> </entry>
8364 <entry>AND <type>tsquery</>s together</entry>
8365 <entry><literal>'fat | rat'::tsquery && 'cat'::tsquery</literal></entry>
8366 <entry><literal>( 'fat' | 'rat' ) & 'cat'</literal></entry>
8369 <entry> <literal>||</literal> </entry>
8370 <entry>OR <type>tsquery</>s together</entry>
8371 <entry><literal>'fat | rat'::tsquery || 'cat'::tsquery</literal></entry>
8372 <entry><literal>( 'fat' | 'rat' ) | 'cat'</literal></entry>
8375 <entry> <literal>!!</literal> </entry>
8376 <entry>negate a <type>tsquery</></entry>
8377 <entry><literal>!! 'cat'::tsquery</literal></entry>
8378 <entry><literal>!'cat'</literal></entry>
8381 <entry> <literal>@></literal> </entry>
8382 <entry><type>tsquery</> contains another ?</entry>
8383 <entry><literal>'cat'::tsquery @> 'cat & rat'::tsquery</literal></entry>
8384 <entry><literal>f</literal></entry>
8387 <entry> <literal><@</literal> </entry>
8388 <entry><type>tsquery</> is contained in ?</entry>
8389 <entry><literal>'cat'::tsquery <@ 'cat & rat'::tsquery</literal></entry>
8390 <entry><literal>t</literal></entry>
8398 The <type>tsquery</> containment operators consider only the lexemes
8399 listed in the two queries, ignoring the combining operators.
8404 In addition to the operators shown in the table, the ordinary B-tree
8405 comparison operators (<literal>=</>, <literal><</>, etc) are defined
8406 for types <type>tsvector</> and <type>tsquery</>. These are not very
8407 useful for text searching but allow, for example, unique indexes to be
8408 built on columns of these types.
8411 <table id="textsearch-functions-table">
8412 <title>Text Search Functions</title>
8416 <entry>Function</entry>
8417 <entry>Return Type</entry>
8418 <entry>Description</entry>
8419 <entry>Example</entry>
8420 <entry>Result</entry>
8427 <primary>get_current_ts_config</primary>
8429 <literal><function>get_current_ts_config()</function></literal>
8431 <entry><type>regconfig</type></entry>
8432 <entry>get default text search configuration</entry>
8433 <entry><literal>get_current_ts_config()</literal></entry>
8434 <entry><literal>english</literal></entry>
8439 <primary>length</primary>
8441 <literal><function>length(<type>tsvector</>)</function></literal>
8443 <entry><type>integer</type></entry>
8444 <entry>number of lexemes in <type>tsvector</></entry>
8445 <entry><literal>length('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
8446 <entry><literal>3</literal></entry>
8451 <primary>numnode</primary>
8453 <literal><function>numnode(<type>tsquery</>)</function></literal>
8455 <entry><type>integer</type></entry>
8456 <entry>number of lexemes plus operators in <type>tsquery</></entry>
8457 <entry><literal> numnode('(fat & rat) | cat'::tsquery)</literal></entry>
8458 <entry><literal>5</literal></entry>
8463 <primary>plainto_tsquery</primary>
8465 <literal><function>plainto_tsquery(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</function></literal>
8467 <entry><type>tsquery</type></entry>
8468 <entry>produce <type>tsquery</> ignoring punctuation</entry>
8469 <entry><literal>plainto_tsquery('english', 'The Fat Rats')</literal></entry>
8470 <entry><literal>'fat' & 'rat'</literal></entry>
8475 <primary>querytree</primary>
8477 <literal><function>querytree(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>)</function></literal>
8479 <entry><type>text</type></entry>
8480 <entry>get indexable part of a <type>tsquery</></entry>
8481 <entry><literal>querytree('foo & ! bar'::tsquery)</literal></entry>
8482 <entry><literal>'foo'</literal></entry>
8487 <primary>setweight</primary>
8489 <literal><function>setweight(<type>tsvector</>, <type>"char"</>)</function></literal>
8491 <entry><type>tsvector</type></entry>
8492 <entry>assign weight to each element of <type>tsvector</></entry>
8493 <entry><literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</literal></entry>
8494 <entry><literal>'cat':3A 'fat':2A,4A 'rat':5A</literal></entry>
8499 <primary>strip</primary>
8501 <literal><function>strip(<type>tsvector</>)</function></literal>
8503 <entry><type>tsvector</type></entry>
8504 <entry>remove positions and weights from <type>tsvector</></entry>
8505 <entry><literal>strip('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
8506 <entry><literal>'cat' 'fat' 'rat'</literal></entry>
8511 <primary>to_tsquery</primary>
8513 <literal><function>to_tsquery(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</function></literal>
8515 <entry><type>tsquery</type></entry>
8516 <entry>normalize words and convert to <type>tsquery</></entry>
8517 <entry><literal>to_tsquery('english', 'The & Fat & Rats')</literal></entry>
8518 <entry><literal>'fat' & 'rat'</literal></entry>
8523 <primary>to_tsvector</primary>
8525 <literal><function>to_tsvector(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">document</> <type>text</type>)</function></literal>
8527 <entry><type>tsvector</type></entry>
8528 <entry>reduce document text to <type>tsvector</></entry>
8529 <entry><literal>to_tsvector('english', 'The Fat Rats')</literal></entry>
8530 <entry><literal>'fat':2 'rat':3</literal></entry>
8535 <primary>ts_headline</primary>
8537 <literal><function>ts_headline(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">document</replaceable> <type>text</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">options</replaceable> <type>text</> </optional>)</function></literal>
8539 <entry><type>text</type></entry>
8540 <entry>display a query match</entry>
8541 <entry><literal>ts_headline('x y z', 'z'::tsquery)</literal></entry>
8542 <entry><literal>x y <b>z</b></literal></entry>
8547 <primary>ts_rank</primary>
8549 <literal><function>ts_rank(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>)</function></literal>
8551 <entry><type>float4</type></entry>
8552 <entry>rank document for query</entry>
8553 <entry><literal>ts_rank(textsearch, query)</literal></entry>
8554 <entry><literal>0.818</literal></entry>
8559 <primary>ts_rank_cd</primary>
8561 <literal><function>ts_rank_cd(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>)</function></literal>
8563 <entry><type>float4</type></entry>
8564 <entry>rank document for query using cover density</entry>
8565 <entry><literal>ts_rank_cd('{0.1, 0.2, 0.4, 1.0}', textsearch, query)</literal></entry>
8566 <entry><literal>2.01317</literal></entry>
8571 <primary>ts_rewrite</primary>
8573 <literal><function>ts_rewrite(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">target</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">substitute</replaceable> <type>tsquery</>)</function></literal>
8575 <entry><type>tsquery</type></entry>
8576 <entry>replace target with substitute within query</entry>
8577 <entry><literal>ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal></entry>
8578 <entry><literal>'b' & ( 'foo' | 'bar' )</literal></entry>
8581 <entry><literal><function>ts_rewrite(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">select</replaceable> <type>text</>)</function></literal></entry>
8582 <entry><type>tsquery</type></entry>
8583 <entry>replace using targets and substitutes from a <command>SELECT</> command</entry>
8584 <entry><literal>SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')</literal></entry>
8585 <entry><literal>'b' & ( 'foo' | 'bar' )</literal></entry>
8590 <primary>tsvector_update_trigger</primary>
8592 <literal><function>tsvector_update_trigger()</function></literal>
8594 <entry><type>trigger</type></entry>
8595 <entry>trigger function for automatic <type>tsvector</> column update</entry>
8596 <entry><literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal></entry>
8597 <entry><literal></literal></entry>
8602 <primary>tsvector_update_trigger_column</primary>
8604 <literal><function>tsvector_update_trigger_column()</function></literal>
8606 <entry><type>trigger</type></entry>
8607 <entry>trigger function for automatic <type>tsvector</> column update</entry>
8608 <entry><literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, configcol, title, body)</literal></entry>
8609 <entry><literal></literal></entry>
8617 All the text search functions that accept an optional <type>regconfig</>
8618 argument will use the configuration specified by
8619 <xref linkend="guc-default-text-search-config">
8620 when that argument is omitted.
8626 <xref linkend="textsearch-functions-debug-table">
8627 are listed separately because they are not usually used in everyday text
8628 searching operations. They are helpful for development and debugging
8629 of new text search configurations.
8632 <table id="textsearch-functions-debug-table">
8633 <title>Text Search Debugging Functions</title>
8637 <entry>Function</entry>
8638 <entry>Return Type</entry>
8639 <entry>Description</entry>
8640 <entry>Example</entry>
8641 <entry>Result</entry>
8648 <primary>ts_debug</primary>
8650 <literal><function>ts_debug(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>, OUT <replaceable class="PARAMETER">token</> <type>text</>, OUT <replaceable class="PARAMETER">dictionaries</> <type>regdictionary[]</>, OUT <replaceable class="PARAMETER">dictionary</> <type>regdictionary</>, OUT <replaceable class="PARAMETER">lexemes</> <type>text[]</>)</function></literal>
8652 <entry><type>setof record</type></entry>
8653 <entry>test a configuration</entry>
8654 <entry><literal>ts_debug('english', 'The Brightest supernovaes')</literal></entry>
8655 <entry><literal>(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</literal></entry>
8660 <primary>ts_lexize</primary>
8662 <literal><function>ts_lexize(<replaceable class="PARAMETER">dict</replaceable> <type>regdictionary</>, <replaceable class="PARAMETER">token</replaceable> <type>text</>)</function></literal>
8664 <entry><type>text[]</type></entry>
8665 <entry>test a dictionary</entry>
8666 <entry><literal>ts_lexize('english_stem', 'stars')</literal></entry>
8667 <entry><literal>{star}</literal></entry>
8672 <primary>ts_parse</primary>
8674 <literal><function>ts_parse(<replaceable class="PARAMETER">parser_name</replaceable> <type>text</>, <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">token</> <type>text</>)</function></literal>
8676 <entry><type>setof record</type></entry>
8677 <entry>test a parser</entry>
8678 <entry><literal>ts_parse('default', 'foo - bar')</literal></entry>
8679 <entry><literal>(1,foo) ...</literal></entry>
8682 <entry><literal><function>ts_parse(<replaceable class="PARAMETER">parser_oid</replaceable> <type>oid</>, <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">token</> <type>text</>)</function></literal></entry>
8683 <entry><type>setof record</type></entry>
8684 <entry>test a parser</entry>
8685 <entry><literal>ts_parse(3722, 'foo - bar')</literal></entry>
8686 <entry><literal>(1,foo) ...</literal></entry>
8691 <primary>ts_token_type</primary>
8693 <literal><function>ts_token_type(<replaceable class="PARAMETER">parser_name</> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>)</function></literal>
8695 <entry><type>setof record</type></entry>
8696 <entry>get token types defined by parser</entry>
8697 <entry><literal>ts_token_type('default')</literal></entry>
8698 <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
8701 <entry><literal><function>ts_token_type(<replaceable class="PARAMETER">parser_oid</> <type>oid</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>)</function></literal></entry>
8702 <entry><type>setof record</type></entry>
8703 <entry>get token types defined by parser</entry>
8704 <entry><literal>ts_token_type(3722)</literal></entry>
8705 <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
8710 <primary>ts_stat</primary>
8712 <literal><function>ts_stat(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>, </optional> OUT <replaceable class="PARAMETER">word</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">ndoc</replaceable> <type>integer</>, OUT <replaceable class="PARAMETER">nentry</replaceable> <type>integer</>)</function></literal>
8714 <entry><type>setof record</type></entry>
8715 <entry>get statistics of a <type>tsvector</> column</entry>
8716 <entry><literal>ts_stat('SELECT vector from apod')</literal></entry>
8717 <entry><literal>(foo,10,15) ...</literal></entry>
8726 <sect1 id="functions-xml">
8727 <title>XML Functions</title>
8730 The functions and function-like expressions described in this
8731 section operate on values of type <type>xml</type>. Check <xref
8732 linkend="datatype-xml"> for information about the <type>xml</type>
8733 type. The function-like expressions <function>xmlparse</function>
8734 and <function>xmlserialize</function> for converting to and from
8735 type <type>xml</type> are not repeated here. Use of most of these
8736 functions requires the installation to have been built
8737 with <command>configure --with-libxml</>.
8740 <sect2 id="functions-producing-xml">
8741 <title>Producing XML Content</title>
8744 A set of functions and function-like expressions are available for
8745 producing XML content from SQL data. As such, they are
8746 particularly suitable for formatting query results into XML
8747 documents for processing in client applications.
8751 <title><literal>xmlcomment</literal></title>
8754 <primary>xmlcomment</primary>
8758 <function>xmlcomment</function>(<replaceable>text</replaceable>)
8762 The function <function>xmlcomment</function> creates an XML value
8763 containing an XML comment with the specified text as content.
8764 The text cannot contain <quote><literal>--</literal></quote> or end with a
8765 <quote><literal>-</literal></quote> so that the resulting construct is a valid
8766 XML comment. If the argument is null, the result is null.
8772 SELECT xmlcomment('hello');
8782 <title><literal>xmlconcat</literal></title>
8785 <primary>xmlconcat</primary>
8789 <function>xmlconcat</function>(<replaceable>xml</replaceable><optional>, ...</optional>)
8793 The function <function>xmlconcat</function> concatenates a list
8794 of individual XML values to create a single value containing an
8795 XML content fragment. Null values are omitted; the result is
8796 only null if there are no nonnull arguments.
8802 SELECT xmlconcat('<abc/>', '<bar>foo</bar>');
8805 ----------------------
8806 <abc/><bar>foo</bar>
8811 XML declarations, if present, are combined as follows. If all
8812 argument values have the same XML version declaration, that
8813 version is used in the result, else no version is used. If all
8814 argument values have the standalone declaration value
8815 <quote>yes</quote>, then that value is used in the result. If
8816 all argument values have a standalone declaration value and at
8817 least one is <quote>no</quote>, then that is used in the result.
8818 Else the result will have no standalone declaration. If the
8819 result is determined to require a standalone declaration but no
8820 version declaration, a version declaration with version 1.0 will
8821 be used because XML requires an XML declaration to contain a
8822 version declaration. Encoding declarations are ignored and
8823 removed in all cases.
8829 SELECT xmlconcat('<?xml version="1.1"?><foo/>', '<?xml version="1.1" standalone="no"?><bar/>');
8832 -----------------------------------
8833 <?xml version="1.1"?><foo/><bar/>
8839 <title><literal>xmlelement</literal></title>
8842 <primary>xmlelement</primary>
8846 <function>xmlelement</function>(name <replaceable>name</replaceable> <optional>, xmlattributes(<replaceable>value</replaceable> <optional>AS <replaceable>attname</replaceable></optional> <optional>, ... </optional>)</optional> <optional><replaceable>, content, ...</replaceable></optional>)
8850 The <function>xmlelement</function> expression produces an XML
8851 element with the given name, attributes, and content.
8857 SELECT xmlelement(name foo);
8863 SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
8869 SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
8872 -------------------------------------
8873 <foo bar="2007-01-26">content</foo>
8878 Element and attribute names that are not valid XML names are
8879 escaped by replacing the offending characters by the sequence
8880 <literal>_x<replaceable>HHHH</replaceable>_</literal>, where
8881 <replaceable>HHHH</replaceable> is the character's Unicode
8882 codepoint in hexadecimal notation. For example:
8884 SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&b"));
8887 ----------------------------------
8888 <foo_x0024_bar a_x0026_b="xyz"/>
8893 An explicit attribute name need not be specified if the attribute
8894 value is a column reference, in which case the column's name will
8895 be used as the attribute name by default. In other cases, the
8896 attribute must be given an explicit name. So this example is
8899 CREATE TABLE test (a xml, b xml);
8900 SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
8904 SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
8905 SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
8910 Element content, if specified, will be formatted according to
8911 its data type. If the content is itself of type <type>xml</type>,
8912 complex XML documents can be constructed. For example:
8914 SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
8915 xmlelement(name abc),
8917 xmlelement(name xyz));
8920 ----------------------------------------------
8921 <foo bar="xyz"><abc/><!--test--><xyz/></foo>
8924 Content of other types will be formatted into valid XML character
8925 data. This means in particular that the characters <, >,
8926 and & will be converted to entities. Binary data (data type
8927 <type>bytea</type>) will be represented in base64 or hex
8928 encoding, depending on the setting of the configuration parameter
8929 <xref linkend="guc-xmlbinary">. The particular behavior for
8930 individual data types is expected to evolve in order to align the
8931 SQL and PostgreSQL data types with the XML Schema specification,
8932 at which point a more precise description will appear.
8937 <title><literal>xmlforest</literal></title>
8940 <primary>xmlforest</primary>
8944 <function>xmlforest</function>(<replaceable>content</replaceable> <optional>AS <replaceable>name</replaceable></optional> <optional>, ...</optional>)
8948 The <function>xmlforest</function> expression produces an XML
8949 forest (sequence) of elements using the given names and content.
8955 SELECT xmlforest('abc' AS foo, 123 AS bar);
8958 ------------------------------
8959 <foo>abc</foo><bar>123</bar>
8962 SELECT xmlforest(table_name, column_name)
8963 FROM information_schema.columns
8964 WHERE table_schema = 'pg_catalog';
8967 -------------------------------------------------------------------------------------------
8968 <table_name>pg_authid</table_name><column_name>rolname</column_name>
8969 <table_name>pg_authid</table_name><column_name>rolsuper</column_name>
8973 As seen in the second example, the element name can be omitted if
8974 the content value is a column reference, in which case the column
8975 name is used by default. Otherwise, a name must be specified.
8979 Element names that are not valid XML names are escaped as shown
8980 for <function>xmlelement</function> above. Similarly, content
8981 data is escaped to make valid XML content, unless it is already
8982 of type <type>xml</type>.
8986 Note that XML forests are not valid XML documents if they consist
8987 of more than one element, so it might be useful to wrap
8988 <function>xmlforest</function> expressions in
8989 <function>xmlelement</function>.
8994 <title><literal>xmlpi</literal></title>
8997 <primary>xmlpi</primary>
9001 <function>xmlpi</function>(name <replaceable>target</replaceable> <optional>, <replaceable>content</replaceable></optional>)
9005 The <function>xmlpi</function> expression creates an XML
9006 processing instruction. The content, if present, must not
9007 contain the character sequence <literal>?></literal>.
9013 SELECT xmlpi(name php, 'echo "hello world";');
9016 -----------------------------
9017 <?php echo "hello world";?>
9023 <title><literal>xmlroot</literal></title>
9026 <primary>xmlroot</primary>
9030 <function>xmlroot</function>(<replaceable>xml</replaceable>, version <replaceable>text</replaceable> | no value <optional>, standalone yes|no|no value</optional>)
9034 The <function>xmlroot</function> expression alters the properties
9035 of the root node of an XML value. If a version is specified,
9036 it replaces the value in the root node's version declaration; if a
9037 standalone setting is specified, it replaces the value in the
9038 root node's standalone declaration.
9043 SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
9044 version '1.0', standalone yes);
9047 ----------------------------------------
9048 <?xml version="1.0" standalone="yes"?>
9049 <content>abc</content>
9054 <sect3 id="functions-xml-xmlagg">
9055 <title><literal>xmlagg</literal></title>
9058 <primary>xmlagg</primary>
9062 <function>xmlagg</function>(<replaceable>xml</replaceable>)
9066 The function <function>xmlagg</function> is, unlike the other
9067 functions described here, an aggregate function. It concatenates the
9068 input values to the aggregate function call,
9069 much like <function>xmlconcat</function> does, except that concatenation
9070 occurs across rows rather than across expressions in a single row.
9071 See <xref linkend="functions-aggregate"> for additional information
9072 about aggregate functions.
9078 CREATE TABLE test (y int, x xml);
9079 INSERT INTO test VALUES (1, '<foo>abc</foo>');
9080 INSERT INTO test VALUES (2, '<bar/>');
9081 SELECT xmlagg(x) FROM test;
9083 ----------------------
9084 <foo>abc</foo><bar/>
9089 To determine the order of the concatenation, an <literal>ORDER BY</>
9090 clause may be added to the aggregate call as described in
9091 <xref linkend="syntax-aggregates">. For example:
9094 SELECT xmlagg(x ORDER BY y DESC) FROM test;
9096 ----------------------
9097 <bar/><foo>abc</foo>
9102 The following non-standard approach used to be recommended
9103 in previous versions, and may still be useful in specific
9107 SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
9109 ----------------------
9110 <bar/><foo>abc</foo>
9116 <sect2 id="functions-xml-predicates">
9117 <title>XML Predicates</title>
9120 The expressions described in this section check properties
9121 of <type>xml</type> values.
9125 <title><literal>IS DOCUMENT</literal></title>
9128 <primary>IS DOCUMENT</primary>
9132 <replaceable>xml</replaceable> IS DOCUMENT
9136 The expression <literal>IS DOCUMENT</literal> returns true if the
9137 argument XML value is a proper XML document, false if it is not
9138 (that is, it is a content fragment), or null if the argument is
9139 null. See <xref linkend="datatype-xml"> about the difference
9140 between documents and content fragments.
9144 <sect3 id="xml-exists">
9145 <title><literal>XMLEXISTS</literal></title>
9148 <primary>XMLEXISTS</primary>
9152 <function>XMLEXISTS</function>(<replaceable>text</replaceable> PASSING <optional>BY REF</optional> <replaceable>xml</replaceable> <optional>BY REF</optional>)
9156 The function <function>xmlexists</function> returns true if the
9157 XPath expression in the first argument returns any nodes, and
9158 false otherwise. (If either argument is null, the result is
9165 SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY REF '<towns><town>Toronto</town><town>Ottawa</town></towns>');
9175 The <literal>BY REF</literal> clauses have no effect in
9176 PostgreSQL, but are allowed for SQL conformance and compatibility
9177 with other implementations. Per SQL standard, the
9178 first <literal>BY REF</literal> is required, the second is
9179 optional. Also note that the SQL standard specifies
9180 the <function>xmlexists</function> construct to take an XQuery
9181 expression as first argument, but PostgreSQL currently only
9182 supports XPath, which is a subset of XQuery.
9186 <sect3 id="xml-is-well-formed">
9187 <title><literal>xml_is_well_formed</literal></title>
9190 <primary>xml_is_well_formed</primary>
9194 <primary>xml_is_well_formed_document</primary>
9198 <primary>xml_is_well_formed_content</primary>
9202 <function>xml_is_well_formed</function>(<replaceable>text</replaceable>)
9203 <function>xml_is_well_formed_document</function>(<replaceable>text</replaceable>)
9204 <function>xml_is_well_formed_content</function>(<replaceable>text</replaceable>)
9208 These functions check whether a <type>text</> string is well-formed XML,
9209 returning a Boolean result.
9210 <function>xml_is_well_formed_document</function> checks for a well-formed
9211 document, while <function>xml_is_well_formed_content</function> checks
9212 for well-formed content. <function>xml_is_well_formed</function> does
9213 the former if the <xref linkend="guc-xmloption"> configuration
9214 parameter is set to <literal>DOCUMENT</>, or the latter if it is set to
9215 <literal>CONTENT</>. This means that
9216 <function>xml_is_well_formed</function> is useful for seeing whether
9217 a simple cast to type <type>xml</> will succeed, whereas the other two
9218 functions are useful for seeing whether the corresponding variants of
9219 <function>XMLPARSE</> will succeed.
9226 SET xmloption TO DOCUMENT;
9227 SELECT xml_is_well_formed('<>');
9229 --------------------
9233 SELECT xml_is_well_formed('<abc/>');
9235 --------------------
9239 SET xmloption TO CONTENT;
9240 SELECT xml_is_well_formed('abc');
9242 --------------------
9246 SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</pg:foo>');
9247 xml_is_well_formed_document
9248 -----------------------------
9252 SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</my:foo>');
9253 xml_is_well_formed_document
9254 -----------------------------
9259 The last example shows that the checks include whether
9260 namespaces are correctly matched.
9265 <sect2 id="functions-xml-processing">
9266 <title>Processing XML</title>
9269 <primary>XPath</primary>
9273 To process values of data type <type>xml</type>, PostgreSQL offers
9274 the functions <function>xpath</function> and
9275 <function>xpath_exists</function>, which evaluate XPath 1.0
9280 <function>xpath</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable> <optional>, <replaceable>nsarray</replaceable></optional>)
9284 The function <function>xpath</function> evaluates the XPath
9285 expression <replaceable>xpath</replaceable> (a <type>text</> value)
9286 against the XML value
9287 <replaceable>xml</replaceable>. It returns an array of XML values
9288 corresponding to the node set produced by the XPath expression.
9289 If the XPath expression returns a scalar value rather than a node set,
9290 a single-element array is returned.
9294 The second argument must be a well formed XML document. In particular,
9295 it must have a single root node element.
9299 The optional third argument of the function is an array of namespace
9300 mappings. This array should be a two-dimensional <type>text</> array with
9301 the length of the second axis being equal to 2 (i.e., it should be an
9302 array of arrays, each of which consists of exactly 2 elements).
9303 The first element of each array entry is the namespace name (alias), the
9304 second the namespace URI. It is not required that aliases provided in
9305 this array be the same as those being used in the XML document itself (in
9306 other words, both in the XML document and in the <function>xpath</function>
9307 function context, aliases are <emphasis>local</>).
9313 SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
9314 ARRAY[ARRAY['my', 'http://example.com']]);
9324 To deal with default (anonymous) namespaces, do something like this:
9326 SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a>',
9327 ARRAY[ARRAY['mydefns', 'http://example.com']]);
9337 <primary>xpath_exists</primary>
9341 <function>xpath_exists</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable> <optional>, <replaceable>nsarray</replaceable></optional>)
9345 The function <function>xpath_exists</function> is a specialized form
9346 of the <function>xpath</function> function. Instead of returning the
9347 individual XML values that satisfy the XPath, this function returns a
9348 Boolean indicating whether the query was satisfied or not. This
9349 function is equivalent to the standard <literal>XMLEXISTS</> predicate,
9350 except that it also offers support for a namespace mapping argument.
9356 SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
9357 ARRAY[ARRAY['my', 'http://example.com']]);
9367 <sect2 id="functions-xml-mapping">
9368 <title>Mapping Tables to XML</title>
9370 <indexterm zone="functions-xml-mapping">
9371 <primary>XML export</primary>
9375 The following functions map the contents of relational tables to
9376 XML values. They can be thought of as XML export functionality:
9378 table_to_xml(tbl regclass, nulls boolean, tableforest boolean, targetns text)
9379 query_to_xml(query text, nulls boolean, tableforest boolean, targetns text)
9380 cursor_to_xml(cursor refcursor, count int, nulls boolean,
9381 tableforest boolean, targetns text)
9383 The return type of each function is <type>xml</type>.
9387 <function>table_to_xml</function> maps the content of the named
9388 table, passed as parameter <parameter>tbl</parameter>. The
9389 <type>regclass</type> type accepts strings identifying tables using the
9390 usual notation, including optional schema qualifications and
9391 double quotes. <function>query_to_xml</function> executes the
9392 query whose text is passed as parameter
9393 <parameter>query</parameter> and maps the result set.
9394 <function>cursor_to_xml</function> fetches the indicated number of
9395 rows from the cursor specified by the parameter
9396 <parameter>cursor</parameter>. This variant is recommended if
9397 large tables have to be mapped, because the result value is built
9398 up in memory by each function.
9402 If <parameter>tableforest</parameter> is false, then the resulting
9403 XML document looks like this:
9407 <columnname1>data</columnname1>
9408 <columnname2>data</columnname2>
9419 If <parameter>tableforest</parameter> is true, the result is an
9420 XML content fragment that looks like this:
9423 <columnname1>data</columnname1>
9424 <columnname2>data</columnname2>
9434 If no table name is available, that is, when mapping a query or a
9435 cursor, the string <literal>table</literal> is used in the first
9436 format, <literal>row</literal> in the second format.
9440 The choice between these formats is up to the user. The first
9441 format is a proper XML document, which will be important in many
9442 applications. The second format tends to be more useful in the
9443 <function>cursor_to_xml</function> function if the result values are to be
9444 reassembled into one document later on. The functions for
9445 producing XML content discussed above, in particular
9446 <function>xmlelement</function>, can be used to alter the results
9451 The data values are mapped in the same way as described for the
9452 function <function>xmlelement</function> above.
9456 The parameter <parameter>nulls</parameter> determines whether null
9457 values should be included in the output. If true, null values in
9458 columns are represented as:
9460 <columnname xsi:nil="true"/>
9462 where <literal>xsi</literal> is the XML namespace prefix for XML
9463 Schema Instance. An appropriate namespace declaration will be
9464 added to the result value. If false, columns containing null
9465 values are simply omitted from the output.
9469 The parameter <parameter>targetns</parameter> specifies the
9470 desired XML namespace of the result. If no particular namespace
9471 is wanted, an empty string should be passed.
9475 The following functions return XML Schema documents describing the
9476 mappings performed by the corresponding functions above:
9478 table_to_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text)
9479 query_to_xmlschema(query text, nulls boolean, tableforest boolean, targetns text)
9480 cursor_to_xmlschema(cursor refcursor, nulls boolean, tableforest boolean, targetns text)
9482 It is essential that the same parameters are passed in order to
9483 obtain matching XML data mappings and XML Schema documents.
9487 The following functions produce XML data mappings and the
9488 corresponding XML Schema in one document (or forest), linked
9489 together. They can be useful where self-contained and
9490 self-describing results are wanted:
9492 table_to_xml_and_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text)
9493 query_to_xml_and_xmlschema(query text, nulls boolean, tableforest boolean, targetns text)
9498 In addition, the following functions are available to produce
9499 analogous mappings of entire schemas or the entire current
9502 schema_to_xml(schema name, nulls boolean, tableforest boolean, targetns text)
9503 schema_to_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)
9504 schema_to_xml_and_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)
9506 database_to_xml(nulls boolean, tableforest boolean, targetns text)
9507 database_to_xmlschema(nulls boolean, tableforest boolean, targetns text)
9508 database_to_xml_and_xmlschema(nulls boolean, tableforest boolean, targetns text)
9511 Note that these potentially produce a lot of data, which needs to
9512 be built up in memory. When requesting content mappings of large
9513 schemas or databases, it might be worthwhile to consider mapping the
9514 tables separately instead, possibly even through a cursor.
9518 The result of a schema content mapping looks like this:
9529 </schemaname>]]></screen>
9531 where the format of a table mapping depends on the
9532 <parameter>tableforest</parameter> parameter as explained above.
9536 The result of a database content mapping looks like this:
9551 </dbname>]]></screen>
9553 where the schema mapping is as above.
9557 As an example of using the output produced by these functions,
9558 <xref linkend="xslt-xml-html"> shows an XSLT stylesheet that
9559 converts the output of
9560 <function>table_to_xml_and_xmlschema</function> to an HTML
9561 document containing a tabular rendition of the table data. In a
9562 similar manner, the results from these functions can be
9563 converted into other XML-based formats.
9566 <figure id="xslt-xml-html">
9567 <title>XSLT Stylesheet for Converting SQL/XML Output to HTML</title>
9568 <programlisting><![CDATA[
9569 <?xml version="1.0"?>
9570 <xsl:stylesheet version="1.0"
9571 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
9572 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
9573 xmlns="http://www.w3.org/1999/xhtml"
9576 <xsl:output method="xml"
9577 doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
9578 doctype-public="-//W3C/DTD XHTML 1.0 Strict//EN"
9581 <xsl:template match="/*">
9582 <xsl:variable name="schema" select="//xsd:schema"/>
9583 <xsl:variable name="tabletypename"
9584 select="$schema/xsd:element[@name=name(current())]/@type"/>
9585 <xsl:variable name="rowtypename"
9586 select="$schema/xsd:complexType[@name=$tabletypename]/xsd:sequence/xsd:element[@name='row']/@type"/>
9590 <title><xsl:value-of select="name(current())"/></title>
9595 <xsl:for-each select="$schema/xsd:complexType[@name=$rowtypename]/xsd:sequence/xsd:element/@name">
9596 <th><xsl:value-of select="."/></th>
9600 <xsl:for-each select="row">
9602 <xsl:for-each select="*">
9603 <td><xsl:value-of select="."/></td>
9613 ]]></programlisting>
9619 <sect1 id="functions-sequence">
9620 <title>Sequence Manipulation Functions</title>
9623 <primary>sequence</primary>
9626 <primary>nextval</primary>
9629 <primary>currval</primary>
9632 <primary>lastval</primary>
9635 <primary>setval</primary>
9639 This section describes <productname>PostgreSQL</productname>'s
9640 functions for operating on <firstterm>sequence objects</firstterm>.
9641 Sequence objects (also called sequence generators or just
9642 sequences) are special single-row tables created with <xref
9643 linkend="sql-createsequence">.
9644 A sequence object is usually used to generate unique identifiers
9645 for rows of a table. The sequence functions, listed in <xref
9646 linkend="functions-sequence-table">, provide simple, multiuser-safe
9647 methods for obtaining successive sequence values from sequence
9651 <table id="functions-sequence-table">
9652 <title>Sequence Functions</title>
9655 <row><entry>Function</entry> <entry>Return Type</entry> <entry>Description</entry></row>
9660 <entry><literal><function>currval(<type>regclass</type>)</function></literal></entry>
9661 <entry><type>bigint</type></entry>
9662 <entry>Return value most recently obtained with
9663 <function>nextval</function> for specified sequence</entry>
9666 <entry><literal><function>lastval()</function></literal></entry>
9667 <entry><type>bigint</type></entry>
9668 <entry>Return value most recently obtained with
9669 <function>nextval</function> for any sequence</entry>
9672 <entry><literal><function>nextval(<type>regclass</type>)</function></literal></entry>
9673 <entry><type>bigint</type></entry>
9674 <entry>Advance sequence and return new value</entry>
9677 <entry><literal><function>setval(<type>regclass</type>, <type>bigint</type>)</function></literal></entry>
9678 <entry><type>bigint</type></entry>
9679 <entry>Set sequence's current value</entry>
9682 <entry><literal><function>setval(<type>regclass</type>, <type>bigint</type>, <type>boolean</type>)</function></literal></entry>
9683 <entry><type>bigint</type></entry>
9684 <entry>Set sequence's current value and <literal>is_called</literal> flag</entry>
9691 The sequence to be operated on by a sequence function is specified by
9692 a <type>regclass</> argument, which is simply the OID of the sequence in the
9693 <structname>pg_class</> system catalog. You do not have to look up the
9694 OID by hand, however, since the <type>regclass</> data type's input
9695 converter will do the work for you. Just write the sequence name enclosed
9696 in single quotes so that it looks like a literal constant. For
9697 compatibility with the handling of ordinary
9698 <acronym>SQL</acronym> names, the string will be converted to lower case
9699 unless it contains double quotes around the sequence name. Thus:
9701 nextval('foo') <lineannotation>operates on sequence <literal>foo</literal></>
9702 nextval('FOO') <lineannotation>operates on sequence <literal>foo</literal></>
9703 nextval('"Foo"') <lineannotation>operates on sequence <literal>Foo</literal></>
9705 The sequence name can be schema-qualified if necessary:
9707 nextval('myschema.foo') <lineannotation>operates on <literal>myschema.foo</literal></>
9708 nextval('"myschema".foo') <lineannotation>same as above</lineannotation>
9709 nextval('foo') <lineannotation>searches search path for <literal>foo</literal></>
9711 See <xref linkend="datatype-oid"> for more information about
9717 Before <productname>PostgreSQL</productname> 8.1, the arguments of the
9718 sequence functions were of type <type>text</>, not <type>regclass</>, and
9719 the above-described conversion from a text string to an OID value would
9720 happen at run time during each call. For backward compatibility, this
9721 facility still exists, but internally it is now handled as an implicit
9722 coercion from <type>text</> to <type>regclass</> before the function is
9727 When you write the argument of a sequence function as an unadorned
9728 literal string, it becomes a constant of type <type>regclass</>.
9729 Since this is really just an OID, it will track the originally
9730 identified sequence despite later renaming, schema reassignment,
9731 etc. This <quote>early binding</> behavior is usually desirable for
9732 sequence references in column defaults and views. But sometimes you might
9733 want <quote>late binding</> where the sequence reference is resolved
9734 at run time. To get late-binding behavior, force the constant to be
9735 stored as a <type>text</> constant instead of <type>regclass</>:
9737 nextval('foo'::text) <lineannotation><literal>foo</literal> is looked up at runtime</>
9739 Note that late binding was the only behavior supported in
9740 <productname>PostgreSQL</productname> releases before 8.1, so you
9741 might need to do this to preserve the semantics of old applications.
9745 Of course, the argument of a sequence function can be an expression
9746 as well as a constant. If it is a text expression then the implicit
9747 coercion will result in a run-time lookup.
9752 The available sequence functions are:
9756 <term><function>nextval</function></term>
9759 Advance the sequence object to its next value and return that
9760 value. This is done atomically: even if multiple sessions
9761 execute <function>nextval</function> concurrently, each will safely receive
9762 a distinct sequence value.
9768 <term><function>currval</function></term>
9771 Return the value most recently obtained by <function>nextval</function>
9772 for this sequence in the current session. (An error is
9773 reported if <function>nextval</function> has never been called for this
9774 sequence in this session.) Because this is returning
9775 a session-local value, it gives a predictable answer whether or not
9776 other sessions have executed <function>nextval</function> since the
9777 current session did.
9783 <term><function>lastval</function></term>
9786 Return the value most recently returned by
9787 <function>nextval</> in the current session. This function is
9788 identical to <function>currval</function>, except that instead
9789 of taking the sequence name as an argument it fetches the
9790 value of the last sequence used by <function>nextval</function>
9791 in the current session. It is an error to call
9792 <function>lastval</function> if <function>nextval</function>
9793 has not yet been called in the current session.
9799 <term><function>setval</function></term>
9802 Reset the sequence object's counter value. The two-parameter
9803 form sets the sequence's <literal>last_value</literal> field to the
9804 specified value and sets its <literal>is_called</literal> field to
9805 <literal>true</literal>, meaning that the next
9806 <function>nextval</function> will advance the sequence before
9807 returning a value. The value reported by <function>currval</> is
9808 also set to the specified value. In the three-parameter form,
9809 <literal>is_called</literal> can be set to either <literal>true</literal>
9810 or <literal>false</literal>. <literal>true</> has the same effect as
9811 the two-parameter form. If it is set to <literal>false</literal>, the
9812 next <function>nextval</function> will return exactly the specified
9813 value, and sequence advancement commences with the following
9814 <function>nextval</function>. Furthermore, the value reported by
9815 <function>currval</> is not changed in this case (this is a change
9816 from pre-8.3 behavior). For example,
9819 SELECT setval('foo', 42); <lineannotation>Next <function>nextval</> will return 43</lineannotation>
9820 SELECT setval('foo', 42, true); <lineannotation>Same as above</lineannotation>
9821 SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</> will return 42</lineannotation>
9824 The result returned by <function>setval</function> is just the value of its
9833 If a sequence object has been created with default parameters,
9834 successive <function>nextval</function> calls will return successive values
9835 beginning with 1. Other behaviors can be obtained by using
9836 special parameters in the <xref linkend="sql-createsequence"> command;
9837 see its command reference page for more information.
9842 To avoid blocking concurrent transactions that obtain numbers from the
9843 same sequence, a <function>nextval</function> operation is never rolled back;
9844 that is, once a value has been fetched it is considered used, even if the
9845 transaction that did the <function>nextval</function> later aborts. This means
9846 that aborted transactions might leave unused <quote>holes</quote> in the
9847 sequence of assigned values. <function>setval</function> operations are never
9848 rolled back, either.
9855 <sect1 id="functions-conditional">
9856 <title>Conditional Expressions</title>
9859 <primary>CASE</primary>
9863 <primary>conditional expression</primary>
9867 This section describes the <acronym>SQL</acronym>-compliant conditional expressions
9868 available in <productname>PostgreSQL</productname>.
9873 If your needs go beyond the capabilities of these conditional
9874 expressions, you might want to consider writing a stored procedure
9875 in a more expressive programming language.
9879 <sect2 id="functions-case">
9880 <title><literal>CASE</></title>
9883 The <acronym>SQL</acronym> <token>CASE</token> expression is a
9884 generic conditional expression, similar to if/else statements in
9885 other programming languages:
9888 CASE WHEN <replaceable>condition</replaceable> THEN <replaceable>result</replaceable>
9889 <optional>WHEN ...</optional>
9890 <optional>ELSE <replaceable>result</replaceable></optional>
9894 <token>CASE</token> clauses can be used wherever
9895 an expression is valid. Each <replaceable>condition</replaceable> is an
9896 expression that returns a <type>boolean</type> result. If the condition's
9897 result is true, the value of the <token>CASE</token> expression is the
9898 <replaceable>result</replaceable> that follows the condition, and the
9899 remainder of the <token>CASE</token> expression is not processed. If the
9900 condition's result is not true, any subsequent <token>WHEN</token> clauses
9901 are examined in the same manner. If no <token>WHEN</token>
9902 <replaceable>condition</replaceable> yields true, the value of the
9903 <token>CASE</> expression is the <replaceable>result</replaceable> of the
9904 <token>ELSE</token> clause. If the <token>ELSE</token> clause is
9905 omitted and no condition is true, the result is null.
9921 CASE WHEN a=1 THEN 'one'
9936 The data types of all the <replaceable>result</replaceable>
9937 expressions must be convertible to a single output type.
9938 See <xref linkend="typeconv-union-case"> for more details.
9942 There is a <quote>simple</> form of <token>CASE</token> expression
9943 that is a variant of the general form above:
9946 CASE <replaceable>expression</replaceable>
9947 WHEN <replaceable>value</replaceable> THEN <replaceable>result</replaceable>
9948 <optional>WHEN ...</optional>
9949 <optional>ELSE <replaceable>result</replaceable></optional>
9954 <replaceable>expression</replaceable> is computed, then compared to
9955 each of the <replaceable>value</replaceable> expressions in the
9956 <token>WHEN</token> clauses until one is found that is equal to it. If
9957 no match is found, the <replaceable>result</replaceable> of the
9958 <token>ELSE</token> clause (or a null value) is returned. This is similar
9959 to the <function>switch</function> statement in C.
9963 The example above can be written using the simple
9964 <token>CASE</token> syntax:
9967 CASE a WHEN 1 THEN 'one'
9982 A <token>CASE</token> expression does not evaluate any subexpressions
9983 that are not needed to determine the result. For example, this is a
9984 possible way of avoiding a division-by-zero failure:
9986 SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
9991 <sect2 id="functions-coalesce-nvl-ifnull">
9992 <title><literal>COALESCE</></title>
9995 <primary>COALESCE</primary>
9999 <primary>NVL</primary>
10003 <primary>IFNULL</primary>
10007 <function>COALESCE</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
10011 The <function>COALESCE</function> function returns the first of its
10012 arguments that is not null. Null is returned only if all arguments
10013 are null. It is often used to substitute a default value for
10014 null values when data is retrieved for display, for example:
10016 SELECT COALESCE(description, short_description, '(none)') ...
10018 This returns <varname>description</> if it is not null, otherwise
10019 <varname>short_description</> if it is not null, otherwise <literal>(none)</>.
10023 Like a <token>CASE</token> expression, <function>COALESCE</function> only
10024 evaluates the arguments that are needed to determine the result;
10025 that is, arguments to the right of the first non-null argument are
10026 not evaluated. This SQL-standard function provides capabilities similar
10027 to <function>NVL</> and <function>IFNULL</>, which are used in some other
10032 <sect2 id="functions-nullif">
10033 <title><literal>NULLIF</></title>
10036 <primary>NULLIF</primary>
10040 <function>NULLIF</function>(<replaceable>value1</replaceable>, <replaceable>value2</replaceable>)
10044 The <function>NULLIF</function> function returns a null value if
10045 <replaceable>value1</replaceable> equals <replaceable>value2</replaceable>;
10046 otherwise it returns <replaceable>value1</replaceable>.
10047 This can be used to perform the inverse operation of the
10048 <function>COALESCE</function> example given above:
10050 SELECT NULLIF(value, '(none)') ...
10054 In this example, if <literal>value</literal> is <literal>(none)</>,
10055 null is returned, otherwise the value of <literal>value</literal>
10061 <sect2 id="functions-greatest-least">
10062 <title><literal>GREATEST</literal> and <literal>LEAST</literal></title>
10065 <primary>GREATEST</primary>
10068 <primary>LEAST</primary>
10072 <function>GREATEST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
10075 <function>LEAST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
10079 The <function>GREATEST</> and <function>LEAST</> functions select the
10080 largest or smallest value from a list of any number of expressions.
10081 The expressions must all be convertible to a common data type, which
10082 will be the type of the result
10083 (see <xref linkend="typeconv-union-case"> for details). NULL values
10084 in the list are ignored. The result will be NULL only if all the
10085 expressions evaluate to NULL.
10089 Note that <function>GREATEST</> and <function>LEAST</> are not in
10090 the SQL standard, but are a common extension. Some other databases
10091 make them return NULL if any argument is NULL, rather than only when
10097 <sect1 id="functions-array">
10098 <title>Array Functions and Operators</title>
10101 <xref linkend="array-operators-table"> shows the operators
10102 available for array types.
10105 <table id="array-operators-table">
10106 <title>Array Operators</title>
10110 <entry>Operator</entry>
10111 <entry>Description</entry>
10112 <entry>Example</entry>
10113 <entry>Result</entry>
10118 <entry> <literal>=</literal> </entry>
10119 <entry>equal</entry>
10120 <entry><literal>ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3]</literal></entry>
10121 <entry><literal>t</literal></entry>
10125 <entry> <literal><></literal> </entry>
10126 <entry>not equal</entry>
10127 <entry><literal>ARRAY[1,2,3] <> ARRAY[1,2,4]</literal></entry>
10128 <entry><literal>t</literal></entry>
10132 <entry> <literal><</literal> </entry>
10133 <entry>less than</entry>
10134 <entry><literal>ARRAY[1,2,3] < ARRAY[1,2,4]</literal></entry>
10135 <entry><literal>t</literal></entry>
10139 <entry> <literal>></literal> </entry>
10140 <entry>greater than</entry>
10141 <entry><literal>ARRAY[1,4,3] > ARRAY[1,2,4]</literal></entry>
10142 <entry><literal>t</literal></entry>
10146 <entry> <literal><=</literal> </entry>
10147 <entry>less than or equal</entry>
10148 <entry><literal>ARRAY[1,2,3] <= ARRAY[1,2,3]</literal></entry>
10149 <entry><literal>t</literal></entry>
10153 <entry> <literal>>=</literal> </entry>
10154 <entry>greater than or equal</entry>
10155 <entry><literal>ARRAY[1,4,3] >= ARRAY[1,4,3]</literal></entry>
10156 <entry><literal>t</literal></entry>
10160 <entry> <literal>@></literal> </entry>
10161 <entry>contains</entry>
10162 <entry><literal>ARRAY[1,4,3] @> ARRAY[3,1]</literal></entry>
10163 <entry><literal>t</literal></entry>
10167 <entry> <literal><@</literal> </entry>
10168 <entry>is contained by</entry>
10169 <entry><literal>ARRAY[2,7] <@ ARRAY[1,7,4,2,6]</literal></entry>
10170 <entry><literal>t</literal></entry>
10174 <entry> <literal>&&</literal> </entry>
10175 <entry>overlap (have elements in common)</entry>
10176 <entry><literal>ARRAY[1,4,3] && ARRAY[2,1]</literal></entry>
10177 <entry><literal>t</literal></entry>
10181 <entry> <literal>||</literal> </entry>
10182 <entry>array-to-array concatenation</entry>
10183 <entry><literal>ARRAY[1,2,3] || ARRAY[4,5,6]</literal></entry>
10184 <entry><literal>{1,2,3,4,5,6}</literal></entry>
10188 <entry> <literal>||</literal> </entry>
10189 <entry>array-to-array concatenation</entry>
10190 <entry><literal>ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]]</literal></entry>
10191 <entry><literal>{{1,2,3},{4,5,6},{7,8,9}}</literal></entry>
10195 <entry> <literal>||</literal> </entry>
10196 <entry>element-to-array concatenation</entry>
10197 <entry><literal>3 || ARRAY[4,5,6]</literal></entry>
10198 <entry><literal>{3,4,5,6}</literal></entry>
10202 <entry> <literal>||</literal> </entry>
10203 <entry>array-to-element concatenation</entry>
10204 <entry><literal>ARRAY[4,5,6] || 7</literal></entry>
10205 <entry><literal>{4,5,6,7}</literal></entry>
10212 Array comparisons compare the array contents element-by-element,
10213 using the default B-tree comparison function for the element data type.
10214 In multidimensional arrays the elements are visited in row-major order
10215 (last subscript varies most rapidly).
10216 If the contents of two arrays are equal but the dimensionality is
10217 different, the first difference in the dimensionality information
10218 determines the sort order. (This is a change from versions of
10219 <productname>PostgreSQL</> prior to 8.2: older versions would claim
10220 that two arrays with the same contents were equal, even if the
10221 number of dimensions or subscript ranges were different.)
10225 See <xref linkend="arrays"> for more details about array operator
10230 <xref linkend="array-functions-table"> shows the functions
10231 available for use with array types. See <xref linkend="arrays">
10232 for more information and examples of the use of these functions.
10236 <primary>array_append</primary>
10239 <primary>array_cat</primary>
10242 <primary>array_ndims</primary>
10245 <primary>array_dims</primary>
10248 <primary>array_fill</primary>
10251 <primary>array_length</primary>
10254 <primary>array_lower</primary>
10257 <primary>array_prepend</primary>
10260 <primary>array_to_string</primary>
10263 <primary>array_upper</primary>
10266 <primary>string_to_array</primary>
10269 <primary>unnest</primary>
10272 <table id="array-functions-table">
10273 <title>Array Functions</title>
10277 <entry>Function</entry>
10278 <entry>Return Type</entry>
10279 <entry>Description</entry>
10280 <entry>Example</entry>
10281 <entry>Result</entry>
10288 <function>array_append</function>(<type>anyarray</type>, <type>anyelement</type>)
10291 <entry><type>anyarray</type></entry>
10292 <entry>append an element to the end of an array</entry>
10293 <entry><literal>array_append(ARRAY[1,2], 3)</literal></entry>
10294 <entry><literal>{1,2,3}</literal></entry>
10299 <function>array_cat</function>(<type>anyarray</type>, <type>anyarray</type>)
10302 <entry><type>anyarray</type></entry>
10303 <entry>concatenate two arrays</entry>
10304 <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
10305 <entry><literal>{1,2,3,4,5}</literal></entry>
10310 <function>array_ndims</function>(<type>anyarray</type>)
10313 <entry><type>int</type></entry>
10314 <entry>returns the number of dimensions of the array</entry>
10315 <entry><literal>array_ndims(ARRAY[[1,2,3], [4,5,6]])</literal></entry>
10316 <entry><literal>2</literal></entry>
10321 <function>array_dims</function>(<type>anyarray</type>)
10324 <entry><type>text</type></entry>
10325 <entry>returns a text representation of array's dimensions</entry>
10326 <entry><literal>array_dims(ARRAY[[1,2,3], [4,5,6]])</literal></entry>
10327 <entry><literal>[1:2][1:3]</literal></entry>
10332 <function>array_fill</function>(<type>anyelement</type>, <type>int[]</type>,
10333 <optional>, <type>int[]</type></optional>)
10336 <entry><type>anyarray</type></entry>
10337 <entry>returns an array initialized with supplied value and
10338 dimensions, optionally with lower bounds other than 1</entry>
10339 <entry><literal>array_fill(7, ARRAY[3], ARRAY[2])</literal></entry>
10340 <entry><literal>[2:4]={7,7,7}</literal></entry>
10345 <function>array_length</function>(<type>anyarray</type>, <type>int</type>)
10348 <entry><type>int</type></entry>
10349 <entry>returns the length of the requested array dimension</entry>
10350 <entry><literal>array_length(array[1,2,3], 1)</literal></entry>
10351 <entry><literal>3</literal></entry>
10356 <function>array_lower</function>(<type>anyarray</type>, <type>int</type>)
10359 <entry><type>int</type></entry>
10360 <entry>returns lower bound of the requested array dimension</entry>
10361 <entry><literal>array_lower('[0:2]={1,2,3}'::int[], 1)</literal></entry>
10362 <entry><literal>0</literal></entry>
10367 <function>array_prepend</function>(<type>anyelement</type>, <type>anyarray</type>)
10370 <entry><type>anyarray</type></entry>
10371 <entry>append an element to the beginning of an array</entry>
10372 <entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
10373 <entry><literal>{1,2,3}</literal></entry>
10378 <function>array_to_string</function>(<type>anyarray</type>, <type>text</type> <optional>, <type>text</type></optional>)
10381 <entry><type>text</type></entry>
10382 <entry>concatenates array elements using supplied delimiter and
10383 optional null string</entry>
10384 <entry><literal>array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')</literal></entry>
10385 <entry><literal>1,2,3,*,5</literal></entry>
10390 <function>array_upper</function>(<type>anyarray</type>, <type>int</type>)
10393 <entry><type>int</type></entry>
10394 <entry>returns upper bound of the requested array dimension</entry>
10395 <entry><literal>array_upper(ARRAY[1,8,3,7], 1)</literal></entry>
10396 <entry><literal>4</literal></entry>
10401 <function>string_to_array</function>(<type>text</type>, <type>text</type> <optional>, <type>text</type></optional>)
10404 <entry><type>text[]</type></entry>
10405 <entry>splits string into array elements using supplied delimiter and
10406 optional null string</entry>
10407 <entry><literal>string_to_array('xx~^~yy~^~zz', '~^~', 'yy')</literal></entry>
10408 <entry><literal>{xx,NULL,zz}</literal></entry>
10413 <function>unnest</function>(<type>anyarray</type>)
10416 <entry><type>setof anyelement</type></entry>
10417 <entry>expand an array to a set of rows</entry>
10418 <entry><literal>unnest(ARRAY[1,2])</literal></entry>
10419 <entry><literallayout class="monospaced">1
10420 2</literallayout>(2 rows)</entry>
10427 In <function>string_to_array</function>, if the delimiter parameter is
10428 NULL, each character in the input string will become a separate element in
10429 the resulting array. If the delimiter is an empty string, then the entire
10430 input string is returned as a one-element array. Otherwise the input
10431 string is split at each occurrence of the delimiter string.
10435 In <function>string_to_array</function>, if the null-string parameter
10436 is omitted or NULL, none of the substrings of the input will be replaced
10438 In <function>array_to_string</function>, if the null-string parameter
10439 is omitted or NULL, any null elements in the array are simply skipped
10440 and not represented in the output string.
10445 There are two differences in the behavior of <function>string_to_array</>
10446 from pre-9.1 versions of <productname>PostgreSQL</>.
10447 First, it will return an empty (zero-element) array rather than NULL when
10448 the input string is of zero length. Second, if the delimiter string is
10449 NULL, the function splits the input into individual characters, rather
10450 than returning NULL as before.
10455 See also <xref linkend="functions-aggregate"> about the aggregate
10456 function <function>array_agg</function> for use with arrays.
10460 <sect1 id="functions-aggregate">
10461 <title>Aggregate Functions</title>
10463 <indexterm zone="functions-aggregate">
10464 <primary>aggregate function</primary>
10465 <secondary>built-in</secondary>
10469 <firstterm>Aggregate functions</firstterm> compute a single result
10470 from a set of input values. The built-in aggregate functions
10472 <xref linkend="functions-aggregate-table"> and
10473 <xref linkend="functions-aggregate-statistics-table">.
10474 The special syntax considerations for aggregate
10475 functions are explained in <xref linkend="syntax-aggregates">.
10476 Consult <xref linkend="tutorial-agg"> for additional introductory
10480 <table id="functions-aggregate-table">
10481 <title>General-Purpose Aggregate Functions</title>
10486 <entry>Function</entry>
10487 <entry>Argument Type(s)</entry>
10488 <entry>Return Type</entry>
10489 <entry>Description</entry>
10497 <primary>array_agg</primary>
10499 <function>array_agg(<replaceable class="parameter">expression</replaceable>)</function>
10505 array of the argument type
10507 <entry>input values, including nulls, concatenated into an array</entry>
10513 <primary>average</primary>
10516 <primary>avg</primary>
10518 <function>avg(<replaceable class="parameter">expression</replaceable>)</function>
10521 <type>smallint</type>, <type>int</type>,
10522 <type>bigint</type>, <type>real</type>, <type>double
10523 precision</type>, <type>numeric</type>, or <type>interval</type>
10526 <type>numeric</type> for any integer-type argument,
10527 <type>double precision</type> for a floating-point argument,
10528 otherwise the same as the argument data type
10530 <entry>the average (arithmetic mean) of all input values</entry>
10536 <primary>bit_and</primary>
10538 <function>bit_and(<replaceable class="parameter">expression</replaceable>)</function>
10541 <type>smallint</type>, <type>int</type>, <type>bigint</type>, or
10545 same as argument data type
10547 <entry>the bitwise AND of all non-null input values, or null if none</entry>
10553 <primary>bit_or</primary>
10555 <function>bit_or(<replaceable class="parameter">expression</replaceable>)</function>
10558 <type>smallint</type>, <type>int</type>, <type>bigint</type>, or
10562 same as argument data type
10564 <entry>the bitwise OR of all non-null input values, or null if none</entry>
10570 <primary>bool_and</primary>
10572 <function>bool_and(<replaceable class="parameter">expression</replaceable>)</function>
10580 <entry>true if all input values are true, otherwise false</entry>
10586 <primary>bool_or</primary>
10588 <function>bool_or(<replaceable class="parameter">expression</replaceable>)</function>
10596 <entry>true if at least one input value is true, otherwise false</entry>
10602 <primary>count</primary>
10604 <function>count(*)</function>
10607 <entry><type>bigint</type></entry>
10608 <entry>number of input rows</entry>
10612 <entry><function>count(<replaceable class="parameter">expression</replaceable>)</function></entry>
10614 <entry><type>bigint</type></entry>
10616 number of input rows for which the value of <replaceable
10617 class="parameter">expression</replaceable> is not null
10624 <primary>every</primary>
10626 <function>every(<replaceable class="parameter">expression</replaceable>)</function>
10634 <entry>equivalent to <function>bool_and</function></entry>
10640 <primary>max</primary>
10642 <function>max(<replaceable class="parameter">expression</replaceable>)</function>
10644 <entry>any array, numeric, string, or date/time type</entry>
10645 <entry>same as argument type</entry>
10647 maximum value of <replaceable
10648 class="parameter">expression</replaceable> across all input
10656 <primary>min</primary>
10658 <function>min(<replaceable class="parameter">expression</replaceable>)</function>
10660 <entry>any array, numeric, string, or date/time type</entry>
10661 <entry>same as argument type</entry>
10663 minimum value of <replaceable
10664 class="parameter">expression</replaceable> across all input
10672 <primary>string_agg</primary>
10675 string_agg(<replaceable class="parameter">expression</replaceable>,
10676 <replaceable class="parameter">delimiter</replaceable>)
10680 <type>text</type>, <type>text</type>
10685 <entry>input values concatenated into a string, separated by delimiter</entry>
10691 <primary>sum</primary>
10693 <function>sum(<replaceable class="parameter">expression</replaceable>)</function>
10696 <type>smallint</type>, <type>int</type>,
10697 <type>bigint</type>, <type>real</type>, <type>double
10698 precision</type>, <type>numeric</type>, or
10699 <type>interval</type>
10702 <type>bigint</type> for <type>smallint</type> or
10703 <type>int</type> arguments, <type>numeric</type> for
10704 <type>bigint</type> arguments, <type>double precision</type>
10705 for floating-point arguments, otherwise the same as the
10708 <entry>sum of <replaceable class="parameter">expression</replaceable> across all input values</entry>
10714 <primary>xmlagg</primary>
10716 <function>xmlagg(<replaceable class="parameter">expression</replaceable>)</function>
10724 <entry>concatenation of XML values (see also <xref linkend="functions-xml-xmlagg">)</entry>
10731 It should be noted that except for <function>count</function>,
10732 these functions return a null value when no rows are selected. In
10733 particular, <function>sum</function> of no rows returns null, not
10734 zero as one might expect, and <function>array_agg</function>
10735 returns null rather than an empty array when there are no input
10736 rows. The <function>coalesce</function> function can be used to
10737 substitute zero or an empty array for null when necessary.
10742 <primary>ANY</primary>
10745 <primary>SOME</primary>
10748 Boolean aggregates <function>bool_and</function> and
10749 <function>bool_or</function> correspond to standard SQL aggregates
10750 <function>every</function> and <function>any</function> or
10751 <function>some</function>.
10752 As for <function>any</function> and <function>some</function>,
10753 it seems that there is an ambiguity built into the standard syntax:
10755 SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
10757 Here <function>ANY</function> can be considered either as introducing
10758 a subquery, or as being an aggregate function, if the subquery
10759 returns one row with a Boolean value.
10760 Thus the standard name cannot be given to these aggregates.
10766 Users accustomed to working with other SQL database management
10767 systems might be disappointed by the performance of the
10768 <function>count</function> aggregate when it is applied to the
10769 entire table. A query like:
10771 SELECT count(*) FROM sometable;
10773 will be executed by <productname>PostgreSQL</productname> using a
10774 sequential scan of the entire table.
10779 The aggregate functions <function>array_agg</function>,
10780 <function>string_agg</function>,
10781 and <function>xmlagg</function>, as well as similar user-defined
10782 aggregate functions, produce meaningfully different result values
10783 depending on the order of the input values. This ordering is
10784 unspecified by default, but can be controlled by writing an
10785 <literal>ORDER BY</> clause within the aggregate call, as shown in
10786 <xref linkend="syntax-aggregates">.
10787 Alternatively, supplying the input values from a sorted subquery
10788 will usually work. For example:
10791 SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
10794 But this syntax is not allowed in the SQL standard, and is
10795 not portable to other database systems.
10799 <xref linkend="functions-aggregate-statistics-table"> shows
10800 aggregate functions typically used in statistical analysis.
10801 (These are separated out merely to avoid cluttering the listing
10802 of more-commonly-used aggregates.) Where the description mentions
10803 <replaceable class="parameter">N</replaceable>, it means the
10804 number of input rows for which all the input expressions are non-null.
10805 In all cases, null is returned if the computation is meaningless,
10806 for example when <replaceable class="parameter">N</replaceable> is zero.
10810 <primary>statistics</primary>
10813 <primary>linear regression</primary>
10816 <table id="functions-aggregate-statistics-table">
10817 <title>Aggregate Functions for Statistics</title>
10822 <entry>Function</entry>
10823 <entry>Argument Type</entry>
10824 <entry>Return Type</entry>
10825 <entry>Description</entry>
10834 <primary>correlation</primary>
10837 <primary>corr</primary>
10839 <function>corr(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10842 <type>double precision</type>
10845 <type>double precision</type>
10847 <entry>correlation coefficient</entry>
10853 <primary>covariance</primary>
10854 <secondary>population</secondary>
10857 <primary>covar_pop</primary>
10859 <function>covar_pop(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10862 <type>double precision</type>
10865 <type>double precision</type>
10867 <entry>population covariance</entry>
10873 <primary>covariance</primary>
10874 <secondary>sample</secondary>
10877 <primary>covar_samp</primary>
10879 <function>covar_samp(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10882 <type>double precision</type>
10885 <type>double precision</type>
10887 <entry>sample covariance</entry>
10893 <primary>regr_avgx</primary>
10895 <function>regr_avgx(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10898 <type>double precision</type>
10901 <type>double precision</type>
10903 <entry>average of the independent variable
10904 (<literal>sum(<replaceable class="parameter">X</replaceable>)/<replaceable class="parameter">N</replaceable></literal>)</entry>
10910 <primary>regr_avgy</primary>
10912 <function>regr_avgy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10915 <type>double precision</type>
10918 <type>double precision</type>
10920 <entry>average of the dependent variable
10921 (<literal>sum(<replaceable class="parameter">Y</replaceable>)/<replaceable class="parameter">N</replaceable></literal>)</entry>
10927 <primary>regr_count</primary>
10929 <function>regr_count(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10932 <type>double precision</type>
10935 <type>bigint</type>
10937 <entry>number of input rows in which both expressions are nonnull</entry>
10943 <primary>regression intercept</primary>
10946 <primary>regr_intercept</primary>
10948 <function>regr_intercept(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10951 <type>double precision</type>
10954 <type>double precision</type>
10956 <entry>y-intercept of the least-squares-fit linear equation
10957 determined by the (<replaceable
10958 class="parameter">X</replaceable>, <replaceable
10959 class="parameter">Y</replaceable>) pairs</entry>
10965 <primary>regr_r2</primary>
10967 <function>regr_r2(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10970 <type>double precision</type>
10973 <type>double precision</type>
10975 <entry>square of the correlation coefficient</entry>
10981 <primary>regression slope</primary>
10984 <primary>regr_slope</primary>
10986 <function>regr_slope(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10989 <type>double precision</type>
10992 <type>double precision</type>
10994 <entry>slope of the least-squares-fit linear equation determined
10995 by the (<replaceable class="parameter">X</replaceable>,
10996 <replaceable class="parameter">Y</replaceable>) pairs</entry>
11002 <primary>regr_sxx</primary>
11004 <function>regr_sxx(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
11007 <type>double precision</type>
11010 <type>double precision</type>
11012 <entry><literal>sum(<replaceable
11013 class="parameter">X</replaceable>^2) - sum(<replaceable
11014 class="parameter">X</replaceable>)^2/<replaceable
11015 class="parameter">N</replaceable></literal> (<quote>sum of
11016 squares</quote> of the independent variable)</entry>
11022 <primary>regr_sxy</primary>
11024 <function>regr_sxy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
11027 <type>double precision</type>
11030 <type>double precision</type>
11032 <entry><literal>sum(<replaceable
11033 class="parameter">X</replaceable>*<replaceable
11034 class="parameter">Y</replaceable>) - sum(<replaceable
11035 class="parameter">X</replaceable>) * sum(<replaceable
11036 class="parameter">Y</replaceable>)/<replaceable
11037 class="parameter">N</replaceable></literal> (<quote>sum of
11038 products</quote> of independent times dependent
11045 <primary>regr_syy</primary>
11047 <function>regr_syy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
11050 <type>double precision</type>
11053 <type>double precision</type>
11055 <entry><literal>sum(<replaceable
11056 class="parameter">Y</replaceable>^2) - sum(<replaceable
11057 class="parameter">Y</replaceable>)^2/<replaceable
11058 class="parameter">N</replaceable></literal> (<quote>sum of
11059 squares</quote> of the dependent variable)</entry>
11065 <primary>standard deviation</primary>
11068 <primary>stddev</primary>
11070 <function>stddev(<replaceable class="parameter">expression</replaceable>)</function>
11073 <type>smallint</type>, <type>int</type>,
11074 <type>bigint</type>, <type>real</type>, <type>double
11075 precision</type>, or <type>numeric</type>
11078 <type>double precision</type> for floating-point arguments,
11079 otherwise <type>numeric</type>
11081 <entry>historical alias for <function>stddev_samp</function></entry>
11087 <primary>standard deviation</primary>
11088 <secondary>population</secondary>
11091 <primary>stddev_pop</primary>
11093 <function>stddev_pop(<replaceable class="parameter">expression</replaceable>)</function>
11096 <type>smallint</type>, <type>int</type>,
11097 <type>bigint</type>, <type>real</type>, <type>double
11098 precision</type>, or <type>numeric</type>
11101 <type>double precision</type> for floating-point arguments,
11102 otherwise <type>numeric</type>
11104 <entry>population standard deviation of the input values</entry>
11110 <primary>standard deviation</primary>
11111 <secondary>sample</secondary>
11114 <primary>stddev_samp</primary>
11116 <function>stddev_samp(<replaceable class="parameter">expression</replaceable>)</function>
11119 <type>smallint</type>, <type>int</type>,
11120 <type>bigint</type>, <type>real</type>, <type>double
11121 precision</type>, or <type>numeric</type>
11124 <type>double precision</type> for floating-point arguments,
11125 otherwise <type>numeric</type>
11127 <entry>sample standard deviation of the input values</entry>
11133 <primary>variance</primary>
11135 <function>variance</function>(<replaceable class="parameter">expression</replaceable>)
11138 <type>smallint</type>, <type>int</type>,
11139 <type>bigint</type>, <type>real</type>, <type>double
11140 precision</type>, or <type>numeric</type>
11143 <type>double precision</type> for floating-point arguments,
11144 otherwise <type>numeric</type>
11146 <entry>historical alias for <function>var_samp</function></entry>
11152 <primary>variance</primary>
11153 <secondary>population</secondary>
11156 <primary>var_pop</primary>
11158 <function>var_pop</function>(<replaceable class="parameter">expression</replaceable>)
11161 <type>smallint</type>, <type>int</type>,
11162 <type>bigint</type>, <type>real</type>, <type>double
11163 precision</type>, or <type>numeric</type>
11166 <type>double precision</type> for floating-point arguments,
11167 otherwise <type>numeric</type>
11169 <entry>population variance of the input values (square of the population standard deviation)</entry>
11175 <primary>variance</primary>
11176 <secondary>sample</secondary>
11179 <primary>var_samp</primary>
11181 <function>var_samp</function>(<replaceable class="parameter">expression</replaceable>)
11184 <type>smallint</type>, <type>int</type>,
11185 <type>bigint</type>, <type>real</type>, <type>double
11186 precision</type>, or <type>numeric</type>
11189 <type>double precision</type> for floating-point arguments,
11190 otherwise <type>numeric</type>
11192 <entry>sample variance of the input values (square of the sample standard deviation)</entry>
11200 <sect1 id="functions-window">
11201 <title>Window Functions</title>
11203 <indexterm zone="functions-window">
11204 <primary>window function</primary>
11205 <secondary>built-in</secondary>
11209 <firstterm>Window functions</firstterm> provide the ability to perform
11210 calculations across sets of rows that are related to the current query
11211 row. See <xref linkend="tutorial-window"> for an introduction to this
11216 The built-in window functions are listed in
11217 <xref linkend="functions-window-table">. Note that these functions
11218 <emphasis>must</> be invoked using window function syntax; that is an
11219 <literal>OVER</> clause is required.
11223 In addition to these functions, any built-in or user-defined aggregate
11224 function can be used as a window function (see
11225 <xref linkend="functions-aggregate"> for a list of the built-in aggregates).
11226 Aggregate functions act as window functions only when an <literal>OVER</>
11227 clause follows the call; otherwise they act as regular aggregates.
11230 <table id="functions-window-table">
11231 <title>General-Purpose Window Functions</title>
11236 <entry>Function</entry>
11237 <entry>Return Type</entry>
11238 <entry>Description</entry>
11246 <primary>row_number</primary>
11248 <function>row_number()</function>
11251 <type>bigint</type>
11253 <entry>number of the current row within its partition, counting from 1</entry>
11259 <primary>rank</primary>
11261 <function>rank()</function>
11264 <type>bigint</type>
11266 <entry>rank of the current row with gaps; same as <function>row_number</> of its first peer</entry>
11272 <primary>dense_rank</primary>
11274 <function>dense_rank()</function>
11277 <type>bigint</type>
11279 <entry>rank of the current row without gaps; this function counts peer groups</entry>
11285 <primary>percent_rank</primary>
11287 <function>percent_rank()</function>
11290 <type>double precision</type>
11292 <entry>relative rank of the current row: (<function>rank</> - 1) / (total rows - 1)</entry>
11298 <primary>cume_dist</primary>
11300 <function>cume_dist()</function>
11303 <type>double precision</type>
11305 <entry>relative rank of the current row: (number of rows preceding or peer with current row) / (total rows)</entry>
11311 <primary>ntile</primary>
11313 <function>ntile(<replaceable class="parameter">num_buckets</replaceable> <type>integer</>)</function>
11316 <type>integer</type>
11318 <entry>integer ranging from 1 to the argument value, dividing the
11319 partition as equally as possible</entry>
11325 <primary>lag</primary>
11328 lag(<replaceable class="parameter">value</replaceable> <type>any</>
11329 [, <replaceable class="parameter">offset</replaceable> <type>integer</>
11330 [, <replaceable class="parameter">default</replaceable> <type>any</> ]])
11334 <type>same type as <replaceable class="parameter">value</replaceable></type>
11337 returns <replaceable class="parameter">value</replaceable> evaluated at
11338 the row that is <replaceable class="parameter">offset</replaceable>
11339 rows before the current row within the partition; if there is no such
11340 row, instead return <replaceable class="parameter">default</replaceable>.
11341 Both <replaceable class="parameter">offset</replaceable> and
11342 <replaceable class="parameter">default</replaceable> are evaluated
11343 with respect to the current row. If omitted,
11344 <replaceable class="parameter">offset</replaceable> defaults to 1 and
11345 <replaceable class="parameter">default</replaceable> to null
11352 <primary>lead</primary>
11355 lead(<replaceable class="parameter">value</replaceable> <type>any</>
11356 [, <replaceable class="parameter">offset</replaceable> <type>integer</>
11357 [, <replaceable class="parameter">default</replaceable> <type>any</> ]])
11361 <type>same type as <replaceable class="parameter">value</replaceable></type>
11364 returns <replaceable class="parameter">value</replaceable> evaluated at
11365 the row that is <replaceable class="parameter">offset</replaceable>
11366 rows after the current row within the partition; if there is no such
11367 row, instead return <replaceable class="parameter">default</replaceable>.
11368 Both <replaceable class="parameter">offset</replaceable> and
11369 <replaceable class="parameter">default</replaceable> are evaluated
11370 with respect to the current row. If omitted,
11371 <replaceable class="parameter">offset</replaceable> defaults to 1 and
11372 <replaceable class="parameter">default</replaceable> to null
11379 <primary>first_value</primary>
11381 <function>first_value(<replaceable class="parameter">value</replaceable> <type>any</>)</function>
11384 <type>same type as <replaceable class="parameter">value</replaceable></type>
11387 returns <replaceable class="parameter">value</replaceable> evaluated
11388 at the row that is the first row of the window frame
11395 <primary>last_value</primary>
11397 <function>last_value(<replaceable class="parameter">value</replaceable> <type>any</>)</function>
11400 <type>same type as <replaceable class="parameter">value</replaceable></type>
11403 returns <replaceable class="parameter">value</replaceable> evaluated
11404 at the row that is the last row of the window frame
11411 <primary>nth_value</primary>
11414 nth_value(<replaceable class="parameter">value</replaceable> <type>any</>, <replaceable class="parameter">nth</replaceable> <type>integer</>)
11418 <type>same type as <replaceable class="parameter">value</replaceable></type>
11421 returns <replaceable class="parameter">value</replaceable> evaluated
11422 at the row that is the <replaceable class="parameter">nth</replaceable>
11423 row of the window frame (counting from 1); null if no such row
11431 All of the functions listed in
11432 <xref linkend="functions-window-table"> depend on the sort ordering
11433 specified by the <literal>ORDER BY</> clause of the associated window
11434 definition. Rows that are not distinct in the <literal>ORDER BY</>
11435 ordering are said to be <firstterm>peers</>; the four ranking functions
11436 are defined so that they give the same answer for any two peer rows.
11440 Note that <function>first_value</>, <function>last_value</>, and
11441 <function>nth_value</> consider only the rows within the <quote>window
11442 frame</>, which by default contains the rows from the start of the
11443 partition through the last peer of the current row. This is
11444 likely to give unhelpful results for <function>last_value</> and
11445 sometimes also <function>nth_value</>. You can redefine the frame by
11446 adding a suitable frame specification (<literal>RANGE</> or
11447 <literal>ROWS</>) to the <literal>OVER</> clause.
11448 See <xref linkend="syntax-window-functions"> for more information
11449 about frame specifications.
11453 When an aggregate function is used as a window function, it aggregates
11454 over the rows within the current row's window frame.
11455 An aggregate used with <literal>ORDER BY</> and the default window frame
11456 definition produces a <quote>running sum</> type of behavior, which may or
11457 may not be what's wanted. To obtain
11458 aggregation over the whole partition, omit <literal>ORDER BY</> or use
11459 <literal>ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</>.
11460 Other frame specifications can be used to obtain other effects.
11465 The SQL standard defines a <literal>RESPECT NULLS</> or
11466 <literal>IGNORE NULLS</> option for <function>lead</>, <function>lag</>,
11467 <function>first_value</>, <function>last_value</>, and
11468 <function>nth_value</>. This is not implemented in
11469 <productname>PostgreSQL</productname>: the behavior is always the
11470 same as the standard's default, namely <literal>RESPECT NULLS</>.
11471 Likewise, the standard's <literal>FROM FIRST</> or <literal>FROM LAST</>
11472 option for <function>nth_value</> is not implemented: only the
11473 default <literal>FROM FIRST</> behavior is supported. (You can achieve
11474 the result of <literal>FROM LAST</> by reversing the <literal>ORDER BY</>
11481 <sect1 id="functions-subquery">
11482 <title>Subquery Expressions</title>
11485 <primary>EXISTS</primary>
11489 <primary>IN</primary>
11493 <primary>NOT IN</primary>
11497 <primary>ANY</primary>
11501 <primary>ALL</primary>
11505 <primary>SOME</primary>
11509 <primary>subquery</primary>
11513 This section describes the <acronym>SQL</acronym>-compliant subquery
11514 expressions available in <productname>PostgreSQL</productname>.
11515 All of the expression forms documented in this section return
11516 Boolean (true/false) results.
11519 <sect2 id="functions-subquery-exists">
11520 <title><literal>EXISTS</literal></title>
11523 EXISTS (<replaceable>subquery</replaceable>)
11527 The argument of <token>EXISTS</token> is an arbitrary <command>SELECT</> statement,
11528 or <firstterm>subquery</firstterm>. The
11529 subquery is evaluated to determine whether it returns any rows.
11530 If it returns at least one row, the result of <token>EXISTS</token> is
11531 <quote>true</>; if the subquery returns no rows, the result of <token>EXISTS</token>
11532 is <quote>false</>.
11536 The subquery can refer to variables from the surrounding query,
11537 which will act as constants during any one evaluation of the subquery.
11541 The subquery will generally only be executed long enough to determine
11542 whether at least one row is returned, not all the way to completion.
11543 It is unwise to write a subquery that has side effects (such as
11544 calling sequence functions); whether the side effects occur
11545 might be unpredictable.
11549 Since the result depends only on whether any rows are returned,
11550 and not on the contents of those rows, the output list of the
11551 subquery is normally unimportant. A common coding convention is
11552 to write all <literal>EXISTS</> tests in the form
11553 <literal>EXISTS(SELECT 1 WHERE ...)</literal>. There are exceptions to
11554 this rule however, such as subqueries that use <token>INTERSECT</token>.
11558 This simple example is like an inner join on <literal>col2</>, but
11559 it produces at most one output row for each <literal>tab1</> row,
11560 even if there are several matching <literal>tab2</> rows:
11564 WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
11569 <sect2 id="functions-subquery-in">
11570 <title><literal>IN</literal></title>
11573 <replaceable>expression</replaceable> IN (<replaceable>subquery</replaceable>)
11577 The right-hand side is a parenthesized
11578 subquery, which must return exactly one column. The left-hand expression
11579 is evaluated and compared to each row of the subquery result.
11580 The result of <token>IN</token> is <quote>true</> if any equal subquery row is found.
11581 The result is <quote>false</> if no equal row is found (including the
11582 case where the subquery returns no rows).
11586 Note that if the left-hand expression yields null, or if there are
11587 no equal right-hand values and at least one right-hand row yields
11588 null, the result of the <token>IN</token> construct will be null, not false.
11589 This is in accordance with SQL's normal rules for Boolean combinations
11594 As with <token>EXISTS</token>, it's unwise to assume that the subquery will
11595 be evaluated completely.
11599 <replaceable>row_constructor</replaceable> IN (<replaceable>subquery</replaceable>)
11603 The left-hand side of this form of <token>IN</token> is a row constructor,
11604 as described in <xref linkend="sql-syntax-row-constructors">.
11605 The right-hand side is a parenthesized
11606 subquery, which must return exactly as many columns as there are
11607 expressions in the left-hand row. The left-hand expressions are
11608 evaluated and compared row-wise to each row of the subquery result.
11609 The result of <token>IN</token> is <quote>true</> if any equal subquery row is found.
11610 The result is <quote>false</> if no equal row is found (including the
11611 case where the subquery returns no rows).
11615 As usual, null values in the rows are combined per
11616 the normal rules of SQL Boolean expressions. Two rows are considered
11617 equal if all their corresponding members are non-null and equal; the rows
11618 are unequal if any corresponding members are non-null and unequal;
11619 otherwise the result of that row comparison is unknown (null).
11620 If all the per-row results are either unequal or null, with at least one
11621 null, then the result of <token>IN</token> is null.
11625 <sect2 id="functions-subquery-notin">
11626 <title><literal>NOT IN</literal></title>
11629 <replaceable>expression</replaceable> NOT IN (<replaceable>subquery</replaceable>)
11633 The right-hand side is a parenthesized
11634 subquery, which must return exactly one column. The left-hand expression
11635 is evaluated and compared to each row of the subquery result.
11636 The result of <token>NOT IN</token> is <quote>true</> if only unequal subquery rows
11637 are found (including the case where the subquery returns no rows).
11638 The result is <quote>false</> if any equal row is found.
11642 Note that if the left-hand expression yields null, or if there are
11643 no equal right-hand values and at least one right-hand row yields
11644 null, the result of the <token>NOT IN</token> construct will be null, not true.
11645 This is in accordance with SQL's normal rules for Boolean combinations
11650 As with <token>EXISTS</token>, it's unwise to assume that the subquery will
11651 be evaluated completely.
11655 <replaceable>row_constructor</replaceable> NOT IN (<replaceable>subquery</replaceable>)
11659 The left-hand side of this form of <token>NOT IN</token> is a row constructor,
11660 as described in <xref linkend="sql-syntax-row-constructors">.
11661 The right-hand side is a parenthesized
11662 subquery, which must return exactly as many columns as there are
11663 expressions in the left-hand row. The left-hand expressions are
11664 evaluated and compared row-wise to each row of the subquery result.
11665 The result of <token>NOT IN</token> is <quote>true</> if only unequal subquery rows
11666 are found (including the case where the subquery returns no rows).
11667 The result is <quote>false</> if any equal row is found.
11671 As usual, null values in the rows are combined per
11672 the normal rules of SQL Boolean expressions. Two rows are considered
11673 equal if all their corresponding members are non-null and equal; the rows
11674 are unequal if any corresponding members are non-null and unequal;
11675 otherwise the result of that row comparison is unknown (null).
11676 If all the per-row results are either unequal or null, with at least one
11677 null, then the result of <token>NOT IN</token> is null.
11681 <sect2 id="functions-subquery-any-some">
11682 <title><literal>ANY</literal>/<literal>SOME</literal></title>
11685 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>subquery</replaceable>)
11686 <replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>subquery</replaceable>)
11690 The right-hand side is a parenthesized
11691 subquery, which must return exactly one column. The left-hand expression
11692 is evaluated and compared to each row of the subquery result using the
11693 given <replaceable>operator</replaceable>, which must yield a Boolean
11695 The result of <token>ANY</token> is <quote>true</> if any true result is obtained.
11696 The result is <quote>false</> if no true result is found (including the
11697 case where the subquery returns no rows).
11701 <token>SOME</token> is a synonym for <token>ANY</token>.
11702 <token>IN</token> is equivalent to <literal>= ANY</literal>.
11706 Note that if there are no successes and at least one right-hand row yields
11707 null for the operator's result, the result of the <token>ANY</token> construct
11708 will be null, not false.
11709 This is in accordance with SQL's normal rules for Boolean combinations
11714 As with <token>EXISTS</token>, it's unwise to assume that the subquery will
11715 be evaluated completely.
11719 <replaceable>row_constructor</replaceable> <replaceable>operator</> ANY (<replaceable>subquery</replaceable>)
11720 <replaceable>row_constructor</replaceable> <replaceable>operator</> SOME (<replaceable>subquery</replaceable>)
11724 The left-hand side of this form of <token>ANY</token> is a row constructor,
11725 as described in <xref linkend="sql-syntax-row-constructors">.
11726 The right-hand side is a parenthesized
11727 subquery, which must return exactly as many columns as there are
11728 expressions in the left-hand row. The left-hand expressions are
11729 evaluated and compared row-wise to each row of the subquery result,
11730 using the given <replaceable>operator</replaceable>.
11731 The result of <token>ANY</token> is <quote>true</> if the comparison
11732 returns true for any subquery row.
11733 The result is <quote>false</> if the comparison returns false for every
11734 subquery row (including the case where the subquery returns no
11736 The result is NULL if the comparison does not return true for any row,
11737 and it returns NULL for at least one row.
11741 See <xref linkend="row-wise-comparison"> for details about the meaning
11742 of a row-wise comparison.
11746 <sect2 id="functions-subquery-all">
11747 <title><literal>ALL</literal></title>
11750 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
11754 The right-hand side is a parenthesized
11755 subquery, which must return exactly one column. The left-hand expression
11756 is evaluated and compared to each row of the subquery result using the
11757 given <replaceable>operator</replaceable>, which must yield a Boolean
11759 The result of <token>ALL</token> is <quote>true</> if all rows yield true
11760 (including the case where the subquery returns no rows).
11761 The result is <quote>false</> if any false result is found.
11762 The result is NULL if the comparison does not return false for any row,
11763 and it returns NULL for at least one row.
11767 <token>NOT IN</token> is equivalent to <literal><> ALL</literal>.
11771 As with <token>EXISTS</token>, it's unwise to assume that the subquery will
11772 be evaluated completely.
11776 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
11780 The left-hand side of this form of <token>ALL</token> is a row constructor,
11781 as described in <xref linkend="sql-syntax-row-constructors">.
11782 The right-hand side is a parenthesized
11783 subquery, which must return exactly as many columns as there are
11784 expressions in the left-hand row. The left-hand expressions are
11785 evaluated and compared row-wise to each row of the subquery result,
11786 using the given <replaceable>operator</replaceable>.
11787 The result of <token>ALL</token> is <quote>true</> if the comparison
11788 returns true for all subquery rows (including the
11789 case where the subquery returns no rows).
11790 The result is <quote>false</> if the comparison returns false for any
11792 The result is NULL if the comparison does not return false for any
11793 subquery row, and it returns NULL for at least one row.
11797 See <xref linkend="row-wise-comparison"> for details about the meaning
11798 of a row-wise comparison.
11803 <title>Row-wise Comparison</title>
11805 <indexterm zone="functions-subquery">
11806 <primary>comparison</primary>
11807 <secondary>subquery result row</secondary>
11811 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> (<replaceable>subquery</replaceable>)
11815 The left-hand side is a row constructor,
11816 as described in <xref linkend="sql-syntax-row-constructors">.
11817 The right-hand side is a parenthesized subquery, which must return exactly
11818 as many columns as there are expressions in the left-hand row. Furthermore,
11819 the subquery cannot return more than one row. (If it returns zero rows,
11820 the result is taken to be null.) The left-hand side is evaluated and
11821 compared row-wise to the single subquery result row.
11825 See <xref linkend="row-wise-comparison"> for details about the meaning
11826 of a row-wise comparison.
11832 <sect1 id="functions-comparisons">
11833 <title>Row and Array Comparisons</title>
11836 <primary>IN</primary>
11840 <primary>NOT IN</primary>
11844 <primary>ANY</primary>
11848 <primary>ALL</primary>
11852 <primary>SOME</primary>
11856 <primary>row-wise comparison</primary>
11860 <primary>comparison</primary>
11861 <secondary>row-wise</secondary>
11865 <primary>IS DISTINCT FROM</primary>
11869 <primary>IS NOT DISTINCT FROM</primary>
11873 This section describes several specialized constructs for making
11874 multiple comparisons between groups of values. These forms are
11875 syntactically related to the subquery forms of the previous section,
11876 but do not involve subqueries.
11877 The forms involving array subexpressions are
11878 <productname>PostgreSQL</productname> extensions; the rest are
11879 <acronym>SQL</acronym>-compliant.
11880 All of the expression forms documented in this section return
11881 Boolean (true/false) results.
11885 <title><literal>IN</literal></title>
11888 <replaceable>expression</replaceable> IN (<replaceable>value</replaceable> <optional>, ...</optional>)
11892 The right-hand side is a parenthesized list
11893 of scalar expressions. The result is <quote>true</> if the left-hand expression's
11894 result is equal to any of the right-hand expressions. This is a shorthand
11898 <replaceable>expression</replaceable> = <replaceable>value1</replaceable>
11900 <replaceable>expression</replaceable> = <replaceable>value2</replaceable>
11907 Note that if the left-hand expression yields null, or if there are
11908 no equal right-hand values and at least one right-hand expression yields
11909 null, the result of the <token>IN</token> construct will be null, not false.
11910 This is in accordance with SQL's normal rules for Boolean combinations
11916 <title><literal>NOT IN</literal></title>
11919 <replaceable>expression</replaceable> NOT IN (<replaceable>value</replaceable> <optional>, ...</optional>)
11923 The right-hand side is a parenthesized list
11924 of scalar expressions. The result is <quote>true</quote> if the left-hand expression's
11925 result is unequal to all of the right-hand expressions. This is a shorthand
11929 <replaceable>expression</replaceable> <> <replaceable>value1</replaceable>
11931 <replaceable>expression</replaceable> <> <replaceable>value2</replaceable>
11938 Note that if the left-hand expression yields null, or if there are
11939 no equal right-hand values and at least one right-hand expression yields
11940 null, the result of the <token>NOT IN</token> construct will be null, not true
11941 as one might naively expect.
11942 This is in accordance with SQL's normal rules for Boolean combinations
11948 <literal>x NOT IN y</literal> is equivalent to <literal>NOT (x IN y)</literal> in all
11949 cases. However, null values are much more likely to trip up the novice when
11950 working with <token>NOT IN</token> than when working with <token>IN</token>.
11951 It is best to express your condition positively if possible.
11957 <title><literal>ANY</literal>/<literal>SOME</literal> (array)</title>
11960 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>array expression</replaceable>)
11961 <replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>array expression</replaceable>)
11965 The right-hand side is a parenthesized expression, which must yield an
11967 The left-hand expression
11968 is evaluated and compared to each element of the array using the
11969 given <replaceable>operator</replaceable>, which must yield a Boolean
11971 The result of <token>ANY</token> is <quote>true</> if any true result is obtained.
11972 The result is <quote>false</> if no true result is found (including the
11973 case where the array has zero elements).
11977 If the array expression yields a null array, the result of
11978 <token>ANY</token> will be null. If the left-hand expression yields null,
11979 the result of <token>ANY</token> is ordinarily null (though a non-strict
11980 comparison operator could possibly yield a different result).
11981 Also, if the right-hand array contains any null elements and no true
11982 comparison result is obtained, the result of <token>ANY</token>
11983 will be null, not false (again, assuming a strict comparison operator).
11984 This is in accordance with SQL's normal rules for Boolean combinations
11989 <token>SOME</token> is a synonym for <token>ANY</token>.
11994 <title><literal>ALL</literal> (array)</title>
11997 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>array expression</replaceable>)
12001 The right-hand side is a parenthesized expression, which must yield an
12003 The left-hand expression
12004 is evaluated and compared to each element of the array using the
12005 given <replaceable>operator</replaceable>, which must yield a Boolean
12007 The result of <token>ALL</token> is <quote>true</> if all comparisons yield true
12008 (including the case where the array has zero elements).
12009 The result is <quote>false</> if any false result is found.
12013 If the array expression yields a null array, the result of
12014 <token>ALL</token> will be null. If the left-hand expression yields null,
12015 the result of <token>ALL</token> is ordinarily null (though a non-strict
12016 comparison operator could possibly yield a different result).
12017 Also, if the right-hand array contains any null elements and no false
12018 comparison result is obtained, the result of <token>ALL</token>
12019 will be null, not true (again, assuming a strict comparison operator).
12020 This is in accordance with SQL's normal rules for Boolean combinations
12025 <sect2 id="row-wise-comparison">
12026 <title>Row-wise Comparison</title>
12029 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> <replaceable>row_constructor</replaceable>
12033 Each side is a row constructor,
12034 as described in <xref linkend="sql-syntax-row-constructors">.
12035 The two row values must have the same number of fields.
12036 Each side is evaluated and they are compared row-wise. Row comparisons
12037 are allowed when the <replaceable>operator</replaceable> is
12039 <literal><></>,
12042 <literal>></> or
12044 or has semantics similar to one of these. (To be specific, an operator
12045 can be a row comparison operator if it is a member of a B-tree operator
12046 class, or is the negator of the <literal>=</> member of a B-tree operator
12051 The <literal>=</> and <literal><></> cases work slightly differently
12052 from the others. Two rows are considered
12053 equal if all their corresponding members are non-null and equal; the rows
12054 are unequal if any corresponding members are non-null and unequal;
12055 otherwise the result of the row comparison is unknown (null).
12059 For the <literal><</>, <literal><=</>, <literal>></> and
12060 <literal>>=</> cases, the row elements are compared left-to-right,
12061 stopping as soon as an unequal or null pair of elements is found.
12062 If either of this pair of elements is null, the result of the
12063 row comparison is unknown (null); otherwise comparison of this pair
12064 of elements determines the result. For example,
12065 <literal>ROW(1,2,NULL) < ROW(1,3,0)</>
12066 yields true, not null, because the third pair of elements are not
12072 Prior to <productname>PostgreSQL</productname> 8.2, the
12073 <literal><</>, <literal><=</>, <literal>></> and <literal>>=</>
12074 cases were not handled per SQL specification. A comparison like
12075 <literal>ROW(a,b) < ROW(c,d)</>
12077 <literal>a < c AND b < d</>
12078 whereas the correct behavior is equivalent to
12079 <literal>a < c OR (a = c AND b < d)</>.
12084 <replaceable>row_constructor</replaceable> IS DISTINCT FROM <replaceable>row_constructor</replaceable>
12088 This construct is similar to a <literal><></literal> row comparison,
12089 but it does not yield null for null inputs. Instead, any null value is
12090 considered unequal to (distinct from) any non-null value, and any two
12091 nulls are considered equal (not distinct). Thus the result will
12092 either be true or false, never null.
12096 <replaceable>row_constructor</replaceable> IS NOT DISTINCT FROM <replaceable>row_constructor</replaceable>
12100 This construct is similar to a <literal>=</literal> row comparison,
12101 but it does not yield null for null inputs. Instead, any null value is
12102 considered unequal to (distinct from) any non-null value, and any two
12103 nulls are considered equal (not distinct). Thus the result will always
12104 be either true or false, never null.
12109 The SQL specification requires row-wise comparison to return NULL if the
12110 result depends on comparing two NULL values or a NULL and a non-NULL.
12111 <productname>PostgreSQL</productname> does this only when comparing the
12112 results of two row constructors or comparing a row constructor to the
12113 output of a subquery (as in <xref linkend="functions-subquery">).
12114 In other contexts where two composite-type values are compared, two
12115 NULL field values are considered equal, and a NULL is considered larger
12116 than a non-NULL. This is necessary in order to have consistent sorting
12117 and indexing behavior for composite types.
12124 <sect1 id="functions-srf">
12125 <title>Set Returning Functions</title>
12127 <indexterm zone="functions-srf">
12128 <primary>set returning functions</primary>
12129 <secondary>functions</secondary>
12133 <primary>generate_series</primary>
12137 This section describes functions that possibly return more than one row.
12138 Currently the only functions in this class are series generating functions,
12139 as detailed in <xref linkend="functions-srf-series"> and
12140 <xref linkend="functions-srf-subscripts">.
12143 <table id="functions-srf-series">
12144 <title>Series Generating Functions</title>
12148 <entry>Function</entry>
12149 <entry>Argument Type</entry>
12150 <entry>Return Type</entry>
12151 <entry>Description</entry>
12157 <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>)</function></literal></entry>
12158 <entry><type>int</type> or <type>bigint</type></entry>
12159 <entry><type>setof int</type> or <type>setof bigint</type> (same as argument type)</entry>
12161 Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
12162 with a step size of one
12167 <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter>)</function></literal></entry>
12168 <entry><type>int</type> or <type>bigint</type></entry>
12169 <entry><type>setof int</type> or <type>setof bigint</type> (same as argument type)</entry>
12171 Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
12172 with a step size of <parameter>step</parameter>
12177 <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter> <type>interval</>)</function></literal></entry>
12178 <entry><type>timestamp</type> or <type>timestamp with time zone</type></entry>
12179 <entry><type>setof timestamp</type> or <type>setof timestamp with time zone</type> (same as argument type)</entry>
12181 Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
12182 with a step size of <parameter>step</parameter>
12191 When <parameter>step</parameter> is positive, zero rows are returned if
12192 <parameter>start</parameter> is greater than <parameter>stop</parameter>.
12193 Conversely, when <parameter>step</parameter> is negative, zero rows are
12194 returned if <parameter>start</parameter> is less than <parameter>stop</parameter>.
12195 Zero rows are also returned for <literal>NULL</literal> inputs. It is an error
12196 for <parameter>step</parameter> to be zero. Some examples follow:
12198 SELECT * FROM generate_series(2,4);
12206 SELECT * FROM generate_series(5,1,-2);
12214 SELECT * FROM generate_series(4,3);
12219 -- this example relies on the date-plus-integer operator
12220 SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a);
12228 SELECT * FROM generate_series('2008-03-01 00:00'::timestamp,
12229 '2008-03-04 12:00', '10 hours');
12231 ---------------------
12232 2008-03-01 00:00:00
12233 2008-03-01 10:00:00
12234 2008-03-01 20:00:00
12235 2008-03-02 06:00:00
12236 2008-03-02 16:00:00
12237 2008-03-03 02:00:00
12238 2008-03-03 12:00:00
12239 2008-03-03 22:00:00
12240 2008-03-04 08:00:00
12245 <table id="functions-srf-subscripts">
12246 <title>Subscript Generating Functions</title>
12250 <entry>Function</entry>
12251 <entry>Return Type</entry>
12252 <entry>Description</entry>
12258 <entry><literal><function>generate_subscripts(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>)</function></literal></entry>
12259 <entry><type>setof int</type></entry>
12261 Generate a series comprising the given array's subscripts.
12266 <entry><literal><function>generate_subscripts(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>, <parameter>reverse boolean</parameter>)</function></literal></entry>
12267 <entry><type>setof int</type></entry>
12269 Generate a series comprising the given array's subscripts. When
12270 <parameter>reverse</parameter> is true, the series is returned in
12280 <primary>generate_subscripts</primary>
12284 <function>generate_subscripts</> is a convenience function that generates
12285 the set of valid subscripts for the specified dimension of the given
12287 Zero rows are returned for arrays that do not have the requested dimension,
12288 or for NULL arrays (but valid subscripts are returned for NULL array
12289 elements). Some examples follow:
12292 SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s;
12301 -- presenting an array, the subscript and the subscripted
12302 -- value requires a subquery
12303 SELECT * FROM arrays;
12305 --------------------
12310 SELECT a AS array, s AS subscript, a[s] AS value
12311 FROM (SELECT generate_subscripts(a, 1) AS s, a FROM arrays) foo;
12312 array | subscript | value
12313 ---------------+-----------+-------
12316 {100,200,300} | 1 | 100
12317 {100,200,300} | 2 | 200
12318 {100,200,300} | 3 | 300
12321 -- unnest a 2D array
12322 CREATE OR REPLACE FUNCTION unnest2(anyarray)
12323 RETURNS SETOF anyelement AS $$
12325 from generate_subscripts($1,1) g1(i),
12326 generate_subscripts($1,2) g2(j);
12327 $$ LANGUAGE sql IMMUTABLE;
12329 postgres=# SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]);
12342 <sect1 id="functions-info">
12343 <title>System Information Functions</title>
12346 <xref linkend="functions-info-session-table"> shows several
12347 functions that extract session and system information.
12351 In addition to the functions listed in this section, there are a number of
12352 functions related to the statistics system that also provide system
12353 information. See <xref linkend="monitoring-stats-views"> for more
12357 <table id="functions-info-session-table">
12358 <title>Session Information Functions</title>
12361 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12366 <entry><literal><function>current_catalog</function></literal></entry>
12367 <entry><type>name</type></entry>
12368 <entry>name of current database (called <quote>catalog</quote> in the SQL standard)</entry>
12372 <entry><literal><function>current_database()</function></literal></entry>
12373 <entry><type>name</type></entry>
12374 <entry>name of current database</entry>
12378 <entry><literal><function>current_query()</function></literal></entry>
12379 <entry><type>text</type></entry>
12380 <entry>text of the currently executing query, as submitted
12381 by the client (might contain more than one statement)</entry>
12385 <entry><literal><function>current_schema</function>[()]</literal></entry>
12386 <entry><type>name</type></entry>
12387 <entry>name of current schema</entry>
12391 <entry><literal><function>current_schemas(<type>boolean</type>)</function></literal></entry>
12392 <entry><type>name[]</type></entry>
12393 <entry>names of schemas in search path, optionally including implicit schemas</entry>
12397 <entry><literal><function>current_user</function></literal></entry>
12398 <entry><type>name</type></entry>
12399 <entry>user name of current execution context</entry>
12403 <entry><literal><function>inet_client_addr()</function></literal></entry>
12404 <entry><type>inet</type></entry>
12405 <entry>address of the remote connection</entry>
12409 <entry><literal><function>inet_client_port()</function></literal></entry>
12410 <entry><type>int</type></entry>
12411 <entry>port of the remote connection</entry>
12415 <entry><literal><function>inet_server_addr()</function></literal></entry>
12416 <entry><type>inet</type></entry>
12417 <entry>address of the local connection</entry>
12421 <entry><literal><function>inet_server_port()</function></literal></entry>
12422 <entry><type>int</type></entry>
12423 <entry>port of the local connection</entry>
12427 <!-- See also the entry for this in monitoring.sgml -->
12428 <entry><literal><function>pg_backend_pid()</function></literal></entry>
12429 <entry><type>int</type></entry>
12431 Process ID of the server process attached to the current session
12436 <entry><literal><function>pg_conf_load_time()</function></literal></entry>
12437 <entry><type>timestamp with time zone</type></entry>
12438 <entry>configuration load time</entry>
12442 <entry><literal><function>pg_is_other_temp_schema(<type>oid</type>)</function></literal></entry>
12443 <entry><type>boolean</type></entry>
12444 <entry>is schema another session's temporary schema?</entry>
12448 <entry><literal><function>pg_listening_channels()</function></literal></entry>
12449 <entry><type>setof text</type></entry>
12450 <entry>channel names that the session is currently listening on</entry>
12454 <entry><literal><function>pg_my_temp_schema()</function></literal></entry>
12455 <entry><type>oid</type></entry>
12456 <entry>OID of session's temporary schema, or 0 if none</entry>
12460 <entry><literal><function>pg_postmaster_start_time()</function></literal></entry>
12461 <entry><type>timestamp with time zone</type></entry>
12462 <entry>server start time</entry>
12466 <entry><literal><function>session_user</function></literal></entry>
12467 <entry><type>name</type></entry>
12468 <entry>session user name</entry>
12472 <entry><literal><function>user</function></literal></entry>
12473 <entry><type>name</type></entry>
12474 <entry>equivalent to <function>current_user</function></entry>
12478 <entry><literal><function>version()</function></literal></entry>
12479 <entry><type>text</type></entry>
12480 <entry><productname>PostgreSQL</> version information</entry>
12488 <function>current_catalog</function>, <function>current_schema</function>,
12489 <function>current_user</function>, <function>session_user</function>,
12490 and <function>user</function> have special syntactic status
12491 in <acronym>SQL</acronym>: they must be called without trailing
12492 parentheses. (In PostgreSQL, parentheses can optionally be used with
12493 <function>current_schema</function>, but not with the others.)
12498 <primary>current_catalog</primary>
12502 <primary>current_database</primary>
12506 <primary>current_query</primary>
12510 <primary>current_schema</primary>
12514 <primary>current_schemas</primary>
12518 <primary>current_user</primary>
12522 <primary>pg_backend_pid</primary>
12526 <primary>schema</primary>
12527 <secondary>current</secondary>
12531 <primary>search path</primary>
12532 <secondary>current</secondary>
12536 <primary>session_user</primary>
12540 <primary>user</primary>
12541 <secondary>current</secondary>
12545 <primary>user</primary>
12549 The <function>session_user</function> is normally the user who initiated
12550 the current database connection; but superusers can change this setting
12551 with <xref linkend="sql-set-session-authorization">.
12552 The <function>current_user</function> is the user identifier
12553 that is applicable for permission checking. Normally it is equal
12554 to the session user, but it can be changed with
12555 <xref linkend="sql-set-role">.
12556 It also changes during the execution of
12557 functions with the attribute <literal>SECURITY DEFINER</literal>.
12558 In Unix parlance, the session user is the <quote>real user</quote> and
12559 the current user is the <quote>effective user</quote>.
12563 <function>current_schema</function> returns the name of the schema that is
12564 first in the search path (or a null value if the search path is
12565 empty). This is the schema that will be used for any tables or
12566 other named objects that are created without specifying a target schema.
12567 <function>current_schemas(boolean)</function> returns an array of the names of all
12568 schemas presently in the search path. The Boolean option determines whether or not
12569 implicitly included system schemas such as <literal>pg_catalog</> are included in the
12570 returned search path.
12575 The search path can be altered at run time. The command is:
12577 SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ...</optional>
12583 <primary>pg_listening_channels</primary>
12587 <function>pg_listening_channels</function> returns a set of names of
12588 channels that the current session is listening to. See <xref
12589 linkend="sql-listen"> for more information.
12593 <primary>inet_client_addr</primary>
12597 <primary>inet_client_port</primary>
12601 <primary>inet_server_addr</primary>
12605 <primary>inet_server_port</primary>
12609 <function>inet_client_addr</function> returns the IP address of the
12610 current client, and <function>inet_client_port</function> returns the
12612 <function>inet_server_addr</function> returns the IP address on which
12613 the server accepted the current connection, and
12614 <function>inet_server_port</function> returns the port number.
12615 All these functions return NULL if the current connection is via a
12616 Unix-domain socket.
12620 <primary>pg_my_temp_schema</primary>
12624 <primary>pg_is_other_temp_schema</primary>
12628 <function>pg_my_temp_schema</function> returns the OID of the current
12629 session's temporary schema, or zero if it has none (because it has not
12630 created any temporary tables).
12631 <function>pg_is_other_temp_schema</function> returns true if the
12632 given OID is the OID of another session's temporary schema.
12633 (This can be useful, for example, to exclude other sessions' temporary
12634 tables from a catalog display.)
12638 <primary>pg_postmaster_start_time</primary>
12642 <function>pg_postmaster_start_time</function> returns the
12643 <type>timestamp with time zone</type> when the
12648 <primary>pg_conf_load_time</primary>
12652 <function>pg_conf_load_time</function> returns the
12653 <type>timestamp with time zone</type> when the
12654 server configuration files were last loaded.
12655 (If the current session was alive at the time, this will be the time
12656 when the session itself re-read the configuration files, so the
12657 reading will vary a little in different sessions. Otherwise it is
12658 the time when the postmaster process re-read the configuration files.)
12662 <primary>version</primary>
12666 <function>version</function> returns a string describing the
12667 <productname>PostgreSQL</productname> server's version.
12671 <primary>privilege</primary>
12672 <secondary>querying</secondary>
12676 <xref linkend="functions-info-access-table"> lists functions that
12677 allow the user to query object access privileges programmatically.
12678 See <xref linkend="ddl-priv"> for more information about
12682 <table id="functions-info-access-table">
12683 <title>Access Privilege Inquiry Functions</title>
12686 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12691 <entry><literal><function>has_any_column_privilege</function>(<parameter>user</parameter>,
12692 <parameter>table</parameter>,
12693 <parameter>privilege</parameter>)</literal>
12695 <entry><type>boolean</type></entry>
12696 <entry>does user have privilege for any column of table</entry>
12699 <entry><literal><function>has_any_column_privilege</function>(<parameter>table</parameter>,
12700 <parameter>privilege</parameter>)</literal>
12702 <entry><type>boolean</type></entry>
12703 <entry>does current user have privilege for any column of table</entry>
12706 <entry><literal><function>has_column_privilege</function>(<parameter>user</parameter>,
12707 <parameter>table</parameter>,
12708 <parameter>column</parameter>,
12709 <parameter>privilege</parameter>)</literal>
12711 <entry><type>boolean</type></entry>
12712 <entry>does user have privilege for column</entry>
12715 <entry><literal><function>has_column_privilege</function>(<parameter>table</parameter>,
12716 <parameter>column</parameter>,
12717 <parameter>privilege</parameter>)</literal>
12719 <entry><type>boolean</type></entry>
12720 <entry>does current user have privilege for column</entry>
12723 <entry><literal><function>has_database_privilege</function>(<parameter>user</parameter>,
12724 <parameter>database</parameter>,
12725 <parameter>privilege</parameter>)</literal>
12727 <entry><type>boolean</type></entry>
12728 <entry>does user have privilege for database</entry>
12731 <entry><literal><function>has_database_privilege</function>(<parameter>database</parameter>,
12732 <parameter>privilege</parameter>)</literal>
12734 <entry><type>boolean</type></entry>
12735 <entry>does current user have privilege for database</entry>
12738 <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>user</parameter>,
12739 <parameter>fdw</parameter>,
12740 <parameter>privilege</parameter>)</literal>
12742 <entry><type>boolean</type></entry>
12743 <entry>does user have privilege for foreign-data wrapper</entry>
12746 <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>fdw</parameter>,
12747 <parameter>privilege</parameter>)</literal>
12749 <entry><type>boolean</type></entry>
12750 <entry>does current user have privilege for foreign-data wrapper</entry>
12753 <entry><literal><function>has_function_privilege</function>(<parameter>user</parameter>,
12754 <parameter>function</parameter>,
12755 <parameter>privilege</parameter>)</literal>
12757 <entry><type>boolean</type></entry>
12758 <entry>does user have privilege for function</entry>
12761 <entry><literal><function>has_function_privilege</function>(<parameter>function</parameter>,
12762 <parameter>privilege</parameter>)</literal>
12764 <entry><type>boolean</type></entry>
12765 <entry>does current user have privilege for function</entry>
12768 <entry><literal><function>has_language_privilege</function>(<parameter>user</parameter>,
12769 <parameter>language</parameter>,
12770 <parameter>privilege</parameter>)</literal>
12772 <entry><type>boolean</type></entry>
12773 <entry>does user have privilege for language</entry>
12776 <entry><literal><function>has_language_privilege</function>(<parameter>language</parameter>,
12777 <parameter>privilege</parameter>)</literal>
12779 <entry><type>boolean</type></entry>
12780 <entry>does current user have privilege for language</entry>
12783 <entry><literal><function>has_schema_privilege</function>(<parameter>user</parameter>,
12784 <parameter>schema</parameter>,
12785 <parameter>privilege</parameter>)</literal>
12787 <entry><type>boolean</type></entry>
12788 <entry>does user have privilege for schema</entry>
12791 <entry><literal><function>has_schema_privilege</function>(<parameter>schema</parameter>,
12792 <parameter>privilege</parameter>)</literal>
12794 <entry><type>boolean</type></entry>
12795 <entry>does current user have privilege for schema</entry>
12798 <entry><literal><function>has_sequence_privilege</function>(<parameter>user</parameter>,
12799 <parameter>sequence</parameter>,
12800 <parameter>privilege</parameter>)</literal>
12802 <entry><type>boolean</type></entry>
12803 <entry>does user have privilege for sequence</entry>
12806 <entry><literal><function>has_sequence_privilege</function>(<parameter>sequence</parameter>,
12807 <parameter>privilege</parameter>)</literal>
12809 <entry><type>boolean</type></entry>
12810 <entry>does current user have privilege for sequence</entry>
12813 <entry><literal><function>has_server_privilege</function>(<parameter>user</parameter>,
12814 <parameter>server</parameter>,
12815 <parameter>privilege</parameter>)</literal>
12817 <entry><type>boolean</type></entry>
12818 <entry>does user have privilege for foreign server</entry>
12821 <entry><literal><function>has_server_privilege</function>(<parameter>server</parameter>,
12822 <parameter>privilege</parameter>)</literal>
12824 <entry><type>boolean</type></entry>
12825 <entry>does current user have privilege for foreign server</entry>
12828 <entry><literal><function>has_table_privilege</function>(<parameter>user</parameter>,
12829 <parameter>table</parameter>,
12830 <parameter>privilege</parameter>)</literal>
12832 <entry><type>boolean</type></entry>
12833 <entry>does user have privilege for table</entry>
12836 <entry><literal><function>has_table_privilege</function>(<parameter>table</parameter>,
12837 <parameter>privilege</parameter>)</literal>
12839 <entry><type>boolean</type></entry>
12840 <entry>does current user have privilege for table</entry>
12843 <entry><literal><function>has_tablespace_privilege</function>(<parameter>user</parameter>,
12844 <parameter>tablespace</parameter>,
12845 <parameter>privilege</parameter>)</literal>
12847 <entry><type>boolean</type></entry>
12848 <entry>does user have privilege for tablespace</entry>
12851 <entry><literal><function>has_tablespace_privilege</function>(<parameter>tablespace</parameter>,
12852 <parameter>privilege</parameter>)</literal>
12854 <entry><type>boolean</type></entry>
12855 <entry>does current user have privilege for tablespace</entry>
12858 <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>,
12859 <parameter>role</parameter>,
12860 <parameter>privilege</parameter>)</literal>
12862 <entry><type>boolean</type></entry>
12863 <entry>does user have privilege for role</entry>
12866 <entry><literal><function>pg_has_role</function>(<parameter>role</parameter>,
12867 <parameter>privilege</parameter>)</literal>
12869 <entry><type>boolean</type></entry>
12870 <entry>does current user have privilege for role</entry>
12877 <primary>has_any_column_privilege</primary>
12880 <primary>has_column_privilege</primary>
12883 <primary>has_database_privilege</primary>
12886 <primary>has_function_privilege</primary>
12889 <primary>has_foreign_data_wrapper_privilege</primary>
12892 <primary>has_language_privilege</primary>
12895 <primary>has_schema_privilege</primary>
12898 <primary>has_server_privilege</primary>
12901 <primary>has_sequence_privilege</primary>
12904 <primary>has_table_privilege</primary>
12907 <primary>has_tablespace_privilege</primary>
12910 <primary>pg_has_role</primary>
12914 <function>has_table_privilege</function> checks whether a user
12915 can access a table in a particular way. The user can be
12916 specified by name, by OID (<literal>pg_authid.oid</literal>),
12917 <literal>public</> to indicate the PUBLIC pseudo-role, or if the argument is
12919 <function>current_user</function> is assumed. The table can be specified
12920 by name or by OID. (Thus, there are actually six variants of
12921 <function>has_table_privilege</function>, which can be distinguished by
12922 the number and types of their arguments.) When specifying by name,
12923 the name can be schema-qualified if necessary.
12924 The desired access privilege type
12925 is specified by a text string, which must evaluate to one of the
12926 values <literal>SELECT</literal>, <literal>INSERT</literal>,
12927 <literal>UPDATE</literal>, <literal>DELETE</literal>, <literal>TRUNCATE</>,
12928 <literal>REFERENCES</literal>, or <literal>TRIGGER</literal>. Optionally,
12929 <literal>WITH GRANT OPTION</> can be added to a privilege type to test
12930 whether the privilege is held with grant option. Also, multiple privilege
12931 types can be listed separated by commas, in which case the result will
12932 be <literal>true</> if any of the listed privileges is held.
12933 (Case of the privilege string is not significant, and extra whitespace
12934 is allowed between but not within privilege names.)
12937 SELECT has_table_privilege('myschema.mytable', 'select');
12938 SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
12943 <function>has_sequence_privilege</function> checks whether a user
12944 can access a sequence in a particular way. The possibilities for its
12945 arguments are analogous to <function>has_table_privilege</function>.
12946 The desired access privilege type must evaluate to one of
12947 <literal>USAGE</literal>,
12948 <literal>SELECT</literal>, or
12949 <literal>UPDATE</literal>.
12953 <function>has_any_column_privilege</function> checks whether a user can
12954 access any column of a table in a particular way.
12955 Its argument possibilities
12956 are analogous to <function>has_table_privilege</>,
12957 except that the desired access privilege type must evaluate to some
12959 <literal>SELECT</literal>,
12960 <literal>INSERT</literal>,
12961 <literal>UPDATE</literal>, or
12962 <literal>REFERENCES</literal>. Note that having any of these privileges
12963 at the table level implicitly grants it for each column of the table,
12964 so <function>has_any_column_privilege</function> will always return
12965 <literal>true</> if <function>has_table_privilege</> does for the same
12966 arguments. But <function>has_any_column_privilege</> also succeeds if
12967 there is a column-level grant of the privilege for at least one column.
12971 <function>has_column_privilege</function> checks whether a user
12972 can access a column in a particular way.
12973 Its argument possibilities
12974 are analogous to <function>has_table_privilege</function>,
12975 with the addition that the column can be specified either by name
12976 or attribute number.
12977 The desired access privilege type must evaluate to some combination of
12978 <literal>SELECT</literal>,
12979 <literal>INSERT</literal>,
12980 <literal>UPDATE</literal>, or
12981 <literal>REFERENCES</literal>. Note that having any of these privileges
12982 at the table level implicitly grants it for each column of the table.
12986 <function>has_database_privilege</function> checks whether a user
12987 can access a database in a particular way.
12988 Its argument possibilities
12989 are analogous to <function>has_table_privilege</function>.
12990 The desired access privilege type must evaluate to some combination of
12991 <literal>CREATE</literal>,
12992 <literal>CONNECT</literal>,
12993 <literal>TEMPORARY</literal>, or
12994 <literal>TEMP</literal> (which is equivalent to
12995 <literal>TEMPORARY</literal>).
12999 <function>has_function_privilege</function> checks whether a user
13000 can access a function in a particular way.
13001 Its argument possibilities
13002 are analogous to <function>has_table_privilege</function>.
13003 When specifying a function by a text string rather than by OID,
13004 the allowed input is the same as for the <type>regprocedure</> data type
13005 (see <xref linkend="datatype-oid">).
13006 The desired access privilege type must evaluate to
13007 <literal>EXECUTE</literal>.
13010 SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
13015 <function>has_foreign_data_wrapper_privilege</function> checks whether a user
13016 can access a foreign-data wrapper in a particular way.
13017 Its argument possibilities
13018 are analogous to <function>has_table_privilege</function>.
13019 The desired access privilege type must evaluate to
13020 <literal>USAGE</literal>.
13024 <function>has_language_privilege</function> checks whether a user
13025 can access a procedural language in a particular way.
13026 Its argument possibilities
13027 are analogous to <function>has_table_privilege</function>.
13028 The desired access privilege type must evaluate to
13029 <literal>USAGE</literal>.
13033 <function>has_schema_privilege</function> checks whether a user
13034 can access a schema in a particular way.
13035 Its argument possibilities
13036 are analogous to <function>has_table_privilege</function>.
13037 The desired access privilege type must evaluate to some combination of
13038 <literal>CREATE</literal> or
13039 <literal>USAGE</literal>.
13043 <function>has_server_privilege</function> checks whether a user
13044 can access a foreign server in a particular way.
13045 Its argument possibilities
13046 are analogous to <function>has_table_privilege</function>.
13047 The desired access privilege type must evaluate to
13048 <literal>USAGE</literal>.
13052 <function>has_tablespace_privilege</function> checks whether a user
13053 can access a tablespace in a particular way.
13054 Its argument possibilities
13055 are analogous to <function>has_table_privilege</function>.
13056 The desired access privilege type must evaluate to
13057 <literal>CREATE</literal>.
13061 <function>pg_has_role</function> checks whether a user
13062 can access a role in a particular way.
13063 Its argument possibilities
13064 are analogous to <function>has_table_privilege</function>,
13065 except that <literal>public</> is not allowed as a user name.
13066 The desired access privilege type must evaluate to some combination of
13067 <literal>MEMBER</literal> or
13068 <literal>USAGE</literal>.
13069 <literal>MEMBER</literal> denotes direct or indirect membership in
13070 the role (that is, the right to do <command>SET ROLE</>), while
13071 <literal>USAGE</literal> denotes whether the privileges of the role
13072 are immediately available without doing <command>SET ROLE</>.
13076 <xref linkend="functions-info-schema-table"> shows functions that
13077 determine whether a certain object is <firstterm>visible</> in the
13078 current schema search path.
13079 For example, a table is said to be visible if its
13080 containing schema is in the search path and no table of the same
13081 name appears earlier in the search path. This is equivalent to the
13082 statement that the table can be referenced by name without explicit
13083 schema qualification. To list the names of all visible tables:
13085 SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
13089 <table id="functions-info-schema-table">
13090 <title>Schema Visibility Inquiry Functions</title>
13093 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
13098 <entry><literal><function>pg_collation_is_visible(<parameter>collation_oid</parameter>)</function></literal>
13100 <entry><type>boolean</type></entry>
13101 <entry>is collation visible in search path</entry>
13104 <entry><literal><function>pg_conversion_is_visible(<parameter>conversion_oid</parameter>)</function></literal>
13106 <entry><type>boolean</type></entry>
13107 <entry>is conversion visible in search path</entry>
13110 <entry><literal><function>pg_function_is_visible(<parameter>function_oid</parameter>)</function></literal>
13112 <entry><type>boolean</type></entry>
13113 <entry>is function visible in search path</entry>
13116 <entry><literal><function>pg_opclass_is_visible(<parameter>opclass_oid</parameter>)</function></literal>
13118 <entry><type>boolean</type></entry>
13119 <entry>is operator class visible in search path</entry>
13122 <entry><literal><function>pg_operator_is_visible(<parameter>operator_oid</parameter>)</function></literal>
13124 <entry><type>boolean</type></entry>
13125 <entry>is operator visible in search path</entry>
13128 <entry><literal><function>pg_opfamily_is_visible(<parameter>opclass_oid</parameter>)</function></literal>
13130 <entry><type>boolean</type></entry>
13131 <entry>is operator family visible in search path</entry>
13134 <entry><literal><function>pg_table_is_visible(<parameter>table_oid</parameter>)</function></literal>
13136 <entry><type>boolean</type></entry>
13137 <entry>is table visible in search path</entry>
13140 <entry><literal><function>pg_ts_config_is_visible(<parameter>config_oid</parameter>)</function></literal>
13142 <entry><type>boolean</type></entry>
13143 <entry>is text search configuration visible in search path</entry>
13146 <entry><literal><function>pg_ts_dict_is_visible(<parameter>dict_oid</parameter>)</function></literal>
13148 <entry><type>boolean</type></entry>
13149 <entry>is text search dictionary visible in search path</entry>
13152 <entry><literal><function>pg_ts_parser_is_visible(<parameter>parser_oid</parameter>)</function></literal>
13154 <entry><type>boolean</type></entry>
13155 <entry>is text search parser visible in search path</entry>
13158 <entry><literal><function>pg_ts_template_is_visible(<parameter>template_oid</parameter>)</function></literal>
13160 <entry><type>boolean</type></entry>
13161 <entry>is text search template visible in search path</entry>
13164 <entry><literal><function>pg_type_is_visible(<parameter>type_oid</parameter>)</function></literal>
13166 <entry><type>boolean</type></entry>
13167 <entry>is type (or domain) visible in search path</entry>
13174 <primary>pg_collation_is_visible</primary>
13177 <primary>pg_conversion_is_visible</primary>
13180 <primary>pg_function_is_visible</primary>
13183 <primary>pg_opclass_is_visible</primary>
13186 <primary>pg_operator_is_visible</primary>
13189 <primary>pg_opfamily_is_visible</primary>
13192 <primary>pg_table_is_visible</primary>
13195 <primary>pg_ts_config_is_visible</primary>
13198 <primary>pg_ts_dict_is_visible</primary>
13201 <primary>pg_ts_parser_is_visible</primary>
13204 <primary>pg_ts_template_is_visible</primary>
13207 <primary>pg_type_is_visible</primary>
13211 Each function performs the visibility check for one type of database
13212 object. Note that <function>pg_table_is_visible</function> can also be used
13213 with views, indexes and sequences; <function>pg_type_is_visible</function>
13214 can also be used with domains. For functions and operators, an object in
13215 the search path is visible if there is no object of the same name
13216 <emphasis>and argument data type(s)</> earlier in the path. For operator
13217 classes, both name and associated index access method are considered.
13221 All these functions require object OIDs to identify the object to be
13222 checked. If you want to test an object by name, it is convenient to use
13223 the OID alias types (<type>regclass</>, <type>regtype</>,
13224 <type>regprocedure</>, <type>regoperator</>, <type>regconfig</>,
13225 or <type>regdictionary</>),
13228 SELECT pg_type_is_visible('myschema.widget'::regtype);
13230 Note that it would not make much sense to test a non-schema-qualified
13231 type name in this way — if the name can be recognized at all, it must be visible.
13235 <primary>format_type</primary>
13239 <primary>pg_describe_object</primary>
13243 <primary>pg_get_constraintdef</primary>
13247 <primary>pg_get_expr</primary>
13251 <primary>pg_get_functiondef</primary>
13255 <primary>pg_get_function_arguments</primary>
13259 <primary>pg_get_function_identity_arguments</primary>
13263 <primary>pg_get_function_result</primary>
13267 <primary>pg_get_indexdef</primary>
13271 <primary>pg_get_keywords</primary>
13275 <primary>pg_get_ruledef</primary>
13279 <primary>pg_get_serial_sequence</primary>
13283 <primary>pg_get_triggerdef</primary>
13287 <primary>pg_get_userbyid</primary>
13291 <primary>pg_get_viewdef</primary>
13295 <primary>pg_options_to_table</primary>
13299 <primary>pg_tablespace_databases</primary>
13303 <primary>pg_typeof</primary>
13307 <xref linkend="functions-info-catalog-table"> lists functions that
13308 extract information from the system catalogs.
13311 <table id="functions-info-catalog-table">
13312 <title>System Catalog Information Functions</title>
13315 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
13320 <entry><literal><function>format_type(<parameter>type_oid</parameter>, <parameter>typemod</>)</function></literal></entry>
13321 <entry><type>text</type></entry>
13322 <entry>get SQL name of a data type</entry>
13325 <entry><literal><function>pg_describe_object(<parameter>catalog_id</parameter>, <parameter>object_id</parameter>, <parameter>object_sub_id</parameter>)</function></literal></entry>
13326 <entry><type>text</type></entry>
13327 <entry>get description of a database object</entry>
13330 <entry><literal><function>pg_get_constraintdef(<parameter>constraint_oid</parameter>)</function></literal></entry>
13331 <entry><type>text</type></entry>
13332 <entry>get definition of a constraint</entry>
13335 <entry><literal><function>pg_get_constraintdef(<parameter>constraint_oid</parameter>, <parameter>pretty_bool</>)</function></literal></entry>
13336 <entry><type>text</type></entry>
13337 <entry>get definition of a constraint</entry>
13340 <entry><literal><function>pg_get_expr(<parameter>pg_node_tree</parameter>, <parameter>relation_oid</>)</function></literal></entry>
13341 <entry><type>text</type></entry>
13342 <entry>decompile internal form of an expression, assuming that any Vars
13343 in it refer to the relation indicated by the second parameter</entry>
13346 <entry><literal><function>pg_get_expr(<parameter>pg_node_tree</parameter>, <parameter>relation_oid</>, <parameter>pretty_bool</>)</function></literal></entry>
13347 <entry><type>text</type></entry>
13348 <entry>decompile internal form of an expression, assuming that any Vars
13349 in it refer to the relation indicated by the second parameter</entry>
13352 <entry><literal><function>pg_get_functiondef(<parameter>func_oid</parameter>)</function></literal></entry>
13353 <entry><type>text</type></entry>
13354 <entry>get definition of a function</entry>
13357 <entry><literal><function>pg_get_function_arguments(<parameter>func_oid</parameter>)</function></literal></entry>
13358 <entry><type>text</type></entry>
13359 <entry>get argument list of function's definition (with default values)</entry>
13362 <entry><literal><function>pg_get_function_identity_arguments(<parameter>func_oid</parameter>)</function></literal></entry>
13363 <entry><type>text</type></entry>
13364 <entry>get argument list to identify a function (without default values)</entry>
13367 <entry><literal><function>pg_get_function_result(<parameter>func_oid</parameter>)</function></literal></entry>
13368 <entry><type>text</type></entry>
13369 <entry>get <literal>RETURNS</> clause for function</entry>
13372 <entry><literal><function>pg_get_indexdef(<parameter>index_oid</parameter>)</function></literal></entry>
13373 <entry><type>text</type></entry>
13374 <entry>get <command>CREATE INDEX</> command for index</entry>
13377 <entry><literal><function>pg_get_indexdef(<parameter>index_oid</parameter>, <parameter>column_no</>, <parameter>pretty_bool</>)</function></literal></entry>
13378 <entry><type>text</type></entry>
13379 <entry>get <command>CREATE INDEX</> command for index,
13380 or definition of just one index column when
13381 <parameter>column_no</> is not zero</entry>
13384 <entry><literal><function>pg_get_keywords()</function></literal></entry>
13385 <entry><type>setof record</type></entry>
13386 <entry>get list of SQL keywords and their categories</entry>
13389 <entry><literal><function>pg_get_ruledef(<parameter>rule_oid</parameter>)</function></literal></entry>
13390 <entry><type>text</type></entry>
13391 <entry>get <command>CREATE RULE</> command for rule</entry>
13394 <entry><literal><function>pg_get_ruledef(<parameter>rule_oid</parameter>, <parameter>pretty_bool</>)</function></literal></entry>
13395 <entry><type>text</type></entry>
13396 <entry>get <command>CREATE RULE</> command for rule</entry>
13399 <entry><literal><function>pg_get_serial_sequence(<parameter>table_name</parameter>, <parameter>column_name</parameter>)</function></literal></entry>
13400 <entry><type>text</type></entry>
13401 <entry>get name of the sequence that a <type>serial</type>, <type>smallserial</type> or <type>bigserial</type> column
13405 <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry>
13406 <entry><type>text</type></entry>
13407 <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry>
13410 <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>, <parameter>pretty_bool</>)</entry>
13411 <entry><type>text</type></entry>
13412 <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry>
13415 <entry><literal><function>pg_get_userbyid(<parameter>role_oid</parameter>)</function></literal></entry>
13416 <entry><type>name</type></entry>
13417 <entry>get role name with given OID</entry>
13420 <entry><literal><function>pg_get_viewdef(<parameter>view_name</parameter>)</function></literal></entry>
13421 <entry><type>text</type></entry>
13422 <entry>get underlying <command>SELECT</command> command for view (<emphasis>deprecated</emphasis>)</entry>
13425 <entry><literal><function>pg_get_viewdef(<parameter>view_name</parameter>, <parameter>pretty_bool</>)</function></literal></entry>
13426 <entry><type>text</type></entry>
13427 <entry>get underlying <command>SELECT</command> command for view (<emphasis>deprecated</emphasis>)</entry>
13430 <entry><literal><function>pg_get_viewdef(<parameter>view_oid</parameter>)</function></literal></entry>
13431 <entry><type>text</type></entry>
13432 <entry>get underlying <command>SELECT</command> command for view</entry>
13435 <entry><literal><function>pg_get_viewdef(<parameter>view_oid</parameter>, <parameter>pretty_bool</>)</function></literal></entry>
13436 <entry><type>text</type></entry>
13437 <entry>get underlying <command>SELECT</command> command for view</entry>
13440 <entry><literal><function>pg_options_to_table(<parameter>reloptions</parameter>)</function></literal></entry>
13441 <entry><type>setof record</type></entry>
13442 <entry>get the set of storage option name/value pairs</entry>
13445 <entry><literal><function>pg_tablespace_databases(<parameter>tablespace_oid</parameter>)</function></literal></entry>
13446 <entry><type>setof oid</type></entry>
13447 <entry>get the set of database OIDs that have objects in the tablespace</entry>
13450 <entry><literal><function>pg_typeof(<parameter>any</parameter>)</function></literal></entry>
13451 <entry><type>regtype</type></entry>
13452 <entry>get the data type of any value</entry>
13459 <function>format_type</function> returns the SQL name of a data type that
13460 is identified by its type OID and possibly a type modifier. Pass NULL
13461 for the type modifier if no specific modifier is known.
13465 <function>pg_get_keywords</function> returns a set of records describing
13466 the SQL keywords recognized by the server. The <structfield>word</> column
13467 contains the keyword. The <structfield>catcode</> column contains a
13468 category code: <literal>U</> for unreserved, <literal>C</> for column name,
13469 <literal>T</> for type or function name, or <literal>R</> for reserved.
13470 The <structfield>catdesc</> column contains a possibly-localized string
13471 describing the category.
13475 <function>pg_get_constraintdef</function>,
13476 <function>pg_get_indexdef</function>, <function>pg_get_ruledef</function>,
13477 and <function>pg_get_triggerdef</function>, respectively reconstruct the
13478 creating command for a constraint, index, rule, or trigger. (Note that this
13479 is a decompiled reconstruction, not the original text of the command.)
13480 <function>pg_get_expr</function> decompiles the internal form of an
13481 individual expression, such as the default value for a column. It can be
13482 useful when examining the contents of system catalogs. If the expression
13483 might contain Vars, specify the OID of the relation they refer to as the
13484 second parameter; if no Vars are expected, zero is sufficient.
13485 <function>pg_get_viewdef</function> reconstructs the <command>SELECT</>
13486 query that defines a view. Most of these functions come in two variants,
13487 one of which can optionally <quote>pretty-print</> the result. The
13488 pretty-printed format is more readable, but the default format is more
13489 likely to be interpreted the same way by future versions of
13490 <productname>PostgreSQL</>; avoid using pretty-printed output for dump
13491 purposes. Passing <literal>false</> for the pretty-print parameter yields
13492 the same result as the variant that does not have the parameter at all.
13496 <function>pg_get_functiondef</> returns a complete
13497 <command>CREATE OR REPLACE FUNCTION</> statement for a function.
13498 <function>pg_get_function_arguments</function> returns the argument list
13499 of a function, in the form it would need to appear in within
13500 <command>CREATE FUNCTION</>.
13501 <function>pg_get_function_result</function> similarly returns the
13502 appropriate <literal>RETURNS</> clause for the function.
13503 <function>pg_get_function_identity_arguments</function> returns the
13504 argument list necessary to identify a function, in the form it
13505 would need to appear in within <command>ALTER FUNCTION</>, for
13506 instance. This form omits default values.
13510 <function>pg_get_serial_sequence</function> returns the name of the
13511 sequence associated with a column, or NULL if no sequence is associated
13512 with the column. The first input parameter is a table name with
13513 optional schema, and the second parameter is a column name. Because
13514 the first parameter is potentially a schema and table, it is not treated
13515 as a double-quoted identifier, meaning it is lower cased by default,
13516 while the second parameter, being just a column name, is treated as
13517 double-quoted and has its case preserved. The function returns a value
13518 suitably formatted for passing to sequence functions (see <xref
13519 linkend="functions-sequence">). This association can be modified or
13520 removed with <command>ALTER SEQUENCE OWNED BY</>. (The function
13521 probably should have been called
13522 <function>pg_get_owned_sequence</function>; its current name reflects the fact
13523 that it's typically used with <type>serial</> or <type>bigserial</>
13528 <function>pg_get_userbyid</function> extracts a role's name given
13533 <function>pg_options_to_table</function> returns the set of storage
13534 option name/value pairs
13535 (<literal>option_name</>/<literal>option_value</>) when passed
13536 <structname>pg_class</>.<structfield>reloptions</> or
13537 <structname>pg_attribute</>.<structfield>attoptions</>.
13541 <function>pg_tablespace_databases</function> allows a tablespace to be
13542 examined. It returns the set of OIDs of databases that have objects stored
13543 in the tablespace. If this function returns any rows, the tablespace is not
13544 empty and cannot be dropped. To display the specific objects populating the
13545 tablespace, you will need to connect to the databases identified by
13546 <function>pg_tablespace_databases</function> and query their
13547 <structname>pg_class</> catalogs.
13551 <function>pg_describe_object</function> returns a description of a database
13552 object specified by catalog OID, object OID and a (possibly zero) sub-object ID.
13553 This is useful to determine the identity of an object as stored in the
13554 <structname>pg_depend</structname> catalog.
13558 <function>pg_typeof</function> returns the OID of the data type of the
13559 value that is passed to it. This can be helpful for troubleshooting or
13560 dynamically constructing SQL queries. The function is declared as
13561 returning <type>regtype</>, which is an OID alias type (see
13562 <xref linkend="datatype-oid">); this means that it is the same as an
13563 OID for comparison purposes but displays as a type name. For example:
13565 SELECT pg_typeof(33);
13572 SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
13581 <primary>col_description</primary>
13585 <primary>obj_description</primary>
13589 <primary>shobj_description</primary>
13593 <primary>comment</primary>
13594 <secondary sortas="database objects">about database objects</secondary>
13598 The functions shown in <xref linkend="functions-info-comment-table">
13599 extract comments previously stored with the <xref linkend="sql-comment">
13600 command. A null value is returned if no
13601 comment could be found for the specified parameters.
13604 <table id="functions-info-comment-table">
13605 <title>Comment Information Functions</title>
13608 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
13613 <entry><literal><function>col_description(<parameter>table_oid</parameter>, <parameter>column_number</parameter>)</function></literal></entry>
13614 <entry><type>text</type></entry>
13615 <entry>get comment for a table column</entry>
13618 <entry><literal><function>obj_description(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</function></literal></entry>
13619 <entry><type>text</type></entry>
13620 <entry>get comment for a database object</entry>
13623 <entry><literal><function>obj_description(<parameter>object_oid</parameter>)</function></literal></entry>
13624 <entry><type>text</type></entry>
13625 <entry>get comment for a database object (<emphasis>deprecated</emphasis>)</entry>
13628 <entry><literal><function>shobj_description(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</function></literal></entry>
13629 <entry><type>text</type></entry>
13630 <entry>get comment for a shared database object</entry>
13637 <function>col_description</function> returns the comment for a table
13638 column, which is specified by the OID of its table and its column number.
13639 (<function>obj_description</function> cannot be used for table columns
13640 since columns do not have OIDs of their own.)
13644 The two-parameter form of <function>obj_description</function> returns the
13645 comment for a database object specified by its OID and the name of the
13646 containing system catalog. For example,
13647 <literal>obj_description(123456,'pg_class')</literal>
13648 would retrieve the comment for the table with OID 123456.
13649 The one-parameter form of <function>obj_description</function> requires only
13650 the object OID. It is deprecated since there is no guarantee that
13651 OIDs are unique across different system catalogs; therefore, the wrong
13652 comment might be returned.
13656 <function>shobj_description</function> is used just like
13657 <function>obj_description</function> except it is used for retrieving
13658 comments on shared objects. Some system catalogs are global to all
13659 databases within each cluster, and the descriptions for objects in them
13660 are stored globally as well.
13664 <primary>txid_current</primary>
13668 <primary>txid_current_snapshot</primary>
13672 <primary>txid_snapshot_xip</primary>
13676 <primary>txid_snapshot_xmax</primary>
13680 <primary>txid_snapshot_xmin</primary>
13684 <primary>txid_visible_in_snapshot</primary>
13688 The functions shown in <xref linkend="functions-txid-snapshot">
13689 provide server transaction information in an exportable form. The main
13690 use of these functions is to determine which transactions were committed
13691 between two snapshots.
13694 <table id="functions-txid-snapshot">
13695 <title>Transaction IDs and Snapshots</title>
13698 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
13703 <entry><literal><function>txid_current()</function></literal></entry>
13704 <entry><type>bigint</type></entry>
13705 <entry>get current transaction ID</entry>
13708 <entry><literal><function>txid_current_snapshot()</function></literal></entry>
13709 <entry><type>txid_snapshot</type></entry>
13710 <entry>get current snapshot</entry>
13713 <entry><literal><function>txid_snapshot_xip(<parameter>txid_snapshot</parameter>)</function></literal></entry>
13714 <entry><type>setof bigint</type></entry>
13715 <entry>get in-progress transaction IDs in snapshot</entry>
13718 <entry><literal><function>txid_snapshot_xmax(<parameter>txid_snapshot</parameter>)</function></literal></entry>
13719 <entry><type>bigint</type></entry>
13720 <entry>get <literal>xmax</literal> of snapshot</entry>
13723 <entry><literal><function>txid_snapshot_xmin(<parameter>txid_snapshot</parameter>)</function></literal></entry>
13724 <entry><type>bigint</type></entry>
13725 <entry>get <literal>xmin</literal> of snapshot</entry>
13728 <entry><literal><function>txid_visible_in_snapshot(<parameter>bigint</parameter>, <parameter>txid_snapshot</parameter>)</function></literal></entry>
13729 <entry><type>boolean</type></entry>
13730 <entry>is transaction ID visible in snapshot? (do not use with subtransaction ids)</entry>
13737 The internal transaction ID type (<type>xid</>) is 32 bits wide and
13738 wraps around every 4 billion transactions. However, these functions
13739 export a 64-bit format that is extended with an <quote>epoch</> counter
13740 so it will not wrap around during the life of an installation.
13741 The data type used by these functions, <type>txid_snapshot</type>,
13742 stores information about transaction ID
13743 visibility at a particular moment in time. Its components are
13744 described in <xref linkend="functions-txid-snapshot-parts">.
13747 <table id="functions-txid-snapshot-parts">
13748 <title>Snapshot Components</title>
13752 <entry>Name</entry>
13753 <entry>Description</entry>
13760 <entry><type>xmin</type></entry>
13762 Earliest transaction ID (txid) that is still active. All earlier
13763 transactions will either be committed and visible, or rolled
13769 <entry><type>xmax</type></entry>
13771 First as-yet-unassigned txid. All txids greater than or equal to this
13772 are not yet started as of the time of the snapshot, and thus invisible.
13777 <entry><type>xip_list</type></entry>
13779 Active txids at the time of the snapshot. The list
13780 includes only those active txids between <literal>xmin</>
13781 and <literal>xmax</>; there might be active txids higher
13782 than <literal>xmax</>. A txid that is <literal>xmin <= txid <
13783 xmax</literal> and not in this list was already completed
13784 at the time of the snapshot, and thus either visible or
13785 dead according to its commit status. The list does not
13786 include txids of subtransactions.
13795 <type>txid_snapshot</>'s textual representation is
13796 <literal><replaceable>xmin</>:<replaceable>xmax</>:<replaceable>xip_list</></literal>.
13797 For example <literal>10:20:10,14,15</literal> means
13798 <literal>xmin=10, xmax=20, xip_list=10, 14, 15</literal>.
13802 <sect1 id="functions-admin">
13803 <title>System Administration Functions</title>
13806 <xref linkend="functions-admin-set-table"> shows the functions
13807 available to query and alter run-time configuration parameters.
13810 <table id="functions-admin-set-table">
13811 <title>Configuration Settings Functions</title>
13814 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
13821 <primary>current_setting</primary>
13823 <literal><function>current_setting(<parameter>setting_name</parameter>)</function></literal>
13825 <entry><type>text</type></entry>
13826 <entry>get current value of setting</entry>
13831 <primary>set_config</primary>
13833 <literal><function>set_config(<parameter>setting_name</parameter>,
13834 <parameter>new_value</parameter>,
13835 <parameter>is_local</parameter>)</function></literal>
13837 <entry><type>text</type></entry>
13838 <entry>set parameter and return new value</entry>
13845 <primary>SET</primary>
13849 <primary>SHOW</primary>
13853 <primary>configuration</primary>
13854 <secondary sortas="server">of the server</secondary>
13855 <tertiary>functions</tertiary>
13859 The function <function>current_setting</function> yields the
13860 current value of the setting <parameter>setting_name</parameter>.
13861 It corresponds to the <acronym>SQL</acronym> command
13862 <command>SHOW</command>. An example:
13864 SELECT current_setting('datestyle');
13874 <function>set_config</function> sets the parameter
13875 <parameter>setting_name</parameter> to
13876 <parameter>new_value</parameter>. If
13877 <parameter>is_local</parameter> is <literal>true</literal>, the
13878 new value will only apply to the current transaction. If you want
13879 the new value to apply for the current session, use
13880 <literal>false</literal> instead. The function corresponds to the
13881 SQL command <command>SET</command>. An example:
13883 SELECT set_config('log_statement_stats', 'off', false);
13893 <primary>pg_cancel_backend</primary>
13896 <primary>pg_reload_conf</primary>
13899 <primary>pg_rotate_logfile</primary>
13902 <primary>pg_terminate_backend</primary>
13906 <primary>signal</primary>
13907 <secondary sortas="backend">backend processes</secondary>
13911 The functions shown in <xref
13912 linkend="functions-admin-signal-table"> send control signals to
13913 other server processes. Use of these functions is restricted
13917 <table id="functions-admin-signal-table">
13918 <title>Server Signalling Functions</title>
13921 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
13928 <literal><function>pg_cancel_backend(<parameter>pid</parameter> <type>int</>)</function></literal>
13930 <entry><type>boolean</type></entry>
13931 <entry>Cancel a backend's current query</entry>
13935 <literal><function>pg_reload_conf()</function></literal>
13937 <entry><type>boolean</type></entry>
13938 <entry>Cause server processes to reload their configuration files</entry>
13942 <literal><function>pg_rotate_logfile()</function></literal>
13944 <entry><type>boolean</type></entry>
13945 <entry>Rotate server's log file</entry>
13949 <literal><function>pg_terminate_backend(<parameter>pid</parameter> <type>int</>)</function></literal>
13951 <entry><type>boolean</type></entry>
13952 <entry>Terminate a backend</entry>
13959 Each of these functions returns <literal>true</literal> if
13960 successful and <literal>false</literal> otherwise.
13964 <function>pg_cancel_backend</> and <function>pg_terminate_backend</>
13965 send signals (<systemitem>SIGINT</> or <systemitem>SIGTERM</>
13966 respectively) to backend processes identified by process ID.
13967 The process ID of an active backend can be found from
13968 the <structfield>procpid</structfield> column of the
13969 <structname>pg_stat_activity</structname> view, or by listing the
13970 <command>postgres</command> processes on the server (using
13971 <application>ps</> on Unix or the <application>Task
13972 Manager</> on <productname>Windows</>).
13976 <function>pg_reload_conf</> sends a <systemitem>SIGHUP</> signal
13977 to the server, causing configuration files
13978 to be reloaded by all server processes.
13982 <function>pg_rotate_logfile</> signals the log-file manager to switch
13983 to a new output file immediately. This works only when the built-in
13984 log collector is running, since otherwise there is no log-file manager
13989 <primary>backup</primary>
13992 <primary>pg_create_restore_point</primary>
13995 <primary>pg_current_xlog_insert_location</primary>
13998 <primary>pg_current_xlog_location</primary>
14001 <primary>pg_start_backup</primary>
14004 <primary>pg_stop_backup</primary>
14007 <primary>pg_switch_xlog</primary>
14010 <primary>pg_xlogfile_name</primary>
14013 <primary>pg_xlogfile_name_offset</primary>
14017 The functions shown in <xref
14018 linkend="functions-admin-backup-table"> assist in making on-line backups.
14019 These functions cannot be executed during recovery.
14022 <table id="functions-admin-backup-table">
14023 <title>Backup Control Functions</title>
14026 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14033 <literal><function>pg_create_restore_point(<parameter>name</> <type>text</>)</function></literal>
14035 <entry><type>text</type></entry>
14036 <entry>Create a named point for performing restore (restricted to superusers)</entry>
14040 <literal><function>pg_current_xlog_insert_location()</function></literal>
14042 <entry><type>text</type></entry>
14043 <entry>Get current transaction log insert location</entry>
14047 <literal><function>pg_current_xlog_location()</function></literal>
14049 <entry><type>text</type></entry>
14050 <entry>Get current transaction log write location</entry>
14054 <literal><function>pg_start_backup(<parameter>label</> <type>text</> <optional>, <parameter>fast</> <type>boolean</> </optional>)</function></literal>
14056 <entry><type>text</type></entry>
14057 <entry>Prepare for performing on-line backup (restricted to superusers or replication roles)</entry>
14061 <literal><function>pg_stop_backup()</function></literal>
14063 <entry><type>text</type></entry>
14064 <entry>Finish performing on-line backup (restricted to superusers or replication roles)</entry>
14068 <literal><function>pg_switch_xlog()</function></literal>
14070 <entry><type>text</type></entry>
14071 <entry>Force switch to a new transaction log file (restricted to superusers)</entry>
14075 <literal><function>pg_xlogfile_name(<parameter>location</> <type>text</>)</function></literal>
14077 <entry><type>text</type></entry>
14078 <entry>Convert transaction log location string to file name</entry>
14082 <literal><function>pg_xlogfile_name_offset(<parameter>location</> <type>text</>)</function></literal>
14084 <entry><type>text</>, <type>integer</></entry>
14085 <entry>Convert transaction log location string to file name and decimal byte offset within file</entry>
14092 <function>pg_start_backup</> accepts an
14093 arbitrary user-defined label for the backup. (Typically this would be
14094 the name under which the backup dump file will be stored.) The function
14095 writes a backup label file (<filename>backup_label</>) into the
14096 database cluster's data directory, performs a checkpoint,
14097 and then returns the backup's starting transaction log location as text.
14098 The user can ignore this result value, but it is
14099 provided in case it is useful.
14101 postgres=# select pg_start_backup('label_goes_here');
14107 There is an optional second parameter of type <type>boolean</type>. If <literal>true</>,
14108 it specifies executing <function>pg_start_backup</> as quickly as
14109 possible. This forces an immediate checkpoint which will cause a
14110 spike in I/O operations, slowing any concurrently executing queries.
14114 <function>pg_stop_backup</> removes the label file created by
14115 <function>pg_start_backup</>, and creates a backup history file in
14116 the transaction log archive area. The history file includes the label given to
14117 <function>pg_start_backup</>, the starting and ending transaction log locations for
14118 the backup, and the starting and ending times of the backup. The return
14119 value is the backup's ending transaction log location (which again
14120 can be ignored). After recording the ending location, the current
14121 transaction log insertion
14122 point is automatically advanced to the next transaction log file, so that the
14123 ending transaction log file can be archived immediately to complete the backup.
14127 <function>pg_switch_xlog</> moves to the next transaction log file, allowing the
14128 current file to be archived (assuming you are using continuous archiving).
14129 The return value is the ending transaction log location + 1 within the just-completed transaction log file.
14130 If there has been no transaction log activity since the last transaction log switch,
14131 <function>pg_switch_xlog</> does nothing and returns the start location
14132 of the transaction log file currently in use.
14136 <function>pg_create_restore_point</> creates a named transaction log
14137 record that can be used as recovery target, and returns the corresponding
14138 transaction log location. The given name can then be used with
14139 <xref linkend="recovery-target-name"> to specify the point up to which
14140 recovery will proceed. Avoid creating multiple restore points with the
14141 same name, since recovery will stop at the first one whose name matches
14142 the recovery target.
14146 <function>pg_current_xlog_location</> displays the current transaction log write
14147 location in the same format used by the above functions. Similarly,
14148 <function>pg_current_xlog_insert_location</> displays the current transaction log
14149 insertion point. The insertion point is the <quote>logical</> end
14150 of the transaction log
14151 at any instant, while the write location is the end of what has actually
14152 been written out from the server's internal buffers. The write location
14153 is the end of what can be examined from outside the server, and is usually
14154 what you want if you are interested in archiving partially-complete transaction log
14155 files. The insertion point is made available primarily for server
14156 debugging purposes. These are both read-only operations and do not
14157 require superuser permissions.
14161 You can use <function>pg_xlogfile_name_offset</> to extract the
14162 corresponding transaction log file name and byte offset from the results of any of the
14163 above functions. For example:
14165 postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
14166 file_name | file_offset
14167 --------------------------+-------------
14168 00000001000000000000000D | 4039624
14171 Similarly, <function>pg_xlogfile_name</> extracts just the transaction log file name.
14172 When the given transaction log location is exactly at a transaction log file boundary, both
14173 these functions return the name of the preceding transaction log file.
14174 This is usually the desired behavior for managing transaction log archiving
14175 behavior, since the preceding file is the last one that currently
14176 needs to be archived.
14180 For details about proper usage of these functions, see
14181 <xref linkend="continuous-archiving">.
14185 <primary>pg_is_in_recovery</primary>
14188 <primary>pg_last_xlog_receive_location</primary>
14191 <primary>pg_last_xlog_replay_location</primary>
14194 <primary>pg_last_xact_replay_timestamp</primary>
14198 The functions shown in <xref
14199 linkend="functions-recovery-info-table"> provide information
14200 about the current status of the standby.
14201 These functions may be executed during both recovery and in normal running.
14204 <table id="functions-recovery-info-table">
14205 <title>Recovery Information Functions</title>
14208 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14215 <literal><function>pg_is_in_recovery()</function></literal>
14217 <entry><type>bool</type></entry>
14218 <entry>True if recovery is still in progress.
14223 <literal><function>pg_last_xlog_receive_location()</function></literal>
14225 <entry><type>text</type></entry>
14226 <entry>Get last transaction log location received and synced to disk by
14227 streaming replication. While streaming replication is in progress
14228 this will increase monotonically. If recovery has completed this will
14230 the value of the last WAL record received and synced to disk during
14231 recovery. If streaming replication is disabled, or if it has not yet
14232 started, the function returns NULL.
14237 <literal><function>pg_last_xlog_replay_location()</function></literal>
14239 <entry><type>text</type></entry>
14240 <entry>Get last transaction log location replayed during recovery.
14241 If recovery is still in progress this will increase monotonically.
14242 If recovery has completed then this value will remain static at
14243 the value of the last WAL record applied during that recovery.
14244 When the server has been started normally without recovery
14245 the function returns NULL.
14250 <literal><function>pg_last_xact_replay_timestamp()</function></literal>
14252 <entry><type>timestamp with time zone</type></entry>
14253 <entry>Get time stamp of last transaction replayed during recovery.
14254 This is the time at which the commit or abort WAL record for that
14255 transaction was generated on the primary.
14256 If no transactions have been replayed during recovery, this function
14257 returns NULL. Otherwise, if recovery is still in progress this will
14258 increase monotonically. If recovery has completed then this value will
14259 remain static at the value of the last transaction applied during that
14260 recovery. When the server has been started normally without recovery
14261 the function returns NULL.
14269 <primary>pg_is_xlog_replay_paused</primary>
14272 <primary>pg_xlog_replay_pause</primary>
14275 <primary>pg_xlog_replay_resume</primary>
14279 The functions shown in <xref
14280 linkend="functions-recovery-control-table"> control the progress of recovery.
14281 These functions may be executed only during recovery.
14284 <table id="functions-recovery-control-table">
14285 <title>Recovery Control Functions</title>
14288 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14295 <literal><function>pg_is_xlog_replay_paused()</function></literal>
14297 <entry><type>bool</type></entry>
14298 <entry>True if recovery is paused.
14303 <literal><function>pg_xlog_replay_pause()</function></literal>
14305 <entry><type>void</type></entry>
14306 <entry>Pauses recovery immediately.
14311 <literal><function>pg_xlog_replay_resume()</function></literal>
14313 <entry><type>void</type></entry>
14314 <entry>Restarts recovery if it was paused.
14322 While recovery is paused no further database changes are applied.
14323 If in hot standby, all new queries will see the same consistent snapshot
14324 of the database, and no further query conflicts will be generated until
14325 recovery is resumed.
14329 If streaming replication is disabled, the paused state may continue
14330 indefinitely without problem. While streaming replication is in
14331 progress WAL records will continue to be received, which will
14332 eventually fill available disk space, depending upon the duration of
14333 the pause, the rate of WAL generation and available disk space.
14337 The functions shown in <xref linkend="functions-admin-dbsize"> calculate
14338 the disk space usage of database objects.
14342 <primary>pg_column_size</primary>
14345 <primary>pg_database_size</primary>
14348 <primary>pg_indexes_size</primary>
14351 <primary>pg_relation_size</primary>
14354 <primary>pg_size_pretty</primary>
14357 <primary>pg_table_size</primary>
14360 <primary>pg_tablespace_size</primary>
14363 <primary>pg_total_relation_size</primary>
14366 <table id="functions-admin-dbsize">
14367 <title>Database Object Size Functions</title>
14370 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14376 <entry><literal><function>pg_column_size(<type>any</type>)</function></literal></entry>
14377 <entry><type>int</type></entry>
14378 <entry>Number of bytes used to store a particular value (possibly compressed)</entry>
14382 <literal><function>pg_database_size(<type>oid</type>)</function></literal>
14384 <entry><type>bigint</type></entry>
14385 <entry>Disk space used by the database with the specified OID</entry>
14389 <literal><function>pg_database_size(<type>name</type>)</function></literal>
14391 <entry><type>bigint</type></entry>
14392 <entry>Disk space used by the database with the specified name</entry>
14396 <literal><function>pg_indexes_size(<type>regclass</type>)</function></literal>
14398 <entry><type>bigint</type></entry>
14400 Total disk space used by indexes attached to the specified table
14405 <literal><function>pg_relation_size(<parameter>relation</parameter> <type>regclass</type>, <parameter>fork</parameter> <type>text</type>)</function></literal>
14407 <entry><type>bigint</type></entry>
14409 Disk space used by the specified fork (<literal>'main'</literal>,
14410 <literal>'fsm'</literal> or <literal>'vm'</>)
14411 of the specified table or index
14416 <literal><function>pg_relation_size(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
14418 <entry><type>bigint</type></entry>
14420 Shorthand for <literal>pg_relation_size(..., 'main')</literal>
14425 <literal><function>pg_size_pretty(<type>bigint</type>)</function></literal>
14427 <entry><type>text</type></entry>
14428 <entry>Converts a size in bytes into a human-readable format with size units</entry>
14432 <literal><function>pg_table_size(<type>regclass</type>)</function></literal>
14434 <entry><type>bigint</type></entry>
14436 Disk space used by the specified table, excluding indexes
14437 (but including TOAST, free space map, and visibility map)
14442 <literal><function>pg_tablespace_size(<type>oid</type>)</function></literal>
14444 <entry><type>bigint</type></entry>
14445 <entry>Disk space used by the tablespace with the specified OID</entry>
14449 <literal><function>pg_tablespace_size(<type>name</type>)</function></literal>
14451 <entry><type>bigint</type></entry>
14452 <entry>Disk space used by the tablespace with the specified name</entry>
14456 <literal><function>pg_total_relation_size(<type>regclass</type>)</function></literal>
14458 <entry><type>bigint</type></entry>
14460 Total disk space used by the specified table,
14461 including all indexes and <acronym>TOAST</> data
14469 <function>pg_column_size</> shows the space used to store any individual
14474 <function>pg_total_relation_size</> accepts the OID or name of a
14475 table or toast table, and returns the total on-disk space used for
14476 that table, including all associated indexes. This function is
14477 equivalent to <function>pg_table_size</function>
14478 <literal>+</> <function>pg_indexes_size</function>.
14482 <function>pg_table_size</> accepts the OID or name of a table and
14483 returns the disk space needed for that table, exclusive of indexes.
14484 (TOAST space, free space map, and visibility map are included.)
14488 <function>pg_indexes_size</> accepts the OID or name of a table and
14489 returns the total disk space used by all the indexes attached to that
14494 <function>pg_database_size</function> and <function>pg_tablespace_size</>
14495 accept the OID or name of a database or tablespace, and return the total
14496 disk space used therein.
14500 <function>pg_relation_size</> accepts the OID or name of a table, index or
14501 toast table, and returns the on-disk size in bytes. Specifying
14502 <literal>'main'</literal> or leaving out the second argument returns the
14503 size of the main data fork of the relation. Specifying
14504 <literal>'fsm'</literal> returns the size of the
14505 Free Space Map (see <xref linkend="storage-fsm">) associated with the
14506 relation. Specifying <literal>'vm'</literal> returns the size of the
14507 Visibility Map (see <xref linkend="storage-vm">) associated with the
14508 relation. Note that this function shows the size of only one fork;
14509 for most purposes it is more convenient to use the higher-level
14510 functions <function>pg_total_relation_size</> or
14511 <function>pg_table_size</>.
14515 <function>pg_size_pretty</> can be used to format the result of one of
14516 the other functions in a human-readable way, using kB, MB, GB or TB as
14521 The functions above that operate on tables or indexes accept a
14522 <type>regclass</> argument, which is simply the OID of the table or index
14523 in the <structname>pg_class</> system catalog. You do not have to look up
14524 the OID by hand, however, since the <type>regclass</> data type's input
14525 converter will do the work for you. Just write the table name enclosed in
14526 single quotes so that it looks like a literal constant. For compatibility
14527 with the handling of ordinary <acronym>SQL</acronym> names, the string
14528 will be converted to lower case unless it contains double quotes around
14533 The functions shown in <xref linkend="functions-admin-dblocation"> assist
14534 in identifying the specific disk files associated with database objects.
14538 <primary>pg_relation_filenode</primary>
14541 <primary>pg_relation_filepath</primary>
14544 <table id="functions-admin-dblocation">
14545 <title>Database Object Location Functions</title>
14548 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14555 <literal><function>pg_relation_filenode(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
14557 <entry><type>oid</type></entry>
14559 Filenode number of the specified relation
14564 <literal><function>pg_relation_filepath(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
14566 <entry><type>text</type></entry>
14568 File path name of the specified relation
14576 <function>pg_relation_filenode</> accepts the OID or name of a table,
14577 index, sequence, or toast table, and returns the <quote>filenode</> number
14578 currently assigned to it. The filenode is the base component of the file
14579 name(s) used for the relation (see <xref linkend="storage-file-layout">
14580 for more information). For most tables the result is the same as
14581 <structname>pg_class</>.<structfield>relfilenode</>, but for certain
14582 system catalogs <structfield>relfilenode</> is zero and this function must
14583 be used to get the correct value. The function returns NULL if passed
14584 a relation that does not have storage, such as a view.
14588 <function>pg_relation_filepath</> is similar to
14589 <function>pg_relation_filenode</>, but it returns the entire file path name
14590 (relative to the database cluster's data directory <varname>PGDATA</>) of
14595 The functions shown in <xref
14596 linkend="functions-admin-genfile"> provide native access to
14597 files on the machine hosting the server. Only files within the
14598 database cluster directory and the <varname>log_directory</> can be
14599 accessed. Use a relative path for files in the cluster directory,
14600 and a path matching the <varname>log_directory</> configuration setting
14601 for log files. Use of these functions is restricted to superusers.
14604 <table id="functions-admin-genfile">
14605 <title>Generic File Access Functions</title>
14608 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14615 <literal><function>pg_ls_dir(<parameter>dirname</> <type>text</>)</function></literal>
14617 <entry><type>setof text</type></entry>
14618 <entry>List the contents of a directory</entry>
14622 <literal><function>pg_read_file(<parameter>filename</> <type>text</> [, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>])</function></literal>
14624 <entry><type>text</type></entry>
14625 <entry>Return the contents of a text file</entry>
14629 <literal><function>pg_read_binary_file(<parameter>filename</> <type>text</> [, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>])</function></literal>
14631 <entry><type>bytea</type></entry>
14632 <entry>Return the contents of a file</entry>
14636 <literal><function>pg_stat_file(<parameter>filename</> <type>text</>)</function></literal>
14638 <entry><type>record</type></entry>
14639 <entry>Return information about a file</entry>
14646 <primary>pg_ls_dir</primary>
14649 <function>pg_ls_dir</> returns all the names in the specified
14650 directory, except the special entries <quote><literal>.</></> and
14651 <quote><literal>..</></>.
14655 <primary>pg_read_file</primary>
14658 <function>pg_read_file</> returns part of a text file, starting
14659 at the given <parameter>offset</>, returning at most <parameter>length</>
14660 bytes (less if the end of file is reached first). If <parameter>offset</>
14661 is negative, it is relative to the end of the file.
14662 If <parameter>offset</> and <parameter>length</> are omitted, the entire
14663 file is returned. The bytes read from the file are interpreted as a string
14664 in the server encoding; an error is thrown if they are not valid in that
14669 <primary>pg_read_binary_file</primary>
14672 <function>pg_read_binary_file</> is similar to
14673 <function>pg_read_file</>, except that the result is a <type>bytea</type> value;
14674 accordingly, no encoding checks are performed.
14675 In combination with the <function>convert_from</> function, this function
14676 can be used to read a file in a specified encoding:
14678 SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
14683 <primary>pg_stat_file</primary>
14686 <function>pg_stat_file</> returns a record containing the file
14687 size, last accessed time stamp, last modified time stamp,
14688 last file status change time stamp (Unix platforms only),
14689 file creation time stamp (Windows only), and a <type>boolean</type>
14690 indicating if it is a directory. Typical usages include:
14692 SELECT * FROM pg_stat_file('filename');
14693 SELECT (pg_stat_file('filename')).modification;
14698 The functions shown in <xref linkend="functions-advisory-locks"> manage
14699 advisory locks. For details about proper use of these functions, see
14700 <xref linkend="advisory-locks">.
14703 <table id="functions-advisory-locks">
14704 <title>Advisory Lock Functions</title>
14707 <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
14714 <literal><function>pg_advisory_lock(<parameter>key</> <type>bigint</>)</function></literal>
14716 <entry><type>void</type></entry>
14717 <entry>Obtain exclusive session level advisory lock</entry>
14721 <literal><function>pg_advisory_lock(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14723 <entry><type>void</type></entry>
14724 <entry>Obtain exclusive session level advisory lock</entry>
14728 <literal><function>pg_advisory_lock_shared(<parameter>key</> <type>bigint</>)</function></literal>
14730 <entry><type>void</type></entry>
14731 <entry>Obtain shared session level advisory lock</entry>
14735 <literal><function>pg_advisory_lock_shared(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14737 <entry><type>void</type></entry>
14738 <entry>Obtain shared session level advisory lock</entry>
14742 <literal><function>pg_advisory_unlock(<parameter>key</> <type>bigint</>)</function></literal>
14744 <entry><type>boolean</type></entry>
14745 <entry>Release an exclusive session level advisory lock</entry>
14749 <literal><function>pg_advisory_unlock(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14751 <entry><type>boolean</type></entry>
14752 <entry>Release an exclusive session level advisory lock</entry>
14756 <literal><function>pg_advisory_unlock_all()</function></literal>
14758 <entry><type>void</type></entry>
14759 <entry>Release all session level advisory locks held by the current session</entry>
14763 <literal><function>pg_advisory_unlock_shared(<parameter>key</> <type>bigint</>)</function></literal>
14765 <entry><type>boolean</type></entry>
14766 <entry>Release a shared session level advisory lock</entry>
14770 <literal><function>pg_advisory_unlock_shared(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14772 <entry><type>boolean</type></entry>
14773 <entry>Release a shared session level advisory lock</entry>
14777 <literal><function>pg_advisory_xact_lock(<parameter>key</> <type>bigint</>)</function></literal>
14779 <entry><type>void</type></entry>
14780 <entry>Obtain exclusive transaction level advisory lock</entry>
14784 <literal><function>pg_advisory_xact_lock(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14786 <entry><type>void</type></entry>
14787 <entry>Obtain exclusive transaction level advisory lock</entry>
14791 <literal><function>pg_advisory_xact_lock_shared(<parameter>key</> <type>bigint</>)</function></literal>
14793 <entry><type>void</type></entry>
14794 <entry>Obtain shared transaction level advisory lock</entry>
14798 <literal><function>pg_advisory_xact_lock_shared(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14800 <entry><type>void</type></entry>
14801 <entry>Obtain shared advisory lock for the current transaction</entry>
14805 <literal><function>pg_try_advisory_lock(<parameter>key</> <type>bigint</>)</function></literal>
14807 <entry><type>boolean</type></entry>
14808 <entry>Obtain exclusive session level advisory lock if available</entry>
14812 <literal><function>pg_try_advisory_lock(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14814 <entry><type>boolean</type></entry>
14815 <entry>Obtain exclusive session level advisory lock if available</entry>
14819 <literal><function>pg_try_advisory_lock_shared(<parameter>key</> <type>bigint</>)</function></literal>
14821 <entry><type>boolean</type></entry>
14822 <entry>Obtain shared session level advisory lock if available</entry>
14826 <literal><function>pg_try_advisory_lock_shared(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14828 <entry><type>boolean</type></entry>
14829 <entry>Obtain shared session level advisory lock if available</entry>
14833 <literal><function>pg_try_advisory_xact_lock(<parameter>key</> <type>bigint</>)</function></literal>
14835 <entry><type>boolean</type></entry>
14836 <entry>Obtain exclusive transaction level advisory lock if available</entry>
14840 <literal><function>pg_try_advisory_xact_lock(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14842 <entry><type>boolean</type></entry>
14843 <entry>Obtain exclusive transaction level advisory lock if available</entry>
14847 <literal><function>pg_try_advisory_xact_lock_shared(<parameter>key</> <type>bigint</>)</function></literal>
14849 <entry><type>boolean</type></entry>
14850 <entry>Obtain shared transaction level advisory lock if available</entry>
14854 <literal><function>pg_try_advisory_xact_lock_shared(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</function></literal>
14856 <entry><type>boolean</type></entry>
14857 <entry>Obtain shared transaction level advisory lock if available</entry>
14864 <primary>pg_advisory_lock</primary>
14867 <function>pg_advisory_lock</> locks an application-defined resource,
14868 which can be identified either by a single 64-bit key value or two
14869 32-bit key values (note that these two key spaces do not overlap).
14870 The key type is specified in <literal>pg_locks.objid</>. If
14871 another session already holds a lock on the same resource, the
14872 function will wait until the resource becomes available. The lock
14873 is exclusive. Multiple lock requests stack, so that if the same resource
14874 is locked three times it must be also unlocked three times to be
14875 released for other sessions' use.
14879 <primary>pg_advisory_lock_shared</primary>
14882 <function>pg_advisory_lock_shared</> works the same as
14883 <function>pg_advisory_lock</>,
14884 except the lock can be shared with other sessions requesting shared locks.
14885 Only would-be exclusive lockers are locked out.
14889 <primary>pg_try_advisory_lock</primary>
14892 <function>pg_try_advisory_lock</> is similar to
14893 <function>pg_advisory_lock</>, except the function will not wait for the
14894 lock to become available. It will either obtain the lock immediately and
14895 return <literal>true</>, or return <literal>false</> if the lock cannot be
14896 acquired immediately.
14900 <primary>pg_try_advisory_lock_shared</primary>
14903 <function>pg_try_advisory_lock_shared</> works the same as
14904 <function>pg_try_advisory_lock</>, except it attempts to acquire
14905 a shared rather than an exclusive lock.
14909 <primary>pg_advisory_xact_lock</primary>
14912 <function>pg_advisory_xact_lock</> works the same as
14913 <function>pg_advisory_lock</>, expect the lock is automatically released
14914 at the end of the current transaction and can not be released explicitly.
14918 <primary>pg_advisory_xact_lock_shared</primary>
14921 <function>pg_advisory_xact_lock_shared</> works the same as
14922 <function>pg_advisory_lock_shared</>, expect the lock is automatically released
14923 at the end of the current transaction and can not be released explicitly.
14927 <primary>pg_try_advisory_xact_lock</primary>
14930 <function>pg_try_advisory_xact_lock</> works the same as
14931 <function>pg_try_advisory_lock</>, expect the lock, if acquired,
14932 is automatically released at the end of the current transaction and
14933 can not be released explicitly.
14937 <primary>pg_try_advisory_xact_lock_shared</primary>
14940 <function>pg_try_advisory_xact_lock_shared</> works the same as
14941 <function>pg_try_advisory_lock_shared</>, expect the lock, if acquired,
14942 is automatically released at the end of the current transaction and
14943 can not be released explicitly.
14947 <primary>pg_advisory_unlock</primary>
14950 <function>pg_advisory_unlock</> will release a previously-acquired
14951 exclusive session level advisory lock. It
14952 returns <literal>true</> if the lock is successfully released.
14953 If the lock was not held, it will return <literal>false</>,
14954 and in addition, an SQL warning will be raised by the server.
14958 <primary>pg_advisory_unlock_shared</primary>
14961 <function>pg_advisory_unlock_shared</> works the same as
14962 <function>pg_advisory_unlock</>,
14963 except it releases a shared session level advisory lock.
14967 <primary>pg_advisory_unlock_all</primary>
14970 <function>pg_advisory_unlock_all</> will release all session level advisory
14971 locks held by the current session. (This function is implicitly invoked
14972 at session end, even if the client disconnects ungracefully.)
14977 <sect1 id="functions-trigger">
14978 <title>Trigger Functions</title>
14981 <primary>suppress_redundant_updates_trigger</primary>
14985 Currently <productname>PostgreSQL</> provides one built in trigger
14986 function, <function>suppress_redundant_updates_trigger</>,
14987 which will prevent any update
14988 that does not actually change the data in the row from taking place, in
14989 contrast to the normal behavior which always performs the update
14990 regardless of whether or not the data has changed. (This normal behavior
14991 makes updates run faster, since no checking is required, and is also
14992 useful in certain cases.)
14996 Ideally, you should normally avoid running updates that don't actually
14997 change the data in the record. Redundant updates can cost considerable
14998 unnecessary time, especially if there are lots of indexes to alter,
14999 and space in dead rows that will eventually have to be vacuumed.
15000 However, detecting such situations in client code is not
15001 always easy, or even possible, and writing expressions to detect
15002 them can be error-prone. An alternative is to use
15003 <function>suppress_redundant_updates_trigger</>, which will skip
15004 updates that don't change the data. You should use this with care,
15005 however. The trigger takes a small but non-trivial time for each record,
15006 so if most of the records affected by an update are actually changed,
15007 use of this trigger will actually make the update run slower.
15011 The <function>suppress_redundant_updates_trigger</> function can be
15012 added to a table like this:
15014 CREATE TRIGGER z_min_update
15015 BEFORE UPDATE ON tablename
15016 FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
15018 In most cases, you would want to fire this trigger last for each row.
15019 Bearing in mind that triggers fire in name order, you would then
15020 choose a trigger name that comes after the name of any other trigger
15021 you might have on the table.
15024 For more information about creating triggers, see
15025 <xref linkend="SQL-CREATETRIGGER">.