| Quellcodebibliothek Statistik Leitseite products/Sources/formale Sprachen/C/Postgres/doc/src/sgml/ (Postgres Database Version 18.4©) Datei vom 11.4.2026 mit Größe 1 MB |
|
SSL func.sgml Sprache: unbekannt |
|
|
Spracherkennung für: .sgml vermutete Sprache: Unknown {[0] [0] [0]} [Methode: Schwerpunktbildung, einfache Gewichte, sechs Dimensionen] <!-- doc/src/sgml/func.sgml -->
<chapter id="functions"> <title>Functions and Operators</title> <indexterm zone="functions"> <primary>function</primary> </indexterm> <indexterm zone="functions"> <primary>operator</primary> </indexterm> <para> <productname>PostgreSQL</productname> provides a large number of functions and operators for the built-in data types. This chapter describes most of them, although additional special-purpose functions appear in relevant sections of the manual. Users can also define their own functions and operators, as described in <xref linkend="server-programming"/>. The <application>psql</application> commands <command>\df</command> and <command>\do</command> can be used to list all available functions and operators, respectively. </para> <para> The notation used throughout this chapter to describe the argument and result data types of a function or operator is like this: <synopsis> <function>repeat</function> ( <type>text</type>, <type>integer</type> ) <returnvalue>text</returnval </synopsis> which says that the function <function>repeat</function> takes one text and one integer argument and returns a result of type text. The right arrow is also used to indicate the result of an example, thus: <programlisting> repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> </programlisting> </para> <para> If you are concerned about portability then note that most of the functions and operators described in this chapter, with the exception of the most trivial arithmetic and comparison operators and some explicitly marked functions, are not specified by the <acronym>SQL</acronym> standard. Some of this extended functionality is present in other <acronym>SQL</acronym> database management systems, and in many cases this functionality is compatible and consistent between the various implementations. </para> <sect1 id="functions-logical"> <title>Logical Operators</title> <indexterm zone="functions-logical"> <primary>operator</primary> <secondary>logical</secondary> </indexterm> <indexterm> <primary>Boolean</primary> <secondary>operators</secondary> <see>operators, logical</see> </indexterm> <para> The usual logical operators are available: <indexterm> <primary>AND (operator)</primary> </indexterm> <indexterm> <primary>OR (operator)</primary> </indexterm> <indexterm> <primary>NOT (operator)</primary> </indexterm> <indexterm> <primary>conjunction</primary> </indexterm> <indexterm> <primary>disjunction</primary> </indexterm> <indexterm> <primary>negation</primary> </indexterm> <synopsis> <type>boolean</type> <literal>AND</literal> <type>boolean</type> <returnvalue>boolean</returnvalue> <type>boolean</type> <literal>OR</literal> <type>boolean</type> <returnvalue>boolean</returnvalue> <literal>NOT</literal> <type>boolean</type> <returnvalue>boolean</returnvalue> </synopsis> <acronym>SQL</acronym> uses a three-valued logic system with true, false, and <literal>null</literal>, which represents <quote>unknown</quote>. Observe the following truth tables: <informaltable> <tgroup cols="4"> <thead> <row> <entry><replaceable>a</replaceable></entry> <entry><replaceable>b</replaceable></entry> <entry><replaceable>a</replaceable> AND <replaceable>b</replaceable></entry> <entry><replaceable>a</replaceable> OR <replaceable>b</replaceable></entry> </row> </thead> <tbody> <row> <entry>TRUE</entry> <entry>TRUE</entry> <entry>TRUE</entry> <entry>TRUE</entry> </row> <row> <entry>TRUE</entry> <entry>FALSE</entry> <entry>FALSE</entry> <entry>TRUE</entry> </row> <row> <entry>TRUE</entry> <entry>NULL</entry> <entry>NULL</entry> <entry>TRUE</entry> </row> <row> <entry>FALSE</entry> <entry>FALSE</entry> <entry>FALSE</entry> <entry>FALSE</entry> </row> <row> <entry>FALSE</entry> <entry>NULL</entry> <entry>FALSE</entry> <entry>NULL</entry> </row> <row> <entry>NULL</entry> <entry>NULL</entry> <entry>NULL</entry> <entry>NULL</entry> </row> </tbody> </tgroup> </informaltable> <informaltable> <tgroup cols="2"> <thead> <row> <entry><replaceable>a</replaceable></entry> <entry>NOT <replaceable>a</replaceable></entry> </row> </thead> <tbody> <row> <entry>TRUE</entry> <entry>FALSE</entry> </row> <row> <entry>FALSE</entry> <entry>TRUE</entry> </row> <row> <entry>NULL</entry> <entry>NULL</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> The operators <literal>AND</literal> and <literal>OR</literal> are commutative, that is, you can switch the left and right operands without affecting the result. (However, it is not guaranteed that the left operand is evaluated before the right operand. See <xref linkend="syntax-express-eval"/> for more information about the order of evaluation of subexpressions.) </para> </sect1> <sect1 id="functions-comparison"> <title>Comparison Functions and Operators</title> <indexterm zone="functions-comparison"> <primary>comparison</primary> <secondary>operators</secondary> </indexterm> <para> The usual comparison operators are available, as shown in <xref linkend="functions-comparison-op-table"/>. </para> <table id="functions-comparison-op-table"> <title>Comparison Operators</title> <tgroup cols="2"> <thead> <row> <entry>Operator</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <replaceable>datatype</replaceable> <literal><</literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Less than</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal>></literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Greater than</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal><=</literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Less than or equal to</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal>>=</literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Greater than or equal to</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal>=</literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Equal</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal><></literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Not equal</entry> </row> <row> <entry> <replaceable>datatype</replaceable> <literal>!=</literal> <replaceable>datatype</replaceable> <returnvalue>boolean</returnvalue> </entry> <entry>Not equal</entry> </row> </tbody> </tgroup> </table> <note> <para> <literal><></literal> is the standard SQL notation for <quote>not equal</quote>. <literal>!=</literal> is an alias, which is converted to <literal><></literal> at a very early stage of parsing. Hence, it is not possible to implement <literal>!=</literal> and <literal><></literal> operators that do different things. </para> </note> <para> These comparison operators are available for all built-in data types that have a natural ordering, including numeric, string, and date/time types. In addition, arrays, composite types, and ranges can be compared if their component data types are comparable. </para> <para> It is usually possible to compare values of related data types as well; for example <type>integer</type> <literal>></literal> <type>bigint</type> will work. Some cases of this sort are implemented directly by <quote>cross-type</quote> comparison operators, but if no such operator is available, the parser will coerce the less-general type to the more-general type and apply the latter's comparison operator. </para> <para> As shown above, all comparison operators are binary operators that return values of type <type>boolean</type>. Thus, expressions like <literal>1 < 2 < 3</literal> are not valid (because there is no <literal><</literal> operator to compare a Boolean value with <literal>3</literal>). Use the <literal>BETWEEN</literal> predicates shown below to perform range tests. </para> <para> There are also some comparison predicates, as shown in <xref linkend="functions-comparison-pred-table"/>. These behave much like operators, but have special syntax mandated by the SQL standard. </para> <table id="functions-comparison-pred-table"> <title>Comparison Predicates</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Predicate </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>BETWEEN</literal> <replaceable>datatype</replace <returnvalue>boolean</returnvalue> </para> <para> Between (inclusive of the range endpoints). </para> <para> <literal>2 BETWEEN 1 AND 3</literal> <returnvalue>t</returnvalue> </para> <para> <literal>2 BETWEEN 3 AND 1</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>NOT BETWEEN</literal> <replaceable>datatype</repl <returnvalue>boolean</returnvalue> </para> <para> Not between (the negation of <literal>BETWEEN</literal>). </para> <para> <literal>2 NOT BETWEEN 1 AND 3</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>BETWEEN SYMMETRIC</literal> <replaceable>datatyp <returnvalue>boolean</returnvalue> </para> <para> Between, after sorting the two endpoint values. </para> <para> <literal>2 BETWEEN SYMMETRIC 3 AND 1</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>NOT BETWEEN SYMMETRIC</literal> <replaceable>data <returnvalue>boolean</returnvalue> </para> <para> Not between, after sorting the two endpoint values. </para> <para> <literal>2 NOT BETWEEN SYMMETRIC 3 AND 1</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>IS DISTINCT FROM</literal> <replaceable>datatype</ <returnvalue>boolean</returnvalue> </para> <para> Not equal, treating null as a comparable value. </para> <para> <literal>1 IS DISTINCT FROM NULL</literal> <returnvalue>t</returnvalue> (rather than <literal>NULL</literal>) </para> <para> <literal>NULL IS DISTINCT FROM NULL</literal> <returnvalue>f</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>IS NOT DISTINCT FROM</literal> <replaceable>dataty <returnvalue>boolean</returnvalue> </para> <para> Equal, treating null as a comparable value. </para> <para> <literal>1 IS NOT DISTINCT FROM NULL</literal> <returnvalue>f</returnvalue> (rather than <literal>NULL</literal>) </para> <para> <literal>NULL IS NOT DISTINCT FROM NULL</literal> <returnvalue>t</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>IS NULL</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether value is null. </para> <para> <literal>1.5 IS NULL</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>IS NOT NULL</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether value is not null. </para> <para> <literal>'null' IS NOT NULL</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>ISNULL</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether value is null (nonstandard syntax). </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>datatype</replaceable> <literal>NOTNULL</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether value is not null (nonstandard syntax). </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS TRUE</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields true. </para> <para> <literal>true IS TRUE</literal> <returnvalue>t</returnvalue> </para> <para> <literal>NULL::boolean IS TRUE</literal> <returnvalue>f</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS NOT TRUE</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields false or unknown. </para> <para> <literal>true IS NOT TRUE</literal> <returnvalue>f</returnvalue> </para> <para> <literal>NULL::boolean IS NOT TRUE</literal> <returnvalue>t</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS FALSE</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields false. </para> <para> <literal>true IS FALSE</literal> <returnvalue>f</returnvalue> </para> <para> <literal>NULL::boolean IS FALSE</literal> <returnvalue>f</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS NOT FALSE</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields true or unknown. </para> <para> <literal>true IS NOT FALSE</literal> <returnvalue>t</returnvalue> </para> <para> <literal>NULL::boolean IS NOT FALSE</literal> <returnvalue>t</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS UNKNOWN</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields unknown. </para> <para> <literal>true IS UNKNOWN</literal> <returnvalue>f</returnvalue> </para> <para> <literal>NULL::boolean IS UNKNOWN</literal> <returnvalue>t</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>boolean</type> <literal>IS NOT UNKNOWN</literal> <returnvalue>boolean</returnvalue> </para> <para> Test whether boolean expression yields true or false. </para> <para> <literal>true IS NOT UNKNOWN</literal> <returnvalue>t</returnvalue> </para> <para> <literal>NULL::boolean IS NOT UNKNOWN</literal> <returnvalue>f</returnvalue> (rather than <literal>NULL</literal>) </para></entry> </row> </tbody> </tgroup> </table> <para> <indexterm> <primary>BETWEEN</primary> </indexterm> <indexterm> <primary>BETWEEN SYMMETRIC</primary> </indexterm> The <token>BETWEEN</token> predicate simplifies range tests: <synopsis> <replaceable>a</replaceable> BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceab </synopsis> is equivalent to <synopsis> <replaceable>a</replaceable> >= <replaceable>x</replaceable> AND <replaceable>a</replaceable> <= <rep </synopsis> Notice that <token>BETWEEN</token> treats the endpoint values as included in the range. <literal>BETWEEN SYMMETRIC</literal> is like <literal>BETWEEN</literal> except there is no requirement that the argument to the left of <literal>AND</literal> be less than or equal to the argument on the right. If it is not, those two arguments are automatically swapped, so that a nonempty range is always implied. </para> <para> The various variants of <literal>BETWEEN</literal> are implemented in terms of the ordinary comparison operators, and therefore will work for any data type(s) that can be compared. </para> <note> <para> The use of <literal>AND</literal> in the <literal>BETWEEN</literal> syntax creates an ambiguity with the use of <literal>AND</literal> as a logical operator. To resolve this, only a limited set of expression types are allowed as the second argument of a <literal>BETWEEN</literal> clause. If you need to write a more complex sub-expression in <literal>BETWEEN</literal>, write parentheses around the sub-expression. </para> </note> <para> <indexterm> <primary>IS DISTINCT FROM</primary> </indexterm> <indexterm> <primary>IS NOT DISTINCT FROM</primary> </indexterm> Ordinary comparison operators yield null (signifying <quote>unknown</quote>), not true or false, when either input is null. For example, <literal>7 = NULL</literal> yields null, as does <literal>7 <> NULL</literal>. When this behavior is not suitable, use the <literal>IS <optional> NOT </optional> DISTINCT FROM</literal> predicates: <synopsis> <replaceable>a</replaceable> IS DISTINCT FROM <replaceable>b</replaceable> <replaceable>a</replaceable> IS NOT DISTINCT FROM <replaceable>b</replaceable> </synopsis> For non-null inputs, <literal>IS DISTINCT FROM</literal> is the same as the <literal><></literal> operator. However, if both inputs are null it returns false, and if only one input is null it returns true. Similarly, <literal>IS NOT DISTINCT FROM</literal> is identical to <literal>=</literal> for non-null inputs, but it returns true when both inputs are null, and false when only one input is null. Thus, these predicates effectively act as though null were a normal data value, rather than <quote>unknown</quote>. </para> <para> <indexterm> <primary>IS NULL</primary> </indexterm> <indexterm> <primary>IS NOT NULL</primary> </indexterm> <indexterm> <primary>ISNULL</primary> </indexterm> <indexterm> <primary>NOTNULL</primary> </indexterm> To check whether a value is or is not null, use the predicates: <synopsis> <replaceable>expression</replaceable> IS NULL <replaceable>expression</replaceable> IS NOT NULL </synopsis> or the equivalent, but nonstandard, predicates: <synopsis> <replaceable>expression</replaceable> ISNULL <replaceable>expression</replaceable> NOTNULL </synopsis> <indexterm><primary>null value</primary><secondary>comparing</secondary></indexterm> </para> <para> Do <emphasis>not</emphasis> write <literal><replaceable>expression</replaceable> = NULL</literal> because <literal>NULL</literal> is not <quote>equal to</quote> <literal>NULL</literal>. (The null value represents an unknown value, and it is not known whether two unknown values are equal.) </para> <tip> <para> Some applications might expect that <literal><replaceable>expression</replaceable> = NULL</literal> returns true if <replaceable>expression</replaceable> evaluates to the null value. It is highly recommended that these applications be modified to comply with the SQL standard. However, if that cannot be done the <xref linkend="guc-transform-null-equals"/> configuration variable is available. If it is enabled, <productname>PostgreSQL</productname> will convert <literal>x = NULL</literal> clauses to <literal>x IS NULL</literal>. </para> </tip> <para> If the <replaceable>expression</replaceable> is row-valued, then <literal>IS NULL</literal> is true when the row expression itself is null or when all the row's fields are null, while <literal>IS NOT NULL</literal> is true when the row expression itself is non-null and all the row's fields are non-null. Because of this behavior, <literal>IS NULL</literal> and <literal>IS NOT NULL</literal> do not always return inverse results for row-valued expressions; in particular, a row-valued expression that contains both null and non-null fields will return false for both tests. For example: <programlisting> SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same'); SELECT ROW(table.*) IS NULL FROM table; -- detect all-null rows SELECT ROW(table.*) IS NOT NULL FROM table; -- detect all-non-null rows SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows </programlisting> In some cases, it may be preferable to write <replaceable>row</replaceable> <literal>IS DISTINCT FROM NULL</literal> or <replaceable>row</replaceable> <literal>IS NOT DISTINCT FROM NULL</literal>, which will simply check whether the overall row value is null without any additional tests on the row fields. </para> <para> <indexterm> <primary>IS TRUE</primary> </indexterm> <indexterm> <primary>IS NOT TRUE</primary> </indexterm> <indexterm> <primary>IS FALSE</primary> </indexterm> <indexterm> <primary>IS NOT FALSE</primary> </indexterm> <indexterm> <primary>IS UNKNOWN</primary> </indexterm> <indexterm> <primary>IS NOT UNKNOWN</primary> </indexterm> Boolean values can also be tested using the predicates <synopsis> <replaceable>boolean_expression</replaceable> IS TRUE <replaceable>boolean_expression</replaceable> IS NOT TRUE <replaceable>boolean_expression</replaceable> IS FALSE <replaceable>boolean_expression</replaceable> IS NOT FALSE <replaceable>boolean_expression</replaceable> IS UNKNOWN <replaceable>boolean_expression</replaceable> IS NOT UNKNOWN </synopsis> These will always return true or false, never a null value, even when the operand is null. A null input is treated as the logical value <quote>unknown</quote>. Notice that <literal>IS UNKNOWN</literal> and <literal>IS NOT UNKNOWN</literal> are effectively the same as <literal>IS NULL</literal> and <literal>IS NOT NULL</literal>, respectively, except that the input expression must be of Boolean type. </para> <para> Some comparison-related functions are also available, as shown in <xref linkend="functions-comparison-func-table"/>. </para> <table id="functions-comparison-func-table"> <title>Comparison Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>num_nonnulls</primary> </indexterm> <function>num_nonnulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of non-null arguments. </para> <para> <literal>num_nonnulls(1, NULL, 2)</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>num_nulls</primary> </indexterm> <function>num_nulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of null arguments. </para> <para> <literal>num_nulls(1, NULL, 2)</literal> <returnvalue>1</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> </sect1> <sect1 id="functions-math"> <title>Mathematical Functions and Operators</title> <para> Mathematical operators are provided for many <productname>PostgreSQL</productname> types. For types without standard mathematical conventions (e.g., date/time types) we describe the actual behavior in subsequent sections. </para> <para> <xref linkend="functions-math-op-table"/> shows the mathematical operators that are available for the standard numeric types. Unless otherwise noted, operators shown as accepting <replaceable>numeric_type</replaceable> are available for all the types <type>smallint</type>, <type>integer</type>, <type>bigint</type>, <type>numeric</type>, <type>real</type>, and <type>double precision</type>. Operators shown as accepting <replaceable>integral_type</replaceable> are available for the types <type>smallint</type>, <type>integer</type>, and <type>bigint</type>. Except where noted, each form of an operator returns the same data type as its argument(s). Calls involving multiple argument data types, such as <type>integer</type> <literal>+</literal> <type>numeric</type>, are resolved by using the type appearing later in these lists. </para> <table id="functions-math-op-table"> <title>Mathematical Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>numeric_type</replaceable> <literal>+</literal> <replaceable>numeric_type</repla <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Addition </para> <para> <literal>2 + 3</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>+</literal> <replaceable>numeric_type</replaceable> <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Unary plus (no operation) </para> <para> <literal>+ 3.5</literal> <returnvalue>3.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>numeric_type</replaceable> <literal>-</literal> <replaceable>numeric_type</repla <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Subtraction </para> <para> <literal>2 - 3</literal> <returnvalue>-1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>-</literal> <replaceable>numeric_type</replaceable> <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Negation </para> <para> <literal>- (-4)</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>numeric_type</replaceable> <literal>*</literal> <replaceable>numeric_type</repla <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Multiplication </para> <para> <literal>2 * 3</literal> <returnvalue>6</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>numeric_type</replaceable> <literal>/</literal> <replaceable>numeric_type</repla <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Division (for integral types, division truncates the result towards zero) </para> <para> <literal>5.0 / 2</literal> <returnvalue>2.5000000000000000</returnvalue> </para> <para> <literal>5 / 2</literal> <returnvalue>2</returnvalue> </para> <para> <literal>(-5) / 2</literal> <returnvalue>-2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>numeric_type</replaceable> <literal>%</literal> <replaceable>numeric_type</repla <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Modulo (remainder); available for <type>smallint</type>, <type>integer</type>, <type>bigint</type>, and <type>numeric</type> </para> <para> <literal>5 % 4</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>numeric</type> <literal>^</literal> <type>numeric</type> <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <type>double precision</type> <literal>^</literal> <type>double precision</type> <returnvalue>double precision</returnvalue> </para> <para> Exponentiation </para> <para> <literal>2 ^ 3</literal> <returnvalue>8</returnvalue> </para> <para> Unlike typical mathematical practice, multiple uses of <literal>^</literal> will associate left to right by default: </para> <para> <literal>2 ^ 3 ^ 3</literal> <returnvalue>512</returnvalue> </para> <para> <literal>2 ^ (3 ^ 3)</literal> <returnvalue>134217728</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>|/</literal> <type>double precision</type> <returnvalue>double precision</returnvalue> </para> <para> Square root </para> <para> <literal>|/ 25.0</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>||/</literal> <type>double precision</type> <returnvalue>double precision</returnvalue> </para> <para> Cube root </para> <para> <literal>||/ 64.0</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>@</literal> <replaceable>numeric_type</replaceable> <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Absolute value </para> <para> <literal>@ -5.0</literal> <returnvalue>5.0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>integral_type</replaceable> <literal>&</literal> <replaceable>integral_type</repl <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise AND </para> <para> <literal>91 & 15</literal> <returnvalue>11</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>integral_type</replaceable> <literal>|</literal> <replaceable>integral_type</rep <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise OR </para> <para> <literal>32 | 3</literal> <returnvalue>35</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>integral_type</replaceable> <literal>#</literal> <replaceable>integral_type</rep <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise exclusive OR </para> <para> <literal>17 # 5</literal> <returnvalue>20</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>~</literal> <replaceable>integral_type</replaceable> <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise NOT </para> <para> <literal>~1</literal> <returnvalue>-2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>integral_type</replaceable> <literal><<</literal> <type>integer</type> <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise shift left </para> <para> <literal>1 << 4</literal> <returnvalue>16</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>integral_type</replaceable> <literal>>></literal> <type>integer</type> <returnvalue><replaceable>integral_type</replaceable></returnvalue> </para> <para> Bitwise shift right </para> <para> <literal>8 >> 2</literal> <returnvalue>2</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> <xref linkend="functions-math-func-table"/> shows the available mathematical functions. Many of these functions are provided in multiple forms with different argument types. Except where noted, any given form of a function returns the same data type as its argument(s); cross-type cases are resolved in the same way as explained above for operators. The functions working with <type>double precision</type> data are mostly implemented on top of the host system's C library; accuracy and behavior in boundary cases can therefore vary depending on the host system. </para> <table id="functions-math-func-table"> <title>Mathematical Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>abs</primary> </indexterm> <function>abs</function> ( <replaceable>numeric_type</replaceable> ) <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Absolute value </para> <para> <literal>abs(-17.4)</literal> <returnvalue>17.4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cbrt</primary> </indexterm> <function>cbrt</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Cube root </para> <para> <literal>cbrt(64.0)</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ceil</primary> </indexterm> <function>ceil</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>ceil</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Nearest integer greater than or equal to argument </para> <para> <literal>ceil(42.2)</literal> <returnvalue>43</returnvalue> </para> <para> <literal>ceil(-42.8)</literal> <returnvalue>-42</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ceiling</primary> </indexterm> <function>ceiling</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>ceiling</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Nearest integer greater than or equal to argument (same as <function>ceil</function>) </para> <para> <literal>ceiling(95.3)</literal> <returnvalue>96</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>degrees</primary> </indexterm> <function>degrees</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Converts radians to degrees </para> <para> <literal>degrees(0.5)</literal> <returnvalue>28.64788975654116</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>div</primary> </indexterm> <function>div</function> ( <parameter>y</parameter> <type>numeric</type>, <parameter>x</parameter> <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para> Integer quotient of <parameter>y</parameter>/<parameter>x</parameter> (truncates towards zero) </para> <para> <literal>div(9, 4)</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>erf</primary> </indexterm> <function>erf</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Error function </para> <para> <literal>erf(1.0)</literal> <returnvalue>0.8427007929497149</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>erfc</primary> </indexterm> <function>erfc</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Complementary error function (<literal>1 - erf(x)</literal>, without loss of precision for large inputs) </para> <para> <literal>erfc(1.0)</literal> <returnvalue>0.15729920705028513</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>exp</primary> </indexterm> <function>exp</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>exp</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Exponential (<literal>e</literal> raised to the given power) </para> <para> <literal>exp(1.0)</literal> <returnvalue>2.7182818284590452</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-factorial"> <primary>factorial</primary> </indexterm> <function>factorial</function> ( <type>bigint</type> ) <returnvalue>numeric</returnvalue> </para> <para> Factorial </para> <para> <literal>factorial(5)</literal> <returnvalue>120</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>floor</primary> </indexterm> <function>floor</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>floor</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Nearest integer less than or equal to argument </para> <para> <literal>floor(42.8)</literal> <returnvalue>42</returnvalue> </para> <para> <literal>floor(-42.8)</literal> <returnvalue>-43</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>gamma</primary> </indexterm> <function>gamma</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Gamma function </para> <para> <literal>gamma(0.5)</literal> <returnvalue>1.772453850905516</returnvalue> </para> <para> <literal>gamma(6)</literal> <returnvalue>120</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>gcd</primary> </indexterm> <function>gcd</function> ( <replaceable>numeric_type</replaceable>, <replaceable>numeric_type< <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Greatest common divisor (the largest positive number that divides both inputs with no remainder); returns <literal>0</literal> if both inputs are zero; available for <type>integer</type>, <type>bigint</type>, and <type>numeric</type> </para> <para> <literal>gcd(1071, 462)</literal> <returnvalue>21</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>lcm</primary> </indexterm> <function>lcm</function> ( <replaceable>numeric_type</replaceable>, <replaceable>numeric_type< <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Least common multiple (the smallest strictly positive number that is an integral multiple of both inputs); returns <literal>0</literal> if either input is zero; available for <type>integer</type>, <type>bigint</type>, and <type>numeric</type> </para> <para> <literal>lcm(1071, 462)</literal> <returnvalue>23562</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>lgamma</primary> </indexterm> <function>lgamma</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Natural logarithm of the absolute value of the gamma function </para> <para> <literal>lgamma(1000)</literal> <returnvalue>5905.220423209181</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ln</primary> </indexterm> <function>ln</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>ln</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Natural logarithm </para> <para> <literal>ln(2.0)</literal> <returnvalue>0.6931471805599453</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>log</primary> </indexterm> <function>log</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>log</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Base 10 logarithm </para> <para> <literal>log(100)</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>log10</primary> </indexterm> <function>log10</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>log10</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Base 10 logarithm (same as <function>log</function>) </para> <para> <literal>log10(1000)</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>log</function> ( <parameter>b</parameter> <type>numeric</type>, <parameter>x</parameter> <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para> Logarithm of <parameter>x</parameter> to base <parameter>b</parameter> </para> <para> <literal>log(2.0, 64.0)</literal> <returnvalue>6.0000000000000000</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>min_scale</primary> </indexterm> <function>min_scale</function> ( <type>numeric</type> ) <returnvalue>integer</returnvalue> </para> <para> Minimum scale (number of fractional decimal digits) needed to represent the supplied value precisely </para> <para> <literal>min_scale(8.4100)</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>mod</primary> </indexterm> <function>mod</function> ( <parameter>y</parameter> <replaceable>numeric_type</replaceable>, <parameter>x</parameter> <replaceable>numeric_type</replaceable> ) <returnvalue><replaceable>numeric_type</replaceable></returnvalue> </para> <para> Remainder of <parameter>y</parameter>/<parameter>x</parameter>; available for <type>smallint</type>, <type>integer</type>, <type>bigint</type>, and <type>numeric</type> </para> <para> <literal>mod(9, 4)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pi</primary> </indexterm> <function>pi</function> ( ) <returnvalue>double precision</returnvalue> </para> <para> Approximate value of <phrase role="symbol_font">π</phrase> </para> <para> <literal>pi()</literal> <returnvalue>3.141592653589793</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>power</primary> </indexterm> <function>power</function> ( <parameter>a</parameter> <type>numeric</type>, <parameter>b</parameter> <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>power</function> ( <parameter>a</parameter> <type>double precision</type>, <parameter>b</parameter> <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> <parameter>a</parameter> raised to the power of <parameter>b</parameter> </para> <para> <literal>power(9, 3)</literal> <returnvalue>729</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>radians</primary> </indexterm> <function>radians</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Converts degrees to radians </para> <para> <literal>radians(45.0)</literal> <returnvalue>0.7853981633974483</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>round</primary> </indexterm> <function>round</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>round</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Rounds to nearest integer. For <type>numeric</type>, ties are broken by rounding away from zero. For <type>double precision</type>, the tie-breaking behavior is platform dependent, but <quote>round to nearest even</quote> is the most common rule. </para> <para> <literal>round(42.4)</literal> <returnvalue>42</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>round</function> ( <parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> < <returnvalue>numeric</returnvalue> </para> <para> Rounds <parameter>v</parameter> to <parameter>s</parameter> decimal places. Ties are broken by rounding away from zero. </para> <para> <literal>round(42.4382, 2)</literal> <returnvalue>42.44</returnvalue> </para> <para> <literal>round(1234.56, -1)</literal> <returnvalue>1230</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>scale</primary> </indexterm> <function>scale</function> ( <type>numeric</type> ) <returnvalue>integer</returnvalue> </para> <para> Scale of the argument (the number of decimal digits in the fractional part) </para> <para> <literal>scale(8.4100)</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sign</primary> </indexterm> <function>sign</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>sign</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Sign of the argument (-1, 0, or +1) </para> <para> <literal>sign(-8.4)</literal> <returnvalue>-1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sqrt</primary> </indexterm> <function>sqrt</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>sqrt</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Square root </para> <para> <literal>sqrt(2)</literal> <returnvalue>1.4142135623730951</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>trim_scale</primary> </indexterm> <function>trim_scale</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para> Reduces the value's scale (number of fractional decimal digits) by removing trailing zeroes </para> <para> <literal>trim_scale(8.4100)</literal> <returnvalue>8.41</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>trunc</primary> </indexterm> <function>trunc</function> ( <type>numeric</type> ) <returnvalue>numeric</returnvalue> </para> <para role="func_signature"> <function>trunc</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Truncates to integer (towards zero) </para> <para> <literal>trunc(42.8)</literal> <returnvalue>42</returnvalue> </para> <para> <literal>trunc(-42.8)</literal> <returnvalue>-42</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>trunc</function> ( <parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> < <returnvalue>numeric</returnvalue> </para> <para> Truncates <parameter>v</parameter> to <parameter>s</parameter> decimal places </para> <para> <literal>trunc(42.4382, 2)</literal> <returnvalue>42.43</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>width_bucket</primary> </indexterm> <function>width_bucket</function> ( <parameter>operand</parameter> <type>numeric</type>, <paramet <returnvalue>integer</returnvalue> </para> <para role="func_signature"> <function>width_bucket</function> ( <parameter>operand</parameter> <type>double precision</type> <returnvalue>integer</returnvalue> </para> <para> Returns the number of the bucket in which <parameter>operand</parameter> falls in a histogram having <parameter>count</parameter> equal-width buckets spanning the range <parameter>low</parameter> to <parameter>high</parameter>. The buckets have inclusive lower bounds and exclusive upper bounds. Returns <literal>0</literal> for an input less than <parameter>low</parameter>, or <literal><parameter>count</parameter>+1</literal> for an input greater than or equal to <parameter>high</parameter>. If <parameter>low</parameter> > <parameter>high</parameter>, the behavior is mirror-reversed, with bucket <literal>1</literal> now being the one just below <parameter>low</parameter>, and the inclusive bounds now being on the upper side. </para> <para> <literal>width_bucket(5.35, 0.024, 10.06, 5)</literal> <returnvalue>3</returnvalue> </para> <para> <literal>width_bucket(9, 10, 0, 10)</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>width_bucket</function> ( <parameter>operand</parameter> <type>anycompatible</type>, <p <returnvalue>integer</returnvalue> </para> <para> Returns the number of the bucket in which <parameter>operand</parameter> falls given an array listing the inclusive lower bounds of the buckets. Returns <literal>0</literal> for an input less than the first lower bound. <parameter>operand</parameter> and the array elements can be of any type having standard comparison operators. The <parameter>thresholds</parameter> array <emphasis>must be sorted</emphasis>, smallest first, or unexpected results will be obtained. </para> <para> <literal>width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])</ <returnvalue>2</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> <xref linkend="functions-math-random-table"/> shows functions for generating random numbers. </para> <table id="functions-math-random-table"> <title>Random Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>random</primary> </indexterm> <function>random</function> ( ) <returnvalue>double precision</returnvalue> </para> <para> Returns a random value in the range 0.0 <= x < 1.0 </para> <para> <literal>random()</literal> <returnvalue>0.897124072839091</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>random</primary> </indexterm> <function>random</function> ( <parameter>min</parameter> <type>integer</type>, <parameter>max</para <returnvalue>integer</returnvalue> </para> <para role="func_signature"> <function>random</function> ( <parameter>min</parameter> <type>bigint</type>, <parameter>max</param <returnvalue>bigint</returnvalue> </para> <para role="func_signature"> <function>random</function> ( <parameter>min</parameter> <type>numeric</type>, <parameter>max</para <returnvalue>numeric</returnvalue> </para> <para> Returns a random value in the range <parameter>min</parameter> <= x <= <parameter>max</parameter>. For type <type>numeric</type>, the result will have the same number of fractional decimal digits as <parameter>min</parameter> or <parameter>max</parameter>, whichever has more. </para> <para> <literal>random(1, 10)</literal> <returnvalue>7</returnvalue> </para> <para> <literal>random(-0.499, 0.499)</literal> <returnvalue>0.347</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>random_normal</primary> </indexterm> <function>random_normal</function> ( <optional> <parameter>mean</parameter> <type>double precision</type> <optional>, <parameter>stddev</parameter> <type>double precision</type> </optional></optional> ) <returnvalue>double precision</returnvalue> </para> <para> Returns a random value from the normal distribution with the given parameters; <parameter>mean</parameter> defaults to 0.0 and <parameter>stddev</parameter> defaults to 1.0 </para> <para> <literal>random_normal(0.0, 1.0)</literal> <returnvalue>0.051285419</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>setseed</primary> </indexterm> <function>setseed</function> ( <type>double precision</type> ) <returnvalue>void</returnvalue> </para> <para> Sets the seed for subsequent <literal>random()</literal> and <literal>random_normal()</literal> calls; argument must be between -1.0 and 1.0, inclusive </para> <para> <literal>setseed(0.12345)</literal> </para></entry> </row> </tbody> </tgroup> </table> <para> The <function>random()</function> and <function>random_normal()</function> functions listed in <xref linkend="functions-math-random-table"/> use a deterministic pseudo-random number generator. It is fast but not suitable for cryptographic applications; see the <xref linkend="pgcrypto"/> module for a more secure alternative. If <function>setseed()</function> is called, the series of results of subsequent calls to these functions in the current session can be repeated by re-issuing <function>setseed()</function> with the same argument. Without any prior <function>setseed()</function> call in the same session, the first call to any of these functions obtains a seed from a platform-dependent source of random bits. </para> <para> <xref linkend="functions-math-trig-table"/> shows the available trigonometric functions. Each of these functions comes in two variants, one that measures angles in radians and one that measures angles in degrees. </para> <table id="functions-math-trig-table"> <title>Trigonometric Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>acos</primary> </indexterm> <function>acos</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse cosine, result in radians </para> <para> <literal>acos(1)</literal> <returnvalue>0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>acosd</primary> </indexterm> <function>acosd</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse cosine, result in degrees </para> <para> <literal>acosd(0.5)</literal> <returnvalue>60</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>asin</primary> </indexterm> <function>asin</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse sine, result in radians </para> <para> <literal>asin(1)</literal> <returnvalue>1.5707963267948966</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>asind</primary> </indexterm> <function>asind</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse sine, result in degrees </para> <para> <literal>asind(0.5)</literal> <returnvalue>30</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>atan</primary> </indexterm> <function>atan</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse tangent, result in radians </para> <para> <literal>atan(1)</literal> <returnvalue>0.7853981633974483</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>atand</primary> </indexterm> <function>atand</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse tangent, result in degrees </para> <para> <literal>atand(1)</literal> <returnvalue>45</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>atan2</primary> </indexterm> <function>atan2</function> ( <parameter>y</parameter> <type>double precision</type>, <parameter>x</parameter> <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse tangent of <parameter>y</parameter>/<parameter>x</parameter>, result in radians </para> <para> <literal>atan2(1, 0)</literal> <returnvalue>1.5707963267948966</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>atan2d</primary> </indexterm> <function>atan2d</function> ( <parameter>y</parameter> <type>double precision</type>, <parameter>x</parameter> <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse tangent of <parameter>y</parameter>/<parameter>x</parameter>, result in degrees </para> <para> <literal>atan2d(1, 0)</literal> <returnvalue>90</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cos</primary> </indexterm> <function>cos</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Cosine, argument in radians </para> <para> <literal>cos(0)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cosd</primary> </indexterm> <function>cosd</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Cosine, argument in degrees </para> <para> <literal>cosd(60)</literal> <returnvalue>0.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cot</primary> </indexterm> <function>cot</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Cotangent, argument in radians </para> <para> <literal>cot(0.5)</literal> <returnvalue>1.830487721712452</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cotd</primary> </indexterm> <function>cotd</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Cotangent, argument in degrees </para> <para> <literal>cotd(45)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sin</primary> </indexterm> <function>sin</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Sine, argument in radians </para> <para> <literal>sin(1)</literal> <returnvalue>0.8414709848078965</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sind</primary> </indexterm> <function>sind</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Sine, argument in degrees </para> <para> <literal>sind(30)</literal> <returnvalue>0.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>tan</primary> </indexterm> <function>tan</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Tangent, argument in radians </para> <para> <literal>tan(1)</literal> <returnvalue>1.5574077246549023</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>tand</primary> </indexterm> <function>tand</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Tangent, argument in degrees </para> <para> <literal>tand(45)</literal> <returnvalue>1</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <note> <para> Another way to work with angles measured in degrees is to use the unit transformation functions <literal><function>radians()</function></literal> and <literal><function>degrees()</function></literal> shown earlier. However, using the degree-based trigonometric functions is preferred, as that way avoids round-off error for special cases such as <literal>sind(30)</literal>. </para> </note> <para> <xref linkend="functions-math-hyp-table"/> shows the available hyperbolic functions. </para> <table id="functions-math-hyp-table"> <title>Hyperbolic Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sinh</primary> </indexterm> <function>sinh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Hyperbolic sine </para> <para> <literal>sinh(1)</literal> <returnvalue>1.1752011936438014</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>cosh</primary> </indexterm> <function>cosh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Hyperbolic cosine </para> <para> <literal>cosh(0)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>tanh</primary> </indexterm> <function>tanh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Hyperbolic tangent </para> <para> <literal>tanh(1)</literal> <returnvalue>0.7615941559557649</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>asinh</primary> </indexterm> <function>asinh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse hyperbolic sine </para> <para> <literal>asinh(1)</literal> <returnvalue>0.881373587019543</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>acosh</primary> </indexterm> <function>acosh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse hyperbolic cosine </para> <para> <literal>acosh(1)</literal> <returnvalue>0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>atanh</primary> </indexterm> <function>atanh</function> ( <type>double precision</type> ) <returnvalue>double precision</returnvalue> </para> <para> Inverse hyperbolic tangent </para> <para> <literal>atanh(0.5)</literal> <returnvalue>0.5493061443340548</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> </sect1> <sect1 id="functions-string"> <title>String Functions and Operators</title> <para> This section describes functions and operators for examining and manipulating string values. Strings in this context include values of the types <type>character</type>, <type>character varying</type>, and <type>text</type>. Except where noted, these functions and operators are declared to accept and return type <type>text</type>. They will interchangeably accept <type>character varying</type> arguments. Values of type <type>character</type> will be converted to <type>text</type> before the function or operator is applied, resulting in stripping any trailing spaces in the <type>character</type> value. </para> <para> <acronym>SQL</acronym> defines some string functions that use key words, rather than commas, to separate arguments. Details are in <xref linkend="functions-string-sql"/>. <productname>PostgreSQL</productname> also provides versions of these functions that use the regular function invocation syntax (see <xref linkend="functions-string-other"/>). </para> <note> <para> The string concatenation operator (<literal>||</literal>) will accept non-string input, so long as at least one input is of string type, as shown in <xref linkend="functions-string-sql"/>. For other cases, inserting an explicit coercion to <type>text</type> can be used to have non-string input accepted. </para> </note> <table id="functions-string-sql"> <title><acronym>SQL</acronym> String Functions and Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function/Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>character string</primary> <secondary>concatenation</secondary> </indexterm> <type>text</type> <literal>||</literal> <type>text</type> <returnvalue>text</returnvalue> </para> <para> Concatenates the two strings. </para> <para> <literal>'Post' || 'greSQL'</literal> <returnvalue>PostgreSQL</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>||</literal> <type>anynonarray</type> <returnvalue>text</returnvalue> </para> <para role="func_signature"> <type>anynonarray</type> <literal>||</literal> <type>text</type> <returnvalue>text</returnvalue> </para> <para> Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array <literal>||</literal> operators. If you want to concatenate an array's text equivalent, cast it to <type>text</type> explicitly.) </para> <para> <literal>'Value: ' || 42</literal> <returnvalue>Value: 42</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>btrim</primary> </indexterm> <function>btrim</function> ( <parameter>string</parameter> <type>text</type> <optional>, <parameter>characters</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Removes the longest string containing only characters in <parameter>characters</parameter> (a space by default) from the start and end of <parameter>string</parameter>. </para> <para> <literal>btrim('xyxtrimyyx', 'xyz')</literal> <returnvalue>trim</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>normalized</primary> </indexterm> <indexterm> <primary>Unicode normalization</primary> </indexterm> <type>text</type> <literal>IS</literal> <optional><literal>NOT</literal></optional> <optional><paramet <returnvalue>boolean</returnvalue> </para> <para> Checks whether the string is in the specified Unicode normalization form. The optional <parameter>form</parameter> key word specifies the form: <literal>NFC</literal> (the default), <literal>NFD</literal>, <literal>NFKC</literal>, or <literal>NFKD</literal>. This expression can only be used when the server encoding is <literal>UTF8</literal>. Note that checking for normalization using this expression is often faster than normalizing possibly already normalized strings. </para> <para> <literal>U&'\0061\0308bc' IS NFD NORMALIZED</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bit_length</primary> </indexterm> <function>bit_length</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bits in the string (8 times the <function>octet_length</function>). </para> <para> <literal>bit_length('jose')</literal> <returnvalue>32</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>char_length</primary> </indexterm> <indexterm> <primary>character string</primary> <secondary>length</secondary> </indexterm> <indexterm> <primary>length</primary> <secondary sortas="character string">of a character string</secondary> <see>character string, length</see> </indexterm> <function>char_length</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para role="func_signature"> <indexterm> <primary>character_length</primary> </indexterm> <function>character_length</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of characters in the string. </para> <para> <literal>char_length('josé')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-lower"> <primary>lower</primary> </indexterm> <function>lower</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the string to all lower case, according to the rules of the database's locale. </para> <para> <literal>lower('TOM')</literal> <returnvalue>tom</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>lpad</primary> </indexterm> <function>lpad</function> ( <parameter>string</parameter> <type>text</type>, <parameter>length</parameter> <type>integer</type> <optional>, <parameter>fill</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Extends the <parameter>string</parameter> to length <parameter>length</parameter> by prepending the characters <parameter>fill</parameter> (a space by default). If the <parameter>string</parameter> is already longer than <parameter>length</parameter> then it is truncated (on the right). </para> <para> <literal>lpad('hi', 5, 'xy')</literal> <returnvalue>xyxhi</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ltrim</primary> </indexterm> <function>ltrim</function> ( <parameter>string</parameter> <type>text</type> <optional>, <parameter>characters</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Removes the longest string containing only characters in <parameter>characters</parameter> (a space by default) from the start of <parameter>string</parameter>. </para> <para> <literal>ltrim('zzzytest', 'xyz')</literal> <returnvalue>test</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-normalize"> <primary>normalize</primary> </indexterm> <indexterm> <primary>Unicode normalization</primary> </indexterm> <function>normalize</function> ( <type>text</type> <optional>, <parameter>form</parameter> </optional> ) <returnvalue>text</returnvalue> </para> <para> Converts the string to the specified Unicode normalization form. The optional <parameter>form</parameter> key word specifies the form: <literal>NFC</literal> (the default), <literal>NFD</literal>, <literal>NFKC</literal>, or <literal>NFKD</literal>. This function can only be used when the server encoding is <literal>UTF8</literal>. </para> <para> <literal>normalize(U&'\0061\0308bc', NFC)</literal> <returnvalue>U&'\00E4bc'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>octet_length</primary> </indexterm> <function>octet_length</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bytes in the string. </para> <para> <literal>octet_length('josé')</literal> <returnvalue>5</returnvalue> (if server encoding is UTF8) </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>octet_length</primary> </indexterm> <function>octet_length</function> ( <type>character</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bytes in the string. Since this version of the function accepts type <type>character</type> directly, it will not strip trailing spaces. </para> <para> <literal>octet_length('abc '::character(4))</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>overlay</primary> </indexterm> <function>overlay</function> ( <parameter>string</parameter> <type>text</type> <literal>PLACING</li <returnvalue>text</returnvalue> </para> <para> Replaces the substring of <parameter>string</parameter> that starts at the <parameter>start</parameter>'th character and extends for <parameter>count</parameter> characters with <parameter>newsubstring</parameter>. If <parameter>count</parameter> is omitted, it defaults to the length of <parameter>newsubstring</parameter>. </para> <para> <literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal> <returnvalue>Thomas</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>position</primary> </indexterm> <function>position</function> ( <parameter>substring</parameter> <type>text</type> <literal>IN</lit <returnvalue>integer</returnvalue> </para> <para> Returns first starting index of the specified <parameter>substring</parameter> within <parameter>string</parameter>, or zero if it's not present. </para> <para> <literal>position('om' in 'Thomas')</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>rpad</primary> </indexterm> <function>rpad</function> ( <parameter>string</parameter> <type>text</type>, <parameter>length</parameter> <type>integer</type> <optional>, <parameter>fill</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Extends the <parameter>string</parameter> to length <parameter>length</parameter> by appending the characters <parameter>fill</parameter> (a space by default). If the <parameter>string</parameter> is already longer than <parameter>length</parameter> then it is truncated. </para> <para> <literal>rpad('hi', 5, 'xy')</literal> <returnvalue>hixyx</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>rtrim</primary> </indexterm> <function>rtrim</function> ( <parameter>string</parameter> <type>text</type> <optional>, <parameter>characters</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Removes the longest string containing only characters in <parameter>characters</parameter> (a space by default) from the end of <parameter>string</parameter>. </para> <para> <literal>rtrim('testxxzx', 'xyz')</literal> <returnvalue>test</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>substring</primary> </indexterm> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <optional> <literal> <returnvalue>text</returnvalue> </para> <para> Extracts the substring of <parameter>string</parameter> starting at the <parameter>start</parameter>'th character if that is specified, and stopping after <parameter>count</parameter> characters if that is specified. Provide at least one of <parameter>start</parameter> and <parameter>count</parameter>. </para> <para> <literal>substring('Thomas' from 2 for 3)</literal> <returnvalue>hom</returnvalue> </para> <para> <literal>substring('Thomas' from 3)</literal> <returnvalue>omas</returnvalue> </para> <para> <literal>substring('Thomas' for 2)</literal> <returnvalue>Th</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</lit <returnvalue>text</returnvalue> </para> <para> Extracts the first substring matching POSIX regular expression; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>substring('Thomas' from '...$')</literal> <returnvalue>mas</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>SIMILAR</ <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</lit <returnvalue>text</returnvalue> </para> <para> Extracts the first substring matching <acronym>SQL</acronym> regular expression; see <xref linkend="functions-similarto-regexp"/>. The first form has been specified since SQL:2003; the second form was only in SQL:1999 and should be considered obsolete. </para> <para> <literal>substring('Thomas' similar '%#"o_a#"_' escape '#')</literal> <returnvalue>oma</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>trim</primary> </indexterm> <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <lit <optional> <parameter>characters</parameter> <type>text</type> </optional> <literal>FROM</literal> <parameter>string</parameter> <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Removes the longest string containing only characters in <parameter>characters</parameter> (a space by default) from the start, end, or both ends (<literal>BOTH</literal> is the default) of <parameter>string</parameter>. </para> <para> <literal>trim(both 'xyz' from 'yxTomxx')</literal> <returnvalue>Tom</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <lit <parameter>string</parameter> <type>text</type> <optional>, <parameter>characters</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> This is a non-standard syntax for <function>trim()</function>. </para> <para> <literal>trim(both from 'yxTomxx', 'xyz')</literal> <returnvalue>Tom</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>unicode_assigned</primary> </indexterm> <function>unicode_assigned</function> ( <type>text</type> ) <returnvalue>boolean</returnvalue> </para> <para> Returns <literal>true</literal> if all characters in the string are assigned Unicode codepoints; <literal>false</literal> otherwise. This function can only be used when the server encoding is <literal>UTF8</literal>. </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>upper</primary> </indexterm> <function>upper</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the string to all upper case, according to the rules of the database's locale. </para> <para> <literal>upper('tom')</literal> <returnvalue>TOM</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> Additional string manipulation functions and operators are available and are listed in <xref linkend="functions-string-other"/>. (Some of these are used internally to implement the <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql"/>.) There are also pattern-matching operators, which are described in <xref linkend="functions-matching"/>, and operators for full-text search, which are described in <xref linkend="textsearch"/>. </para> <table id="functions-string-other"> <title>Other String Functions and Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function/Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>character string</primary> <secondary>prefix test</secondary> </indexterm> <type>text</type> <literal>^@</literal> <type>text</type> <returnvalue>boolean</returnvalue> </para> <para> Returns true if the first string starts with the second string (equivalent to the <function>starts_with()</function> function). </para> <para> <literal>'alphabet' ^@ 'alph'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ascii</primary> </indexterm> <function>ascii</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the numeric code of the first character of the argument. In <acronym>UTF8</acronym> encoding, returns the Unicode code point of the character. In other multibyte encodings, the argument must be an <acronym>ASCII</acronym> character. </para> <para> <literal>ascii('x')</literal> <returnvalue>120</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>chr</primary> </indexterm> <function>chr</function> ( <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the character with the given code. In <acronym>UTF8</acronym> encoding the argument is treated as a Unicode code point. In other multibyte encodings the argument must designate an <acronym>ASCII</acronym> character. <literal>chr(0)</literal> is disallowed because text data types cannot store that character. </para> <para> <literal>chr(65)</literal> <returnvalue>A</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>concat</primary> </indexterm> <function>concat</function> ( <parameter>val1</parameter> <type>"any"</type> <optional>, <parameter>val2</parameter> <type>"any"</type> <optional>, ...</optional> </optional> ) <returnvalue>text</returnvalue> </para> <para> Concatenates the text representations of all the arguments. NULL arguments are ignored. </para> <para> <literal>concat('abcde', 2, NULL, 22)</literal> <returnvalue>abcde222</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>concat_ws</primary> </indexterm> <function>concat_ws</function> ( <parameter>sep</parameter> <type>text</type>, <parameter>val1</parameter> <type>"any"</type> <optional>, <parameter>val2</parameter> <type>"any"</type> <optional>, ...</optional> </optional> ) <returnvalue>text</returnvalue> </para> <para> Concatenates all but the first argument, with separators. The first argument is used as the separator string, and should not be NULL. Other NULL arguments are ignored. </para> <para> <literal>concat_ws(',', 'abcde', 2, NULL, 22)</literal> <returnvalue>abcde,2,22</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>format</primary> </indexterm> <function>format</function> ( <parameter>formatstr</parameter> <type>text</type> <optional>, <parameter>formatarg</parameter> <type>"any"</type> <optional>, ...</optional> </optiona <returnvalue>text</returnvalue> </para> <para> Formats arguments according to a format string; see <xref linkend="functions-string-format"/>. This function is similar to the C function <function>sprintf</function>. </para> <para> <literal>format('Hello %s, %1$s', 'World')</literal> <returnvalue>Hello World, World</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>initcap</primary> </indexterm> <function>initcap</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the first letter of each word to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters. </para> <para> <literal>initcap('hi THOMAS')</literal> <returnvalue>Hi Thomas</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>casefold</primary> </indexterm> <function>casefold</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Performs case folding of the input string according to the collation. Case folding is similar to case conversion, but the purpose of case folding is to facilitate case-insensitive matching of strings, whereas the purpose of case conversion is to convert to a particular cased form. This function can only be used when the server encoding is <literal>UTF8</literal>. </para> <para> Ordinarily, case folding simply converts to lowercase, but there may be exceptions depending on the collation. For instance, some characters have more than two lowercase variants, or fold to uppercase. </para> <para> Case folding may change the length of the string. For instance, in the <literal>PG_UNICODE_FAST</literal> collation, <literal>ß</literal> (U+00DF) folds to <literal>ss</literal>. </para> <para> <function>casefold</function> can be used for Unicode Default Caseless Matching. It does not always preserve the normalized form of the input string (see <xref linkend="function-normalize"/>). </para> <para> The <literal>libc</literal> provider doesn't support case folding, so <function>casefold</function> is identical to <xref linkend="function-lower"/>. </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>left</primary> </indexterm> <function>left</function> ( <parameter>string</parameter> <type>text</type>, <parameter>n</parameter> <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para> Returns first <parameter>n</parameter> characters in the string, or when <parameter>n</parameter> is negative, returns all but last |<parameter>n</parameter>| characters. </para> <para> <literal>left('abcde', 2)</literal> <returnvalue>ab</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>length</primary> </indexterm> <function>length</function> ( <type>text</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of characters in the string. </para> <para> <literal>length('jose')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>md5</primary> </indexterm> <function>md5</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Computes the MD5 <link linkend="functions-hash-note">hash</link> of the argument, with the result written in hexadecimal. </para> <para> <literal>md5('abc')</literal> <returnvalue>900150983cd24fb0&zwsp;d6963f7d28e17f72</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>parse_ident</primary> </indexterm> <function>parse_ident</function> ( <parameter>qualified_identifier</parameter> <type>text</typ <optional>, <parameter>strict_mode</parameter> <type>boolean</type> <literal>DEFAULT</literal> <lit <returnvalue>text[]</returnvalue> </para> <para> Splits <parameter>qualified_identifier</parameter> into an array of identifiers, removing any quoting of individual identifiers. By default, extra characters after the last identifier are considered an error; but if the second parameter is <literal>false</literal>, then such extra characters are ignored. (This behavior is useful for parsing names for objects like functions.) Note that this function does not truncate over-length identifiers. If you want truncation you can cast the result to <type>name[]</type>. </para> <para> <literal>parse_ident('"SomeSchema".someTable')</literal> <returnvalue>{SomeSchema,sometable}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pg_client_encoding</primary> </indexterm> <function>pg_client_encoding</function> ( ) <returnvalue>name</returnvalue> </para> <para> Returns current client encoding name. </para> <para> <literal>pg_client_encoding()</literal> <returnvalue>UTF8</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>quote_ident</primary> </indexterm> <function>quote_ident</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the given string suitably quoted to be used as an identifier in an <acronym>SQL</acronym> statement string. Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled. See also <xref linkend="plpgsql-quote-literal-example"/>. </para> <para> <literal>quote_ident('Foo bar')</literal> <returnvalue>"Foo bar"</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>quote_literal</primary> </indexterm> <function>quote_literal</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the given string suitably quoted to be used as a string literal in an <acronym>SQL</acronym> statement string. Embedded single-quotes and backslashes are properly doubled. Note that <function>quote_literal</function> returns null on null input; if the argument might be null, <function>quote_nullable</function> is often more suitable. See also <xref linkend="plpgsql-quote-literal-example"/>. </para> <para> <literal>quote_literal(E'O\'Reilly')</literal> <returnvalue>'O''Reilly'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>quote_literal</function> ( <type>anyelement</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the given value to text and then quotes it as a literal. Embedded single-quotes and backslashes are properly doubled. </para> <para> <literal>quote_literal(42.5)</literal> <returnvalue>'42.5'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>quote_nullable</primary> </indexterm> <function>quote_nullable</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the given string suitably quoted to be used as a string literal in an <acronym>SQL</acronym> statement string; or, if the argument is null, returns <literal>NULL</literal>. Embedded single-quotes and backslashes are properly doubled. See also <xref linkend="plpgsql-quote-literal-example"/>. </para> <para> <literal>quote_nullable(NULL)</literal> <returnvalue>NULL</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>quote_nullable</function> ( <type>anyelement</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the given value to text and then quotes it as a literal; or, if the argument is null, returns <literal>NULL</literal>. Embedded single-quotes and backslashes are properly doubled. </para> <para> <literal>quote_nullable(42.5)</literal> <returnvalue>'42.5'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_count</primary> </indexterm> <function>regexp_count</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pa <optional>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> </optional> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of times the POSIX regular expression <parameter>pattern</parameter> matches in the <parameter>string</parameter>; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_count('123456789012', '\d\d\d', 2)</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_instr</primary> </indexterm> <function>regexp_instr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pa <optional>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>N</parameter> <type>integer</type> <optional>, <parameter>endoption</parameter> <type>integer</type> <optional>, <parameter>flags</parameter> <type>text</type> <optional>, <parameter>subexpr</parameter> <type>integer</type> </optional> </optional> </optional> </o <returnvalue>integer</returnvalue> </para> <para> Returns the position within <parameter>string</parameter> where the <parameter>N</parameter>'th match of the POSIX regular expression <parameter>pattern</parameter> occurs, or zero if there is no such match; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i')</literal> <returnvalue>3</returnvalue> </para> <para> <literal>regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i', 2)</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_like</primary> </indexterm> <function>regexp_like</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pat <optional>, <parameter>flags</parameter> <type>text</type> </optional> ) <returnvalue>boolean</returnvalue> </para> <para> Checks whether a match of the POSIX regular expression <parameter>pattern</parameter> occurs within <parameter>string</parameter>; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_like('Hello World', 'world$', 'i')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_match</primary> </indexterm> <function>regexp_match</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pa <returnvalue>text[]</returnvalue> </para> <para> Returns substrings within the first match of the POSIX regular expression <parameter>pattern</parameter> to the <parameter>string</parameter>; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_match('foobarbequebaz', '(bar)(beque)')</literal> <returnvalue>{bar,beque}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_matches</primary> </indexterm> <function>regexp_matches</function> ( <parameter>string</parameter> <type>text</type>, <parameter> <returnvalue>setof text[]</returnvalue> </para> <para> Returns substrings within the first match of the POSIX regular expression <parameter>pattern</parameter> to the <parameter>string</parameter>, or substrings within all such matches if the <literal>g</literal> flag is used; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal> <returnvalue></returnvalue> <programlisting> {bar} {baz} </programlisting> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_replace</primary> </indexterm> <function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter> <optional>, <parameter>flags</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Replaces the substring that is the first match to the POSIX regular expression <parameter>pattern</parameter>, or all such matches if the <literal>g</literal> flag is used; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal> <returnvalue>ThM</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter> <parameter>start</parameter> <type>integer</type> <optional>, <parameter>N</parameter> <type>integer</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> </optional> ) <returnvalue>text</returnvalue> </para> <para> Replaces the substring that is the <parameter>N</parameter>'th match to the POSIX regular expression <parameter>pattern</parameter>, or all such matches if <parameter>N</parameter> is zero, with the search beginning at the <parameter>start</parameter>'th character of <parameter>string</parameter>. If <parameter>N</parameter> is omitted, it defaults to 1. See <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_replace('Thomas', '.', 'X', 3, 2)</literal> <returnvalue>ThoXas</returnvalue> </para> <para> <literal>regexp_replace(string=>'hello world', pattern=>'l', replacement=>'XX', start=>1, " <returnvalue>helXXo world</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_split_to_array</primary> </indexterm> <function>regexp_split_to_array</function> ( <parameter>string</parameter> <type>text</type>, <pa <returnvalue>text[]</returnvalue> </para> <para> Splits <parameter>string</parameter> using a POSIX regular expression as the delimiter, producing an array of results; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_split_to_array('hello world', '\s+')</literal> <returnvalue>{hello,world}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_split_to_table</primary> </indexterm> <function>regexp_split_to_table</function> ( <parameter>string</parameter> <type>text</type>, <pa <returnvalue>setof text</returnvalue> </para> <para> Splits <parameter>string</parameter> using a POSIX regular expression as the delimiter, producing a set of results; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_split_to_table('hello world', '\s+')</literal> <returnvalue></returnvalue> <programlisting> hello world </programlisting> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>regexp_substr</primary> </indexterm> <function>regexp_substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>p <optional>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>N</parameter> <type>integer</type> <optional>, <parameter>flags</parameter> <type>text</type> <optional>, <parameter>subexpr</parameter> <type>integer</type> </optional> </optional> </optional> </o <returnvalue>text</returnvalue> </para> <para> Returns the substring within <parameter>string</parameter> that matches the <parameter>N</parameter>'th occurrence of the POSIX regular expression <parameter>pattern</parameter>, or <literal>NULL</literal> if there is no such match; see <xref linkend="functions-posix-regexp"/>. </para> <para> <literal>regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i')</literal> <returnvalue>CDEF</returnvalue> </para> <para> <literal>regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i', 2)</literal> <returnvalue>EF</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>repeat</primary> </indexterm> <function>repeat</function> ( <parameter>string</parameter> <type>text</type>, <parameter>number</p <returnvalue>text</returnvalue> </para> <para> Repeats <parameter>string</parameter> the specified <parameter>number</parameter> of times. </para> <para> <literal>repeat('Pg', 4)</literal> <returnvalue>PgPgPgPg</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>replace</primary> </indexterm> <function>replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter>from</parameter> <type>text</type>, <parameter>to</parameter> <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Replaces all occurrences in <parameter>string</parameter> of substring <parameter>from</parameter> with substring <parameter>to</parameter>. </para> <para> <literal>replace('abcdefabcdef', 'cd', 'XX')</literal> <returnvalue>abXXefabXXef</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>reverse</primary> </indexterm> <function>reverse</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Reverses the order of the characters in the string. </para> <para> <literal>reverse('abcde')</literal> <returnvalue>edcba</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>right</primary> </indexterm> <function>right</function> ( <parameter>string</parameter> <type>text</type>, <parameter>n</parameter> <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para> Returns last <parameter>n</parameter> characters in the string, or when <parameter>n</parameter> is negative, returns all but first |<parameter>n</parameter>| characters. </para> <para> <literal>right('abcde', 2)</literal> <returnvalue>de</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>split_part</primary> </indexterm> <function>split_part</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type>, <parameter>n</parameter> <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para> Splits <parameter>string</parameter> at occurrences of <parameter>delimiter</parameter> and returns the <parameter>n</parameter>'th field (counting from one), or when <parameter>n</parameter> is negative, returns the |<parameter>n</parameter>|'th-from-last field. </para> <para> <literal>split_part('abc~@~def~@~ghi', '~@~', 2)</literal> <returnvalue>def</returnvalue> </para> <para> <literal>split_part('abc,def,ghi,jkl', ',', -2)</literal> <returnvalue>ghi</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>starts_with</primary> </indexterm> <function>starts_with</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pre <returnvalue>boolean</returnvalue> </para> <para> Returns true if <parameter>string</parameter> starts with <parameter>prefix</parameter>. </para> <para> <literal>starts_with('alphabet', 'alph')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-string-to-array"> <primary>string_to_array</primary> </indexterm> <function>string_to_array</function> ( <parameter>string</parameter> <type>text</type>, <paramete <returnvalue>text[]</returnvalue> </para> <para> Splits the <parameter>string</parameter> at occurrences of <parameter>delimiter</parameter> and forms the resulting fields into a <type>text</type> array. If <parameter>delimiter</parameter> is <literal>NULL</literal>, each character in the <parameter>string</parameter> will become a separate element in the array. If <parameter>delimiter</parameter> is an empty string, then the <parameter>string</parameter> is treated as a single field. If <parameter>null_string</parameter> is supplied and is not <literal>NULL</literal>, fields matching that string are replaced by <literal>NULL</literal>. See also <link linkend="function-array-to-string"><function>array_to_string</function></li </para> <para> <literal>string_to_array('xx~~yy~~zz', '~~', 'yy')</literal> <returnvalue>{xx,NULL,zz}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>string_to_table</primary> </indexterm> <function>string_to_table</function> ( <parameter>string</parameter> <type>text</type>, <paramete <returnvalue>setof text</returnvalue> </para> <para> Splits the <parameter>string</parameter> at occurrences of <parameter>delimiter</parameter> and returns the resulting fields as a set of <type>text</type> rows. If <parameter>delimiter</parameter> is <literal>NULL</literal>, each character in the <parameter>string</parameter> will become a separate row of the result. If <parameter>delimiter</parameter> is an empty string, then the <parameter>string</parameter> is treated as a single field. If <parameter>null_string</parameter> is supplied and is not <literal>NULL</literal>, fields matching that string are replaced by <literal>NULL</literal>. </para> <para> <literal>string_to_table('xx~^~yy~^~zz', '~^~', 'yy')</literal> <returnvalue></returnvalue> <programlisting> xx NULL zz </programlisting> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>strpos</primary> </indexterm> <function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substrin <returnvalue>integer</returnvalue> </para> <para> Returns first starting index of the specified <parameter>substring</parameter> within <parameter>string</parameter>, or zero if it's not present. (Same as <literal>position(<parameter>substring</parameter> in <parameter>string</parameter>)</literal>, but note the reversed argument order.) </para> <para> <literal>strpos('high', 'ig')</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>substr</primary> </indexterm> <function>substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>start</pa <returnvalue>text</returnvalue> </para> <para> Extracts the substring of <parameter>string</parameter> starting at the <parameter>start</parameter>'th character, and extending for <parameter>count</parameter> characters if that is specified. (Same as <literal>substring(<parameter>string</parameter> from <parameter>start</parameter> for <parameter>count</parameter>)</literal>.) </para> <para> <literal>substr('alphabet', 3)</literal> <returnvalue>phabet</returnvalue> </para> <para> <literal>substr('alphabet', 3, 2)</literal> <returnvalue>ph</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_ascii</primary> </indexterm> <function>to_ascii</function> ( <parameter>string</parameter> <type>text</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_ascii</function> ( <parameter>string</parameter> <type>text</type>, <parameter>encoding</parameter> <type>name</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_ascii</function> ( <parameter>string</parameter> <type>text</type>, <parameter>encoding</parameter> <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para> Converts <parameter>string</parameter> to <acronym>ASCII</acronym> from another encoding, which may be identified by name or number. If <parameter>encoding</parameter> is omitted the database encoding is assumed (which in practice is the only useful case). The conversion consists primarily of dropping accents. Conversion is only supported from <literal>LATIN1</literal>, <literal>LATIN2</literal>, <literal>LATIN9</literal>, and <literal>WIN1250</literal> encodings. (See the <xref linkend="unaccent"/> module for another, more flexible solution.) </para> <para> <literal>to_ascii('Karél')</literal> <returnvalue>Karel</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_bin</primary> </indexterm> <function>to_bin</function> ( <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_bin</function> ( <type>bigint</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the number to its equivalent two's complement binary representation. </para> <para> <literal>to_bin(2147483647)</literal> <returnvalue>1111111111111111111111111111111</returnvalue> </para> <para> <literal>to_bin(-1234)</literal> <returnvalue>11111111111111111111101100101110</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_hex</primary> </indexterm> <function>to_hex</function> ( <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_hex</function> ( <type>bigint</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the number to its equivalent two's complement hexadecimal representation. </para> <para> <literal>to_hex(2147483647)</literal> <returnvalue>7fffffff</returnvalue> </para> <para> <literal>to_hex(-1234)</literal> <returnvalue>fffffb2e</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_oct</primary> </indexterm> <function>to_oct</function> ( <type>integer</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_oct</function> ( <type>bigint</type> ) <returnvalue>text</returnvalue> </para> <para> Converts the number to its equivalent two's complement octal representation. </para> <para> <literal>to_oct(2147483647)</literal> <returnvalue>17777777777</returnvalue> </para> <para> <literal>to_oct(-1234)</literal> <returnvalue>37777775456</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>translate</primary> </indexterm> <function>translate</function> ( <parameter>string</parameter> <type>text</type>, <parameter>from</parameter> <type>text</type>, <parameter>to</parameter> <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Replaces each character in <parameter>string</parameter> that matches a character in the <parameter>from</parameter> set with the corresponding character in the <parameter>to</parameter> set. If <parameter>from</parameter> is longer than <parameter>to</parameter>, occurrences of the extra characters in <parameter>from</parameter> are deleted. </para> <para> <literal>translate('12345', '143', 'ax')</literal> <returnvalue>a2x5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>unistr</primary> </indexterm> <function>unistr</function> ( <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Evaluate escaped Unicode characters in the argument. Unicode characters can be specified as <literal>\<replaceable>XXXX</replaceable></literal> (4 hexadecimal digits), <literal>\+<replaceable>XXXXXX</replaceable></literal> (6 hexadecimal digits), <literal>\u<replaceable>XXXX</replaceable></literal> (4 hexadecimal digits), or <literal>\U<replaceable>XXXXXXXX</replaceable></literal> (8 hexadecimal digits). To specify a backslash, write two backslashes. All other characters are taken literally. </para> <para> If the server encoding is not UTF-8, the Unicode code point identified by one of these escape sequences is converted to the actual server encoding; an error is reported if that's not possible. </para> <para> This function provides a (non-standard) alternative to string constants with Unicode escapes (see <xref linkend="sql-syntax-strings-uescape"/>). </para> <para> <literal>unistr('d\0061t\+000061')</literal> <returnvalue>data</returnvalue> </para> <para> <literal>unistr('d\u0061t\U00000061')</literal> <returnvalue>data</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> The <function>concat</function>, <function>concat_ws</function> and <function>format</function> functions are variadic, so it is possible to pass the values to be concatenated or formatted as an array marked with the <literal>VARIADIC</literal> keyword (see <xref linkend="xfunc-sql-variadic-functions"/>). The array's elements are treated as if they were separate ordinary arguments to the function. If the variadic array argument is NULL, <function>concat</function> and <function>concat_ws</function> return NULL, but <function>format</function> treats a NULL as a zero-element array. </para> <para> See also the aggregate function <function>string_agg</function> in <xref linkend="functions-aggregate"/>, and the functions for converting between strings and the <type>bytea</type> type in <xref linkend="functions-binarystring-conversions"/>. </para> <sect2 id="functions-string-format"> <title><function>format</function></title> <indexterm> <primary>format</primary> </indexterm> <para> The function <function>format</function> produces output formatted according to a format string, in a style similar to the C function <function>sprintf</function>. </para> <para> <synopsis> <function>format</function>(<parameter>formatstr</parameter> <type>text</type> <optional>, <parame </synopsis> <parameter>formatstr</parameter> is a format string that specifies how the result should be formatted. Text in the format string is copied directly to the result, except where <firstterm>format specifiers</firstterm> are used. Format specifiers act as placeholders in the string, defining how subsequent function arguments should be formatted and inserted into the result. Each <parameter>formatarg</parameter> argument is converted to text according to the usual output rules for its data type, and then formatted and inserted into the result string according to the format specifier(s). </para> <para> Format specifiers are introduced by a <literal>%</literal> character and have the form <synopsis> %[<parameter>position</parameter>][<parameter>flags</parameter>][<parameter>width</paramete </synopsis> where the component fields are: <variablelist> <varlistentry> <term><parameter>position</parameter> (optional)</term> <listitem> <para> A string of the form <literal><parameter>n</parameter>$</literal> where <parameter>n</parameter> is the index of the argument to print. Index 1 means the first argument after <parameter>formatstr</parameter>. If the <parameter>position</parameter> is omitted, the default is to use the next argument in sequence. </para> </listitem> </varlistentry> <varlistentry> <term><parameter>flags</parameter> (optional)</term> <listitem> <para> Additional options controlling how the format specifier's output is formatted. Currently the only supported flag is a minus sign (<literal>-</literal>) which will cause the format specifier's output to be left-justified. This has no effect unless the <parameter>width</parameter> field is also specified. </para> </listitem> </varlistentry> <varlistentry> <term><parameter>width</parameter> (optional)</term> <listitem> <para> Specifies the <emphasis>minimum</emphasis> number of characters to use to display the format specifier's output. The output is padded on the left or right (depending on the <literal>-</literal> flag) with spaces as needed to fill the width. A too-small width does not cause truncation of the output, but is simply ignored. The width may be specified using any of the following: a positive integer; an asterisk (<literal>*</literal>) to use the next function argument as the width; or a string of the form <literal>*<parameter>n</parameter>$</literal> to use the <parameter>n</parameter>th function argument as the width. </para> <para> If the width comes from a function argument, that argument is consumed before the argument that is used for the format specifier's value. If the width argument is negative, the result is left aligned (as if the <literal>-</literal> flag had been specified) within a field of length <function>abs</function>(<parameter>width</parameter>). </para> </listitem> </varlistentry> <varlistentry> <term><parameter>type</parameter> (required)</term> <listitem> <para> The type of format conversion to use to produce the format specifier's output. The following types are supported: <itemizedlist> <listitem> <para> <literal>s</literal> formats the argument value as a simple string. A null value is treated as an empty string. </para> </listitem> <listitem> <para> <literal>I</literal> treats the argument value as an SQL identifier, double-quoting it if necessary. It is an error for the value to be null (equivalent to <function>quote_ident</function>). </para> </listitem> <listitem> <para> <literal>L</literal> quotes the argument value as an SQL literal. A null value is displayed as the string <literal>NULL</literal>, without quotes (equivalent to <function>quote_nullable</function>). </para> </listitem> </itemizedlist> </para> </listitem> </varlistentry> </variablelist> </para> <para> In addition to the format specifiers described above, the special sequence <literal>%%</literal> may be used to output a literal <literal>%</literal> character. </para> <para> Here are some examples of the basic format conversions: <screen> SELECT format('Hello %s', 'World'); <lineannotation>Result: </lineannotation><computeroutput>Hello World</computeroutput> SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three'); <lineannotation>Result: </lineannotation><computeroutput>Testing one, two, three, %</compute SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly'); <lineannotation>Result: </lineannotation><computeroutput>INSERT INTO "Foo bar" VALUES('O''R SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files'); <lineannotation>Result: </lineannotation><computeroutput>INSERT INTO locations VALUES('C:\ </screen> </para> <para> Here are examples using <parameter>width</parameter> fields and the <literal>-</literal> flag: <screen> SELECT format('|%10s|', 'foo'); <lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput> SELECT format('|%-10s|', 'foo'); <lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput> SELECT format('|%*s|', 10, 'foo'); <lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput> SELECT format('|%*s|', -10, 'foo'); <lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput> SELECT format('|%-*s|', 10, 'foo'); <lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput> SELECT format('|%-*s|', -10, 'foo'); <lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput> </screen> </para> <para> These examples show use of <parameter>position</parameter> fields: <screen> SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three'); <lineannotation>Result: </lineannotation><computeroutput>Testing three, two, one</computero SELECT format('|%*2$s|', 'foo', 10, 'bar'); <lineannotation>Result: </lineannotation><computeroutput>| bar|</computeroutput> SELECT format('|%1$*2$s|', 'foo', 10, 'bar'); <lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput> </screen> </para> <para> Unlike the standard C function <function>sprintf</function>, <productname>PostgreSQL</productname>'s <function>format</function> function allows format specifiers with and without <parameter>position</parameter> fields to be mixed in the same format string. A format specifier without a <parameter>position</parameter> field always uses the next argument after the last argument consumed. In addition, the <function>format</function> function does not require all function arguments to be used in the format string. For example: <screen> SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); <lineannotation>Result: </lineannotation><computeroutput>Testing three, two, three</compute </screen> </para> <para> The <literal>%I</literal> and <literal>%L</literal> format specifiers are particularly useful for safely constructing dynamic SQL statements. See <xref linkend="plpgsql-quote-literal-example"/>. </para> </sect2> </sect1> <sect1 id="functions-binarystring"> <title>Binary String Functions and Operators</title> <indexterm zone="functions-binarystring"> <primary>binary data</primary> <secondary>functions</secondary> </indexterm> <para> This section describes functions and operators for examining and manipulating binary strings, that is values of type <type>bytea</type>. Many of these are equivalent, in purpose and syntax, to the text-string functions described in the previous section. </para> <para> <acronym>SQL</acronym> defines some string functions that use key words, rather than commas, to separate arguments. Details are in <xref linkend="functions-binarystring-sql"/>. <productname>PostgreSQL</productname> also provides versions of these functions that use the regular function invocation syntax (see <xref linkend="functions-binarystring-other"/>). </para> <table id="functions-binarystring-sql"> <title><acronym>SQL</acronym> Binary String Functions and Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function/Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>binary string</primary> <secondary>concatenation</secondary> </indexterm> <type>bytea</type> <literal>||</literal> <type>bytea</type> <returnvalue>bytea</returnvalue> </para> <para> Concatenates the two binary strings. </para> <para> <literal>'\x123456'::bytea || '\x789a00bcde'::bytea</literal> <returnvalue>\x123456789a00bcde</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bit_length</primary> </indexterm> <function>bit_length</function> ( <type>bytea</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bits in the binary string (8 times the <function>octet_length</function>). </para> <para> <literal>bit_length('\x123456'::bytea)</literal> <returnvalue>24</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>btrim</primary> </indexterm> <function>btrim</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>bytesremoved</parameter> <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start and end of <parameter>bytes</parameter>. </para> <para> <literal>btrim('\x1234567890'::bytea, '\x9012'::bytea)</literal> <returnvalue>\x345678</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ltrim</primary> </indexterm> <function>ltrim</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>bytesremoved</parameter> <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start of <parameter>bytes</parameter>. </para> <para> <literal>ltrim('\x1234567890'::bytea, '\x9012'::bytea)</literal> <returnvalue>\x34567890</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>octet_length</primary> </indexterm> <function>octet_length</function> ( <type>bytea</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bytes in the binary string. </para> <para> <literal>octet_length('\x123456'::bytea)</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>overlay</primary> </indexterm> <function>overlay</function> ( <parameter>bytes</parameter> <type>bytea</type> <literal>PLACING</li <returnvalue>bytea</returnvalue> </para> <para> Replaces the substring of <parameter>bytes</parameter> that starts at the <parameter>start</parameter>'th byte and extends for <parameter>count</parameter> bytes with <parameter>newsubstring</parameter>. If <parameter>count</parameter> is omitted, it defaults to the length of <parameter>newsubstring</parameter>. </para> <para> <literal>overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)</literal> <returnvalue>\x12020390</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>position</primary> </indexterm> <function>position</function> ( <parameter>substring</parameter> <type>bytea</type> <literal>IN</li <returnvalue>integer</returnvalue> </para> <para> Returns first starting index of the specified <parameter>substring</parameter> within <parameter>bytes</parameter>, or zero if it's not present. </para> <para> <literal>position('\x5678'::bytea in '\x1234567890'::bytea)</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>rtrim</primary> </indexterm> <function>rtrim</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>bytesremoved</parameter> <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the end of <parameter>bytes</parameter>. </para> <para> <literal>rtrim('\x1234567890'::bytea, '\x9012'::bytea)</literal> <returnvalue>\x12345678</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>substring</primary> </indexterm> <function>substring</function> ( <parameter>bytes</parameter> <type>bytea</type> <optional> <literal> <returnvalue>bytea</returnvalue> </para> <para> Extracts the substring of <parameter>bytes</parameter> starting at the <parameter>start</parameter>'th byte if that is specified, and stopping after <parameter>count</parameter> bytes if that is specified. Provide at least one of <parameter>start</parameter> and <parameter>count</parameter>. </para> <para> <literal>substring('\x1234567890'::bytea from 3 for 2)</literal> <returnvalue>\x5678</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>trim</primary> </indexterm> <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <lit <parameter>bytesremoved</parameter> <type>bytea</type> <literal>FROM</literal> <parameter>bytes</parameter> <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Removes the longest string containing only bytes appearing in <parameter>bytesremoved</parameter> from the start, end, or both ends (<literal>BOTH</literal> is the default) of <parameter>bytes</parameter>. </para> <para> <literal>trim('\x9012'::bytea from '\x1234567890'::bytea)</literal> <returnvalue>\x345678</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <lit <parameter>bytes</parameter> <type>bytea</type>, <parameter>bytesremoved</parameter> <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> This is a non-standard syntax for <function>trim()</function>. </para> <para> <literal>trim(both from '\x1234567890'::bytea, '\x9012'::bytea)</literal> <returnvalue>\x345678</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> Additional binary string manipulation functions are available and are listed in <xref linkend="functions-binarystring-other"/>. Some of them are used internally to implement the <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-binarystring-sql"/>. </para> <table id="functions-binarystring-other"> <title>Other Binary String Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bit_count</primary> </indexterm> <indexterm> <primary>popcount</primary> <see>bit_count</see> </indexterm> <function>bit_count</function> ( <parameter>bytes</parameter> <type>bytea</type> ) <returnvalue>bigint</returnvalue> </para> <para> Returns the number of bits set in the binary string (also known as <quote>popcount</quote>). </para> <para> <literal>bit_count('\x1234567890'::bytea)</literal> <returnvalue>15</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>crc32</primary> </indexterm> <function>crc32</function> ( <type>bytea</type> ) <returnvalue>bigint</returnvalue> </para> <para> Computes the CRC-32 value of the binary string. </para> <para> <literal>crc32('abc'::bytea)</literal> <returnvalue>891568578</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>crc32c</primary> </indexterm> <function>crc32c</function> ( <type>bytea</type> ) <returnvalue>bigint</returnvalue> </para> <para> Computes the CRC-32C value of the binary string. </para> <para> <literal>crc32c('abc'::bytea)</literal> <returnvalue>910901175</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>get_bit</primary> </indexterm> <function>get_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>n</parameter> <type>bigint</type> ) <returnvalue>integer</returnvalue> </para> <para> Extracts <link linkend="functions-zerobased-note">n'th</link> bit from binary string. </para> <para> <literal>get_bit('\x1234567890'::bytea, 30)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>get_byte</primary> </indexterm> <function>get_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>n</parameter> <type>integer</type> ) <returnvalue>integer</returnvalue> </para> <para> Extracts <link linkend="functions-zerobased-note">n'th</link> byte from binary string. </para> <para> <literal>get_byte('\x1234567890'::bytea, 4)</literal> <returnvalue>144</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>length</primary> </indexterm> <indexterm> <primary>binary string</primary> <secondary>length</secondary> </indexterm> <indexterm> <primary>length</primary> <secondary sortas="binary string">of a binary string</secondary> <see>binary strings, length</see> </indexterm> <function>length</function> ( <type>bytea</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of bytes in the binary string. </para> <para> <literal>length('\x1234567890'::bytea)</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>length</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>encoding</parameter> <type>name</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of characters in the binary string, assuming that it is text in the given <parameter>encoding</parameter>. </para> <para> <literal>length('jose'::bytea, 'UTF8')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>md5</primary> </indexterm> <function>md5</function> ( <type>bytea</type> ) <returnvalue>text</returnvalue> </para> <para> Computes the MD5 <link linkend="functions-hash-note">hash</link> of the binary string, with the result written in hexadecimal. </para> <para> <literal>md5('Th\000omas'::bytea)</literal> <returnvalue>8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>reverse</primary> </indexterm> <function>reverse</function> ( <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Reverses the order of the bytes in the binary string. </para> <para> <literal>reverse('\xabcd'::bytea)</literal> <returnvalue>\xcdab</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>set_bit</primary> </indexterm> <function>set_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>n</parameter> <type>bigint</type>, <parameter>newvalue</parameter> <type>integer</type> ) <returnvalue>bytea</returnvalue> </para> <para> Sets <link linkend="functions-zerobased-note">n'th</link> bit in binary string to <parameter>newvalue</parameter>. </para> <para> <literal>set_bit('\x1234567890'::bytea, 30, 0)</literal> <returnvalue>\x1234563890</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>set_byte</primary> </indexterm> <function>set_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>n</parameter> <type>integer</type>, <parameter>newvalue</parameter> <type>integer</type> ) <returnvalue>bytea</returnvalue> </para> <para> Sets <link linkend="functions-zerobased-note">n'th</link> byte in binary string to <parameter>newvalue</parameter>. </para> <para> <literal>set_byte('\x1234567890'::bytea, 4, 64)</literal> <returnvalue>\x1234567840</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sha224</primary> </indexterm> <function>sha224</function> ( <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Computes the SHA-224 <link linkend="functions-hash-note">hash</link> of the binary string. </para> <para> <literal>sha224('abc'::bytea)</literal> <returnvalue>\x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7</returnvalu </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sha256</primary> </indexterm> <function>sha256</function> ( <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Computes the SHA-256 <link linkend="functions-hash-note">hash</link> of the binary string. </para> <para> <literal>sha256('abc'::bytea)</literal> <returnvalue>\xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad</re </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sha384</primary> </indexterm> <function>sha384</function> ( <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Computes the SHA-384 <link linkend="functions-hash-note">hash</link> of the binary string. </para> <para> <literal>sha384('abc'::bytea)</literal> <returnvalue>\xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;808 </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>sha512</primary> </indexterm> <function>sha512</function> ( <type>bytea</type> ) <returnvalue>bytea</returnvalue> </para> <para> Computes the SHA-512 <link linkend="functions-hash-note">hash</link> of the binary string. </para> <para> <literal>sha512('abc'::bytea)</literal> <returnvalue>\xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;219 </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>substr</primary> </indexterm> <function>substr</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>start</pa <returnvalue>bytea</returnvalue> </para> <para> Extracts the substring of <parameter>bytes</parameter> starting at the <parameter>start</parameter>'th byte, and extending for <parameter>count</parameter> bytes if that is specified. (Same as <literal>substring(<parameter>bytes</parameter> from <parameter>start</parameter> for <parameter>count</parameter>)</literal>.) </para> <para> <literal>substr('\x1234567890'::bytea, 3, 2)</literal> <returnvalue>\x5678</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para id="functions-zerobased-note"> Functions <function>get_byte</function> and <function>set_byte</function> number the first byte of a binary string as byte 0. Functions <function>get_bit</function> and <function>set_bit</function> number bits from the right within each byte; for example bit 0 is the least significant bit of the first byte, and bit 15 is the most significant bit of the second byte. </para> <para id="functions-hash-note"> For historical reasons, the function <function>md5</function> returns a hex-encoded value of type <type>text</type> whereas the SHA-2 functions return type <type>bytea</type>. Use the functions <link linkend="function-encode"><function>encode</function></link> and <link linkend="function-decode"><function>decode</function></link> to convert between the two. For example write <literal>encode(sha256('abc'), 'hex')</literal> to get a hex-encoded text representation, or <literal>decode(md5('abc'), 'hex')</literal> to get a <type>bytea</type> value. </para> <para> <indexterm> <primary>character string</primary> <secondary>converting to binary string</secondary> </indexterm> <indexterm> <primary>binary string</primary> <secondary>converting to character string</secondary> </indexterm> Functions for converting strings between different character sets (encodings), and for representing arbitrary binary data in textual form, are shown in <xref linkend="functions-binarystring-conversions"/>. For these functions, an argument or result of type <type>text</type> is expressed in the database's default encoding, while arguments or results of type <type>bytea</type> are in an encoding named by another argument. </para> <table id="functions-binarystring-conversions"> <title>Text/Binary String Conversion Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>convert</primary> </indexterm> <function>convert</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>src_encoding</parameter> <type>name</type>, <parameter>dest_encoding</parameter> <type>name</type> ) <returnvalue>bytea</returnvalue> </para> <para> Converts a binary string representing text in encoding <parameter>src_encoding</parameter> to a binary string in encoding <parameter>dest_encoding</parameter> (see <xref linkend="multibyte-conversions-supported"/> for available conversions). </para> <para> <literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal> <returnvalue>\x746578745f696e5f75746638</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>convert_from</primary> </indexterm> <function>convert_from</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>src_encoding</parameter> <type>name</type> ) <returnvalue>text</returnvalue> </para> <para> Converts a binary string representing text in encoding <parameter>src_encoding</parameter> to <type>text</type> in the database encoding (see <xref linkend="multibyte-conversions-supported"/> for available conversions). </para> <para> <literal>convert_from('text_in_utf8', 'UTF8')</literal> <returnvalue>text_in_utf8</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>convert_to</primary> </indexterm> <function>convert_to</function> ( <parameter>string</parameter> <type>text</type>, <parameter>dest_encoding</parameter> <type>name</type> ) <returnvalue>bytea</returnvalue> </para> <para> Converts a <type>text</type> string (in the database encoding) to a binary string encoded in encoding <parameter>dest_encoding</parameter> (see <xref linkend="multibyte-conversions-supported"/> for available conversions). </para> <para> <literal>convert_to('some_text', 'UTF8')</literal> <returnvalue>\x736f6d655f74657874</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-encode"> <primary>encode</primary> </indexterm> <function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>format</parameter> <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Encodes binary data into a textual representation; supported <parameter>format</parameter> values are: <link linkend="encode-format-base64"><literal>base64</literal></link>, <link linkend="encode-format-escape"><literal>escape</literal></link>, <link linkend="encode-format-hex"><literal>hex</literal></link>. </para> <para> <literal>encode('123\000\001', 'base64')</literal> <returnvalue>MTIzAAE=</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-decode"> <primary>decode</primary> </indexterm> <function>decode</function> ( <parameter>string</parameter> <type>text</type>, <parameter>format</parameter> <type>text</type> ) <returnvalue>bytea</returnvalue> </para> <para> Decodes binary data from a textual representation; supported <parameter>format</parameter> values are the same as for <function>encode</function>. </para> <para> <literal>decode('MTIzAAE=', 'base64')</literal> <returnvalue>\x3132330001</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> The <function>encode</function> and <function>decode</function> functions support the following textual formats: <variablelist> <varlistentry id="encode-format-base64"> <term>base64 <indexterm> <primary>base64 format</primary> </indexterm></term> <listitem> <para> The <literal>base64</literal> format is that of <ulink url="https://datatracker.ietf.org/doc/html/rfc2045#section-6.8">RFC 2045 Section 6.8</ulink>. As per the <acronym>RFC</acronym>, encoded lines are broken at 76 characters. However instead of the MIME CRLF end-of-line marker, only a newline is used for end-of-line. The <function>decode</function> function ignores carriage-return, newline, space, and tab characters. Otherwise, an error is raised when <function>decode</function> is supplied invalid base64 data — including when trailing padding is incorrect. </para> </listitem> </varlistentry> <varlistentry id="encode-format-escape"> <term>escape <indexterm> <primary>escape format</primary> </indexterm></term> <listitem> <para> The <literal>escape</literal> format converts zero bytes and bytes with the high bit set into octal escape sequences (<literal>\</literal><replaceable>nnn</replaceable>), and it doubles backslashes. Other byte values are represented literally. The <function>decode</function> function will raise an error if a backslash is not followed by either a second backslash or three octal digits; it accepts other byte values unchanged. </para> </listitem> </varlistentry> <varlistentry id="encode-format-hex"> <term>hex <indexterm> <primary>hex format</primary> </indexterm></term> <listitem> <para> The <literal>hex</literal> format represents each 4 bits of data as one hexadecimal digit, <literal>0</literal> through <literal>f</literal>, writing the higher-order digit of each byte first. The <function>encode</function> function outputs the <literal>a</literal>-<literal>f</literal> hex digits in lower case. Because the smallest unit of data is 8 bits, there are always an even number of characters returned by <function>encode</function>. The <function>decode</function> function accepts the <literal>a</literal>-<literal>f</literal> characters in either upper or lower case. An error is raised when <function>decode</function> is given invalid hex data — including when given an odd number of characters. </para> </listitem> </varlistentry> </variablelist> </para> <para> In addition, it is possible to cast integral values to and from type <type>bytea</type>. Casting an integer to <type>bytea</type> produces 2, 4, or 8 bytes, depending on the width of the integer type. The result is the two's complement representation of the integer, with the most significant byte first. Some examples: <programlisting> 1234::smallint::bytea <lineannotation>\x04d2</lineannotation> cast(1234 as bytea) <lineannotation>\x000004d2</lineannotation> cast(-1234 as bytea) <lineannotation>\xfffffb2e</lineannotation> '\x8000'::bytea::smallint <lineannotation>-32768</lineannotation> '\x8000'::bytea::integer <lineannotation>32768</lineannotation> </programlisting> Casting a <type>bytea</type> to an integer will raise an error if the length of the <type>bytea</type> exceeds the width of the integer type. </para> <para> See also the aggregate function <function>string_agg</function> in <xref linkend="functions-aggregate"/> and the large object functions in <xref linkend="lo-funcs"/>. </para> </sect1> <sect1 id="functions-bitstring"> <title>Bit String Functions and Operators</title> <indexterm zone="functions-bitstring"> <primary>bit strings</primary> <secondary>functions</secondary> </indexterm> <para> This section describes functions and operators for examining and manipulating bit strings, that is values of the types <type>bit</type> and <type>bit varying</type>. (While only type <type>bit</type> is mentioned in these tables, values of type <type>bit varying</type> can be used interchangeably.) Bit strings support the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/>, as well as the operators shown in <xref linkend="functions-bit-string-op-table"/>. </para> <table id="functions-bit-string-op-table"> <title>Bit String Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal>||</literal> <type>bit</type> <returnvalue>bit</returnvalue> </para> <para> Concatenation </para> <para> <literal>B'10001' || B'011'</literal> <returnvalue>10001011</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal>&</literal> <type>bit</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise AND (inputs must be of equal length) </para> <para> <literal>B'10001' & B'01101'</literal> <returnvalue>00001</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal>|</literal> <type>bit</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise OR (inputs must be of equal length) </para> <para> <literal>B'10001' | B'01101'</literal> <returnvalue>11101</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal>#</literal> <type>bit</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise exclusive OR (inputs must be of equal length) </para> <para> <literal>B'10001' # B'01101'</literal> <returnvalue>11100</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>~</literal> <type>bit</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise NOT </para> <para> <literal>~ B'10001'</literal> <returnvalue>01110</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal><<</literal> <type>integer</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise shift left (string length is preserved) </para> <para> <literal>B'10001' << 3</literal> <returnvalue>01000</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bit</type> <literal>>></literal> <type>integer</type> <returnvalue>bit</returnvalue> </para> <para> Bitwise shift right (string length is preserved) </para> <para> <literal>B'10001' >> 2</literal> <returnvalue>00100</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> Some of the functions available for binary strings are also available for bit strings, as shown in <xref linkend="functions-bit-string-table"/>. </para> <table id="functions-bit-string-table"> <title>Bit String Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bit_count</primary> </indexterm> <function>bit_count</function> ( <type>bit</type> ) <returnvalue>bigint</returnvalue> </para> <para> Returns the number of bits set in the bit string (also known as <quote>popcount</quote>). </para> <para> <literal>bit_count(B'10111')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bit_length</primary> </indexterm> <function>bit_length</function> ( <type>bit</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bits in the bit string. </para> <para> <literal>bit_length(B'10111')</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>length</primary> </indexterm> <indexterm> <primary>bit string</primary> <secondary>length</secondary> </indexterm> <function>length</function> ( <type>bit</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bits in the bit string. </para> <para> <literal>length(B'10111')</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>octet_length</primary> </indexterm> <function>octet_length</function> ( <type>bit</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns number of bytes in the bit string. </para> <para> <literal>octet_length(B'1011111011')</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>overlay</primary> </indexterm> <function>overlay</function> ( <parameter>bits</parameter> <type>bit</type> <literal>PLACING</liter <returnvalue>bit</returnvalue> </para> <para> Replaces the substring of <parameter>bits</parameter> that starts at the <parameter>start</parameter>'th bit and extends for <parameter>count</parameter> bits with <parameter>newsubstring</parameter>. If <parameter>count</parameter> is omitted, it defaults to the length of <parameter>newsubstring</parameter>. </para> <para> <literal>overlay(B'01010101010101010' placing B'11111' from 2 for 3)</literal> <returnvalue>0111110101010101010</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>position</primary> </indexterm> <function>position</function> ( <parameter>substring</parameter> <type>bit</type> <literal>IN</lite <returnvalue>integer</returnvalue> </para> <para> Returns first starting index of the specified <parameter>substring</parameter> within <parameter>bits</parameter>, or zero if it's not present. </para> <para> <literal>position(B'010' in B'000001101011')</literal> <returnvalue>8</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>substring</primary> </indexterm> <function>substring</function> ( <parameter>bits</parameter> <type>bit</type> <optional> <literal>FRO <returnvalue>bit</returnvalue> </para> <para> Extracts the substring of <parameter>bits</parameter> starting at the <parameter>start</parameter>'th bit if that is specified, and stopping after <parameter>count</parameter> bits if that is specified. Provide at least one of <parameter>start</parameter> and <parameter>count</parameter>. </para> <para> <literal>substring(B'110010111111' from 3 for 2)</literal> <returnvalue>00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>get_bit</primary> </indexterm> <function>get_bit</function> ( <parameter>bits</parameter> <type>bit</type>, <parameter>n</parameter> <type>integer</type> ) <returnvalue>integer</returnvalue> </para> <para> Extracts <parameter>n</parameter>'th bit from bit string; the first (leftmost) bit is bit 0. </para> <para> <literal>get_bit(B'101010101010101010', 6)</literal> <returnvalue>1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>set_bit</primary> </indexterm> <function>set_bit</function> ( <parameter>bits</parameter> <type>bit</type>, <parameter>n</parameter> <type>integer</type>, <parameter>newvalue</parameter> <type>integer</type> ) <returnvalue>bit</returnvalue> </para> <para> Sets <parameter>n</parameter>'th bit in bit string to <parameter>newvalue</parameter>; the first (leftmost) bit is bit 0. </para> <para> <literal>set_bit(B'101010101010101010', 6, 0)</literal> <returnvalue>101010001010101010</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> In addition, it is possible to cast integral values to and from type <type>bit</type>. Casting an integer to <type>bit(n)</type> copies the rightmost <literal>n</literal> bits. Casting an integer to a bit string width wider than the integer itself will sign-extend on the left. Some examples: <programlisting> 44::bit(10) <lineannotation>0000101100</lineannotation> 44::bit(3) <lineannotation>100</lineannotation> cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> '1110'::bit(4)::integer <lineannotation>14</lineannotation> </programlisting> Note that casting to just <quote>bit</quote> means casting to <literal>bit(1)</literal>, and so will deliver only the least significant bit of the integer. </para> </sect1> <sect1 id="functions-matching"> <title>Pattern Matching</title> <indexterm zone="functions-matching"> <primary>pattern matching</primary> </indexterm> <para> There are three separate approaches to pattern matching provided by <productname>PostgreSQL</productname>: the traditional <acronym>SQL</acronym> <function>LIKE</function> operator, the more recent <function>SIMILAR TO</function> operator (added in SQL:1999), and <acronym>POSIX</acronym>-style regular expressions. Aside from the basic <quote>does this string match this pattern?</quote> operators, functions are available to extract or replace matching substrings and to split a string at matching locations. </para> <tip> <para> If you have pattern matching needs that go beyond this, consider writing a user-defined function in Perl or Tcl. </para> </tip> <caution> <para> While most regular-expression searches can be executed very quickly, regular expressions can be contrived that take arbitrary amounts of time and memory to process. Be wary of accepting regular-expression search patterns from hostile sources. If you must do so, it is advisable to impose a statement timeout. </para> <para> Searches using <function>SIMILAR TO</function> patterns have the same security hazards, since <function>SIMILAR TO</function> provides many of the same capabilities as <acronym>POSIX</acronym>-style regular expressions. </para> <para> <function>LIKE</function> searches, being much simpler than the other two options, are safer to use with possibly-hostile pattern sources. </para> </caution> <para> <function>SIMILAR TO</function> and <acronym>POSIX</acronym>-style regular expressions do not support nondeterministic collations. If required, use <function>LIKE</function> or apply a different collation to the expression to work around this limitation. </para> <sect2 id="functions-like"> <title><function>LIKE</function></title> <indexterm> <primary>LIKE</primary> </indexterm> <synopsis> <replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <rep <replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE < </synopsis> <para> The <function>LIKE</function> expression returns true if the <replaceable>string</replaceable> matches the supplied <replaceable>pattern</replaceable>. (As expected, the <function>NOT LIKE</function> expression returns false if <function>LIKE</function> returns true, and vice versa. An equivalent expression is <literal>NOT (<replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable>)</literal>.) </para> <para> If <replaceable>pattern</replaceable> does not contain percent signs or underscores, then the pattern only represents the string itself; in that case <function>LIKE</function> acts like the equals operator. An underscore (<literal>_</literal>) in <replaceable>pattern</replaceable> stands for (matches) any single character; a percent sign (<literal>%</literal>) matches any sequence of zero or more characters. </para> <para> Some examples: <programlisting> 'abc' LIKE 'abc' <lineannotation>true</lineannotation> 'abc' LIKE 'a%' <lineannotation>true</lineannotation> 'abc' LIKE '_b_' <lineannotation>true</lineannotation> 'abc' LIKE 'c' <lineannotation>false</lineannotation> </programlisting> </para> <para> <function>LIKE</function> pattern matching supports nondeterministic collations (see <xref linkend="collation-nondeterministic"/>), such as case-insensitive collations or collations that, say, ignore punctuation. So with a case-insensitive collation, one could have: <programlisting> 'AbC' LIKE 'abc' COLLATE case_insensitive <lineannotation>true</lineannotation> 'AbC' LIKE 'a%' COLLATE case_insensitive <lineannotation>true</lineannotation> </programlisting> With collations that ignore certain characters or in general that consider strings of different lengths equal, the semantics can become a bit more complicated. Consider these examples: <programlisting> '.foo.' LIKE 'foo' COLLATE ign_punct <lineannotation>true</lineannotation> '.foo.' LIKE 'f_o' COLLATE ign_punct <lineannotation>true</lineannotation> '.foo.' LIKE '_oo' COLLATE ign_punct <lineannotation>false</lineannotation> </programlisting> The way the matching works is that the pattern is partitioned into sequences of wildcards and non-wildcard strings (wildcards being <literal>_</literal> and <literal>%</literal>). For example, the pattern <literal>f_o</literal> is partitioned into <literal>f, _, o</literal>, the pattern <literal>_oo</literal> is partitioned into <literal>_, oo</literal>. The input string matches the pattern if it can be partitioned in such a way that the wildcards match one character or any number of characters respectively and the non-wildcard partitions are equal under the applicable collation. So for example, <literal>'.foo.' LIKE 'f_o' COLLATE ign_punct</literal> is true because one can partition <literal>.foo.</literal> into <literal>.f, o, o.</literal>, and then <literal>'.f' = 'f' COLLATE ign_punct</literal>, <literal>'o'</literal> matches the <literal>_</literal> wildcard, and <literal>'o.' = 'o' COLLATE ign_punct</literal>. But <literal>'.foo.' LIKE '_oo' COLLATE ign_punct</literal> is false because <literal>.foo.</literal> cannot be partitioned in a way that the first character is any character and the rest of the string compares equal to <literal>oo</literal>. (Note that the single-character wildcard always matches exactly one character, independent of the collation. So in this example, the <literal>_</literal> would match <literal>.</literal>, but then the rest of the input string won't match the rest of the pattern.) </para> <para> <function>LIKE</function> pattern matching always covers the entire string. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign. </para> <para> To match a literal underscore or percent sign without matching other characters, the respective character in <replaceable>pattern</replaceable> must be preceded by the escape character. The default escape character is the backslash but a different one can be selected by using the <literal>ESCAPE</literal> clause. To match the escape character itself, write two escape characters. </para> <note> <para> If you have <xref linkend="guc-standard-conforming-strings"/> turned off, any backslashes you write in literal string constants will need to be doubled. See <xref linkend="sql-syntax-strings"/> for more information. </para> </note> <para> It's also possible to select no escape character by writing <literal>ESCAPE ''</literal>. This effectively disables the escape mechanism, which makes it impossible to turn off the special meaning of underscore and percent signs in the pattern. </para> <para> According to the SQL standard, omitting <literal>ESCAPE</literal> means there is no escape character (rather than defaulting to a backslash), and a zero-length <literal>ESCAPE</literal> value is disallowed. <productname>PostgreSQL</productname>'s behavior in this regard is therefore slightly nonstandard. </para> <para> The key word <token>ILIKE</token> can be used instead of <token>LIKE</token> to make the match case-insensitive according to the active locale. (But this does not support nondeterministic collations.) This is not in the <acronym>SQL</acronym> standard but is a <productname>PostgreSQL</productname> extension. </para> <para> The operator <literal>~~</literal> is equivalent to <function>LIKE</function>, and <literal>~~*</literal> corresponds to <function>ILIKE</function>. There are also <literal>!~~</literal> and <literal>!~~*</literal> operators that represent <function>NOT LIKE</function> and <function>NOT ILIKE</function>, respectively. All of these operators are <productname>PostgreSQL</productname>-specific. You may see these operator names in <command>EXPLAIN</command> output and similar places, since the parser actually translates <function>LIKE</function> et al. to these operators. </para> <para> The phrases <function>LIKE</function>, <function>ILIKE</function>, <function>NOT LIKE</function>, and <function>NOT ILIKE</function> are generally treated as operators in <productname>PostgreSQL</productname> syntax; for example they can be used in <replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>subquery</replaceable>) constructs, although an <literal>ESCAPE</literal> clause cannot be included there. In some obscure cases it may be necessary to use the underlying operator names instead. </para> <para> Also see the starts-with operator <literal>^@</literal> and the corresponding <function>starts_with()</function> function, which are useful in cases where simply matching the beginning of a string is needed. </para> </sect2> <sect2 id="functions-similarto-regexp"> <title><function>SIMILAR TO</function> Regular Expressions</title> <indexterm> <primary>regular expression</primary> <!-- <seealso>pattern matching</seealso> breaks index build --> </indexterm> <indexterm> <primary>SIMILAR TO</primary> </indexterm> <indexterm> <primary>substring</primary> </indexterm> <synopsis> <replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCA <replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>E </synopsis> <para> The <function>SIMILAR TO</function> operator returns true or false depending on whether its pattern matches the given string. It is similar to <function>LIKE</function>, except that it interprets the pattern using the SQL standard's definition of a regular expression. SQL regular expressions are a curious cross between <function>LIKE</function> notation and common (POSIX) regular expression notation. </para> <para> Like <function>LIKE</function>, the <function>SIMILAR TO</function> operator succeeds only if its pattern matches the entire string; this is unlike common regular expression behavior where the pattern can match any part of the string. Also like <function>LIKE</function>, <function>SIMILAR TO</function> uses <literal>_</literal> and <literal>%</literal> as wildcard characters denoting any single character and any string, respectively (these are comparable to <literal>.</literal> and <literal>.*</literal> in POSIX regular expressions). </para> <para> In addition to these facilities borrowed from <function>LIKE</function>, <function>SIMILAR TO</function> supports these pattern-matching metacharacters borrowed from POSIX regular expressions: <itemizedlist> <listitem> <para> <literal>|</literal> denotes alternation (either of two alternatives). </para> </listitem> <listitem> <para> <literal>*</literal> denotes repetition of the previous item zero or more times. </para> </listitem> <listitem> <para> <literal>+</literal> denotes repetition of the previous item one or more times. </para> </listitem> <listitem> <para> <literal>?</literal> denotes repetition of the previous item zero or one time. </para> </listitem> <listitem> <para> <literal>{</literal><replaceable>m</replaceable><literal>}</literal> denotes repetition of the previous item exactly <replaceable>m</replaceable> times. </para> </listitem> <listitem> <para> <literal>{</literal><replaceable>m</replaceable><literal>,}</literal> denotes repetition of the previous item <replaceable>m</replaceable> or more times. </para> </listitem> <listitem> <para> <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable>< denotes repetition of the previous item at least <replaceable>m</replaceable> and not more than <replaceable>n</replaceable> times. </para> </listitem> <listitem> <para> Parentheses <literal>()</literal> can be used to group items into a single logical item. </para> </listitem> <listitem> <para> A bracket expression <literal>[...]</literal> specifies a character class, just as in POSIX regular expressions. </para> </listitem> </itemizedlist> Notice that the period (<literal>.</literal>) is not a metacharacter for <function>SIMILAR TO</function>. </para> <para> As with <function>LIKE</function>, a backslash disables the special meaning of any of these metacharacters. A different escape character can be specified with <literal>ESCAPE</literal>, or the escape capability can be disabled by writing <literal>ESCAPE ''</literal>. </para> <para> According to the SQL standard, omitting <literal>ESCAPE</literal> means there is no escape character (rather than defaulting to a backslash), and a zero-length <literal>ESCAPE</literal> value is disallowed. <productname>PostgreSQL</productname>'s behavior in this regard is therefore slightly nonstandard. </para> <para> Another nonstandard extension is that following the escape character with a letter or digit provides access to the escape sequences defined for POSIX regular expressions; see <xref linkend="posix-character-entry-escapes-table"/>, <xref linkend="posix-class-shorthand-escapes-table"/>, and <xref linkend="posix-constraint-escapes-table"/> below. </para> <para> Some examples: <programlisting> 'abc' SIMILAR TO 'abc' <lineannotation>true</lineannotation> 'abc' SIMILAR TO 'a' <lineannotation>false</lineannotation> 'abc' SIMILAR TO '%(b|d)%' <lineannotation>true</lineannotation> 'abc' SIMILAR TO '(b|c)%' <lineannotation>false</lineannotation> '-abc-' SIMILAR TO '%\mabc\M%' <lineannotation>true</lineannotation> 'xabcy' SIMILAR TO '%\mabc\M%' <lineannotation>false</lineannotation> </programlisting> </para> <para> The <function>substring</function> function with three parameters provides extraction of a substring that matches an SQL regular expression pattern. The function can be written according to standard SQL syntax: <synopsis> substring(<replaceable>string</replaceable> similar <replaceable>pattern</replaceable> esca </synopsis> or using the now obsolete SQL:1999 syntax: <synopsis> substring(<replaceable>string</replaceable> from <replaceable>pattern</replaceable> for <repl </synopsis> or as a plain three-argument function: <synopsis> substring(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceab </synopsis> As with <literal>SIMILAR TO</literal>, the specified pattern must match the entire data string, or else the function fails and returns null. To indicate the part of the pattern for which the matching data sub-string is of interest, the pattern should contain two occurrences of the escape character followed by a double quote (<literal>"</literal>). <!-- " font-lock sanity --> The text matching the portion of the pattern between these separators is returned when the match is successful. </para> <para> The escape-double-quote separators actually divide <function>substring</function>'s pattern into three independent regular expressions; for example, a vertical bar (<literal>|</literal>) in any of the three sections affects only that section. Also, the first and third of these regular expressions are defined to match the smallest possible amount of text, not the largest, when there is any ambiguity about how much of the data string matches which pattern. (In POSIX parlance, the first and third regular expressions are forced to be non-greedy.) </para> <para> As an extension to the SQL standard, <productname>PostgreSQL</productname> allows there to be just one escape-double-quote separator, in which case the third regular expression is taken as empty; or no separators, in which case the first and third regular expressions are taken as empty. </para> <para> Some examples, with <literal>#"</literal> delimiting the return string: <programlisting> substring('foobar' similar '%#"o_b#"%' escape '#') <lineannotation>oob</lineannotation> substring('foobar' similar '#"o_b#"%' escape '#') <lineannotation>NULL</lineannotation> </programlisting> </para> </sect2> <sect2 id="functions-posix-regexp"> <title><acronym>POSIX</acronym> Regular Expressions</title> <indexterm zone="functions-posix-regexp"> <primary>regular expression</primary> <seealso>pattern matching</seealso> </indexterm> <indexterm> <primary>substring</primary> </indexterm> <indexterm> <primary>regexp_count</primary> </indexterm> <indexterm> <primary>regexp_instr</primary> </indexterm> <indexterm> <primary>regexp_like</primary> </indexterm> <indexterm> <primary>regexp_match</primary> </indexterm> <indexterm> <primary>regexp_matches</primary> </indexterm> <indexterm> <primary>regexp_replace</primary> </indexterm> <indexterm> <primary>regexp_split_to_table</primary> </indexterm> <indexterm> <primary>regexp_split_to_array</primary> </indexterm> <indexterm> <primary>regexp_substr</primary> </indexterm> <para> <xref linkend="functions-posix-table"/> lists the available operators for pattern matching using POSIX regular expressions. </para> <table id="functions-posix-table"> <title>Regular Expression Match Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>~</literal> <type>text</type> <returnvalue>boolean</returnvalue> </para> <para> String matches regular expression, case sensitively </para> <para> <literal>'thomas' ~ 't.*ma'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>~*</literal> <type>text</type> <returnvalue>boolean</returnvalue> </para> <para> String matches regular expression, case-insensitively </para> <para> <literal>'thomas' ~* 'T.*ma'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>!~</literal> <type>text</type> <returnvalue>boolean</returnvalue> </para> <para> String does not match regular expression, case sensitively </para> <para> <literal>'thomas' !~ 't.*max'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>!~*</literal> <type>text</type> <returnvalue>boolean</returnvalue> </para> <para> String does not match regular expression, case-insensitively </para> <para> <literal>'thomas' !~* 'T.*ma'</literal> <returnvalue>f</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> <acronym>POSIX</acronym> regular expressions provide a more powerful means for pattern matching than the <function>LIKE</function> and <function>SIMILAR TO</function> operators. Many Unix tools such as <command>egrep</command>, <command>sed</command>, or <command>awk</command> use a pattern matching language that is similar to the one described here. </para> <para> A regular expression is a character sequence that is an abbreviated definition of a set of strings (a <firstterm>regular set</firstterm>). A string is said to match a regular expression if it is a member of the regular set described by the regular expression. As with <function>LIKE</function>, pattern characters match string characters exactly unless they are special characters in the regular expression language — but regular expressions use different special characters than <function>LIKE</function> does. Unlike <function>LIKE</function> patterns, a regular expression is allowed to match anywhere within a string, unless the regular expression is explicitly anchored to the beginning or end of the string. </para> <para> Some examples: <programlisting> 'abcd' ~ 'bc' <lineannotation>true</lineannotation> 'abcd' ~ 'a.c' <lineannotation>true — dot matches any character</lineannotation> 'abcd' ~ 'a.*d' <lineannotation>true — <literal>*</literal> repeats the preceding pattern item</li 'abcd' ~ '(b|x)' <lineannotation>true — <literal>|</literal> means OR, parentheses group</lineann 'abcd' ~ '^a' <lineannotation>true — <literal>^</literal> anchors to start of string</lineannotati 'abcd' ~ '^(b|c)' <lineannotation>false — would match except for anchoring</lineannotation> </programlisting> </para> <para> The <acronym>POSIX</acronym> pattern language is described in much greater detail below. </para> <para> The <function>substring</function> function with two parameters, <function>substring(<replaceable>string</replaceable> from <replaceable>pattern</replaceable>)</function>, provides extraction of a substring that matches a POSIX regular expression pattern. It returns null if there is no match, otherwise the first portion of the text that matched the pattern. But if the pattern contains any parentheses, the portion of the text that matched the first parenthesized subexpression (the one whose left parenthesis comes first) is returned. You can put parentheses around the whole expression if you want to use parentheses within it without triggering this exception. If you need parentheses in the pattern before the subexpression you want to extract, see the non-capturing parentheses described below. </para> <para> Some examples: <programlisting> substring('foobar' from 'o.b') <lineannotation>oob</lineannotation> substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> </programlisting> </para> <para> The <function>regexp_count</function> function counts the number of places where a POSIX regular expression pattern matches a string. It has the syntax <function>regexp_count</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable> <optional>, <replaceable>start</replaceable> <optional>, <replaceable>flags</replaceable> </optional></optional>). <replaceable>pattern</replaceable> is searched for in <replaceable>string</replaceable>, normally from the beginning of the string, but if the <replaceable>start</replaceable> parameter is provided then beginning from that character index. The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. For example, including <literal>i</literal> in <replaceable>flags</replaceable> specifies case-insensitive matching. Supported flags are described in <xref linkend="posix-embedded-options-table"/>. </para> <para> Some examples: <programlisting> regexp_count('ABCABCAXYaxy', 'A.') <lineannotation>3</lineannotation> regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') <lineannotation>4</lineannotation> </programlisting> </para> <para> The <function>regexp_instr</function> function returns the starting or ending position of the <replaceable>N</replaceable>'th match of a POSIX regular expression pattern to a string, or zero if there is no such match. It has the syntax <function>regexp_instr</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable> <optional>, <replaceable>start</replaceable> <optional>, <replaceable>N</replaceable> <optional>, <replaceable>endoption</replaceable> <optional>, <replaceable>flags</replaceable> <optional>, <replaceable>subexpr</replaceable> </optional></optional></optional></optional></optional>). <replaceable>pattern</replaceable> is searched for in <replaceable>string</replaceable>, normally from the beginning of the string, but if the <replaceable>start</replaceable> parameter is provided then beginning from that character index. If <replaceable>N</replaceable> is specified then the <replaceable>N</replaceable>'th match of the pattern is located, otherwise the first match is located. If the <replaceable>endoption</replaceable> parameter is omitted or specified as zero, the function returns the position of the first character of the match. Otherwise, <replaceable>endoption</replaceable> must be one, and the function returns the position of the character following the match. The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described in <xref linkend="posix-embedded-options-table"/>. For a pattern containing parenthesized subexpressions, <replaceable>subexpr</replaceable> is an integer indicating which subexpression is of interest: the result identifies the position of the substring matching that subexpression. Subexpressions are numbered in the order of their leading parentheses. When <replaceable>subexpr</replaceable> is omitted or zero, the result identifies the position of the whole match regardless of parenthesized subexpressions. </para> <para> Some examples: <programlisting> regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2) <lineannotation>23</lineannotation> regexp_instr(string=>'ABCDEFGHI', pattern=>'(c..)(...)', start=>1, "N"=>1, endoption=>0, f <lineannotation>6</lineannotation> </programlisting> </para> <para> The <function>regexp_like</function> function checks whether a match of a POSIX regular expression pattern occurs within a string, returning boolean true or false. It has the syntax <function>regexp_like</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable> <optional>, <replaceable>flags</replaceable> </optional>). The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described in <xref linkend="posix-embedded-options-table"/>. This function has the same results as the <literal>~</literal> operator if no flags are specified. If only the <literal>i</literal> flag is specified, it has the same results as the <literal>~*</literal> operator. </para> <para> Some examples: <programlisting> regexp_like('Hello World', 'world') <lineannotation>false</lineannotation> regexp_like('Hello World', 'world', 'i') <lineannotation>true</lineannotation> </programlisting> </para> <para> The <function>regexp_match</function> function returns a text array of matching substring(s) within the first match of a POSIX regular expression pattern to a string. It has the syntax <function>regexp_match</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable> <optional>, <replaceable>flags</replaceable> </optional>). If there is no match, the result is <literal>NULL</literal>. If a match is found, and the <replaceable>pattern</replaceable> contains no parenthesized subexpressions, then the result is a single-element text array containing the substring matching the whole pattern. If a match is found, and the <replaceable>pattern</replaceable> contains parenthesized subexpressions, then the result is a text array whose <replaceable>n</replaceable>'th element is the substring matching the <replaceable>n</replaceable>'th parenthesized subexpression of the <replaceable>pattern</replaceable> (not counting <quote>non-capturing</quote> parentheses; see below for details). The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described in <xref linkend="posix-embedded-options-table"/>. </para> <para> Some examples: <programlisting> SELECT regexp_match('foobarbequebaz', 'bar.*que'); regexp_match -------------- {barbeque} (1 row) SELECT regexp_match('foobarbequebaz', '(bar)(beque)'); regexp_match -------------- {bar,beque} (1 row) </programlisting> </para> <tip> <para> In the common case where you just want the whole matching substring or <literal>NULL</literal> for no match, the best solution is to use <function>regexp_substr()</function>. However, <function>regexp_substr()</function> only exists in <productname>PostgreSQL</productname> version 15 and up. When working in older versions, you can extract the first element of <function>regexp_match()</function>'s result, for example: <programlisting> SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1]; regexp_match -------------- barbeque (1 row) </programlisting> </para> </tip> <para> The <function>regexp_matches</function> function returns a set of text arrays of matching substring(s) within matches of a POSIX regular expression pattern to a string. It has the same syntax as <function>regexp_match</function>. This function returns no rows if there is no match, one row if there is a match and the <literal>g</literal> flag is not given, or <replaceable>N</replaceable> rows if there are <replaceable>N</replaceable> matches and the <literal>g</literal> flag is given. Each returned row is a text array containing the whole matched substring or the substrings matching parenthesized subexpressions of the <replaceable>pattern</replaceable>, just as described above for <function>regexp_match</function>. <function>regexp_matches</function> accepts all the flags shown in <xref linkend="posix-embedded-options-table"/>, plus the <literal>g</literal> flag which commands it to return all matches, not just the first one. </para> <para> Some examples: <programlisting> SELECT regexp_matches('foo', 'not there'); regexp_matches ---------------- (0 rows) SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g'); regexp_matches ---------------- {bar,beque} {bazil,barf} (2 rows) </programlisting> </para> <tip> <para> In most cases <function>regexp_matches()</function> should be used with the <literal>g</literal> flag, since if you only want the first match, it's easier and more efficient to use <function>regexp_match()</function>. However, <function>regexp_match()</function> only exists in <productname>PostgreSQL</productname> version 10 and up. When working in older versions, a common trick is to place a <function>regexp_matches()</function> call in a sub-select, for example: <programlisting> SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; </programlisting> This produces a text array if there's a match, or <literal>NULL</literal> if not, the same as <function>regexp_match()</function> would do. Without the sub-select, this query would produce no output at all for table rows without a match, which is typically not the desired behavior. </para> </tip> <para> The <function>regexp_replace</function> function provides substitution of new text for substrings that match POSIX regular expression patterns. It has the syntax <function>regexp_replace</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>replacement</replaceable> <optional>, <replaceable>flags</replaceable> </optional>) or <function>regexp_replace</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>replacement</replaceable>, <replaceable>start</replaceable> <optional>, <replaceable>N</replaceable> <optional>, <replaceable>flags</replaceable> </optional></optional>). The source <replaceable>string</replaceable> is returned unchanged if there is no match to the <replaceable>pattern</replaceable>. If there is a match, the <replaceable>string</replaceable> is returned with the <replaceable>replacement</replaceable> string substituted for the matching substring. The <replaceable>replacement</replaceable> string can contain <literal>\</literal><replaceable>n</replaceable>, where <replaceable>n</replaceable> is 1 through 9, to indicate that the source substring matching the <replaceable>n</replaceable>'th parenthesized subexpression of the pattern should be inserted, and it can contain <literal>\&</literal> to indicate that the substring matching the entire pattern should be inserted. Write <literal>\\</literal> if you need to put a literal backslash in the replacement text. <replaceable>pattern</replaceable> is searched for in <replaceable>string</replaceable>, normally from the beginning of the string, but if the <replaceable>start</replaceable> parameter is provided then beginning from that character index. By default, only the first match of the pattern is replaced. If <replaceable>N</replaceable> is specified and is greater than zero, then the <replaceable>N</replaceable>'th match of the pattern is replaced. If the <literal>g</literal> flag is given, or if <replaceable>N</replaceable> is specified and is zero, then all matches at or after the <replaceable>start</replaceable> position are replaced. (The <literal>g</literal> flag is ignored when <replaceable>N</replaceable> is specified.) The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags (though not <literal>g</literal>) are described in <xref linkend="posix-embedded-options-table"/>. </para> <para> Some examples: <programlisting> regexp_replace('foobarbaz', 'b..', 'X') <lineannotation>fooXbaz</lineannotation> regexp_replace('foobarbaz', 'b..', 'X', 'g') <lineannotation>fooXX</lineannotation> regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g') <lineannotation>fooXarYXazY</lineannotation> regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i') <lineannotation>X PXstgrXSQL fXnctXXn</lineannotation> regexp_replace(string=>'A PostgreSQL function', pattern=>'a|e|i|o|u', replacement=>'X', <lineannotation>A PostgrXSQL function</lineannotation> </programlisting> </para> <para> The <function>regexp_split_to_table</function> function splits a string using a POSIX regular expression pattern as a delimiter. It has the syntax <function>regexp_split_to_table</function>(<replaceable>string</replaceable>, <replaceable> <optional>, <replaceable>flags</replaceable> </optional>). If there is no match to the <replaceable>pattern</replaceable>, the function returns the <replaceable>string</replaceable>. If there is at least one match, for each match it returns the text from the end of the last match (or the beginning of the string) to the beginning of the match. When there are no more matches, it returns the text from the end of the last match to the end of the string. The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. <function>regexp_split_to_table</function> supports the flags described in <xref linkend="posix-embedded-options-table"/>. </para> <para> The <function>regexp_split_to_array</function> function behaves the same as <function>regexp_split_to_table</function>, except that <function>regexp_split_to_array</f returns its result as an array of <type>text</type>. It has the syntax <function>regexp_split_to_array</function>(<replaceable>string</replaceable>, <replaceable> <optional>, <replaceable>flags</replaceable> </optional>). The parameters are the same as for <function>regexp_split_to_table</function>. </para> <para> Some examples: <programlisting> SELECT foo FROM regexp_split_to_table('the quick brown fox jumps over the lazy dog', '\s+') A foo ------- the quick brown fox jumps over the lazy dog (9 rows) SELECT regexp_split_to_array('the quick brown fox jumps over the lazy dog', '\s+'); regexp_split_to_array ----------------------------------------------- {the,quick,brown,fox,jumps,over,the,lazy,dog} (1 row) SELECT foo FROM regexp_split_to_table('the quick brown fox', '\s*') AS foo; foo ----- t h e q u i c k b r o w n f o x (16 rows) </programlisting> </para> <para> As the last example demonstrates, the regexp split functions ignore zero-length matches that occur at the start or end of the string or immediately after a previous match. This is contrary to the strict definition of regexp matching that is implemented by the other regexp functions, but is usually the most convenient behavior in practice. Other software systems such as Perl use similar definitions. </para> <para> The <function>regexp_substr</function> function returns the substring that matches a POSIX regular expression pattern, or <literal>NULL</literal> if there is no match. It has the syntax <function>regexp_substr</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable> <optional>, <replaceable>start</replaceable> <optional>, <replaceable>N</replaceable> <optional>, <replaceable>flags</replaceable> <optional>, <replaceable>subexpr</replaceable> </optional></optional></optional></optional>). <replaceable>pattern</replaceable> is searched for in <replaceable>string</replaceable>, normally from the beginning of the string, but if the <replaceable>start</replaceable> parameter is provided then beginning from that character index. If <replaceable>N</replaceable> is specified then the <replaceable>N</replaceable>'th match of the pattern is returned, otherwise the first match is returned. The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described in <xref linkend="posix-embedded-options-table"/>. For a pattern containing parenthesized subexpressions, <replaceable>subexpr</replaceable> is an integer indicating which subexpression is of interest: the result is the substring matching that subexpression. Subexpressions are numbered in the order of their leading parentheses. When <replaceable>subexpr</replaceable> is omitted or zero, the result is the whole match regardless of parenthesized subexpressions. </para> <para> Some examples: <programlisting> regexp_substr('number of your street, town zip, FR', '[^,]+', 1, 2) <lineannotation> town zip</lineannotation> regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2) <lineannotation>FGH</lineannotation> </programlisting> </para> <!-- derived from the re_syntax.n man page --> <sect3 id="posix-syntax-details"> <title>Regular Expression Details</title> <para> <productname>PostgreSQL</productname>'s regular expressions are implemented using a software package written by Henry Spencer. Much of the description of regular expressions below is copied verbatim from his manual. </para> <para> Regular expressions (<acronym>RE</acronym>s), as defined in <acronym>POSIX</acronym> 1003.2, come in two forms: <firstterm>extended</firstterm> <acronym>RE</acronym>s or <acronym>ERE</acronym>s (roughly those of <command>egrep</command>), and <firstterm>basic</firstterm> <acronym>RE</acronym>s or <acronym>BRE</acronym>s (roughly those of <command>ed</command>). <productname>PostgreSQL</productname> supports both forms, and also implements some extensions that are not in the POSIX standard, but have become widely used due to their availability in programming languages such as Perl and Tcl. <acronym>RE</acronym>s using these non-POSIX extensions are called <firstterm>advanced</firstterm> <acronym>RE</acronym>s or <acronym>ARE</acronym>s in this documentation. AREs are almost an exact superset of EREs, but BREs have several notational incompatibilities (as well as being much more limited). We first describe the ARE and ERE forms, noting features that apply only to AREs, and then describe how BREs differ. </para> <note> <para> <productname>PostgreSQL</productname> always initially presumes that a regular expression follows the ARE rules. However, the more limited ERE or BRE rules can be chosen by prepending an <firstterm>embedded option</firstterm> to the RE pattern, as described in <xref linkend="posix-metasyntax"/>. This can be useful for compatibility with applications that expect exactly the <acronym>POSIX</acronym> 1003.2 rules. </para> </note> <para> A regular expression is defined as one or more <firstterm>branches</firstterm>, separated by <literal>|</literal>. It matches anything that matches one of the branches. </para> <para> A branch is zero or more <firstterm>quantified atoms</firstterm> or <firstterm>constraints</firstterm>, concatenated. It matches a match for the first, followed by a match for the second, etc.; an empty branch matches the empty string. </para> <para> A quantified atom is an <firstterm>atom</firstterm> possibly followed by a single <firstterm>quantifier</firstterm>. Without a quantifier, it matches a match for the atom. With a quantifier, it can match some number of matches of the atom. An <firstterm>atom</firstterm> can be any of the possibilities shown in <xref linkend="posix-atoms-table"/>. The possible quantifiers and their meanings are shown in <xref linkend="posix-quantifiers-table"/>. </para> <para> A <firstterm>constraint</firstterm> matches an empty string, but matches only when specific conditions are met. A constraint can be used where an atom could be used, except it cannot be followed by a quantifier. The simple constraints are shown in <xref linkend="posix-constraints-table"/>; some more constraints are described later. </para> <table id="posix-atoms-table"> <title>Regular Expression Atoms</title> <tgroup cols="2"> <thead> <row> <entry>Atom</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>(</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> (where <replaceable>re</replaceable> is any regular expression) matches a match for <replaceable>re</replaceable>, with the match noted for possible reporting </entry> </row> <row> <entry> <literal>(?:</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> as above, but the match is not noted for reporting (a <quote>non-capturing</quote> set of parentheses) (AREs only) </entry> </row> <row> <entry> <literal>.</literal> </entry> <entry> matches any single character </entry> </row> <row> <entry> <literal>[</literal><replaceable>chars</replaceable><literal>]</literal> </entry> <entry> a <firstterm>bracket expression</firstterm>, matching any one of the <replaceable>chars</replaceable> (see <xref linkend="posix-bracket-expressions"/> for more detail) </entry> </row> <row> <entry> <literal>\</literal><replaceable>k</replaceable> </entry> <entry> (where <replaceable>k</replaceable> is a non-alphanumeric character) matches that character taken as an ordinary character, e.g., <literal>\\</literal> matches a backslash character </entry> </row> <row> <entry> <literal>\</literal><replaceable>c</replaceable> </entry> <entry> where <replaceable>c</replaceable> is alphanumeric (possibly followed by other characters) is an <firstterm>escape</firstterm>, see <xref linkend="posix-escape-sequences"/> (AREs only; in EREs and BREs, this matches <replaceable>c</replaceable>) </entry> </row> <row> <entry> <literal>{</literal> </entry> <entry> when followed by a character other than a digit, matches the left-brace character <literal>{</literal>; when followed by a digit, it is the beginning of a <replaceable>bound</replaceable> (see below) </entry> </row> <row> <entry> <replaceable>x</replaceable> </entry> <entry> where <replaceable>x</replaceable> is a single character with no other significance, matches that character </entry> </row> </tbody> </tgroup> </table> <para> An RE cannot end with a backslash (<literal>\</literal>). </para> <note> <para> If you have <xref linkend="guc-standard-conforming-strings"/> turned off, any backslashes you write in literal string constants will need to be doubled. See <xref linkend="sql-syntax-strings"/> for more information. </para> </note> <table id="posix-quantifiers-table"> <title>Regular Expression Quantifiers</title> <tgroup cols="2"> <thead> <row> <entry>Quantifier</entry> <entry>Matches</entry> </row> </thead> <tbody> <row> <entry> <literal>*</literal> </entry> <entry> a sequence of 0 or more matches of the atom </entry> </row> <row> <entry> <literal>+</literal> </entry> <entry> a sequence of 1 or more matches of the atom </entry> </row> <row> <entry> <literal>?</literal> </entry> <entry> a sequence of 0 or 1 matches of the atom </entry> </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>}</literal> </entry> <entry> a sequence of exactly <replaceable>m</replaceable> matches of the atom </entry> </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>,}</literal> </entry> <entry> a sequence of <replaceable>m</replaceable> or more matches of the atom </entry> </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable>< <entry> a sequence of <replaceable>m</replaceable> through <replaceable>n</replaceable> (inclusive) matches of the atom; <replaceable>m</replaceable> cannot exceed <replaceable>n</replaceable> </entry> </row> <row> <entry> <literal>*?</literal> </entry> <entry> non-greedy version of <literal>*</literal> </entry> </row> <row> <entry> <literal>+?</literal> </entry> <entry> non-greedy version of <literal>+</literal> </entry> </row> <row> <entry> <literal>??</literal> </entry> <entry> non-greedy version of <literal>?</literal> </entry> </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>}?</literal> </entry> <entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>}</literal> < </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>,}?</literal> </entry> <entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>,}</litera </row> <row> <entry> <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable>< <entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>,</literal>< </row> </tbody> </tgroup> </table> <para> The forms using <literal>{</literal><replaceable>...</replaceable><literal>}</literal> are known as <firstterm>bounds</firstterm>. The numbers <replaceable>m</replaceable> and <replaceable>n</replaceable> within a bound are unsigned decimal integers with permissible values from 0 to 255 inclusive. </para> <para> <firstterm>Non-greedy</firstterm> quantifiers (available in AREs only) match the same possibilities as their corresponding normal (<firstterm>greedy</firstterm>) counterparts, but prefer the smallest number rather than the largest number of matches. See <xref linkend="posix-matching-rules"/> for more detail. </para> <note> <para> A quantifier cannot immediately follow another quantifier, e.g., <literal>**</literal> is invalid. A quantifier cannot begin an expression or subexpression or follow <literal>^</literal> or <literal>|</literal>. </para> </note> <table id="posix-constraints-table"> <title>Regular Expression Constraints</title> <tgroup cols="2"> <thead> <row> <entry>Constraint</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>^</literal> </entry> <entry> matches at the beginning of the string </entry> </row> <row> <entry> <literal>$</literal> </entry> <entry> matches at the end of the string </entry> </row> <row> <entry> <literal>(?=</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> <firstterm>positive lookahead</firstterm> matches at any point where a substring matching <replaceable>re</replaceable> begins (AREs only) </entry> </row> <row> <entry> <literal>(?!</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> <firstterm>negative lookahead</firstterm> matches at any point where no substring matching <replaceable>re</replaceable> begins (AREs only) </entry> </row> <row> <entry> <literal>(?<=</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> <firstterm>positive lookbehind</firstterm> matches at any point where a substring matching <replaceable>re</replaceable> ends (AREs only) </entry> </row> <row> <entry> <literal>(?<!</literal><replaceable>re</replaceable><literal>)</literal> </entry> <entry> <firstterm>negative lookbehind</firstterm> matches at any point where no substring matching <replaceable>re</replaceable> ends (AREs only) </entry> </row> </tbody> </tgroup> </table> <para> Lookahead and lookbehind constraints cannot contain <firstterm>back references</firstterm> (see <xref linkend="posix-escape-sequences"/>), and all parentheses within them are considered non-capturing. </para> </sect3> <sect3 id="posix-bracket-expressions"> <title>Bracket Expressions</title> <para> A <firstterm>bracket expression</firstterm> is a list of characters enclosed in <literal>[]</literal>. It normally matches any single character from the list (but see below). If the list begins with <literal>^</literal>, it matches any single character <emphasis>not</emphasis> from the rest of the list. If two characters in the list are separated by <literal>-</literal>, this is shorthand for the full range of characters between those two (inclusive) in the collating sequence, e.g., <literal>[0-9]</literal> in <acronym>ASCII</acronym> matches any decimal digit. It is illegal for two ranges to share an endpoint, e.g., <literal>a-c-e</literal>. Ranges are very collating-sequence-dependent, so portable programs should avoid relying on them. </para> <para> To include a literal <literal>]</literal> in the list, make it the first character (after <literal>^</literal>, if that is used). To include a literal <literal>-</literal>, make it the first or last character, or the second endpoint of a range. To use a literal <literal>-</literal> as the first endpoint of a range, enclose it in <literal>[.</literal> and <literal>.]</literal> to make it a collating element (see below). With the exception of these characters, some combinations using <literal>[</literal> (see next paragraphs), and escapes (AREs only), all other special characters lose their special significance within a bracket expression. In particular, <literal>\</literal> is not special when following ERE or BRE rules, though it is special (as introducing an escape) in AREs. </para> <para> Within a bracket expression, a collating element (a character, a multiple-character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in <literal>[.</literal> and <literal>.]</literal> stands for the sequence of characters of that collating element. The sequence is treated as a single element of the bracket expression's list. This allows a bracket expression containing a multiple-character collating element to match more than one character, e.g., if the collating sequence includes a <literal>ch</literal> collating element, then the RE <literal>[[.ch.]]*c</literal> matches the first five characters of <literal>chchcc</literal>. </para> <note> <para> <productname>PostgreSQL</productname> currently does not support multi-character collating elements. This information describes possible future behavior. </para> </note> <para> Within a bracket expression, a collating element enclosed in <literal>[=</literal> and <literal>=]</literal> is an <firstterm>equivalence class</firstterm>, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were <literal>[.</literal> and <literal>.]</literal>.) For example, if <literal>o</literal> and <literal>^</literal> are the members of an equivalence class, then <literal>[[=o=]]</literal>, <literal>[[=^=]]</literal>, and <literal>[o^]</literal> are all synonymous. An equivalence class cannot be an endpoint of a range. </para> <para> Within a bracket expression, the name of a character class enclosed in <literal>[:</literal> and <literal>:]</literal> stands for the list of all characters belonging to that class. A character class cannot be used as an endpoint of a range. The <acronym>POSIX</acronym> standard defines these character class names: <literal>alnum</literal> (letters and numeric digits), <literal>alpha</literal> (letters), <literal>blank</literal> (space and tab), <literal>cntrl</literal> (control characters), <literal>digit</literal> (numeric digits), <literal>graph</literal> (printable characters except space), <literal>lower</literal> (lower-case letters), <literal>print</literal> (printable characters including space), <literal>punct</literal> (punctuation), <literal>space</literal> (any white space), <literal>upper</literal> (upper-case letters), and <literal>xdigit</literal> (hexadecimal digits). The behavior of these standard character classes is generally consistent across platforms for characters in the 7-bit ASCII set. Whether a given non-ASCII character is considered to belong to one of these classes depends on the <firstterm>collation</firstterm> that is used for the regular-expression function or operator (see <xref linkend="collation"/>), or by default on the database's <envar>LC_CTYPE</envar> locale setting (see <xref linkend="locale"/>). The classification of non-ASCII characters can vary across platforms even in similarly-named locales. (But the <literal>C</literal> locale never considers any non-ASCII characters to belong to any of these classes.) In addition to these standard character classes, <productname>PostgreSQL</productname> defines the <literal>word</literal> character class, which is the same as <literal>alnum</literal> plus the underscore (<literal>_</literal>) character, and the <literal>ascii</literal> character class, which contains exactly the 7-bit ASCII set. </para> <para> There are two special cases of bracket expressions: the bracket expressions <literal>[[:<:]]</literal> and <literal>[[:>:]]</literal> are constraints, matching empty strings at the beginning and end of a word respectively. A word is defined as a sequence of word characters that is neither preceded nor followed by word characters. A word character is any character belonging to the <literal>word</literal> character class, that is, any letter, digit, or underscore. This is an extension, compatible with but not specified by <acronym>POSIX</acronym> 1003.2, and should be used with caution in software intended to be portable to other systems. The constraint escapes described below are usually preferable; they are no more standard, but are easier to type. </para> </sect3> <sect3 id="posix-escape-sequences"> <title>Regular Expression Escapes</title> <para> <firstterm>Escapes</firstterm> are special sequences beginning with <literal>\</literal> followed by an alphanumeric character. Escapes come in several varieties: character entry, class shorthands, constraint escapes, and back references. A <literal>\</literal> followed by an alphanumeric character but not constituting a valid escape is illegal in AREs. In EREs, there are no escapes: outside a bracket expression, a <literal>\</literal> followed by an alphanumeric character merely stands for that character as an ordinary character, and inside a bracket expression, <literal>\</literal> is an ordinary character. (The latter is the one actual incompatibility between EREs and AREs.) </para> <para> <firstterm>Character-entry escapes</firstterm> exist to make it easier to specify non-printing and other inconvenient characters in REs. They are shown in <xref linkend="posix-character-entry-escapes-table"/>. </para> <para> <firstterm>Class-shorthand escapes</firstterm> provide shorthands for certain commonly-used character classes. They are shown in <xref linkend="posix-class-shorthand-escapes-table"/>. </para> <para> A <firstterm>constraint escape</firstterm> is a constraint, matching the empty string if specific conditions are met, written as an escape. They are shown in <xref linkend="posix-constraint-escapes-table"/>. </para> <para> A <firstterm>back reference</firstterm> (<literal>\</literal><replaceable>n</replaceable>) match same string matched by the previous parenthesized subexpression specified by the number <replaceable>n</replaceable> (see <xref linkend="posix-constraint-backref-table"/>). For example, <literal>([bc])\1</literal> matches <literal>bb</literal> or <literal>cc</literal> but not <literal>bc</literal> or <literal>cb</literal>. The subexpression must entirely precede the back reference in the RE. Subexpressions are numbered in the order of their leading parentheses. Non-capturing parentheses do not define subexpressions. The back reference considers only the string characters matched by the referenced subexpression, not any constraints contained in it. For example, <literal>(^\d)\1</literal> will match <literal>22</literal>. </para> <table id="posix-character-entry-escapes-table"> <title>Regular Expression Character-Entry Escapes</title> <tgroup cols="2"> <thead> <row> <entry>Escape</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>\a</literal> </entry> <entry> alert (bell) character, as in C </entry> </row> <row> <entry> <literal>\b</literal> </entry> <entry> backspace, as in C </entry> </row> <row> <entry> <literal>\B</literal> </entry> <entry> synonym for backslash (<literal>\</literal>) to help reduce the need for backslash doubling </entry> </row> <row> <entry> <literal>\c</literal><replaceable>X</replaceable> </entry> <entry> (where <replaceable>X</replaceable> is any character) the character whose low-order 5 bits are the same as those of <replaceable>X</replaceable>, and whose other bits are all zero </entry> </row> <row> <entry> <literal>\e</literal> </entry> <entry> the character whose collating-sequence name is <literal>ESC</literal>, or failing that, the character with octal value <literal>033</literal> </entry> </row> <row> <entry> <literal>\f</literal> </entry> <entry> form feed, as in C </entry> </row> <row> <entry> <literal>\n</literal> </entry> <entry> newline, as in C </entry> </row> <row> <entry> <literal>\r</literal> </entry> <entry> carriage return, as in C </entry> </row> <row> <entry> <literal>\t</literal> </entry> <entry> horizontal tab, as in C </entry> </row> <row> <entry> <literal>\u</literal><replaceable>wxyz</replaceable> </entry> <entry> (where <replaceable>wxyz</replaceable> is exactly four hexadecimal digits) the character whose hexadecimal value is <literal>0x</literal><replaceable>wxyz</replaceable> </entry> </row> <row> <entry> <literal>\U</literal><replaceable>stuvwxyz</replaceable> </entry> <entry> (where <replaceable>stuvwxyz</replaceable> is exactly eight hexadecimal digits) the character whose hexadecimal value is <literal>0x</literal><replaceable>stuvwxyz</replaceable> </entry> </row> <row> <entry> <literal>\v</literal> </entry> <entry> vertical tab, as in C </entry> </row> <row> <entry> <literal>\x</literal><replaceable>hhh</replaceable> </entry> <entry> (where <replaceable>hhh</replaceable> is any sequence of hexadecimal digits) the character whose hexadecimal value is <literal>0x</literal><replaceable>hhh</replaceable> (a single character no matter how many hexadecimal digits are used) </entry> </row> <row> <entry> <literal>\0</literal> </entry> <entry> the character whose value is <literal>0</literal> (the null byte)</entry> </row> <row> <entry> <literal>\</literal><replaceable>xy</replaceable> </entry> <entry> (where <replaceable>xy</replaceable> is exactly two octal digits, and is not a <firstterm>back reference</firstterm>) the character whose octal value is <literal>0</literal><replaceable>xy</replaceable> </entry> </row> <row> <entry> <literal>\</literal><replaceable>xyz</replaceable> </entry> <entry> (where <replaceable>xyz</replaceable> is exactly three octal digits, and is not a <firstterm>back reference</firstterm>) the character whose octal value is <literal>0</literal><replaceable>xyz</replaceable> </entry> </row> </tbody> </tgroup> </table> <para> Hexadecimal digits are <literal>0</literal>-<literal>9</literal>, <literal>a</literal>-<literal>f</literal>, and <literal>A</literal>-<literal>F</literal>. Octal digits are <literal>0</literal>-<literal>7</literal>. </para> <para> Numeric character-entry escapes specifying values outside the ASCII range (0–127) have meanings dependent on the database encoding. When the encoding is UTF-8, escape values are equivalent to Unicode code points, for example <literal>\u1234</literal> means the character <literal>U+1234</literal>. For other multibyte encodings, character-entry escapes usually just specify the concatenation of the byte values for the character. If the escape value does not correspond to any legal character in the database encoding, no error will be raised, but it will never match any data. </para> <para> The character-entry escapes are always taken as ordinary characters. For example, <literal>\135</literal> is <literal>]</literal> in ASCII, but <literal>\135</literal> does not terminate a bracket expression. </para> <table id="posix-class-shorthand-escapes-table"> <title>Regular Expression Class-Shorthand Escapes</title> <tgroup cols="2"> <thead> <row> <entry>Escape</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>\d</literal> </entry> <entry> matches any digit, like <literal>[[:digit:]]</literal> </entry> </row> <row> <entry> <literal>\s</literal> </entry> <entry> matches any whitespace character, like <literal>[[:space:]]</literal> </entry> </row> <row> <entry> <literal>\w</literal> </entry> <entry> matches any word character, like <literal>[[:word:]]</literal> </entry> </row> <row> <entry> <literal>\D</literal> </entry> <entry> matches any non-digit, like <literal>[^[:digit:]]</literal> </entry> </row> <row> <entry> <literal>\S</literal> </entry> <entry> matches any non-whitespace character, like <literal>[^[:space:]]</literal> </entry> </row> <row> <entry> <literal>\W</literal> </entry> <entry> matches any non-word character, like <literal>[^[:word:]]</literal> </entry> </row> </tbody> </tgroup> </table> <para> The class-shorthand escapes also work within bracket expressions, although the definitions shown above are not quite syntactically valid in that context. For example, <literal>[a-c\d]</literal> is equivalent to <literal>[a-c[:digit:]]</literal>. </para> <table id="posix-constraint-escapes-table"> <title>Regular Expression Constraint Escapes</title> <tgroup cols="2"> <thead> <row> <entry>Escape</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>\A</literal> </entry> <entry> matches only at the beginning of the string (see <xref linkend="posix-matching-rules"/> for how this differs from <literal>^</literal>) </entry> </row> <row> <entry> <literal>\m</literal> </entry> <entry> matches only at the beginning of a word </entry> </row> <row> <entry> <literal>\M</literal> </entry> <entry> matches only at the end of a word </entry> </row> <row> <entry> <literal>\y</literal> </entry> <entry> matches only at the beginning or end of a word </entry> </row> <row> <entry> <literal>\Y</literal> </entry> <entry> matches only at a point that is not the beginning or end of a word </entry> </row> <row> <entry> <literal>\Z</literal> </entry> <entry> matches only at the end of the string (see <xref linkend="posix-matching-rules"/> for how this differs from <literal>$</literal>) </entry> </row> </tbody> </tgroup> </table> <para> A word is defined as in the specification of <literal>[[:<:]]</literal> and <literal>[[:>:]]</literal> above. Constraint escapes are illegal within bracket expressions. </para> <table id="posix-constraint-backref-table"> <title>Regular Expression Back References</title> <tgroup cols="2"> <thead> <row> <entry>Escape</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>\</literal><replaceable>m</replaceable> </entry> <entry> (where <replaceable>m</replaceable> is a nonzero digit) a back reference to the <replaceable>m</replaceable>'th subexpression </entry> </row> <row> <entry> <literal>\</literal><replaceable>mnn</replaceable> </entry> <entry> (where <replaceable>m</replaceable> is a nonzero digit, and <replaceable>nn</replaceable> is some more digits, and the decimal value <replaceable>mnn</replaceable> is not greater than the number of closing capturing parentheses seen so far) a back reference to the <replaceable>mnn</replaceable>'th subexpression </entry> </row> </tbody> </tgroup> </table> <note> <para> There is an inherent ambiguity between octal character-entry escapes and back references, which is resolved by the following heuristics, as hinted at above. A leading zero always indicates an octal escape. A single non-zero digit, not followed by another digit, is always taken as a back reference. A multi-digit sequence not starting with a zero is taken as a back reference if it comes after a suitable subexpression (i.e., the number is in the legal range for a back reference), and otherwise is taken as octal. </para> </note> </sect3> <sect3 id="posix-metasyntax"> <title>Regular Expression Metasyntax</title> <para> In addition to the main syntax described above, there are some special forms and miscellaneous syntactic facilities available. </para> <para> An RE can begin with one of two special <firstterm>director</firstterm> prefixes. If an RE begins with <literal>***:</literal>, the rest of the RE is taken as an ARE. (This normally has no effect in <productname>PostgreSQL</productname>, since REs are assumed to be AREs; but it does have an effect if ERE or BRE mode had been specified by the <replaceable>flags</replaceable> parameter to a regex function.) If an RE begins with <literal>***=</literal>, the rest of the RE is taken to be a literal string, with all characters considered ordinary characters. </para> <para> An ARE can begin with <firstterm>embedded options</firstterm>: a sequence <literal>(?</literal><replaceable>xyz</replaceable><literal>)</literal> (where <replaceable>xyz</replaceable> is one or more alphabetic characters) specifies options affecting the rest of the RE. These options override any previously determined options — in particular, they can override the case-sensitivity behavior implied by a regex operator, or the <replaceable>flags</replaceable> parameter to a regex function. The available option letters are shown in <xref linkend="posix-embedded-options-table"/>. Note that these same option letters are used in the <replaceable>flags</replaceable> parameters of regex functions. </para> <table id="posix-embedded-options-table"> <title>ARE Embedded-Option Letters</title> <tgroup cols="2"> <thead> <row> <entry>Option</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry> <literal>b</literal> </entry> <entry> rest of RE is a BRE </entry> </row> <row> <entry> <literal>c</literal> </entry> <entry> case-sensitive matching (overrides operator type) </entry> </row> <row> <entry> <literal>e</literal> </entry> <entry> rest of RE is an ERE </entry> </row> <row> <entry> <literal>i</literal> </entry> <entry> case-insensitive matching (see <xref linkend="posix-matching-rules"/>) (overrides operator type) </entry> </row> <row> <entry> <literal>m</literal> </entry> <entry> historical synonym for <literal>n</literal> </entry> </row> <row> <entry> <literal>n</literal> </entry> <entry> newline-sensitive matching (see <xref linkend="posix-matching-rules"/>) </entry> </row> <row> <entry> <literal>p</literal> </entry> <entry> partial newline-sensitive matching (see <xref linkend="posix-matching-rules"/>) </entry> </row> <row> <entry> <literal>q</literal> </entry> <entry> rest of RE is a literal (<quote>quoted</quote>) string, all ordinary characters </entry> </row> <row> <entry> <literal>s</literal> </entry> <entry> non-newline-sensitive matching (default) </entry> </row> <row> <entry> <literal>t</literal> </entry> <entry> tight syntax (default; see below) </entry> </row> <row> <entry> <literal>w</literal> </entry> <entry> inverse partial newline-sensitive (<quote>weird</quote>) matching (see <xref linkend="posix-matching-rules"/>) </entry> </row> <row> <entry> <literal>x</literal> </entry> <entry> expanded syntax (see below) </entry> </row> </tbody> </tgroup> </table> <para> Embedded options take effect at the <literal>)</literal> terminating the sequence. They can appear only at the start of an ARE (after the <literal>***:</literal> director if any). </para> <para> In addition to the usual (<firstterm>tight</firstterm>) RE syntax, in which all characters are significant, there is an <firstterm>expanded</firstterm> syntax, available by specifying the embedded <literal>x</literal> option. In the expanded syntax, white-space characters in the RE are ignored, as are all characters between a <literal>#</literal> and the following newline (or the end of the RE). This permits paragraphing and commenting a complex RE. There are three exceptions to that basic rule: <itemizedlist> <listitem> <para> a white-space character or <literal>#</literal> preceded by <literal>\</literal> is retained </para> </listitem> <listitem> <para> white space or <literal>#</literal> within a bracket expression is retained </para> </listitem> <listitem> <para> white space and comments cannot appear within multi-character symbols, such as <literal>(?:</literal> </para> </listitem> </itemizedlist> For this purpose, white-space characters are blank, tab, newline, and any character that belongs to the <replaceable>space</replaceable> character class. </para> <para> Finally, in an ARE, outside bracket expressions, the sequence <literal>(?#</literal><replaceable>ttt</replaceable><literal>)</literal> (where <replaceable>ttt</replaceable> is any text not containing a <literal>)</literal>) is a comment, completely ignored. Again, this is not allowed between the characters of multi-character symbols, like <literal>(?:</literal>. Such comments are more a historical artifact than a useful facility, and their use is deprecated; use the expanded syntax instead. </para> <para> <emphasis>None</emphasis> of these metasyntax extensions is available if an initial <literal>***=</literal> director has specified that the user's input be treated as a literal string rather than as an RE. </para> </sect3> <sect3 id="posix-matching-rules"> <title>Regular Expression Matching Rules</title> <para> In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, either the longest possible match or the shortest possible match will be taken, depending on whether the RE is <firstterm>greedy</firstterm> or <firstterm>non-greedy</firstterm>. </para> <para> Whether an RE is greedy or not is determined by the following rules: <itemizedlist> <listitem> <para> Most atoms, and all constraints, have no greediness attribute (because they cannot match variable amounts of text anyway). </para> </listitem> <listitem> <para> Adding parentheses around an RE does not change its greediness. </para> </listitem> <listitem> <para> A quantified atom with a fixed-repetition quantifier (<literal>{</literal><replaceable>m</replaceable><literal>}</literal> or <literal>{</literal><replaceable>m</replaceable><literal>}?</literal>) has the same greediness (possibly none) as the atom itself. </para> </listitem> <listitem> <para> A quantified atom with other normal quantifiers (including <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable>< with <replaceable>m</replaceable> equal to <replaceable>n</replaceable>) is greedy (prefers longest match). </para> </listitem> <listitem> <para> A quantified atom with a non-greedy quantifier (including <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable>< with <replaceable>m</replaceable> equal to <replaceable>n</replaceable>) is non-greedy (prefers shortest match). </para> </listitem> <listitem> <para> A branch — that is, an RE that has no top-level <literal>|</literal> operator — has the same greediness as the first quantified atom in it that has a greediness attribute. </para> </listitem> <listitem> <para> An RE consisting of two or more branches connected by the <literal>|</literal> operator is always greedy. </para> </listitem> </itemizedlist> </para> <para> The above rules associate greediness attributes not only with individual quantified atoms, but with branches and entire REs that contain quantified atoms. What that means is that the matching is done in such a way that the branch, or whole RE, matches the longest or shortest possible substring <emphasis>as a whole</emphasis>. Once the length of the entire match is determined, the part of it that matches any particular subexpression is determined on the basis of the greediness attribute of that subexpression, with subexpressions starting earlier in the RE taking priority over ones starting later. </para> <para> An example of what this means: <screen> SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})'); <lineannotation>Result: </lineannotation><computeroutput>123</computeroutput> SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput> </screen> In the first case, the RE as a whole is greedy because <literal>Y*</literal> is greedy. It can match beginning at the <literal>Y</literal>, and it matches the longest possible string starting there, i.e., <literal>Y123</literal>. The output is the parenthesized part of that, or <literal>123</literal>. In the second case, the RE as a whole is non-greedy because <literal>Y*?</literal> is non-greedy. It can match beginning at the <literal>Y</literal>, and it matches the shortest possible string starting there, i.e., <literal>Y1</literal>. The subexpression <literal>[0-9]{1,3}</literal> is greedy but it cannot change the decision as to the overall match length; so it is forced to match just <literal>1</literal>. </para> <para> In short, when an RE contains both greedy and non-greedy subexpressions, the total match length is either as long as possible or as short as possible, according to the attribute assigned to the whole RE. The attributes assigned to the subexpressions only affect how much of that match they are allowed to <quote>eat</quote> relative to each other. </para> <para> The quantifiers <literal>{1,1}</literal> and <literal>{1,1}?</literal> can be used to force greediness or non-greediness, respectively, on a subexpression or a whole RE. This is useful when you need the whole RE to have a greediness attribute different from what's deduced from its elements. As an example, suppose that we are trying to separate a string containing some digits into the digits and the parts before and after them. We might try to do that like this: <screen> SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)'); <lineannotation>Result: </lineannotation><computeroutput>{abc0123,4,xyz}</computeroutput> </screen> That didn't work: the first <literal>.*</literal> is greedy so it <quote>eats</quote> as much as it can, leaving the <literal>\d+</literal> to match at the last possible place, the last digit. We might try to fix that by making it non-greedy: <screen> SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)'); <lineannotation>Result: </lineannotation><computeroutput>{abc,0,""}</computeroutput> </screen> That didn't work either, because now the RE as a whole is non-greedy and so it ends the overall match as soon as possible. We can get what we want by forcing the RE as a whole to be greedy: <screen> SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <lineannotation>Result: </lineannotation><computeroutput>{abc,01234,xyz}</computeroutput> </screen> Controlling the RE's overall greediness separately from its components' greediness allows great flexibility in handling variable-length patterns. </para> <para> When deciding what is a longer or shorter match, match lengths are measured in characters, not collating elements. An empty string is considered longer than no match at all. For example: <literal>bb*</literal> matches the three middle characters of <literal>abbbc</literal>; <literal>(week|wee)(night|knights)</literal> matches all ten characters of <literal>weeknights</literal>; when <literal>(.*).*</literal> is matched against <literal>abc</literal> the parenthesized subexpression matches all three characters; and when <literal>(a*)*</literal> is matched against <literal>bc</literal> both the whole RE and the parenthesized subexpression match an empty string. </para> <para> If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, e.g., <literal>x</literal> becomes <literal>[xX]</literal>. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, e.g., <literal>[x]</literal> becomes <literal>[xX]</literal> and <literal>[^x]</literal> becomes <literal>[^xX]</literal>. </para> <para> If newline-sensitive matching is specified, <literal>.</literal> and bracket expressions using <literal>^</literal> will never match the newline character (so that matches will not cross lines unless the RE explicitly includes a newline) and <literal>^</literal> and <literal>$</literal> will match the empty string after and before a newline respectively, in addition to matching at beginning and end of string respectively. But the ARE escapes <literal>\A</literal> and <literal>\Z</literal> continue to match beginning or end of string <emphasis>only</emphasis>. Also, the character class shorthands <literal>\D</literal> and <literal>\W</literal> will match a newline regardless of this mode. (Before <productname>PostgreSQL</productname> 14, they did not match newlines when in newline-sensitive mode. Write <literal>[^[:digit:]]</literal> or <literal>[^[:word:]]</literal> to get the old behavior.) </para> <para> If partial newline-sensitive matching is specified, this affects <literal>.</literal> and bracket expressions as with newline-sensitive matching, but not <literal>^</literal> and <literal>$</literal>. </para> <para> If inverse partial newline-sensitive matching is specified, this affects <literal>^</literal> and <literal>$</literal> as with newline-sensitive matching, but not <literal>.</literal> and bracket expressions. This isn't very useful but is provided for symmetry. </para> </sect3> <sect3 id="posix-limits-compatibility"> <title>Limits and Compatibility</title> <para> No particular limit is imposed on the length of REs in this implementation. However, programs intended to be highly portable should not employ REs longer than 256 bytes, as a POSIX-compliant implementation can refuse to accept such REs. </para> <para> The only feature of AREs that is actually incompatible with POSIX EREs is that <literal>\</literal> does not lose its special significance inside bracket expressions. All other ARE features use syntax which is illegal or has undefined or unspecified effects in POSIX EREs; the <literal>***</literal> syntax of directors likewise is outside the POSIX syntax for both BREs and EREs. </para> <para> Many of the ARE extensions are borrowed from Perl, but some have been changed to clean them up, and a few Perl extensions are not present. Incompatibilities of note include <literal>\b</literal>, <literal>\B</literal>, the lack of special treatment for a trailing newline, the addition of complemented bracket expressions to the things affected by newline-sensitive matching, the restrictions on parentheses and back references in lookahead/lookbehind constraints, and the longest/shortest-match (rather than first-match) matching semantics. </para> </sect3> <sect3 id="posix-basic-regexes"> <title>Basic Regular Expressions</title> <para> BREs differ from EREs in several respects. In BREs, <literal>|</literal>, <literal>+</literal>, and <literal>?</literal> are ordinary characters and there is no equivalent for their functionality. The delimiters for bounds are <literal>\{</literal> and <literal>\}</literal>, with <literal>{</literal> and <literal>}</literal> by themselves ordinary characters. The parentheses for nested subexpressions are <literal>\(</literal> and <literal>\)</literal>, with <literal>(</literal> and <literal>)</literal> by themselves ordinary characters. <literal>^</literal> is an ordinary character except at the beginning of the RE or the beginning of a parenthesized subexpression, <literal>$</literal> is an ordinary character except at the end of the RE or the end of a parenthesized subexpression, and <literal>*</literal> is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading <literal>^</literal>). Finally, single-digit back references are available, and <literal>\<</literal> and <literal>\></literal> are synonyms for <literal>[[:<:]]</literal> and <literal>[[:>:]]</literal> respectively; no other escapes are available in BREs. </para> </sect3> <!-- end re_syntax.n man page --> <sect3 id="posix-vs-xquery"> <title>Differences from SQL Standard and XQuery</title> <indexterm zone="posix-vs-xquery"> <primary>LIKE_REGEX</primary> </indexterm> <indexterm zone="posix-vs-xquery"> <primary>OCCURRENCES_REGEX</primary> </indexterm> <indexterm zone="posix-vs-xquery"> <primary>POSITION_REGEX</primary> </indexterm> <indexterm zone="posix-vs-xquery"> <primary>SUBSTRING_REGEX</primary> </indexterm> <indexterm zone="posix-vs-xquery"> <primary>TRANSLATE_REGEX</primary> </indexterm> <indexterm zone="posix-vs-xquery"> <primary>XQuery regular expressions</primary> </indexterm> <para> Since SQL:2008, the SQL standard includes regular expression operators and functions that performs pattern matching according to the XQuery regular expression standard: <itemizedlist> <listitem><para><literal>LIKE_REGEX</literal></para></listitem> <listitem><para><literal>OCCURRENCES_REGEX</literal></para></listitem> <listitem><para><literal>POSITION_REGEX</literal></para></listitem> <listitem><para><literal>SUBSTRING_REGEX</literal></para></listitem> <listitem><para><literal>TRANSLATE_REGEX</literal></para></listitem> </itemizedlist> <productname>PostgreSQL</productname> does not currently implement these operators and functions. You can get approximately equivalent functionality in each case as shown in <xref linkend="functions-regexp-sql-table"/>. (Various optional clauses on both sides have been omitted in this table.) </para> <table id="functions-regexp-sql-table"> <title>Regular Expression Functions Equivalencies</title> <tgroup cols="2"> <thead> <row> <entry>SQL standard</entry> <entry><productname>PostgreSQL</productname></entry> </row> </thead> <tbody> <row> <entry><literal><replaceable>string</replaceable> LIKE_REGEX <replaceable>pattern</replaceabl <entry><literal>regexp_like(<replaceable>string</replaceable>, <replaceable>pattern</replace </row> <row> <entry><literal>OCCURRENCES_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</ <entry><literal>regexp_count(<replaceable>string</replaceable>, <replaceable>pattern</replac </row> <row> <entry><literal>POSITION_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</rep <entry><literal>regexp_instr(<replaceable>string</replaceable>, <replaceable>pattern</replac </row> <row> <entry><literal>SUBSTRING_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</re <entry><literal>regexp_substr(<replaceable>string</replaceable>, <replaceable>pattern</repla </row> <row> <entry><literal>TRANSLATE_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</re <entry><literal>regexp_replace(<replaceable>string</replaceable>, <replaceable>pattern</repl </row> </tbody> </tgroup> </table> <para> Regular expression functions similar to those provided by PostgreSQL are also available in a number of other SQL implementations, whereas the SQL-standard functions are not as widely implemented. Some of the details of the regular expression syntax will likely differ in each implementation. </para> <para> The SQL-standard operators and functions use XQuery regular expressions, which are quite close to the ARE syntax described above. Notable differences between the existing POSIX-based regular-expression feature and XQuery regular expressions include: <itemizedlist> <listitem> <para> XQuery character class subtraction is not supported. An example of this feature is using the following to match only English consonants: <literal>[a-z-[aeiou]]</literal>. </para> </listitem> <listitem> <para> XQuery character class shorthands <literal>\c</literal>, <literal>\C</literal>, <literal>\i</literal>, and <literal>\I</literal> are not supported. </para> </listitem> <listitem> <para> XQuery character class elements using <literal>\p{UnicodeProperty}</literal> or the inverse <literal>\P{UnicodeProperty}</literal> are not supported. </para> </listitem> <listitem> <para> POSIX interprets character classes such as <literal>\w</literal> (see <xref linkend="posix-class-shorthand-escapes-table"/>) according to the prevailing locale (which you can control by attaching a <literal>COLLATE</literal> clause to the operator or function). XQuery specifies these classes by reference to Unicode character properties, so equivalent behavior is obtained only with a locale that follows the Unicode rules. </para> </listitem> <listitem> <para> The SQL standard (not XQuery itself) attempts to cater for more variants of <quote>newline</quote> than POSIX does. The newline-sensitive matching options described above consider only ASCII NL (<literal>\n</literal>) to be a newline, but SQL would have us treat CR (<literal>\r</literal>), CRLF (<literal>\r\n</literal>) (a Windows-style newline), and some Unicode-only characters like LINE SEPARATOR (U+2028) as newlines as well. Notably, <literal>.</literal> and <literal>\s</literal> should count <literal>\r\n</literal> as one character not two according to SQL. </para> </listitem> <listitem> <para> Of the character-entry escapes described in <xref linkend="posix-character-entry-escapes-table"/>, XQuery supports only <literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal>. </para> </listitem> <listitem> <para> XQuery does not support the <literal>[:<replaceable>name</replaceable>:]</literal> syntax for character classes within bracket expressions. </para> </listitem> <listitem> <para> XQuery does not have lookahead or lookbehind constraints, nor any of the constraint escapes described in <xref linkend="posix-constraint-escapes-table"/>. </para> </listitem> <listitem> <para> The metasyntax forms described in <xref linkend="posix-metasyntax"/> do not exist in XQuery. </para> </listitem> <listitem> <para> The regular expression flag letters defined by XQuery are related to but not the same as the option letters for POSIX (<xref linkend="posix-embedded-options-table"/>). While the <literal>i</literal> and <literal>q</literal> options behave the same, others do not: <itemizedlist> <listitem> <para> XQuery's <literal>s</literal> (allow dot to match newline) and <literal>m</literal> (allow <literal>^</literal> and <literal>$</literal> to match at newlines) flags provide access to the same behaviors as POSIX's <literal>n</literal>, <literal>p</literal> and <literal>w</literal> flags, but they do <emphasis>not</emphasis> match the behavior of POSIX's <literal>s</literal> and <literal>m</literal> flags. Note in particular that dot-matches-newline is the default behavior in POSIX but not XQuery. </para> </listitem> <listitem> <para> XQuery's <literal>x</literal> (ignore whitespace in pattern) flag is noticeably different from POSIX's expanded-mode flag. POSIX's <literal>x</literal> flag also allows <literal>#</literal> to begin a comment in the pattern, and POSIX will not ignore a whitespace character after a backslash. </para> </listitem> </itemizedlist> </para> </listitem> </itemizedlist> </para> </sect3> </sect2> </sect1> <sect1 id="functions-formatting"> <title>Data Type Formatting Functions</title> <indexterm> <primary>formatting</primary> </indexterm> <para> The <productname>PostgreSQL</productname> formatting functions provide a powerful set of tools for converting various data types (date/time, integer, floating point, numeric) to formatted strings and for converting from formatted strings to specific data types. <xref linkend="functions-formatting-table"/> lists them. These functions all follow a common calling convention: the first argument is the value to be formatted and the second argument is a template that defines the output or input format. </para> <table id="functions-formatting-table"> <title>Formatting Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_char</primary> </indexterm> <function>to_char</function> ( <type>timestamp</type>, <type>text</type> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>to_char</function> ( <type>timestamp with time zone</type>, <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts time stamp to string according to the given format. </para> <para> <literal>to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')</literal> <returnvalue>05:31:12</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>to_char</function> ( <type>interval</type>, <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts interval to string according to the given format. </para> <para> <literal>to_char(interval '15h 2m 12s', 'HH24:MI:SS')</literal> <returnvalue>15:02:12</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>to_char</function> ( <replaceable>numeric_type</replaceable>, <type>text</type> ) <returnvalue>text</returnvalue> </para> <para> Converts number to string according to the given format; available for <type>integer</type>, <type>bigint</type>, <type>numeric</type>, <type>real</type>, <type>double precision</type>. </para> <para> <literal>to_char(125, '999')</literal> <returnvalue>125</returnvalue> </para> <para> <literal>to_char(125.8::real, '999D9')</literal> <returnvalue>125.8</returnvalue> </para> <para> <literal>to_char(-125.8, '999D99S')</literal> <returnvalue>125.80-</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_date</primary> </indexterm> <function>to_date</function> ( <type>text</type>, <type>text</type> ) <returnvalue>date</returnvalue> </para> <para> Converts string to date according to the given format. </para> <para> <literal>to_date('05 Dec 2000', 'DD Mon YYYY')</literal> <returnvalue>2000-12-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_number</primary> </indexterm> <function>to_number</function> ( <type>text</type>, <type>text</type> ) <returnvalue>numeric</returnvalue> </para> <para> Converts string to numeric according to the given format. </para> <para> <literal>to_number('12,454.8-', '99G999D9S')</literal> <returnvalue>-12454.8</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_timestamp</primary> </indexterm> <function>to_timestamp</function> ( <type>text</type>, <type>text</type> ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Converts string to time stamp according to the given format. (See also <function>to_timestamp(double precision)</function> in <xref linkend="functions-datetime-table"/>.) </para> <para> <literal>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</literal> <returnvalue>2000-12-05 00:00:00-05</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <tip> <para> <function>to_timestamp</function> and <function>to_date</function> exist to handle input formats that cannot be converted by simple casting. For most standard date/time formats, simply casting the source string to the required data type works, and is much easier. Similarly, <function>to_number</function> is unnecessary for standard numeric representations. </para> </tip> <para> In a <function>to_char</function> output template string, there are certain patterns that are recognized and replaced with appropriately-formatted data based on the given value. Any text that is not a template pattern is simply copied verbatim. Similarly, in an input template string (for the other functions), template patterns identify the values to be supplied by the input data string. If there are characters in the template string that are not template patterns, the corresponding characters in the input data string are simply skipped over (whether or not they are equal to the template string characters). </para> <para> <xref linkend="functions-formatting-datetime-table"/> shows the template patterns available for formatting date and time values. </para> <table id="functions-formatting-datetime-table"> <title>Template Patterns for Date/Time Formatting</title> <tgroup cols="2"> <thead> <row> <entry>Pattern</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>HH</literal></entry> <entry>hour of day (01–12)</entry> </row> <row> <entry><literal>HH12</literal></entry> <entry>hour of day (01–12)</entry> </row> <row> <entry><literal>HH24</literal></entry> <entry>hour of day (00–23)</entry> </row> <row> <entry><literal>MI</literal></entry> <entry>minute (00–59)</entry> </row> <row> <entry><literal>SS</literal></entry> <entry>second (00–59)</entry> </row> <row> <entry><literal>MS</literal></entry> <entry>millisecond (000–999)</entry> </row> <row> <entry><literal>US</literal></entry> <entry>microsecond (000000–999999)</entry> </row> <row> <entry><literal>FF1</literal></entry> <entry>tenth of second (0–9)</entry> </row> <row> <entry><literal>FF2</literal></entry> <entry>hundredth of second (00–99)</entry> </row> <row> <entry><literal>FF3</literal></entry> <entry>millisecond (000–999)</entry> </row> <row> <entry><literal>FF4</literal></entry> <entry>tenth of a millisecond (0000–9999)</entry> </row> <row> <entry><literal>FF5</literal></entry> <entry>hundredth of a millisecond (00000–99999)</entry> </row> <row> <entry><literal>FF6</literal></entry> <entry>microsecond (000000–999999)</entry> </row> <row> <entry><literal>SSSS</literal>, <literal>SSSSS</literal></entry> <entry>seconds past midnight (0–86399)</entry> </row> <row> <entry><literal>AM</literal>, <literal>am</literal>, <literal>PM</literal> or <literal>pm</literal></entry> <entry>meridiem indicator (without periods)</entry> </row> <row> <entry><literal>A.M.</literal>, <literal>a.m.</literal>, <literal>P.M.</literal> or <literal>p.m.</literal></entry> <entry>meridiem indicator (with periods)</entry> </row> <row> <entry><literal>Y,YYY</literal></entry> <entry>year (4 or more digits) with comma</entry> </row> <row> <entry><literal>YYYY</literal></entry> <entry>year (4 or more digits)</entry> </row> <row> <entry><literal>YYY</literal></entry> <entry>last 3 digits of year</entry> </row> <row> <entry><literal>YY</literal></entry> <entry>last 2 digits of year</entry> </row> <row> <entry><literal>Y</literal></entry> <entry>last digit of year</entry> </row> <row> <entry><literal>IYYY</literal></entry> <entry>ISO 8601 week-numbering year (4 or more digits)</entry> </row> <row> <entry><literal>IYY</literal></entry> <entry>last 3 digits of ISO 8601 week-numbering year</entry> </row> <row> <entry><literal>IY</literal></entry> <entry>last 2 digits of ISO 8601 week-numbering year</entry> </row> <row> <entry><literal>I</literal></entry> <entry>last digit of ISO 8601 week-numbering year</entry> </row> <row> <entry><literal>BC</literal>, <literal>bc</literal>, <literal>AD</literal> or <literal>ad</literal></entry> <entry>era indicator (without periods)</entry> </row> <row> <entry><literal>B.C.</literal>, <literal>b.c.</literal>, <literal>A.D.</literal> or <literal>a.d.</literal></entry> <entry>era indicator (with periods)</entry> </row> <row> <entry><literal>MONTH</literal></entry> <entry>full upper case month name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>Month</literal></entry> <entry>full capitalized month name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>month</literal></entry> <entry>full lower case month name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>MON</literal></entry> <entry>abbreviated upper case month name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>Mon</literal></entry> <entry>abbreviated capitalized month name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>mon</literal></entry> <entry>abbreviated lower case month name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>MM</literal></entry> <entry>month number (01–12)</entry> </row> <row> <entry><literal>DAY</literal></entry> <entry>full upper case day name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>Day</literal></entry> <entry>full capitalized day name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>day</literal></entry> <entry>full lower case day name (blank-padded to 9 chars)</entry> </row> <row> <entry><literal>DY</literal></entry> <entry>abbreviated upper case day name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>Dy</literal></entry> <entry>abbreviated capitalized day name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>dy</literal></entry> <entry>abbreviated lower case day name (3 chars in English, localized lengths vary)</entry> </row> <row> <entry><literal>DDD</literal></entry> <entry>day of year (001–366)</entry> </row> <row> <entry><literal>IDDD</literal></entry> <entry>day of ISO 8601 week-numbering year (001–371; day 1 of the year is Monday of the first ISO wee </row> <row> <entry><literal>DD</literal></entry> <entry>day of month (01–31)</entry> </row> <row> <entry><literal>D</literal></entry> <entry>day of the week, Sunday (<literal>1</literal>) to Saturday (<literal>7</literal>)</entry> </row> <row> <entry><literal>ID</literal></entry> <entry>ISO 8601 day of the week, Monday (<literal>1</literal>) to Sunday (<literal>7</literal>)</entr </row> <row> <entry><literal>W</literal></entry> <entry>week of month (1–5) (the first week starts on the first day of the month)</entry> </row> <row> <entry><literal>WW</literal></entry> <entry>week number of year (1–53) (the first week starts on the first day of the year)</entry> </row> <row> <entry><literal>IW</literal></entry> <entry>week number of ISO 8601 week-numbering year (01–53; the first Thursday of the year is in wee </row> <row> <entry><literal>CC</literal></entry> <entry>century (2 digits) (the twenty-first century starts on 2001-01-01)</entry> </row> <row> <entry><literal>J</literal></entry> <entry>Julian Date (integer days since November 24, 4714 BC at local midnight; see <xref linkend="datetime-julian-dates"/>)</entry> </row> <row> <entry><literal>Q</literal></entry> <entry>quarter</entry> </row> <row> <entry><literal>RM</literal></entry> <entry>month in upper case Roman numerals (I–XII; I=January)</entry> </row> <row> <entry><literal>rm</literal></entry> <entry>month in lower case Roman numerals (i–xii; i=January)</entry> </row> <row> <entry><literal>TZ</literal></entry> <entry>upper case time-zone abbreviation</entry> </row> <row> <entry><literal>tz</literal></entry> <entry>lower case time-zone abbreviation</entry> </row> <row> <entry><literal>TZH</literal></entry> <entry>time-zone hours</entry> </row> <row> <entry><literal>TZM</literal></entry> <entry>time-zone minutes</entry> </row> <row> <entry><literal>OF</literal></entry> <entry>time-zone offset from UTC (<replaceable>HH</replaceable> or <replaceable>HH</replaceable><literal>:</literal><replaceable>MM</replaceable>)</entry> </row> </tbody> </tgroup> </table> <para> Modifiers can be applied to any template pattern to alter its behavior. For example, <literal>FMMonth</literal> is the <literal>Month</literal> pattern with the <literal>FM</literal> modifier. <xref linkend="functions-formatting-datetimemod-table"/> shows the modifier patterns for date/time formatting. </para> <table id="functions-formatting-datetimemod-table"> <title>Template Pattern Modifiers for Date/Time Formatting</title> <tgroup cols="3"> <thead> <row> <entry>Modifier</entry> <entry>Description</entry> <entry>Example</entry> </row> </thead> <tbody> <row> <entry><literal>FM</literal> prefix</entry> <entry>fill mode (suppress leading zeroes and padding blanks)</entry> <entry><literal>FMMonth</literal></entry> </row> <row> <entry><literal>TH</literal> suffix</entry> <entry>upper case ordinal number suffix</entry> <entry><literal>DDTH</literal>, e.g., <literal>12TH</literal></entry> </row> <row> <entry><literal>th</literal> suffix</entry> <entry>lower case ordinal number suffix</entry> <entry><literal>DDth</literal>, e.g., <literal>12th</literal></entry> </row> <row> <entry><literal>FX</literal> prefix</entry> <entry>fixed format global option (see usage notes)</entry> <entry><literal>FX Month DD Day</literal></entry> </row> <row> <entry><literal>TM</literal> prefix</entry> <entry>translation mode (use localized day and month names based on <xref linkend="guc-lc-time"/>)</entry> <entry><literal>TMMonth</literal></entry> </row> <row> <entry><literal>SP</literal> suffix</entry> <entry>spell mode (not implemented)</entry> <entry><literal>DDSP</literal></entry> </row> </tbody> </tgroup> </table> <para> Usage notes for date/time formatting: <itemizedlist> <listitem> <para> <literal>FM</literal> suppresses leading zeroes and trailing blanks that would otherwise be added to make the output of a pattern be fixed-width. In <productname>PostgreSQL</productname>, <literal>FM</literal> modifies only the next specification, while in Oracle <literal>FM</literal> affects all subsequent specifications, and repeated <literal>FM</literal> modifiers toggle fill mode on and off. </para> </listitem> <listitem> <para> <literal>TM</literal> suppresses trailing blanks whether or not <literal>FM</literal> is specified. </para> </listitem> <listitem> <para> <function>to_timestamp</function> and <function>to_date</function> ignore letter case in the input; so for example <literal>MON</literal>, <literal>Mon</literal>, and <literal>mon</literal> all accept the same strings. When using the <literal>TM</literal> modifier, case-folding is done according to the rules of the function's input collation (see <xref linkend="collation"/>). </para> </listitem> <listitem> <para> <function>to_timestamp</function> and <function>to_date</function> skip multiple blank spaces at the beginning of the input string and around date and time values unless the <literal>FX</literal> option is used. For example, <literal>to_timestamp(' 2000 JUN', 'YYYY MON')</literal> and <literal>to_timestamp('2000 - JUN', 'YYYY-MON')</literal> work, but <literal>to_timestamp('2000 JUN', 'FXYYYY MON')</literal> returns an error because <function>to_timestamp</function> expects only a single space. <literal>FX</literal> must be specified as the first item in the template. </para> </listitem> <listitem> <para> A separator (a space or non-letter/non-digit character) in the template string of <function>to_timestamp</function> and <function>to_date</function> matches any single separator in the input string or is skipped, unless the <literal>FX</literal> option is used. For example, <literal>to_timestamp('2000JUN', 'YYYY///MON')</literal> and <literal>to_timestamp('2000/JUN', 'YYYY MON')</literal> work, but <literal>to_timestamp('2000//JUN', 'YYYY/MON')</literal> returns an error because the number of separators in the input string exceeds the number of separators in the template. </para> <para> If <literal>FX</literal> is specified, a separator in the template string matches exactly one character in the input string. But note that the input string character is not required to be the same as the separator from the template string. For example, <literal>to_timestamp('2000/JUN', 'FXYYYY MON')</literal> works, but <literal>to_timestamp('2000/JUN', 'FXYYYY MON')</literal> returns an error because the second space in the template string consumes the letter <literal>J</literal> from the input string. </para> </listitem> <listitem> <para> A <literal>TZH</literal> template pattern can match a signed number. Without the <literal>FX</literal> option, minus signs may be ambiguous, and could be interpreted as a separator. This ambiguity is resolved as follows: If the number of separators before <literal>TZH</literal> in the template string is less than the number of separators before the minus sign in the input string, the minus sign is interpreted as part of <literal>TZH</literal>. Otherwise, the minus sign is considered to be a separator between values. For example, <literal>to_timestamp('2000 -10', 'YYYY TZH')</literal> matches <literal>-10</literal> to <literal>TZH</literal>, but <literal>to_timestamp('2000 -10', 'YYYY TZH')</literal> matches <literal>10</literal> to <literal>TZH</literal>. </para> </listitem> <listitem> <para> Ordinary text is allowed in <function>to_char</function> templates and will be output literally. You can put a substring in double quotes to force it to be interpreted as literal text even if it contains template patterns. For example, in <literal>'"Hello Year "YYYY'</literal>, the <literal>YYYY</literal> will be replaced by the year data, but the single <literal>Y</literal> in <literal>Year</literal> will not be. In <function>to_date</function>, <function>to_number</function>, and <function>to_timestamp</function>, literal text and double-quoted strings result in skipping the number of characters contained in the string; for example <literal>"XX"</literal> skips two input characters (whether or not they are <literal>XX</literal>). </para> <tip> <para> Prior to <productname>PostgreSQL</productname> 12, it was possible to skip arbitrary text in the input string using non-letter or non-digit characters. For example, <literal>to_timestamp('2000y6m1d', 'yyyy-MM-DD')</literal> used to work. Now you can only use letter characters for this purpose. For example, <literal>to_timestamp('2000y6m1d', 'yyyytMMtDDt')</literal> and <literal>to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"')</literal> skip <literal>y</literal>, <literal>m</literal>, and <literal>d</literal>. </para> </tip> </listitem> <listitem> <para> If you want to have a double quote in the output you must precede it with a backslash, for example <literal>'\"YYYY Month\"'</literal>. <!-- "" font-lock sanity :-) --> Backslashes are not otherwise special outside of double-quoted strings. Within a double-quoted string, a backslash causes the next character to be taken literally, whatever it is (but this has no special effect unless the next character is a double quote or another backslash). </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, if the year format specification is less than four digits, e.g., <literal>YYY</literal>, and the supplied year is less than four digits, the year will be adjusted to be nearest to the year 2020, e.g., <literal>95</literal> becomes 1995. </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, negative years are treated as signifying BC. If you write both a negative year and an explicit <literal>BC</literal> field, you get AD again. An input of year zero is treated as 1 BC. </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, the <literal>YYYY</literal> conversion has a restriction when processing years with more than 4 digits. You must use some non-digit character or template after <literal>YYYY</literal>, otherwise the year is always interpreted as 4 digits. For example (with the year 20000): <literal>to_date('200001130', 'YYYYMMDD')</literal> will be interpreted as a 4-digit year; instead use a non-digit separator after the year, like <literal>to_date('20000-1130', 'YYYY-MMDD')</literal> or <literal>to_date('20000Nov30', 'YYYYMonDD')</literal>. </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, the <literal>CC</literal> (century) field is accepted but ignored if there is a <literal>YYY</literal>, <literal>YYYY</literal> or <literal>Y,YYY</literal> field. If <literal>CC</literal> is used with <literal>YY</literal> or <literal>Y</literal> then the result is computed as that year in the specified century. If the century is specified but the year is not, the first year of the century is assumed. </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, weekday names or numbers (<literal>DAY</literal>, <literal>D</literal>, and related field types) are accepted but are ignored for purposes of computing the result. The same is true for quarter (<literal>Q</literal>) fields. </para> </listitem> <listitem> <para> In <function>to_timestamp</function> and <function>to_date</function>, an ISO 8601 week-numbering date (as distinct from a Gregorian date) can be specified in one of two ways: <itemizedlist> <listitem> <para> Year, week number, and weekday: for example <literal>to_date('2006-42-4', 'IYYY-IW-ID')</literal> returns the date <literal>2006-10-19</literal>. If you omit the weekday it is assumed to be 1 (Monday). </para> </listitem> <listitem> <para> Year and day of year: for example <literal>to_date('2006-291', 'IYYY-IDDD')</literal> also returns <literal>2006-10-19</literal>. </para> </listitem> </itemizedlist> </para> <para> Attempting to enter a date using a mixture of ISO 8601 week-numbering fields and Gregorian date fields is nonsensical, and will cause an error. In the context of an ISO 8601 week-numbering year, the concept of a <quote>month</quote> or <quote>day of month</quote> has no meaning. In the context of a Gregorian year, the ISO week has no meaning. </para> <caution> <para> While <function>to_date</function> will reject a mixture of Gregorian and ISO week-numbering date fields, <function>to_char</function> will not, since output format specifications like <literal>YYYY-MM-DD (IYYY-IDDD)</literal> can be useful. But avoid writing something like <literal>IYYY-MM-DD</literal>; that would yield surprising results near the start of the year. (See <xref linkend="functions-datetime-extract"/> for more information.) </para> </caution> </listitem> <listitem> <para> In <function>to_timestamp</function>, millisecond (<literal>MS</literal>) or microsecond (<literal>US</literal>) fields are used as the seconds digits after the decimal point. For example <literal>to_timestamp('12.3', 'SS.MS')</literal> is not 3 milliseconds, but 300, because the conversion treats it as 12 + 0.3 seconds. So, for the format <literal>SS.MS</literal>, the input values <literal>12.3</literal>, <literal>12.30</literal>, and <literal>12.300</literal> specify the same number of milliseconds. To get three milliseconds, one must write <literal>12.003</literal>, which the conversion treats as 12 + 0.003 = 12.003 seconds. </para> <para> Here is a more complex example: <literal>to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')</literal> is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230 microseconds = 2.021230 seconds. </para> </listitem> <listitem> <para> <function>to_char(..., 'ID')</function>'s day of the week numbering matches the <function>extract(isodow from ...)</function> function, but <function>to_char(..., 'D')</function>'s does not match <function>extract(dow from ...)</function>'s day numbering. </para> </listitem> <listitem> <para> <function>to_char(interval)</function> formats <literal>HH</literal> and <literal>HH12</literal> as shown on a 12-hour clock, for example zero hours and 36 hours both output as <literal>12</literal>, while <literal>HH24</literal> outputs the full hour value, which can exceed 23 in an <type>interval</type> value. </para> </listitem> </itemizedlist> </para> <para> <xref linkend="functions-formatting-numeric-table"/> shows the template patterns available for formatting numeric values. </para> <table id="functions-formatting-numeric-table"> <title>Template Patterns for Numeric Formatting</title> <tgroup cols="2"> <thead> <row> <entry>Pattern</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>9</literal></entry> <entry>digit position (can be dropped if insignificant)</entry> </row> <row> <entry><literal>0</literal></entry> <entry>digit position (will not be dropped, even if insignificant)</entry> </row> <row> <entry><literal>.</literal> (period)</entry> <entry>decimal point</entry> </row> <row> <entry><literal>,</literal> (comma)</entry> <entry>group (thousands) separator</entry> </row> <row> <entry><literal>PR</literal></entry> <entry>negative value in angle brackets</entry> </row> <row> <entry><literal>S</literal></entry> <entry>sign anchored to number (uses locale)</entry> </row> <row> <entry><literal>L</literal></entry> <entry>currency symbol (uses locale)</entry> </row> <row> <entry><literal>D</literal></entry> <entry>decimal point (uses locale)</entry> </row> <row> <entry><literal>G</literal></entry> <entry>group separator (uses locale)</entry> </row> <row> <entry><literal>MI</literal></entry> <entry>minus sign in specified position (if number < 0)</entry> </row> <row> <entry><literal>PL</literal></entry> <entry>plus sign in specified position (if number > 0)</entry> </row> <row> <entry><literal>SG</literal></entry> <entry>plus/minus sign in specified position</entry> </row> <row> <entry><literal>RN</literal> or <literal>rn</literal></entry> <entry>Roman numeral (values between 1 and 3999)</entry> </row> <row> <entry><literal>TH</literal> or <literal>th</literal></entry> <entry>ordinal number suffix</entry> </row> <row> <entry><literal>V</literal></entry> <entry>shift specified number of digits (see notes)</entry> </row> <row> <entry><literal>EEEE</literal></entry> <entry>exponent for scientific notation</entry> </row> </tbody> </tgroup> </table> <para> Usage notes for numeric formatting: <itemizedlist> <listitem> <para> <literal>0</literal> specifies a digit position that will always be printed, even if it contains a leading/trailing zero. <literal>9</literal> also specifies a digit position, but if it is a leading zero then it will be replaced by a space, while if it is a trailing zero and fill mode is specified then it will be deleted. (For <function>to_number()</function>, these two pattern characters are equivalent.) </para> </listitem> <listitem> <para> If the format provides fewer fractional digits than the number being formatted, <function>to_char()</function> will round the number to the specified number of fractional digits. </para> </listitem> <listitem> <para> The pattern characters <literal>S</literal>, <literal>L</literal>, <literal>D</literal>, and <literal>G</literal> represent the sign, currency symbol, decimal point, and thousands separator characters defined by the current locale (see <xref linkend="guc-lc-monetary"/> and <xref linkend="guc-lc-numeric"/>). The pattern characters period and comma represent those exact characters, with the meanings of decimal point and thousands separator, regardless of locale. </para> </listitem> <listitem> <para> If no explicit provision is made for a sign in <function>to_char()</function>'s pattern, one column will be reserved for the sign, and it will be anchored to (appear just left of) the number. If <literal>S</literal> appears just left of some <literal>9</literal>'s, it will likewise be anchored to the number. </para> </listitem> <listitem> <para> A sign formatted using <literal>SG</literal>, <literal>PL</literal>, or <literal>MI</literal> is not anchored to the number; for example, <literal>to_char(-12, 'MI9999')</literal> produces <literal>'- 12'</literal> but <literal>to_char(-12, 'S9999')</literal> produces <literal>' -12'</literal>. (The Oracle implementation does not allow the use of <literal>MI</literal> before <literal>9</literal>, but rather requires that <literal>9</literal> precede <literal>MI</literal>.) </para> </listitem> <listitem> <para> <literal>TH</literal> does not convert values less than zero and does not convert fractional numbers. </para> </listitem> <listitem> <para> <literal>PL</literal>, <literal>SG</literal>, and <literal>TH</literal> are <productname>PostgreSQL</productname> extensions. </para> </listitem> <listitem> <para> In <function>to_number</function>, if non-data template patterns such as <literal>L</literal> or <literal>TH</literal> are used, the corresponding number of input characters are skipped, whether or not they match the template pattern, unless they are data characters (that is, digits, sign, decimal point, or comma). For example, <literal>TH</literal> would skip two non-data characters. </para> </listitem> <listitem> <para> <literal>V</literal> with <function>to_char</function> multiplies the input values by <literal>10^<replaceable>n</replaceable></literal>, where <replaceable>n</replaceable> is the number of digits following <literal>V</literal>. <literal>V</literal> with <function>to_number</function> divides in a similar manner. The <literal>V</literal> can be thought of as marking the position of an implicit decimal point in the input or output string. <function>to_char</function> and <function>to_number</function> do not support the use of <literal>V</literal> combined with a decimal point (e.g., <literal>99.9V99</literal> is not allowed). </para> </listitem> <listitem> <para> <literal>EEEE</literal> (scientific notation) cannot be used in combination with any of the other formatting patterns or modifiers other than digit and decimal point patterns, and must be at the end of the format strin (e.g., <literal>9.99EEEE</literal> is a valid pattern). </para> </listitem> <listitem> <para> In <function>to_number()</function>, the <literal>RN</literal> pattern converts Roman numerals (in standard form) to numbers. Input is case-insensitive, so <literal>RN</literal> and <literal>rn</literal> are equivalent. <literal>RN</literal> cannot be used in combination with any other formatting patterns or modifiers except <literal>FM</literal>, which is applicable only in <function>to_char()</function> and is ignored in <function>to_number()</function>. </para> </listitem> </itemizedlist> </para> <para> Certain modifiers can be applied to any template pattern to alter its behavior. For example, <literal>FM99.99</literal> is the <literal>99.99</literal> pattern with the <literal>FM</literal> modifier. <xref linkend="functions-formatting-numericmod-table"/> shows the modifier patterns for numeric formatting. </para> <table id="functions-formatting-numericmod-table"> <title>Template Pattern Modifiers for Numeric Formatting</title> <tgroup cols="3"> <thead> <row> <entry>Modifier</entry> <entry>Description</entry> <entry>Example</entry> </row> </thead> <tbody> <row> <entry><literal>FM</literal> prefix</entry> <entry>fill mode (suppress trailing zeroes and padding blanks)</entry> <entry><literal>FM99.99</literal></entry> </row> <row> <entry><literal>TH</literal> suffix</entry> <entry>upper case ordinal number suffix</entry> <entry><literal>999TH</literal></entry> </row> <row> <entry><literal>th</literal> suffix</entry> <entry>lower case ordinal number suffix</entry> <entry><literal>999th</literal></entry> </row> </tbody> </tgroup> </table> <para> <xref linkend="functions-formatting-examples-table"/> shows some examples of the use of the <function>to_char</function> function. </para> <table id="functions-formatting-examples-table"> <title><function>to_char</function> Examples</title> <tgroup cols="2"> <thead> <row> <entry>Expression</entry> <entry>Result</entry> </row> </thead> <tbody> <row> <entry><literal>to_char(current_timestamp, 'Day, DD HH12:MI:SS')</literal></entry> <entry><literal>'Tuesday , 06 05:39:18'</literal></entry> </row> <row> <entry><literal>to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS')</literal></entry> <entry><literal>'Tuesday, 6 05:39:18'</literal></entry> </row> <row> <entry><literal>to_char(current_timestamp AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')</literal></entry> <entry><literal>'2022-12-06T05:39:18Z'</literal>, <acronym>ISO</acronym> 8601 extended format</entry> </row> <row> <entry><literal>to_char(-0.1, '99.99')</literal></entry> <entry><literal>' -.10'</literal></entry> </row> <row> <entry><literal>to_char(-0.1, 'FM9.99')</literal></entry> <entry><literal>'-.1'</literal></entry> </row> <row> <entry><literal>to_char(-0.1, 'FM90.99')</literal></entry> <entry><literal>'-0.1'</literal></entry> </row> <row> <entry><literal>to_char(0.1, '0.9')</literal></entry> <entry><literal>' 0.1'</literal></entry> </row> <row> <entry><literal>to_char(12, '9990999.9')</literal></entry> <entry><literal>' 0012.0'</literal></entry> </row> <row> <entry><literal>to_char(12, 'FM9990999.9')</literal></entry> <entry><literal>'0012.'</literal></entry> </row> <row> <entry><literal>to_char(485, '999')</literal></entry> <entry><literal>' 485'</literal></entry> </row> <row> <entry><literal>to_char(-485, '999')</literal></entry> <entry><literal>'-485'</literal></entry> </row> <row> <entry><literal>to_char(485, '9 9 9')</literal></entry> <entry><literal>' 4 8 5'</literal></entry> </row> <row> <entry><literal>to_char(1485, '9,999')</literal></entry> <entry><literal>' 1,485'</literal></entry> </row> <row> <entry><literal>to_char(1485, '9G999')</literal></entry> <entry><literal>' 1 485'</literal></entry> </row> <row> <entry><literal>to_char(148.5, '999.999')</literal></entry> <entry><literal>' 148.500'</literal></entry> </row> <row> <entry><literal>to_char(148.5, 'FM999.999')</literal></entry> <entry><literal>'148.5'</literal></entry> </row> <row> <entry><literal>to_char(148.5, 'FM999.990')</literal></entry> <entry><literal>'148.500'</literal></entry> </row> <row> <entry><literal>to_char(148.5, '999D999')</literal></entry> <entry><literal>' 148,500'</literal></entry> </row> <row> <entry><literal>to_char(3148.5, '9G999D999')</literal></entry> <entry><literal>' 3 148,500'</literal></entry> </row> <row> <entry><literal>to_char(-485, '999S')</literal></entry> <entry><literal>'485-'</literal></entry> </row> <row> <entry><literal>to_char(-485, '999MI')</literal></entry> <entry><literal>'485-'</literal></entry> </row> <row> <entry><literal>to_char(485, '999MI')</literal></entry> <entry><literal>'485 '</literal></entry> </row> <row> <entry><literal>to_char(485, 'FM999MI')</literal></entry> <entry><literal>'485'</literal></entry> </row> <row> <entry><literal>to_char(485, 'PL999')</literal></entry> <entry><literal>'+485'</literal></entry> </row> <row> <entry><literal>to_char(485, 'SG999')</literal></entry> <entry><literal>'+485'</literal></entry> </row> <row> <entry><literal>to_char(-485, 'SG999')</literal></entry> <entry><literal>'-485'</literal></entry> </row> <row> <entry><literal>to_char(-485, '9SG99')</literal></entry> <entry><literal>'4-85'</literal></entry> </row> <row> <entry><literal>to_char(-485, '999PR')</literal></entry> <entry><literal>'<485>'</literal></entry> </row> <row> <entry><literal>to_char(485, 'L999')</literal></entry> <entry><literal>'DM 485'</literal></entry> </row> <row> <entry><literal>to_char(485, 'RN')</literal></entry> <entry><literal>' CDLXXXV'</literal></entry> </row> <row> <entry><literal>to_char(485, 'FMRN')</literal></entry> <entry><literal>'CDLXXXV'</literal></entry> </row> <row> <entry><literal>to_char(5.2, 'FMRN')</literal></entry> <entry><literal>'V'</literal></entry> </row> <row> <entry><literal>to_char(482, '999th')</literal></entry> <entry><literal>' 482nd'</literal></entry> </row> <row> <entry><literal>to_char(485, '"Good number:"999')</literal></entry> <entry><literal>'Good number: 485'</literal></entry> </row> <row> <entry><literal>to_char(485.8, '"Pre:"999" Post:" .999')</literal></entry> <entry><literal>'Pre: 485 Post: .800'</literal></entry> </row> <row> <entry><literal>to_char(12, '99V999')</literal></entry> <entry><literal>' 12000'</literal></entry> </row> <row> <entry><literal>to_char(12.4, '99V999')</literal></entry> <entry><literal>' 12400'</literal></entry> </row> <row> <entry><literal>to_char(12.45, '99V9')</literal></entry> <entry><literal>' 125'</literal></entry> </row> <row> <entry><literal>to_char(0.0004859, '9.99EEEE')</literal></entry> <entry><literal>' 4.86e-04'</literal></entry> </row> </tbody> </tgroup> </table> </sect1> <sect1 id="functions-datetime"> <title>Date/Time Functions and Operators</title> <para> <xref linkend="functions-datetime-table"/> shows the available functions for date/time value processing, with details appearing in the following subsections. <xref linkend="operators-datetime-table"/> illustrates the behaviors of the basic arithmetic operators (<literal>+</literal>, <literal>*</literal>, etc.). For formatting functions, refer to <xref linkend="functions-formatting"/>. You should be familiar with the background information on date/time data types from <xref linkend="datatype-datetime"/>. </para> <para> In addition, the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> are available for the date/time types. Dates and timestamps (with or without time zone) are all comparable, while times (with or without time zone) and intervals can only be compared to other values of the same data type. When comparing a timestamp without time zone to a timestamp with time zone, the former value is assumed to be given in the time zone specified by the <xref linkend="guc-timezone"/> configuration parameter, and is rotated to UTC for comparison to the latter value (which is already in UTC internally). Similarly, a date value is assumed to represent midnight in the <varname>TimeZone</varname> zone when comparing it to a timestamp. </para> <para> All the functions and operators described below that take <type>time</type> or <type>timestamp</ty inputs actually come in two variants: one that takes <type>time with time zone</type> or <type>times with time zone</type>, and one that takes <type>time without time zone</type> or <type>timestamp with For brevity, these variants are not shown separately. Also, the <literal>+</literal> and <literal>*</literal> operators come in commutative pairs (for example both <type>date</type> <literal>+</literal> <type>integer</type> and <type>integer</type> <literal>+</literal> <type>date</type>); we show only one of each such pair. </para> <table id="operators-datetime-table"> <title>Date/Time Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>+</literal> <type>integer</type> <returnvalue>date</returnvalue> </para> <para> Add a number of days to a date </para> <para> <literal>date '2001-09-28' + 7</literal> <returnvalue>2001-10-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>+</literal> <type>interval</type> <returnvalue>timestamp</returnvalue> </para> <para> Add an interval to a date </para> <para> <literal>date '2001-09-28' + interval '1 hour'</literal> <returnvalue>2001-09-28 01:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>+</literal> <type>time</type> <returnvalue>timestamp</returnvalue> </para> <para> Add a time-of-day to a date </para> <para> <literal>date '2001-09-28' + time '03:00'</literal> <returnvalue>2001-09-28 03:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>interval</type> <literal>+</literal> <type>interval</type> <returnvalue>interval</returnvalue> </para> <para> Add intervals </para> <para> <literal>interval '1 day' + interval '1 hour'</literal> <returnvalue>1 day 01:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp</type> <literal>+</literal> <type>interval</type> <returnvalue>timestamp</returnvalue> </para> <para> Add an interval to a timestamp </para> <para> <literal>timestamp '2001-09-28 01:00' + interval '23 hours'</literal> <returnvalue>2001-09-29 00:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>time</type> <literal>+</literal> <type>interval</type> <returnvalue>time</returnvalue> </para> <para> Add an interval to a time </para> <para> <literal>time '01:00' + interval '3 hours'</literal> <returnvalue>04:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>-</literal> <type>interval</type> <returnvalue>interval</returnvalue> </para> <para> Negate an interval </para> <para> <literal>- interval '23 hours'</literal> <returnvalue>-23:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>-</literal> <type>date</type> <returnvalue>integer</returnvalue> </para> <para> Subtract dates, producing the number of days elapsed </para> <para> <literal>date '2001-10-01' - date '2001-09-28'</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>-</literal> <type>integer</type> <returnvalue>date</returnvalue> </para> <para> Subtract a number of days from a date </para> <para> <literal>date '2001-10-01' - 7</literal> <returnvalue>2001-09-24</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>date</type> <literal>-</literal> <type>interval</type> <returnvalue>timestamp</returnvalue> </para> <para> Subtract an interval from a date </para> <para> <literal>date '2001-09-28' - interval '1 hour'</literal> <returnvalue>2001-09-27 23:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>time</type> <literal>-</literal> <type>time</type> <returnvalue>interval</returnvalue> </para> <para> Subtract times </para> <para> <literal>time '05:00' - time '03:00'</literal> <returnvalue>02:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>time</type> <literal>-</literal> <type>interval</type> <returnvalue>time</returnvalue> </para> <para> Subtract an interval from a time </para> <para> <literal>time '05:00' - interval '2 hours'</literal> <returnvalue>03:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp</type> <literal>-</literal> <type>interval</type> <returnvalue>timestamp</returnvalue> </para> <para> Subtract an interval from a timestamp </para> <para> <literal>timestamp '2001-09-28 23:00' - interval '23 hours'</literal> <returnvalue>2001-09-28 00:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>interval</type> <literal>-</literal> <type>interval</type> <returnvalue>interval</returnvalue> </para> <para> Subtract intervals </para> <para> <literal>interval '1 day' - interval '1 hour'</literal> <returnvalue>1 day -01:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp</type> <literal>-</literal> <type>timestamp</type> <returnvalue>interval</returnvalue> </para> <para> Subtract timestamps (converting 24-hour intervals into days, similarly to <link linkend="function-justify-hours"><function>justify_hours()</function></link>) </para> <para> <literal>timestamp '2001-09-29 03:00' - timestamp '2001-07-27 12:00'</literal> <returnvalue>63 days 15:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>interval</type> <literal>*</literal> <type>double precision</type> <returnvalue>interval</returnvalue> </para> <para> Multiply an interval by a scalar </para> <para> <literal>interval '1 second' * 900</literal> <returnvalue>00:15:00</returnvalue> </para> <para> <literal>interval '1 day' * 21</literal> <returnvalue>21 days</returnvalue> </para> <para> <literal>interval '1 hour' * 3.5</literal> <returnvalue>03:30:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>interval</type> <literal>/</literal> <type>double precision</type> <returnvalue>interval</returnvalue> </para> <para> Divide an interval by a scalar </para> <para> <literal>interval '1 hour' / 1.5</literal> <returnvalue>00:40:00</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <table id="functions-datetime-table"> <title>Date/Time Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>age</primary> </indexterm> <function>age</function> ( <type>timestamp</type>, <type>timestamp</type> ) <returnvalue>interval</returnvalue> </para> <para> Subtract arguments, producing a <quote>symbolic</quote> result that uses years and months, rather than just days </para> <para> <literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal> <returnvalue>43 years 9 mons 27 days</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>age</function> ( <type>timestamp</type> ) <returnvalue>interval</returnvalue> </para> <para> Subtract argument from <function>current_date</function> (at midnight) </para> <para> <literal>age(timestamp '1957-06-13')</literal> <returnvalue>62 years 6 mons 10 days</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>clock_timestamp</primary> </indexterm> <function>clock_timestamp</function> ( ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (changes during statement execution); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>clock_timestamp()</literal> <returnvalue>2019-12-23 14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>current_date</primary> </indexterm> <function>current_date</function> <returnvalue>date</returnvalue> </para> <para> Current date; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>current_date</literal> <returnvalue>2019-12-23</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>current_time</primary> </indexterm> <function>current_time</function> <returnvalue>time with time zone</returnvalue> </para> <para> Current time of day; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>current_time</literal> <returnvalue>14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>current_time</function> ( <type>integer</type> ) <returnvalue>time with time zone</returnvalue> </para> <para> Current time of day, with limited precision; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>current_time(2)</literal> <returnvalue>14:39:53.66-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>current_timestamp</primary> </indexterm> <function>current_timestamp</function> <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (start of current transaction); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>current_timestamp</literal> <returnvalue>2019-12-23 14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>current_timestamp</function> ( <type>integer</type> ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (start of current transaction), with limited precision; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>current_timestamp(0)</literal> <returnvalue>2019-12-23 14:39:53-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>date_add</primary> </indexterm> <function>date_add</function> ( <type>timestamp with time zone</type>, <type>interval</type> <option <returnvalue>timestamp with time zone</returnvalue> </para> <para> Add an <type>interval</type> to a <type>timestamp with time zone</type>, computing times of day and daylight-savings adjustments according to the time zone named by the third argument, or the current <xref linkend="guc-timezone"/> setting if that is omitted. The form with two arguments is equivalent to the <type>timestamp with time zone</type> <literal>+</literal> <type>interval</type> operator. </para> <para> <literal>date_add('2021-10-31 00:00:00+02'::timestamptz, '1 day'::interval, 'Europe/Wa <returnvalue>2021-10-31 23:00:00+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>date_bin</function> ( <type>interval</type>, <type>timestamp</type>, <type>timestamp</typ <returnvalue>timestamp</returnvalue> </para> <para> Bin input into specified interval aligned with specified origin; see <xref linkend="function </para> <para> <literal>date_bin('15 minutes', timestamp '2001-02-16 20:38:40', timestamp '2001-02-16 20 <returnvalue>2001-02-16 20:35:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>date_part</primary> </indexterm> <function>date_part</function> ( <type>text</type>, <type>timestamp</type> ) <returnvalue>double precision</returnvalue> </para> <para> Get timestamp subfield (equivalent to <function>extract</function>); see <xref linkend="functions-datetime-extract"/> </para> <para> <literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal> <returnvalue>20</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>date_part</function> ( <type>text</type>, <type>interval</type> ) <returnvalue>double precision</returnvalue> </para> <para> Get interval subfield (equivalent to <function>extract</function>); see <xref linkend="functions-datetime-extract"/> </para> <para> <literal>date_part('month', interval '2 years 3 months')</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>date_subtract</primary> </indexterm> <function>date_subtract</function> ( <type>timestamp with time zone</type>, <type>interval</type> <o <returnvalue>timestamp with time zone</returnvalue> </para> <para> Subtract an <type>interval</type> from a <type>timestamp with time zone</type>, computing times of day and daylight-savings adjustments according to the time zone named by the third argument, or the current <xref linkend="guc-timezone"/> setting if that is omitted. The form with two arguments is equivalent to the <type>timestamp with time zone</type> <literal>-</literal> <type>interval</type> operator. </para> <para> <literal>date_subtract('2021-11-01 00:00:00+01'::timestamptz, '1 day'::interval, 'Euro <returnvalue>2021-10-30 22:00:00+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>date_trunc</primary> </indexterm> <function>date_trunc</function> ( <type>text</type>, <type>timestamp</type> ) <returnvalue>timestamp</returnvalue> </para> <para> Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/> </para> <para> <literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal> <returnvalue>2001-02-16 20:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>date_trunc</function> ( <type>text</type>, <type>timestamp with time zone</type>, <type>tex <returnvalue>timestamp with time zone</returnvalue> </para> <para> Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/> </para> <para> <literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</l <returnvalue>2001-02-16 13:00:00+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>date_trunc</function> ( <type>text</type>, <type>interval</type> ) <returnvalue>interval</returnvalue> </para> <para> Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/> </para> <para> <literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal> <returnvalue>2 days 03:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>extract</primary> </indexterm> <function>extract</function> ( <parameter>field</parameter> <literal>from</literal> <type>timestam <returnvalue>numeric</returnvalue> </para> <para> Get timestamp subfield; see <xref linkend="functions-datetime-extract"/> </para> <para> <literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal> <returnvalue>20</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>extract</function> ( <parameter>field</parameter> <literal>from</literal> <type>interval< <returnvalue>numeric</returnvalue> </para> <para> Get interval subfield; see <xref linkend="functions-datetime-extract"/> </para> <para> <literal>extract(month from interval '2 years 3 months')</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>isfinite</primary> </indexterm> <function>isfinite</function> ( <type>date</type> ) <returnvalue>boolean</returnvalue> </para> <para> Test for finite date (not +/-infinity) </para> <para> <literal>isfinite(date '2001-02-16')</literal> <returnvalue>true</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>isfinite</function> ( <type>timestamp</type> ) <returnvalue>boolean</returnvalue> </para> <para> Test for finite timestamp (not +/-infinity) </para> <para> <literal>isfinite(timestamp 'infinity')</literal> <returnvalue>false</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>isfinite</function> ( <type>interval</type> ) <returnvalue>boolean</returnvalue> </para> <para> Test for finite interval (not +/-infinity) </para> <para> <literal>isfinite(interval '4 hours')</literal> <returnvalue>true</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-justify-days"> <primary>justify_days</primary> </indexterm> <function>justify_days</function> ( <type>interval</type> ) <returnvalue>interval</returnvalue> </para> <para> Adjust interval, converting 30-day time periods to months </para> <para> <literal>justify_days(interval '1 year 65 days')</literal> <returnvalue>1 year 2 mons 5 days</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm id="function-justify-hours"> <primary>justify_hours</primary> </indexterm> <function>justify_hours</function> ( <type>interval</type> ) <returnvalue>interval</returnvalue> </para> <para> Adjust interval, converting 24-hour time periods to days </para> <para> <literal>justify_hours(interval '50 hours 10 minutes')</literal> <returnvalue>2 days 02:10:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>justify_interval</primary> </indexterm> <function>justify_interval</function> ( <type>interval</type> ) <returnvalue>interval</returnvalue> </para> <para> Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments </para> <para> <literal>justify_interval(interval '1 mon -1 hour')</literal> <returnvalue>29 days 23:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>localtime</primary> </indexterm> <function>localtime</function> <returnvalue>time</returnvalue> </para> <para> Current time of day; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>localtime</literal> <returnvalue>14:39:53.662522</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>localtime</function> ( <type>integer</type> ) <returnvalue>time</returnvalue> </para> <para> Current time of day, with limited precision; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>localtime(0)</literal> <returnvalue>14:39:53</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>localtimestamp</primary> </indexterm> <function>localtimestamp</function> <returnvalue>timestamp</returnvalue> </para> <para> Current date and time (start of current transaction); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>localtimestamp</literal> <returnvalue>2019-12-23 14:39:53.662522</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>localtimestamp</function> ( <type>integer</type> ) <returnvalue>timestamp</returnvalue> </para> <para> Current date and time (start of current transaction), with limited precision; see <xref linkend="functions-datetime-current"/> </para> <para> <literal>localtimestamp(2)</literal> <returnvalue>2019-12-23 14:39:53.66</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>make_date</primary> </indexterm> <function>make_date</function> ( <parameter>year</parameter> <type>int</type>, <parameter>month</parameter> <type>int</type>, <parameter>day</parameter> <type>int</type> ) <returnvalue>date</returnvalue> </para> <para> Create date from year, month and day fields (negative years signify BC) </para> <para> <literal>make_date(2013, 7, 15)</literal> <returnvalue>2013-07-15</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"><indexterm> <primary>make_interval</primary> </indexterm> <function>make_interval</function> ( <optional> <parameter>years</parameter> <type>int</type> <optional>, <parameter>months</parameter> <type>int</type> <optional>, <parameter>weeks</parameter> <type>int</type> <optional>, <parameter>days</parameter> <type>int</type> <optional>, <parameter>hours</parameter> <type>int</type> <optional>, <parameter>mins</parameter> <type>int</type> <optional>, <parameter>secs</parameter> <type>double precision</type> </optional></optional></optional></optional></optional></optional></optional> ) <returnvalue>interval</returnvalue> </para> <para> Create interval from years, months, weeks, days, hours, minutes and seconds fields, each of which can default to zero </para> <para> <literal>make_interval(days => 10)</literal> <returnvalue>10 days</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>make_time</primary> </indexterm> <function>make_time</function> ( <parameter>hour</parameter> <type>int</type>, <parameter>min</parameter> <type>int</type>, <parameter>sec</parameter> <type>double precision</type> ) <returnvalue>time</returnvalue> </para> <para> Create time from hour, minute and seconds fields </para> <para> <literal>make_time(8, 15, 23.5)</literal> <returnvalue>08:15:23.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>make_timestamp</primary> </indexterm> <function>make_timestamp</function> ( <parameter>year</parameter> <type>int</type>, <parameter>month</parameter> <type>int</type>, <parameter>day</parameter> <type>int</type>, <parameter>hour</parameter> <type>int</type>, <parameter>min</parameter> <type>int</type>, <parameter>sec</parameter> <type>double precision</type> ) <returnvalue>timestamp</returnvalue> </para> <para> Create timestamp from year, month, day, hour, minute and seconds fields (negative years signify BC) </para> <para> <literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal> <returnvalue>2013-07-15 08:15:23.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>make_timestamptz</primary> </indexterm> <function>make_timestamptz</function> ( <parameter>year</parameter> <type>int</type>, <parameter>month</parameter> <type>int</type>, <parameter>day</parameter> <type>int</type>, <parameter>hour</parameter> <type>int</type>, <parameter>min</parameter> <type>int</type>, <parameter>sec</parameter> <type>double precision</type> <optional>, <parameter>timezone</parameter> <type>text</type> </optional> ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Create timestamp with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If <parameter>timezone</parameter> is not specified, the current time zone is used; the examples assume the session time zone is <literal>Europe/London</literal> </para> <para> <literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal> <returnvalue>2013-07-15 08:15:23.5+01</returnvalue> </para> <para> <literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5, 'America/New_York')</literal> <returnvalue>2013-07-15 13:15:23.5+01</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>now</primary> </indexterm> <function>now</function> ( ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (start of current transaction); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>now()</literal> <returnvalue>2019-12-23 14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>statement_timestamp</primary> </indexterm> <function>statement_timestamp</function> ( ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (start of current statement); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>statement_timestamp()</literal> <returnvalue>2019-12-23 14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>timeofday</primary> </indexterm> <function>timeofday</function> ( ) <returnvalue>text</returnvalue> </para> <para> Current date and time (like <function>clock_timestamp</function>, but as a <type>text</type> string); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>timeofday()</literal> <returnvalue>Mon Dec 23 14:39:53.662522 2019 EST</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>transaction_timestamp</primary> </indexterm> <function>transaction_timestamp</function> ( ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Current date and time (start of current transaction); see <xref linkend="functions-datetime-current"/> </para> <para> <literal>transaction_timestamp()</literal> <returnvalue>2019-12-23 14:39:53.662522-05</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_timestamp</primary> </indexterm> <function>to_timestamp</function> ( <type>double precision</type> ) <returnvalue>timestamp with time zone</returnvalue> </para> <para> Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone </para> <para> <literal>to_timestamp(1284352323)</literal> <returnvalue>2010-09-13 04:32:03+00</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> <indexterm> <primary>OVERLAPS</primary> </indexterm> In addition to these functions, the SQL <literal>OVERLAPS</literal> operator is supported: <synopsis> (<replaceable>start1</replaceable>, <replaceable>end1</replaceable>) OVERLAPS (<replaceable>s (<replaceable>start1</replaceable>, <replaceable>length1</replaceable>) OVERLAPS (<replaceab </synopsis> This expression yields true when two time periods (defined by their endpoints) overlap, false when they do not overlap. The endpoints can be specified as pairs of dates, times, or time stamps; or as a date, time, or time stamp followed by an interval. When a pair of values is provided, either the start or the end can be written first; <literal>OVERLAPS</literal> automatically takes the earlier value of the pair as the start. Each time period is considered to represent the half-open interval <replaceable>start</replaceable> <literal><=</literal> <replaceable>time</replaceable> <literal><</literal> <replaceable>end</replaceable>, unless <replaceable>start</replaceable> and <replaceable>end</replaceable> are equal in which case it represents that single time instant. This means for instance that two time periods with only an endpoint in common do not overlap. </para> <screen> SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS (DATE '2001-10-30', DATE '2002-10-30'); <lineannotation>Result: </lineannotation><computeroutput>true</computeroutput> SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS (DATE '2001-10-30', DATE '2002-10-30'); <lineannotation>Result: </lineannotation><computeroutput>false</computeroutput> SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS (DATE '2001-10-30', DATE '2001-10-31'); <lineannotation>Result: </lineannotation><computeroutput>false</computeroutput> SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS (DATE '2001-10-30', DATE '2001-10-31'); <lineannotation>Result: </lineannotation><computeroutput>true</computeroutput> </screen> <para> When adding an <type>interval</type> value to (or subtracting an <type>interval</type> value from) a <type>timestamp</type> or <type>timestamp with time zone</type> value, the months, days, and microseconds fields of the <type>interval</type> value are handled in turn. First, a nonzero months field advances or decrements the date of the timestamp by the indicated number of months, keeping the day of month the same unless it would be past the end of the new month, in which case the last day of that month is used. (For example, March 31 plus 1 month becomes April 30, but March 31 plus 2 months becomes May 31.) Then the days field advances or decrements the date of the timestamp by the indicated number of days. In both these steps the local time of day is kept the same. Finally, if there is a nonzero microseconds field, it is added or subtracted literally. When doing arithmetic on a <type>timestamp with time zone</type> value in a time zone that recognizes DST, this means that adding or subtracting (say) <literal>interval '1 day'</literal> does not necessarily have the same result as adding or subtracting <literal>interval '24 hours'</literal>. For example, with the session time zone set to <literal>America/Denver</literal>: <screen> SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '1 day'; <lineannotation>Result: </lineannotation><computeroutput>2005-04-03 12:00:00-06</computer SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '24 hours'; <lineannotation>Result: </lineannotation><computeroutput>2005-04-03 13:00:00-06</computer </screen> This happens because an hour was skipped due to a change in daylight saving time at <literal>2005-04-03 02:00:00</literal> in time zone <literal>America/Denver</literal>. </para> <para> Note there can be ambiguity in the <literal>months</literal> field returned by <function>age</function> because different months have different numbers of days. <productname>PostgreSQL</productname>'s approach uses the month from the earlier of the two dates when calculating partial months. For example, <literal>age('2004-06-01', '2004-04-30')</literal> uses April to yield <literal>1 mon 1 day</literal>, while using May would yield <literal>1 mon 2 days</literal> because May has 31 days, while April has only 30. </para> <para> Subtraction of dates and timestamps can also be complex. One conceptually simple way to perform subtraction is to convert each value to a number of seconds using <literal>EXTRACT(EPOCH FROM ...)</literal>, then subtract the results; this produces the number of <emphasis>seconds</emphasis> between the two values. This will adjust for the number of days in each month, timezone changes, and daylight saving time adjustments. Subtraction of date or timestamp values with the <quote><literal>-</literal></quote> operator returns the number of days (24-hours) and hours/minutes/seconds between the values, making the same adjustments. The <function>age</function> function returns years, months, days, and hours/minutes/seconds, performing field-by-field subtraction and then adjusting for negative field values. The following queries illustrate the differences in these approaches. The sample results were produced with <literal>timezone = 'US/Eastern'</literal>; there is a daylight saving time change between the two dates used: </para> <screen> SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') - EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'); <lineannotation>Result: </lineannotation><computeroutput>10537200.000000</computeroutput> SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') - EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00')) / 60 / 60 / 24; <lineannotation>Result: </lineannotation><computeroutput>121.9583333333333333</computero SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00'; <lineannotation>Result: </lineannotation><computeroutput>121 days 23:00:00</computeroutput> SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00'); <lineannotation>Result: </lineannotation><computeroutput>4 mons</computeroutput> </screen> <sect2 id="functions-datetime-extract"> <title><function>EXTRACT</function>, <function>date_part</function></title> <indexterm> <primary>date_part</primary> </indexterm> <indexterm> <primary>extract</primary> </indexterm> <synopsis> EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>) </synopsis> <para> The <function>extract</function> function retrieves subfields such as year or hour from date/time values. <replaceable>source</replaceable> must be a value expression of type <type>timestamp</type>, <type>date</type>, <type>time</type>, or <type>interval</type>. (Timestamps and times can be with or without time zone.) <replaceable>field</replaceable> is an identifier or string that selects what field to extract from the source value. Not all fields are valid for every input data type; for example, fields smaller than a day cannot be extracted from a <type>date</type>, while fields of a day or more cannot be extracted from a <type>time</type>. The <function>extract</function> function returns values of type <type>numeric</type>. </para> <para> The following are valid field names: <!-- alphabetical --> <variablelist> <varlistentry> <term><literal>century</literal></term> <listitem> <para> The century; for <type>interval</type> values, the year field divided by 100 </para> <screen> SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13'); <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput> SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>21</computeroutput> SELECT EXTRACT(CENTURY FROM DATE '0001-01-01 AD'); <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput> SELECT EXTRACT(CENTURY FROM DATE '0001-12-31 BC'); <lineannotation>Result: </lineannotation><computeroutput>-1</computeroutput> SELECT EXTRACT(CENTURY FROM INTERVAL '2001 years'); <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>day</literal></term> <listitem> <para> The day of the month (1–31); for <type>interval</type> values, the number of days </para> <screen> SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput> SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute'); <lineannotation>Result: </lineannotation><computeroutput>40</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>decade</literal></term> <listitem> <para> The year field divided by 10 </para> <screen> SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>200</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>dow</literal></term> <listitem> <para> The day of the week as Sunday (<literal>0</literal>) to Saturday (<literal>6</literal>) </para> <screen> SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>5</computeroutput> </screen> <para> Note that <function>extract</function>'s day of the week numbering differs from that of the <function>to_char(..., 'D')</function> function. </para> </listitem> </varlistentry> <varlistentry> <term><literal>doy</literal></term> <listitem> <para> The day of the year (1–365/366) </para> <screen> SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>47</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>epoch</literal></term> <listitem> <para> For <type>timestamp with time zone</type> values, the number of seconds since 1970-01-01 00:00:00 UTC (negative for timestamps before that); for <type>date</type> and <type>timestamp</type> values, the nominal number of seconds since 1970-01-01 00:00:00, without regard to timezone or daylight-savings rules; for <type>interval</type> values, the total number of seconds in the interval </para> <screen> SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08'); <lineannotation>Result: </lineannotation><computeroutput>982384720.120000</computeroutpu SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12'); <lineannotation>Result: </lineannotation><computeroutput>982355920.120000</computeroutpu SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); <lineannotation>Result: </lineannotation><computeroutput>442800.000000</computeroutput> </screen> <para> You can convert an epoch value back to a <type>timestamp with time zone</type> with <function>to_timestamp</function>: </para> <screen> SELECT to_timestamp(982384720.12); <lineannotation>Result: </lineannotation><computeroutput>2001-02-17 04:38:40.12+00</compu </screen> <para> Beware that applying <function>to_timestamp</function> to an epoch extracted from a <type>date</type> or <type>timestamp</type> value could produce a misleading result: the result will effectively assume that the original value had been given in UTC, which might not be the case. </para> </listitem> </varlistentry> <varlistentry> <term><literal>hour</literal></term> <listitem> <para> The hour field (0–23 in timestamps, unrestricted in intervals) </para> <screen> SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>isodow</literal></term> <listitem> <para> The day of the week as Monday (<literal>1</literal>) to Sunday (<literal>7</literal>) </para> <screen> SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput> </screen> <para> This is identical to <literal>dow</literal> except for Sunday. This matches the <acronym>ISO</acronym> 8601 day of the week numbering. </para> </listitem> </varlistentry> <varlistentry> <term><literal>isoyear</literal></term> <listitem> <para> The <acronym>ISO</acronym> 8601 week-numbering year that the date falls in </para> <screen> SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01'); <lineannotation>Result: </lineannotation><computeroutput>2005</computeroutput> SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02'); <lineannotation>Result: </lineannotation><computeroutput>2006</computeroutput> </screen> <para> Each <acronym>ISO</acronym> 8601 week-numbering 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. </para> </listitem> </varlistentry> <varlistentry> <term><literal>julian</literal></term> <listitem> <para> The <firstterm>Julian Date</firstterm> corresponding to the date or timestamp. Timestamps that are not local midnight result in a fractional value. See <xref linkend="datetime-julian-dates"/> for more information. </para> <screen> SELECT EXTRACT(JULIAN FROM DATE '2006-01-01'); <lineannotation>Result: </lineannotation><computeroutput>2453737</computeroutput> SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00'); <lineannotation>Result: </lineannotation><computeroutput>2453737.50000000000000000000</c </screen> </listitem> </varlistentry> <varlistentry> <term><literal>microseconds</literal></term> <listitem> <para> The seconds field, including fractional parts, multiplied by 1 000 000; note that this includes full seconds </para> <screen> SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5'); <lineannotation>Result: </lineannotation><computeroutput>28500000</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>millennium</literal></term> <listitem> <para> The millennium; for <type>interval</type> values, the year field divided by 1000 </para> <screen> SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput> SELECT EXTRACT(MILLENNIUM FROM INTERVAL '2001 years'); <lineannotation>Result: </lineannotation><computeroutput>2</computeroutput> </screen> <para> Years in the 1900s are in the second millennium. The third millennium started January 1, 2001. </para> </listitem> </varlistentry> <varlistentry> <term><literal>milliseconds</literal></term> <listitem> <para> The seconds field, including fractional parts, multiplied by 1000. Note that this includes full seconds. </para> <screen> SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5'); <lineannotation>Result: </lineannotation><computeroutput>28500.000</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>minute</literal></term> <listitem> <para> The minutes field (0–59) </para> <screen> SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>38</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>month</literal></term> <listitem> <para> The number of the month within the year (1–12); for <type>interval</type> values, the number of months modulo 12 (0–11) </para> <screen> SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>2</computeroutput> SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months'); <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput> SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months'); <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>quarter</literal></term> <listitem> <para> The quarter of the year (1–4) that the date is in; for <type>interval</type> values, the month field divided by 3 plus 1 </para> <screen> SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput> SELECT EXTRACT(QUARTER FROM INTERVAL '1 year 6 months'); <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>second</literal></term> <listitem> <para> The seconds field, including any fractional seconds </para> <screen> SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>40.000000</computeroutput> SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); <lineannotation>Result: </lineannotation><computeroutput>28.500000</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>timezone</literal></term> <listitem> <para> The time zone offset from UTC, measured in seconds. Positive values correspond to time zones east of UTC, negative values to zones west of UTC. (Technically, <productname>PostgreSQL</productname> does not use UTC because leap seconds are not handled.) </para> </listitem> </varlistentry> <varlistentry> <term><literal>timezone_hour</literal></term> <listitem> <para> The hour component of the time zone offset </para> </listitem> </varlistentry> <varlistentry> <term><literal>timezone_minute</literal></term> <listitem> <para> The minute component of the time zone offset </para> </listitem> </varlistentry> <varlistentry> <term><literal>week</literal></term> <listitem> <para> The number of the <acronym>ISO</acronym> 8601 week-numbering week of the year. By definition, ISO weeks start on Mondays and the first week of a year contains January 4 of that year. In other words, the first Thursday of a year is in week 1 of that year. </para> <para> In the ISO week-numbering system, it is possible for early-January dates to be part of the 52nd or 53rd week of the previous year, and for late-December dates to be part of the first week of the next year. For example, <literal>2005-01-01</literal> is part of the 53rd week of year 2004, and <literal>2006-01-01</literal> is part of the 52nd week of year 2005, while <literal>2012-12-31</literal> is part of the first week of 2013. It's recommended to use the <literal>isoyear</literal> field together with <literal>week</literal> to get consistent results. </para> <para> For <type>interval</type> values, the week field is simply the number of integral days divided by 7. </para> <screen> SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput> SELECT EXTRACT(WEEK FROM INTERVAL '13 days 24 hours'); <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput> </screen> </listitem> </varlistentry> <varlistentry> <term><literal>year</literal></term> <listitem> <para> The year field. Keep in mind there is no <literal>0 AD</literal>, so subtracting <literal>BC</literal> years from <literal>AD</literal> years should be done with care. </para> <screen> SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>2001</computeroutput> </screen> </listitem> </varlistentry> </variablelist> </para> <para> When processing an <type>interval</type> value, the <function>extract</function> function produces field values that match the interpretation used by the interval output function. This can produce surprising results if one starts with a non-normalized interval representation, for example: <screen> SELECT INTERVAL '80 minutes'; <lineannotation>Result: </lineannotation><computeroutput>01:20:00</computeroutput> SELECT EXTRACT(MINUTES FROM INTERVAL '80 minutes'); <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput> </screen> </para> <note> <para> When the input value is +/-Infinity, <function>extract</function> returns +/-Infinity for monotonically-increasing fields (<literal>epoch</literal>, <literal>julian</literal>, <literal>year</literal>, <literal>isoyear</literal>, <literal>decade</literal>, <literal>century</literal>, and <literal>millennium</literal> for <type>timestamp</type> inputs; <literal>epoch</literal>, <literal>hour</literal>, <literal>day</literal>, <literal>year</literal>, <literal>decade</literal>, <literal>century</literal>, and <literal>millennium</literal> for <type>interval</type> inputs). For other fields, NULL is returned. <productname>PostgreSQL</productname> versions before 9.6 returned zero for all cases of infinite input. </para> </note> <para> The <function>extract</function> function is primarily intended for computational processing. For formatting date/time values for display, see <xref linkend="functions-formatting"/>. </para> <para> The <function>date_part</function> function is modeled on the traditional <productname>Ingres</productname> equivalent to the <acronym>SQL</acronym>-standard function <function>extract</function>: <synopsis> date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>) </synopsis> Note that here the <replaceable>field</replaceable> parameter needs to be a string value, not a name. The valid field names for <function>date_part</function> are the same as for <function>extract</function>. For historical reasons, the <function>date_part</function> function returns values of type <type>double precision</type>. This can result in a loss of precision in certain uses. Using <function>extract</function> is recommended instead. </para> <screen> SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput> SELECT date_part('hour', INTERVAL '4 hours 3 minutes'); <lineannotation>Result: </lineannotation><computeroutput>4</computeroutput> </screen> </sect2> <sect2 id="functions-datetime-trunc"> <title><function>date_trunc</function></title> <indexterm> <primary>date_trunc</primary> </indexterm> <para> The function <function>date_trunc</function> is conceptually similar to the <function>trunc</function> function for numbers. </para> <para> <synopsis> date_trunc(<replaceable>field</replaceable>, <replaceable>source</replaceable> <optional>, <re </synopsis> <replaceable>source</replaceable> is a value expression of type <type>timestamp</type>, <type>timestamp with time zone</type>, or <type>interval</type>. (Values of type <type>date</type> and <type>time</type> are cast automatically to <type>timestamp</type> or <type>interval</type>, respectively.) <replaceable>field</replaceable> selects to which precision to truncate the input value. The return value is likewise of type <type>timestamp</type>, <type>timestamp with time zone</type>, or <type>interval</type>, and it has all fields that are less significant than the selected one set to zero (or one, for day and month). </para> <para> Valid values for <replaceable>field</replaceable> are: <simplelist> <member><literal>microseconds</literal></member> <member><literal>milliseconds</literal></member> <member><literal>second</literal></member> <member><literal>minute</literal></member> <member><literal>hour</literal></member> <member><literal>day</literal></member> <member><literal>week</literal></member> <member><literal>month</literal></member> <member><literal>quarter</literal></member> <member><literal>year</literal></member> <member><literal>decade</literal></member> <member><literal>century</literal></member> <member><literal>millennium</literal></member> </simplelist> </para> <para> When the input value is of type <type>timestamp with time zone</type>, the truncation is performed with respect to a particular time zone; for example, truncation to <literal>day</literal> produces a value that is midnight in that zone. By default, truncation is done with respect to the current <xref linkend="guc-timezone"/> setting, but the optional <replaceable>time_zone</replaceable> argument can be provided to specify a different time zone. The time zone name can be specified in any of the ways described in <xref linkend="datatype-timezones"/>. </para> <para> A time zone cannot be specified when processing <type>timestamp without time zone</type> or <type>interval</type> inputs. These are always taken at face value. </para> <para> Examples (assuming the local time zone is <literal>America/New_York</literal>): <screen> SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:00:00</computerout SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); <lineannotation>Result: </lineannotation><computeroutput>2001-01-01 00:00:00</computerout SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00'); <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 00:00:00-05</computer SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/S <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 08:00:00-05</computer SELECT date_trunc('hour', INTERVAL '3 days 02:47:33'); <lineannotation>Result: </lineannotation><computeroutput>3 days 02:00:00</computeroutput> </screen> </para> </sect2> <sect2 id="functions-datetime-bin"> <title><function>date_bin</function></title> <indexterm> <primary>date_bin</primary> </indexterm> <para> The function <function>date_bin</function> <quote>bins</quote> the input timestamp into the specified interval (the <firstterm>stride</firstterm>) aligned with a specified origin. </para> <para> <synopsis> date_bin(<replaceable>stride</replaceable>, <replaceable>source</replaceable>, <replaceable> </synopsis> <replaceable>source</replaceable> is a value expression of type <type>timestamp</type> or <type>timestamp with time zone</type>. (Values of type <type>date</type> are cast automatically to <type>timestamp</type>.) <replaceable>stride</replaceable> is a value expression of type <type>interval</type>. The return value is likewise of type <type>timestamp</type> or <type>timestamp with time zone</type>, and it marks the beginning of the bin into which the <replaceable>source</replaceable> is placed. </para> <para> Examples: <screen> SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01'); <lineannotation>Result: </lineannotation><computeroutput>2020-02-11 15:30:00</computerout SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00: <lineannotation>Result: </lineannotation><computeroutput>2020-02-11 15:32:30</computerout </screen> </para> <para> In the case of full units (1 minute, 1 hour, etc.), it gives the same result as the analogous <function>date_trunc</function> call, but the difference is that <function>date_bin</function> can truncate to an arbitrary interval. </para> <para> The <parameter>stride</parameter> interval must be greater than zero and cannot contain units of month or larger. </para> </sect2> <sect2 id="functions-datetime-zoneconvert"> <title><literal>AT TIME ZONE</literal> and <literal>AT LOCAL</literal></title> <indexterm> <primary>time zone</primary> <secondary>conversion</secondary> </indexterm> <indexterm> <primary>AT TIME ZONE</primary> </indexterm> <indexterm> <primary>AT LOCAL</primary> </indexterm> <para> The <literal>AT TIME ZONE</literal> operator converts time stamp <emphasis>without</emphasis> time zone to/from time stamp <emphasis>with</emphasis> time zone, and <type>time with time zone</type> values to different time zones. <xref linkend="functions-datetime-zoneconvert-table"/> shows its variants. </para> <table id="functions-datetime-zoneconvert-table"> <title><literal>AT TIME ZONE</literal> and <literal>AT LOCAL</literal> Variants</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp without time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replac <returnvalue>timestamp with time zone</returnvalue> </para> <para> Converts given time stamp <emphasis>without</emphasis> time zone to time stamp <emphasis>with</emphasis> time zone, assuming the given value is in the named time zone. </para> <para> <literal>timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'</literal> <returnvalue>2001-02-17 03:38:40+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp without time zone</type> <literal>AT LOCAL</literal> <returnvalue>timestamp with time zone</returnvalue> </para> <para> Converts given time stamp <emphasis>without</emphasis> time zone to time stamp <emphasis>with</emphasis> the session's <varname>TimeZone</varname> value as time zone. </para> <para> <literal>timestamp '2001-02-16 20:38:40' at local</literal> <returnvalue>2001-02-17 03:38:40+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp with time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replaceab <returnvalue>timestamp without time zone</returnvalue> </para> <para> Converts given time stamp <emphasis>with</emphasis> time zone to time stamp <emphasis>without</emphasis> time zone, as the time would appear in that zone. </para> <para> <literal>timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'</li <returnvalue>2001-02-16 18:38:40</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>timestamp with time zone</type> <literal>AT LOCAL</literal> <returnvalue>timestamp without time zone</returnvalue> </para> <para> Converts given time stamp <emphasis>with</emphasis> time zone to time stamp <emphasis>without</emphasis> time zone, as the time would appear with the session's <varname>TimeZone</varname> value as time zone. </para> <para> <literal>timestamp with time zone '2001-02-16 20:38:40-05' at local</literal> <returnvalue>2001-02-16 18:38:40</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>time with time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replaceable> <returnvalue>time with time zone</returnvalue> </para> <para> Converts given time <emphasis>with</emphasis> time zone to a new time zone. Since no date is supplied, this uses the currently active UTC offset for the named destination zone. </para> <para> <literal>time with time zone '05:34:17-05' at time zone 'UTC'</literal> <returnvalue>10:34:17+00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>time with time zone</type> <literal>AT LOCAL</literal> <returnvalue>time with time zone</returnvalue> </para> <para> Converts given time <emphasis>with</emphasis> time zone to a new time zone. Since no date is supplied, this uses the currently active UTC offset for the session's <varname>TimeZone</varname> value. </para> <para> Assuming the session's <varname>TimeZone</varname> is set to <literal>UTC</literal>: </para> <para> <literal>time with time zone '05:34:17-05' at local</literal> <returnvalue>10:34:17+00</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> In these expressions, the desired time zone <replaceable>zone</replaceable> can be specified either as a text value (e.g., <literal>'America/Los_Angeles'</literal>) or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>). In the text case, a time zone name can be specified in any of the ways described in <xref linkend="datatype-timezones"/>. The interval case is only useful for zones that have fixed offsets from UTC, so it is not very common in practice. </para> <para> The syntax <literal>AT LOCAL</literal> may be used as shorthand for <literal>AT TIME ZONE <replaceable>local</replaceable></literal>, where <replaceable>local</replaceable> is the session's <varname>TimeZone</varname> value. </para> <para> Examples (assuming the current <xref linkend="guc-timezone"/> setting is <literal>America/Los_Angeles</literal>): <screen> SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver'; <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computer SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver'; <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computerout SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chic <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 05:38:40</computerout SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL; <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 17:38:40</computerout SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE '+05'; <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:38:40</computerout SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL; <lineannotation>Result: </lineannotation><computeroutput>17:38:40</computeroutput> </screen> The first example adds a time zone to a value that lacks it, and displays the value using the current <varname>TimeZone</varname> setting. The second example shifts the time stamp with time zone value to the specified time zone, and returns the value without a time zone. This allows storage and display of values different from the current <varname>TimeZone</varname> setting. The third example converts Tokyo time to Chicago time. The fourth example shifts the time stamp with time zone value to the time zone currently specified by the <varname>TimeZone</varname> setting and returns the value without a time zone. The fifth example demonstrates that the sign in a POSIX-style time zone specification has the opposite meaning of the sign in an ISO-8601 datetime literal, as described in <xref linkend="datatype-timezones"/> and <xref linkend="datetime-appendix"/>. </para> <para> The sixth example is a cautionary tale. Due to the fact that there is no date associated with the input value, the conversion is made using the current date of the session. Therefore, this static example may show a wrong result depending on the time of the year it is viewed because <literal>'America/Los_Angeles'</literal> observes Daylight Savings Time. </para> <para> The function <literal><function>timezone</function>(<replaceable>zone</replaceable>, <replaceable>timestamp</replaceable>)</literal> is equivalent to the SQL-conforming construc <literal><replaceable>timestamp</replaceable> AT TIME ZONE <replaceable>zone</replaceable></literal>. </para> <para> The function <literal><function>timezone</function>(<replaceable>zone</replaceable>, <replaceable>time</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>time</replaceable> AT TIME ZONE <replaceable>zone</replaceable></literal>. </para> <para> The function <literal><function>timezone</function>(<replaceable>timestamp</replaceable>)</li is equivalent to the SQL-conforming construct <literal><replaceable>timestamp</replaceable> AT LOCAL</literal>. </para> <para> The function <literal><function>timezone</function>(<replaceable>time</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>time</replaceable> AT LOCAL</literal>. </para> </sect2> <sect2 id="functions-datetime-current"> <title>Current Date/Time</title> <indexterm> <primary>date</primary> <secondary>current</secondary> </indexterm> <indexterm> <primary>time</primary> <secondary>current</secondary> </indexterm> <para> <productname>PostgreSQL</productname> provides a number of functions that return values related to the current date and time. These SQL-standard functions all return values based on the start time of the current transaction: <synopsis> CURRENT_DATE CURRENT_TIME CURRENT_TIMESTAMP CURRENT_TIME(<replaceable>precision</replaceable>) CURRENT_TIMESTAMP(<replaceable>precision</replaceable>) LOCALTIME LOCALTIMESTAMP LOCALTIME(<replaceable>precision</replaceable>) LOCALTIMESTAMP(<replaceable>precision</replaceable>) </synopsis> </para> <para> <function>CURRENT_TIME</function> and <function>CURRENT_TIMESTAMP</function> deliver values with time zone; <function>LOCALTIME</function> and <function>LOCALTIMESTAMP</function> deliver values without time zone. </para> <para> <function>CURRENT_TIME</function>, <function>CURRENT_TIMESTAMP</function>, <function>LOCALTIME</function>, and <function>LOCALTIMESTAMP</function> can optionally take a precision parameter, which causes the result to be rounded to that many fractional digits in the seconds field. Without a precision parameter, the result is given to the full available precision. </para> <para> Some examples: <screen> SELECT CURRENT_TIME; <lineannotation>Result: </lineannotation><computeroutput>14:39:53.662522-05</computerout SELECT CURRENT_DATE; <lineannotation>Result: </lineannotation><computeroutput>2019-12-23</computeroutput> SELECT CURRENT_TIMESTAMP; <lineannotation>Result: </lineannotation><computeroutput>2019-12-23 14:39:53.662522-05</c SELECT CURRENT_TIMESTAMP(2); <lineannotation>Result: </lineannotation><computeroutput>2019-12-23 14:39:53.66-05</compu SELECT LOCALTIMESTAMP; <lineannotation>Result: </lineannotation><computeroutput>2019-12-23 14:39:53.662522</comp </screen> </para> <para> Since these functions return the start time of the current transaction, their values do not change during the transaction. This is considered a feature: the intent is to allow a single transaction to have a consistent notion of the <quote>current</quote> time, so that multiple modifications within the same transaction bear the same time stamp. </para> <note> <para> Other database systems might advance these values more frequently. </para> </note> <para> <productname>PostgreSQL</productname> also provides functions that return the start time of the current statement, as well as the actual current time at the instant the function is called. The complete list of non-SQL-standard time functions is: <synopsis> transaction_timestamp() statement_timestamp() clock_timestamp() timeofday() now() </synopsis> </para> <para> <function>transaction_timestamp()</function> is equivalent to <function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect what it returns. <function>statement_timestamp()</function> returns the start time of the current statement (more specifically, the time of receipt of the latest command message from the client). <function>statement_timestamp()</function> and <function>transaction_timestamp()</functio return the same value during the first statement of a transaction, but might differ during subsequent statements. <function>clock_timestamp()</function> returns the actual current time, and therefore its value changes even within a single SQL statement. <function>timeofday()</function> is a historical <productname>PostgreSQL</productname> function. Like <function>clock_timestamp()</function>, it returns the actual current time, but as a formatted <type>text</type> string rather than a <type>timestamp with time zone</type> value. <function>now()</function> is a traditional <productname>PostgreSQL</productname> equivalent to <function>transaction_timestamp()</function>. </para> <para> All the date/time data types also accept the special literal value <literal>now</literal> to specify the current date and time (again, interpreted as the transaction start time). Thus, the following three all return the same result: <programlisting> SELECT CURRENT_TIMESTAMP; SELECT now(); SELECT TIMESTAMP 'now'; -- but see tip below </programlisting> </para> <tip> <para> Do not use the third form when specifying a value to be evaluated later, for example in a <literal>DEFAULT</literal> clause for a table column. The system will convert <literal>now</literal> to a <type>timestamp</type> as soon as the constant is parsed, so that when the default value is needed, the time of the table creation would be used! The first two forms will not be evaluated until the default value is used, because they are function calls. Thus they will give the desired behavior of defaulting to the time of row insertion. (See also <xref linkend="datatype-datetime-special-values"/>.) </para> </tip> </sect2> <sect2 id="functions-datetime-delay"> <title>Delaying Execution</title> <indexterm> <primary>pg_sleep</primary> </indexterm> <indexterm> <primary>pg_sleep_for</primary> </indexterm> <indexterm> <primary>pg_sleep_until</primary> </indexterm> <indexterm> <primary>sleep</primary> </indexterm> <indexterm> <primary>delay</primary> </indexterm> <para> The following functions are available to delay execution of the server process: <synopsis> pg_sleep ( <type>double precision</type> ) pg_sleep_for ( <type>interval</type> ) pg_sleep_until ( <type>timestamp with time zone</type> ) </synopsis> <function>pg_sleep</function> makes the current session's process sleep until the given number of seconds have elapsed. Fractional-second delays can be specified. <function>pg_sleep_for</function> is a convenience function to allow the sleep time to be specified as an <type>interval</type>. <function>pg_sleep_until</function> is a convenience function for when a specific wake-up time is desired. For example: <programlisting> SELECT pg_sleep(1.5); SELECT pg_sleep_for('5 minutes'); SELECT pg_sleep_until('tomorrow 03:00'); </programlisting> </para> <note> <para> The effective resolution of the sleep interval is platform-specific; 0.01 seconds is a common value. The sleep delay will be at least as long as specified. It might be longer depending on factors such as server load. In particular, <function>pg_sleep_until</function> is not guaranteed to wake up exactly at the specified time, but it will not wake up any earlier. </para> </note> <warning> <para> Make sure that your session does not hold more locks than necessary when calling <function>pg_sleep</function> or its variants. Otherwise other sessions might have to wait for your sleeping process, slowing down the entire system. </para> </warning> </sect2> </sect1> <sect1 id="functions-enum"> <title>Enum Support Functions</title> <para> For enum types (described in <xref linkend="datatype-enum"/>), there are several functions that allow cleaner programming without hard-coding particular values of an enum type. These are listed in <xref linkend="functions-enum-table"/>. The examples assume an enum type created as: <programlisting> CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple'); </programlisting> </para> <table id="functions-enum-table"> <title>Enum Support Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>enum_first</primary> </indexterm> <function>enum_first</function> ( <type>anyenum</type> ) <returnvalue>anyenum</returnvalue> </para> <para> Returns the first value of the input enum type. </para> <para> <literal>enum_first(null::rainbow)</literal> <returnvalue>red</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>enum_last</primary> </indexterm> <function>enum_last</function> ( <type>anyenum</type> ) <returnvalue>anyenum</returnvalue> </para> <para> Returns the last value of the input enum type. </para> <para> <literal>enum_last(null::rainbow)</literal> <returnvalue>purple</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>enum_range</primary> </indexterm> <function>enum_range</function> ( <type>anyenum</type> ) <returnvalue>anyarray</returnvalue> </para> <para> Returns all values of the input enum type in an ordered array. </para> <para> <literal>enum_range(null::rainbow)</literal> <returnvalue>{red,orange,yellow,&zwsp;green,blue,purple}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>enum_range</function> ( <type>anyenum</type>, <type>anyenum</type> ) <returnvalue>anyarray</returnvalue> </para> <para> Returns the range between the two given enum values, as an ordered array. The values must be from the same enum type. If the first parameter is null, the result will start with the first value of the enum type. If the second parameter is null, the result will end with the last value of the enum type. </para> <para> <literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal> <returnvalue>{orange,yellow,green}</returnvalue> </para> <para> <literal>enum_range(NULL, 'green'::rainbow)</literal> <returnvalue>{red,orange,&zwsp;yellow,green}</returnvalue> </para> <para> <literal>enum_range('orange'::rainbow, NULL)</literal> <returnvalue>{orange,yellow,green,&zwsp;blue,purple}</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> Notice that except for the two-argument form of <function>enum_range</function>, these functions disregard the specific value passed to them; they care only about its declared data type. Either null or a specific value of the type can be passed, with the same result. It is more common to apply these functions to a table column or function argument than to a hardwired type name as used in the examples. </para> </sect1> <sect1 id="functions-geometry"> <title>Geometric Functions and Operators</title> <para> The geometric types <type>point</type>, <type>box</type>, <type>lseg</type>, <type>line</type>, <type>path</type>, <type>polygon</type>, and <type>circle</type> have a large set of native support functions and operators, shown in <xref linkend="functions-geometry-op-table"/>, <xref linkend="functions-geometry-func-table"/>, and <xref linkend="functions-geometry-conv-table"/>. </para> <table id="functions-geometry-op-table"> <title>Geometric Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>+</literal> <type>point</type> <returnvalue><replaceable>geometric_type</replaceable></returnvalue> </para> <para> Adds the coordinates of the second <type>point</type> to those of each point of the first argument, thus performing translation. Available for <type>point</type>, <type>box</type>, <type>path</type>, <type>circle</type>. </para> <para> <literal>box '(1,1),(0,0)' + point '(2,0)'</literal> <returnvalue>(3,1),(2,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>path</type> <literal>+</literal> <type>path</type> <returnvalue>path</returnvalue> </para> <para> Concatenates two open paths (returns NULL if either path is closed). </para> <para> <literal>path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]'</literal> <returnvalue>[(0,0),(1,1),(2,2),(3,3),(4,4)]</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>-</literal> <type>point</type> <returnvalue><replaceable>geometric_type</replaceable></returnvalue> </para> <para> Subtracts the coordinates of the second <type>point</type> from those of each point of the first argument, thus performing translation. Available for <type>point</type>, <type>box</type>, <type>path</type>, <type>circle</type>. </para> <para> <literal>box '(1,1),(0,0)' - point '(2,0)'</literal> <returnvalue>(-1,1),(-2,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>*</literal> <type>point</type> <returnvalue><replaceable>geometric_type</replaceable></returnvalue> </para> <para> Multiplies each point of the first argument by the second <type>point</type> (treating a point as being a complex number represented by real and imaginary parts, and performing standard complex multiplication). If one interprets the second <type>point</type> as a vector, this is equivalent to scaling the object's size and distance from the origin by the length of the vector, and rotating it counterclockwise around the origin by the vector's angle from the <replaceable>x</replaceable> axis. Available for <type>point</type>, <type>box</type>,<footnote id="functions-geometry-rotation-fn"><para><quote>Rotating</quote> a box with these operators only moves its corner points: the box is still considered to have sides parallel to the axes. Hence the box's size is not preserved, as a true rotation would do.</para></footnote> <type>path</type>, <type>circle</type>. </para> <para> <literal>path '((0,0),(1,0),(1,1))' * point '(3.0,0)'</literal> <returnvalue>((0,0),(3,0),(3,3))</returnvalue> </para> <para> <literal>path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45))</literal> <returnvalue>((0,0),&zwsp;(0.7071067811865475,0.7071067811865475),&zwsp;(0,1.414213562373095))< </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>/</literal> <type>point</type> <returnvalue><replaceable>geometric_type</replaceable></returnvalue> </para> <para> Divides each point of the first argument by the second <type>point</type> (treating a point as being a complex number represented by real and imaginary parts, and performing standard complex division). If one interprets the second <type>point</type> as a vector, this is equivalent to scaling the object's size and distance from the origin down by the length of the vector, and rotating it clockwise around the origin by the vector's angle from the <replaceable>x</replaceable> axis. Available for <type>point</type>, <type>box</type>,<footnoteref linkend="functions-geometry-rotation-fn"/> <type>path</type>, <type>circle</type>. </para> <para> <literal>path '((0,0),(1,0),(1,1))' / point '(2.0,0)'</literal> <returnvalue>((0,0),(0.5,0),(0.5,0.5))</returnvalue> </para> <para> <literal>path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45))</literal> <returnvalue>((0,0),&zwsp;(0.7071067811865476,-0.7071067811865476),&zwsp;(1.4142135623730951,0 </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>@-@</literal> <replaceable>geometric_type</replaceable> <returnvalue>double precision</returnvalue> </para> <para> Computes the total length. Available for <type>lseg</type>, <type>path</type>. </para> <para> <literal>@-@ path '[(0,0),(1,0),(1,1)]'</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>@@</literal> <replaceable>geometric_type</replaceable> <returnvalue>point</returnvalue> </para> <para> Computes the center point. Available for <type>box</type>, <type>lseg</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>@@ box '(2,2),(0,0)'</literal> <returnvalue>(1,1)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>#</literal> <replaceable>geometric_type</replaceable> <returnvalue>integer</returnvalue> </para> <para> Returns the number of points. Available for <type>path</type>, <type>polygon</type>. </para> <para> <literal># path '((1,0),(0,1),(-1,0))'</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>#</literal> <replaceable>geometric_type</r <returnvalue>point</returnvalue> </para> <para> Computes the point of intersection, or NULL if there is none. Available for <type>lseg</type>, <type>line</type>. </para> <para> <literal>lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]'</literal> <returnvalue>(0.5,0.5)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>box</type> <literal>#</literal> <type>box</type> <returnvalue>box</returnvalue> </para> <para> Computes the intersection of two boxes, or NULL if there is none. </para> <para> <literal>box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)'</literal> <returnvalue>(1,1),(-1,-1)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>##</literal> <replaceable>geometric_type</ <returnvalue>point</returnvalue> </para> <para> Computes the closest point to the first object on the second object. Available for these pairs of types: (<type>point</type>, <type>box</type>), (<type>point</type>, <type>lseg</type>), (<type>point</type>, <type>line</type>), (<type>lseg</type>, <type>box</type>), (<type>lseg</type>, <type>lseg</type>), (<type>line</type>, <type>lseg</type>). </para> <para> <literal>point '(0,0)' ## lseg '[(2,0),(0,2)]'</literal> <returnvalue>(1,1)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal><-></literal> <replaceable>geometric_type</r <returnvalue>double precision</returnvalue> </para> <para> Computes the distance between the objects. Available for all seven geometric types, for all combinations of <type>point</type> with another geometric type, and for these additional pairs of types: (<type>box</type>, <type>lseg</type>), (<type>lseg</type>, <type>line</type>), (<type>polygon</type>, <type>circle</type>) (and the commutator cases). </para> <para> <literal>circle '<(0,0),1>' <-> circle '<(5,0),1>'</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>@></literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Does first object contain second? Available for these pairs of types: (<literal>box</literal>, <literal>point</literal>), (<literal>box</literal>, <literal>box</literal>), (<literal>path</literal>, <literal>point</literal>), (<literal>polygon</literal>, <literal>point</literal>), (<literal>polygon</literal>, <literal>polygon</literal>), (<literal>circle</literal>, <literal>point</literal>), (<literal>circle</literal>, <literal>circle</literal>). </para> <para> <literal>circle '<(0,0),2>' @> point '(1,1)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal><@</literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Is first object contained in or on second? Available for these pairs of types: (<literal>point</literal>, <literal>box</literal>), (<literal>point</literal>, <literal>lseg</literal>), (<literal>point</literal>, <literal>line</literal>), (<literal>point</literal>, <literal>path</literal>), (<literal>point</literal>, <literal>polygon</literal>), (<literal>point</literal>, <literal>circle</literal>), (<literal>box</literal>, <literal>box</literal>), (<literal>lseg</literal>, <literal>box</literal>), (<literal>lseg</literal>, <literal>line</literal>), (<literal>polygon</literal>, <literal>polygon</literal>), (<literal>circle</literal>, <literal>circle</literal>). </para> <para> <literal>point '(1,1)' <@ circle '<(0,0),2>'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>&&</literal> <replaceable>geometric_type</re <returnvalue>boolean</returnvalue> </para> <para> Do these objects overlap? (One point in common makes this true.) Available for <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(1,1),(0,0)' && box '(2,2),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal><<</literal> <replaceable>geometric_type</re <returnvalue>boolean</returnvalue> </para> <para> Is first object strictly left of second? Available for <type>point</type>, <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>circle '<(0,0),1>' << circle '<(5,0),1>'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>>></literal> <replaceable>geometric_type</re <returnvalue>boolean</returnvalue> </para> <para> Is first object strictly right of second? Available for <type>point</type>, <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>circle '<(5,0),1>' >> circle '<(0,0),1>'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>&<</literal> <replaceable>geometric_type</re <returnvalue>boolean</returnvalue> </para> <para> Does first object not extend to the right of second? Available for <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(1,1),(0,0)' &< box '(2,2),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>&></literal> <replaceable>geometric_type</re <returnvalue>boolean</returnvalue> </para> <para> Does first object not extend to the left of second? Available for <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(3,3),(0,0)' &> box '(2,2),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal><<|</literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Is first object strictly below second? Available for <type>point</type>, <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(3,3),(0,0)' <<| box '(5,5),(3,4)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>|>></literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Is first object strictly above second? Available for <type>point</type>, <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(5,5),(3,4)' |>> box '(3,3),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>&<|</literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Does first object not extend above second? Available for <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(1,1),(0,0)' &<| box '(2,2),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>|&></literal> <replaceable>geometric_type</r <returnvalue>boolean</returnvalue> </para> <para> Does first object not extend below second? Available for <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>box '(3,3),(0,0)' |&> box '(2,2),(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>box</type> <literal><^</literal> <type>box</type> <returnvalue>boolean</returnvalue> </para> <para> Is first object below second (allows edges to touch)? </para> <para> <literal>box '((1,1),(0,0))' <^ box '((2,2),(1,1))'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>box</type> <literal>>^</literal> <type>box</type> <returnvalue>boolean</returnvalue> </para> <para> Is first object above second (allows edges to touch)? </para> <para> <literal>box '((2,2),(1,1))' >^ box '((1,1),(0,0))'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>?#</literal> <replaceable>geometric_type</ <returnvalue>boolean</returnvalue> </para> <para> Do these objects intersect? Available for these pairs of types: (<type>box</type>, <type>box</type>), (<type>lseg</type>, <type>box</type>), (<type>lseg</type>, <type>lseg</type>), (<type>lseg</type>, <type>line</type>), (<type>line</type>, <type>box</type>), (<type>line</type>, <type>line</type>), (<type>path</type>, <type>path</type>). </para> <para> <literal>lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>?-</literal> <type>line</type> <returnvalue>boolean</returnvalue> </para> <para role="func_signature"> <literal>?-</literal> <type>lseg</type> <returnvalue>boolean</returnvalue> </para> <para> Is line horizontal? </para> <para> <literal>?- lseg '[(-1,0),(1,0)]'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>point</type> <literal>?-</literal> <type>point</type> <returnvalue>boolean</returnvalue> </para> <para> Are points horizontally aligned (that is, have same y coordinate)? </para> <para> <literal>point '(1,0)' ?- point '(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>?|</literal> <type>line</type> <returnvalue>boolean</returnvalue> </para> <para role="func_signature"> <literal>?|</literal> <type>lseg</type> <returnvalue>boolean</returnvalue> </para> <para> Is line vertical? </para> <para> <literal>?| lseg '[(-1,0),(1,0)]'</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>point</type> <literal>?|</literal> <type>point</type> <returnvalue>boolean</returnvalue> </para> <para> Are points vertically aligned (that is, have same x coordinate)? </para> <para> <literal>point '(0,1)' ?| point '(0,0)'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>line</type> <literal>?-|</literal> <type>line</type> <returnvalue>boolean</returnvalue> </para> <para role="func_signature"> <type>lseg</type> <literal>?-|</literal> <type>lseg</type> <returnvalue>boolean</returnvalue> </para> <para> Are lines perpendicular? </para> <para> <literal>lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>line</type> <literal>?||</literal> <type>line</type> <returnvalue>boolean</returnvalue> </para> <para role="func_signature"> <type>lseg</type> <literal>?||</literal> <type>lseg</type> <returnvalue>boolean</returnvalue> </para> <para> Are lines parallel? </para> <para> <literal>lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <replaceable>geometric_type</replaceable> <literal>~=</literal> <replaceable>geometric_type</ <returnvalue>boolean</returnvalue> </para> <para> Are these objects the same? Available for <type>point</type>, <type>box</type>, <type>polygon</type>, <type>circle</type>. </para> <para> <literal>polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'</literal> <returnvalue>t</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <caution> <para> Note that the <quote>same as</quote> operator, <literal>~=</literal>, represents the usual notion of equality for the <type>point</type>, <type>box</type>, <type>polygon</type>, and <type>circle</type> types. Some of the geometric types also have an <literal>=</literal> operator, but <literal>=</literal> compares for equal <emphasis>areas</emphasis> only. The other scalar comparison operators (<literal><=</literal> and so on), where available for these types, likewise compare areas. </para> </caution> <note> <para> Before <productname>PostgreSQL</productname> 14, the point is strictly below/above comparison operators <type>point</type> <literal><<|</literal> <type>point</type> and <type>point</type> <literal>|>></literal> <type>point</type> were respectively called <literal><^</literal> and <literal>>^</literal>. These names are still available, but are deprecated and will eventually be removed. </para> </note> <table id="functions-geometry-func-table"> <title>Geometric Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>area</primary> </indexterm> <function>area</function> ( <replaceable>geometric_type</replaceable> ) <returnvalue>double precision</returnvalue> </para> <para> Computes area. Available for <type>box</type>, <type>path</type>, <type>circle</type>. A <type>path</type> input must be closed, else NULL is returned. Also, if the <type>path</type> is self-intersecting, the result may be meaningless. </para> <para> <literal>area(box '(2,2),(0,0)')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>center</primary> </indexterm> <function>center</function> ( <replaceable>geometric_type</replaceable> ) <returnvalue>point</returnvalue> </para> <para> Computes center point. Available for <type>box</type>, <type>circle</type>. </para> <para> <literal>center(box '(1,2),(0,0)')</literal> <returnvalue>(0.5,1)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>diagonal</primary> </indexterm> <function>diagonal</function> ( <type>box</type> ) <returnvalue>lseg</returnvalue> </para> <para> Extracts box's diagonal as a line segment (same as <function>lseg(box)</function>). </para> <para> <literal>diagonal(box '(1,2),(0,0)')</literal> <returnvalue>[(1,2),(0,0)]</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>diameter</primary> </indexterm> <function>diameter</function> ( <type>circle</type> ) <returnvalue>double precision</returnvalue> </para> <para> Computes diameter of circle. </para> <para> <literal>diameter(circle '<(0,0),2>')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>height</primary> </indexterm> <function>height</function> ( <type>box</type> ) <returnvalue>double precision</returnvalue> </para> <para> Computes vertical size of box. </para> <para> <literal>height(box '(1,2),(0,0)')</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>isclosed</primary> </indexterm> <function>isclosed</function> ( <type>path</type> ) <returnvalue>boolean</returnvalue> </para> <para> Is path closed? </para> <para> <literal>isclosed(path '((0,0),(1,1),(2,0))')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>isopen</primary> </indexterm> <function>isopen</function> ( <type>path</type> ) <returnvalue>boolean</returnvalue> </para> <para> Is path open? </para> <para> <literal>isopen(path '[(0,0),(1,1),(2,0)]')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>length</primary> </indexterm> <function>length</function> ( <replaceable>geometric_type</replaceable> ) <returnvalue>double precision</returnvalue> </para> <para> Computes the total length. Available for <type>lseg</type>, <type>path</type>. </para> <para> <literal>length(path '((-1,0),(1,0))')</literal> <returnvalue>4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>npoints</primary> </indexterm> <function>npoints</function> ( <replaceable>geometric_type</replaceable> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of points. Available for <type>path</type>, <type>polygon</type>. </para> <para> <literal>npoints(path '[(0,0),(1,1),(2,0)]')</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pclose</primary> </indexterm> <function>pclose</function> ( <type>path</type> ) <returnvalue>path</returnvalue> </para> <para> Converts path to closed form. </para> <para> <literal>pclose(path '[(0,0),(1,1),(2,0)]')</literal> <returnvalue>((0,0),(1,1),(2,0))</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>popen</primary> </indexterm> <function>popen</function> ( <type>path</type> ) <returnvalue>path</returnvalue> </para> <para> Converts path to open form. </para> <para> <literal>popen(path '((0,0),(1,1),(2,0))')</literal> <returnvalue>[(0,0),(1,1),(2,0)]</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>radius</primary> </indexterm> <function>radius</function> ( <type>circle</type> ) <returnvalue>double precision</returnvalue> </para> <para> Computes radius of circle. </para> <para> <literal>radius(circle '<(0,0),2>')</literal> <returnvalue>2</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>slope</primary> </indexterm> <function>slope</function> ( <type>point</type>, <type>point</type> ) <returnvalue>double precision</returnvalue> </para> <para> Computes slope of a line drawn through the two points. </para> <para> <literal>slope(point '(0,0)', point '(2,1)')</literal> <returnvalue>0.5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>width</primary> </indexterm> <function>width</function> ( <type>box</type> ) <returnvalue>double precision</returnvalue> </para> <para> Computes horizontal size of box. </para> <para> <literal>width(box '(1,2),(0,0)')</literal> <returnvalue>1</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <table id="functions-geometry-conv-table"> <title>Geometric Type Conversion Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>box</primary> </indexterm> <function>box</function> ( <type>circle</type> ) <returnvalue>box</returnvalue> </para> <para> Computes box inscribed within the circle. </para> <para> <literal>box(circle '<(0,0),2>')</literal> <returnvalue>(1.414213562373095,1.414213562373095),&zwsp;(-1.414213562373095,-1.41421356 </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>box</function> ( <type>point</type> ) <returnvalue>box</returnvalue> </para> <para> Converts point to empty box. </para> <para> <literal>box(point '(1,0)')</literal> <returnvalue>(1,0),(1,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>box</function> ( <type>point</type>, <type>point</type> ) <returnvalue>box</returnvalue> </para> <para> Converts any two corner points to box. </para> <para> <literal>box(point '(0,1)', point '(1,0)')</literal> <returnvalue>(1,1),(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>box</function> ( <type>polygon</type> ) <returnvalue>box</returnvalue> </para> <para> Computes bounding box of polygon. </para> <para> <literal>box(polygon '((0,0),(1,1),(2,0))')</literal> <returnvalue>(2,1),(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>bound_box</primary> </indexterm> <function>bound_box</function> ( <type>box</type>, <type>box</type> ) <returnvalue>box</returnvalue> </para> <para> Computes bounding box of two boxes. </para> <para> <literal>bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)')</literal> <returnvalue>(4,4),(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>circle</primary> </indexterm> <function>circle</function> ( <type>box</type> ) <returnvalue>circle</returnvalue> </para> <para> Computes smallest circle enclosing box. </para> <para> <literal>circle(box '(1,1),(0,0)')</literal> <returnvalue><(0.5,0.5),0.7071067811865476></returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>circle</function> ( <type>point</type>, <type>double precision</type> ) <returnvalue>circle</returnvalue> </para> <para> Constructs circle from center and radius. </para> <para> <literal>circle(point '(0,0)', 2.0)</literal> <returnvalue><(0,0),2></returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>circle</function> ( <type>polygon</type> ) <returnvalue>circle</returnvalue> </para> <para> Converts polygon to circle. The circle's center is the mean of the positions of the polygon's points, and the radius is the average distance of the polygon's points from that center. </para> <para> <literal>circle(polygon '((0,0),(1,3),(2,0))')</literal> <returnvalue><(1,1),1.6094757082487299></returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>line</primary> </indexterm> <function>line</function> ( <type>point</type>, <type>point</type> ) <returnvalue>line</returnvalue> </para> <para> Converts two points to the line through them. </para> <para> <literal>line(point '(-1,0)', point '(1,0)')</literal> <returnvalue>{0,-1,0}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>lseg</primary> </indexterm> <function>lseg</function> ( <type>box</type> ) <returnvalue>lseg</returnvalue> </para> <para> Extracts box's diagonal as a line segment. </para> <para> <literal>lseg(box '(1,0),(-1,0)')</literal> <returnvalue>[(1,0),(-1,0)]</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>lseg</function> ( <type>point</type>, <type>point</type> ) <returnvalue>lseg</returnvalue> </para> <para> Constructs line segment from two endpoints. </para> <para> <literal>lseg(point '(-1,0)', point '(1,0)')</literal> <returnvalue>[(-1,0),(1,0)]</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>path</primary> </indexterm> <function>path</function> ( <type>polygon</type> ) <returnvalue>path</returnvalue> </para> <para> Converts polygon to a closed path with the same list of points. </para> <para> <literal>path(polygon '((0,0),(1,1),(2,0))')</literal> <returnvalue>((0,0),(1,1),(2,0))</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>point</primary> </indexterm> <function>point</function> ( <type>double precision</type>, <type>double precision</type> ) <returnvalue>point</returnvalue> </para> <para> Constructs point from its coordinates. </para> <para> <literal>point(23.4, -44.5)</literal> <returnvalue>(23.4,-44.5)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>point</function> ( <type>box</type> ) <returnvalue>point</returnvalue> </para> <para> Computes center of box. </para> <para> <literal>point(box '(1,0),(-1,0)')</literal> <returnvalue>(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>point</function> ( <type>circle</type> ) <returnvalue>point</returnvalue> </para> <para> Computes center of circle. </para> <para> <literal>point(circle '<(0,0),2>')</literal> <returnvalue>(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>point</function> ( <type>lseg</type> ) <returnvalue>point</returnvalue> </para> <para> Computes center of line segment. </para> <para> <literal>point(lseg '[(-1,0),(1,0)]')</literal> <returnvalue>(0,0)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>point</function> ( <type>polygon</type> ) <returnvalue>point</returnvalue> </para> <para> Computes center of polygon (the mean of the positions of the polygon's points). </para> <para> <literal>point(polygon '((0,0),(1,1),(2,0))')</literal> <returnvalue>(1,0.3333333333333333)</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>polygon</primary> </indexterm> <function>polygon</function> ( <type>box</type> ) <returnvalue>polygon</returnvalue> </para> <para> Converts box to a 4-point polygon. </para> <para> <literal>polygon(box '(1,1),(0,0)')</literal> <returnvalue>((0,0),(0,1),(1,1),(1,0))</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>polygon</function> ( <type>circle</type> ) <returnvalue>polygon</returnvalue> </para> <para> Converts circle to a 12-point polygon. </para> <para> <literal>polygon(circle '<(0,0),2>')</literal> <returnvalue>((-2,0),&zwsp;(-1.7320508075688774,0.9999999999999999),&zwsp;(-1.0000000000000002 </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>polygon</function> ( <type>integer</type>, <type>circle</type> ) <returnvalue>polygon</returnvalue> </para> <para> Converts circle to an <replaceable>n</replaceable>-point polygon. </para> <para> <literal>polygon(4, circle '<(3,0),1>')</literal> <returnvalue>((2,0),&zwsp;(3,1),&zwsp;(4,1.2246063538223773e-16),&zwsp;(3,-1))</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>polygon</function> ( <type>path</type> ) <returnvalue>polygon</returnvalue> </para> <para> Converts closed path to a polygon with the same list of points. </para> <para> <literal>polygon(path '((0,0),(1,1),(2,0))')</literal> <returnvalue>((0,0),(1,1),(2,0))</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> It is possible to access the two component numbers of a <type>point</type> as though the point were an array with indexes 0 and 1. For example, if <literal>t.p</literal> is a <type>point</type> column then <literal>SELECT p[0] FROM t</literal> retrieves the X coordinate and <literal>UPDATE t SET p[1] = ...</literal> changes the Y coordinate. In the same way, a value of type <type>box</type> or <type>lseg</type> can be treated as an array of two <type>point</type> values. </para> </sect1> <sect1 id="functions-net"> <title>Network Address Functions and Operators</title> <para> The IP network address types, <type>cidr</type> and <type>inet</type>, support the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> as well as the specialized operators and functions shown in <xref linkend="cidr-inet-operators-table"/> and <xref linkend="cidr-inet-functions-table"/>. </para> <para> Any <type>cidr</type> value can be cast to <type>inet</type> implicitly; therefore, the operators and functions shown below as operating on <type>inet</type> also work on <type>cidr</type> values. (Where there are separate functions for <type>inet</type> and <type>cidr</type>, it is because the behavior should be different for the two cases.) Also, it is permitted to cast an <type>inet</type> value to <type>cidr</type>. When this is done, any bits to the right of the netmask are silently zeroed to create a valid <type>cidr</type> value. </para> <table id="cidr-inet-operators-table"> <title>IP Address Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal><<</literal> <type>inet</type> <returnvalue>boolean</returnvalue> </para> <para> Is subnet strictly contained by subnet? This operator, and the next four, test for subnet inclusion. They consider only the network parts of the two addresses (ignoring any bits to the right of the netmasks) and determine whether one network is identical to or a subnet of the other. </para> <para> <literal>inet '192.168.1.5' << inet '192.168.1/24'</literal> <returnvalue>t</returnvalue> </para> <para> <literal>inet '192.168.0.5' << inet '192.168.1/24'</literal> <returnvalue>f</returnvalue> </para> <para> <literal>inet '192.168.1/24' << inet '192.168.1/24'</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal><<=</literal> <type>inet</type> <returnvalue>boolean</returnvalue> </para> <para> Is subnet contained by or equal to subnet? </para> <para> <literal>inet '192.168.1/24' <<= inet '192.168.1/24'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>>></literal> <type>inet</type> <returnvalue>boolean</returnvalue> </para> <para> Does subnet strictly contain subnet? </para> <para> <literal>inet '192.168.1/24' >> inet '192.168.1.5'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>>>=</literal> <type>inet</type> <returnvalue>boolean</returnvalue> </para> <para> Does subnet contain or equal subnet? </para> <para> <literal>inet '192.168.1/24' >>= inet '192.168.1/24'</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>&&</literal> <type>inet</type> <returnvalue>boolean</returnvalue> </para> <para> Does either subnet contain or equal the other? </para> <para> <literal>inet '192.168.1/24' && inet '192.168.1.80/28'</literal> <returnvalue>t</returnvalue> </para> <para> <literal>inet '192.168.1/24' && inet '192.168.2.0/28'</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>~</literal> <type>inet</type> <returnvalue>inet</returnvalue> </para> <para> Computes bitwise NOT. </para> <para> <literal>~ inet '192.168.1.6'</literal> <returnvalue>63.87.254.249</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>&</literal> <type>inet</type> <returnvalue>inet</returnvalue> </para> <para> Computes bitwise AND. </para> <para> <literal>inet '192.168.1.6' & inet '0.0.0.255'</literal> <returnvalue>0.0.0.6</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>|</literal> <type>inet</type> <returnvalue>inet</returnvalue> </para> <para> Computes bitwise OR. </para> <para> <literal>inet '192.168.1.6' | inet '0.0.0.255'</literal> <returnvalue>192.168.1.255</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>+</literal> <type>bigint</type> <returnvalue>inet</returnvalue> </para> <para> Adds an offset to an address. </para> <para> <literal>inet '192.168.1.6' + 25</literal> <returnvalue>192.168.1.31</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>bigint</type> <literal>+</literal> <type>inet</type> <returnvalue>inet</returnvalue> </para> <para> Adds an offset to an address. </para> <para> <literal>200 + inet '::ffff:fff0:1'</literal> <returnvalue>::ffff:255.240.0.201</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>-</literal> <type>bigint</type> <returnvalue>inet</returnvalue> </para> <para> Subtracts an offset from an address. </para> <para> <literal>inet '192.168.1.43' - 36</literal> <returnvalue>192.168.1.7</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>inet</type> <literal>-</literal> <type>inet</type> <returnvalue>bigint</returnvalue> </para> <para> Computes the difference of two addresses. </para> <para> <literal>inet '192.168.1.43' - inet '192.168.1.19'</literal> <returnvalue>24</returnvalue> </para> <para> <literal>inet '::1' - inet '::ffff:1'</literal> <returnvalue>-4294901760</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <table id="cidr-inet-functions-table"> <title>IP Address Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>abbrev</primary> </indexterm> <function>abbrev</function> ( <type>inet</type> ) <returnvalue>text</returnvalue> </para> <para> Creates an abbreviated display format as text. (The result is the same as the <type>inet</type> output function produces; it is <quote>abbreviated</quote> only in comparison to the result of an explicit cast to <type>text</type>, which for historical reasons will never suppress the netmask part.) </para> <para> <literal>abbrev(inet '10.1.0.0/32')</literal> <returnvalue>10.1.0.0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>abbrev</function> ( <type>cidr</type> ) <returnvalue>text</returnvalue> </para> <para> Creates an abbreviated display format as text. (The abbreviation consists of dropping all-zero octets to the right of the netmask; more examples are in <xref linkend="datatype-net-cidr-table"/>.) </para> <para> <literal>abbrev(cidr '10.1.0.0/16')</literal> <returnvalue>10.1/16</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>broadcast</primary> </indexterm> <function>broadcast</function> ( <type>inet</type> ) <returnvalue>inet</returnvalue> </para> <para> Computes the broadcast address for the address's network. </para> <para> <literal>broadcast(inet '192.168.1.5/24')</literal> <returnvalue>192.168.1.255/24</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>family</primary> </indexterm> <function>family</function> ( <type>inet</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the address's family: <literal>4</literal> for IPv4, <literal>6</literal> for IPv6. </para> <para> <literal>family(inet '::1')</literal> <returnvalue>6</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>host</primary> </indexterm> <function>host</function> ( <type>inet</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the IP address as text, ignoring the netmask. </para> <para> <literal>host(inet '192.168.1.0/24')</literal> <returnvalue>192.168.1.0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>hostmask</primary> </indexterm> <function>hostmask</function> ( <type>inet</type> ) <returnvalue>inet</returnvalue> </para> <para> Computes the host mask for the address's network. </para> <para> <literal>hostmask(inet '192.168.23.20/30')</literal> <returnvalue>0.0.0.3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>inet_merge</primary> </indexterm> <function>inet_merge</function> ( <type>inet</type>, <type>inet</type> ) <returnvalue>cidr</returnvalue> </para> <para> Computes the smallest network that includes both of the given networks. </para> <para> <literal>inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')</literal> <returnvalue>192.168.0.0/22</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>inet_same_family</primary> </indexterm> <function>inet_same_family</function> ( <type>inet</type>, <type>inet</type> ) <returnvalue>boolean</returnvalue> </para> <para> Tests whether the addresses belong to the same IP family. </para> <para> <literal>inet_same_family(inet '192.168.1.5/24', inet '::1')</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>masklen</primary> </indexterm> <function>masklen</function> ( <type>inet</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the netmask length in bits. </para> <para> <literal>masklen(inet '192.168.1.5/24')</literal> <returnvalue>24</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>netmask</primary> </indexterm> <function>netmask</function> ( <type>inet</type> ) <returnvalue>inet</returnvalue> </para> <para> Computes the network mask for the address's network. </para> <para> <literal>netmask(inet '192.168.1.5/24')</literal> <returnvalue>255.255.255.0</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>network</primary> </indexterm> <function>network</function> ( <type>inet</type> ) <returnvalue>cidr</returnvalue> </para> <para> Returns the network part of the address, zeroing out whatever is to the right of the netmask. (This is equivalent to casting the value to <type>cidr</type>.) </para> <para> <literal>network(inet '192.168.1.5/24')</literal> <returnvalue>192.168.1.0/24</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>set_masklen</primary> </indexterm> <function>set_masklen</function> ( <type>inet</type>, <type>integer</type> ) <returnvalue>inet</returnvalue> </para> <para> Sets the netmask length for an <type>inet</type> value. The address part does not change. </para> <para> <literal>set_masklen(inet '192.168.1.5/24', 16)</literal> <returnvalue>192.168.1.5/16</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>set_masklen</function> ( <type>cidr</type>, <type>integer</type> ) <returnvalue>cidr</returnvalue> </para> <para> Sets the netmask length for a <type>cidr</type> value. Address bits to the right of the new netmask are set to zero. </para> <para> <literal>set_masklen(cidr '192.168.1.0/24', 16)</literal> <returnvalue>192.168.0.0/16</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>text</primary> </indexterm> <function>text</function> ( <type>inet</type> ) <returnvalue>text</returnvalue> </para> <para> Returns the unabbreviated IP address and netmask length as text. (This has the same result as an explicit cast to <type>text</type>.) </para> <para> <literal>text(inet '192.168.1.5')</literal> <returnvalue>192.168.1.5/32</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <tip> <para> The <function>abbrev</function>, <function>host</function>, and <function>text</function> functions are primarily intended to offer alternative display formats for IP addresses. </para> </tip> <para> The MAC address types, <type>macaddr</type> and <type>macaddr8</type>, support the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> as well as the specialized functions shown in <xref linkend="macaddr-functions-table"/>. In addition, they support the bitwise logical operators <literal>~</literal>, <literal>&</literal> and <literal>|</literal> (NOT, AND and OR), just as shown above for IP addresses. </para> <table id="macaddr-functions-table"> <title>MAC Address Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>trunc</primary> </indexterm> <function>trunc</function> ( <type>macaddr</type> ) <returnvalue>macaddr</returnvalue> </para> <para> Sets the last 3 bytes of the address to zero. The remaining prefix can be associated with a particular manufacturer (using data not included in <productname>PostgreSQL</productname>). </para> <para> <literal>trunc(macaddr '12:34:56:78:90:ab')</literal> <returnvalue>12:34:56:00:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>trunc</function> ( <type>macaddr8</type> ) <returnvalue>macaddr8</returnvalue> </para> <para> Sets the last 5 bytes of the address to zero. The remaining prefix can be associated with a particular manufacturer (using data not included in <productname>PostgreSQL</productname>). </para> <para> <literal>trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</literal> <returnvalue>12:34:56:00:00:00:00:00</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>macaddr8_set7bit</primary> </indexterm> <function>macaddr8_set7bit</function> ( <type>macaddr8</type> ) <returnvalue>macaddr8</returnvalue> </para> <para> Sets the 7th bit of the address to one, creating what is known as modified EUI-64, for inclusion in an IPv6 address. </para> <para> <literal>macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</literal> <returnvalue>02:34:56:ff:fe:ab:cd:ef</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> </sect1> <sect1 id="functions-textsearch"> <title>Text Search Functions and Operators</title> <indexterm zone="datatype-textsearch"> <primary>full text search</primary> <secondary>functions and operators</secondary> </indexterm> <indexterm zone="datatype-textsearch"> <primary>text search</primary> <secondary>functions and operators</secondary> </indexterm> <para> <xref linkend="textsearch-operators-table"/>, <xref linkend="textsearch-functions-table"/> and <xref linkend="textsearch-functions-debug-table"/> summarize the functions and operators that are provided for full text searching. See <xref linkend="textsearch"/> for a detailed explanation of <productname>PostgreSQL</productname>'s text search facility. </para> <table id="textsearch-operators-table"> <title>Text Search Operators</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Operator </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsvector</type> <literal>@@</literal> <type>tsquery</type> <returnvalue>boolean</returnvalue> </para> <para role="func_signature"> <type>tsquery</type> <literal>@@</literal> <type>tsvector</type> <returnvalue>boolean</returnvalue> </para> <para> Does <type>tsvector</type> match <type>tsquery</type>? (The arguments can be given in either order.) </para> <para> <literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>text</type> <literal>@@</literal> <type>tsquery</type> <returnvalue>boolean</returnvalue> </para> <para> Does text string, after implicit invocation of <function>to_tsvector()</function>, match <type>tsquery</type>? </para> <para> <literal>'fat cats ate rats' @@ to_tsquery('cat & rat')</literal> <returnvalue>t</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsvector</type> <literal>||</literal> <type>tsvector</type> <returnvalue>tsvector</returnvalue> </para> <para> Concatenates two <type>tsvector</type>s. If both inputs contain lexeme positions, the second input's positions are adjusted accordingly. </para> <para> <literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal> <returnvalue>'a':1 'b':2,5 'c':3 'd':4</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsquery</type> <literal>&&</literal> <type>tsquery</type> <returnvalue>tsquery</returnvalue> </para> <para> ANDs two <type>tsquery</type>s together, producing a query that matches documents that match both input queries. </para> <para> <literal>'fat | rat'::tsquery && 'cat'::tsquery</literal> <returnvalue>( 'fat' | 'rat' ) & 'cat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsquery</type> <literal>||</literal> <type>tsquery</type> <returnvalue>tsquery</returnvalue> </para> <para> ORs two <type>tsquery</type>s together, producing a query that matches documents that match either input query. </para> <para> <literal>'fat | rat'::tsquery || 'cat'::tsquery</literal> <returnvalue>'fat' | 'rat' | 'cat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <literal>!!</literal> <type>tsquery</type> <returnvalue>tsquery</returnvalue> </para> <para> Negates a <type>tsquery</type>, producing a query that matches documents that do not match the input query. </para> <para> <literal>!! 'cat'::tsquery</literal> <returnvalue>!'cat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsquery</type> <literal><-></literal> <type>tsquery</type> <returnvalue>tsquery</returnvalue> </para> <para> Constructs a phrase query, which matches if the two input queries match at successive lexemes. </para> <para> <literal>to_tsquery('fat') <-> to_tsquery('rat')</literal> <returnvalue>'fat' <-> 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsquery</type> <literal>@></literal> <type>tsquery</type> <returnvalue>boolean</returnvalue> </para> <para> Does first <type>tsquery</type> contain the second? (This considers only whether all the lexemes appearing in one query appear in the other, ignoring the combining operators.) </para> <para> <literal>'cat'::tsquery @> 'cat & rat'::tsquery</literal> <returnvalue>f</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <type>tsquery</type> <literal><@</literal> <type>tsquery</type> <returnvalue>boolean</returnvalue> </para> <para> Is first <type>tsquery</type> contained in the second? (This considers only whether all the lexemes appearing in one query appear in the other, ignoring the combining operators.) </para> <para> <literal>'cat'::tsquery <@ 'cat & rat'::tsquery</literal> <returnvalue>t</returnvalue> </para> <para> <literal>'cat'::tsquery <@ '!cat & rat'::tsquery</literal> <returnvalue>t</returnvalue> </para></entry> </row> </tbody> </tgroup> </table> <para> In addition to these specialized operators, the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> are available for types <type>tsvector</type> and <type>tsquery</type>. These are not very useful for text searching but allow, for example, unique indexes to be built on columns of these types. </para> <table id="textsearch-functions-table"> <title>Text Search Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>array_to_tsvector</primary> </indexterm> <function>array_to_tsvector</function> ( <type>text[]</type> ) <returnvalue>tsvector</returnvalue> </para> <para> Converts an array of text strings to a <type>tsvector</type>. The given strings are used as lexemes as-is, without further processing. Array elements must not be empty strings or <literal>NULL</literal>. </para> <para> <literal>array_to_tsvector('{fat,cat,rat}'::text[])</literal> <returnvalue>'cat' 'fat' 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>get_current_ts_config</primary> </indexterm> <function>get_current_ts_config</function> ( ) <returnvalue>regconfig</returnvalue> </para> <para> Returns the OID of the current default text search configuration (as set by <xref linkend="guc-default-text-search-config"/>). </para> <para> <literal>get_current_ts_config()</literal> <returnvalue>english</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>length</primary> </indexterm> <function>length</function> ( <type>tsvector</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of lexemes in the <type>tsvector</type>. </para> <para> <literal>length('fat:2,4 cat:3 rat:5A'::tsvector)</literal> <returnvalue>3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>numnode</primary> </indexterm> <function>numnode</function> ( <type>tsquery</type> ) <returnvalue>integer</returnvalue> </para> <para> Returns the number of lexemes plus operators in the <type>tsquery</type>. </para> <para> <literal>numnode('(fat & rat) | cat'::tsquery)</literal> <returnvalue>5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>plainto_tsquery</primary> </indexterm> <function>plainto_tsquery</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>query</parameter> <type>text</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Converts text to a <type>tsquery</type>, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches documents containing all non-stopwords in the text. </para> <para> <literal>plainto_tsquery('english', 'The Fat Rats')</literal> <returnvalue>'fat' & 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>phraseto_tsquery</primary> </indexterm> <function>phraseto_tsquery</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>query</parameter> <type>text</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Converts text to a <type>tsquery</type>, normalizing words according to the specified or default configuration. Any punctuation in the string is ignored (it does not determine query operators). The resulting query matches phrases containing all non-stopwords in the text. </para> <para> <literal>phraseto_tsquery('english', 'The Fat Rats')</literal> <returnvalue>'fat' <-> 'rat'</returnvalue> </para> <para> <literal>phraseto_tsquery('english', 'The Cat and Rats')</literal> <returnvalue>'cat' <2> 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>websearch_to_tsquery</primary> </indexterm> <function>websearch_to_tsquery</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>query</parameter> <type>text</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Converts text to a <type>tsquery</type>, normalizing words according to the specified or default configuration. Quoted word sequences are converted to phrase tests. The word <quote>or</quote> is understood as producing an OR operator, and a dash produces a NOT operator; other punctuation is ignored. This approximates the behavior of some common web search tools. </para> <para> <literal>websearch_to_tsquery('english', '"fat rat" or cat dog')</literal> <returnvalue>'fat' <-> 'rat' | 'cat' & 'dog'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>querytree</primary> </indexterm> <function>querytree</function> ( <type>tsquery</type> ) <returnvalue>text</returnvalue> </para> <para> Produces a representation of the indexable portion of a <type>tsquery</type>. A result that is empty or just <literal>T</literal> indicates a non-indexable query. </para> <para> <literal>querytree('foo & ! bar'::tsquery)</literal> <returnvalue>'foo'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>setweight</primary> </indexterm> <function>setweight</function> ( <parameter>vector</parameter> <type>tsvector</type>, <parameter>w <returnvalue>tsvector</returnvalue> </para> <para> Assigns the specified <parameter>weight</parameter> to each element of the <parameter>vector</parameter>. </para> <para> <literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</literal> <returnvalue>'cat':3A 'fat':2A,4A 'rat':5A</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>setweight</primary> <secondary>setweight for specific lexeme(s)</secondary> </indexterm> <function>setweight</function> ( <parameter>vector</parameter> <type>tsvector</type>, <parameter>w <returnvalue>tsvector</returnvalue> </para> <para> Assigns the specified <parameter>weight</parameter> to elements of the <parameter>vector</parameter> that are listed in <parameter>lexemes</parameter>. The strings in <parameter>lexemes</parameter> are taken as lexemes as-is, without further processing. Strings that do not match any lexeme in <parameter>vector</parameter> are ignored. </para> <para> <literal>setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}')</literal> <returnvalue>'cat':3A 'fat':2,4 'rat':5A,6A</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>strip</primary> </indexterm> <function>strip</function> ( <type>tsvector</type> ) <returnvalue>tsvector</returnvalue> </para> <para> Removes positions and weights from the <type>tsvector</type>. </para> <para> <literal>strip('fat:2,4 cat:3 rat:5A'::tsvector)</literal> <returnvalue>'cat' 'fat' 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_tsquery</primary> </indexterm> <function>to_tsquery</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>query</parameter> <type>text</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Converts text to a <type>tsquery</type>, normalizing words according to the specified or default configuration. The words must be combined by valid <type>tsquery</type> operators. </para> <para> <literal>to_tsquery('english', 'The & Fat & Rats')</literal> <returnvalue>'fat' & 'rat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>to_tsvector</primary> </indexterm> <function>to_tsvector</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>text</type> ) <returnvalue>tsvector</returnvalue> </para> <para> Converts text to a <type>tsvector</type>, normalizing words according to the specified or default configuration. Position information is included in the result. </para> <para> <literal>to_tsvector('english', 'The Fat Rats')</literal> <returnvalue>'fat':2 'rat':3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>to_tsvector</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>json</type> ) <returnvalue>tsvector</returnvalue> </para> <para role="func_signature"> <function>to_tsvector</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>jsonb</type> ) <returnvalue>tsvector</returnvalue> </para> <para> Converts each string value in the JSON document to a <type>tsvector</type>, normalizing words according to the specified or default configuration. The results are then concatenated in document order to produce the output. Position information is generated as though one stopword exists between each pair of string values. (Beware that <quote>document order</quote> of the fields of a JSON object is implementation-dependent when the input is <type>jsonb</type>; observe the difference in the examples.) </para> <para> <literal>to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json)</literal> <returnvalue>'dog':5 'fat':2 'rat':3</returnvalue> </para> <para> <literal>to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb)</literal> <returnvalue>'dog':1 'fat':4 'rat':5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>json_to_tsvector</primary> </indexterm> <function>json_to_tsvector</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>json</type>, <parameter>filter</parameter> <type>jsonb</type> ) <returnvalue>tsvector</returnvalue> </para> <para role="func_signature"> <indexterm> <primary>jsonb_to_tsvector</primary> </indexterm> <function>jsonb_to_tsvector</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>jsonb</type>, <parameter>filter</parameter> <type>jsonb</type> ) <returnvalue>tsvector</returnvalue> </para> <para> Selects each item in the JSON document that is requested by the <parameter>filter</parameter> and converts each one to a <type>tsvector</type>, normalizing words according to the specified or default configuration. The results are then concatenated in document order to produce the output. Position information is generated as though one stopword exists between each pair of selected items. (Beware that <quote>document order</quote> of the fields of a JSON object is implementation-dependent when the input is <type>jsonb</type>.) The <parameter>filter</parameter> must be a <type>jsonb</type> array containing zero or more of these keywords: <literal>"string"</literal> (to include all string values), <literal>"numeric"</literal> (to include all numeric values), <literal>"boolean"</literal> (to include all boolean values), <literal>"key"</literal> (to include all keys), or <literal>"all"</literal> (to include all the above). As a special case, the <parameter>filter</parameter> can also be a simple JSON value that is one of these keywords. </para> <para> <literal>json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", <returnvalue>'123':5 'fat':2 'rat':3</returnvalue> </para> <para> <literal>json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"' <returnvalue>'123':9 'cat':1 'dog':7 'fat':4 'rat':5</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_delete</primary> </indexterm> <function>ts_delete</function> ( <parameter>vector</parameter> <type>tsvector</type>, <parameter>l <returnvalue>tsvector</returnvalue> </para> <para> Removes any occurrence of the given <parameter>lexeme</parameter> from the <parameter>vector</parameter>. The <parameter>lexeme</parameter> string is treated as a lexeme as-is, without further processing. </para> <para> <literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')</literal> <returnvalue>'cat':3 'rat':5A</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>ts_delete</function> ( <parameter>vector</parameter> <type>tsvector</type>, <parameter>l <returnvalue>tsvector</returnvalue> </para> <para> Removes any occurrences of the lexemes in <parameter>lexemes</parameter> from the <parameter>vector</parameter>. The strings in <parameter>lexemes</parameter> are taken as lexemes as-is, without further processing. Strings that do not match any lexeme in <parameter>vector</parameter> are ignored. </para> <para> <literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])</literal> <returnvalue>'cat':3</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_filter</primary> </indexterm> <function>ts_filter</function> ( <parameter>vector</parameter> <type>tsvector</type>, <parameter>w <returnvalue>tsvector</returnvalue> </para> <para> Selects only elements with the given <parameter>weights</parameter> from the <parameter>vector</parameter>. </para> <para> <literal>ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}')</literal> <returnvalue>'cat':3B 'rat':5A</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_headline</primary> </indexterm> <function>ts_headline</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>tsquery</type> <optional>, <parameter>options</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Displays, in an abbreviated form, the match(es) for the <parameter>query</parameter> in the <parameter>document</parameter>, which must be raw text not a <type>tsvector</type>. Words in the document are normalized according to the specified or default configuration before matching to the query. Use of this function is discussed in <xref linkend="textsearch-headline"/>, which also describes the available <parameter>options</parameter>. </para> <para> <literal>ts_headline('The fat cat ate the rat.', 'cat')</literal> <returnvalue>The fat <b>cat</b> ate the rat.</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>ts_headline</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>json</type>, <parameter>query</parameter> <type>tsquery</type> <optional>, <parameter>options</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para role="func_signature"> <function>ts_headline</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>jsonb</type>, <parameter>query</parameter> <type>tsquery</type> <optional>, <parameter>options</parameter> <type>text</type> </optional> ) <returnvalue>text</returnvalue> </para> <para> Displays, in an abbreviated form, match(es) for the <parameter>query</parameter> that occur in string values within the JSON <parameter>document</parameter>. See <xref linkend="textsearch-headline"/> for more details. </para> <para> <literal>ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat')</literal> <returnvalue>{"cat": "raining <b>cats</b> and dogs"}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_rank</primary> </indexterm> <function>ts_rank</function> ( <optional> <parameter>weights</parameter> <type>real[]</type>, </optional> <parameter>vector</parameter> <type>tsvector</type>, <parameter>query</parameter> <type>tsquery</type> <optional>, <parameter>normalization</parameter> <type>integer</type> </optional> ) <returnvalue>real</returnvalue> </para> <para> Computes a score showing how well the <parameter>vector</parameter> matches the <parameter>query</parameter>. See <xref linkend="textsearch-ranking"/> for details. </para> <para> <literal>ts_rank(to_tsvector('raining cats and dogs'), 'cat')</literal> <returnvalue>0.06079271</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_rank_cd</primary> </indexterm> <function>ts_rank_cd</function> ( <optional> <parameter>weights</parameter> <type>real[]</type>, </optional> <parameter>vector</parameter> <type>tsvector</type>, <parameter>query</parameter> <type>tsquery</type> <optional>, <parameter>normalization</parameter> <type>integer</type> </optional> ) <returnvalue>real</returnvalue> </para> <para> Computes a score showing how well the <parameter>vector</parameter> matches the <parameter>query</parameter>, using a cover density algorithm. See <xref linkend="textsearch-ranking"/> for details. </para> <para> <literal>ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat')</literal> <returnvalue>0.1</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_rewrite</primary> </indexterm> <function>ts_rewrite</function> ( <parameter>query</parameter> <type>tsquery</type>, <parameter>target</parameter> <type>tsquery</type>, <parameter>substitute</parameter> <type>tsquery</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Replaces occurrences of <parameter>target</parameter> with <parameter>substitute</parameter> within the <parameter>query</parameter>. See <xref linkend="textsearch-query-rewriting"/> for details. </para> <para> <literal>ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal> <returnvalue>'b' & ( 'foo' | 'bar' )</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>ts_rewrite</function> ( <parameter>query</parameter> <type>tsquery</type>, <parameter>select</parameter> <type>text</type> ) <returnvalue>tsquery</returnvalue> </para> <para> Replaces portions of the <parameter>query</parameter> according to target(s) and substitute(s) obtained by executing a <command>SELECT</command> command. See <xref linkend="textsearch-query-rewriting"/> for details. </para> <para> <literal>SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')</literal> <returnvalue>'b' & ( 'foo' | 'bar' )</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>tsquery_phrase</primary> </indexterm> <function>tsquery_phrase</function> ( <parameter>query1</parameter> <type>tsquery</type>, <parame <returnvalue>tsquery</returnvalue> </para> <para> Constructs a phrase query that searches for matches of <parameter>query1</parameter> and <parameter>query2</parameter> at successive lexemes (same as <literal><-></literal> operator). </para> <para> <literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))</literal> <returnvalue>'fat' <-> 'cat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <function>tsquery_phrase</function> ( <parameter>query1</parameter> <type>tsquery</type>, <parame <returnvalue>tsquery</returnvalue> </para> <para> Constructs a phrase query that searches for matches of <parameter>query1</parameter> and <parameter>query2</parameter> that occur exactly <parameter>distance</parameter> lexemes apart. </para> <para> <literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</literal> <returnvalue>'fat' <10> 'cat'</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>tsvector_to_array</primary> </indexterm> <function>tsvector_to_array</function> ( <type>tsvector</type> ) <returnvalue>text[]</returnvalue> </para> <para> Converts a <type>tsvector</type> to an array of lexemes. </para> <para> <literal>tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)</literal> <returnvalue>{cat,fat,rat}</returnvalue> </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>unnest</primary> <secondary>for tsvector</secondary> </indexterm> <function>unnest</function> ( <type>tsvector</type> ) <returnvalue>setof record</returnvalue> ( <parameter>lexeme</parameter> <type>text</type>, <parameter>positions</parameter> <type>smallint[]</type>, <parameter>weights</parameter> <type>text</type> ) </para> <para> Expands a <type>tsvector</type> into a set of rows, one per lexeme. </para> <para> <literal>select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector)</literal> <returnvalue></returnvalue> <programlisting> lexeme | positions | weights --------+-----------+--------- cat | {3} | {D} fat | {2,4} | {D,D} rat | {5} | {A} </programlisting> </para></entry> </row> </tbody> </tgroup> </table> <note> <para> All the text search functions that accept an optional <type>regconfig</type> argument will use the configuration specified by <xref linkend="guc-default-text-search-config"/> when that argument is omitted. </para> </note> <para> The functions in <xref linkend="textsearch-functions-debug-table"/> are listed separately because they are not usually used in everyday text searching operations. They are primarily helpful for development and debugging of new text search configurations. </para> <table id="textsearch-functions-debug-table"> <title>Text Search Debugging Functions</title> <tgroup cols="1"> <thead> <row> <entry role="func_table_entry"><para role="func_signature"> Function </para> <para> Description </para> <para> Example(s) </para></entry> </row> </thead> <tbody> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_debug</primary> </indexterm> <function>ts_debug</function> ( <optional> <parameter>config</parameter> <type>regconfig</type>, </optional> <parameter>document</parameter> <type>text</type> ) <returnvalue>setof record</returnvalue> ( <parameter>alias</parameter> <type>text</type>, <parameter>description</parameter> <type>text</type>, <parameter>token</parameter> <type>text</type>, <parameter>dictionaries</parameter> <type>regdictionary[]</type>, <parameter>dictionary</parameter> <type>regdictionary</type>, <parameter>lexemes</parameter> <type>text[]</type> ) </para> <para> Extracts and normalizes tokens from the <parameter>document</parameter> according to the specified or default text search configuration, and returns information about how each token was processed. See <xref linkend="textsearch-configuration-testing"/> for details. </para> <para> <literal>ts_debug('english', 'The Brightest supernovaes')</literal> <returnvalue>(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</ret </para></entry> </row> <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> <primary>ts_lexize</primary> </indexterm> --> -------------------- --> maximum size reached --> -------------------- [Verzeichnis aufwärts0.782unsichere VerbindungÜbersetzung europäischer Sprachen durch Browser2026-08-07] |
2026-08-25