ClickHouse/docs/ru/query_language/functions/array_functions.md
BayoNet 779648f7cc DOCAPI-7695: EN review, RU translation. Functions support for indexes (#7045)
* Typo fix.

* DOCAPI-7695: Typo fixed

* Update mergetree.md (#49)

* DOCAPI-7695: RU translation

* Update mergetree.md
2019-09-24 02:50:26 +03:00

662 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Функции по работе с массивами
## empty {#function-empty}
Возвращает 1 для пустого массива, и 0 для непустого массива.
Тип результата - UInt8.
Функция также работает для строк.
## notEmpty {#function-notempty}
Возвращает 0 для пустого массива, и 1 для непустого массива.
Тип результата - UInt8.
Функция также работает для строк.
## length {#array_functions-length}
Возвращает количество элементов в массиве.
Тип результата - UInt64.
Функция также работает для строк.
## emptyArrayUInt8, emptyArrayUInt16, emptyArrayUInt32, emptyArrayUInt64
## emptyArrayInt8, emptyArrayInt16, emptyArrayInt32, emptyArrayInt64
## emptyArrayFloat32, emptyArrayFloat64
## emptyArrayDate, emptyArrayDateTime
## emptyArrayString
Принимает ноль аргументов и возвращает пустой массив соответствующего типа.
## emptyArrayToSingle
Принимает пустой массив и возвращает массив из одного элемента, равного значению по умолчанию.
## range(N)
Возвращает массив чисел от 0 до N-1.
На всякий случай, если на блок данных, создаются массивы суммарной длины больше 100 000 000 элементов, то кидается исключение.
## array(x1, ...), оператор \[x1, ...\]
Создаёт массив из аргументов функции.
Аргументы должны быть константами и иметь типы, для которых есть наименьший общий тип. Должен быть передан хотя бы один аргумент, так как иначе непонятно, какого типа создавать массив. То есть, с помощью этой функции невозможно создать пустой массив (для этого используйте функции emptyArray\*, описанные выше).
Возвращает результат типа Array(T), где T - наименьший общий тип от переданных аргументов.
## arrayConcat
Объединяет массивы, переданные в качестве аргументов.
```sql
arrayConcat(arrays)
```
**Параметры**
- `arrays` произвольное количество элементов типа [Array](../../data_types/array.md)
**Пример**
```sql
SELECT arrayConcat([1, 2], [3, 4], [5, 6]) AS res
```
```text
┌─res───────────┐
│ [1,2,3,4,5,6] │
└───────────────┘
```
## arrayElement(arr, n), operator arr[n]
Достаёт элемент с индексом n из массива arr. n должен быть любым целочисленным типом.
Индексы в массиве начинаются с единицы.
Поддерживаются отрицательные индексы. В этом случае, будет выбран соответствующий по номеру элемент с конца. Например, arr\[-1\] - последний элемент массива.
Если индекс выходит за границы массива, то возвращается некоторое значение по умолчанию (0 для чисел, пустая строка для строк и т. п.), кроме случая с неконстантным массивом и константным индексом 0 (в этом случае будет ошибка `Array indices are 1-based`).
## has(arr, elem)
Проверяет наличие элемента elem в массиве arr.
Возвращает 0, если элемента в массиве нет, или 1, если есть.
`NULL` обрабатывается как значение.
```sql
SELECT has([1, 2, NULL], NULL)
```
```text
┌─has([1, 2, NULL], NULL)─┐
│ 1 │
└─────────────────────────┘
```
## hasAll
Проверяет, является ли один массив подмножеством другого.
```sql
hasAll(set, subset)
```
**Параметры**
- `set` массив любого типа с набором элементов.
- `subset` массив любого типа со значениями, которые проверяются на вхождение в `set`.
**Возвращаемые значения**
- `1`, если `set` содержит все элементы из `subset`.
- `0`, в противном случае.
**Особенности**
- Пустой массив является подмножеством любого массива.
- `NULL` обрабатывается как значение.
- Порядок значений в обоих массивах не имеет значения.
**Примеры**
`SELECT hasAll([], [])` возвращает 1.
`SELECT hasAll([1, Null], [Null])` возвращает 1.
`SELECT hasAll([1.0, 2, 3, 4], [1, 3])` возвращает 1.
`SELECT hasAll(['a', 'b'], ['a'])` возвращает 1.
`SELECT hasAll([1], ['a'])` возвращает 0.
`SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]])` возвращает 0.
## hasAny
Проверяет, имеют ли два массива хотя бы один общий элемент.
```sql
hasAny(array1, array2)
```
**Параметры**
- `array1` массив любого типа с набором элементов.
- `array2` массив любого типа с набором элементов.
**Возвращаемые значения**
- `1`, если `array1` и `array2` имеют хотя бы один одинаковый элемент.
- `0`, в противном случае.
**Особенности**
- `NULL` обрабатывается как значение.
- Порядок значений в обоих массивах не имеет значения.
**Примеры**
`SELECT hasAny([1], [])` возвращает `0`.
`SELECT hasAny([Null], [Null, 1])` возвращает `1`.
`SELECT hasAny([-128, 1., 512], [1])` возвращает `1`.
`SELECT hasAny([[1, 2], [3, 4]], ['a', 'c'])` возвращает `0`.
`SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [1, 2]])` возвращает `1`.
## indexOf(arr, x)
Возвращает индекс первого элемента x (начиная с 1), если он есть в массиве, или 0, если его нет.
Пример:
```sql
SELECT indexOf([1, 3, NULL, NULL], NULL)
```
```text
┌─indexOf([1, 3, NULL, NULL], NULL)─┐
│ 3 │
└───────────────────────────────────┘
```
Элементы, равные `NULL`, обрабатываются как обычные значения.
## countEqual(arr, x)
Возвращает количество элементов массива, равных x. Эквивалентно arrayCount(elem -> elem = x, arr).
`NULL` обрабатывается как значение.
Пример:
```sql
SELECT countEqual([1, 2, NULL, NULL], NULL)
```
```text
┌─countEqual([1, 2, NULL, NULL], NULL)─┐
│ 2 │
└──────────────────────────────────────┘
```
## arrayEnumerate(arr) {#array_functions-arrayenumerate}
Возвращает массив \[1, 2, 3, ..., length(arr)\]
Эта функция обычно используется совместно с ARRAY JOIN. Она позволяет, после применения ARRAY JOIN, посчитать что-либо только один раз для каждого массива. Пример:
```sql
SELECT
count() AS Reaches,
countIf(num = 1) AS Hits
FROM test.hits
ARRAY JOIN
GoalsReached,
arrayEnumerate(GoalsReached) AS num
WHERE CounterID = 160656
LIMIT 10
```
```text
┌─Reaches─┬──Hits─┐
│ 95606 │ 31406 │
└─────────┴───────┘
```
В этом примере, Reaches - число достижений целей (строк, получившихся после применения ARRAY JOIN), а Hits - число хитов (строк, которые были до ARRAY JOIN). В данном случае, тот же результат можно получить проще:
```sql
SELECT
sum(length(GoalsReached)) AS Reaches,
count() AS Hits
FROM test.hits
WHERE (CounterID = 160656) AND notEmpty(GoalsReached)
```
```text
┌─Reaches─┬──Hits─┐
│ 95606 │ 31406 │
└─────────┴───────┘
```
Также эта функция может быть использована в функциях высшего порядка. Например, с её помощью можно достать индексы массива для элементов, удовлетворяющих некоторому условию.
## arrayEnumerateUniq(arr, ...)
Возвращает массив, такого же размера, как исходный, где для каждого элемента указано, какой он по счету среди элементов с таким же значением.
Например: arrayEnumerateUniq(\[10, 20, 10, 30\]) = \[1, 1, 2, 1\].
Эта функция полезна при использовании ARRAY JOIN и агрегации по элементам массива.
Пример:
```sql
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
```
```text
┌──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 │
└─────────┴─────────┴────────┘
```
В этом примере, для каждого идентификатора цели, посчитано количество достижений целей (каждый элемент вложенной структуры данных Goals является достижением целей) и количество визитов. Если бы не было ARRAY JOIN, мы бы считали количество визитов как sum(Sign). Но в данном случае, строчки были размножены по вложенной структуре Goals, и чтобы после этого учесть каждый визит один раз, мы поставили условие на значение функции arrayEnumerateUniq(Goals.ID).
Функция arrayEnumerateUniq может принимать несколько аргументов - массивов одинаковых размеров. В этом случае, уникальность считается для кортежей элементов на одинаковых позициях всех массивов.
```sql
SELECT arrayEnumerateUniq([1, 1, 1, 2, 2, 2], [1, 1, 2, 1, 1, 2]) AS res
```
```text
┌─res───────────┐
│ [1,2,1,1,2,1] │
└───────────────┘
```
Это нужно при использовании ARRAY JOIN с вложенной структурой данных и затем агрегации по нескольким элементам этой структуры.
## arrayPopBack
Удаляет последний элемент из массива.
```sql
arrayPopBack(array)
```
**Параметры**
- `array` - Массив.
**Пример**
```sql
SELECT arrayPopBack([1, 2, 3]) AS res
```
text
```
┌─res───┐
│ [1,2] │
└───────┘
```
## arrayPopFront
Удаляет первый элемент из массива.
```sql
arrayPopFront(array)
```
**Параметры**
- `array` - Массив.
**Пример**
```sql
SELECT arrayPopFront([1, 2, 3]) AS res
```
```text
┌─res───┐
│ [2,3] │
└───────┘
```
## arrayPushBack
Добавляет один элемент в конец массива.
```sql
arrayPushBack(array, single_value)
```
**Параметры**
- `array` - Массив.
- `single_value` - Одиночное значение. В массив с числам можно добавить только числа, в массив со строками только строки. При добавлении чисел ClickHouse автоматически приводит тип `single_value` к типу данных массива. Подробнее о типах данных в ClickHouse читайте в разделе "[Типы данных](../../data_types/index.md#data_types)". Может быть равно `NULL`. Функция добавит элемент `NULL` в массив, а тип элементов массива преобразует в `Nullable`.
**Пример**
```sql
SELECT arrayPushBack(['a'], 'b') AS res
```
```text
┌─res───────┐
│ ['a','b'] │
└───────────┘
```
## arrayPushFront
Добавляет один элемент в начало массива.
```sql
arrayPushFront(array, single_value)
```
**Параметры**
- `array` - Массив.
- `single_value` - Одиночное значение. В массив с числам можно добавить только числа, в массив со строками только строки. При добавлении чисел ClickHouse автоматически приводит тип `single_value` к типу данных массива. Подробнее о типах данных в ClickHouse читайте в разделе "[Типы данных](../../data_types/index.md#data_types)". Может быть равно `NULL`. Функция добавит элемент `NULL` в массив, а тип элементов массива преобразует в `Nullable`.
**Пример**
```sql
SELECT arrayPushBack(['b'], 'a') AS res
```
```text
┌─res───────┐
│ ['a','b'] │
└───────────┘
```
## arrayResize
Изменяет длину массива.
```sql
arrayResize(array, size[, extender])
```
**Параметры**
- `array` — массив.
- `size` — необходимая длина массива.
- Если `size` меньше изначального размера массива, то массив обрезается справа.
- Если `size` больше изначального размера массива, массив дополняется справа значениями `extender` или значениями по умолчанию для типа данных элементов массива.
- `extender` — значение для дополнения массива. Может быть `NULL`.
**Возвращаемое значение:**
Массив длины `size`.
**Примеры вызовов**
```sql
SELECT arrayResize([1], 3)
```
```text
┌─arrayResize([1], 3)─┐
│ [1,0,0] │
└─────────────────────┘
```
```sql
SELECT arrayResize([1], 3, NULL)
```
```text
┌─arrayResize([1], 3, NULL)─┐
│ [1,NULL,NULL] │
└───────────────────────────┘
```
## arraySlice
Возвращает срез массива.
```sql
arraySlice(array, offset[, length])
```
**Параметры**
- `array` - Массив данных.
- `offset` - Отступ от края массива. Положительное значение - отступ слева, отрицательное значение - отступ справа. Отсчет элементов массива начинается с 1.
- `length` - Длина необходимого среза. Если указать отрицательное значение, то функция вернёт открытый срез `[offset, array_length - length)`. Если не указать значение, то функция вернёт срез `[offset, the_end_of_array]`.
**Пример**
```sql
SELECT arraySlice([1, 2, NULL, 4, 5], 2, 3) AS res
```
```text
┌─res────────┐
│ [2,NULL,4] │
└────────────┘
```
Элементы массива равные `NULL` обрабатываются как обычные значения.
## arraySort([func,] arr, ...) {#array_functions-sort}
Возвращает массив `arr`, отсортированный в восходящем порядке. Если задана функция `func`, то порядок сортировки определяется результатом применения этой функции на элементы массива `arr`. Если `func` принимает несколько аргументов, то в функцию `arraySort` нужно передавать несколько массивов, которые будут соответствовать аргументам функции `func`. Подробные примеры рассмотрены в конце описания `arraySort`.
Пример сортировки целочисленных значений:
```sql
SELECT arraySort([1, 3, 3, 0])
```
```text
┌─arraySort([1, 3, 3, 0])─┐
│ [0,1,3,3] │
└─────────────────────────┘
```
Пример сортировки строковых значений:
```sql
SELECT arraySort(['hello', 'world', '!'])
```
```text
┌─arraySort(['hello', 'world', '!'])─┐
│ ['!','hello','world'] │
└────────────────────────────────────┘
```
Значения `NULL`, `NaN` и `Inf` сортируются по следующему принципу:
```sql
SELECT arraySort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf]);
```
```text
┌─arraySort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf])─┐
│ [-inf,-4,1,2,3,inf,nan,nan,NULL,NULL] │
└───────────────────────────────────────────────────────────┘
```
- Значения `-Inf` идут в начале массива.
- Значения `NULL` идут в конце массива.
- Значения `NaN` идут перед `NULL`.
- Значения `Inf` идут перед `NaN`.
Функция `arraySort` является [функцией высшего порядка](higher_order_functions.md) — в качестве первого аргумента ей можно передать лямбда-функцию. В этом случае порядок сортировки определяется результатом применения лямбда-функции на элементы массива.
Рассмотрим пример:
```sql
SELECT arraySort((x) -> -x, [1, 2, 3]) as res;
```
```text
┌─res─────┐
│ [3,2,1] │
└─────────┘
```
Для каждого элемента исходного массива лямбда-функция возвращает ключ сортировки, то есть [1 > -1, 2 > -2, 3 > -3]. Так как `arraySort` сортирует элементы в порядке возрастания ключей, результат будет [3, 2, 1]. Как можно заметить, функция `x > -x` устанавливает [обратный порядок сортировки](#array_functions-reverse-sort).
Лямбда-функция может принимать несколько аргументов. В этом случае, в функцию `arraySort` нужно передавать несколько массивов, которые будут соответствовать аргументам лямбда-функции (массивы должны быть одинаковой длины). Следует иметь в виду, что результат будет содержать элементы только из первого массива; элементы из всех последующих массивов будут задавать ключи сортировки. Например:
```sql
SELECT arraySort((x, y) -> y, ['hello', 'world'], [2, 1]) as res;
```
```text
┌─res────────────────┐
│ ['world', 'hello'] │
└────────────────────┘
```
Элементы, указанные во втором массиве ([2,1]), определяют ключ сортировки для элементов из исходного массива (['hello', 'world']), то есть ['hello' > 2, 'world' > 1]. Так как лямбда-функция не использует `x`, элементы исходного массива не влияют на порядок сортировки. Таким образом, 'hello' будет вторым элементом в отсортированном массиве, а 'world' — первым.
Ниже приведены другие примеры.
```sql
SELECT arraySort((x, y) -> y, [0, 1, 2], ['c', 'b', 'a']) as res;
```
```text
┌─res─────┐
│ [2,1,0] │
└─────────┘
```
```sql
SELECT arraySort((x, y) -> -y, [0, 1, 2], [1, 2, 3]) as res;
```
```text
┌─res─────┐
│ [2,1,0] │
└─────────┘
```
!!! note "Примечание"
Для улучшения эффективности сортировки применяется [преобразование Шварца](https://ru.wikipedia.org/wiki/%D0%9F%D1%80%D0%B5%D0%BE%D0%B1%D1%80%D0%B0%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_%D0%A8%D0%B2%D0%B0%D1%80%D1%86%D0%B0).
## arrayReverseSort([func,] arr, ...) {#array_functions-reverse-sort}
Возвращает массив `arr`, отсортированный в нисходящем порядке. Если указана функция `func`, то массив `arr` сначала сортируется в порядке, который определяется функцией `func`, а затем отсортированный массив переворачивается. Если функция `func` принимает несколько аргументов, то в функцию `arrayReverseSort` необходимо передавать несколько массивов, которые будут соответствовать аргументам функции `func`. Подробные примеры рассмотрены в конце описания функции `arrayReverseSort`.
Пример сортировки целочисленных значений:
```sql
SELECT arrayReverseSort([1, 3, 3, 0]);
```
```text
┌─arrayReverseSort([1, 3, 3, 0])─┐
│ [3,3,1,0] │
└────────────────────────────────┘
```
Пример сортировки строковых значений:
```sql
SELECT arrayReverseSort(['hello', 'world', '!']);
```
```text
┌─arrayReverseSort(['hello', 'world', '!'])─┐
│ ['world','hello','!'] │
└───────────────────────────────────────────┘
```
Значения `NULL`, `NaN` и `Inf` сортируются в следующем порядке:
```sql
SELECT arrayReverseSort([1, nan, 2, NULL, 3, nan, -4, NULL, inf, -inf]) as res;
```
```text
┌─res───────────────────────────────────┐
│ [inf,3,2,1,-4,-inf,nan,nan,NULL,NULL] │
└───────────────────────────────────────┘
```
- Значения `Inf` идут в начале массива.
- Значения `NULL` идут в конце массива.
- Значения `NaN` идут перед `NULL`.
- Значения `-Inf` идут перед `NaN`.
Функция `arrayReverseSort` является [функцией высшего порядка](higher_order_functions.md). Вы можете передать ей в качестве первого аргумента лямбда-функцию. Например:
```sql
SELECT arrayReverseSort((x) -> -x, [1, 2, 3]) as res;
```
```text
┌─res─────┐
│ [1,2,3] │
└─────────┘
```
В этом примере, порядок сортировки устанавливается следующим образом:
1. Сначала исходный массив ([1, 2, 3]) сортируется в том порядке, который определяется лямбда-функцией. Результатом будет массив [3, 2, 1].
2. Массив, который был получен на предыдущем шаге, переворачивается. То есть, получается массив [1, 2, 3].
Лямбда-функция может принимать на вход несколько аргументов. В этом случае, в функцию `arrayReverseSort` нужно передавать несколько массивов, которые будут соответствовать аргументам лямбда-функции (массивы должны быть одинаковой длины). Следует иметь в виду, что результат будет содержать элементы только из первого массива; элементы из всех последующих массивов будут определять ключи сортировки. Например:
```sql
SELECT arrayReverseSort((x, y) -> y, ['hello', 'world'], [2, 1]) as res;
```
```text
┌─res───────────────┐
│ ['hello','world'] │
└───────────────────┘
```
В этом примере, массив сортируется следующим образом:
1. Сначала массив сортируется в том порядке, который определяется лямбда-функцией. Элементы, указанные во втором массиве ([2,1]), определяют ключи сортировки соответствующих элементов из исходного массива (['hello', 'world']). То есть, будет массив ['world', 'hello'].
2. Массив, который был отсортирован на предыдущем шаге, переворачивается. Получается массив ['hello', 'world'].
Ниже приведены ещё примеры.
```sql
SELECT arrayReverseSort((x, y) -> y, [0, 1, 2], ['c', 'b', 'a']) as res;
```
```text
┌─res─────┐
│ [0,1,2] │
└─────────┘
```
```sql
SELECT arrayReverseSort((x, y) -> -y, [4, 3, 5], [1, 2, 3]) AS res;
```
```text
┌─res─────┐
│ [4,3,5] │
└─────────┘
```
## arrayUniq(arr, ...)
Если передан один аргумент, считает количество разных элементов в массиве.
Если передано несколько аргументов, считает количество разных кортежей из элементов на соответствующих позициях в нескольких массивах.
Если необходимо получить список уникальных элементов массива, можно воспользоваться arrayReduce('groupUniqArray', arr).
## arrayJoin(arr)
Особенная функция. Смотрите раздел ["Функция arrayJoin"](array_join.md#functions_arrayjoin).
[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/array_functions/) <!--hide-->