> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Документация по функциям для работы с массивами
# Функции для работы с массивами
{/*AUTOGENERATED_START*/}
## array
Добавленный в: v1.1.0
Создаёт массив из аргументов функции.
Аргументы должны быть константами и иметь типы с общим супертипом.
Нужно передать как минимум один аргумент, иначе будет неясно, массив какого типа создавать.
Это означает, что эту функцию нельзя использовать для создания пустого массива. Для этого используйте функцию `emptyArray*`.
Для той же цели используйте оператор `[ ]`.
**Синтаксис**
```sql theme={null}
array(x1 [, x2, ..., xN])
```
**Аргументы**
* `x1` — Константное значение любого типа T. Если указан только этот аргумент, массив будет иметь тип T. - `[, x2, ..., xN]` — Дополнительные N константных значений с общим супертипом с `x1`
**Возвращаемое значение**
Возвращает массив, где 'T' — наименьший общий тип среди переданных аргументов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Допустимое использование**
```sql title=Query theme={null}
SELECT array(toInt32(1), toUInt16(2), toInt8(3)) AS a, toTypeName(a)
```
```response title=Response theme={null}
┌─a───────┬─toTypeName(a)─┐
│ [1,2,3] │ Array(Int32) │
└─────────┴───────────────┘
```
**Недопустимое использование**
```sql title=Query theme={null}
SELECT array(toInt32(5), toDateTime('1998-06-16'), toInt8(5)) AS a, toTypeName(a)
```
```response title=Response theme={null}
Received exception from server (version 25.4.3):
Code: 386. DB::Exception: Received from localhost:9000. DB::Exception:
There is no supertype for types Int32, DateTime, Int8 ...
```
## arrayAUCPR
Добавленный в: v20.4.0
Вычисляет площадь под кривой точность-полнота (PR).
Кривая точность-полнота строится путём откладывания точности по оси y и полноты по оси x для всех порогов.
Итоговое значение лежит в диапазоне от 0 до 1, при этом более высокое значение указывает на лучшую производительность модели.
PR AUC особенно полезен для несбалансированных наборов данных, поскольку в таких случаях даёт более наглядное представление о производительности, чем ROC AUC.
Подробнее см. [здесь](https://developers.google.com/machine-learning/glossary#pr-auc-area-under-the-pr-curve), [здесь](https://developers.google.com/machine-learning/crash-course/classification/roc-and-auc#expandable-1) и [здесь](https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve).
**Синтаксис**
```sql theme={null}
arrayAUCPR(scores, labels[, partial_offsets])
```
**Псевдонимы**: `arrayPRAUC`
**Аргументы**
* `cores` — Оценки, выдаваемые моделью предсказания. [`Array((U)Int*)`](/docs/ru/reference/data-types/array) или [`Array(Float*)`](/docs/ru/reference/data-types/array)
* `labels` — Метки примеров: обычно 1 для положительного примера и 0 для отрицательного. [`Array((U)Int*)`](/docs/ru/reference/data-types/array) или [`Array(Enum)`](/docs/ru/reference/data-types/array)
* `partial_offsets` —
* Необязательно. [`Array(T)`](/docs/ru/reference/data-types/array) из трёх неотрицательных целых чисел для вычисления частичной площади под PR-кривой (что эквивалентно вертикальной полосе в PR-пространстве) вместо полного AUC. Этот параметр полезен при распределённом вычислении PR AUC. Массив должен содержать следующие элементы \[`higher_partitions_tp`, `higher_partitions_fp`, `total_positives`].
* `higher_partitions_tp`: Количество положительных меток в партициях с более высокими оценками.
* `higher_partitions_fp`: Количество отрицательных меток в партициях с более высокими оценками.
* `total_positives`: Общее количество положительных примеров во всём наборе данных.
При использовании `arr_partial_offsets` `arr_scores` и `arr_labels` должны представлять только одну партицию всего набора данных, содержащую интервал оценок.
Набор данных следует разбить на непрерывные партиции, где каждая партиция содержит подмножество данных, оценки которых попадают в определённый диапазон.
Например:
* Одна партиция может содержать все оценки в диапазоне \[0, 0.5).
* Другая партиция может содержать оценки в диапазоне \[0.5, 1.0].
**Возвращаемое значение**
Возвращает площадь под кривой точность-полнота (PR). [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);
```
```response title=Response theme={null}
┌─arrayAUCPR([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1])─┐
│ 0.8333333333333333 │
└─────────────────────────────────────────────────┘
```
## arrayAll
Добавленный в: v1.1.0
Возвращает `1`, если лямбда-функция `func(x [, y1, y2, ... yN])` возвращает true для всех элементов. В противном случае возвращает `0`.
**Синтаксис**
```sql theme={null}
arrayAll(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — лямбда-функция, которая работает с элементами исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `cond1_arr, ...` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает `1`, если лямбда-функция возвращает true для всех элементов, иначе `0` [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Все элементы удовлетворяют условию**
```sql title=Query theme={null}
SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 2, 3])
```
```response title=Response theme={null}
1
```
**Не все элементы совпадают**
```sql title=Query theme={null}
SELECT arrayAll(x, y -> x=y, [1, 2, 3], [1, 1, 1])
```
```response title=Response theme={null}
0
```
## arrayAutocorrelation
Добавленный в: v26.4.0
Вычисляет автокорреляцию массива.
Если указан `max_lag`, корреляция вычисляется только для лагов в диапазоне `[0, max_lag)`.
Если `max_lag` не указан, она вычисляется для всех возможных лагов.
**Синтаксис**
```sql theme={null}
arrayAutocorrelation(arr, [max_lag])
```
**Аргументы**
* `arr` — Массив чисел. [`Array(T)`](/docs/ru/reference/data-types/array)
* `max_lag` — Необязательный параметр. Максимальное число вычисляемых лагов. Должен быть неотрицательным целым числом. [`Integer`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает массив значений типа Float64. Возвращает NaN, если дисперсия равна 0. [`Array(Float64)`](/docs/ru/reference/data-types/array)
**Примеры**
**Линейный**
```sql title=Query theme={null}
SELECT arrayAutocorrelation([1, 2, 3, 4, 5]);
```
```response title=Response theme={null}
[1, 0.4, -0.1, -0.4, -0.4]
```
**Симметричный**
```sql title=Query theme={null}
SELECT arrayAutocorrelation([10, 20, 10]);
```
```response title=Response theme={null}
[1, -0.6666666666666669, 0.16666666666666674]
```
**Константа**
```sql title=Query theme={null}
SELECT arrayAutocorrelation([5, 5, 5]);
```
```response title=Response theme={null}
[nan, nan, nan]
```
**Ограничено**
```sql title=Query theme={null}
SELECT arrayAutocorrelation([1, 2, 3, 4, 5], 2);
```
```response title=Response theme={null}
[1, 0.4]
```
## arrayAvg
Добавленный в: v21.1.0
Возвращает среднее значение элементов исходного массива.
Если указана лямбда-функция `func`, возвращает среднее значение результатов лямбда-функции.
**Синтаксис**
```sql theme={null}
arrayAvg([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Необязательно. Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, которые передают дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает среднее арифметическое элементов исходного массива или, если указана лямбда-функция, среднее арифметическое элементов её результатов. [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT arrayAvg([1, 2, 3, 4]);
```
```response title=Response theme={null}
2.5
```
**Использование с лямбда-функцией**
```sql title=Query theme={null}
SELECT arrayAvg(x, y -> x*y, [2, 3], [2, 3]) AS res;
```
```response title=Response theme={null}
6.5
```
## arrayBottomK
Добавленный в: v26.6.0
Возвращает массив из K наименьших элементов входного массива, отсортированных по возрастанию.
Если указана лямбда-функция `f`, элементы сравниваются по результату применения `f` к каждому элементу.
Если `f` принимает несколько аргументов, в `arrayBottomK` передаются дополнительные массивы, а их элементы
соответствуют аргументам `f`.
Значения `NULL` пропускаются и не включаются в результат. Размер результата не превышает `K`
и может быть меньше, если входной массив содержит меньше не-`NULL` элементов, чем `K`.
Тип элементов результата — не-Nullable версия типа элементов входного массива.
`arrayBottomK` — это [функция высшего порядка](/docs/ru/reference/functions/regular-functions/overview#higher-order-functions).
См. также:
* `arrayTopK`, которая возвращает K наибольших элементов.
* `arrayPartialSort`, которая помещает те же K элементов в позиции `[1..K]`, но
также сохраняет остальные элементы в неопределённом порядке и не пропускает значения `NULL`.
**Синтаксис**
```sql theme={null}
arrayBottomK([f,] K, arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(arr[, arr1, ... ,arrN])` — Необязательно. Лямбда-функция для вычисления ключа сортировки для каждого элемента. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `K` — Число наименьших элементов, которые нужно вернуть. [`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint)
* `arr` — Массив. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr1, ... ,arrN` — N дополнительных массивов, если `f` принимает несколько аргументов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает до `K` элементов массива `arr` с наименьшими значениями (или наименьшими результатами лямбда-функции), отсортированных по возрастанию.
NULL пропускаются. Возвращаемый массив имеет тип элементов `T`, даже если входной массив имеет тип `Nullable(T)`.
**Примеры**
**simple\_int**
```sql title=Query theme={null}
SELECT arrayBottomK(3, [1, 5, 2, 7, 3])
```
```response title=Response theme={null}
[1,2,3]
```
**skip\_nulls**
```sql title=Query theme={null}
SELECT arrayBottomK(3, [1, NULL, 5, 2, NULL, 7])
```
```response title=Response theme={null}
[1,2,5]
```
**fewer\_than\_k**
```sql title=Query theme={null}
SELECT arrayBottomK(5, [1, NULL, 2])
```
```response title=Response theme={null}
[1,2]
```
**lambda\_simple**
```sql title=Query theme={null}
SELECT arrayBottomK((x) -> -x, 2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[9,5]
```
**lambda\_multi**
```sql title=Query theme={null}
SELECT arrayBottomK((x, y) -> y, 2, ['a', 'b', 'c'], [3, 1, 2])
```
```response title=Response theme={null}
['b','c']
```
## arrayCompact
Добавленный в: v20.1.0
Удаляет из массива подряд идущие повторяющиеся элементы, включая значения `null`. Порядок значений в результирующем массиве определяется порядком элементов в исходном массиве.
**Синтаксис**
```sql theme={null}
arrayCompact(arr)
```
**Аргументы**
* `arr` — Массив, из которого удаляются дубликаты. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив без повторяющихся значений [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayCompact([1, 1, nan, nan, 2, 3, 3, 3]);
```
```response title=Response theme={null}
[1,nan,2,3]
```
## arrayConcat
Добавленный в: v1.1.0
Объединяет массивы, переданные в качестве аргументов.
**Синтаксис**
```sql theme={null}
arrayConcat(arr1 [, arr2, ... , arrN])
```
**Аргументы**
* `arr1 [, arr2, ... , arrN]` — N массивов, которые нужно объединить. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает один массив, полученный объединением переданных массивов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayConcat([1, 2], [3, 4], [5, 6]) AS res
```
```response title=Response theme={null}
[1, 2, 3, 4, 5, 6]
```
## arrayCount
Добавленный в: v1.1.0
Возвращает количество элементов, для которых `func(arr1[i], ..., arrN[i])` возвращает `true`.
Если `func` не указана, возвращает количество ненулевых элементов в массиве.
`arrayCount` — это [функция высшего порядка](/docs/ru/reference/functions/regular-functions/overview#higher-order-functions).
**Синтаксис**
```sql theme={null}
arrayCount([func, ] arr1, ...)
```
**Аргументы**
* `func` — Необязательный. Функция, применяемая к каждому элементу массива (массивов). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1, ..., arrN` — N массивов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает количество элементов, для которых `func` возвращает true. В противном случае возвращает количество ненулевых элементов в массиве. [`UInt32`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayCount(x -> (x % 2), groupArray(number)) FROM numbers(10)
```
```response title=Response theme={null}
5
```
## arrayCumSum
Добавленный в: v1.1.0
Возвращает массив частичных (накопленных) сумм элементов исходного массива. Если указана лямбда-функция, сумма вычисляется путем применения лямбда-функции к элементам массива на каждой позиции.
**Синтаксис**
```sql theme={null}
arrayCumSum([func,] arr1[, arr2, ... , arrN])
```
**Аргументы**
* `func` — Необязательно. Лямбда-функция, применяемая к элементам массива на каждой позиции. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1` — Исходный массив числовых значений. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[arr2, ..., arrN]` — Необязательно. Дополнительные массивы того же размера, передаваемые в качестве аргументов лямбда-функции, если она указана. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив накопленных сумм элементов исходного массива. Тип результата совпадает с числовым типом входного массива. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовое использование**
```sql title=Query theme={null}
SELECT arrayCumSum([1, 1, 1, 1]) AS res
```
```response title=Response theme={null}
[1, 2, 3, 4]
```
**С лямбда-функцией**
```sql title=Query theme={null}
SELECT arrayCumSum(x -> x * 2, [1, 2, 3]) AS res
```
```response title=Response theme={null}
[2, 6, 12]
```
## arrayCumSumNonNegative
Добавленный в: v18.12.0
Возвращает массив частичных (накопительных) сумм элементов исходного массива, заменяя любую отрицательную накопительную сумму на ноль. Если указана лямбда-функция, сумма вычисляется путем применения этой функции к элементам массива для каждой позиции.
**Синтаксис**
```sql theme={null}
arrayCumSumNonNegative([func,] arr1[, arr2, ... , arrN])
```
**Аргументы**
* `func` — Необязательно. Лямбда-функция, применяемая к элементам массива в каждой позиции. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1` — Исходный массив числовых значений. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[arr2, ..., arrN]` — Необязательно. Дополнительные массивы того же размера, передаваемые в лямбда-функцию в качестве аргументов, если она указана. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив частичных сумм элементов исходного массива, в котором любая отрицательная накопленная сумма заменяется нулём. Тип результата соответствует числовому типу входного массива. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовое использование**
```sql title=Query theme={null}
SELECT arrayCumSumNonNegative([1, 1, -4, 1]) AS res
```
```response title=Response theme={null}
[1, 2, 0, 1]
```
**С лямбда-выражением**
```sql title=Query theme={null}
SELECT arrayCumSumNonNegative(x -> x * 2, [1, -2, 3]) AS res
```
```response title=Response theme={null}
[2, 0, 6]
```
## arrayDifference
Добавленный в: v1.1.0
Вычисляет массив разностей между соседними элементами массива.
Первым элементом результирующего массива будет 0, вторым — `arr[1] - arr[0]`, третьим — `arr[2] - arr[1]` и так далее.
Тип элементов результирующего массива определяется правилами вывода типов для вычитания (например, `UInt8` - `UInt8` = `Int16`).
**Синтаксис**
```sql theme={null}
arrayDifference(arr)
```
**Аргументы**
* `arr` — массив `Array`, для которого вычисляются разности между соседними элементами. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив разностей между соседними элементами массива [`UInt*`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayDifference([1, 2, 3, 4]);
```
```response title=Response theme={null}
[0,1,1,1]
```
**Пример переполнения из-за типа результата Int64**
```sql title=Query theme={null}
SELECT arrayDifference([0, 10000000000000000000]);
```
```response title=Response theme={null}
┌─arrayDifference([0, 10000000000000000000])─┐
│ [0,-8446744073709551616] │
└────────────────────────────────────────────┘
```
## arrayDistinct
Добавленный в: v1.1.0
Возвращает массив, содержащий только уникальные элементы исходного массива.
**Синтаксис**
```sql theme={null}
arrayDistinct(arr)
```
**Аргументы**
* `arr` — Массив, из которого нужно извлечь уникальные элементы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, содержащий уникальные элементы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayDistinct([1, 2, 2, 3, 1]);
```
```response title=Response theme={null}
[1,2,3]
```
## arrayDotProduct
Добавленный в: v23.5.0
Возвращает скалярное произведение двух массивов.
Размеры двух векторов должны быть одинаковыми. Типы Array и Tuple также могут содержать элементы разных типов.
**Синтаксис**
```sql theme={null}
arrayDotProduct(v1, v2)
```
**Аргументы**
* `v1` — Первый вектор. [`Array((U)Int* | Float* | BFloat16 | Decimal)`](/docs/ru/reference/data-types/array) или [`Tuple((U)Int* | Float* | Decimal)`](/docs/ru/reference/data-types/tuple)
* `v2` — Второй вектор. [`Array((U)Int* | Float* | BFloat16 | Decimal)`](/docs/ru/reference/data-types/array) или [`Tuple((U)Int* | Float* | Decimal)`](/docs/ru/reference/data-types/tuple)
**Возвращаемое значение**
Скалярное произведение двух векторов.
Возвращаемый тип определяется типами аргументов. Если Array или Tuple содержат элементы разных типов, то тип результата — супертип.
Два массива `BFloat16` накапливаются и возвращают значение типа `Float32` (то же правило, что и для двух массивов `Float32`).
[`(U)Int*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float) или [`Decimal`](/docs/ru/reference/data-types/decimal)
**Примеры**
**Пример с Array**
```sql title=Query theme={null}
SELECT arrayDotProduct([1, 2, 3], [4, 5, 6]) AS res, toTypeName(res);
```
```response title=Response theme={null}
32 UInt16
```
**Пример с Tuple**
```sql title=Query theme={null}
SELECT dotProduct((1::UInt16, 2::UInt8, 3::Float32),(4::Int16, 5::Float32, 6::UInt8)) AS res, toTypeName(res);
```
```response title=Response theme={null}
32 Float64
```
## arrayElement
Добавленный в: v1.1.0
Возвращает элемент указанного массива с индексом `n`, где `n` может быть любым целочисленным типом.
Если индекс выходит за пределы массива, возвращается значение по умолчанию (0 для чисел, пустая строка для строк и т. д.),
за исключением случаев, когда аргументом является неконстантный массив, а индекс 0 — константа. В этом случае возникнет ошибка `Array indices are 1-based`.
Массивы в ClickHouse индексируются с 1.
Поддерживаются отрицательные индексы. В этом случае выбирается соответствующий элемент с нумерацией от конца. Например, `arr[-1]` — последний элемент массива.
Оператор `[n]` обеспечивает ту же функциональность.
**Синтаксис**
```sql theme={null}
arrayElement(arr, n)
```
**Аргументы**
* `arr` — Массив, в котором выполняется поиск. [`Array(T)`](/docs/ru/reference/data-types/array). - `n` — Позиция элемента, который требуется получить. [`(U)Int*`](/docs/ru/reference/data-types/int-uint).
**Возвращаемое значение**
Возвращает один объединённый массив из переданных массивов-аргументов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayElement(arr, 2) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
2
```
**Индексация с отрицательными индексами**
```sql title=Query theme={null}
SELECT arrayElement(arr, -1) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
3
```
**Использование нотации \[n]**
```sql title=Query theme={null}
SELECT arr[2] FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
2
```
**Индекс выходит за границы массива**
```sql title=Query theme={null}
SELECT arrayElement(arr, 4) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
0
```
## arrayElementOrNull
Добавленный в: v1.1.0
Возвращает элемент указанного массива по индексу `n`, где `n` может иметь любой целочисленный тип.
Если индекс выходит за границы массива, вместо значения по умолчанию возвращается `NULL`.
Массивы в ClickHouse индексируются с 1.
Поддерживаются отрицательные индексы. В этом случае выбирается соответствующий элемент, отсчитываемый с конца. Например, `arr[-1]` — это последний элемент массива.
**Синтаксис**
```sql theme={null}
arrayElementOrNull(arrays)
```
**Аргументы**
* `arrays` — Произвольное количество аргументов типа массив. [`Array`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает объединённый массив, объединяющий переданные аргументы-массивы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, 2) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
2
```
**Индексация с отрицательными индексами**
```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, -1) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
3
```
**Индекс выходит за границы массива**
```sql title=Query theme={null}
SELECT arrayElementOrNull(arr, 4) FROM (SELECT [1, 2, 3] AS arr)
```
```response title=Response theme={null}
NULL
```
## arrayEnumerate
Добавленный в: v1.1.0
Возвращает массив `[1, 2, 3, ..., length (arr)]`
Эта функция обычно используется с оператором [`ARRAY JOIN`](/docs/ru/reference/statements/select/array-join). Она позволяет выполнять подсчёт
только один раз для каждого массива после применения `ARRAY JOIN`.
Эту функцию также можно использовать в функциях высшего порядка. Например, с её помощью можно получить индексы элементов массива, соответствующих условию.
**Синтаксис**
```sql theme={null}
arrayEnumerate(arr)
```
**Аргументы**
* `arr` — массив, который нужно пронумеровать. [`Array`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив `[1, 2, 3, ..., length (arr)]`. [`Array(UInt32)`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовый пример с ARRAY JOIN**
```sql title=Query theme={null}
CREATE TABLE test
(
`id` UInt8,
`tag` Array(String),
`version` Array(String)
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO test VALUES (1, ['release-stable', 'dev', 'security'], ['2.4.0', '2.6.0-alpha', '2.4.0-sec1']);
SELECT
id,
tag,
version,
seq
FROM test
ARRAY JOIN
tag,
version,
arrayEnumerate(tag) AS seq
```
```response title=Response theme={null}
┌─id─┬─tag────────────┬─version─────┬─seq─┐
│ 1 │ release-stable │ 2.4.0 │ 1 │
│ 1 │ dev │ 2.6.0-alpha │ 2 │
│ 1 │ security │ 2.4.0-sec1 │ 3 │
└────┴────────────────┴─────────────┴─────┘
```
## arrayEnumerateDense
Добавленный в: v18.12.0
Возвращает массив того же размера, что и исходный, показывая, где каждый элемент впервые встречается в исходном массиве.
**Синтаксис**
```sql theme={null}
arrayEnumerateDense(arr)
```
**Аргументы**
* `arr` — Массив, который нужно пронумеровать. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив того же размера, что и `arr`, указывающий позицию первого вхождения каждого элемента в исходном массиве [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayEnumerateDense([10, 20, 10, 30])
```
```response title=Response theme={null}
[1,2,1,3]
```
## arrayEnumerateDenseRanked
Добавленный в: v20.1.0
Возвращает массив того же размера, что и исходный, указывая, где каждый элемент впервые встречается в исходном массиве. Позволяет выполнять нумерацию многомерного массива с возможностью указать, на какую глубину просматривать массив.
**Синтаксис**
```sql theme={null}
arrayEnumerateDenseRanked(clear_depth, arr, max_array_depth)
```
**Аргументы**
* `clear_depth` — Отдельно нумерует элементы на указанном уровне. Должен быть меньше или равен `max_arr_depth`. [`UInt*`](/docs/ru/reference/data-types/int-uint)
* `arr` — N-мерный массив, элементы которого нужно пронумеровать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `max_array_depth` — Максимальная эффективная глубина. Должна быть меньше или равна глубине `arr`. [`UInt*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает массив, указывающий, где каждый элемент впервые встречается в исходном массиве [`Array`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовое использование**
```sql title=Query theme={null}
-- При clear_depth=1 и max_array_depth=1 результат идентичен результату arrayEnumerateDense.
SELECT arrayEnumerateDenseRanked(1,[10, 20, 10, 30],1);
```
```response title=Response theme={null}
[1,2,1,3]
```
**Использование с многомерным массивом**
```sql title=Query theme={null}
-- В этом примере arrayEnumerateDenseRanked используется для получения массива, указывающего для каждого элемента
-- многомерного массива его порядковый номер среди элементов с одинаковым значением.
-- Для первой строки переданного массива [10, 10, 30, 20] соответствующая первая строка результата равна [1, 1, 2, 3]:
-- 10 — первое встреченное число (позиции 1 и 2), 30 — второе встреченное число (позиция 3),
-- 20 — третье встреченное число (позиция 4).
-- Для второй строки [40, 50, 10, 30] соответствующая вторая строка результата равна [4,5,1,2]: 40
-- и 50 — четвёртое и пятое встреченные числа (позиции 1 и 2 этой строки), ещё одно 10
-- (первое встреченное число) находится в позиции 3, а 30 (второе встреченное число) — в последней позиции.
SELECT arrayEnumerateDenseRanked(1,[[10,10,30,20],[40,50,10,30]],2);
```
```response title=Response theme={null}
[[1,1,2,3],[4,5,1,2]]
```
**Пример с увеличенным значением clear\_depth**
```sql title=Query theme={null}
-- При clear_depth=2 перечисление выполняется заново отдельно для каждой строки.
SELECT arrayEnumerateDenseRanked(2,[[10,10,30,20],[40,50,10,30]],2);
```
```response title=Response theme={null}
[[1, 1, 2, 3], [1, 2, 3, 4]]
```
## arrayEnumerateUniq
Добавленный в: v1.1.0
Возвращает массив того же размера, что и исходный, где для каждого элемента указана его позиция среди элементов с тем же значением.
Эта функция полезна при использовании `ARRAY JOIN` и агрегации элементов массива.
Функция может принимать в качестве аргументов несколько массивов одинакового размера. В этом случае уникальность определяется для кортежей элементов, находящихся на одинаковых позициях во всех массивах.
**Синтаксис**
```sql theme={null}
arrayEnumerateUniq(arr1[, arr2, ... , arrN])
```
**Аргументы**
* `arr1` — Первый массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr2, ...` — Необязательно. Дополнительные массивы того же размера для обеспечения уникальности кортежей. [`Array(UInt32)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, в котором каждый элемент — это порядковый номер среди элементов с тем же значением или тем же кортежем. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовое использование**
```sql title=Query theme={null}
SELECT arrayEnumerateUniq([10, 20, 10, 30]);
```
```response title=Response theme={null}
[1, 1, 2, 1]
```
**Несколько массивов**
```sql title=Query theme={null}
SELECT arrayEnumerateUniq([1, 1, 1, 2, 2, 2], [1, 1, 2, 1, 1, 2]);
```
```response title=Response theme={null}
[1,2,1,1,2,1]
```
**Агрегация ARRAY JOIN**
```sql title=Query theme={null}
-- Для каждого идентификатора цели вычисляется количество конверсий (каждый элемент вложенной структуры данных Goals является достигнутой целью, которую мы называем конверсией)
-- и количество сеансов. Без ARRAY JOIN количество сеансов считалось бы как sum(Sign). Однако в данном случае
-- строки были умножены на вложенную структуру Goals, поэтому чтобы учесть каждый сеанс ровно один раз, применяется условие на
-- значение функции arrayEnumerateUniq(Goals.ID).
SELECT
Goals.ID AS GoalID,
sum(Sign) AS Reaches,
sumIf(Sign, num = 1) AS Visits
FROM test.visits
ARRAY JOIN
Goals,
arrayEnumerateUniq(Goals.ID) AS num
WHERE CounterID = 160656
GROUP BY GoalID
ORDER BY Reaches DESC
LIMIT 10
```
```response title=Response theme={null}
┌──GoalID─┬─Reaches─┬─Visits─┐
│ 53225 │ 3214 │ 1097 │
│ 2825062 │ 3188 │ 1097 │
│ 56600 │ 2803 │ 488 │
│ 1989037 │ 2401 │ 365 │
│ 2830064 │ 2396 │ 910 │
│ 1113562 │ 2372 │ 373 │
│ 3270895 │ 2262 │ 812 │
│ 1084657 │ 2262 │ 345 │
│ 56599 │ 2260 │ 799 │
│ 3271094 │ 2256 │ 812 │
└─────────┴─────────┴────────┘
```
## arrayEnumerateUniqRanked
Добавленный в: v20.1.0
Возвращает массив (или многомерный массив) той же размерности, что и исходный массив,
где для каждого элемента указана его позиция среди элементов с тем же значением.
Позволяет выполнять нумерацию многомерного массива с возможностью указать, на какую глубину просматривать массив.
**Синтаксис**
```sql theme={null}
arrayEnumerateUniqRanked(clear_depth, arr, max_array_depth)
```
**Аргументы**
* `clear_depth` — Отдельно нумерует элементы на указанном уровне. Положительное целое число, меньшее или равное `max_arr_depth`. [`UInt*`](/docs/ru/reference/data-types/int-uint)
* `arr` — N-мерный массив, элементы которого нужно пронумеровать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `max_array_depth` — Максимальная эффективная глубина. Положительное целое число, меньшее или равное глубине `arr`. [`UInt*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает N-мерный массив того же размера, что и `arr`, где каждый элемент показывает порядковый номер данного элемента среди других элементов с тем же значением. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример 1**
```sql title=Query theme={null}
-- При clear_depth=1 и max_array_depth=1 результат arrayEnumerateUniqRanked
-- совпадает с результатом, который вернул бы arrayEnumerateUniq для того же массива.
SELECT arrayEnumerateUniqRanked(1, [1, 2, 1], 1);
```
```response title=Response theme={null}
[1, 1, 2]
```
**Пример 2**
```sql title=Query theme={null}
-- При clear_depth=1 и max_array_depth=1 результат arrayEnumerateUniqRanked
-- идентичен результату, который дал бы arrayEnumerateUniq для того же массива.
SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);", "[[1, 1, 1], [2, 3, 2], [2]]
```
```response title=Response theme={null}
[1, 1, 2]
```
**Пример 3**
```sql title=Query theme={null}
-- В этом примере arrayEnumerateUniqRanked используется для получения массива, указывающего,
-- для каждого элемента многомерного массива, какова его позиция среди элементов
-- с тем же значением. Для первой строки переданного массива [1, 2, 3] соответствующий
-- результат равен [1, 1, 1]: значения 1, 2 и 3 встречаются впервые.
-- Для второй строки переданного массива [2, 2, 1] соответствующий результат равен [2, 3, 3]:
-- значение 2 встречается второй и третий раз, а 1 — второй раз.
-- Аналогично, для третьей строки переданного массива [3]
-- соответствующий результат равен [2]: значение 3 встречается второй раз.
SELECT arrayEnumerateUniqRanked(1, [[1, 2, 3], [2, 2, 1], [3]], 2);
```
```response title=Response theme={null}
[[1, 1, 1], [2, 3, 2], [2]]
```
**Пример 4**
```sql title=Query theme={null}
-- При clear_depth=2 элементы перечисляются отдельно для каждой строки.
SELECT arrayEnumerateUniqRanked(2,[[1, 2, 3],[2, 2, 1],[3]], 2);
```
```response title=Response theme={null}
[[1, 1, 1], [1, 2, 1], [1]]
```
## arrayExcept
Добавленный в: v25.9.0
Возвращает массив, содержащий элементы из `source`, которых нет в `except`, с сохранением исходного порядка.
Эта функция выполняет операцию разности множеств между двумя массивами. Для каждого элемента в `source` она проверяет, есть ли этот элемент в `except` (с использованием точного сравнения). Если нет, элемент включается в результат.
Операция сохраняет следующие свойства:
1. Порядок элементов из `source` сохраняется
2. Дубликаты в `source` сохраняются, если их нет в `except`
3. NULL обрабатывается как отдельное значение
**Синтаксис**
```sql theme={null}
arrayExcept(source, except)
```
**Аргументы**
* `source` — Исходный массив, содержащий элементы для фильтрации. [`Array(T)`](/docs/ru/reference/data-types/array)
* `except` — Массив, содержащий элементы, которые нужно исключить из результата. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив того же типа, что и входной массив, содержащий элементы из `source`, отсутствующие в `except`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**базовый**
```sql title=Query theme={null}
SELECT arrayExcept([1, 2, 3, 2, 4], [3, 5])
```
```response title=Response theme={null}
[1, 2, 2, 4]
```
**with\_nulls1**
```sql title=Query theme={null}
SELECT arrayExcept([1, NULL, 2, NULL], [2])
```
```response title=Response theme={null}
[1, NULL, NULL]
```
**with\_nulls2**
```sql title=Query theme={null}
SELECT arrayExcept([1, NULL, 2, NULL], [NULL, 2, NULL])
```
```response title=Response theme={null}
[1]
```
**строки**
```sql title=Query theme={null}
SELECT arrayExcept(['apple', 'banana', 'cherry'], ['banana', 'date'])
```
```response title=Response theme={null}
['apple', 'cherry']
```
## arrayExists
Добавленный в: v1.1.0
Возвращает `1`, если в исходном массиве есть хотя бы один элемент, для которого `func(x[, y1, y2, ... yN])` возвращает истину. В противном случае возвращает `0`.
**Синтаксис**
```sql theme={null}
arrayExists(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, которая применяется к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, которые передают лямбда-функции дополнительные аргументы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает `1`, если лямбда-функция возвращает true хотя бы для одного элемента, иначе — `0` [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayExists(x, y -> x=y, [1, 2, 3], [0, 0, 0])
```
```response title=Response theme={null}
0
```
## arrayFill
Добавленный в: v20.1.0
Функция `arrayFill` последовательно обрабатывает исходный массив от первого элемента
до последнего, вычисляя лямбда-условие для каждой позиции с использованием элементов из
исходного массива и массивов условий. Если лямбда-функция возвращает false в
позиции i, функция заменяет этот элемент элементом из позиции i-1
в текущем состоянии массива. Первый элемент всегда сохраняется
независимо от условия.
**Синтаксис**
```sql theme={null}
arrayFill(func(x [, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x [, y1, ..., yN])` — лямбда-функция `func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN])`, которая применяется к элементам исходного массива (`x`) и условных массивов (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — исходный массив для обработки. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N условных массивов, которые передают дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример с одним массивом**
```sql title=Query theme={null}
SELECT arrayFill(x -> not isNull(x), [1, null, 2, null]) AS res
```
```response title=Response theme={null}
[1, 1, 2, 2]
```
**Пример с двумя массивами**
```sql title=Query theme={null}
SELECT arrayFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res
```
```response title=Response theme={null}
[5, 5, 6, 6]
```
## arrayFilter
Добавленный в: v1.1.0
Возвращает массив, содержащий только те элементы исходного массива, для которых лямбда-функция возвращает true.
**Синтаксис**
```sql theme={null}
arrayFilter(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])]
```
**Аргументы**
* `func(x[, y1, ..., yN])` — лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает подмножество исходного массива [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример 1**
```sql title=Query theme={null}
SELECT arrayFilter(x -> x LIKE '%World%', ['Hello', 'abc World']) AS res
```
```response title=Response theme={null}
['abc World']
```
**Пример 2**
```sql title=Query theme={null}
SELECT
arrayFilter(
(i, x) -> x LIKE '%World%',
arrayEnumerate(arr),
['Hello', 'abc World'] AS arr)
AS res
```
```response title=Response theme={null}
[2]
```
## arrayFirst
Добавленный в: v1.1.0
Возвращает первый элемент исходного массива, для которого `func(x[, y1, y2, ... yN])` возвращает true; в противном случае возвращает значение по умолчанию.
**Синтаксис**
```sql theme={null}
arrayFirst(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [Лямбда-функция](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает первый элемент исходного массива, для которого `λ` истинна; в противном случае возвращает значение по умолчанию для `T`.
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```
```response title=Response theme={null}
b
```
**Нет совпадений**
```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```
```response title=Response theme={null}
0 UInt8
```
## arrayFirstIndex
Добавленный в: v1.1.0
Возвращает индекс первого элемента в исходном массиве, для которого `func(x[, y1, y2, ... yN])` возвращает true; в противном случае возвращает '0'.
**Синтаксис**
```sql theme={null}
arrayFirstIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [Лямбда-функция](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — Исходный массив, который нужно обработать. [`Array(T)`](/docs/ru/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает индекс первого элемента исходного массива, для которого `func` возвращает true, в противном случае возвращает `0` [`UInt32`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```
```response title=Response theme={null}
2
```
**Нет совпадений**
```sql title=Query theme={null}
SELECT arrayFirstIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f'])
```
```response title=Response theme={null}
0
```
## arrayFirstOrNull
Добавленный в: v1.1.0
Возвращает первый элемент исходного массива, для которого `func(x[, y1, y2, ... yN])` возвращает true; в противном случае возвращает `NULL`.
**Синтаксис**
```sql theme={null}
arrayFirstOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив, который нужно обработать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает первый элемент исходного массива, для которого `func` возвращает true; в противном случае возвращает `NULL`.
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayFirstOrNull(x, y -> x=y, ['a', 'b', 'c'], ['c', 'b', 'a'])
```
```response title=Response theme={null}
b
```
**Совпадений не найдено**
```sql title=Query theme={null}
SELECT arrayFirstOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```
```response title=Response theme={null}
NULL Nullable(UInt8)
```
## arrayFlatten
Добавленный в: v20.1.0
Преобразует массив массивов в плоский массив.
Функция:
* Работает с вложенными массивами любой глубины.
* Не изменяет массивы, которые уже являются плоскими.
Полученный плоский массив содержит все элементы из всех исходных массивов.
**Синтаксис**
```sql theme={null}
arrayFlatten(arr)
```
**Псевдонимы**: `flatten`
**Аргументы**
* `arr` — Многомерный массив. [`Array(Array(T))`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает плоский массив, полученный из многомерного массива [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayFlatten([[[1]], [[2], [3]]]);
```
```response title=Response theme={null}
[1, 2, 3]
```
## arrayFold
Добавленный в: v23.10.0
Применяет лямбда-функцию к одному или нескольким массивам одинаковой длины и накапливает результат в аккумуляторе.
**Синтаксис**
```sql theme={null}
arrayFold(λ(acc, x1 [, x2, x3, ... xN]), arr1 [, arr2, arr3, ... arrN], acc)
```
**Аргументы**
* `λ(x, x1 [, x2, x3, ... xN])` — Лямбда-функция `λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN])`, где `F` — операция, применяемая к `acc` и значениям массива `x`, а затем результат снова используется как `acc`. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr1 [, arr2, arr3, ... arrN]` — N массивов, над которыми выполняется операция. [`Array(T)`](/docs/ru/reference/data-types/array)
* `acc` — Значение аккумулятора того же типа, что и возвращаемое значение лямбда-функции.
**Возвращаемое значение**
Возвращает итоговое значение `acc`.
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayFold(acc,x -> acc + x*2, [1, 2, 3, 4], 3::Int64) AS res;
```
```response title=Response theme={null}
23
```
**Последовательность Фибоначчи**
```sql title=Query theme={null}
SELECT arrayFold(acc, x -> (acc.2, acc.2 + acc.1),range(number),(1::Int64, 0::Int64)).1 AS fibonacci FROM numbers(1,10);
```
```response title=Response theme={null}
┌─fibonacci─┐
│ 0 │
│ 1 │
│ 1 │
│ 2 │
│ 3 │
│ 5 │
│ 8 │
│ 13 │
│ 21 │
│ 34 │
└───────────┘
```
**Пример использования нескольких массивов**
```sql title=Query theme={null}
SELECT arrayFold(
(acc, x, y) -> acc + (x * y),
[1, 2, 3, 4],
[10, 20, 30, 40],
0::Int64
) AS res;
```
```response title=Response theme={null}
300
```
## arrayIntersect
Добавленный в: v1.1.0
Принимает несколько массивов и возвращает массив с элементами, которые присутствуют во всех исходных массивах. Результат содержит только уникальные значения.
**Синтаксис**
```sql theme={null}
arrayIntersect(arr, arr1, ..., arrN)
```
**Аргументы**
* `arrN` — N массивов, из которых составляется новый массив. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает массив с уникальными элементами, присутствующими во всех N массивах [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT
arrayIntersect([1, 2], [1, 3], [2, 3]) AS empty_intersection,
arrayIntersect([1, 2], [1, 3], [1, 4]) AS non_empty_intersection
```
```response title=Response theme={null}
┌─empty_intersection─┬─non_empty_intersection─┐
│ [] │ [1] │
└────────────────────┴────────────────────────┘
```
## arrayJaccardIndex
Добавленный в: v23.7.0
Возвращает [индекс Жаккара](https://en.wikipedia.org/wiki/Jaccard_index) двух массивов.
**Синтаксис**
```sql theme={null}
arrayJaccardIndex(arr_x, arr_y)
```
**Аргументы**
* `arr_x` — Первый массив. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr_y` — Второй массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает индекс Жаккара массивов `arr_x` и `arr_y` [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayJaccardIndex([1, 2], [2, 3]) AS res
```
```response title=Response theme={null}
0.3333333333333333
```
## arrayJoin
Добавленный в: v1.1.0
Функция `arrayJoin` принимает строку, содержащую массив, и разворачивает его, создавая несколько строк — по одной для каждого элемента массива.
Это отличается от обычных функций в ClickHouse, которые сопоставляют входные значения выходным в пределах одной и той же строки,
и агрегатных функций, которые берут группу строк и "сжимают" или "сводят" их в одну итоговую строку
(или в одно значение в итоговой строке, если используются с `GROUP BY`).
Все значения в столбцах просто копируются, за исключением значений в столбце, к которому применяется эта функция;
они заменяются соответствующим значением массива.
Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayJoin(arr)
```
**Псевдонимы**: `unnest`
**Аргументы**
* `arr` — Массив, который нужно развернуть. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает набор строк, полученных при разворачивании `arr`.
**Примеры**
**Базовое использование**
```sql title=Query theme={null}
SELECT arrayJoin([1, 2, 3] AS src) AS dst, 'Hello', src
```
```response title=Response theme={null}
┌─dst─┬─\'Hello\'─┬─src─────┐
│ 1 │ Hello │ [1,2,3] │
│ 2 │ Hello │ [1,2,3] │
│ 3 │ Hello │ [1,2,3] │
└─────┴───────────┴─────────┘
```
**arrayJoin влияет на все части запроса**
```sql title=Query theme={null}
-- The arrayJoin function affects all sections of the query, including the WHERE section. Notice the result 2, even though the subquery returned 1 row.
SELECT sum(1) AS impressions
FROM
(
SELECT ['Istanbul', 'Berlin', 'Bobruisk'] AS cities
)
WHERE arrayJoin(cities) IN ['Istanbul', 'Berlin'];
```
```response title=Response theme={null}
┌─impressions─┐
│ 2 │
└─────────────┘
```
**Использование нескольких вызовов функции arrayJoin**
```sql title=Query theme={null}
-- A query can use multiple arrayJoin functions. In this case, the transformation is performed multiple times and the rows are multiplied.
SELECT
sum(1) AS impressions,
arrayJoin(cities) AS city,
arrayJoin(browsers) AS browser
FROM
(
SELECT
['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
2,
3
ORDER BY
city,
browser
```
```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│ 2 │ Berlin │ Chrome │
│ 1 │ Berlin │ Firefox │
│ 2 │ Bobruisk │ Chrome │
│ 1 │ Bobruisk │ Firefox │
│ 2 │ Istanbul │ Chrome │
│ 1 │ Istanbul │ Firefox │
└─────────────┴──────────┴─────────┘
```
**Неожиданные результаты из-за оптимизации**
```sql title=Query theme={null}
-- Using multiple arrayJoin with the same expression may not produce the expected result due to optimizations.
-- For these cases, consider modifying the repeated array expression with extra operations that do not affect join result.
-- e.g. arrayJoin(arraySort(arr)), arrayJoin(arrayConcat(arr, []))
SELECT
arrayJoin(dice) as first_throw,
/* arrayJoin(dice) as second_throw */ -- is technically correct, but will annihilate result set
arrayJoin(arrayConcat(dice, [])) as second_throw -- intentionally changed expression to force re-evaluation
FROM (
SELECT [1, 2, 3, 4, 5, 6] as dice
);
```
```response title=Response theme={null}
┌─first_throw─┬─second_throw─┐
│ 1 │ 1 │
│ 1 │ 2 │
│ 1 │ 3 │
│ 1 │ 4 │
│ 1 │ 5 │
│ 1 │ 6 │
│ 2 │ 1 │
│ 2 │ 2 │
│ 2 │ 3 │
│ 2 │ 4 │
│ 2 │ 5 │
│ 2 │ 6 │
│ 3 │ 1 │
│ 3 │ 2 │
│ 3 │ 3 │
│ 3 │ 4 │
│ 3 │ 5 │
│ 3 │ 6 │
│ 4 │ 1 │
│ 4 │ 2 │
│ 4 │ 3 │
│ 4 │ 4 │
│ 4 │ 5 │
│ 4 │ 6 │
│ 5 │ 1 │
│ 5 │ 2 │
│ 5 │ 3 │
│ 5 │ 4 │
│ 5 │ 5 │
│ 5 │ 6 │
│ 6 │ 1 │
│ 6 │ 2 │
│ 6 │ 3 │
│ 6 │ 4 │
│ 6 │ 5 │
│ 6 │ 6 │
└─────────────┴──────────────┘
```
**Использование синтаксиса ARRAY JOIN**
```sql title=Query theme={null}
-- Note the ARRAY JOIN syntax in the `SELECT` query below, which provides broader possibilities.
-- ARRAY JOIN allows you to convert multiple arrays with the same number of elements at a time.
SELECT
sum(1) AS impressions,
city,
browser
FROM
(
SELECT
['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
['Firefox', 'Chrome', 'Chrome'] AS browsers
)
ARRAY JOIN
cities AS city,
browsers AS browser
GROUP BY
2,
3
ORDER BY
2,
3
```
```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│ 1 │ Berlin │ Chrome │
│ 1 │ Bobruisk │ Chrome │
│ 1 │ Istanbul │ Firefox │
└─────────────┴──────────┴─────────┘
```
**Использование типа Tuple**
```sql title=Query theme={null}
-- You can also use Tuple
SELECT
sum(1) AS impressions,
(arrayJoin(arrayZip(cities, browsers)) AS t).1 AS city,
t.2 AS browser
FROM
(
SELECT
['Istanbul', 'Berlin', 'Bobruisk'] AS cities,
['Firefox', 'Chrome', 'Chrome'] AS browsers
)
GROUP BY
2,
3
ORDER BY
2,
3
```
```response title=Response theme={null}
┌─impressions─┬─city─────┬─browser─┐
│ 1 │ Berlin │ Chrome │
│ 1 │ Bobruisk │ Chrome │
│ 1 │ Istanbul │ Firefox │
└─────────────┴──────────┴─────────┘
```
## arrayLast
Добавленный в: v1.1.0
Возвращает последний элемент исходного массива, для которого лямбда `func(x [, y1, y2, ... yN])` возвращает true; в противном случае возвращает значение по умолчанию.
**Синтаксис**
```sql theme={null}
arrayLast(func(x[, y1, ..., yN]), source[, cond1, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [Лямбда-функция](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source` — Исходный массив, который нужно обработать. [`Array(T)`](/docs/ru/reference/data-types/array). - `[, cond1, ... , condN]` — Необязательно. N массивов условий, передающих лямбда-функции дополнительные аргументы. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает последний элемент исходного массива, для которого `func` возвращает true; в противном случае возвращает значение по умолчанию для `T`.
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayLast(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])
```
```response title=Response theme={null}
c
```
**Нет совпадений**
```sql title=Query theme={null}
SELECT arrayFirst(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```
```response title=Response theme={null}
0 UInt8
```
## arrayLastIndex
Добавленный в: v1.1.0
Возвращает индекс последнего элемента в исходном массиве, для которого `func(x[, y1, y2, ... yN])` возвращает true; в противном случае возвращает '0'.
**Синтаксис**
```sql theme={null}
arrayLastIndex(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, которая применяется к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, которые передают дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает индекс последнего элемента исходного массива, для которого `func` возвращает true; в противном случае возвращает `0` [`UInt32`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c']);
```
```response title=Response theme={null}
3
```
**Совпадений нет**
```sql title=Query theme={null}
SELECT arrayLastIndex(x, y -> x=y, ['a', 'b', 'c'], ['d', 'e', 'f']);
```
```response title=Response theme={null}
0
```
## arrayLastOrNull
Добавленный в: v1.1.0
Возвращает последний элемент исходного массива, для которого лямбда-функция `func(x [, y1, y2, ... yN])` возвращает `true`; в противном случае возвращает `NULL`.
**Синтаксис**
```sql theme={null}
arrayLastOrNull(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x [, y1, ..., yN])` — лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [Лямбда-функция](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает последний элемент исходного массива, для которого `λ` ложно; в противном случае возвращает `NULL`.
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayLastOrNull(x, y -> x=y, ['a', 'b', 'c'], ['a', 'b', 'c'])
```
```response title=Response theme={null}
c
```
**Совпадений нет**
```sql title=Query theme={null}
SELECT arrayLastOrNull(x, y -> x=y, [0, 1, 2], [3, 3, 3]) AS res, toTypeName(res)
```
```response title=Response theme={null}
NULL Nullable(UInt8)
```
## arrayLevenshteinDistance
Добавленный в: v25.4.0
Вычисляет расстояние Левенштейна между двумя массивами.
**Синтаксис**
```sql theme={null}
arrayLevenshteinDistance(from, to)
```
**Аргументы**
* `from` — Первый массив. [`Array(T)`](/docs/ru/reference/data-types/array). - `to` — Второй массив. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Расстояние Левенштейна между первым и вторым массивами. [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayLevenshteinDistance([1, 2, 4], [1, 2, 3])
```
```response title=Response theme={null}
1
```
## arrayLevenshteinDistanceWeighted
Добавленный в: v25.4.0
Вычисляет расстояние Левенштейна между двумя массивами с пользовательскими весами для каждого элемента.
Количество элементов в массиве и количество соответствующих весов должны совпадать.
**Синтаксис**
```sql theme={null}
arrayLevenshteinDistanceWeighted(from, to, from_weights, to_weights)
```
**Аргументы**
* `from` — первый массив. [`Array(T)`](/docs/ru/reference/data-types/array). - `to` — второй массив. [`Array(T)`](/docs/ru/reference/data-types/array). - `from_weights` — веса первого массива. [`Array((U)Int*|Float*)`](/docs/ru/reference/data-types/array)
* `to_weights` — веса второго массива. [`Array((U)Int*|Float*)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Расстояние Левенштейна между первым и вторым массивами с заданными весами для каждого элемента [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayLevenshteinDistanceWeighted(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5])
```
```response title=Response theme={null}
14
```
## arrayMap
Добавленный в: v1.1.0
Возвращает массив, полученный из исходных массивов путём применения лямбда-функции к каждому элементу.
**Синтаксис**
```sql theme={null}
arrayMap(func, arr)
```
**Аргументы**
* `func` — Лямбда-функция, которая применяется к элементам исходного массива (`x`) и условных массивов (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `arr` — N массивов для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив результатов лямбда-функции [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayMap(x -> (x + 2), [1, 2, 3]) as res;
```
```response title=Response theme={null}
[3, 4, 5]
```
**Создание кортежа из элементов разных массивов**
```sql title=Query theme={null}
SELECT arrayMap((x, y) -> (x, y), [1, 2, 3], [4, 5, 6]) AS res
```
```response title=Response theme={null}
[(1, 4),(2, 5),(3, 6)]
```
## arrayMax
Добавленный в: v21.1.0
Возвращает максимальный элемент исходного массива.
Если указана лямбда-функция `func`, возвращает максимальный элемент среди результатов лямбда-функции.
**Синтаксис**
```sql theme={null}
arrayMax([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Необязательно. Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает максимальный элемент исходного массива или, если указана лямбда-функция, максимальный элемент среди результатов её применения.
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT arrayMax([5, 3, 2, 7]);
```
```response title=Response theme={null}
7
```
**Использование с лямбда-функцией**
```sql title=Query theme={null}
SELECT arrayMax(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);
```
```response title=Response theme={null}
12
```
## arrayMin
Добавленный в: v21.1.0
Возвращает минимальный элемент исходного массива.
Если указана лямбда-функция `func`, возвращает минимальный элемент среди результатов её выполнения.
**Синтаксис**
```sql theme={null}
arrayMin([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Необязательно. Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `cond1_arr, ...` — Необязательно. N массивов условий, передающих в лямбда-функцию дополнительные аргументы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает минимальный элемент исходного массива или, если указана лямбда-функция, минимальный элемент среди её результатов.
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT arrayMin([5, 3, 2, 7]);
```
```response title=Response theme={null}
2
```
**Использование с лямбда-функцией**
```sql title=Query theme={null}
SELECT arrayMin(x, y -> x/y, [4, 8, 12, 16], [1, 2, 1, 2]);
```
```response title=Response theme={null}
4
```
## arrayNormalizedGini
Добавлено в: v25.1.0
Вычисляет нормализованный коэффициент Джини.
**Синтаксис**
```sql theme={null}
arrayNormalizedGini(predicted, label)
```
**Аргументы**
* `predicted` — Предсказанное значение. [`Array(T)`](/docs/ru/reference/data-types/array)
* `label` — Фактическое значение. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Кортеж, содержащий коэффициент Джини для предсказанных значений, коэффициент Джини для нормализованных значений и нормализованный коэффициент Джини (= отношение первых двух коэффициентов Джини) [`Tuple(Float64, Float64, Float64)`](/docs/ru/reference/data-types/tuple)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayNormalizedGini([0.9, 0.3, 0.8, 0.7],[6, 1, 0, 2]);
```
```response title=Response theme={null}
(0.18055555555555558, 0.2638888888888889, 0.6842105263157896)
```
## arrayPartialReverseSort
Добавленный в: v23.2.0
Эта функция аналогична `arrayReverseSort`, но с дополнительным аргументом `limit`, который позволяет выполнять частичную сортировку.
Чтобы сохранить только отсортированные элементы, используйте `arrayResize`.
Эта функция является недетерминированной: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayPartialReverseSort([f,] limit, arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(arr[, arr1, ... ,arrN])` — Лямбда-функция, применяемая к элементам массива `arr`. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — Значение индекса, до которого выполняется сортировка. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
* `arr` — Массив для сортировки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr1, ... ,arrN` — N дополнительных массивов, если `f` принимает несколько аргументов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив того же размера, что и исходный, в котором элементы в диапазоне `[1..limit]` отсортированы
в порядке убывания. Остальные элементы `(limit..N]` находятся в неопределённом порядке.
**Примеры**
**simple\_int**
```sql title=Query theme={null}
SELECT arrayPartialReverseSort(2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[9, 5, 1, 3]
```
**simple\_string**
```sql title=Query theme={null}
SELECT arrayPartialReverseSort(2, ['expenses','lasso','embolism','gladly'])
```
```response title=Response theme={null}
['lasso','gladly','expenses','embolism']
```
**retain\_sorted**
```sql title=Query theme={null}
SELECT arrayResize(arrayPartialReverseSort(2, [5, 9, 1, 3]), 2)
```
```response title=Response theme={null}
[9, 5]
```
**lambda\_simple**
```sql title=Query theme={null}
SELECT arrayPartialReverseSort((x) -> -x, 2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[1, 3, 5, 9]
```
**lambda\_complex**
```sql title=Query theme={null}
SELECT arrayPartialReverseSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res
```
```response title=Response theme={null}
[0, 1, 2]
```
## arrayPartialShuffle
Добавленный в: v23.2.0
Возвращает массив того же размера, что и исходный, где элементы в диапазоне `[1..limit]` представляют собой случайное
подмножество исходного массива. Оставшаяся часть `(limit..n]` содержит элементы, не входящие в диапазон `[1..limit]`, в неопределённом порядке.
Значение `limit` должно находиться в диапазоне `[1..n]`. Значения вне этого диапазона эквивалентны полному `arrayShuffle`:
Эта функция не материализует константы.
Значение `limit` должно находиться в диапазоне `[1..N]`. Значения вне этого диапазона эквивалентны полному [`arrayShuffle`](#arrayShuffle).
Эта функция является недетерминированной: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayPartialShuffle(arr [, limit[, seed]])
```
**Аргументы**
* `arr` — Массив, который нужно перемешать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `seed` — Необязательно. Seed, используемый при генерации случайных чисел. Если не указан, используется случайное значение. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
* `limit` — Необязательно. Число, ограничивающее количество перестановок элементов, в диапазоне `[1..N]`. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Массив с частично перемешанными элементами. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**no\_limit1**
```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 0)
```
```response title=Response theme={null}
[2, 4, 3, 1]
```
**no\_limit2**
```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4])
```
```response title=Response theme={null}
[4, 1, 3, 2]
```
**random\_seed**
```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 2)
```
```response title=Response theme={null}
[3, 4, 1, 2]
```
**explicit\_seed**
```sql title=Query theme={null}
SELECT arrayPartialShuffle([1, 2, 3, 4], 2, 41)
```
```response title=Response theme={null}
[3, 2, 1, 4]
```
**материализовать**
```sql title=Query theme={null}
SELECT arrayPartialShuffle(materialize([1, 2, 3, 4]), 2, 42), arrayPartialShuffle([1, 2, 3], 2, 42) FROM numbers(10)
```
```response title=Response theme={null}
┌─arrayPartial⋯4]), 2, 42)─┬─arrayPartial⋯ 3], 2, 42)─┐
│ [3,2,1,4] │ [3,2,1] │
│ [3,2,1,4] │ [3,2,1] │
│ [4,3,2,1] │ [3,2,1] │
│ [1,4,3,2] │ [3,2,1] │
│ [3,4,1,2] │ [3,2,1] │
│ [1,2,3,4] │ [3,2,1] │
│ [1,4,3,2] │ [3,2,1] │
│ [1,4,3,2] │ [3,2,1] │
│ [3,1,2,4] │ [3,2,1] │
│ [1,3,2,4] │ [3,2,1] │
└──────────────────────────┴──────────────────────────┘
```
## arrayPartialSort
Добавленный в: v23.2.0
Эта функция аналогична `arraySort`, но с дополнительным аргументом `limit`, который позволяет выполнять частичную сортировку.
Чтобы сохранить только отсортированные элементы, используйте `arrayResize`.
Эта функция является недетерминированной: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayPartialSort([f,] limit, arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(arr[, arr1, ... ,arrN])` — Лямбда-функция, применяемая к элементам массива `x`. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — Значение индекса, до которого будет выполняться сортировка. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
* `arr` — Массив, который нужно отсортировать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr1, ... ,arrN` — N дополнительных массивов, если `f` принимает несколько аргументов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив того же размера, что и исходный, в котором элементы в диапазоне `[1..limit]` отсортированы
по возрастанию. Остальные элементы `(limit..N]` находятся в неопределённом порядке.
**Примеры**
**simple\_int**
```sql title=Query theme={null}
SELECT arrayPartialSort(2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[1, 3, 5, 9]
```
**simple\_string**
```sql title=Query theme={null}
SELECT arrayPartialSort(2, ['expenses', 'lasso', 'embolism', 'gladly'])
```
```response title=Response theme={null}
['embolism', 'expenses', 'gladly', 'lasso']
```
**retain\_sorted**
```sql title=Query theme={null}
SELECT arrayResize(arrayPartialSort(2, [5, 9, 1, 3]), 2)
```
```response title=Response theme={null}
[1, 3]
```
**lambda\_simple**
```sql title=Query theme={null}
SELECT arrayPartialSort((x) -> -x, 2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[9, 5, 1, 3]
```
**lambda\_complex**
```sql title=Query theme={null}
SELECT arrayPartialSort((x, y) -> -y, 1, [0, 1, 2], [1, 2, 3]) as res
```
```response title=Response theme={null}
[2, 1, 0]
```
## arrayPopBack
Добавленный в: v1.1.0
Удаляет последний элемент массива.
**Синтаксис**
```sql theme={null}
arrayPopBack(arr)
```
**Аргументы**
* `arr` — Массив, из которого нужно удалить последний элемент. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, совпадающий с `arr`, но без его последнего элемента [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayPopBack([1, 2, 3]) AS res;
```
```response title=Response theme={null}
[1, 2]
```
## arrayPopFront
Добавленный в: v1.1.0
Удаляет первый элемент массива.
**Синтаксис**
```sql theme={null}
arrayPopFront(arr)
```
**Аргументы**
* `arr` — массив, из которого нужно удалить первый элемент. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, идентичный `arr`, но без его первого элемента [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayPopFront([1, 2, 3]) AS res;
```
```response title=Response theme={null}
[2, 3]
```
## arrayProduct
Добавленный в: v21.1.0
Возвращает произведение элементов исходного массива.
Если указана лямбда-функция `func`, возвращает произведение результатов лямбда-функции для элементов массива.
**Синтаксис**
```sql theme={null}
arrayProduct([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Необязательно. Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает произведение элементов исходного массива или, если указана лямбда-функция, произведение результатов её применения к элементам. [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT arrayProduct([1, 2, 3, 4]);
```
```response title=Response theme={null}
24
```
**Использование с лямбда-функцией**
```sql title=Query theme={null}
SELECT arrayProduct(x, y -> x+y, [2, 2], [2, 2]) AS res;
```
```response title=Response theme={null}
16
```
## arrayPushBack
Добавленный в: v1.1.0
Добавляет один элемент в конец массива.
**Синтаксис**
```sql theme={null}
arrayPushBack(arr, x)
```
**Аргументы**
* `arr` — Массив, в конец которого добавляется значение `x`. [`Array(T)`](/docs/ru/reference/data-types/array)
* `x` —
* Одно значение, добавляемое в конец массива. [`Array(T)`](/docs/ru/reference/data-types/array).
- В массив чисел можно добавлять только числа, а в массив строк — только строки.
- При добавлении чисел ClickHouse автоматически приводит тип `x` к типу данных массива.
- Может быть `NULL`. Функция добавляет в массив элемент `NULL`, а тип элементов массива преобразуется в `Nullable`.
Дополнительные сведения о типах данных в ClickHouse см. в разделе [Типы данных](/docs/ru/reference/data-types/index).
**Возвращаемое значение**
Возвращает массив, идентичный `arr`, но с дополнительным значением `x` в конце [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayPushBack(['a'], 'b') AS res;
```
```response title=Response theme={null}
['a','b']
```
## arrayPushFront
Добавленный в: v1.1.0
Добавляет один элемент в начало массива.
**Синтаксис**
```sql theme={null}
arrayPushFront(arr, x)
```
**Аргументы**
* `arr` — Массив, в конец которого добавляется значение `x`. [`Array(T)`](/docs/ru/reference/data-types/array). - `x` —
* Одно значение, добавляемое в начало массива. [`Array(T)`](/docs/ru/reference/data-types/array).
- В массив чисел можно добавлять только числа, а в массив строк — только строки.
- При добавлении чисел ClickHouse автоматически приводит тип `x` к типу данных массива.
- Может быть `NULL`. Функция добавляет в массив элемент `NULL`, а тип элементов массива преобразуется в `Nullable`.
Дополнительные сведения о типах данных в ClickHouse см. в разделе [Типы данных](/docs/ru/reference/data-types/index).
**Возвращаемое значение**
Возвращает массив, идентичный `arr`, но с дополнительным значением `x` в начале массива [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayPushFront(['b'], 'a') AS res;
```
```response title=Response theme={null}
['a','b']
```
## arrayROCAUC
Добавленный в: v20.4.0
Вычисляет площадь под ROC-кривой (receiver operating characteristic).
ROC-кривая строится путём откладывания True Positive Rate (TPR) по оси y и False Positive Rate (FPR) по оси x для всех порогов.
Итоговое значение находится в диапазоне от нуля до единицы; чем оно выше, тем лучше качество модели.
ROC AUC (также известная просто как AUC) — это понятие из области машинного обучения.
Подробнее см. [здесь](https://developers.google.com/machine-learning/glossary#pr-auc-area-under-the-pr-curve), [здесь](https://developers.google.com/machine-learning/crash-course/classification/roc-and-auc#expandable-1) и [здесь](https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve).
**Синтаксис**
```sql theme={null}
arrayROCAUC(scores, labels[, scale[, partial_offsets]])
```
**Псевдонимы**: `arrayAUC`
**Аргументы**
* `scores` — Оценки, которые выдаёт модель. [`Array((U)Int*)`](/docs/ru/reference/data-types/array) или [`Array(Float*)`](/docs/ru/reference/data-types/array)
* `labels` — Метки объектов, обычно 1 для положительного примера и 0 для отрицательного. [`Array((U)Int*)`](/docs/ru/reference/data-types/array) или [`Enum`](/docs/ru/reference/data-types/enum)
* `scale` — Необязательно. Определяет, нужно ли возвращать нормализованную площадь. Если false, вместо этого возвращается площадь под кривой TP (true positives) x FP (false positives). Значение по умолчанию: true. [`Bool`](/docs/ru/reference/data-types/boolean)
* `partial_offsets` —
* Массив из четырёх неотрицательных целых чисел для вычисления частичной площади под ROC-кривой (эквивалентной вертикальной полосе в пространстве ROC) вместо полного AUC. Эта опция полезна для распределённого вычисления ROC AUC. Массив должен содержать следующие элементы \[`higher_partitions_tp`, `higher_partitions_fp`, `total_positives`, `total_negatives`]. [Array](/docs/ru/reference/data-types/array) из неотрицательных [Integers](/docs/ru/reference/data-types/int-uint). Необязательно.
* `higher_partitions_tp`: Количество положительных меток в партициях с более высокими оценками.
* `higher_partitions_fp`: Количество отрицательных меток в партициях с более высокими оценками.
* `total_positives`: Общее количество положительных примеров во всём наборе данных.
* `total_negatives`: Общее количество отрицательных примеров во всём наборе данных.
Когда используется `arr_partial_offsets`, `arr_scores` и `arr_labels` должны представлять только одну партицию всего набора данных, содержащую некоторый диапазон оценок.
Набор данных следует разделить на непрерывные партиции, где каждая партиция содержит подмножество данных, оценки которых попадают в определённый диапазон.
Например:
* Одна партиция может содержать все оценки в диапазоне \[0, 0.5).
* Другая партиция может содержать оценки в диапазоне \[0.5, 1.0].
**Возвращаемое значение**
Возвращает площадь под ROC-кривой (receiver operating characteristic). [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayROCAUC([0.1, 0.4, 0.35, 0.8], [0, 0, 1, 1]);
```
```response title=Response theme={null}
0.75
```
## arrayRandomSample
Добавленный в: v23.10.0
Возвращает подмножество из `samples` случайно выбранных элементов входного массива. Если `samples` превышает размер входного массива, размер выборки ограничивается размером массива, то есть возвращаются все элементы массива, но их порядок не гарантируется. Функция поддерживает как плоские, так и вложенные массивы.
Эта функция недетерминирована: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayRandomSample(arr, samples)
```
**Аргументы**
* `arr` — Входной массив или многомерный массив, из которого производится выборка элементов. [`Array(T)`](/docs/ru/reference/data-types/array)
* `samples` — Количество элементов, которые нужно включить в случайную выборку. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Массив, содержащий случайную выборку элементов из входного массива [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayRandomSample(['apple', 'banana', 'cherry', 'date'], 2) as res;
```
```response title=Response theme={null}
['cherry','apple']
```
**Использование многомерного массива**
```sql title=Query theme={null}
SELECT arrayRandomSample([[1, 2], [3, 4], [5, 6]], 2) as res;
```
```response title=Response theme={null}
[[3,4],[5,6]]
```
## arrayReduce
Добавленный в: v1.1.0
Применяет агрегатную функцию к элементам массива и возвращает результат.
Имя агрегатной функции передаётся в виде строки в одинарных кавычках: `'max'`, `'sum'`.
При использовании параметрических агрегатных функций параметр указывается после имени функции в круглых скобках: `'uniqUpTo(6)'`.
**Синтаксис**
```sql theme={null}
arrayReduce(agg_f, arr1[, arr2, ... , arrN])
```
**Аргументы**
* `agg_f` — имя агрегатной функции; должно быть константой. [`String`](/docs/ru/reference/data-types/string)
* `arr1[, arr2, ... , arrN]` — N массивов, соответствующих аргументам `agg_f`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Результат агрегатной функции
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayReduce('max', [1, 2, 3]);
```
```response title=Response theme={null}
┌─arrayReduce('max', [1, 2, 3])─┐
│ 3 │
└───────────────────────────────┘
```
**Пример агрегатной функции с несколькими аргументами**
```sql title=Query theme={null}
--Если агрегатная функция принимает несколько аргументов, она должна применяться к нескольким массивам одинакового размера.
SELECT arrayReduce('maxIf', [3, 5], [1, 0]);
```
```response title=Response theme={null}
┌─arrayReduce('maxIf', [3, 5], [1, 0])─┐
│ 3 │
└──────────────────────────────────────┘
```
**Пример с параметрической агрегатной функцией**
```sql title=Query theme={null}
SELECT arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
```
```response title=Response theme={null}
┌─arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])─┐
│ 4 │
└─────────────────────────────────────────────────────────────┘
```
## arrayReduceInRanges
Добавленный в: v20.4.0
Применяет агрегатную функцию к элементам массива в заданных диапазонах и возвращает массив с результатом для каждого диапазона.
Функция вернёт тот же результат, что и несколько вызовов `arrayReduce(agg_func, arraySlice(arr1, index, length), ...)`.
**Синтаксис**
```sql theme={null}
arrayReduceInRanges(agg_f, ranges, arr1[, arr2, ... ,arrN])
```
**Аргументы**
* `agg_f` — Имя используемой агрегатной функции. [`String`](/docs/ru/reference/data-types/string)
* `ranges` — Диапазон, по которому выполняется агрегирование. Массив кортежей `(i, r)`, содержащих индекс `i`, с которого следует начинать, и диапазон `r`, по которому выполняется агрегирование. [`Array(T)`](/docs/ru/reference/data-types/array) или [`Tuple(T)`](/docs/ru/reference/data-types/tuple)
* `arr1[, arr2, ... ,arrN]` — N массивов в качестве аргументов агрегатной функции. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, содержащий результаты агрегатной функции по указанным диапазонам [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayReduceInRanges(
'sum',
[(1, 5), (2, 3), (3, 4), (4, 4)],
[1000000, 200000, 30000, 4000, 500, 60, 7]
) AS res
```
```response title=Response theme={null}
┌─res─────────────────────────┐
│ [1234500,234000,34560,4567] │
└─────────────────────────────┘
```
## arrayRemove
Добавленный в: v25.11.0
Удаляет из массива все элементы, равные указанному значению.
NULL считается равным NULL.
**Синтаксис**
```sql theme={null}
arrayRemove(arr, elem)
```
**Псевдонимы**: `array_remove`
**Аргументы**
* `arr` — Array(T) - `elem` — T
**Возвращаемое значение**
Возвращает часть исходного массива [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример 1**
```sql title=Query theme={null}
SELECT arrayRemove([1, 2, 2, 3], 2)
```
```response title=Response theme={null}
[1, 3]
```
**Пример 2**
```sql title=Query theme={null}
SELECT arrayRemove(['a', NULL, 'b', NULL], NULL)
```
```response title=Response theme={null}
['a', 'b']
```
## arrayResize
Добавлено в: v1.1.0
Изменяет длину массива.
**Синтаксис**
```sql theme={null}
arrayResize(arr, size[, extender])
```
**Аргументы**
* `arr` — Массив, размер которого нужно изменить. [`Array(T)`](/docs/ru/reference/data-types/array)
* `size` —
-Новая длина массива.
Если `size` меньше исходного размера массива, массив обрезается справа.
Если `size` больше исходного размера массива, массив расширяется вправо значениями `extender` или значениями по умолчанию для типа данных элементов массива.
* `extender` — Значение, используемое для расширения массива. Может быть `NULL`.
**Возвращаемое значение**
Массив длиной `size`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример 1**
```sql title=Query theme={null}
SELECT arrayResize([1], 3);
```
```response title=Response theme={null}
[1,0,0]
```
**Пример 2**
```sql title=Query theme={null}
SELECT arrayResize([1], 3, NULL);
```
```response title=Response theme={null}
[1,NULL,NULL]
```
## arrayReverse
Добавленный в: v1.1.0
Изменяет порядок элементов заданного массива на обратный.
Функция `reverse(arr)` выполняет ту же операцию, но работает и с другими типами данных
помимо массивов.
**Синтаксис**
```sql theme={null}
arrayReverse(arr)
```
**Аргументы**
* `arr` — Массив, который нужно развернуть. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив того же размера, что и исходный, с элементами в обратном порядке [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayReverse([1, 2, 3])
```
```response title=Response theme={null}
[3,2,1]
```
## arrayReverseFill
Добавленный в: v20.1.0
Функция `arrayReverseFill` последовательно обрабатывает исходный массив от последнего
элемента к первому, вычисляя в каждой позиции лямбда-условие с использованием элементов
из исходного массива и массивов условий. Если в позиции i условие принимает значение false,
функция заменяет этот элемент элементом из позиции i+1
в текущем состоянии массива. Последний элемент всегда сохраняется
независимо от условия.
**Синтаксис**
```sql theme={null}
arrayReverseFill(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и условных массивов (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N условных массивов, передающих дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив, в котором элементы исходного массива заменены результатами лямбда-функции. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример с одним массивом**
```sql title=Query theme={null}
SELECT arrayReverseFill(x -> not isNull(x), [1, null, 2, null]) AS res
```
```response title=Response theme={null}
[1, 2, 2, NULL]
```
**Пример с двумя массивами**
```sql title=Query theme={null}
SELECT arrayReverseFill(x, y, z -> x > y AND x < z, [5, 3, 6, 2], [4, 7, 1, 3], [10, 2, 8, 5]) AS res;
```
```response title=Response theme={null}
[5, 6, 6, 2]
```
## arrayReverseSort
Добавленный в: v1.1.0
Сортирует элементы массива по убыванию.
Если указана функция `f`, переданный массив сортируется по результату
применения этой функции к элементам массива, а затем отсортированный массив переворачивается.
Если `f` принимает несколько аргументов, в функцию `arrayReverseSort` передаётся несколько массивов,
аргументам `func` будут соответствовать их элементы.
Если сортируемый массив содержит `-Inf`, `NULL`, `NaN` или `Inf`, они будут отсортированы в следующем порядке:
1. `-Inf`
2. `Inf`
3. `NaN`
4. `NULL`
`arrayReverseSort` — это [функция высшего порядка](/docs/ru/reference/functions/regular-functions/overview#higher-order-functions).
**Синтаксис**
```sql theme={null}
arrayReverseSort([f,] arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(y1[, y2 ... yN])` — лямбда-функция, применяемая к элементам массива `x`. - `arr` — массив, который нужно отсортировать. [`Array(T)`](/docs/ru/reference/data-types/array) - `arr1, ..., arrN` — необязательно. N дополнительных массивов, если `f` принимает несколько аргументов.
**Возвращаемое значение**
Возвращает массив `x`, отсортированный по убыванию, если лямбда-функция не указана; в противном случае
возвращает массив, отсортированный в соответствии с логикой переданной лямбда-функции, а затем перевёрнутый. [`Array(T)`](/docs/ru/reference/data-types/array).
**Примеры**
**Пример 1**
```sql title=Query theme={null}
SELECT arrayReverseSort((x, y) -> y, [4, 3, 5], ['a', 'b', 'c']) AS res;
```
```response title=Response theme={null}
[5,3,4]
```
**Пример 2**
```sql title=Query theme={null}
SELECT arrayReverseSort((x, y) -> -y, [4, 3, 5], [1, 2, 3]) AS res;
```
```response title=Response theme={null}
[4,3,5]
```
## arrayReverseSplit
Добавленный в: v20.1.0
Разбивает исходный массив на несколько массивов. Когда `func(x[, y1, ..., yN])` возвращает значение, отличное от нуля, массив разбивается справа от элемента. После последнего элемента массив не разбивается.
**Синтаксис**
```sql theme={null}
arrayReverseSplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `[, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, предоставляющих лямбда-функции дополнительные аргументы. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив массивов. [`Array(Array(T))`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayReverseSplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res
```
```response title=Response theme={null}
[[1], [2, 3, 4], [5]]
```
## arrayRotateLeft
Добавленный в: v23.8.0
Циклически сдвигает массив влево на указанное число элементов. Отрицательные значения `n` интерпретируются как циклический сдвиг вправо на абсолютную величину сдвига.
**Синтаксис**
```sql theme={null}
arrayRotateLeft(arr, n)
```
**Аргументы**
* `arr` — Массив, элементы которого нужно циклически сдвинуть.[`Array(T)`](/docs/ru/reference/data-types/array). - `n` — Количество элементов для циклического сдвига. [`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint).
**Возвращаемое значение**
Массив, циклически сдвинутый влево на указанное число элементов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayRotateLeft([1,2,3,4,5,6], 2) as res;
```
```response title=Response theme={null}
[3,4,5,6,1,2]
```
**Отрицательное значение n**
```sql title=Query theme={null}
SELECT arrayRotateLeft([1,2,3,4,5,6], -2) as res;
```
```response title=Response theme={null}
[5,6,1,2,3,4]
```
## arrayRotateRight
Добавленный в: v23.8.0
Циклически сдвигает массив вправо на указанное число элементов. Отрицательные значения `n` трактуются как циклический сдвиг влево на абсолютную величину сдвига.
**Синтаксис**
```sql theme={null}
arrayRotateRight(arr, n)
```
**Аргументы**
* `arr` — Массив, элементы которого нужно циклически сдвинуть.[`Array(T)`](/docs/ru/reference/data-types/array). - `n` — Количество элементов, на которое выполняется циклический сдвиг. [`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint).
**Возвращаемое значение**
Массив, циклически сдвинутый вправо на указанное количество элементов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayRotateRight([1,2,3,4,5,6], 2) as res;
```
```response title=Response theme={null}
[5,6,1,2,3,4]
```
**Отрицательное значение n**
```sql title=Query theme={null}
SELECT arrayRotateRight([1,2,3,4,5,6], -2) as res;
```
```response title=Response theme={null}
[3,4,5,6,1,2]
```
## arrayShiftLeft
Добавленный в: v23.8.0
Сдвигает массив влево на указанное количество элементов.
Новые элементы заполняются указанным аргументом или значением по умолчанию для типа элементов массива.
Если количество элементов отрицательное, массив сдвигается вправо.
**Синтаксис**
```sql theme={null}
arrayShiftLeft(arr, n[, default])
```
**Аргументы**
* `arr` — Массив, элементы которого нужно сдвинуть.[`Array(T)`](/docs/ru/reference/data-types/array). - `n` — Количество элементов, на которое нужно выполнить сдвиг.[`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint). - `default` — Необязательно. Значение по умолчанию для новых элементов.
**Возвращаемое значение**
Массив, сдвинутый влево на указанное количество элементов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], 2) as res;
```
```response title=Response theme={null}
[3,4,5,6,0,0]
```
**Отрицательное значение параметра n**
```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], -2) as res;
```
```response title=Response theme={null}
[0,0,1,2,3,4]
```
**Использование значения по умолчанию**
```sql title=Query theme={null}
SELECT arrayShiftLeft([1,2,3,4,5,6], 2, 42) as res;
```
```response title=Response theme={null}
[3,4,5,6,42,42]
```
## arrayShiftRight
Добавленный в: v23.8.0
Сдвигает массив вправо на указанное количество элементов.
Новые элементы заполняются переданным аргументом или значением по умолчанию для типа элементов массива.
Если количество элементов отрицательное, массив сдвигается влево.
**Синтаксис**
```sql theme={null}
arrayShiftRight(arr, n[, default])
```
**Аргументы**
* `arr` — Массив, элементы которого нужно сдвинуть. [`Array(T)`](/docs/ru/reference/data-types/array)
* `n` — Количество элементов, на которое нужно выполнить сдвиг. [`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint)
* `default` — Необязательно. Значение по умолчанию для новых элементов.
**Возвращаемое значение**
Массив, сдвинутый вправо на указанное количество элементов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2) as res;
```
```response title=Response theme={null}
[0, 0, 1, 2, 3, 4]
```
**Отрицательное значение n**
```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], -2) as res;
```
```response title=Response theme={null}
[3, 4, 5, 6, 0, 0]
```
**Использование значения по умолчанию**
```sql title=Query theme={null}
SELECT arrayShiftRight([1, 2, 3, 4, 5, 6], 2, 42) as res;
```
```response title=Response theme={null}
[42, 42, 1, 2, 3, 4]
```
## arrayShingles
Добавленный в: v24.1.0
Генерирует массив шинглов (по аналогии с n-граммами для строк), то есть последовательность подмассивов заданной длины из входного массива.
**Синтаксис**
```sql theme={null}
arrayShingles(arr, l)
```
**Аргументы**
* `arr` — массив, для которого нужно сгенерировать массив шинглов. [`Array(T)`](/docs/ru/reference/data-types/array)
* `l` — длина каждого шингла. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Массив сгенерированных шинглов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayShingles([1, 2, 3, 4], 3) as res;
```
```response title=Response theme={null}
[[1, 2, 3], [2, 3, 4]]
```
## arrayShuffle
Добавленный в: v23.2.0
Возвращает массив того же размера, что и исходный, с элементами в случайном порядке.
Элементы переупорядочиваются так, что каждая возможная их перестановка появляется с одинаковой вероятностью.
Эта функция не материализует константы.
Эта функция является недетерминированной: она может возвращать разные результаты для одних и тех же аргументов.
**Синтаксис**
```sql theme={null}
arrayShuffle(arr [, seed])
```
**Аргументы**
* `arr` — Массив, который нужно перемешать. [`Array(T)`](/docs/ru/reference/data-types/array)
* `seed (optional)` — Необязательно. Значение seed, используемое для генерации случайных чисел. Если не указано, используется случайное значение. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Массив с перемешанными элементами [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример без seed (нестабильные результаты)**
```sql title=Query theme={null}
SELECT arrayShuffle([1, 2, 3, 4]);
```
```response title=Response theme={null}
[1,4,2,3]
```
**Пример без seed (устойчивые результаты)**
```sql title=Query theme={null}
SELECT arrayShuffle([1, 2, 3, 4], 41);
```
```response title=Response theme={null}
[3,2,1,4]
```
## arraySimilarity
Добавленный в: v25.4.0
Вычисляет степень сходства двух массивов в диапазоне от `0` до `1` на основе взвешенного расстояния Левенштейна.
**Синтаксис**
```sql theme={null}
arraySimilarity(from, to, from_weights, to_weights)
```
**Аргументы**
* `from` — первый массив [`Array(T)`](/docs/ru/reference/data-types/array)
* `to` — второй массив [`Array(T)`](/docs/ru/reference/data-types/array)
* `from_weights` — веса первого массива. [`Array((U)Int*|Float*)`](/docs/ru/reference/data-types/array)
* `to_weights` — веса второго массива. [`Array((U)Int*|Float*)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает значение сходства двух массивов в диапазоне от `0` до `1`, вычисленное на основе взвешенного расстояния Левенштейна [`Float64`](/docs/ru/reference/data-types/float)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arraySimilarity(['A', 'B', 'C'], ['A', 'K', 'L'], [1.0, 2, 3], [3.0, 4, 5]);
```
```response title=Response theme={null}
0.2222222222222222
```
## arraySlice
Добавленный в: v1.1.0
Возвращает срез массива, включая элементы со значением `NULL`.
**Синтаксис**
```sql theme={null}
arraySlice(arr, offset [, length])
```
**Аргументы**
* `arr` — Массив, из которого берётся срез. [`Array(T)`](/docs/ru/reference/data-types/array)
* `offset` — Отступ от края массива. Положительное значение указывает на смещение слева, а отрицательное — на отступ справа. Нумерация элементов массива начинается с `1`. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
* `length` — Длина требуемого среза. Если указать отрицательное значение, функция возвращает открытый срез `[offset, array_length - length]`. Если не указывать это значение, функция возвращает срез `[offset, the_end_of_array]`. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает срез массива длиной `length` элементов, начиная с указанного `offset` [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arraySlice([1, 2, NULL, 4, 5], 2, 3) AS res;
```
```response title=Response theme={null}
[2, NULL, 4]
```
## arraySort
Добавленный в: v1.1.0
Сортирует элементы переданного массива по возрастанию.
Если указана лямбда-функция `f`, порядок сортировки определяется результатом
применения этой функции к каждому элементу массива.
Если лямбда-функция принимает несколько аргументов, в `arraySort` передаётся несколько
массивов, аргументам `f` будут соответствовать их элементы.
Если сортируемый массив содержит `-Inf`, `NULL`, `NaN` или `Inf`, они будут отсортированы в следующем порядке:
1. `-Inf`
2. `Inf`
3. `NaN`
4. `NULL`
`arraySort` — это [функция высшего порядка](/docs/ru/reference/functions/regular-functions/overview#higher-order-functions).
**Синтаксис**
```sql theme={null}
arraySort([f,] arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(y1[, y2 ... yN])` — лямбда-функция, применяемая к элементам массива `x`. - `arr` — массив, который необходимо отсортировать. [`Array(T)`](/docs/ru/reference/data-types/array) - `arr1, ..., arrN` — Необязательно. N дополнительных массивов, если `f` принимает несколько аргументов.
**Возвращаемое значение**
Возвращает массив `arr`, отсортированный по возрастанию, если лямбда-функция не указана; в противном случае
возвращает массив, отсортированный в соответствии с логикой указанной лямбда-функции. [`Array(T)`](/docs/ru/reference/data-types/array).
**Примеры**
**Пример 1**
```sql title=Query theme={null}
SELECT arraySort([1, 3, 3, 0]);
```
```response title=Response theme={null}
[0,1,3,3]
```
**Пример 2**
```sql title=Query theme={null}
SELECT arraySort(['hello', 'world', '!']);
```
```response title=Response theme={null}
['!','hello','world']
```
**Пример 3**
```sql title=Query theme={null}
SELECT arraySort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf]);
```
```response title=Response theme={null}
[-inf,-4,1,2,3,inf,nan,nan,NULL,NULL]
```
## arraySplit
Добавленный в: v20.1.0
Разбивает исходный массив на несколько массивов. Если `func(x [, y1, ..., yN])` возвращает значение, отличное от нуля, массив будет разделён слева от этого элемента. Массив не разделяется перед первым элементом.
**Синтаксис**
```sql theme={null}
arraySplit(func(x[, y1, ..., yN]), source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Лямбда-функция, применяемая к элементам исходного массива (`x`) и условных массивов (`y`). [Лямбда-функция](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda). - `source_arr` — Исходный массив, который нужно разбить [`Array(T)`](/docs/ru/reference/data-types/array). - `[, cond1_arr, ... , condN_arr]` — Необязательно. N условных массивов, передающих лямбда-функции дополнительные аргументы. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает массив массивов [`Array(Array(T))`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arraySplit((x, y) -> y, [1, 2, 3, 4, 5], [1, 0, 0, 1, 0]) AS res
```
```response title=Response theme={null}
[[1, 2, 3], [4, 5]]
```
## arraySum
Добавленный в: v21.1.0
Возвращает сумму элементов исходного массива.
Если указана лямбда-функция `func`, возвращает сумму элементов, полученных в результате её применения.
**Синтаксис**
```sql theme={null}
arraySum([func(x[, y1, ..., yN])], source_arr[, cond1_arr, ... , condN_arr])
```
**Аргументы**
* `func(x[, y1, ..., yN])` — Необязательно. Лямбда-функция, применяемая к элементам исходного массива (`x`) и массивов условий (`y`). [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `source_arr` — Исходный массив для обработки. [`Array(T)`](/docs/ru/reference/data-types/array)
* `, cond1_arr, ... , condN_arr]` — Необязательно. N массивов условий, которые передают дополнительные аргументы в лямбда-функцию. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает сумму элементов исходного массива или, если указана лямбда-функция, сумму элементов результатов её применения.
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT arraySum([1, 2, 3, 4]);
```
```response title=Response theme={null}
10
```
**Использование с лямбда-функцией**
```sql title=Query theme={null}
SELECT arraySum(x, y -> x+y, [1, 1, 1, 1], [1, 1, 1, 1]);
```
```response title=Response theme={null}
8
```
## arraySymmetricDifference
Добавленный в: v25.4.0
Принимает несколько массивов и возвращает массив с элементами, которые содержатся не во всех исходных массивах. Результат содержит только уникальные значения.
Симметрическая разность *более чем двух множеств* [математически определяется](https://en.wikipedia.org/wiki/Symmetric_difference#n-ary_symmetric_difference)
как множество всех входных элементов, которые встречаются в нечётном числе входных множеств.
В отличие от этого, функция `arraySymmetricDifference` просто возвращает множество входных элементов, которые содержатся не во всех входных множествах.
**Синтаксис**
```sql theme={null}
arraySymmetricDifference(arr1, arr2, ... , arrN)
```
**Аргументы**
* `arrN` — N массивов, из которых создаётся новый массив. [`Array(T)`](/docs/ru/reference/data-types/array).
**Возвращаемое значение**
Возвращает массив различных элементов, которые присутствуют не во всех исходных массивах [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT
arraySymmetricDifference([1, 2], [1, 2], [1, 2]) AS empty_symmetric_difference,
arraySymmetricDifference([1, 2], [1, 2], [1, 3]) AS non_empty_symmetric_difference;
```
```response title=Response theme={null}
┌─empty_symmetric_difference─┬─non_empty_symmetric_difference─┐
│ [] │ [3,2] │
└────────────────────────────┴────────────────────────────────┘
```
## arrayTopK
Добавленный в: v26.6.0
Возвращает массив из K наибольших элементов входного массива, отсортированных по убыванию.
Если указана `лямбда-функция` `f`, элементы сравниваются по результату применения `f` к каждому элементу.
Если `f` принимает несколько аргументов, в `arrayTopK` передаются дополнительные массивы; их элементы
соответствуют аргументам `f`.
Значения `NULL` пропускаются и не включаются в результат. Размер результата не превышает `K`
и может быть меньше, если входной массив содержит менее `K` значений, отличных от `NULL`.
Тип элементов результата — соответствующий тип элементов входного массива без `Nullable`.
`arrayTopK` — это [функция высшего порядка](/docs/ru/reference/functions/regular-functions/overview#higher-order-functions).
См. также `arrayBottomK`, которая возвращает K наименьших элементов.
**Синтаксис**
```sql theme={null}
arrayTopK([f,] K, arr [, arr1, ... ,arrN])
```
**Аргументы**
* `f(arr[, arr1, ... ,arrN])` — Необязательно. Лямбда-функция для вычисления ключа сортировки для каждого элемента. [`Лямбда-функция`](/docs/ru/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `K` — Количество наибольших элементов, которые нужно вернуть. [`(U)Int8/16/32/64`](/docs/ru/reference/data-types/int-uint)
* `arr` — Массив. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr1, ... ,arrN` — N дополнительных массивов, если `f` принимает несколько аргументов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает до `K` элементов массива `arr` с наибольшими значениями (или наибольшими результатами лямбда-функции), отсортированных по убыванию.
NULL-значения пропускаются. Возвращаемый массив имеет тип элементов `T`, даже если входной массив имеет тип `Nullable(T)`.
**Примеры**
**simple\_int**
```sql title=Query theme={null}
SELECT arrayTopK(3, [1, 5, 2, 7, 3])
```
```response title=Response theme={null}
[7,5,3]
```
**skip\_nulls**
```sql title=Query theme={null}
SELECT arrayTopK(3, [1, NULL, 5, 2, NULL, 7])
```
```response title=Response theme={null}
[7,5,2]
```
**fewer\_than\_k**
```sql title=Query theme={null}
SELECT arrayTopK(5, [1, NULL, 2])
```
```response title=Response theme={null}
[2,1]
```
**lambda\_simple**
```sql title=Query theme={null}
SELECT arrayTopK((x) -> -x, 2, [5, 9, 1, 3])
```
```response title=Response theme={null}
[1,3]
```
**lambda\_multi**
```sql title=Query theme={null}
SELECT arrayTopK((x, y) -> y, 2, ['a', 'b', 'c'], [3, 1, 2])
```
```response title=Response theme={null}
['a','c']
```
## arrayTranspose
Добавленный в: v26.4.0
Транспонирует двумерный массив.
Все вложенные массивы должны иметь одинаковую длину.
**Синтаксис**
```sql theme={null}
arrayTranspose(arr)
```
**Аргументы**
* `arr` — двумерный массив для транспонирования. Все внутренние массивы должны иметь одинаковую длину. [`Array(Array(T))`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Транспонированный двумерный массив, в котором элемент `[i][j]` результата равен элементу `[j][i]` исходного массива. [`Array(Array(T))`](/docs/ru/reference/data-types/array)
**Примеры**
**Квадратная матрица**
```sql title=Query theme={null}
SELECT arrayTranspose([[1, 2], [3, 4]])
```
```response title=Response theme={null}
[[1, 3], [2, 4]]
```
**Неквадратная матрица**
```sql title=Query theme={null}
SELECT arrayTranspose([[1, 2, 3], [4, 5, 6]])
```
```response title=Response theme={null}
[[1, 4], [2, 5], [3, 6]]
```
**Строковые элементы**
```sql title=Query theme={null}
SELECT arrayTranspose([['a', 'b'], ['c', 'd']])
```
```response title=Response theme={null}
[['a', 'c'], ['b', 'd']]
```
## arrayUnion
Добавленный в: v24.10.0
Принимает несколько массивов и возвращает массив, содержащий все элементы, которые присутствуют хотя бы в одном из исходных массивов. Результат содержит только уникальные значения.
**Синтаксис**
```sql theme={null}
arrayUnion(arr1, arr2, ..., arrN)
```
**Аргументы**
* `arrN` — N массивов, из которых создаётся новый массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив с уникальными элементами из исходных массивов [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT
arrayUnion([-2, 1], [10, 1], [-2], []) as num_example,
arrayUnion(['hi'], [], ['hello', 'hi']) as str_example,
arrayUnion([1, 3, NULL], [2, 3, NULL]) as null_example
```
```response title=Response theme={null}
┌─num_example─┬─str_example────┬─null_example─┐
│ [10,-2,1] │ ['hello','hi'] │ [3,2,1,NULL] │
└─────────────┴────────────────┴──────────────┘
```
## arrayUniq
Добавленный в: v1.1.0
При передаче одного аргумента подсчитывает количество различных элементов в массиве.
При передаче нескольких аргументов подсчитывает количество различных **кортежей**, составленных из элементов, находящихся на соответствующих позициях в нескольких массивах.
Например, `SELECT arrayUniq([1,2], [3,4], [5,6])` сформирует следующие кортежи:
* Позиция 1: (1,3,5)
* Позиция 2: (2,4,6)
Затем будет подсчитано количество уникальных кортежей. В данном случае это `2`.
Все переданные массивы должны иметь одинаковую длину.
Если вы хотите получить список уникальных элементов массива, можно использовать `arrayReduce('groupUniqArray', arr)`.
**Синтаксис**
```sql theme={null}
arrayUniq(arr1[, arr2, ..., arrN])
```
**Аргументы**
* `arr1` — Массив, для которого подсчитывается количество уникальных элементов. [`Array(T)`](/docs/ru/reference/data-types/array)
* `[, arr2, ..., arrN]` — Необязательно. Дополнительные массивы, используемые для подсчета количества уникальных кортежей из элементов, находящихся на соответствующих позициях в нескольких массивах. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Для одного аргумента возвращает количество уникальных
элементов. Для нескольких аргументов возвращает количество уникальных кортежей, составленных из
элементов, находящихся на соответствующих позициях в массивах.
[`UInt32`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Один аргумент**
```sql title=Query theme={null}
SELECT arrayUniq([1, 1, 2, 2])
```
```response title=Response theme={null}
2
```
**Несколько аргументов**
```sql title=Query theme={null}
SELECT arrayUniq([1, 2, 3, 1], [4, 5, 6, 4])
```
```response title=Response theme={null}
3
```
## arrayWithConstant
Добавленный в: v20.1.0
Создаёт массив длиной `length`, заполненный постоянным значением `x`.
**Синтаксис**
```sql theme={null}
arrayWithConstant(N, x)
```
**Аргументы**
* `length` — Количество элементов в массиве. [`(U)Int*`](/docs/ru/reference/data-types/int-uint)
* `x` — Значение для `N` элементов массива, любого типа.
**Возвращаемое значение**
Возвращает массив `Array` из `N` элементов со значением `x`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayWithConstant(3, 1)
```
```response title=Response theme={null}
[1, 1, 1]
```
## arrayZip
Добавленный в: v20.1.0
Объединяет несколько массивов в один. Результирующий массив содержит соответствующие элементы исходных массивов, сгруппированные в кортежи в порядке перечисленных аргументов.
**Синтаксис**
```sql theme={null}
arrayZip(arr1, arr2, ... , arrN)
```
**Аргументы**
* `arr1, arr2, ... , arrN` — N массивов, объединяемых в один массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив с элементами из исходных массивов, сгруппированными в кортежи. Типы данных в кортеже совпадают с типами входных массивов и идут в том же порядке, в котором передаются массивы [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayZip(['a', 'b', 'c'], [5, 2, 1]);
```
```response title=Response theme={null}
[('a', 5), ('b', 2), ('c', 1)]
```
## arrayZipUnaligned
Добавленный в: v20.1.0
Объединяет несколько массивов в один, допуская несовпадение их длины. Результирующий массив содержит соответствующие элементы исходных массивов, сгруппированные в кортежи в указанном порядке аргументов.
**Синтаксис**
```sql theme={null}
arrayZipUnaligned(arr1, arr2, ..., arrN)
```
**Аргументы**
* `arr1, arr2, ..., arrN` — N массивов, объединённых в один массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив с элементами из исходных массивов, объединёнными в кортежи. Типы данных в кортеже совпадают с типами входных массивов и идут в том же порядке, в котором передаются массивы. [`Array(T)`](/docs/ru/reference/data-types/array) или [`Tuple(T1, T2, ...)`](/docs/ru/reference/data-types/tuple)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT arrayZipUnaligned(['a'], [1, 2, 3]);
```
```response title=Response theme={null}
[('a', 1),(NULL, 2),(NULL, 3)]
```
## countEqual
Добавлено в: v1.1.0
Возвращает количество элементов массива, равных `x`. Эквивалентно `arrayCount(elem -> elem = x, arr)`.
Элементы `NULL` рассматриваются как отдельные значения.
**Синтаксис**
```sql theme={null}
countEqual(arr, x)
```
**Аргументы**
* `arr` — Массив, в котором выполняется поиск. [`Array(T)`](/docs/ru/reference/data-types/array)
* `x` — Значение в массиве, количество вхождений которого нужно подсчитать. Любой тип.
**Возвращаемое значение**
Возвращает количество элементов массива, равных `x` [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT countEqual([1, 2, NULL, NULL], NULL)
```
```response title=Response theme={null}
2
```
## empty
Добавленный в: v1.1.0
Проверяет, пуст ли входной массив.
Массив считается пустым, если не содержит ни одного элемента.
Можно оптимизировать, включив [настройку `optimize_functions_to_subcolumns`](/docs/ru/reference/settings/session-settings#optimize_functions_to_subcolumns). При `optimize_functions_to_subcolumns = 1` функция читает только подстолбец [size0](/docs/ru/reference/data-types/array#array-size) вместо чтения и обработки всего столбца типа Array. Запрос `SELECT empty(arr) FROM TABLE;` преобразуется в `SELECT arr.size0 = 0 FROM TABLE;`.
Функция также работает со строками и UUID.
**Синтаксис**
```sql theme={null}
empty(arr)
```
**Аргументы**
* `arr` — Входной массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает `1` для пустого массива и `0` — для непустого массива [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT empty([]);
```
```response title=Response theme={null}
1
```
## emptyArrayDate
Добавленный в: v1.1.0
Возвращает пустой массив типа Date
**Синтаксис**
```sql theme={null}
emptyArrayDate()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив Date. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayDate()
```
```response title=Response theme={null}
[]
```
## emptyArrayDateTime
Добавленный в: v1.1.0
Возвращает пустой массив DateTime
**Синтаксис**
```sql theme={null}
emptyArrayDateTime()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив DateTime. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayDateTime()
```
```response title=Response theme={null}
[]
```
## emptyArrayFloat32
Добавленный в: v1.1.0
Возвращает пустой массив типа Float32
**Синтаксис**
```sql theme={null}
emptyArrayFloat32()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив типа Float32. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayFloat32()
```
```response title=Response theme={null}
[]
```
## emptyArrayFloat64
Добавленный в: v1.1.0
Возвращает пустой массив типа Float64
**Синтаксис**
```sql theme={null}
emptyArrayFloat64()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив Float64. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayFloat64()
```
```response title=Response theme={null}
[]
```
## emptyArrayInt16
Добавленный в: v1.1.0
Возвращает пустой массив Int16
**Синтаксис**
```sql theme={null}
emptyArrayInt16()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив Int16. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayInt16()
```
```response title=Response theme={null}
[]
```
## emptyArrayInt32
Добавленный в: v1.1.0
Возвращает пустой массив типа Int32
**Синтаксис**
```sql theme={null}
emptyArrayInt32()
```
**Аргументы**
* Нет аргументов.
**Возвращаемое значение**
Пустой массив Int32. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayInt32()
```
```response title=Response theme={null}
[]
```
## emptyArrayInt64
Добавленный в: v1.1.0
Возвращает пустой массив Int64
**Синтаксис**
```sql theme={null}
emptyArrayInt64()
```
**Аргументы**
* Нет.
**Возвращаемое значение**
Пустой массив Int64. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayInt64()
```
```response title=Response theme={null}
[]
```
## emptyArrayInt8
Добавленный в: v1.1.0
Возвращает пустой массив типа Int8
**Синтаксис**
```sql theme={null}
emptyArrayInt8()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив Int8. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayInt8()
```
```response title=Response theme={null}
[]
```
## emptyArrayString
Добавленный в: v1.1.0
Возвращает пустой массив типа String
**Синтаксис**
```sql theme={null}
emptyArrayString()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив строк. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayString()
```
```response title=Response theme={null}
[]
```
## emptyArrayToSingle
Добавленный в: v1.1.0
Принимает пустой массив и возвращает одноэлементный массив со значением по умолчанию.
**Синтаксис**
```sql theme={null}
emptyArrayToSingle(arr)
```
**Аргументы**
* `arr` — Пустой массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Массив с одним значением типа, используемого по умолчанию для массива. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
CREATE TABLE test (
a Array(Int32),
b Array(String),
c Array(DateTime)
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO test VALUES ([], [], []);
SELECT emptyArrayToSingle(a), emptyArrayToSingle(b), emptyArrayToSingle(c) FROM test;
```
```response title=Response theme={null}
┌─emptyArrayToSingle(a)─┬─emptyArrayToSingle(b)─┬─emptyArrayToSingle(c)───┐
│ [0] │ [''] │ ['1970-01-01 01:00:00'] │
└───────────────────────┴───────────────────────┴─────────────────────────┘
```
## emptyArrayUInt16
Добавлено в: v1.1.0
Возвращает пустой массив UInt16
**Синтаксис**
```sql theme={null}
emptyArrayUInt16()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив типа UInt16. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayUInt16()
```
```response title=Response theme={null}
[]
```
## emptyArrayUInt32
Добавленный в: v1.1.0
Возвращает пустой массив типа UInt32
**Синтаксис**
```sql theme={null}
emptyArrayUInt32()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив типа UInt32. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayUInt32()
```
```response title=Response theme={null}
[]
```
## emptyArrayUInt64
Добавленный в: v1.1.0
Возвращает пустой массив типа UInt64
**Синтаксис**
```sql theme={null}
emptyArrayUInt64()
```
**Аргументы**
* Нет.
**Возвращаемое значение**
Пустой массив UInt64. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayUInt64()
```
```response title=Response theme={null}
[]
```
## emptyArrayUInt8
Добавлено в: v1.1.0
Возвращает пустой массив UInt8
**Синтаксис**
```sql theme={null}
emptyArrayUInt8()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Пустой массив UInt8. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT emptyArrayUInt8()
```
```response title=Response theme={null}
[]
```
## has
Добавленный в: v1.1.0
Возвращает, содержит ли массив указанный элемент, Map — указанный ключ, а объект JSON — указанный путь.
Для JSON поддерживаются вложенные пути с точечной нотацией (например, 'a.b.c').
Когда первый аргумент — константный массив, а второй — столбец или выражение, `has(constant_array, column)` работает как `column IN (constant_array)` и для оптимизации может использовать первичный ключ и индексы пропуска данных. Например, `has([1, 10, 100], id)` может использовать индекс первичного ключа, если `id` входит в `PRIMARY KEY`.
Эта оптимизация также применяется, когда столбец обёрнут в монотонную функцию (например, `has([...], toDate(ts))`).
**Синтаксис**
```sql theme={null}
has(haystack, needle)
```
**Аргументы**
* `haystack` — Исходный массив, map или JSON. [`Array`](/docs/ru/reference/data-types/array) или [`Map`](/docs/ru/reference/data-types/map) или [`JSON`](/docs/ru/reference/data-types/newjson)
* `needle` — Искомое значение (элемент массива, ключ в map или строка path в JSON).
**Возвращаемое значение**
Возвращает `1`, если `haystack` содержит указанное значение `needle`, в противном случае — `0`. [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Базовое использование Array**
```sql title=Query theme={null}
SELECT has([1, 2, 3], 2)
```
```response title=Response theme={null}
1
```
**Массив не найден**
```sql title=Query theme={null}
SELECT has([1, 2, 3], 4)
```
```response title=Response theme={null}
0
```
**Базовое использование Map**
```sql title=Query theme={null}
SELECT has(map('a', 1, 'b', 2), 'b')
```
```response title=Response theme={null}
1
```
**JSON-путь**
```sql title=Query theme={null}
SELECT has('{"a": {"b": 1}}'::JSON, 'a.b')
```
```response title=Response theme={null}
1
```
## hasAll
Добавленный в: v1.1.0
Проверяет, является ли один массив подмножеством другого массива.
* Пустой массив является подмножеством любого массива.
* `Null` обрабатывается как значение.
* Порядок значений в обоих массивах не имеет значения.
**Синтаксис**
```sql theme={null}
hasAll(set, subset)
```
**Аргументы**
* `set` — массив любого типа с набором элементов. [`Array(T)`](/docs/ru/reference/data-types/array)
* `subset` — массив любого типа, элементы которого имеют с `set` общий супертип; используется для проверки того, что он является подмножеством `set`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
* `1`, если `set` содержит все элементы из `subset`.
* `0` — в противном случае.
Вызывает исключение `NO_COMMON_TYPE`, если элементы `set` и `subset` не имеют общего супертипа.
**Примеры**
**Пустые массивы**
```sql title=Query theme={null}
SELECT hasAll([], [])
```
```response title=Response theme={null}
1
```
**Массивы со значениями NULL**
```sql title=Query theme={null}
SELECT hasAll([1, Null], [Null])
```
```response title=Response theme={null}
1
```
**Массивы со значениями другого типа**
```sql title=Query theme={null}
SELECT hasAll([1.0, 2, 3, 4], [1, 3])
```
```response title=Response theme={null}
1
```
**Массивы со значениями String**
```sql title=Query theme={null}
SELECT hasAll(['a', 'b'], ['a'])
```
```response title=Response theme={null}
1
```
**Массивы без общего типа**
```sql title=Query theme={null}
SELECT hasAll([1], ['a'])
```
```response title=Response theme={null}
Raises a NO_COMMON_TYPE exception
```
**Массив массивов**
```sql title=Query theme={null}
SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]])
```
```response title=Response theme={null}
0
```
## hasAny
Добавленный в: v1.1.0
Проверяет, есть ли у двух массивов общие элементы.
* `Null` обрабатывается как значение.
* Порядок значений в обоих массивах не имеет значения.
**Синтаксис**
```sql theme={null}
hasAny(arr_x, arr_y)
```
**Аргументы**
* `arr_x` — Массив любого типа с элементами. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr_y` — Массив любого типа, имеющий общий супертип с массивом `arr_x`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
* `1`, если `arr_x` и `arr_y` имеют хотя бы один общий элемент.
* `0` — в противном случае.
Вызывает исключение `NO_COMMON_TYPE`, если какие-либо элементы двух массивов не имеют общего супертипа.
**Примеры**
**Один из массивов пуст**
```sql title=Query theme={null}
SELECT hasAny([1], [])
```
```response title=Response theme={null}
0
```
**Массивы со значениями NULL**
```sql title=Query theme={null}
SELECT hasAny([Null], [Null, 1])
```
```response title=Response theme={null}
1
```
**Массивы со значениями другого типа**
```sql title=Query theme={null}
SELECT hasAny([-128, 1., 512], [1])
```
```response title=Response theme={null}
1
```
**Массивы без общего типа**
```sql title=Query theme={null}
SELECT hasAny([[1, 2], [3, 4]], ['a', 'c'])
```
```response title=Response theme={null}
Вызывает исключение `NO_COMMON_TYPE`
```
**Массив массивов**
```sql title=Query theme={null}
SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [1, 2]])
```
```response title=Response theme={null}
1
```
## hasSubstr
Добавленный в: v20.6.0
Проверяет, встречаются ли все элементы `array2` в `array1` в точно таком же порядке.
Следовательно, функция вернёт `1` тогда и только тогда, когда array1 = prefix + array2 + suffix.
Иными словами, функция проверяет, содержатся ли все элементы `array2` в `array1`, как и функция `hasAll`.
Кроме того, она проверяет, что элементы следуют в одинаковом порядке и в `array1`, и в `array2`.
* Функция вернёт `1`, если `array2` пуст.
* `NULL` обрабатывается как значение. Иными словами, `hasSubstr([1, 2, NULL, 3, 4], [2,3])` вернёт `0`. Однако `hasSubstr([1, 2, NULL, 3, 4], [2,NULL,3])` вернёт `1`
* Порядок значений в обоих массивах важен.
Вызывает исключение `NO_COMMON_TYPE`, если какие-либо элементы двух массивов не имеют общего супертипа.
**Синтаксис**
```sql theme={null}
hasSubstr(arr1, arr2)
```
**Аргументы**
* `arr1` — Массив любого типа с произвольным набором элементов. [`Array(T)`](/docs/ru/reference/data-types/array)
* `arr2` — Массив любого типа с произвольным набором элементов. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает `1`, если массив `arr1` содержит массив `arr2`; в противном случае возвращает `0`. [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Оба массива пусты**
```sql title=Query theme={null}
SELECT hasSubstr([], [])
```
```response title=Response theme={null}
1
```
**Массивы со значениями NULL**
```sql title=Query theme={null}
SELECT hasSubstr([1, Null], [Null])
```
```response title=Response theme={null}
1
```
**Массивы, содержащие значения другого типа**
```sql title=Query theme={null}
SELECT hasSubstr([1.0, 2, 3, 4], [1, 3])
```
```response title=Response theme={null}
0
```
**Массивы со строками**
```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b'], ['a'])
```
```response title=Response theme={null}
1
```
**Массивы с корректным порядком**
```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'b'])
```
```response title=Response theme={null}
1
```
**Массивы с некорректным порядком**
```sql title=Query theme={null}
SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'c'])
```
```response title=Response theme={null}
0
```
**Массив массивов**
```sql title=Query theme={null}
SELECT hasSubstr([[1, 2], [3, 4], [5, 6]], [[1, 2], [3, 4]])
```
```response title=Response theme={null}
1
```
**Массивы без общего типа**
```sql title=Query theme={null}
SELECT hasSubstr([1, 2, NULL, 3, 4], ['a'])
```
```response title=Response theme={null}
Вызывает исключение `NO_COMMON_TYPE`
```
## indexOf
Добавленный в: v1.1.0
Возвращает индекс первого элемента со значением 'x' (начиная с 1), если такой элемент есть в массиве.
Если массив не содержит искомого значения, функция возвращает `0`.
Элементы со значением `NULL` обрабатываются как обычные значения.
**Синтаксис**
```sql theme={null}
indexOf(arr, x)
```
**Аргументы**
* `arr` — Массив, в котором выполняется поиск `x`. [`Array(T)`](/docs/ru/reference/data-types/array)
* `x` — Значение первого совпавшего элемента в `arr`, индекс которого нужно вернуть. [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает индекс (начиная с единицы) первого `x` в `arr`, если он существует. В противном случае возвращает `0`. [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT indexOf([5, 4, 1, 3], 3)
```
```response title=Response theme={null}
4
```
**Массив с NULL**
```sql title=Query theme={null}
SELECT indexOf([1, 3, NULL, NULL], NULL)
```
```response title=Response theme={null}
3
```
## indexOfAssumeSorted
Добавленный в: v24.12.0
Возвращает индекс первого элемента со значением 'x' (начиная с `1`), если он присутствует в массиве.
Если массив не содержит искомого значения, функция возвращает `0`.
В отличие от функции `indexOf`, эта функция предполагает, что массив отсортирован по
возрастанию. Если массив не отсортирован, результат не определён.
**Синтаксис**
```sql theme={null}
indexOfAssumeSorted(arr, x)
```
**Аргументы**
* `arr` — Отсортированный массив, в котором выполняется поиск. [`Array(T)`](/docs/ru/reference/data-types/array)
* `x` — Значение первого совпадающего элемента в отсортированном `arr`, индекс которого нужно вернуть. [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает индекс (начиная с единицы) первого `x` в `arr`, если такой элемент существует. В противном случае возвращает `0`. [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Базовый пример**
```sql title=Query theme={null}
SELECT indexOfAssumeSorted([1, 3, 3, 3, 4, 4, 5], 4)
```
```response title=Response theme={null}
5
```
## length
Добавленный в: v1.1.0
Вычисляет длину строки или массива.
* Для аргументов String или FixedString: вычисляет число байтов в строке.
* Для аргументов Array: вычисляет число элементов в массиве.
* Для аргументов QBit: вычисляет размерность вектора.
* Если функция применяется к аргументу FixedString или QBit, она является константным выражением.
Обратите внимание, что число байтов в строке — это не то же самое, что число
Unicode "кодовых точек", и не то же самое, что число Unicode "графемных кластеров"
(то, что мы обычно называем "символами"), и не то же самое, что отображаемая ширина строки.
В строках могут присутствовать ASCII-байты NULL, и они тоже учитываются.
**Синтаксис**
```sql theme={null}
length(x)
```
**Псевдонимы**: `OCTET_LENGTH`, `CARDINALITY`
**Аргументы**
* `x` — значение, для которого вычисляется число байтов (для `String`/`FixedString`), элементов (для `Array`) или размерность (для `QBit`). [`String`](/docs/ru/reference/data-types/string) или [`FixedString`](/docs/ru/reference/data-types/fixedstring) или [`Array(T)`](/docs/ru/reference/data-types/array) или [`QBit`](/docs/ru/reference/data-types/qbit)
**Возвращаемое значение**
Возвращает число байтов в `String`/`FixedString` `x`, число элементов в массиве `x` или размерность `QBit` `x` [`UInt64`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример для String**
```sql title=Query theme={null}
SELECT length('Hello, world!')
```
```response title=Response theme={null}
13
```
**Пример Array**
```sql title=Query theme={null}
SELECT length(['Hello', 'world'])
```
```response title=Response theme={null}
2
```
**Пример QBit**
```sql title=Query theme={null}
SELECT length([0, 0, 0, 0, 0, 0, 0, 0]::QBit(Float32, 8))
```
```response title=Response theme={null}
8
```
**пример с constexpr**
```sql title=Query theme={null}
WITH 'hello' || toString(number) AS str
SELECT str,
isConstant(length(str)) AS str_length_is_constant,
isConstant(length(str::FixedString(6))) AS fixed_str_length_is_constant
FROM numbers(3)
```
```response title=Response theme={null}
┌─str────┬─str_length_is_constant─┬─fixed_str_length_is_constant─┐
│ hello0 │ 0 │ 1 │
│ hello1 │ 0 │ 1 │
│ hello2 │ 0 │ 1 │
└────────┴────────────────────────┴──────────────────────────────┘
```
**пример Unicode**
```sql title=Query theme={null}
SELECT 'ёлка' AS str1, length(str1), lengthUTF8(str1), normalizeUTF8NFKD(str1) AS str2, length(str2), lengthUTF8(str2)
```
```response title=Response theme={null}
┌─str1─┬─length(str1)─┬─lengthUTF8(str1)─┬─str2─┬─length(str2)─┬─lengthUTF8(str2)─┐
│ ёлка │ 8 │ 4 │ ёлка │ 10 │ 5 │
└──────┴──────────────┴──────────────────┴──────┴──────────────┴──────────────────┘
```
**Пример ascii\_vs\_utf8**
```sql title=Query theme={null}
SELECT 'ábc' AS str, length(str), lengthUTF8(str)
```
```response title=Response theme={null}
┌─str─┬─length(str)──┬─lengthUTF8(str)─┐
│ ábc │ 4 │ 3 │
└─────┴──────────────┴─────────────────┘
```
## notEmpty
Добавленный в: v1.1.0
Проверяет, является ли входной массив непустым.
Массив считается непустым, если содержит хотя бы один элемент.
Можно оптимизировать, включив настройку [`optimize_functions_to_subcolumns`](/docs/ru/reference/settings/session-settings#optimize_functions_to_subcolumns). При `optimize_functions_to_subcolumns = 1` функция читает только подстолбец [size0](/docs/ru/reference/data-types/array#array-size) вместо чтения и обработки всего столбца типа Array. Запрос `SELECT notEmpty(arr) FROM table` преобразуется в `SELECT arr.size0 != 0 FROM TABLE`.
Функция также работает для строк и UUID.
**Синтаксис**
```sql theme={null}
notEmpty(arr)
```
**Аргументы**
* `arr` — входной массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает `1` для непустого массива и `0` — для пустого массива [`UInt8`](/docs/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT notEmpty([1,2]);
```
```response title=Response theme={null}
1
```
## randomHadamardTransform
Добавленный в: v26.7.0
Применяет случайное преобразование Адамара к вектору чисел с плавающей запятой: `y = (1/sqrt(k)) * (H * D * x)`, где
`D` — диагональная матрица детерминированных знаков +/-1, выбираемых по `seed`, а `H` — преобразование Уолша-Адамара.
Это преобразование представляет собой ортогональное **сохраняющее норму** вращение, которое равномерно распределяет энергию вектора
по координатам, делая распределение каждой координаты приблизительно гауссовым и
независимым от данных. Оно полезно как этап предварительной обработки перед скалярным квантованием, а -- в
усечённом виде -- как случайная проекция Джонсона — Линденштрауса / subsampled-randomized-Hadamard (SRHT).
Полное преобразование (без усечения) сохраняет длину входа. Оно точно для следующих длин:
* степень двойки (обычное быстрое преобразование Уолша-Адамара);
* `2^k * m`, где `m` принадлежит `{12, 20}` (порядки, для которых существует матрица Адамара `+/-1`, например `768 = 64 * 12`,
`1536 = 128 * 12`, `3072 = 256 * 12`, `2560 = 128 * 20`), применяется как точное преобразование Кронекера
`H_(2^k) (x) H_m` (без умножений с плавающей запятой);
* `2^k * m`, где `m` — любое другое нечётное число до `64` (порядки, для которых матрицы Адамара `+/-1` не существует --
они есть только для порядков `1`, `2` и чисел, кратных `4`), применяется как точное преобразование Кронекера
`H_(2^k) (x) C_m`, где `C_m` — вещественная ортогональная матрица дискретного преобразования Хартли. Это покрывает
оставшиеся семейства эмбеддингов, такие как `3584 = 512 * 7`, `1152 = 128 * 9`, `1408 = 128 * 11`.
Полное преобразование для длины, у которой наибольший нечётный множитель превышает `64`, не имеет точной формы и потребовало бы
дополнения нулями до большей степени двойки; вместо того чтобы молча
возвращать более длинный вектор, оно **завершается с исключением**. Используйте поддерживаемую длину или передайте `output_dims`, чтобы вычислить усечённую
проекцию для произвольной длины (см. ниже).
Результат имеет тот же тип элементов, что и вход; пустой входной массив возвращает пустой массив.
* `seed` (необязательно, по умолчанию `0`): выбирает схему знаков; один и тот же seed всегда даёт одно и то же
преобразование.
* `output_dims` (необязательно, по умолчанию длина преобразования): сохраняет только первые `output_dims`
координат, превращая преобразование в случайную проекцию, которая принимает **любую** длину. Масштабирование
`1/sqrt(output_dims)` сохраняет норму результата для полного преобразования и
сохраняет её в математическом ожидании при усечении. Значение не должно превышать длину преобразования. Поскольку
усечённый префикс фактора дискретного преобразования Хартли `C_m` не обладает такой же равномерностью leverage, как
матрица Адамара `+/-1`, усечение через `output_dims` для длины из семейства Хартли (или для любой длины
без точного разложения) использует дополненное нулями преобразование степени двойки, которое это свойство сохраняет.
**Синтаксис**
```sql theme={null}
randomHadamardTransform(vector[, seed[, output_dims]])
```
**Аргументы**
* `vector` — Вектор для преобразования. [`Array(BFloat16)`](/docs/ru/reference/data-types/array) или [`Array(Float32)`](/docs/ru/reference/data-types/array) или [`Array(Float64)`](/docs/ru/reference/data-types/array)
* `seed` — Необязательно. seed для детерминированных знаков +/-1 (по умолчанию 0). [`UInt*`](/docs/ru/reference/data-types/int-uint)
* `output_dims` — Необязательно. Обрезает результат до указанного числа начальных координат (по умолчанию: полная длина преобразования, которая совпадает с длиной входного вектора для любой поддерживаемой размерности). Передача output\_dims также включает преобразование для длин, у которых нет точной формы полного преобразования. [`UInt*`](/docs/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Преобразованный вектор (с тем же типом элементов, что и у входного вектора). Его длина равна длине преобразования (длине входного вектора для полного преобразования поддерживаемой размерности) и при необходимости обрезается до output\_dims. [`Array(BFloat16)`](/docs/ru/reference/data-types/array) или [`Array(Float32)`](/docs/ru/reference/data-types/array) или [`Array(Float64)`](/docs/ru/reference/data-types/array)
**Примеры**
**Полное преобразование для длины, равной степени двойки**
```sql title=Query theme={null}
SELECT length(randomHadamardTransform([1, 2, 3, 4]::Array(Float32)))
```
```response title=Response theme={null}
4
```
**Норма сохраняется**
```sql title=Query theme={null}
SELECT round(arraySum(x -> x * x, randomHadamardTransform([1, 2, 3, 4]::Array(Float32))) - 30, 4)
```
```response title=Response theme={null}
0
```
**Проекция, сокращённая до 3 размерностей (принимает вектор любой длины)**
```sql title=Query theme={null}
SELECT length(randomHadamardTransform([1, 2, 3, 4, 5, 6, 7, 8]::Array(Float32), 42, 3))
```
```response title=Response theme={null}
3
```
**Точное преобразование для размерности `2^k * m` сохраняет длину входного вектора (без дополнения)**
```sql title=Query theme={null}
SELECT length(randomHadamardTransform(CAST(range(1152), 'Array(Float32)')))
```
```response title=Response theme={null}
1152
```
## range
Добавленный в: v1.1.0
Возвращает массив чисел от `start` до `end - 1` с шагом `step`.
Поддерживаются следующие типы:
* `UInt8/16/32/64`
* `Int8/16/32/64]`
* Все аргументы `start`, `end`, `step` должны относиться к одному из поддерживаемых выше типов. Элементы возвращаемого массива будут супертипом аргументов.
* Генерируется исключение, если функция возвращает массив, общая длина которого превышает количество элементов, заданное настройкой [`function_range_max_elements_in_block`](/docs/ru/reference/settings/session-settings#function_range_max_elements_in_block).
* Возвращает `NULL`, если любой аргумент имеет тип Nullable(nothing). Генерируется исключение, если любой аргумент имеет значение `NULL` (тип Nullable(T)).
**Синтаксис**
```sql theme={null}
range([start, ] end [, step])
```
**Аргументы**
* `start` — Необязательный. Первый элемент массива. Обязателен, если используется `step`. Значение по умолчанию: `0`. - `end` — Обязательный. Число, до которого строится массив. - `step` — Необязательный. Определяет шаг между элементами массива. Значение по умолчанию: `1`.
**Возвращаемое значение**
Массив чисел от `start` до `end - 1` с шагом `step`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT range(5), range(1, 5), range(1, 5, 2), range(-1, 5, 2);
```
```response title=Response theme={null}
┌─range(5)────┬─range(1, 5)─┬─range(1, 5, 2)─┬─range(-1, 5, 2)─┐
│ [0,1,2,3,4] │ [1,2,3,4] │ [1,3] │ [-1,1,3] │
└─────────────┴─────────────┴────────────────┴─────────────────┘
```
## replicate
Добавленный в: v1.1.0
Создает массив, содержащий одно значение.
**Синтаксис**
```sql theme={null}
replicate(x, arr)
```
**Аргументы**
* `x` — Значение, которым заполняется результирующий массив. [`Any`](/docs/ru/reference/data-types/index)
* `arr` — Массив. [`Array(T)`](/docs/ru/reference/data-types/array)
**Возвращаемое значение**
Возвращает массив той же длины, что и `arr`, заполненный значением `x`. [`Array(T)`](/docs/ru/reference/data-types/array)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT replicate(1, ['a', 'b', 'c']);
```
```response title=Response theme={null}
┌─replicate(1, ['a', 'b', 'c'])───┐
│ [1, 1, 1] │
└─────────────────────────────────┘
```
## reverse
Добавленный в: v1.1.0
Изменяет порядок элементов входного массива или символов входной строки на обратный.
**Синтаксис**
```sql theme={null}
reverse(arr | str)
```
**Аргументы**
* `arr | str` — Исходный массив или строка. [`Array(T)`](/docs/ru/reference/data-types/array) или [`String`](/docs/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает массив или строку, в которых порядок элементов или символов обратный.
**Примеры**
**Обратный порядок элементов массива**
```sql title=Query theme={null}
SELECT reverse([1, 2, 3, 4]);
```
```response title=Response theme={null}
[4, 3, 2, 1]
```
**Реверс строки**
```sql title=Query theme={null}
SELECT reverse('abcd');
```
```response title=Response theme={null}
'dcba'
```
## Функции расстояния
Все поддерживаемые функции описаны в [документации по функциям расстояния](/docs/ru/reference/functions/regular-functions/distance-functions).