Array functions

**Arguments**

- `func(x[, y1, ..., yN])` — A lambda function which operates on elements of the source array (`x`) and condition arrays (`y`). [`Lambda function`](/docs/sql-reference/functions/overview#arrow-operator-and-lambda)
- `source_arr` — The source array to process. [`Array(T)`](/docs/sql-reference/data-types/array)
- `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns `1` if the lambda function returns true for at least one element, `0` otherwise [`UInt8`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT arrayExists(x, y -> x=y, [1, 2, 3], [0, 0, 0])
```

```
0
```

## arrayFill[​](#arrayFill "Direct link to arrayFill")

Introduced in: v20.1.0

The `arrayFill` function sequentially processes a source array from the first element
to the last, evaluating a lambda condition at each position using elements from
the source and condition arrays. When the lambda function evaluates to false at
position i, the function replaces that element with the element at position i-1
from the current state of the array. The first element is always preserved
regardless of any condition.

**Syntax**

```
arrayFill(func(x [, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**Arguments**

- `func(x [, y1, ..., yN])` — A lambda function `func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN])` which operates on elements of the source array (`x`) and condition arrays (`y`). [`Lambda function`](/docs/sql-reference/functions/overview#arrow-operator-and-lambda)
- `source_arr` — The source array to process. [`Lambda function`](/docs/sql-reference/functions/overview#arrow-operator-and-lambda)
- `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns an array [`Array(T)`](/docs/sql-reference/data-types/array)

**Examples**

**Example with single array**

```
SELECT arrayFill(x -> not isNull(x), [1, null, 2, null]) AS res
```

```
[1, 1, 2, 2]
```

**Example with two arrays**

```
SELECT arrayFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res
```

```
[5, 5, 6, 6]
```

## arrayFilter[​](#arrayFilter "Direct link to arrayFilter")

Introduced in: v1.1.0

Returns an array containing only the elements in the source array for which a lambda function returns true.

**Syntax**

```
arrayFilter(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])]
```

**Arguments**

- `func(x[, y1, ..., yN])` — A lambda function which operates on elements of the source array (`x`) and condition arrays (`y`). [`Lambda function`](/docs/sql-reference/functions/overview#arrow-operator-and-lambda)
- `source_arr` — The source array to process. [`Array(T)`](/docs/sql-reference/data-types/array)
- `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns a subset of the source array [`Array(T)`](/docs/sql-reference/data-types/array)

**Examples**

**Example 1**

```
SELECT arrayFilter(x -> x LIKE '%World%', ['Hello', 'abc World']) AS res
```

```
['abc World']
```

**Example 2**

```
SELECT
    arrayFilter(
        (i, x) -> x LIKE '%World%',
        arrayEnumerate(arr),
        ['Hello', 'abc World'] AS arr)
    AS res
```

```
[2]
```

## arrayFirst[​](#arrayFirst "Direct link to arrayFirst")

Introduced in: v1.1.0

Returns the first element in the source array for which `func(x[, y1, y2, ... yN])` returns true, otherwise it returns a default value.

**Syntax**

```
arrayFirst(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**Arguments**

- `func(x[, y1, ..., yN])` — A lambda function which operates on elements of the source array (`x`) and condition arrays (`y`). [Lambda function](/docs/sql-reference/functions/overview#arrow-operator-and-lambda). - `source_arr` — The source array to process. [`Array(T)`](/docs/sql-reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array).

**Returned value**

Returns the first element of the source array for which `λ` is true, otherwise returns the default value of `T`.

**Examples**

**Usage example**

```
SELECT arrayFirst(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

```
b
```

**No match**

```
SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

```
0 UInt8
```

## arrayFirstIndex[​](#arrayFirstIndex "Direct link to arrayFirstIndex")

Introduced in: v1.1.0

Returns the index of the first element in the source array for which `func(x[, y1, y2, ... yN])` returns true, otherwise it returns '0'.

**Syntax**

```
arrayFirstIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**Arguments**

- `func(x[, y1, ..., yN])` — A lambda function which operates on elements of the source array (`x`) and condition arrays (`y`). [Lambda function](/docs/sql-reference/functions/overview#arrow-operator-and-lambda). - `source_arr` — The source array to process. [`Array(T)`](/docs/sql-reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array).

**Returned value**

Returns the index of the first element of the source array for which `func` is true, otherwise returns `0` [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

```
2
```

**No match**

```
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f'])
```

```
0
```

## arrayFirstOrNull[​](#arrayFirstOrNull "Direct link to arrayFirstOrNull")

Introduced in: v1.1.0

Returns the first element in the source array for which `func(x[, y1, y2, ... yN])` returns true, otherwise it returns `NULL`.

**Syntax**

```
arrayFirstOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```

**Arguments**

- `func(x[, y1, ..., yN])` — A lambda function which operates on elements of the source array (`x`) and condition arrays (`y`). [`Lambda function`](/docs/sql-reference/functions/overview#arrow-operator-and-lambda)
- `source_arr` — The source array to process. [`Array(T)`](/docs/sql-reference/data-types/array)
- `[, cond1_arr, ... , condN_arr]` — Optional. N condition arrays providing additional arguments to the lambda function. [`Array(T)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns the first element of the source array for which `func` is true, otherwise returns `NULL`.

**Examples**

**Usage example**

```
SELECT arrayFirstOrNull(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```

```
b
```

**No match**

```
SELECT arrayFirstOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```

```
NULL Nullable(UInt8)
```

## arrayFlatten[​](#arrayFlatten "Direct link to arrayFlatten")

Introduced in: v20.1.0

Converts an array of arrays to a flat array.

Function:

- Applies to any depth of nested arrays.
- Does not change arrays that are already flat.

The flattened array contains all the elements from all source arrays.

**Syntax**

```
arrayFlatten(arr)
```

**Aliases**: `flatten`

**Arguments**

- `arr` — A multidimensional array. [`Array(Array(T))`](/docs/sql-reference/data-types/array)

**Returned value**

Returns a flattened array from the multidimensional array [`Array(T)`](/docs/sql-reference/data-types/array)

**Examples**

**Usage example**

```
SELECT arrayFlatten([[[1]], [[2], [3]]]);
```

```
[1, 2, 3]
```

## arrayFold[​](#arrayFold "Direct link to arrayFold")

Introduced in: v23.10.0

Applies a lambda function to one or more equally-sized arrays and collects the result in an accumulator.

**Syntax**