Postgres 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 function 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. However, many other RDBMS packages provide a lot of the same or similar functions, and some of the ones provided in Postgres have in fact been inspired by other implementations. Operator Description < 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 boolean values; expressions like 1 < 2 < 3 are not valid (because there is no < operator to compare a boolean with 3). Name Description Example Result + Addition 2 + 3 5 - Subtraction 2 - 3 -1 * Multiplication 2 * 3 6 / Division (integer division truncates results) 4 / 2 2 % Modulo (remainder) 5 % 4 1 ^ Exponentiation 2.0 ^ 3.0 8.0 |/ Square root |/ 25.0 5.0 ||/ Cube root ||/ 27.0 3 ! Factorial 5 ! 120 !! Factorial (left operator) !! 5 120 @ Absolute value @ -5.0 5.0 Function Return Type Description Example Result abs(x) (same as argument type) absolute value abs(-17.4) 17.4 cbrt(double precision) double precision cube root cbrt(27.0) 9.0 ceil(numeric) numeric smallest integer not less than argument ceil(-42.8) -42 degrees(double precision) double precision convert radians to degrees degrees(0.5) 28.6478897565412 exp(double precision) double precision exponential function exp(1.0) 2.71828182845905 floor(numeric) numeric largest integer not greater than argument floor(-42.8) 43 ln(double precision) double precision natural logarithm ln(2.0) 0.693147180559945 log(double precision) double precision base 10 logarithm log(100.0) 2.0 log(base numeric, x numeric) numeric logarithm to specified base log(2.0, 64.0) 6.0 mod(y, x) (same as argument types) remainder (modulo) of the division y/x mod(9,4) 1 pi() double precision Pi constant pi() 3.14159265358979 pow(double precision, double precision) double precision raise a number to the specified exponent pow(9.0, 3.0) 729.0 radians(double precision) double precision convert degrees to radians radians(45.0) 0.785398163397448 random() double precision a pseudo-random value between 0.0 to 1.0 random() round(double precision) double precision round to nearest integer round(42.4) 42 round(value numeric, scale integer) numeric round to specified number of decimal places round(42.4382, 2) 42.44 sqrt(double precision) double precision square root sqrt(2.0) 1.4142135623731 trunc(double precision) double precision truncate (toward zero) trunc(42.8) 42 trunc(value numeric, scale integer) numeric truncate to specified number of decimal places round(42.4382, 2) 42.43 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. 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. Function Description acos(x) inverse cosine asin(x) inverse sine atan(x) inverse tangent atan2(x, y) inverse tangent of y/x cos(x) cosine cot(x) cotangent sin(x) sine tan(x) tangent All trigonometric functions have arguments and return values of type double precision. 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. 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 .) Function Return Type Description Example Result string || string text string concatenation 'Postgre' || 'SQL' PostgreSQL char_length(string) or character_length(string) integer length of string char_length('jose') 4 lower(string) text Convert string to lower case. lower('TOM') tom octet_length(string) integer number of bytes in string octet_length('jose') 4 position(substring in string) integer location of specified substring position('om' in 'Thomas') 3 substring(string from integer for integer) text extract substring substring('Thomas' from 2 for 3) oma trim(leading | trailing | both characters 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') Tom upper(string) text Convert 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. Function Return type Description Example Result ascii(text) integer Returns the ASCII code of the first character of the argument. ascii('x') 120 btrim(string text, trim text) text Remove (trim) the longest string consisting only of characters in trim from the start and end of string. btrim('xyxtrimyyx','xy') trim chr(integer) text Returns the character with the given ASCII code. chr(65) A initcap(text) text Converts first letter of each word (whitespace separated) to upper case. initcap('hello thomas') Hello Thomas lpad(string text, length integer , fill text) 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') xyxhi ltrim(string text, trim text) text Removes the longest string containing only characters from trim from the start of the string. ltrim('zzzytrim','xyz') trim repeat(text, integer) text Repeat text a number of times. repeat('Pg', 4) PgPgPgPg rpad(string text, length integer , fill text) 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') hixyx rtrim(string text, trim text) text Removes the longest string containing only characters from trim from the end of the string. rtrim('trimxxxx','x') trim strpos(string, substring) text Locates specified substring. (same as position(substring in string), but note the reversed argument order) strpos('high','ig') substr(string, from , count) text Extracts specified substring. (same as substring(string from from for count)) substr('alphabet', 3, 2) ph to_ascii(text , encoding) text Converts text from multibyte encoding to ASCII. to_ascii('Karel') translate(string text, from text, to text) 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 The to_ascii function supports conversion from LATIN1, LATIN2, WIN1250 (CP1250) only. 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. string LIKE pattern ESCAPE escape-character string 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 zero or more characters. Some examples: 'abc' LIKE 'abc' true 'abc' LIKE 'a%' true 'abc' LIKE '_b_' true 'abc' LIKE 'c' false LIKE pattern matches always cover the entire string. On order to match a pattern anywhere within a string, the pattern must therefore start and end with a percent sign. In order to match a literal underscore or percent sign, the respective character in pattern must be preceded by the active escape character. The default escape character is the backslash but a different one may be selected by using the ESCAPE clause. When using the backslash as escape character in literal strings it must be doubled, because the backslash already has a special meaning in string literals. The keyword ILIKE can be used instead of LIKE to make the match case insensitive according to the active locale. This is a Postgres extension. The operator ~~ is equivalent to LIKE, ~~* corresponds to ILIKE. Finally, there are also !~~ and !~~* operators to represent NOT LIKE and NOT ILIKE. All of these are also Postgres-specific. 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. Unlike the LIKE operator, a regular expression also matches anywhere within a string, unless the regular expression is explicitly anchored to the beginning or end of the string. Operator Description Example ~ 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.*' 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). Obsolete REs are not available in Postgres. 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 a line), $ (matching the null string at the end of a line), 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 \. 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 multi-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 multi-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. 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 datetypes. 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 format. Function Returns Description Example to_char(timestamp, text) text convert timestamp to string to_char(timestamp 'now','HH12:MI:SS') to_char(int, text) text convert int4/int8 to string to_char(125, '999') to_char(float, text) text convert float4/float8 to string to_char(125.8, '999D9') to_char(numeric, text) text convert numeric to string to_char(numeric '-125.8', '999D99S') to_date(text, text) date convert string to date to_date('05 Dec 2000', 'DD Mon YYYY') to_timestamp(text, text) date convert string to timestamp to_timestamp('05 Dec 2000', 'DD Mon YYYY') to_number(text, text) numeric convert string to numeric to_number('12,454.8-', '99G999D9S') Template Description HH hour of day (01-12) HH12 hour of day (01-12) HH24 hour of day (00-23) MI minute (00-59) SS second (00-59) SSSS seconds 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,YYY year (4 and more digits) with comma YYYY year (4 and more digits) YYY last 3 digits of year YY last 2 digits of year Y last digit of year BC or B.C. or AD or A.D. year indicator (upper case) bc or b.c. or ad or a.d. year indicator (lower case) MONTH full upper case month name (9 chars) Month full mixed case month name (9 chars) month full lower case month name (9 chars) MON upper case abbreviated month name (3 chars) Mon abbreviated mixed case month name (3 chars) mon abbreviated lower case month name (3 chars) MM month (01-12) DAY full upper case day name (9 chars) Day full mixed case day name (9 chars) day full lower case day name (9 chars) DY abbreviated upper case day name (3 chars) Dy abbreviated mixed case day name (3 chars) dy abbreviated lower case day name (3 chars) DDD day of year (001-366) DD day of month (01-31) D day of week (1-7; SUN=1) W week of month (1-5) where first week start on the first day of the month WW week number of year (1-53) where first week start on the first day of the year IW ISO week number of year (The first Thursday of the new year is in week 1.) CC century (2 digits) J Julian Day (days since January 1, 4712 BC) Q quarter RM month in Roman Numerals (I-XII; I=January) - upper case rm month in Roman Numerals (I-XII; I=January) - lower case TZ timezone string - upper case tz timezone string - lower case All templates allow the use of prefix and suffix modifiers. Modifiers are always valid for use in templates. The prefix FX is a global modifier only. Suffix Description Example FM fill mode prefix FMMonth TH upper ordinal number suffix DDTH th lower ordinal number suffix DDTH FX FiXed format global option (see below) FX Month DD Day SP spell mode (not yet implemented) DDSP Usage notes: to_timestamp and to_date skip multiple blank space in converted 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 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 but any string between double quotes is guaranteed that it will not be interpreted as a template keyword and it is also processed faster. (Example: '"Hello Year: "YYYY'). A double quote (") between quotation marks is skipped and is not parsed. If you want to have a double quote in the output you must preceed it with a double 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'). Template Description 9 value with the specified number of digits 0 value with leading zeros . (period) decimal point , (comma) group (thousand) separator PR negative value in angle brackets S negative value with minus sign (uses locale) L currency symbol (uses locale) D decimal point (uses locale) G group separator (uses locale) MI minus sign in specified position (if number < 0) PL plus sign in specified position (if number > 0) SG plus/minus sign in specified position RN roman numeral (input between 1 and 3999) TH or th convert to ordinal number V shift n digits (see notes) EEEE scientific 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 preceed MI. PL, SG, and TH are Postgres extensions. 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. TH is a Postgres extension. 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.) Input Output to_char(now(),'Day, HH12:MI:SS') 'Tuesday , 05:39:18' to_char(now(),'FMDay, HH12:MI:SS') 'Tuesday, 05:39:18' to_char(-0.1,'99.99') ' -.10' to_char(-0.1,'FM9.99') '-.1' to_char(0.1,'0.9') ' 0.1' to_char(12,'9990999.9') ' 0012.0' to_char(12,'FM9990999.9') '0012' to_char(485,'999') ' 485' to_char(-485,'999') '-485' to_char(485,'9 9 9') ' 4 8 5' to_char(1485,'9,999') ' 1,485' to_char(1485,'9G999') ' 1 485' to_char(148.5,'999.999') ' 148.500' to_char(148.5,'999D999') ' 148,500' to_char(3148.5,'9G999D999') ' 3 148,500' to_char(-485,'999S') '485-' to_char(-485,'999MI') '485-' to_char(485,'999MI') '485' to_char(485,'PL999') '+485' to_char(485,'SG999') '+485' to_char(-485,'SG999') '-485' to_char(-485,'9SG99') '4-85' to_char(-485,'999PR') '<485>' to_char(485,'L999') 'DM 485 to_char(485,'RN') ' CDLXXXV' to_char(485,'FMRN') 'CDLXXXV' to_char(5.2,'FMRN') V to_char(482,'999th') ' 482nd' to_char(485, '"Good number:"999') 'Good number: 485' to_char(485.8,'"Pre-decimal:"999" Post-decimal:" .999') 'Pre-decimal: 485 Post-decimal: .800' to_char(12,'99V999') ' 12000' to_char(12.4,'99V999') ' 12400' to_char(12.45, '99V9') ' 125' The date/time functions provide a powerful set of tools for manipulating various date/time types. Function Returns Description Example abstime(timestamp) abstime convert to abstime abstime(timestamp 'now') age(timestamp) interval preserve months and years age(timestamp '1957-06-13') age(timestamp,timestamp) interval preserve months and years age('now', timestamp '1957-06-13') date_part(text,timestamp) float8 portion of date date_part('dow',timestamp 'now') date_part(text,interval) float8 portion of time date_part('hour',interval '4 hrs 3 mins') date_trunc(text,timestamp) timestamp truncate date date_trunc('month',abstime 'now') interval(reltime) interval convert to interval interval(reltime '4 hours') isfinite(timestamp) bool a finite time? isfinite(timestamp 'now') isfinite(interval) bool a finite time? isfinite(interval '4 hrs') reltime(interval) reltime convert to reltime reltime(interval '4 hrs') timestamp(date) timestamp convert to timestamp timestamp(date 'today') timestamp(date,time) timestamp convert to timestamp timestamp(timestamp '1998-02-24',time '23:07'); to_char(timestamp,text) text convert to string to_char(timestamp '1998-02-24','DD'); For the date_part and date_trunc functions, arguments can be `year', `month', `day', `hour', `minute', and `second', as well as the more specialized quantities `decade', `century', `millennium', `millisecond', and `microsecond'. date_part allows `dow' to return day of week, 'week' to return the ISO-defined week of year, and `epoch' to return seconds since 1970 (for timestamp) or 'epoch' to return total elapsed seconds (for interval). The geometric types point, box, lseg, line, path, polygon, and circle have a large set of native support functions and operators. Operator Description Usage + Translation '((0,0),(1,1))'::box + '(2.0,0)'::point - Translation '((0,0),(1,1))'::box - '(2.0,0)'::point * Scaling/rotation '((0,0),(1,1))'::box * '(2.0,0)'::point / Scaling/rotation '((0,0),(2,2))'::box / '(2.0,0)'::point # Intersection '((1,-1),(-1,1))' # '((1,1),(-1,-1))' # Number of points in polygon # '((1,0),(0,1),(-1,0))' ## Point of closest proximity '(0,0)'::point ## '((2,0),(0,2))'::lseg && Overlaps? '((0,0),(1,1))'::box && '((0,0),(2,2))'::box &< Overlaps to left? '((0,0),(1,1))'::box &< '((0,0),(2,2))'::box &> Overlaps to right? '((0,0),(3,3))'::box &> '((0,0),(2,2))'::box <-> Distance between '((0,0),1)'::circle <-> '((5,0),1)'::circle << Left of? '((0,0),1)'::circle << '((5,0),1)'::circle <^ Is below? '((0,0),1)'::circle <^ '((0,5),1)'::circle >> Is right of? '((5,0),1)'::circle >> '((0,0),1)'::circle >^ Is above? '((0,5),1)'::circle >^ '((0,0),1)'::circle ?# Intersects or overlaps '((-1,0),(1,0))'::lseg ?# '((-2,-2),(2,2))'::box; ?- Is horizontal? '(1,0)'::point ?- '(0,0)'::point ?-| Is perpendicular? '((0,0),(0,1))'::lseg ?-| '((0,0),(1,0))'::lseg @-@ Length or circumference @-@ '((0,0),(1,0))'::path ?| Is vertical? '(0,1)'::point ?| '(0,0)'::point ?|| Is parallel? '((-1,0),(1,0))'::lseg ?|| '((-1,2),(1,2))'::lseg @ Contained or on '(1,1)'::point @ '((0,0),2)'::circle @@ Center of @@ '((0,0),10)'::circle ~= Same as '((0,0),(1,1))'::polygon ~= '((1,1),(0,0))'::polygon Function Returns Description Example area(object) float8 area of item area(box '((0,0),(1,1))') box(box,box) box intersection box box(box '((0,0),(1,1))',box '((0.5,0.5),(2,2))') center(object) point center of item center(box '((0,0),(1,2))') diameter(circle) float8 diameter of circle diameter(circle '((0,0),2.0)') height(box) float8 vertical size of box height(box '((0,0),(1,1))') isclosed(path) bool a closed path? isclosed(path '((0,0),(1,1),(2,0))') isopen(path) bool an open path? isopen(path '[(0,0),(1,1),(2,0)]') length(object) float8 length of item length(path '((-1,0),(1,0))') pclose(path) path convert path to closed popen(path '[(0,0),(1,1),(2,0)]') npoint(path) int4 number of points npoints(path '[(0,0),(1,1),(2,0)]') popen(path) path convert path to open path popen(path '((0,0),(1,1),(2,0))') radius(circle) float8 radius of circle radius(circle '((0,0),2.0)') width(box) float8 horizontal size width(box '((0,0),(1,1))') Function Returns Description Example box(circle) box circle to box box('((0,0),2.0)'::circle) box(point,point) box points to box box('(0,0)'::point,'(1,1)'::point) box(polygon) box polygon to box box('((0,0),(1,1),(2,0))'::polygon) circle(box) circle to circle circle('((0,0),(1,1))'::box) circle(point,float8) circle point to circle circle('(0,0)'::point,2.0) lseg(box) lseg box diagonal to lseg lseg('((-1,0),(1,0))'::box) lseg(point,point) lseg points to lseg lseg('(-1,0)'::point,'(1,0)'::point) path(polygon) point polygon to path path('((0,0),(1,1),(2,0))'::polygon) point(circle) point center point('((0,0),2.0)'::circle) point(lseg,lseg) point intersection point('((-1,0),(1,0))'::lseg, '((-2,-2),(2,2))'::lseg) point(polygon) point center point('((0,0),(1,1),(2,0))'::polygon) polygon(box) polygon 12 point polygon polygon('((0,0),(1,1))'::box) polygon(circle) polygon 12-point polygon polygon('((0,0),2.0)'::circle) polygon(npts,circle) polygon npts polygon polygon(12,'((0,0),2.0)'::circle) polygon(path) polygon path to polygon polygon('((0,0),(1,1),(2,0))'::path) Operator Description Usage < Less than inet '192.168.1.5' < inet '192.168.1.6' <= Less than or equal inet '192.168.1.5' <= inet '192.168.1.5' = Equals inet '192.168.1.5' = inet '192.168.1.5' >= Greater or equal inet '192.168.1.5' >= inet '192.168.1.5' > Greater inet '192.168.1.5' > inet '192.168.1.4' <> Not equal inet '192.168.1.5' <> inet '192.168.1.4' << is contained within inet '192.168.1.5' << inet '192.168.1/24' <<= is contained within or equals inet '192.168.1/24' <<= inet '192.168.1/24' >> contains inet'192.168.1/24' >> inet '192.168.1.5' >>= contains or equals inet '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. Function Returns Description Example Result broadcast(inet) inet broadcast address for network broadcast('192.168.1.5/24') 192.168.1.255/24 host(inet) text extract IP address as text host('192.168.1.5/24') 192.168.1.5 masklen(inet) integer extract netmask length masklen('192.168.1.5/24') 24 netmask(inet) inet construct netmask for network netmask('192.168.1.5/24') 255.255.255.0 network(inet) cidr extract network part of address network('192.168.1.5/24') 192.168.1/24 text(inet) text extract IP address and masklen as text text(inet '192.168.1.5') 192.168.1.5/32 All of the functions for inet can be applied to cidr values as well. The host() and text() functions are primarily intended to offer alternative display formats. Function Returns Description Example Result trunc(macaddr) macaddr set last 3 bytes to zero trunc(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. This section descibes 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 result WHEN ... 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 whereever 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 WHEN condition 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 possible result expressions must match. CASE expression WHEN value THEN result WHEN ... ELSE result END This simple CASE 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 COALESCE COALESCE(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)') ... NULLIF NULLIF(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)') ... 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. Function Description Notes AVG(expression) the average (arithmetic mean) of all input values 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 values The return value is of type integer. COUNT(expression) Counts the input values for which the value of expression is not NULL. 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 values 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 numeric for any integer type input, double precision for floating point input, otherwise the same as the input data type. VARIANCE(expression) the sample variance of the input values The variance is the square of the standard deviation. The supported data types are the same. 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.