9.18. Array Functions and Operators
Table 9.51 shows the operators available for array types.
Table 9.51. Array Operators
Operator  Description  Example  Result 

=

equal 
ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3]

t

<>

not equal 
ARRAY[1,2,3] <> ARRAY[1,2,4]

t

<

less than 
ARRAY[1,2,3] < ARRAY[1,2,4]

t

>

greater than 
ARRAY[1,4,3] > ARRAY[1,2,4]

t

<=

less than or equal 
ARRAY[1,2,3] <= ARRAY[1,2,3]

t

>=

greater than or equal 
ARRAY[1,4,3] >= ARRAY[1,4,3]

t

@>

contains 
ARRAY[1,4,3] @> ARRAY[3,1,3]

t

<@

is contained by 
ARRAY[2,2,7] <@ ARRAY[1,7,4,2,6]

t

&&

overlap (have elements in common) 
ARRAY[1,4,3] && ARRAY[2,1]

t



arraytoarray concatenation 
ARRAY[1,2,3]  ARRAY[4,5,6]

{1,2,3,4,5,6}



arraytoarray concatenation 
ARRAY[1,2,3]  ARRAY[[4,5,6],[7,8,9]]

{{1,2,3},{4,5,6},{7,8,9}}



elementtoarray concatenation 
3  ARRAY[4,5,6]

{3,4,5,6}



arraytoelement concatenation 
ARRAY[4,5,6]  7

{4,5,6,7}

The array ordering operators (
<
,
>=
, etc) compare the array contents
elementbyelement, using the default Btree comparison function for
the element data type, and sort based on the first difference.
In multidimensional arrays the elements are visited in rowmajor order
(last subscript varies most rapidly).
If the contents of two arrays are equal but the dimensionality is
different, the first difference in the dimensionality information
determines the sort order. (This is a change from versions of
PostgreSQL
prior to 8.2: older versions would claim
that two arrays with the same contents were equal, even if the
number of dimensions or subscript ranges were different.)
The array containment operators (
<@
and
@>
) consider one array to be contained in
another one if each of its elements appears in the other one.
Duplicates are not treated specially, thus
ARRAY[1]
and
ARRAY[1,1]
are each considered to contain the
other.
See Section 8.15 for more details about array operator behavior. See Section 11.2 for more details about which operators support indexed operations.
Table 9.52 shows the functions available for use with array types. See Section 8.15 for more information and examples of the use of these functions.
Table 9.52. Array Functions
Function  Return Type  Description  Example  Result 


anyarray

append an element to the end of an array 
array_append(ARRAY[1,2], 3)

{1,2,3}


anyarray

concatenate two arrays 
array_cat(ARRAY[1,2,3], ARRAY[4,5])

{1,2,3,4,5}


int

returns the number of dimensions of the array 
array_ndims(ARRAY[[1,2,3], [4,5,6]])

2


text

returns a text representation of array's dimensions 
array_dims(ARRAY[[1,2,3], [4,5,6]])

[1:2][1:3]


anyarray

returns an array initialized with supplied value and dimensions, optionally with lower bounds other than 1 
array_fill(7, ARRAY[3], ARRAY[2])

[2:4]={7,7,7}


int

returns the length of the requested array dimension 
array_length(array[1,2,3], 1)

3


int

returns lower bound of the requested array dimension 
array_lower('[0:2]={1,2,3}'::int[], 1)

0


int

returns the subscript of the first occurrence of the second argument in the array, starting at the element indicated by the third argument or at the first element (array must be onedimensional) 
array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon')

2


int[]

returns an array of subscripts of all occurrences of the second argument in the array given as first argument (array must be onedimensional) 
array_positions(ARRAY['A','A','B','A'], 'A')

{1,2,4}


anyarray

append an element to the beginning of an array 
array_prepend(1, ARRAY[2,3])

{1,2,3}


anyarray

remove all elements equal to the given value from the array (array must be onedimensional) 
array_remove(ARRAY[1,2,3,2], 2)

{1,3}


anyarray

replace each array element equal to the given value with a new value 
array_replace(ARRAY[1,2,5,4], 5, 3)

{1,2,3,4}


text

concatenates array elements using supplied delimiter and optional null string 
array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')

1,2,3,*,5


int

returns upper bound of the requested array dimension 
array_upper(ARRAY[1,8,3,7], 1)

4


int

returns the total number of elements in the array, or 0 if the array is empty 
cardinality(ARRAY[[1,2],[3,4]])

4


text[]

splits string into array elements using supplied delimiter and optional null string 
string_to_array('xx~^~yy~^~zz', '~^~', 'yy')

{xx,NULL,zz}


setof anyelement

expand an array to a set of rows 
unnest(ARRAY[1,2])

1 2(2 rows) 

setof anyelement, anyelement [, ...]

expand multiple arrays (possibly of different types) to a set of rows. This is only allowed in the FROM clause; see Section 7.2.1.4 
unnest(ARRAY[1,2],ARRAY['foo','bar','baz'])

1 foo 2 bar NULL baz(3 rows) 
In
array_position
and
array_positions
,
each array element is compared to the searched value using
IS NOT DISTINCT FROM
semantics.
In
array_position
,
NULL
is returned
if the value is not found.
In
array_positions
,
NULL
is returned
only if the array is
NULL
; if the value is not found in
the array, an empty array is returned instead.
In
string_to_array
, if the delimiter parameter is
NULL, each character in the input string will become a separate element in
the resulting array. If the delimiter is an empty string, then the entire
input string is returned as a oneelement array. Otherwise the input
string is split at each occurrence of the delimiter string.
In
string_to_array
, if the nullstring parameter
is omitted or NULL, none of the substrings of the input will be replaced
by NULL.
In
array_to_string
, if the nullstring parameter
is omitted or NULL, any null elements in the array are simply skipped
and not represented in the output string.
Note
There are two differences in the behavior of
string_to_array
from pre9.1 versions of
PostgreSQL
.
First, it will return an empty (zeroelement) array rather than NULL when
the input string is of zero length. Second, if the delimiter string is
NULL, the function splits the input into individual characters, rather
than returning NULL as before.
See also
Section 9.20
about the aggregate
function
array_agg
for use with arrays.