begriffs open source - ai-pg/blob - full-docs/txt/functions-array.txt

   1
   2 9.19. Array Functions and Operators #
   3
   4    Table 9.56 shows the specialized operators available for array types.
   5    In addition to those, the usual comparison operators shown in Table 9.1
   6    are available for arrays. The comparison operators compare the array
   7    contents element-by-element, using the default B-tree comparison
   8    function for the element data type, and sort based on the first
   9    difference. In multidimensional arrays the elements are visited in
  10    row-major order (last subscript varies most rapidly). If the contents
  11    of two arrays are equal but the dimensionality is different, the first
  12    difference in the dimensionality information determines the sort order.
  13
  14    Table 9.56. Array Operators
  15
  16    Operator
  17
  18    Description
  19
  20    Example(s)
  21
  22    anyarray @> anyarray → boolean
  23
  24    Does the first array contain the second, that is, does each element
  25    appearing in the second array equal some element of the first array?
  26    (Duplicates are not treated specially, thus ARRAY[1] and ARRAY[1,1] are
  27    each considered to contain the other.)
  28
  29    ARRAY[1,4,3] @> ARRAY[3,1,3] → t
  30
  31    anyarray <@ anyarray → boolean
  32
  33    Is the first array contained by the second?
  34
  35    ARRAY[2,2,7] <@ ARRAY[1,7,4,2,6] → t
  36
  37    anyarray && anyarray → boolean
  38
  39    Do the arrays overlap, that is, have any elements in common?
  40
  41    ARRAY[1,4,3] && ARRAY[2,1] → t
  42
  43    anycompatiblearray || anycompatiblearray → anycompatiblearray
  44
  45    Concatenates the two arrays. Concatenating a null or empty array is a
  46    no-op; otherwise the arrays must have the same number of dimensions (as
  47    illustrated by the first example) or differ in number of dimensions by
  48    one (as illustrated by the second). If the arrays are not of identical
  49    element types, they will be coerced to a common type (see
  50    Section 10.5).
  51
  52    ARRAY[1,2,3] || ARRAY[4,5,6,7] → {1,2,3,4,5,6,7}
  53
  54    ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9.9]] → {{1,2,3},{4,5,6},{7,8,9.9}}
  55
  56    anycompatible || anycompatiblearray → anycompatiblearray
  57
  58    Concatenates an element onto the front of an array (which must be empty
  59    or one-dimensional).
  60
  61    3 || ARRAY[4,5,6] → {3,4,5,6}
  62
  63    anycompatiblearray || anycompatible → anycompatiblearray
  64
  65    Concatenates an element onto the end of an array (which must be empty
  66    or one-dimensional).
  67
  68    ARRAY[4,5,6] || 7 → {4,5,6,7}
  69
  70    See Section 8.15 for more details about array operator behavior. See
  71    Section 11.2 for more details about which operators support indexed
  72    operations.
  73
  74    Table 9.57 shows the functions available for use with array types. See
  75    Section 8.15 for more information and examples of the use of these
  76    functions.
  77
  78    Table 9.57. Array Functions
  79
  80    Function
  81
  82    Description
  83
  84    Example(s)
  85
  86    array_append ( anycompatiblearray, anycompatible ) → anycompatiblearray
  87
  88    Appends an element to the end of an array (same as the
  89    anycompatiblearray || anycompatible operator).
  90
  91    array_append(ARRAY[1,2], 3) → {1,2,3}
  92
  93    array_cat ( anycompatiblearray, anycompatiblearray ) →
  94    anycompatiblearray
  95
  96    Concatenates two arrays (same as the anycompatiblearray ||
  97    anycompatiblearray operator).
  98
  99    array_cat(ARRAY[1,2,3], ARRAY[4,5]) → {1,2,3,4,5}
 100
 101    array_dims ( anyarray ) → text
 102
 103    Returns a text representation of the array's dimensions.
 104
 105    array_dims(ARRAY[[1,2,3], [4,5,6]]) → [1:2][1:3]
 106
 107    array_fill ( anyelement, integer[] [, integer[] ] ) → anyarray
 108
 109    Returns an array filled with copies of the given value, having
 110    dimensions of the lengths specified by the second argument. The
 111    optional third argument supplies lower-bound values for each dimension
 112    (which default to all 1).
 113
 114    array_fill(11, ARRAY[2,3]) → {{11,11,11},{11,11,11}}
 115
 116    array_fill(7, ARRAY[3], ARRAY[2]) → [2:4]={7,7,7}
 117
 118    array_length ( anyarray, integer ) → integer
 119
 120    Returns the length of the requested array dimension. (Produces NULL
 121    instead of 0 for empty or missing array dimensions.)
 122
 123    array_length(array[1,2,3], 1) → 3
 124
 125    array_length(array[]::int[], 1) → NULL
 126
 127    array_length(array['text'], 2) → NULL
 128
 129    array_lower ( anyarray, integer ) → integer
 130
 131    Returns the lower bound of the requested array dimension.
 132
 133    array_lower('[0:2]={1,2,3}'::integer[], 1) → 0
 134
 135    array_ndims ( anyarray ) → integer
 136
 137    Returns the number of dimensions of the array.
 138
 139    array_ndims(ARRAY[[1,2,3], [4,5,6]]) → 2
 140
 141    array_position ( anycompatiblearray, anycompatible [, integer ] ) →
 142    integer
 143
 144    Returns the subscript of the first occurrence of the second argument in
 145    the array, or NULL if it's not present. If the third argument is given,
 146    the search begins at that subscript. The array must be one-dimensional.
 147    Comparisons are done using IS NOT DISTINCT FROM semantics, so it is
 148    possible to search for NULL.
 149
 150    array_position(ARRAY['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'],
 151    'mon') → 2
 152
 153    array_positions ( anycompatiblearray, anycompatible ) → integer[]
 154
 155    Returns an array of the subscripts of all occurrences of the second
 156    argument in the array given as first argument. The array must be
 157    one-dimensional. Comparisons are done using IS NOT DISTINCT FROM
 158    semantics, so it is possible to search for NULL. NULL is returned only
 159    if the array is NULL; if the value is not found in the array, an empty
 160    array is returned.
 161
 162    array_positions(ARRAY['A','A','B','A'], 'A') → {1,2,4}
 163
 164    array_prepend ( anycompatible, anycompatiblearray ) →
 165    anycompatiblearray
 166
 167    Prepends an element to the beginning of an array (same as the
 168    anycompatible || anycompatiblearray operator).
 169
 170    array_prepend(1, ARRAY[2,3]) → {1,2,3}
 171
 172    array_remove ( anycompatiblearray, anycompatible ) → anycompatiblearray
 173
 174    Removes all elements equal to the given value from the array. The array
 175    must be one-dimensional. Comparisons are done using IS NOT DISTINCT
 176    FROM semantics, so it is possible to remove NULLs.
 177
 178    array_remove(ARRAY[1,2,3,2], 2) → {1,3}
 179
 180    array_replace ( anycompatiblearray, anycompatible, anycompatible ) →
 181    anycompatiblearray
 182
 183    Replaces each array element equal to the second argument with the third
 184    argument.
 185
 186    array_replace(ARRAY[1,2,5,4], 5, 3) → {1,2,3,4}
 187
 188    array_reverse ( anyarray ) → anyarray
 189
 190    Reverses the first dimension of the array.
 191
 192    array_reverse(ARRAY[[1,2],[3,4],[5,6]]) → {{5,6},{3,4},{1,2}}
 193
 194    array_sample ( array anyarray, n integer ) → anyarray
 195
 196    Returns an array of n items randomly selected from array. n may not
 197    exceed the length of array's first dimension. If array is
 198    multi-dimensional, an “item” is a slice having a given first subscript.
 199
 200    array_sample(ARRAY[1,2,3,4,5,6], 3) → {2,6,1}
 201
 202    array_sample(ARRAY[[1,2],[3,4],[5,6]], 2) → {{5,6},{1,2}}
 203
 204    array_shuffle ( anyarray ) → anyarray
 205
 206    Randomly shuffles the first dimension of the array.
 207
 208    array_shuffle(ARRAY[[1,2],[3,4],[5,6]]) → {{5,6},{1,2},{3,4}}
 209
 210    array_sort ( array anyarray [, descending boolean [, nulls_first
 211    boolean ]] ) → anyarray
 212
 213    Sorts the first dimension of the array. The sort order is determined by
 214    the default sort ordering of the array's element type; however, if the
 215    element type is collatable, the collation to use can be specified by
 216    adding a COLLATE clause to the array argument.
 217
 218    If descending is true then sort in descending order, otherwise
 219    ascending order. If omitted, the default is ascending order. If
 220    nulls_first is true then nulls appear before non-null values, otherwise
 221    nulls appear after non-null values. If omitted, nulls_first is taken to
 222    have the same value as descending.
 223
 224    array_sort(ARRAY[[2,4],[2,1],[6,5]]) → {{2,1},{2,4},{6,5}}
 225
 226    array_to_string ( array anyarray, delimiter text [, null_string text ]
 227    ) → text
 228
 229    Converts each array element to its text representation, and
 230    concatenates those separated by the delimiter string. If null_string is
 231    given and is not NULL, then NULL array entries are represented by that
 232    string; otherwise, they are omitted. See also string_to_array.
 233
 234    array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*') → 1,2,3,*,5
 235
 236    array_upper ( anyarray, integer ) → integer
 237
 238    Returns the upper bound of the requested array dimension.
 239
 240    array_upper(ARRAY[1,8,3,7], 1) → 4
 241
 242    cardinality ( anyarray ) → integer
 243
 244    Returns the total number of elements in the array, or 0 if the array is
 245    empty.
 246
 247    cardinality(ARRAY[[1,2],[3,4]]) → 4
 248
 249    trim_array ( array anyarray, n integer ) → anyarray
 250
 251    Trims an array by removing the last n elements. If the array is
 252    multidimensional, only the first dimension is trimmed.
 253
 254    trim_array(ARRAY[1,2,3,4,5,6], 2) → {1,2,3,4}
 255
 256    unnest ( anyarray ) → setof anyelement
 257
 258    Expands an array into a set of rows. The array's elements are read out
 259    in storage order.
 260
 261    unnest(ARRAY[1,2]) →
 262  1
 263  2
 264
 265    unnest(ARRAY[['foo','bar'],['baz','quux']]) →
 266  foo
 267  bar
 268  baz
 269  quux
 270
 271    unnest ( anyarray, anyarray [, ... ] ) → setof anyelement, anyelement
 272    [, ... ]
 273
 274    Expands multiple arrays (possibly of different data types) into a set
 275    of rows. If the arrays are not all the same length then the shorter
 276    ones are padded with NULLs. This form is only allowed in a query's FROM
 277    clause; see Section 7.2.1.4.
 278
 279    select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b) →
 280  a |  b
 281 ---+-----
 282  1 | foo
 283  2 | bar
 284    | baz
 285
 286    See also Section 9.21 about the aggregate function array_agg for use
 287    with arrays.