Functions and OperatorsfunctionsoperatorsPostgres 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
Programmer's Guide. 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
RDBMS products, and in many cases this
functionality is compatible and consistant between various products.
Logical OperatorsoperatorslogicalBooleanoperatorsoperators, logical
The usual logical operators are available:
andoperatororoperatornotoperatorANDORNOT
SQL uses a three-valued Boolean logic where NULL represents
unknown. Observe the following truth tables:
aba AND ba OR bTRUETRUETRUETRUETRUEFALSEFALSETRUETRUENULLNULLTRUEFALSEFALSEFALSEFALSEFALSENULLFALSENULLNULLNULLNULLNULLaNOT aTRUEFALSEFALSETRUENULLNULLComparison Operatorscomparisonoperators
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
Do not use
expression = NULL
because NULL is not equal to NULL. (NULL 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 would 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 NULL, 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.
Bit string arguments to &, |,
and # must be of equal length. When bit
shifting, the original length of the string is preserved, as shown
here.
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, sinteger)numerictruncate to s decimal placestrunc(42.4382, 2)42.43
In the table above, 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 and behavior in boundary cases could
therefore vary depending on the operating system.
Trigonometric FunctionsFunctionDescriptionacos(x)inverse cosineasin(x)inverse sineatan(x)inverse tangentatan2(x, y)inverse tangent of y/xcos(x)cosinecot(x)cotangentsin(x)sinetan(x)tangent
All trigonometric functions have arguments and return values of
type double precision.
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 keywords 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'Postgre' || 'SQL'>PostgreSQL>bit_length(string)integernumber of bits in stringbit_length('jose')32char_length(string) or character_length(string)integer
length of string
character stringslengthlengthcharacter stringscharacter strings, lengthchar_length('jose')>4>lower(string)textConvert string to lower case.lower('TOM')tomoctet_length(string)integernumber of bytes in stringoctet_length('jose')4position(substring in string)integerlocation of specified substringposition('om' in 'Thomas')3substring(stringfrom integerfor integer)text
extract substring
substringsubstring('Thomas' from 2 for 3)homtrim(leading | trailing | bothcharacters from
string)
text
Removes the longest string containing only the
characters (a space by default) from the
beginning/end/both ends of the string.
trim(both 'x' from 'xTomx')Tomupper(string)textConvert string to upper case.upper('tom')TOM
Additional string manipulation functions are available and are
listed below. Some of them are used internally to implement the
SQL string functions listed above.
Other String FunctionsFunctionReturn TypeDescriptionExampleResultascii(text)integerReturns the ASCII 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
string.
btrim('xyxtrimyyx','xy')trimchr(integer)textReturns the character with the given ASCII code.chr(65)Aconvert(stringtext,
src_encodingname,dest_encodingname)
text
Converts string using 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-1initcap(text)textConverts first letter of each word (whitespace separated) to upper case.initcap('hi thomas')Hi Thomaslpad(stringtext,
lengthinteger, filltext)
text
Fills 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, trimtext)text
Removes the longest string containing only characters from
trim from the start of the string.
ltrim('zzzytrim','xyz')trimpg_client_encoding()name
Returns current client encoding name.
pg_client_encoding()SQL_ASCIIrepeat(text, integer)textRepeat text a number of times.repeat('Pg', 4)PgPgPgPgrpad(stringtext,
lengthinteger, filltext)
text
Fills 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
Removes the longest string containing only characters from
trim from the end of the string.
rtrim('trimxxxx','x')trimstrpos(string, substring)text
Locates specified substring. (same as
position(substring in
string), but note the reversed
argument order)
strpos('high','ig')2substr(string, from, count)text
Extracts specified substring. (same as substring(string from from for count))
substr('alphabet', 3, 2)phto_ascii(text, encoding)textConverts text from multibyte encoding to ASCII.to_ascii('Karel')Kareltranslate(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')a23x5encode(databytea,
typetext)
text
Encodes binary data to ASCII-only representation. Supported
types are: 'base64', 'hex'.
encode('123\\000\\001', 'base64')MTIzAAE=decode(stringtext,
typetext)
bytea
Decodes binary data from string previously
encoded with encode(). Parameter type is same as in encode().
decode('MTIzAAE=', 'base64')123\000\001
The to_ascii function supports conversion from
LATIN1, LATIN2, WIN1250 (CP1250) only.
Pattern Matching
There are two separate approaches to pattern matching provided by
Postgres: the SQL
LIKE operator and
POSIX-style regular expressions.
If you have pattern matching needs that go beyond this, or want to
make pattern-driven substitutions or translations, consider
writing a user-defined function in Perl or Tcl.
Pattern Matching with LIKElikestring LIKE pattern ESCAPE escape-characterstring NOT LIKE pattern ESCAPE 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. You can avoid this by
selecting a different escape character with ESCAPE.
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
Postgres 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 are also
Postgres-specific.
POSIX Regular Expressionsregular expressionspattern matching
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 function.
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.
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).
Postgres 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 FunctionsformattingAuthor
Written by Karel Zak (zakkr@zf.jcu.cz) on 2000-01-24
The Postgres 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.
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 int4/int8 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.
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 caseTZtimezone name - upper casetztimezone 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.
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 below)FX Month DD DaySP suffixspell mode (not yet implemented)DDSP
Usage notes:
FM suppresses leading zeroes or 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 Postgres.
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 year data, but the single Y
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 are in conversion from string to time stamp used as part of
second after decimal point. For example
to_timestamp('12:3', 'SS:MS') is not 3 milliseconds,
but 300, because the conversion count it as 12 + 0.3.
It means for format 'SS:MS' is '12:3' or '12:30' or '12:300' same
number of milliseconds. For the three milliseconds must be used
'12:003' that the conversion count 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, 2.021230 seconds.
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 numbers (not supported yet)
Usage notes:
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 use blank space.
TH does not convert values less than zero
and does not convert decimal numbers.
PL, SG, and
TH are Postgres
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.)
Date/Time Functions and Operators shows the available
functions for date/time value processing.
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 ).
The date/time operators described below behave similarly for types
involving time zones as well as those without.
The date/time functions are summarized below, with additional
details in subsequent sections.
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 below
current_timetimeTime of day; see below
current_timestamptimestampdate and time; see also below
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 below
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 below
extract(hour from timestamp '2001-02-16 20:38:40')20extract(field from interval)double precisionGet subfield; see also below
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')truenow()timestampCurrent date and time (equivalent to
current_timestamp); see also below
timeofday()textHigh-precision date and time; see also below
timeofday()Wed Feb 21 17:01:13.000126 2001 ESTtimestamp(date)timestampdate to timestamptimestamp(date '2000-12-25')2000-12-25 00:00:00timestamp(date, time)timestampdate and time to timestamptimestamp(date '1998-02-24',time '23:07')1998-02-24 23:07:00
EXTRACT, date_part
EXTRACT (field FROM source)
The extract function retrieves sub-fields
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 (Result may 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-function extract:
date_part('field', source)
Note that here the field value needs to
be a string. 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
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+00Current Date/Timedatecurrenttimecurrent
The following functions are available to obtain the current date and/or
time:
CURRENT_TIME
CURRENT_DATE
CURRENT_TIMESTAMP
Note that because of the requirements of the
SQL standard, these functions must not be
called with trailing parentheses.
SELECT CURRENT_TIME;
19:07:32
SELECT CURRENT_DATE;
2001-02-17
SELECT CURRENT_TIMESTAMP;
2001-02-17 19:07:32-05
The function now() is the traditional
Postgres equivalent to
CURRENT_TIMESTAMP.
There is also timeofday(), which returns current
time to higher precision than the CURRENT_TIMESTAMP
family does:
SELECT timeofday();
Sat Feb 17 19:07:32.000126 2001 EST
timeofday() uses the operating system call
gettimeofday(2), which may have resolution as
good as microseconds (depending on your platform); the other functions
rely on time(2) which is restricted to one-second
resolution. For historical reasons, timeofday()
returns its result as a text string rather than a timestamp value.
It is quite important to realize that
CURRENT_TIMESTAMP and related functions all return
the time as of the start of the current transaction; their values do not
increment while a transaction is running. But
timeofday() returns the actual current time.
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
value 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.
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 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))')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))')
]]>
npoint(path)integernumber of pointsnpoints(path '[(0,0),(1,1),(2,0)]')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)polygon12 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))')
Network Address Type Functions
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'
All of the operators for inet can be applied to
cidr values as well. 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> 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
All of the functions for inet can be applied to
cidr values as well. 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.
macaddr> FunctionsFunctionReturnsDescriptionExampleResulttrunc(macaddr)macaddrset last 3 bytes to zerotrunc(macaddr '12:34:56:78:90:ab')12:34:56:00:00:00
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.
The macaddr> type also supports the standard relational
operators (>>, <=>, etc.) for
lexicographical ordering.
Conditional Expressionscaseconditionals
This section describes the SQL-compliant conditional expressions
available in Postgres.
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 NULL) 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 NULL 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>
Session Information Functions>
Name> Return Type> Description>current_user>
name>
user name of current execution context>
session_user>
name>
session user name>
user>
name>
equivalent to current_user>>
usercurrent
The session_user> is the user that initiated a database
connection and is fixed for the duration of that connection. The
current_user> is the user identifier that is applicable
for permission checking. Currently it is always equal to the session
user, but in the future there might be setuid> functions and
other facilities to allow the current user to change temporarily.
In Unix parlance, the session user is the real user>
and the current user is the effective user>.
Note that these functions have special syntactic status in SQL>;
they must be called without trailing parentheses.
Deprecated>
The function getpgusername()> is an obsolete equivalent
of current_user>.
Access Privilege Inquiry Functions>
Name> Return Type> Description>has_table_privilege(user,
table,
access)
boolean>
does user have access to table>
has_table_privilege(table,
access)
boolean>
does current user have access to table>
has_table_privilegehas_table_privilege> determines 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.) 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.)
Aggregate FunctionsAuthor
Written by Isaac Wilcox isaac@azartmedia.com on 2000-06-16
Aggregate functions compute a single result
value from a set of input values. The special syntax
considerations for aggregate functions are explained in . Consult the PostgreSQL
Tutorial for additional introductory information.
Aggregate FunctionsFunctionDescriptionNotesAVG(expression)the average (arithmetic mean) of all input valuesaveragefunction
Finding the average value is available on the following data
types: smallint, integer,
bigint, real, double
precision, numeric, interval.
The result is of type numeric for any integer type
input, double precision for floating point input,
otherwise the same as the input data type.
count(*)number of input valuesThe return value is of type bigint.count(expression)
Counts the input values for which the value of expression is not NULL.
The return value is of type bigint.max(expression)the maximum value of expression across all input values
Available for all numeric, string, and date/time types. The
result has the same type as the input expression.
min(expression)the minimum value of expression across all input values
Available for all numeric, string, and date/time types. The
result has the same type as the input expression.
stddev(expression)the sample standard deviation of the input valuesstandard deviation
Finding the standard deviation is available on the following
data types: smallint, integer,
bigint, real, double
precision, numeric. The result is of type
double precision for floating point input,
otherwise numeric.
sum(expression)sum of expression across all input values
Summation is available on the following data types:
smallint, integer,
bigint, real, double
precision, numeric, interval.
The result is of type bigint for smallint
or integer input, numeric for
bigint
input, double precision for floating point input,
otherwise the same as the input data type.
variance(expression)the sample variance of the input valuesvariance
The variance is the square of the standard deviation. The
supported data types and result types are the same as for
standard deviation.
It should be noted that except for COUNT,
these functions return NULL when no rows are selected. In
particular, SUM of no rows returns NULL, not
zero as one might expect. COALESCE may be
used to substitute zero for NULL when necessary.