Перейти к содержимому
Последнее обновление

ARRAY_FIRST

array_first​

SinceVersion 2.0.0

Описание​

Возвращает первый элемент массива, удовлетворяющий условию лямбда-выражения. Функция применяет лямбда-выражение к элементам массива, находит первый элемент, удовлетворяющий условию, и возвращает его.

Синтаксис​

array_first(lambda, array1, ...)

Параметры​

  • lambda：лямбда-выражение для проверки элементов массива, возвращающее true/false или выражения, которые можно преобразовать в логические значения
  • array1, ...：один или несколько параметров типа ARRAY

Поддерживаемые типы T:

  • Числовые типы: TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE, DECIMAL
  • Строковые типы: CHAR, VARCHAR, STRING
  • Типы даты и времени: DATE, DATETIME, DATEV2, DATETIMEV2, TIMESTAMP_NS
  • Логический тип: BOOLEAN
  • Типы IP: IPV4, IPV6
  • UUID: UUID
  • Сложные типы данных: ARRAY, MAP, STRUCT

Возвращаемое значение​

Тип возвращаемого значения: T

Значение результата:

  • Первый элемент массива, удовлетворяющий условию лямбда-выражения
  • NULL: если массив пуст или ни один элемент не удовлетворяет условию

Примечания по использованию:

  • Количество параметров лямбда-выражения должно совпадать с количеством параметров-массивов
  • Все входные массивы должны иметь одинаковую длину
  • Поддерживается поиск по нескольким массивам и по массивам сложных типов
  • Для пустых массивов возвращается NULL
  • Входные параметры со значением NULL не поддерживаются
  • В лямбда-выражении можно использовать любые скалярные выражения, но нельзя использовать агрегатные функции
  • Лямбда-выражения могут вызывать другие функции высшего порядка, но типы возвращаемых значений должны быть совместимы
  • Обработка значений null в элементах массива: элементы со значением null передаются лямбда-выражению для обработки, и оно может проверять наличие значений null

Примеры запросов:

Найти первый элемент, больший или равный 3, в массиве чисел с плавающей точкой:

SELECT array_first(x -> x >= 3, [1.1, 2.2, 3.3, 4.4, 5.5]);
+-----------------------------------------------------+
| array_first(x -> x >= 3, [1.1, 2.2, 3.3, 4.4, 5.5]) |
+-----------------------------------------------------+
|                                                 3.3 |
+-----------------------------------------------------+

Найти первый элемент длиной больше 2 в массиве строк:

SELECT array_first(x -> length(x) > 2, ['a', 'bb', 'ccc', 'dddd', 'eeeee']);
+----------------------------------------------------------------------+
| array_first(x -> length(x) > 2, ['a', 'bb', 'ccc', 'dddd', 'eeeee']) |
+----------------------------------------------------------------------+
| ccc                                                                  |
+----------------------------------------------------------------------+

Для пустого массива возвращается NULL:

SELECT array_first(x -> x > 0, []);
+-------------------------------------+
| array_first(x -> x > 0, [])        |
+-------------------------------------+
| NULL                                |
+-------------------------------------+

Входной параметр со значением NULL вызывает ошибку:

SELECT array_first(x -> x > 2, NULL);
ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array but is NULL

SELECT array_first(NULL);
ERROR 1105 (HY000): errCode = 2, detailMessage = Can not build function: 'array_first', expression: array_first(NULL), The 1st arg of array_filter must be lambda but is NULL

Массив со значениями null: лямбда-выражение может проверять наличие null:

SELECT array_first(x -> x is not null, [null, 1, null, 3, null, 5]);
+--------------------------------------------------------------+
| array_first(x -> x is not null, [null, 1, null, 3, null, 5]) |
+--------------------------------------------------------------+
|                                                            1 |
+--------------------------------------------------------------+

Поиск по нескольким массивам: найти первый элемент первого массива, который больше соответствующего элемента второго массива:

SELECT array_first((x, y) -> x > y, [1, 2, 3, 4, 5], [1.1, 2.2, 3.3, 4.4, 5.5]);
+--------------------------------------------------------------------------+
| array_first((x, y) -> x > y, [1, 2, 3, 4, 5], [1.1, 2.2, 3.3, 4.4, 5.5]) |
+--------------------------------------------------------------------------+
|                                                                     NULL |
+--------------------------------------------------------------------------+

Примеры для сложных типов:

Поиск во вложенном массиве: найти первый подмассив длиной больше 2:

SELECT array_first(x -> size(x) > 2, [[1,2],[3,4,5],[6],[7,8,9,10]]);
+---------------------------------------------------------------+
| array_first(x -> size(x) > 2, [[1,2],[3,4,5],[6],[7,8,9,10]]) |
+---------------------------------------------------------------+
| [3, 4, 5]                                                     |
+---------------------------------------------------------------+

Поиск по элементам типа Map: найти первый элемент, в котором значение по ключу 'a' больше 10:

SELECT array_first(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]);
+---------------------------------------------------------------+
| array_first(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]) |
+---------------------------------------------------------------+
| {"a":15}                                                      |
+---------------------------------------------------------------+

Ошибка при несовпадении количества параметров лямбда-выражения с количеством параметров-массивов:

SELECT array_first(x -> x > 0, [1,2,3], [4,5,6], [7,8,9]);
ERROR 1105 (HY000): errCode = 2, detailMessage = lambda x -> (x > 0) arguments' size is not equal parameters' size

Ошибка при неверном количестве параметров:

SELECT array_first((x, y) -> x > y, [1,2,3], [4,5]);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.6)[INVALID_ARGUMENT]in array map function, the input column size are not equal completely, nested column data rows 1st size is 3, 2th size is 2.

Ошибка при передаче значения, тип которого не является массивом:

SELECT array_first(x -> x > 0, 'not_an_array');
ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array but is 'not_an_array'

Ключевые слова​

ARRAY, FIRST, ARRAY_FIRST

Report issue