String Functions & Operators#

Strings in this context include char, varchar and text. char will be converted to text before the function or operator is applied, so trailing spaces are stripped.

SQL String Functions & Operators#

Function/Operator

Description

Example(s)

text || text → text

Concatenates the two strings.

‘Post’ || ‘greSQL’ → PostgreSQL

text || anynonarray → text
anynonarray || text → text

Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array || operators. If you want to concatenate an array’s text equivalent, cast it to text explicitly.)

‘Value: ‘ || 42 → Value: 42

text IS [NOT] [form] NORMALIZED → boolean

Checks whether the string is in the specified Unicode normalization form. The optional form key word specifies the form: NFC (the default), NFD, NFKC, or NFKD. This expression can only be used when the server encoding is UTF8. Note that checking for normalization using this expression is often faster than normalizing possibly already normalized strings.

U&’\0061\0308bc’ IS NFD NORMALIZED → t

bit_length ( text ) → integer

Returns number of bits in the string (8 times the octet_length).

bit_length(‘jose’) → 32

char_length ( text ) → integer
character_length ( text ) → integer

Returns number of characters in the string.

char_length(‘josé’) → 4

lower ( text ) → text

Converts the string to all lower case, according to the rules of the database’s locale.

lower(‘TOM’) → tom

normalize ( text [, form ] ) → text

Converts the string to the specified Unicode normalization form. The optional form key word specifies the form: NFC (the default), NFD, NFKC, or NFKD. This function can only be used when the server encoding is UTF8.

normalize(U&’\0061\0308bc’, NFC) → U&’\00E4bc’

octet_length ( text ) → integer

Returns number of bytes in the string.

octet_length(‘josé’) → 5 (if server encoding is UTF8)

octet_length ( character ) → integer

Returns number of bytes in the string. Since this version of the function accepts type character directly, it will not strip trailing spaces.

octet_length(‘abc ‘::character(4)) → 4

overlay ( string text PLACING newsubstring text FROM start integer [ FOR count integer ] ) → text

Replaces the substring of string that starts at the start’th character and extends for count characters with newsubstring. If count is omitted, it defaults to the length of newsubstring.

overlay(‘Txxxxas’ placing ‘hom’ from 2 for 4) → Thomas

position ( substring text IN string text ) → integer

Returns first starting index of the specified substring within string, or zero if it’s not present.

position(‘om’ in ‘Thomas’) → 3

substring ( string text [ FROM start integer ] [ FOR count integer ] ) → text

Extracts the substring of string starting at the start’th character if that is specified, and stopping after count characters if that is specified. Provide at least one of start and count.

substring(‘Thomas’ from 2 for 3) → hom
substring(‘Thomas’ from 3) → omas
substring(‘Thomas’ for 2) → Th

substring ( string text FROM pattern text ) → text

Extracts the first substring matching POSIX regular expression.

substring(‘Thomas’ from ‘…$’) → mas

substring ( string text SIMILAR pattern text ESCAPE escape text ) → text
substring ( string text FROM pattern text FOR escape text ) → text

Extracts the first substring matching SQL regular expression. The first form has been specified since SQL:2003; the second form was only in SQL:1999 and should be considered obsolete.

substring(‘Thomas’ similar ‘%#”o_a#”_’ escape ‘#’) → oma

trim ( [ LEADING | TRAILING | BOTH ] [ characters text ] FROM string text ) → text

Removes the longest string containing only characters in characters (a space by default) from the start, end, or both ends (BOTH is the default) of string.

trim(both ‘xyz’ from ‘yxTomxx’) → Tom

trim ( [ LEADING | TRAILING | BOTH ] [ FROM ] string text [, characters text ] ) → text

This is a non-standard syntax for trim().

trim(both from ‘yxTomxx’, ‘xyz’) → Tom

upper ( text ) → text

Converts the string to all upper case, according to the rules of the database’s locale.

upper(‘tom’) → TOM

Additional String Functions#

Function

Description

Example(s)

ascii ( text ) → integer

Returns the numeric code of the first character of the argument. In UTF8 encoding, returns the Unicode code point of the character. In other multibyte encodings, the argument must be an ASCII character.

ascii(‘x’) → 120

btrim ( string text [, characters text ] ) → text

Removes the longest string containing only characters in characters (a space by default) from the start and end of string.

btrim(‘xyxtrimyyx’, ‘xyz’) → trim

chr ( integer ) → text

Returns the character with the given code. In UTF8 encoding the argument is treated as a Unicode code point. In other multibyte encodings the argument must designate an ASCII character. chr(0) is disallowed because text data types cannot store that character.

chr(65) → A

concat ( val1 “any” [, val2 “any” [, …] ] ) → text

Concatenates the text representations of all the arguments. NULL arguments are ignored.

concat(‘abcde’, 2, NULL, 22) → abcde222

concat_ws ( sep text, val1 “any” [, val2 “any” [, …] ] ) → text

Concatenates all but the first argument, with separators. The first argument is used as the separator string, and should not be NULL. Other NULL arguments are ignored.

concat_ws(‘,’, ‘abcde’, 2, NULL, 22) → abcde,2,22

format ( formatstr text [, formatarg “any” [, …] ] ) → text

Formats arguments according to a format string. This function is similar to the C function sprintf.

format(‘Hello %s, %1$s’, ‘World’) → Hello World, World

initcap ( text ) → text

Converts the first letter of each word to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters.

initcap(‘hi THOMAS’) → Hi Thomas

left ( string text, n integer ) → text

Returns first n characters in the string, or when n is negative, returns all but last |n| characters.

left(‘abcde’, 2) → ab

length ( text ) → integer

Returns the number of characters in the string.

length(‘jose’) → 4

lpad ( string text, length integer [, fill text ] ) → text

Extends 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 [, characters text ] ) → text

Removes the longest string containing only characters in characters (a space by default) from the start of string.

ltrim(‘zzzytest’, ‘xyz’) → test

md5 ( text ) → text

Computes the MD5 hash of the argument, with the result written in hexadecimal.

md5(‘abc’) → 900150983cd24fb0​d6963f7d28e17f72

parse_ident ( qualified_identifier text [, strict_mode boolean DEFAULT true ] ) → text[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. By default, extra characters after the last identifier are considered an error; but if the second parameter is false, then such extra characters are ignored. (This behavior is useful for parsing names for objects like functions.) Note that this function does not truncate over-length identifiers. If you want truncation you can cast the result to name[].

parse_ident(‘“SomeSchema”.someTable’) → {SomeSchema,sometable}

pg_client_encoding ( ) → name

Returns current client encoding name.

pg_client_encoding() → UTF8

quote_ident ( text ) → text

Returns the given string suitably quoted to be used as an identifier in an SQL statement string. Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled.

quote_ident(‘Foo bar’) → “Foo bar”

quote_literal ( text ) → text

Returns the given string suitably quoted to be used as a string literal in an SQL statement string. Embedded single-quotes and backslashes are properly doubled. Note that quote_literal returns null on null input; if the argument might be null, quote_nullable is often more suitable.

quote_literal(E’O’Reilly’) → ‘O’’Reilly’

quote_literal ( anyelement ) → text

Converts the given value to text and then quotes it as a literal. Embedded single-quotes and backslashes are properly doubled.

quote_literal(42.5) → ‘42.5’

quote_nullable ( text ) → text

Returns the given string suitably quoted to be used as a string literal in an SQL statement string; or, if the argument is null, returns NULL. Embedded single-quotes and backslashes are properly doubled.

quote_nullable(NULL) → NULL

quote_nullable ( anyelement ) → text

Converts the given value to text and then quotes it as a literal; or, if the argument is null, returns NULL. Embedded single-quotes and backslashes are properly doubled.

quote_nullable(42.5) → ‘42.5’

regexp_match ( string text, pattern text [, flags text ] ) → text[]

Returns captured substrings resulting from the first match of a POSIX regular expression to the string.

regexp_match(‘foobarbequebaz’, ‘(bar)(beque)’) → {bar,beque}

regexp_matches ( string text, pattern text [, flags text ] ) → setof text[]

Returns captured substrings resulting from the first match of a POSIX regular expression to the string, or multiple matches if the g flag is used.

regexp_matches(‘foobarbequebaz’, ‘ba.’, ‘g’) →
{bar}
{baz}

regexp_replace ( string text, pattern text, replacement text [, flags text ] ) → text

Replaces substrings resulting from the first match of a POSIX regular expression, or multiple substring matches if the g flag is used.

regexp_replace(‘Thomas’, ‘.[mN]a.’, ‘M’) → ThM

regexp_split_to_array ( string text, pattern text [, flags text ] ) → text[]

Splits string using a POSIX regular expression as the delimiter, producing an array of results.

regexp_split_to_array(‘hello world’, ‘\s+’) → {hello,world}

regexp_split_to_table ( string text, pattern text [, flags text ] ) → setof text

Splits string using a POSIX regular expression as the delimiter, producing a set of results.

regexp_split_to_table(‘hello world’, ‘\s+’) →
hello
world

repeat ( string text, number integer ) → text

Repeats string the specified number of times.

repeat(‘Pg’, 4) → PgPgPgPg

replace ( string text, from text, to text ) → text

Replaces all occurrences in string of substring from with substring to.

replace(‘abcdefabcdef’, ‘cd’, ‘XX’) → abXXefabXXef

reverse ( text ) → text

Reverses the order of the characters in the string.

reverse(‘abcde’) → edcba

right ( string text, n integer ) → text

Returns last n characters in the string, or when n is negative, returns all but first |n| characters.

right(‘abcde’, 2) → de

rpad ( string text, length integer [, fill text ] ) → text

Extends 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 [, characters text ] ) → text

Removes the longest string containing only characters in characters (a space by default) from the end of string.

rtrim(‘testxxzx’, ‘xyz’) → test

split_part ( string text, delimiter text, n integer ) → text

Splits string at occurrences of delimiter and returns the n’th field (counting from one), or when n is negative, returns the |n|’th-from-last field.

split_part(‘abc~@~def~@~ghi’, ‘~@~’, 2) → def
split_part(‘abc,def,ghi,jkl’, ‘,’, -2) → ghi

strpos ( string text, substring text ) → integer

Returns first starting index of the specified substring within string, or zero if it’s not present. (Same as position(substring in string), but note the reversed argument order.)

strpos(‘high’, ‘ig’) → 2

substr ( string text, start integer [, count integer ] ) → text

Extracts the substring of string starting at the start’th character, and extending for count characters if that is specified. (Same as substring(string from start for count).)

substr(‘alphabet’, 3) → phabet substr(‘alphabet’, 3, 2) → ph

starts_with ( string text, prefix text ) → boolean

Returns true if string starts with prefix.

starts_with(‘alphabet’, ‘alph’) → t

string_to_array ( string text, delimiter text [, null_string text ] ) → text[]

Splits the string at occurrences of delimiter and forms the resulting fields into a text array. If delimiter is NULL, each character in the string will become a separate element in the array. If delimiter is an empty string, then the string is treated as a single field. If null_string is supplied and is not NULL, fields matching that string are replaced by NULL.

string_to_array(‘xx~~yy~~zz’, ‘~~’, ‘yy’) → {xx,NULL,zz}

string_to_table ( string text, delimiter text [, null_string text ] ) → setof text

Splits the string at occurrences of delimiter and returns the resulting fields as a set of text rows. If delimiter is NULL, each character in the string will become a separate row of the result. If delimiter is an empty string, then the string is treated as a single field. If null_string is supplied and is not NULL, fields matching that string are replaced by NULL.

string_to_table(‘xx~^~yy~^~zz’, ‘~^~’, ‘yy’) →
xx
NULL
zz

to_ascii ( string text ) → text
to_ascii ( string text, encoding name ) → text
to_ascii ( string text, encoding integer ) → text

Converts string to ASCII from another encoding, which may be identified by name or number. If encoding is omitted the database encoding is assumed (which in practice is the only useful case). The conversion consists primarily of dropping accents. Conversion is only supported from LATIN1, LATIN2, LATIN9, and WIN1250 encodings. (See the unaccent module for another, more flexible solution.)

to_ascii(‘Karél’) → Karel

to_hex ( integer ) → text
to_hex ( bigint ) → text

Converts the number to its equivalent hexadecimal representation.

to_hex(2147483647) → 7fffffff

translate ( string text, from text, to text ) → text

Replaces each character in string that matches a character in the from set with the corresponding character in the to set. If from is longer than to, occurrences of the extra characters in from are deleted.

translate(‘12345’, ‘143’, ‘ax’) → a2x5

unistr ( text ) → text

Evaluate escaped Unicode characters in the argument. Unicode characters can be specified as \XXXX (4 hexadecimal digits), \+XXXXXX (6 hexadecimal digits), \uXXXX (4 hexadecimal digits), or \UXXXXXXXX (8 hexadecimal digits). To specify a backslash, write two backslashes. All other characters are taken literally. If the server encoding is not UTF-8, the Unicode code point identified by one of these escape sequences is converted to the actual server encoding; an error is reported if that’s not possible. This function provides a (non-standard) alternative to string constants with Unicode escapes.

unistr(‘d\0061t\+000061’) → data
unistr(‘d\u0061t\U00000061’) → data

concat, concat_ws and format are variadic, so you can pass the values to be concatenated/formatted as an array marked with the VARIADIC keyword.

The array’s elements will be treated as separate ordinary arguments.

format#

Produces output as specified by a format string, in likeness to C’s sprintf function.

format(formatstr text [, formatarg "any" [, ...] ])
--e.g format('Hi %s', 'there!')

formatstr specifies how output should be formatted.

Each formatarg is converted to text, and then inserted into the result string as stipulated by format specifiers.

Format Specifiers#

%[position][flags][width]type

  • position: (optional)

    • n$ where n is the index of the argument to print.

    • 1 refers to the first arg after formatstr, and so on.

    • If omitted, args are used in sequence.

  • flags: (optional)

    • - causes output to be left-justified, but only if width is also specified.

  • width: (optional)

    • n, -n, *(use next function arg as the width) or *n$(use nth function arg as the width).

    • Specifies the minimum number of characters to use to display the format specifier’s output.

    • Output is left/right padded depending on the - flag.

    • Very small widths are ignored; output is not truncated.

  • type: (required)

    • s(string), I(SQL identifier), L(SQL literal).

%% may be used to output a literal %

SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');   -- Testing three, two, one
SELECT format('|%*2$s|', 'foo', 10, 'bar');     -- |       bar|
SELECT format('|%1$*2$s|', 'foo', 10, 'bar');   -- |       foo|
SELECT format('|%-*s|', -10, 'foo');    -- |foo       |

Unlike sprintf, format:

  • allows format specifiers with and without position fields in the same format string.

    A format specifier without a position field always uses the next argument after the last argument consumed.

  • doesn’t require all function args to be used in the format string.

SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');  -- Testing three, two, three