Functions and OperatorsfunctionsoperatorsPostgreSQL provides a large number of
functions and operators for the built-in data types. Users can also
define their own functions and operators, as described in the
&cite-programmer;. The
psql commands \df and
\do can be used to show the list of all actually
available functions and operators, respectively.
If you are concerned about portability then take 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
SQL
standard. Some of this extended functionality is present in other
SQL implementations, and in many cases this
functionality is compatible and consistent between various products.
Logical OperatorsoperatorslogicalBooleanoperatorsoperators, logical
The usual logical operators are available:
andoperatororoperatornotoperatorANDORNOT
SQL uses a three-valued Boolean logic where the null value represents
unknown. Observe the following truth tables:
aba AND ba OR bTRUETRUETRUETRUETRUEFALSEFALSETRUETRUENULLNULLTRUEFALSEFALSEFALSEFALSEFALSENULLFALSENULLNULLNULLNULLNULLaNOT aTRUEFALSEFALSETRUENULLNULLComparison Operatorscomparisonoperators
The usual comparison operators are available, shown in .
Comparison OperatorsOperatorDescription<less than>greater than<=less than or equal to>=greater than or equal to=equal<> or !=not equal
The != operator is converted to
<> in the parser stage. It is not
possible to implement != and
<> operators that do different things.
Comparison operators are available for all data types where this
makes sense. All comparison operators are binary operators that
return values of type boolean; expressions like
1 < 2 < 3 are not valid (because there is
no < operator to compare a Boolean value with
3).
between
In addition to the comparison operators, the special
BETWEEN construct is available.
a BETWEEN x AND y
is equivalent to
a >= x AND a <= y
Similarly,
a NOT BETWEEN x AND y
is equivalent to
a < x OR a > y
There is no difference between the two respective forms apart from
the CPU cycles required to rewrite the first one
into the second one internally.
To check whether a value is or is not null, use the constructs
expression IS NULL
expression IS NOT NULL
or the equivalent, but nonstandard, constructs
expression ISNULL
expression NOTNULL
Do not write
expression = NULL
because NULL> is not equal toNULL>. (The null value represents an unknown value,
and it is not known whether two unknown values are equal.)
Some applications may (incorrectly) require that
expression = NULL
returns true if expression evaluates to
the null value. To support these applications, the run-time option
transform_null_equals can be turned on (e.g.,
SET transform_null_equals TO ON;).
PostgreSQL will then convert
x = NULL clauses to
x IS NULL. This was
the default behavior in releases 6.5 through 7.1.
Boolean values can also be tested using the constructs
expression IS TRUE
expression IS NOT TRUE
expression IS FALSE
expression IS NOT FALSE
expression IS UNKNOWN
expression IS NOT UNKNOWN
These are similar to IS NULL in that they 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 unknown>.
Mathematical Functions and Operators
Mathematical operators are provided for many
PostgreSQL types. For types without
common mathematical conventions for all possible permutations
(e.g., date/time types) we
describe the actual behavior in subsequent sections.
shows the available mathematical operators.
The binary operators are also available for the bit
string types BIT and BIT VARYING, as
shown in .
Bit string arguments to &, |,
and # must be of equal length. When bit
shifting, the original length of the string is preserved, as shown
in the table.
shows the available
mathematical functions. In the table, dp
indicates double precision. The functions
exp, ln,
log, pow,
round (1 argument), sqrt,
and trunc (1 argument) are also available for
the type numeric in place of double
precision. Functions returning a numeric
result take numeric input arguments, unless otherwise
specified. Many of these functions are implemented on top of the
host system's C library; accuracy and behavior in boundary cases
could therefore vary depending on the host system.
Mathematical FunctionsFunctionReturn TypeDescriptionExampleResultabs(x)(same as x>)absolute valueabs(-17.4)17.4cbrt(dp)dpcube rootcbrt(27.0)3ceil(numeric)numericsmallest integer not less than argumentceil(-42.8)-42degrees(dp)dpradians to degreesdegrees(0.5)28.6478897565412exp(dp)dpexponentialexp(1.0)2.71828182845905floor(numeric)numericlargest integer not greater than argumentfloor(-42.8)-43ln(dp)dpnatural logarithmln(2.0)0.693147180559945log(dp)dpbase 10 logarithmlog(100.0)2log(bnumeric,
xnumeric)numericlogarithm to base blog(2.0, 64.0)6.0000000000mod(y,
x)(same as argument types)remainder of y/xmod(9,4)1pi()dpPi constantpi()3.14159265358979pow(edp,
ndp)dpraise a number to exponent epow(9.0, 3.0)729radians(dp)dpdegrees to radiansradians(45.0)0.785398163397448random()dpvalue between 0.0 to 1.0random()round(dp)dpround to nearest integerround(42.4)42round(vnumeric, sinteger)numericround to s decimal placesround(42.4382, 2)42.44sign(numeric)numericsign of the argument (-1, 0, +1)sign(-8.4)-1sqrt(dp)dpsquare rootsqrt(2.0)1.4142135623731trunc(dp)dptruncate toward zerotrunc(42.8)42trunc(numeric,
rinteger)numerictruncate to s decimal placestrunc(42.4382, 2)42.43
Finally, shows the
available trigonometric functions. All trigonometric functions
have arguments and return values of type double
precision.
Trigonometric FunctionsFunctionDescriptionacos(x)inverse cosineasin(x)inverse sineatan(x)inverse tangentatan2(x,
y)inverse tangent of
x/ycos(x)cosinecot(x)cotangentsin(x)sinetan(x)tangent
String Functions and Operators
This section describes functions and operators for examining and
manipulating string values. Strings in this context include values
of all the types CHARACTER, CHARACTER
VARYING, and TEXT. Unless otherwise noted, all
of the functions listed below work on all of these types, but be
wary of potential effects of the automatic padding when using the
CHARACTER type. Generally, the functions described
here also work on data of non-string types by converting that data
to a string representation first. Some functions also exist
natively for bit-string types.
SQL defines some string functions with a special syntax where
certain key words rather than commas are used to separate the
arguments. Details are in .
These functions are also implemented using the regular syntax for
function invocation. (See .)
SQL String Functions and OperatorsFunctionReturn TypeDescriptionExampleResultstring||stringtext
String concatenation
character stringsconcatenation'Post' || 'greSQL'PostgreSQLbit_length(string)integerNumber of bits in stringbit_length('jose')32char_length(string) or character_length(string)integer
Number of characters in string
character stringslengthlengthcharacter stringscharacter strings, lengthchar_length('jose')4convert(string
using conversion_name)text
Change encoding using specified conversion name. Conversions
can be defined by CREATE CONVERSION. Also
there are some pre-defined conversion names. See for available conversion
names.
convert('PostgreSQL' using iso_8859_1_to_utf_8)'PostgreSQL' in Unicode (UTF-8) encodinglower(string)textConvert string to lower caselower('TOM')tomoctet_length(string)integerNumber of bytes in stringoctet_length('jose')4overlay(string placing string from integerfor integer)text
Insert substring
overlayoverlay('Txxxxas' placing 'hom' from 2 for 4)Thomasposition(substring in string)integerLocation of specified substringposition('om' in 'Thomas')3substring(stringfrom integerfor integer)text
Extract substring
substringsubstring('Thomas' from 2 for 3)homsubstring(string from pattern)text
Extract substring matching POSIX regular expression
substringsubstring('Thomas' from '...$')massubstring(string from pattern for escape)text
Extract substring matching SQL regular expression
substringsubstring('Thomas' from '%#"o_a#"_' for '#')omatrim(leading | trailing | bothcharacters from
string)
text
Remove the longest string containing only the
characters (a space by default) from the
beginning/end/both ends of the stringtrim(both 'x' from 'xTomxx')Tomupper(string)textConvert string to upper caseupper('tom')TOM
Additional string manipulation functions are available and are
listed in . Some of them are used internally to implement the
SQL-standard string functions listed in .
Other String FunctionsFunctionReturn TypeDescriptionExampleResultascii(text)integerASCII code of the first character of the argument.ascii('x')120btrim(stringtext, trimtext)text
Remove (trim) the longest string consisting only of characters
in trim from the start and end of
stringbtrim('xyxtrimyyx','xy')trimchr(integer)textCharacter with the given ASCII codechr(65)Aconvert(stringtext,
src_encodingname,dest_encodingname)
text
Convert string to dest_encoding.
The original encoding is specified by
src_encoding. If
src_encoding is omitted, database
encoding is assumed.
convert('text_in_unicode', 'UNICODE', 'LATIN1')text_in_unicode represented in ISO 8859-1decode(stringtext,
typetext)
bytea
Decode binary data from string previously
encoded with encode()>. Parameter type is same as in encode()>.
decode('MTIzAAE=', 'base64')123\000\001encode(databytea,
typetext)
text
Encode binary data to ASCII-only representation. Supported
types are: base64, hex, escape.
encode('123\\000\\001', 'base64')MTIzAAE=initcap(text)textConvert first letter of each word (whitespace separated) to upper caseinitcap('hi thomas')Hi Thomaslength(string)integer
Length of string
character stringslengthlengthcharacter stringscharacter strings, lengthlength('jose')4lpad(stringtext,
lengthinteger, filltext)
text
Fill up the string to length
length by prepending the characters
fill (a space by default). If the
string is already longer than
length then it is truncated (on the
right).
lpad('hi', 5, 'xy')xyxhiltrim(stringtext, texttext)text
Remove the longest string containing only characters from
trim from the start of the string.
ltrim('zzzytrim','xyz')trimmd5(stringtext)text
Calculates the MD5 hash of given string, returning the result in hex.
md5('abc')900150983cd24fb0d6963f7d28e17f72pg_client_encoding()name
Current client encoding name.
pg_client_encoding()SQL_ASCIIquote_ident(string text)text
Return the given string suitably quoted to be used as an identifier
in an SQL query 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.
quote_ident('Foo')"Foo"quote_literal(string text)text
Return the given string suitably quoted to be used as a literal
in an SQL query string.
Embedded quotes and backslashes are properly doubled.
quote_literal('O\'Reilly')'O''Reilly'repeat(text, integer)textRepeat text a number of timesrepeat('Pg', 4)PgPgPgPgreplace(stringtext,
fromtext,
totext)textReplace all occurrences in string of substring
from with substring toreplace('abcdefabcdef', 'cd', 'XX')abXXefabXXefrpad(stringtext,
lengthinteger, filltext)
text
Fill up the string to length
length by appending the characters
fill (a space by default). If the
string is already longer than
length then it is truncated.
rpad('hi', 5, 'xy')hixyxrtrim(string
text, trim text)text
Remove the longest string containing only characters from
trim from the end of the string.
rtrim('trimxxxx','x')trimsplit_part(stringtext,
delimitertext,
columninteger)textSplit string on delimiter
returning the resulting (one based) column number.
split_part('abc~@~def~@~ghi','~@~',2)defstrpos(string, substring)text
Locate specified substring (same as
position(substring in
string), but note the reversed
argument order)
strpos('high','ig')2substr(string, from, count)text
Extract specified substring (same as
substring(string from from for count))
substr('alphabet', 3, 2)phto_ascii(text, encoding)text
Convert text to ASCII from other encoding
The to_ascii function supports conversion from
LATIN1>, LATIN2>, and WIN1250> only.
to_ascii('Karel')Karelto_hex(numberinteger
or bigint)textConvert number to its equivalent hexadecimal
representation
to_hex(9223372036854775807::bigint)7ffffffffffffffftranslate(stringtext,
fromtext,
totext)
text
Any character in string that matches a
character in the from set is replaced by
the corresponding character in the to
set.
translate('12345', '14', 'ax')a23x5
Built-in ConversionsConversion Name
The conversion names follow a standard naming scheme: The
official name of the source encoding with all
non-alphanumeric characters replaced by underscores followed
by _to_ followed by the equally processed
destination encoding name. Therefore the names might deviate
from the customary encoding names.
Source EncodingDestination Encodingascii_to_micSQL_ASCIIMULE_INTERNALascii_to_utf_8SQL_ASCIIUNICODEbig5_to_euc_twBIG5EUC_TWbig5_to_micBIG5MULE_INTERNALbig5_to_utf_8BIG5UNICODEeuc_cn_to_micEUC_CNMULE_INTERNALeuc_cn_to_utf_8EUC_CNUNICODEeuc_jp_to_micEUC_JPMULE_INTERNALeuc_jp_to_sjisEUC_JPSJISeuc_jp_to_utf_8EUC_JPUNICODEeuc_kr_to_micEUC_KRMULE_INTERNALeuc_kr_to_utf_8EUC_KRUNICODEeuc_tw_to_big5EUC_TWBIG5euc_tw_to_micEUC_TWMULE_INTERNALeuc_tw_to_utf_8EUC_TWUNICODEgb18030_to_utf_8GB18030UNICODEgbk_to_utf_8GBKUNICODEiso_8859_10_to_utf_8LATIN6UNICODEiso_8859_13_to_utf_8LATIN7UNICODEiso_8859_14_to_utf_8LATIN8UNICODEiso_8859_15_to_utf_8LATIN9UNICODEiso_8859_16_to_utf_8LATIN10UNICODEiso_8859_1_to_micLATIN1MULE_INTERNALiso_8859_1_to_utf_8LATIN1UNICODEiso_8859_2_to_micLATIN2MULE_INTERNALiso_8859_2_to_utf_8LATIN2UNICODEiso_8859_2_to_windows_1250LATIN2WIN1250iso_8859_3_to_micLATIN3MULE_INTERNALiso_8859_3_to_utf_8LATIN3UNICODEiso_8859_4_to_micLATIN4MULE_INTERNALiso_8859_4_to_utf_8LATIN4UNICODEiso_8859_5_to_koi8_rISO_8859_5KOI8iso_8859_5_to_micISO_8859_5MULE_INTERNALiso_8859_5_to_utf_8ISO_8859_5UNICODEiso_8859_5_to_windows_1251ISO_8859_5WINiso_8859_5_to_windows_866ISO_8859_5ALTiso_8859_6_to_utf_8ISO_8859_6UNICODEiso_8859_7_to_utf_8ISO_8859_7UNICODEiso_8859_8_to_utf_8ISO_8859_8UNICODEiso_8859_9_to_utf_8LATIN5UNICODEjohab_to_utf_8JOHABUNICODEkoi8_r_to_iso_8859_5KOI8ISO_8859_5koi8_r_to_micKOI8MULE_INTERNALkoi8_r_to_utf_8KOI8UNICODEkoi8_r_to_windows_1251KOI8WINkoi8_r_to_windows_866KOI8ALTmic_to_asciiMULE_INTERNALSQL_ASCIImic_to_big5MULE_INTERNALBIG5mic_to_euc_cnMULE_INTERNALEUC_CNmic_to_euc_jpMULE_INTERNALEUC_JPmic_to_euc_krMULE_INTERNALEUC_KRmic_to_euc_twMULE_INTERNALEUC_TWmic_to_iso_8859_1MULE_INTERNALLATIN1mic_to_iso_8859_2MULE_INTERNALLATIN2mic_to_iso_8859_3MULE_INTERNALLATIN3mic_to_iso_8859_4MULE_INTERNALLATIN4mic_to_iso_8859_5MULE_INTERNALISO_8859_5mic_to_koi8_rMULE_INTERNALKOI8mic_to_sjisMULE_INTERNALSJISmic_to_windows_1250MULE_INTERNALWIN1250mic_to_windows_1251MULE_INTERNALWINmic_to_windows_866MULE_INTERNALALTsjis_to_euc_jpSJISEUC_JPsjis_to_micSJISMULE_INTERNALsjis_to_utf_8SJISUNICODEtcvn_to_utf_8TCVNUNICODEuhc_to_utf_8UHCUNICODEutf_8_to_asciiUNICODESQL_ASCIIutf_8_to_big5UNICODEBIG5utf_8_to_euc_cnUNICODEEUC_CNutf_8_to_euc_jpUNICODEEUC_JPutf_8_to_euc_krUNICODEEUC_KRutf_8_to_euc_twUNICODEEUC_TWutf_8_to_gb18030UNICODEGB18030utf_8_to_gbkUNICODEGBKutf_8_to_iso_8859_1UNICODELATIN1utf_8_to_iso_8859_10UNICODELATIN6utf_8_to_iso_8859_13UNICODELATIN7utf_8_to_iso_8859_14UNICODELATIN8utf_8_to_iso_8859_15UNICODELATIN9utf_8_to_iso_8859_16UNICODELATIN10utf_8_to_iso_8859_2UNICODELATIN2utf_8_to_iso_8859_3UNICODELATIN3utf_8_to_iso_8859_4UNICODELATIN4utf_8_to_iso_8859_5UNICODEISO_8859_5utf_8_to_iso_8859_6UNICODEISO_8859_6utf_8_to_iso_8859_7UNICODEISO_8859_7utf_8_to_iso_8859_8UNICODEISO_8859_8utf_8_to_iso_8859_9UNICODELATIN5utf_8_to_johabUNICODEJOHAButf_8_to_koi8_rUNICODEKOI8utf_8_to_sjisUNICODESJISutf_8_to_tcvnUNICODETCVNutf_8_to_uhcUNICODEUHCutf_8_to_windows_1250UNICODEWIN1250utf_8_to_windows_1251UNICODEWINutf_8_to_windows_1256UNICODEWIN1256utf_8_to_windows_866UNICODEALTutf_8_to_windows_874UNICODEWIN874windows_1250_to_iso_8859_2WIN1250LATIN2windows_1250_to_micWIN1250MULE_INTERNALwindows_1250_to_utf_8WIN1250UNICODEwindows_1251_to_iso_8859_5WINISO_8859_5windows_1251_to_koi8_rWINKOI8windows_1251_to_micWINMULE_INTERNALwindows_1251_to_utf_8WINUNICODEwindows_1251_to_windows_866WINALTwindows_1256_to_utf_8WIN1256UNICODEwindows_866_to_iso_8859_5ALTISO_8859_5windows_866_to_koi8_rALTKOI8windows_866_to_micALTMULE_INTERNALwindows_866_to_utf_8ALTUNICODEwindows_866_to_windows_1251ALTWINwindows_874_to_utf_8WIN874UNICODE
Binary String Functions and Operators
This section describes functions and operators for examining and
manipulating binary string values. Strings in this context include
values of the type BYTEA.
SQL defines some string functions with a
special syntax where
certain key words rather than commas are used to separate the
arguments. Details are in
.
Some functions are also implemented using the regular syntax for
function invocation.
(See .)
SQL Binary String Functions and OperatorsFunctionReturn TypeDescriptionExampleResultstring||stringbytea
String concatenation
binary stringsconcatenation'\\\\Post'::bytea || '\\047greSQL\\000'::bytea\\Post'greSQL\000octet_length(string)integerNumber of bytes in binary stringoctet_length('jo\\000se'::bytea)5position(substring in string)integerLocation of specified substringposition('\\000om'::bytea in 'Th\\000omas'::bytea)3substring(stringfrom integerfor integer)bytea
Extract substring
substringsubstring('Th\\000omas'::bytea from 2 for 3)h\000otrim(bothcharacters from
string)
bytea
Remove the longest string containing only the
characters from the
beginning/end/both ends of the stringtrim('\\000'::bytea from '\\000Tom\\000'::bytea)Tomget_byte(string, offset)integer
Extract byte from string.
get_byteget_byte('Th\\000omas'::bytea, 4)109set_byte(string, offset)bytea
Set byte in string.
set_byteset_byte('Th\\000omas'::bytea, 4, 64)Th\000o@asget_bit(string, offset)integer
Extract bit from string.
get_bitget_bit('Th\\000omas'::bytea, 45)1set_bit(string, offset)bytea
Set bit in string.
set_bitset_bit('Th\\000omas'::bytea, 45, 0)Th\000omAs
Additional binary string manipulation functions are available and
are listed in . Some
of them are used internally to implement the
SQL-standard string functions listed in .
Other Binary String FunctionsFunctionReturn TypeDescriptionExampleResultbtrim(stringbyteatrimbytea)bytea
Remove (trim) the longest string consisting only of characters
in trim from the start and end of
string.
btrim('\\000trim\\000'::bytea,'\\000'::bytea)trimlength(string)integer
Length of binary string
binary stringslengthlengthbinary stringsbinary strings, lengthlength('jo\\000se'::bytea)5encode(stringbytea,
typetext)
text
Encode binary string to ASCII-only representation. Supported
types are: base64, hex, escape.
encode('123\\000456'::bytea, 'escape')123\000456decode(stringtext,
typetext)
bytea
Decode binary string from string previously
encoded with encode()>. Parameter type is same as in encode()>.
decode('123\\000456', 'escape')123\000456
Pattern Matching
There are three separate approaches to pattern matching provided by
PostgreSQL: the traditional
SQL
LIKE operator, the more recent
SQL99
SIMILAR TO operator, and
POSIX-style regular expressions.
Additionally, a pattern matching function,
SUBSTRING, is available, using either
SQL99-style or POSIX-style regular expressions.
If you have pattern matching needs that go beyond this,
consider writing a user-defined function in Perl or Tcl.
LIKElikestring LIKE patternESCAPE escape-characterstring NOT LIKE patternESCAPE escape-character
Every pattern defines a set of strings.
The LIKE expression returns true if the
string is contained in the set of
strings represented by pattern. (As
expected, the NOT LIKE expression returns
false if LIKE returns true, and vice versa.
An equivalent expression is
NOT (string LIKE
pattern).)
If pattern does not contain percent
signs or underscore, then the pattern only represents the string
itself; in that case LIKE acts like the
equals operator. An underscore (_) in
pattern stands for (matches) any single
character; a percent sign (%) matches any string
of zero or more characters.
Some examples:
'abc' LIKE 'abc' true
'abc' LIKE 'a%' true
'abc' LIKE '_b_' true
'abc' LIKE 'c' falseLIKE pattern matches always cover the entire
string. To match a pattern anywhere within a string, the
pattern must therefore start and end with a percent sign.
To match a literal underscore or percent sign without matching
other characters, the respective character in
pattern must be
preceded by the escape character. The default escape
character is the backslash but a different one may be selected by
using the ESCAPE clause. To match the escape
character itself, write two escape characters.
Note that the backslash already has a special meaning in string
literals, so to write a pattern constant that contains a backslash
you must write two backslashes in the query. Thus, writing a pattern
that actually matches a literal backslash means writing four backslashes
in the query. You can avoid this by selecting a different escape
character with ESCAPE; then backslash is not special
to LIKE anymore. (But it is still special to the string
literal parser, so you still need two of them.)
It's also possible to select no escape character by writing
ESCAPE ''. This effectively disables the
escape mechanism, which makes it impossible to turn off the
special meaning of underscore and percent signs in the pattern.
The keyword ILIKE can be used instead of
LIKE to make the match case insensitive according
to the active locale. This is not in the SQL standard but is a
PostgreSQL extension.
The operator ~~ is equivalent to
LIKE, and ~~* corresponds to
ILIKE. There are also
!~~ and !~~* operators that
represent NOT LIKE and NOT
ILIKE. All of these operators are
PostgreSQL-specific.
SIMILAR TO and SQL99
Regular Expressionsregular expressionssimilar tosubstringstring SIMILAR TO patternESCAPE escape-characterstring NOT SIMILAR TO patternESCAPE escape-character
The SIMILAR TO operator returns true or false
depending on whether its pattern matches the given string. It is
much like LIKE, except that it interprets the
pattern using SQL99's definition of a regular
expression.
SQL99's regular expressions are a curious cross
between LIKE notation and common regular expression
notation.
Like LIKE, the SIMILAR TO
operator succeeds only if its pattern matches the entire string;
this is unlike common regular expression practice, wherein the pattern
may match any part of the string.
Also like
LIKE, SIMILAR TO uses
%> and _> as wildcard characters denoting
any string and any single character, respectively (these are
comparable to .*> and .> in POSIX regular
expressions).
In addition to these facilities borrowed from LIKE,
SIMILAR TO supports these pattern-matching
metacharacters borrowed from POSIX regular expressions:
| denotes alternation (either of two alternatives).
* denotes repetition of the previous item zero
or more times.
+ denotes repetition of the previous item one
or more times.
Parentheses () may be used to group items into
a single logical item.
A bracket expression [...] specifies a character
class, just as in POSIX regular expressions.
Notice that bounded repetition (?> and {...}>)
are not provided, though they exist in POSIX. Also, dot (.>)
is not a metacharacter.
As with LIKE>, a backslash disables the special meaning
of any of these metacharacters; or a different escape character can
be specified with ESCAPE>.
Some examples:
'abc' SIMILAR TO 'abc' true
'abc' SIMILAR TO 'a' false
'abc' SIMILAR TO '%(b|d)%' true
'abc' SIMILAR TO '(b|c)%' false
The SUBSTRING> function with three parameters,
SUBSTRING(string FROM
pattern FOR
escape), provides
extraction of a substring that matches a SQL99 regular expression
pattern. As with SIMILAR TO>, the specified pattern
must match to the entire data string, else the function fails and
returns null. To indicate the part of the pattern that should be
returned on success, SQL99 specifies that the pattern must
contain two occurrences of the escape character followed by
double quote (">). The text matching the portion of
the pattern between these markers is returned.
Some examples:
SUBSTRING('foobar' FROM '%#"o_b#"%' FOR '#') oob
SUBSTRING('foobar' FROM '#"o_b#"%' FOR '#') NULLPOSIX Regular Expressionsregular expressionspattern matching lists the available
operators for pattern matching using POSIX regular expressions.
Regular Expression Match OperatorsOperatorDescriptionExample~Matches regular expression, case sensitive'thomas' ~ '.*thomas.*'~*Matches regular expression, case insensitive'thomas' ~* '.*Thomas.*'!~Does not match regular expression, case sensitive'thomas' !~ '.*Thomas.*'!~*Does not match regular expression, case insensitive'thomas' !~* '.*vadim.*'
POSIX regular expressions provide a more
powerful means for
pattern matching than the LIKE and
SIMILAR TO> operators.
Many Unix tools such as egrep,
sed, or awk use a pattern
matching language that is similar to the one described here.
A regular expression is a character sequence that is an
abbreviated definition of a set of strings (a regular
set). 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 LIKE, pattern characters
match string characters exactly unless they are special characters
in the regular expression language --- but regular expressions use
different special characters than LIKE does.
Unlike LIKE 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.
Some examples:
'abc' ~ 'abc' true
'abc' ~ '^a' true
'abc' ~ '(b|d)' true
'abc' ~ '^(b|c)' false
The SUBSTRING> function with two parameters,
SUBSTRING(string FROM
pattern), provides extraction of a substring
that matches a POSIX regular expression pattern. It returns null if
there is no match, otherwise the 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 always put parentheses around the whole expression
if you want to use parentheses within it without triggering this
exception.
Some examples:
SUBSTRING('foobar' FROM 'o.b') oob
SUBSTRING('foobar' FROM 'o(.)b') o
Regular expressions (REs), as defined in
POSIX
1003.2, come in two forms: modern REs (roughly those of
egrep; 1003.2 calls these
extended REs) and obsolete REs (roughly those of
ed; 1003.2 basic REs).
PostgreSQL implements the modern form.
A (modern) RE is one or more non-empty
branches, separated by
|. It matches anything that matches one of the
branches.
A branch is one or more pieces,
concatenated. It matches a match for the first, followed by a
match for the second, etc.
A piece is an atom possibly followed by a
single *, +,
?, or bound. An atom
followed by * matches a sequence of 0 or more
matches of the atom. An atom followed by +
matches a sequence of 1 or more matches of the atom. An atom
followed by ? matches a sequence of 0 or 1
matches of the atom.
A bound is { followed by
an unsigned decimal integer, possibly followed by
, possibly followed by another unsigned decimal
integer, always followed by }. The integers
must lie between 0 and RE_DUP_MAX (255)
inclusive, and if there are two of them, the first may not exceed
the second. An atom followed by a bound containing one integer
i and no comma matches a sequence of
exactly i matches of the atom. An atom
followed by a bound containing one integer
i and a comma matches a sequence of
i or more matches of the atom. An atom
followed by a bound containing two integers
i and j
matches a sequence of i through
j (inclusive) matches of the atom.
A repetition operator (?,
*, +, or bounds) cannot
follow another repetition operator. A repetition operator cannot
begin an expression or subexpression or follow
^ or |.
An atom is a regular expression enclosed in
() (matching a match for the regular
expression), an empty set of () (matching the
null string), a bracket expression (see
below), . (matching any single character),
^ (matching the null string at the beginning of the
input string), $ (matching the null string at the end
of the input string), a \ followed by one of the
characters ^.[$()|*+?{\ (matching that
character taken as an ordinary character), a \
followed by any other character (matching that character taken as
an ordinary character, as if the \ had not been
present), or a single character with no other significance
(matching that character). A { followed by a
character other than a digit is an ordinary character, not the
beginning of a bound. It is illegal to end an RE with
\.
Note that the backslash (\) already has a special
meaning in string
literals, so to write a pattern constant that contains a backslash
you must write two backslashes in the query.
A bracket expression is a list of
characters enclosed in []. It normally matches
any single character from the list (but see below). If the list
begins with ^, it matches any single character
(but see below) not from the rest of the list. If two characters
in the list are separated by -, this is
shorthand for the full range of characters between those two
(inclusive) in the collating sequence,
e.g. [0-9] in ASCII matches
any decimal digit. It is illegal for two ranges to share an
endpoint, e.g. a-c-e. Ranges are very
collating-sequence-dependent, and portable programs should avoid
relying on them.
To include a literal ] in the list, make it the
first character (following a possible ^). To
include a literal -, make it the first or last
character, or the second endpoint of a range. To use a literal
- as the first endpoint of a range, enclose it
in [. and .] to make it a
collating element (see below). With the exception of these and
some combinations using [ (see next
paragraphs), all other special characters, including
\, lose their special significance within a
bracket expression.
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
[. and .] stands for the
sequence of characters of that collating element. The sequence is
a single element of the bracket expression's list. A bracket
expression containing a multiple-character collating element can thus
match more than one character, e.g. if the collating sequence
includes a ch collating element, then the RE
[[.ch.]]*c matches the first five characters of
chchcc.
Within a bracket expression, a collating element enclosed in
[= and =] is an equivalence
class, 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 [. and
.].) For example, if o and
^ are the members of an equivalence class, then
[[=o=]], [[=^=]], and
[o^] are all synonymous. An equivalence class
may not be an endpoint of a range.
Within a bracket expression, the name of a character class
enclosed in [: and :] stands
for the list of all characters belonging to that class. Standard
character class names are: alnum,
alpha, blank,
cntrl, digit,
graph, lower,
print, punct,
space, upper,
xdigit. These stand for the character classes
defined in
ctype3.
A locale may provide others. A character class may not be used as
an endpoint of a range.
There are two special cases of bracket expressions: the bracket
expressions [[:<:]] and
[[:>:]] match the null string at the beginning
and end of a word respectively. A word is defined as a sequence
of word characters which is neither preceded nor followed by word
characters. A word character is an alnum character (as defined by
ctype3)
or an underscore. This is an extension, compatible with but not
specified by POSIX 1003.2, and should be used with caution in
software intended to be portable to other systems.
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, it matches the longest. Subexpressions also match the
longest possible substrings, subject to the constraint that the
whole match be as long as possible, with subexpressions starting
earlier in the RE taking priority over ones starting later. Note
that higher-level subexpressions thus take priority over their
lower-level component subexpressions.
Match lengths are measured in characters, not collating
elements. A null string is considered longer than no match at
all. For example, bb* matches the three middle
characters of abbbc,
(wee|week)(knights|nights) matches all ten
characters of weeknights, when
(.*).* is matched against
abc the parenthesized subexpression matches all
three characters, and when (a*)* is matched
against bc both the whole RE and the
parenthesized subexpression match the null string.
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. x becomes [xX]. When
it appears inside a bracket expression, all case counterparts of
it are added to the bracket expression, so that (e.g.)
[x] becomes [xX] and
[^x] becomes [^xX].
There is no particular limit on the length of REs, except insofar
as memory is limited. Memory usage is approximately linear in RE
size, and largely insensitive to RE complexity, except for bounded
repetitions. Bounded repetitions are implemented by macro
expansion, which is costly in time and space if counts are large
or bounded repetitions are nested. An RE like, say,
((((a{1,100}){1,100}){1,100}){1,100}){1,100}
will (eventually) run almost any existing machine out of swap
space.
This was written in 1994, mind you. The
numbers have probably changed, but the problem
persists.
Data Type Formatting Functionsformatting
The PostgreSQL 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.
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.
Formatting FunctionsFunctionReturnsDescriptionExampleto_char(timestamp, text)textconvert time stamp to stringto_char(timestamp 'now','HH12:MI:SS')to_char(interval, text)textconvert interval to stringto_char(interval '15h 2m 12s','HH24:MI:SS')to_char(int, text)textconvert integer to stringto_char(125, '999')to_char(double precision,
text)textconvert real/double precision to stringto_char(125.8, '999D9')to_char(numeric, text)textconvert numeric to stringto_char(numeric '-125.8', '999D99S')to_date(text, text)dateconvert string to dateto_date('05 Dec 2000', 'DD Mon YYYY')to_timestamp(text, text)timestampconvert string to time stampto_timestamp('05 Dec 2000', 'DD Mon YYYY')to_number(text, text)numericconvert string to numericto_number('12,454.8-', '99G999D9S')
In an output template string, there are certain patterns that are
recognized and replaced with appropriately-formatted data from the value
to be formatted. Any text that is not a template pattern is simply
copied verbatim. Similarly, in an input template string, template patterns
identify the parts of the input data string to be looked at and the
values to be found there.
shows the
template patterns available for formatting date and time values.
Template patterns for date/time conversionsPatternDescriptionHHhour of day (01-12)HH12hour of day (01-12)HH24hour of day (00-23)MIminute (00-59)SSsecond (00-59)MSmillisecond (000-999)USmicrosecond (000000-999999)SSSSseconds past midnight (0-86399)AM or A.M. or
PM or P.M.meridian indicator (upper case)am or a.m. or
pm or p.m.meridian indicator (lower case)Y,YYYyear (4 and more digits) with commaYYYYyear (4 and more digits)YYYlast 3 digits of yearYYlast 2 digits of yearYlast digit of yearBC or B.C. or
AD or A.D.era indicator (upper case)bc or b.c. or
ad or a.d.era indicator (lower case)MONTHfull upper case month name (blank-padded to 9 chars)Monthfull mixed case month name (blank-padded to 9 chars)monthfull lower case month name (blank-padded to 9 chars)MONabbreviated upper case month name (3 chars)Monabbreviated mixed case month name (3 chars)monabbreviated lower case month name (3 chars)MMmonth number (01-12)DAYfull upper case day name (blank-padded to 9 chars)Dayfull mixed case day name (blank-padded to 9 chars)dayfull lower case day name (blank-padded to 9 chars)DYabbreviated upper case day name (3 chars)Dyabbreviated mixed case day name (3 chars)dyabbreviated lower case day name (3 chars)DDDday of year (001-366)DDday of month (01-31)Dday of week (1-7; SUN=1)Wweek of month (1-5) where first week start on the first day of the monthWWweek number of year (1-53) where first week start on the first day of the yearIWISO week number of year (The first Thursday of the new year is in week 1.)CCcentury (2 digits)JJulian Day (days since January 1, 4712 BC)QquarterRMmonth in Roman Numerals (I-XII; I=January) - upper casermmonth in Roman Numerals (I-XII; I=January) - lower caseTZtime-zone name - upper casetztime-zone name - lower case
Certain modifiers may be applied to any template pattern to alter its
behavior. For example, FMMonth
is the Month pattern with the
FM prefix.
shows the
modifier patterns for date/time formatting.
Template pattern modifiers for date/time conversionsModifierDescriptionExampleFM prefixfill mode (suppress padding blanks and zeroes)FMMonthTH suffixadd upper-case ordinal number suffixDDTHth suffixadd lower-case ordinal number suffixDDthFX prefixfixed format global option (see usage notes)FX Month DD DaySP suffixspell mode (not yet implemented)DDSP
Usage notes for the date/time formatting:
FM suppresses leading zeroes and trailing blanks
that would otherwise be added to make the output of a pattern be
fixed-width.
to_timestamp and to_date
skip multiple blank spaces in the input string if the FX option
is not used. FX must be specified as the first item
in the template; for example
to_timestamp('2000 JUN','YYYY MON') is right, but
to_timestamp('2000 JUN','FXYYYY MON') returns an error,
because to_timestamp expects one blank space only.
If a backslash (\) is desired
in a string constant, a double backslash
(\\) must be entered; for
example '\\HH\\MI\\SS'. This is true for
any string constant in PostgreSQL.
Ordinary text is allowed in to_char
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 pattern keywords. For example, in
'"Hello Year "YYYY', the YYYY
will be replaced by the year data, but the single Y in Year
will not be.
If you want to have a double quote in the output you must
precede it with a backslash, for example '\\"YYYY
Month\\"'.
YYYY conversion from string to timestamp or
date is restricted if you use a year with more than 4 digits. You must
use some non-digit character or template after YYYY,
otherwise the year is always interpreted as 4 digits. For example
(with year 20000):
to_date('200001131', 'YYYYMMDD') will be
interpreted as a 4-digit year; better is to use a non-digit
separator after the year, like
to_date('20000-1131', 'YYYY-MMDD') or
to_date('20000Nov31', 'YYYYMonDD').
Millisecond MS and microsecond US
values in a conversion from string to time stamp are used as part of the
seconds after the decimal point. For example
to_timestamp('12:3', 'SS:MS') is not 3 milliseconds,
but 300, because the conversion counts it as 12 + 0.3.
This means for the format SS:MS, the input values
12:3, 12:30, and 12:300 specify the
same number of milliseconds. To get three milliseconds, one must use
12:003, which the conversion counts as
12 + 0.003 = 12.003 seconds.
Here is a more
complex example:
to_timestamp('15:12:02.020.001230','HH:MI:SS.MS.US')
is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
1230 microseconds = 2.021230 seconds.
shows the
template patterns available for formatting numeric values.
Template patterns for numeric conversionsPatternDescription9value with the specified number of digits0value with leading zeros. (period)decimal point, (comma)group (thousand) separatorPRnegative value in angle bracketsSnegative value with minus sign (uses locale)Lcurrency symbol (uses locale)Ddecimal point (uses locale)Ggroup separator (uses locale)MIminus sign in specified position (if number < 0)PLplus sign in specified position (if number > 0)SGplus/minus sign in specified positionRNroman numeral (input between 1 and 3999)TH or thconvert to ordinal numberVshift n digits (see
notes)EEEEscientific notation (not implemented yet)
Usage notes for the numeric formatting:
A sign formatted using SG, PL, or
MI is not an anchor in
the number; for example,
to_char(-12, 'S9999') produces ' -12',
but to_char(-12, 'MI9999') produces '- 12'.
The Oracle implementation does not allow the use of
MI ahead of 9, but rather
requires that 9 precede
MI.
9 specifies a value with the same number of
digits as there are 9s. If a digit is
not available it outputs a space.
TH does not convert values less than zero
and does not convert decimal numbers.
PL, SG, and
TH are PostgreSQL
extensions.
V effectively
multiplies the input values by
10^n, where
n is the number of digits following
V.
to_char does not support the use of
V combined with a decimal point.
(E.g., 99.9V99 is not allowed.)
shows some
examples of the use of the to_char function.
Date/Time Functions and Operators shows the available
functions for date/time value processing, with details appearing in
the following subsections. illustrates the behaviors of
the basic arithmetic operators (+,
*, etc.). For formatting functions, refer to
. You should be familiar with
the background information on date/time data types (see ).
All the functions and operators described below that take time or timestamp
inputs actually come in two variants: one that takes time or timestamp
with time zone, and one that takes time or timestamp without time zone.
For brevity, these variants are not shown separately.
Date/Time FunctionsNameReturn TypeDescriptionExampleResultage(timestamp)intervalSubtract from todayage(timestamp '1957-06-13')43 years 8 mons 3 daysage(timestamp, timestamp)intervalSubtract argumentsage('2001-04-10', timestamp '1957-06-13')43 years 9 mons 27 dayscurrent_datedateToday's date; see current_timetime with time zoneTime of day; see current_timestamptimestamp with time zoneDate and time; see date_part(text, timestamp)double precisionGet subfield (equivalent to
extract); see also below
date_part('hour', timestamp '2001-02-16 20:38:40')20date_part(text, interval)double precisionGet subfield (equivalent to
extract); see also below
date_part('month', interval '2 years 3 months')3date_trunc(text, timestamp)timestampTruncate to specified precision; see also date_trunc('hour', timestamp '2001-02-16 20:38:40')2001-02-16 20:00:00+00extract(field from
timestamp)double precisionGet subfield; see also extract(hour from timestamp '2001-02-16 20:38:40')20extract(field from
interval)double precisionGet subfield; see also extract(month from interval '2 years 3 months')3isfinite(timestamp)booleanTest for finite time stamp (neither invalid nor infinity)isfinite(timestamp '2001-02-16 21:28:30')trueisfinite(interval)booleanTest for finite intervalisfinite(interval '4 hours')truelocaltimetimeTime of day; see localtimestamptimestampDate and time; see now()timestamp with time zoneCurrent date and time (equivalent to
current_timestamp); see timeofday()textCurrent date and time; see timeofday()Wed Feb 21 17:01:13.000126 2001 EST
EXTRACT, date_part
EXTRACT (field FROM source)
The extract function retrieves subfields
from date/time values, such as year or hour.
source is a value expression that
evaluates to type timestamp or interval.
(Expressions of type date or time will
be cast to timestamp and can therefore be used as
well.) field is an identifier or
string that selects what field to extract from the source value.
The extract function returns values of type
double precision.
The following are valid values:
century
The year field divided by 100
SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 20
Note that the result for the century field is simply the year field
divided by 100, and not the conventional definition which puts most
years in the 1900's in the twentieth century.
day
The day (of the month) field (1 - 31)
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16decade
The year field divided by 10
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200dow
The day of the week (0 - 6; Sunday is 0) (for
timestamp values only)
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5doy
The day of the year (1 - 365/366) (for timestamp values only)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47epoch
For date and timestamp values, the
number of seconds since 1970-01-01 00:00:00-00 (can be negative);
for interval values, the total number
of seconds in the interval
SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 982352320
SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
Result: 442800hour
The hour field (0 - 23)
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 20microseconds
The seconds field, including fractional parts, multiplied by 1
000 000. Note that this includes full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
Result: 28500000millennium
The year field divided by 1000
SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2
Note that the result for the millennium field is simply the year field
divided by 1000, and not the conventional definition which puts
years in the 1900's in the second millennium.
milliseconds
The seconds field, including fractional parts, multiplied by
1000. Note that this includes full seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
Result: 28500minute
The minutes field (0 - 59)
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38month
For timestamp values, the number of the month
within the year (1 - 12) ; for interval values
the number of months, modulo 12 (0 - 11)
SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2
SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
Result: 3
SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
Result: 1quarter
The quarter of the year (1 - 4) that the day is in (for
timestamp values only)
SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 1second
The seconds field, including fractional parts (0 -
5960 if leap seconds are
implemented by the operating system)
SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 40
SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
Result: 28.5timezone_hour
The hour component of the time zone offset.
timezone_minute
The minute component of the time zone offset.
week
From a timestamp value, calculate the number of
the week of the year that the day is in. By definition
(ISO 8601), the first week of a year
contains January 4 of that year. (The ISO
week starts on Monday.) In other words, the first Thursday of
a year is in week 1 of that year.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7year
The year field
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001
The extract function is primarily intended
for computational processing. For formatting date/time values for
display, see .
The date_part function is modeled on the traditional
Ingres equivalent to the
SQL-standard function extract:
date_part('field', source)
Note that here the field parameter needs to
be a string value, not a name. The valid field values for
date_part are the same as for
extract.
SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
Result: 4date_trunc
The function date_trunc is conceptually
similar to the trunc function for numbers.
date_trunc('field', source)
source is a value expression of type
timestamp (values of type date and
time are cast automatically).
field selects to which precision to
truncate the time stamp value. The return value is of type
timestamp with all fields that are less than the
selected one set to zero (or one, for day and month).
Valid values for field are:
microsecondsmillisecondssecondminutehourdaymonthyeardecadecenturymillennium
Examples:
SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-02-16 20:00:00+00
SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-01-01 00:00:00+00AT TIME ZONEtimezoneconversion
The AT TIME ZONE construct allows conversions
of timestamps to different timezones.
AT TIME ZONE VariantsExpressionReturnsDescriptiontimestamp without time zoneAT TIME ZONEzone>
timestamp with time zoneConvert local time in given timezone to UTCtimestamp with time zoneAT TIME ZONEzone>
timestamp without time zoneConvert UTC to local time in given timezonetime with time zoneAT TIME ZONEzone>
time with time zoneConvert local time across timezones
In these expressions, the desired time zone> can be
specified either as a text string (e.g., 'PST')
or as an interval (e.g., INTERVAL '-08:00').
Examples (supposing that TimeZone> is PST8PDT>):
SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
Result: 2001-02-16 19:38:40-08
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
Result: 2001-02-16 18:38:40
The first example takes a zone-less timestamp and interprets it as MST time
(GMT-7) to produce a UTC timestamp, which is then rotated to PST (GMT-8)
for display. The second example takes a timestamp specified in EST
(GMT-5) and converts it to local time in MST (GMT-7).
The function timezone(zone>,
timestamp>) is equivalent to the SQL-compliant construct
timestamp> AT TIME ZONEzone>.
Current Date/Timedatecurrenttimecurrent
The following functions are available to obtain the current date and/or
time:
CURRENT_DATE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_TIME ( precision )
CURRENT_TIMESTAMP ( precision )
LOCALTIME
LOCALTIMESTAMP
LOCALTIME ( precision )
LOCALTIMESTAMP ( precision )
CURRENT_TIME and
CURRENT_TIMESTAMP deliver values with time zone;
LOCALTIME and
LOCALTIMESTAMP deliver values without time zone.
CURRENT_TIME,
CURRENT_TIMESTAMP,
LOCALTIME, and
LOCALTIMESTAMP
can optionally be given
a precision parameter, which causes the result to be rounded
to that many fractional digits. Without a precision parameter,
the result is given to the full available precision.
Prior to PostgreSQL 7.2, the precision
parameters were unimplemented, and the result was always given
in integer seconds.
Some examples:
SELECT CURRENT_TIME;
14:39:53.662522-05
SELECT CURRENT_DATE;
2001-12-23
SELECT CURRENT_TIMESTAMP;
2001-12-23 14:39:53.662522-05
SELECT CURRENT_TIMESTAMP(2);
2001-12-23 14:39:53.66-05
SELECT LOCALTIMESTAMP;
2001-12-23 14:39:53.662522
The function now() is the traditional
PostgreSQL equivalent to
CURRENT_TIMESTAMP.
There is also timeofday(), which for historical
reasons returns a text string rather than a timestamp value:
SELECT timeofday();
Sat Feb 17 19:07:32.000126 2001 EST
It is important to realize that
CURRENT_TIMESTAMP and related functions return
the start time of the current transaction; their values do not
change during the transaction. timeofday()
returns the wall clock time and does advance during transactions.
Many other database systems advance these values more
frequently.
All the date/time data types also accept the special literal value
now to specify the current date and time. Thus,
the following three all return the same result:
SELECT CURRENT_TIMESTAMP;
SELECT now();
SELECT TIMESTAMP 'now';
You do not want to use the third form when specifying a DEFAULT>
clause while creating a table. The system will convert now
to a timestamp 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.
Geometric Functions and Operators
The geometric types point, box,
lseg, line, path,
polygon, and circle have a large set of
native support functions and operators, shown in , , and .
Geometric OperatorsOperatorDescriptionUsage + Translationbox '((0,0),(1,1))' + point '(2.0,0)' - Translationbox '((0,0),(1,1))' - point '(2.0,0)' * Scaling/rotationbox '((0,0),(1,1))' * point '(2.0,0)' / Scaling/rotationbox '((0,0),(2,2))' / point '(2.0,0)' # Intersection'((1,-1),(-1,1))' # '((1,1),(-1,-1))' # Number of points in path or polygon# '((1,0),(0,1),(-1,0))' ## Point of closest proximitypoint '(0,0)' ## lseg '((2,0),(0,2))' && Overlaps?box '((0,0),(1,1))' && box '((0,0),(2,2))' &< Overlaps to left?box '((0,0),(1,1))' &< box '((0,0),(2,2))' &> Overlaps to right?box '((0,0),(3,3))' &> box '((0,0),(2,2))' <-> Distance betweencircle '((0,0),1)' <-> circle '((5,0),1)' << Left of?circle '((0,0),1)' << circle '((5,0),1)' <^ Is below?circle '((0,0),1)' <^ circle '((0,5),1)' >> Is right of?circle '((5,0),1)' >> circle '((0,0),1)' >^ Is above?circle '((0,5),1)' >^ circle '((0,0),1)' ?# Intersects or overlapslseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))' ?- Is horizontal?point '(1,0)' ?- point '(0,0)' ?-| Is perpendicular?lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))' @-@ Length or circumference@-@ path '((0,0),(1,0))' ?| Is vertical?point '(0,1)' ?| point '(0,0)' ?|| Is parallel?lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))' @ Contained or onpoint '(1,1)' @ circle '((0,0),2)' @@ Center of@@ circle '((0,0),10)' ~= Same aspolygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'
Geometric FunctionsFunctionReturnsDescriptionExamplearea(object)double precisionarea of itemarea(box '((0,0),(1,1))')box(box, box)boxintersection boxbox(box '((0,0),(1,1))',box '((0.5,0.5),(2,2))')center(object)pointcenter of itemcenter(box '((0,0),(1,2))')diameter(circle)double precisiondiameter of circlediameter(circle '((0,0),2.0)')height(box)double precisionvertical size of boxheight(box '((0,0),(1,1))')isclosed(path)booleana closed path?isclosed(path '((0,0),(1,1),(2,0))')isopen(path)booleanan open path?isopen(path '[(0,0),(1,1),(2,0)]')length(object)double precisionlength of itemlength(path '((-1,0),(1,0))')npoints(path)integernumber of pointsnpoints(path '[(0,0),(1,1),(2,0)]')npoints(polygon)integernumber of pointsnpoints(polygon '((1,1),(0,0))')pclose(path)pathconvert path to closedpopen(path '[(0,0),(1,1),(2,0)]')point(lseg,lseg)pointintersectionpoint(lseg '((-1,0),(1,0))',lseg '((-2,-2),(2,2))')
]]>
popen(path)pathconvert path to open pathpopen(path '((0,0),(1,1),(2,0))')radius(circle)double precisionradius of circleradius(circle '((0,0),2.0)')width(box)double precisionhorizontal sizewidth(box '((0,0),(1,1))')
Geometric Type Conversion FunctionsFunctionReturnsDescriptionExamplebox(circle)boxcircle to boxbox(circle '((0,0),2.0)')box(point, point)boxpoints to boxbox(point '(0,0)', point '(1,1)')box(polygon)boxpolygon to boxbox(polygon '((0,0),(1,1),(2,0))')circle(box)circleto circlecircle(box '((0,0),(1,1))')circle(point, double precision)circlepoint to circlecircle(point '(0,0)', 2.0)lseg(box)lsegbox diagonal to lseglseg(box '((-1,0),(1,0))')lseg(point, point)lsegpoints to lseglseg(point '(-1,0)', point '(1,0)')path(polygon)pointpolygon to pathpath(polygon '((0,0),(1,1),(2,0))')point(circle)pointcenterpoint(circle '((0,0),2.0)')point(lseg, lseg)pointintersectionpoint(lseg '((-1,0),(1,0))', lseg '((-2,-2),(2,2))')point(polygon)pointcenterpoint(polygon '((0,0),(1,1),(2,0))')polygon(box)polygon4-point polygonpolygon(box '((0,0),(1,1))')polygon(circle)polygon12-point polygonpolygon(circle '((0,0),2.0)')polygon(npts, circle)polygonnpts polygonpolygon(12, circle '((0,0),2.0)')polygon(path)polygonpath to polygonpolygon(path '((0,0),(1,1),(2,0))')
It is possible to access the two component numbers of a point>
as though it were an array with subscripts 0, 1. For example, if
t.p> is a point> column then
SELECT p[0] FROM t> retrieves the X coordinate;
UPDATE t SET p[1] = ...> changes the Y coordinate.
In the same way, a box> or an lseg> may be treated
as an array of two point>s.
Network Address Type Functions shows the operators
available for the inet and cidr types.
The operators <<,
<<=, >>,
>>= test for subnet inclusion: they
consider only the network parts of the two addresses, ignoring any
host part, and determine whether one network part is identical to
or a subnet of the other.
cidr and inet OperatorsOperatorDescriptionUsage < Less thaninet '192.168.1.5' < inet '192.168.1.6' <= Less than or equalinet '192.168.1.5' <= inet '192.168.1.5' = Equalsinet '192.168.1.5' = inet '192.168.1.5' >= Greater or equalinet '192.168.1.5' >= inet '192.168.1.5' > Greaterinet '192.168.1.5' > inet '192.168.1.4' <> Not equalinet '192.168.1.5' <> inet '192.168.1.4' << is contained withininet '192.168.1.5' << inet '192.168.1/24' <<= is contained within or equalsinet '192.168.1/24' <<= inet '192.168.1/24' >> containsinet'192.168.1/24' >> inet '192.168.1.5' >>= contains or equalsinet '192.168.1/24' >>= inet '192.168.1/24'
shows the functions
available for use with the inet and cidr
types. The host(),
text(), and abbrev()
functions are primarily intended to offer alternative display
formats. You can cast a text field to inet using normal casting
syntax: inet(expression) or
colname::inet.
cidr and inet FunctionsFunctionReturnsDescriptionExampleResultbroadcast(inet)inetbroadcast address for networkbroadcast('192.168.1.5/24')192.168.1.255/24host(inet)textextract IP address as texthost('192.168.1.5/24')192.168.1.5masklen(inet)integerextract netmask lengthmasklen('192.168.1.5/24')24set_masklen(inet,integer)inetset netmask length for inet valueset_masklen('192.168.1.5/24',16)192.168.1.5/16netmask(inet)inetconstruct netmask for networknetmask('192.168.1.5/24')255.255.255.0network(inet)cidrextract network part of addressnetwork('192.168.1.5/24')192.168.1.0/24text(inet)textextract IP address and masklen as texttext(inet '192.168.1.5')192.168.1.5/32abbrev(inet)textextract abbreviated display as textabbrev(cidr '10.1.0.0/16')10.1/16
shows the functions
available for use with the mac type. The function
trunc(macaddr) returns a MAC
address with the last 3 bytes set to 0. This can be used to
associate the remaining prefix with a manufacturer. The directory
contrib/mac in the source distribution
contains some utilities to create and maintain such an association
table.
macaddr FunctionsFunctionReturnsDescriptionExampleResulttrunc(macaddr)macaddrset last 3 bytes to zerotrunc(macaddr '12:34:56:78:90:ab')12:34:56:00:00:00
The macaddr type also supports the standard relational
operators (>, <=, etc.) for
lexicographical ordering.
Sequence-Manipulation Functionssequencesnextvalcurrvalsetval
This section describes PostgreSQL's functions
for operating on sequence objects.
Sequence objects (also called sequence generators or
just sequences) are special single-row tables created with
CREATE SEQUENCE. A sequence object is usually used to
generate unique identifiers for rows of a table. The sequence functions,
listed in ,
provide simple, multiuser-safe methods for obtaining successive
sequence values from sequence objects.
Sequence FunctionsFunctionReturnsDescriptionnextval(text)bigintAdvance sequence and return new valuecurrval(text)bigintReturn value most recently obtained with nextvalsetval(text,bigint)bigintSet sequence's current valuesetval(text,bigint,boolean)bigintSet sequence's current value and is_called flag
For largely historical reasons, the sequence to be operated on by
a sequence-function call is specified by a text-string argument.
To achieve some compatibility with the handling of ordinary SQL
names, the sequence functions convert their argument to lower case
unless the string is double-quoted. Thus
nextval('foo') operates on sequence foo>
nextval('FOO') operates on sequence foo>
nextval('"Foo"') operates on sequence Foo>
The sequence name can be schema-qualified if necessary:
nextval('myschema.foo') operates on myschema.foo>
nextval('"myschema".foo') same as above
nextval('foo') searches search path for foo>
Of course, the text argument can be the result of an expression,
not only a simple literal, which is occasionally useful.
The available sequence functions are:
nextval
Advance the sequence object to its next value and return that
value. This is done atomically: even if multiple sessions
execute nextval concurrently, each will safely receive
a distinct sequence value.
currval
Return the value most recently obtained by nextval
for this sequence in the current session. (An error is
reported if nextval has never been called for this
sequence in this session.) Notice that because this is returning
a session-local value, it gives a predictable answer even if other
sessions are executing nextval meanwhile.
setval
Reset the sequence object's counter value. The two-parameter
form sets the sequence's last_value field to the specified
value and sets its is_called field to true,
meaning that the next nextval will advance the sequence
before returning a value. In the three-parameter form,
is_called may be set either true or
false. If it's set to false,
the next nextval will return exactly the specified
value, and sequence advancement commences with the following
nextval. For example,
SELECT setval('foo', 42); Next nextval()> will return 43
SELECT setval('foo', 42, true); Same as above
SELECT setval('foo', 42, false); Next nextval()> will return 42
The result returned by setval is just the value of its
second argument.
To avoid blocking of concurrent transactions that obtain numbers from the
same sequence, a nextval operation is never rolled back;
that is, once a value has been fetched it is considered used, even if the
transaction that did the nextval later aborts. This means
that aborted transactions may leave unused holes in the
sequence of assigned values. setval operations are never
rolled back, either.
If a sequence object has been created with default parameters,
nextval() calls on it will return successive values
beginning with one. Other behaviors can be obtained by using
special parameters in the CREATE SEQUENCE command;
see its command reference page for more information.
Conditional Expressionscaseconditionals
This section describes the SQL-compliant conditional expressions
available in PostgreSQL.
If your needs go beyond the capabilities of these conditional
expressions you might want to consider writing a stored procedure
in a more expressive programming language.
CASE
CASE WHEN condition THEN resultWHEN ...ELSE result
END
The SQL CASE expression is a
generic conditional expression, similar to if/else statements in
other languages. CASE clauses can be used wherever
an expression is valid. condition is an
expression that returns a boolean result. If the result is true
then the value of the CASE expression is
result. If the result is false any
subsequent WHEN clauses are searched in the same
manner. If no WHENcondition is true then the value of the
case expression is the result in the
ELSE clause. If the ELSE clause is
omitted and no condition matches, the result is null.
An example:
=>SELECT * FROM test;
a
---
1
2
3
=>SELECT a,
CASE WHEN a=1 THEN 'one'
WHEN a=2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
The data types of all the result
expressions must be coercible to a single output type.
See for more detail.
CASE expression
WHEN value THEN resultWHEN ...ELSE result
END
This simpleCASE expression is a
specialized variant of the general form above. The
expression is computed and compared to
all the values in the
WHEN clauses until one is found that is equal. If
no match is found, the result in the
ELSE clause (or a null value) is returned. This is similar
to the switch statement in C.
The example above can be written using the simple
CASE syntax:
=>SELECT a,
CASE a WHEN 1 THEN 'one'
WHEN 2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
COALESCECOALESCE(value, ...)
The COALESCE function returns the first of its
arguments that is not null. This is often useful to substitute a
default value for null values when data is retrieved for display,
for example:
SELECT COALESCE(description, short_description, '(none)') ...
NULLIFnullifNULLIF(value1, value2)
The NULLIF function returns a null value if and only
if value1 and
value2 are equal. Otherwise it returns
value1. This can be used to perform the
inverse operation of the COALESCE example
given above:
SELECT NULLIF(value, '(none)') ...
COALESCE and NULLIF are
just shorthand for CASE expressions. They are actually
converted into CASE expressions at a very early stage
of processing, and subsequent processing thinks it is dealing with
CASE. Thus an incorrect COALESCE or
NULLIF usage may draw an error message that
refers to CASE.
Miscellaneous Functions shows several
functions that extract session and system information.
Session Information FunctionsNameReturn TypeDescriptioncurrent_database()namename of current databasecurrent_schema()namename of current schemacurrent_schemas(boolean)name[]names of schemas in search path optionally including implicit schemascurrent_usernameuser name of current execution contextsession_usernamesession user nameusernameequivalent to current_userversion()textPostgreSQL version information
usercurrentschemacurrentsearch pathcurrent
The session_user is the user that initiated a
database connection; it is fixed for the duration of that
connection. The current_user is the user identifier
that is applicable for permission checking. Normally, it is equal
to the session user, but it changes during the execution of
functions with the attribute SECURITY DEFINER.
In Unix parlance, the session user is the real user and
the current user is the effective user.
current_user, session_user, and
user have special syntactic status in SQL:
they must be called without trailing parentheses.
current_schema returns the name of the schema that is
at the front of the search path (or a null value if the search path is
empty). This is the schema that will be used for any tables or
other named objects that are created without specifying a target schema.
current_schemas(boolean) returns an array of the names of all
schemas presently in the search path. The boolean option determines whether or not
implicitly included system schemas such as pg_catalog are included in the search
path returned.
search pathchanging at runtime
The search path may be altered by a run-time setting. The
command to use is
SET SEARCH_PATH 'schema'[,'schema']...
versionversion() returns a string describing the
PostgreSQL server's version.
shows the functions
available to query and alter run-time configuration parameters.
Configuration Settings Information FunctionsNameReturn TypeDescriptioncurrent_setting(setting_name)
textvalue of current settingset_config(setting_name,
new_value,
is_local)textnew value of current setting
settingcurrentsettingset
The current_setting is used to obtain the current
value of the setting_name setting, as a query
result. It is the equivalent to the SQL SHOW command.
For example:
select current_setting('DateStyle');
current_setting
---------------------------------------
ISO with US (NonEuropean) conventions
(1 row)
set_config allows the setting_name
setting to be changed to new_value.
If is_local is set to true,
the new value will only apply to the current transaction. If you want
the new value to apply for the current session, use
false instead. It is the equivalent to the SQL
SET command. For example:
select set_config('show_statement_stats','off','f');
set_config
------------
off
(1 row)
lists functions that
allow the user to query object access privileges programmatically.
See for more information about
privileges.
Access Privilege Inquiry FunctionsNameReturn TypeDescriptionhas_table_privilege(user,
table,
access)
booleandoes user have access to tablehas_table_privilege(table,
access)
booleandoes current user have access to tablehas_database_privilege(user,
database,
access)
booleandoes user have access to databasehas_database_privilege(database,
access)
booleandoes current user have access to databasehas_function_privilege(user,
function,
access)
booleandoes user have access to functionhas_function_privilege(function,
access)
booleandoes current user have access to functionhas_language_privilege(user,
language,
access)
booleandoes user have access to languagehas_language_privilege(language,
access)
booleandoes current user have access to languagehas_schema_privilege(user,
schema,
access)
booleandoes user have access to schemahas_schema_privilege(schema,
access)
booleandoes current user have access to schema
has_table_privilegehas_database_privilegehas_function_privilegehas_language_privilegehas_schema_privilegehas_table_privilege checks whether a user
can access a table in a particular way. The user can be
specified by name or by ID
(pg_user.usesysid), or if the argument is
omitted
current_user is assumed. The table can be specified
by name or by OID. (Thus, there are actually six variants of
has_table_privilege, which can be distinguished by
the number and types of their arguments.) When specifying by name,
the name can be schema-qualified if necessary.
The desired access type
is specified by a text string, which must evaluate to one of the
values SELECT, INSERT, UPDATE,
DELETE, RULE, REFERENCES, or
TRIGGER. (Case of the string is not significant, however.)
An example is:
SELECT has_table_privilege('myschema.mytable', 'select');
has_database_privilege checks whether a user
can access a database in a particular way. The possibilities for its
arguments are analogous to has_table_privilege.
The desired access type must evaluate to
CREATE,
TEMPORARY, or
TEMP (which is equivalent to
TEMPORARY).
has_function_privilege checks whether a user
can access a function in a particular way. The possibilities for its
arguments are analogous to has_table_privilege.
When specifying a function by a text string rather than by OID,
the allowed input is the same as for the regprocedure> data type.
The desired access type must currently evaluate to
EXECUTE.
has_language_privilege checks whether a user
can access a procedural language in a particular way. The possibilities
for its arguments are analogous to has_table_privilege.
The desired access type must currently evaluate to
USAGE.
has_schema_privilege checks whether a user
can access a schema in a particular way. The possibilities for its
arguments are analogous to has_table_privilege.
The desired access type must evaluate to
CREATE or
USAGE.
shows functions that
determine whether a certain object is visible> in the
current schema search path. A table is said to be visible if its
containing schema is in the search path and no table of the same
name appears earlier in the search path. This is equivalent to the
statement that the table can be referenced by name without explicit
schema qualification. For example, to list the names of all
visible tables:
SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
Schema Visibility Inquiry FunctionsNameReturn TypeDescriptionpg_table_is_visible(tableOID)
booleanis table visible in search pathpg_type_is_visible(typeOID)
booleanis type visible in search pathpg_function_is_visible(functionOID)
booleanis function visible in search pathpg_operator_is_visible(operatorOID)
booleanis operator visible in search pathpg_opclass_is_visible(opclassOID)
booleanis operator class visible in search path
pg_table_is_visiblepg_type_is_visiblepg_function_is_visiblepg_operator_is_visiblepg_opclass_is_visiblepg_table_is_visible performs the check for
tables (or views, or any other kind of pg_class> entry).
pg_type_is_visible,
pg_function_is_visible,
pg_operator_is_visible, and
pg_opclass_is_visible perform the same sort of
visibility check for types, functions, operators, and operator
classes, respectively. For functions and operators, an object in
the search path is visible if there is no object of the same name
and argument data type(s)> earlier in the path. For
operator classes, both name and associated index access method are
considered.
All these functions require object OIDs to identify the object to be
checked. If you want to test an object by name, it is convenient to use
the OID alias types (regclass>, regtype>,
regprocedure>, or regoperator>), for example
SELECT pg_type_is_visible('myschema.widget'::regtype);
Note that it would not make much sense to test an unqualified name in
this way --- if the name can be recognized at all, it must be visible.
pg_get_viewdefpg_get_ruledefpg_get_indexdefpg_get_constraintdefpg_get_userbyid lists functions that
extract information from the system catalogs.
pg_get_viewdef(),
pg_get_ruledef(),
pg_get_indexdef(), and
pg_get_constraintdef() respectively
reconstruct the creating command for a view, rule, index, or
constraint. (Note that this is a decompiled reconstruction, not
the verbatim text of the command.) At present
pg_get_constraintdef() only works for
foreign-key constraints. pg_get_userbyid()
extracts a user's name given a usesysid
value.
Catalog Information FunctionsNameReturn TypeDescriptionpg_get_viewdef(viewname)textGet CREATE VIEW> command for view (deprecated)pg_get_viewdef(viewOID)textGet CREATE VIEW> command for viewpg_get_ruledef(ruleOID)textGet CREATE RULE> command for rulepg_get_indexdef(indexOID)textGet CREATE INDEX> command for indexpg_get_constraintdef(constraintOID)textGet definition of a constraintpg_get_userbyid(userid)nameGet user name with given ID
obj_descriptioncol_description
The function shown in extract comments
previously stored with the COMMENT command. A
null value is returned if no comment can be found matching the
specified parameters.
Comment Information FunctionsNameReturn TypeDescriptionobj_description(objectOID, tablename)textGet comment for a database objectobj_description(objectOID)textGet comment for a database object (deprecated)col_description(tableOID, columnnumber)textGet comment for a table column
The two-parameter form of obj_description() returns the
comment for a database object specified by its OID and the name of the
containing system catalog. For example,
obj_description(123456,'pg_class')
would retrieve the comment for a table with OID 123456.
The one-parameter form of obj_description() requires only
the object OID. It is now deprecated since there is no guarantee that
OIDs are unique across different system catalogs; therefore, the wrong
comment could be returned.
col_description() returns the comment for a table column,
which is specified by the OID of its table and its column number.
obj_description() cannot be used for table columns since
columns do not have OIDs of their own.
Aggregate FunctionsAggregate functions compute a single result
value from a set of input values. show the built-in aggregate
functions. The special syntax considerations for aggregate
functions are explained in .
Consult the &cite-tutorial; for additional introductory
information.
Aggregate FunctionsFunctionArgument TypeReturn TypeDescriptionaveragefunctionavg(expression)smallint, integer,
bigint, real, double
precision, numeric, or interval.
numeric for any integer type argument,
double precision for a floating-point argument,
otherwise the same as the argument data type
the average (arithmetic mean) of all input valuescount(*)bigintnumber of input valuescount(expression)anybigint
number of input values for which the value of expression is not null
max(expression)any numeric, string, or date/time typesame as argument type
maximum value of expression across all input
values
min(expression)any numeric, string, or date/time typesame as argument type
minimum value of expression across all input
values
standard deviationstddev(expression)smallint, integer,
bigint, real, double
precision, or numeric.
double precision for floating-point arguments,
otherwise numeric.
sample standard deviation of the input valuessum(expression)smallint, integer,
bigint, real, double
precision, numeric, or
intervalbigint for smallint or
integer arguments, numeric for
bigint arguments, double precision
for floating-point arguments, otherwise the same as the
argument data type
sum of expression across all input valuesvariancevariance(expression)
smallint, integer,
bigint, real, double
precision, or numeric.
double precision for floating-point arguments,
otherwise numeric.
sample variance of the input values (square of the sample standard deviation)
It should be noted that except for count,
these functions return a null value when no rows are selected. In
particular, sum of no rows returns null, not
zero as one might expect. The function coalesce may be
used to substitute zero for null when necessary.
Subquery Expressionsexistsinnot inanyallsomesubqueries
This section describes the SQL-compliant subquery
expressions available in PostgreSQL.
All of the expression forms documented in this section return
Boolean (true/false) results.
EXISTS
EXISTS ( subquery )
The argument of EXISTS is an arbitrary SELECT> statement,
or subquery. The
subquery is evaluated to determine whether it returns any rows.
If it returns at least one row, the result of EXISTS is
true>; if the subquery returns no rows, the result of EXISTS
is false>.
The subquery can refer to variables from the surrounding query,
which will act as constants during any one evaluation of the subquery.
The subquery will generally only be executed far enough to determine
whether at least one row is returned, not all the way to completion.
It is unwise to write a subquery that has any side effects (such as
calling sequence functions); whether the side effects occur or not
may be difficult to predict.
Since the result depends only on whether any rows are returned,
and not on the contents of those rows, the output list of the
subquery is normally uninteresting. A common coding convention is
to write all EXISTS> tests in the form
EXISTS(SELECT 1 WHERE ...). There are exceptions to
this rule however, such as subqueries that use INTERSECT.
This simple example is like an inner join on col2>, but
it produces at most one output row for each tab1> row,
even if there are multiple matching tab2> rows:
SELECT col1 FROM tab1
WHERE EXISTS(SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
IN (scalar form)expression IN (value, ...)
The right-hand side of this form of IN is a parenthesized list
of scalar expressions. The result is true> if the left-hand expression's
result is equal to any of the right-hand expressions. This is a shorthand
notation for
expression = value1
OR
expression = value2
OR
...
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand expression yields
null, the result of the IN construct will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
This form of IN is not truly a subquery expression, but it
seems best to document it in the same place as subquery IN.
IN (subquery form)expression IN (subquery)
The right-hand side of this form of IN is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result.
The result of IN is true> if any equal subquery row is found.
The result is false> if no equal row is found (including the special
case where the subquery returns no rows).
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand row yields
null, the result of the IN construct will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
As with EXISTS, it's unwise to assume that the subquery will
be evaluated completely.
(expression, expression ...) IN (subquery)
The right-hand side of this form of IN is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand list. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result.
The result of IN is true> if any equal subquery row is found.
The result is false> if no equal row is found (including the special
case where the subquery returns no rows).
As usual, null values in the expressions or subquery rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If all the row results are either unequal or null, with at least one null,
then the result of IN is null.
NOT IN (scalar form)expression NOT IN (value, ...)
The right-hand side of this form of NOT IN is a parenthesized list
of scalar expressions. The result is true if the left-hand expression's
result is unequal to all of the right-hand expressions. This is a shorthand
notation for
expression <> value1
AND
expression <> value2
AND
...
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand expression yields
null, the result of the NOT IN construct will be null, not true
as one might naively expect.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
x NOT IN y is equivalent to NOT (x IN y) in all
cases. However, null values are much more likely to trip up the novice when
working with NOT IN than when working with IN.
It's best to express your condition positively if possible.
NOT IN (subquery form)expression NOT IN (subquery)
The right-hand side of this form of NOT IN is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result.
The result of NOT IN is true> if only unequal subquery rows
are found (including the special case where the subquery returns no rows).
The result is false> if any equal row is found.
Note that if the left-hand expression yields null, or if there are
no equal right-hand values and at least one right-hand row yields
null, the result of the NOT IN construct will be null, not true.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
As with EXISTS, it's unwise to assume that the subquery will
be evaluated completely.
(expression, expression ...) NOT IN (subquery)
The right-hand side of this form of NOT IN is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand list. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result.
The result of NOT IN is true> if only unequal subquery rows
are found (including the special case where the subquery returns no rows).
The result is false> if any equal row is found.
As usual, null values in the expressions or subquery rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If all the row results are either unequal or null, with at least one null,
then the result of NOT IN is null.
ANY/SOMEexpressionoperator ANY (subquery)
expressionoperator SOME (subquery)
The right-hand side of this form of ANY is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result using the
given operator, which must yield a Boolean
result.
The result of ANY is true> if any true result is obtained.
The result is false> if no true result is found (including the special
case where the subquery returns no rows).
SOME is a synonym for ANY.
IN is equivalent to = ANY.
Note that if there are no successes and at least one right-hand row yields
null for the operator's result, the result of the ANY construct
will be null, not false.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
As with EXISTS, it's unwise to assume that the subquery will
be evaluated completely.
(expression, expression ...) operator> ANY (subquery)
(expression, expression ...) operator> SOME (subquery)
The right-hand side of this form of ANY is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand list. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result,
using the given operator. Presently,
only = and <> operators are allowed
in row-wise ANY queries.
The result of ANY is true> if any equal or unequal row is
found, respectively.
The result is false> if no such row is found (including the special
case where the subquery returns no rows).
As usual, null values in the expressions or subquery rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If there is at least one null row result, then the result of ANY
cannot be false; it will be true or null.
ALLexpressionoperator ALL (subquery)
The right-hand side of this form of ALL is a parenthesized
subquery, which must return exactly one column. The left-hand expression
is evaluated and compared to each row of the subquery result using the
given operator, which must yield a Boolean
result.
The result of ALL is true> if all rows yield true
(including the special case where the subquery returns no rows).
The result is false> if any false result is found.
NOT IN is equivalent to <> ALL.
Note that if there are no failures but at least one right-hand row yields
null for the operator's result, the result of the ALL construct
will be null, not true.
This is in accordance with SQL's normal rules for Boolean combinations
of null values.
As with EXISTS, it's unwise to assume that the subquery will
be evaluated completely.
(expression, expression ...) operator ALL (subquery)
The right-hand side of this form of ALL is a parenthesized
subquery, which must return exactly as many columns as there are
expressions in the left-hand list. The left-hand expressions are
evaluated and compared row-wise to each row of the subquery result,
using the given operator. Presently,
only = and <> operators are allowed
in row-wise ALL queries.
The result of ALL is true> if all subquery rows are equal
or unequal, respectively (including the special
case where the subquery returns no rows).
The result is false> if any row is found to be unequal or equal,
respectively.
As usual, null values in the expressions or subquery rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of that row comparison is unknown (null).
If there is at least one null row result, then the result of ALL
cannot be true; it will be false or null.
Row-wise Comparison
(expression, expression ...) operator (subquery)
(expression, expression ...) operator (expression, expression ...)
The left-hand side is a list of scalar expressions. The right-hand side
can be either a list of scalar expressions of the same length, or a
parenthesized subquery, which must return exactly as many columns as there
are expressions on the left-hand side. Furthermore, the subquery cannot
return more than one row. (If it returns zero rows, the result is taken to
be null.) The left-hand side is evaluated and compared row-wise to the
single subquery result row, or to the right-hand expression list.
Presently, only = and <> operators are allowed
in row-wise comparisons.
The result is true> if the two rows are equal or unequal, respectively.
As usual, null values in the expressions or subquery rows are combined per
the normal rules of SQL Boolean expressions. Two rows are considered
equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal;
otherwise the result of the row comparison is unknown (null).