Project: YugabyteDB (App Definition and Development / Database)
File: concatenation.md

title: Array concatenation functions and operators linkTitle: Array concatenation headerTitle: Array concatenation functions and operators description: Array concatenation functions and operators menu: v2.18: identifier: array-concatenation parent: array-functions-operators weight: 40 type: docs The `||` operator implements, by itself, all of the functionality that each of the `arraycat()`, `arrayappend()`, and `array_prepend()` functions individually implement. Yugabyte recommends that you use the `||` operator and avoid the functions. They are documented here for completenessespecially in case you find them in inherited code. Purpose: Return the concatenation of any number of compatible `anyarray` and `anyelement` values. Signature ``` LHS and RHS input value: [anyarray | anyelement] [anyarray | anyelement]* return value: anyarray ``` Note: "Compatible" is used here to denote two requirements: The values within the array, or the value of the scalar, must be of the same data type, for example, an `int[]` array and an `int` scalar. The LHS and the RHS must be dimensionally compatible. For example, you can produce a one-dimensional array: either by concatenating two scalars; or by concatenating a scalar and a one-dimensional array; or by concatenating two one-dimensional arrays. This notion extends to multidimensional arrays. The next bullet gives the rules. When you concatenate two N-dimensional arrays, the lengths along the major (that is, the first dimension) may be different but the lengths along the other dimensions must be identical. And when (as the analogy of concatenating a one-dimensional array and a scalar) you concatenate an N-dimensional and an (N-1)-dimensional array, the lengths along the dimensions of the (N-1)-dimensional array must all be identical to the corresponding lengths along the dimensions that follow the major dimension in the N-dimensional array. These rules follow directly from the fact that arrays are rectilinear. For examples, see below. Example: ```plpgsql create table t(k int primary key, arr int[]); insert into t(k, arr) values (1, '{3, 4, 5}'::int[]); select arr as "old value of arr" from t where k = 1; update t set arr = '{1, 2}'::int[]||arr||6::int where k = 1; select arr as "new value of arr" from t where k = 1; ``` It shows this: ``` old value of arr {3,4,5} ``` and then this: ``` new value of arr {1,2,3,4,5,6} ``` Purpose: Return the concatenation of two compatible `anyarray` values. Signature ``` input value: anyarray, anyarray return value: anyarray ``` Note: The `DO` block shows that the `||` operator is able to implement the full functionality of the `array_cat()`

```plpgsql do $body$ declare arr_1 constant int[] := '{1, 2, 3}'::int[]; arr_2 constant int[] := '{4, 5, 6}'::int[]; val constant int := 5; workaround constant int[] := array[val]; begin assert arraycat(arr1, arr2) = arr1||arr_2 and arraycat(arr1, workaround) = arr_1||val , 'unexpected'; end; $body$; ``` Purpose: Return an array that results from appending a scalar value to (that is, after) an array value. Signature ``` input value: anyarray, anyelement return value: anyarray ``` Note: The `DO` block shows that the `||` operator is able to implement the full functionality of the `array_append()` function. The values must be compatible. ```plpgsql do $body$ declare arr constant int[] := '{1, 2, 3, 4}'::int[]; val constant int := 5; workaround constant int[] := array[val]; begin assert array_append(arr, val) = arr||val and arrayappend(arr, val) = arraycat(arr, workaround) , 'unexpected'; end; $body$; ``` Purpose: Return an array that results from prepending a scalar value to (that is, before) an array value. Signature ``` input value: anyelement, anyarray return value: anyarray ``` Note: The `DO` block shows that the `||` operator is able to implement the full functionality of the `array_prepend()` function. The values must be compatible. ```plpgsql do $body$ declare arr constant int[] := '{1, 2, 3, 4}'::int[]; val constant int := 5; workaround constant int[] := array[val]; begin assert array_prepend(val, arr) = val||arr and arrayprepend(val, arr) = arraycat(workaround, arr) , 'unexpected'; end; $body$; ``` Semantics for one-arrays ```plpgsql create type rt as (f1 int, f2 text); do $body$ declare arr constant rt[] := array[(3, 'c')::rt, (4, 'd')::rt, (5, 'e')::rt]; prepend_row constant rt := (0, 'z')::rt; prepend_arr constant rt[] := array[(1, 'a')::rt, (2, 'b')::rt]; append_row constant rt := (6, 'f')::rt; catresult constant rt[] := prependrow||prependarr||arr||appendrow; expected_result constant rt[] := array[(0, 'z')::rt, (1, 'a')::rt, (2, 'b')::rt, (3, 'c')::rt, (4, 'd')::rt, (5, 'e')::rt, (6, 'f')::rt]; begin assert (catresult = expectedresult), 'unexpected'; end; $body$; ``` Semantics for multidimensional arrays ```plpgsql do $body$ declare -- arr1 and arr2 are demensionally compatible. -- Its's OK for array_length(*, 1) to differ. -- But array_length(*, 1) must be the same. arr_1 constant int[] := array[ array[11, 12, 13], array[21, 22, 23] ]; arr_2 constant int[] := array[ array[31, 32, 33], array[41, 42, 43], array[51, 52, 53] ]; -- Notice that this is a 1-d array. -- Its lenth is the same as that of arr_1 -- along arr_1's SECOND dimension. arr_3 constant int[] := array[31, 32, 33]; -- Notice that badarr is dimensionally INCOMPATIBLE with arr1: -- they have different lengths along their SECOND major dimension. bad_arr constant int[] := array[ array[61, 62, 63, 64], array[71, 72, 73, 74], array[81, 82, 83, 84] ]; expectedcat1 constant int[] := array[ array[11, 12, 13], array[21, 22, 23], array[31, 32, 33], array[41, 42, 43], array[51, 52, 53] ]; expectedcat2 constant int[] := array[ array[11, 12, 13], array[21, 22, 23], array[31, 32, 33] ]; begin assert arr1||arr2 = expectedcat1 and arr1||arr3 = expectedcat2, 'unexpected'; declare a int[]; begin -- ERROR: cannot concatenate incompatible arrays. a := arr1||badarr; exception when arraysubscripterror then null; end; end; $body$; ```