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

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
  • Логический тип: BOOLEAN
  • Типы IP-адресов: IPV4, IPV6
  • Сложные типы данных: ARRAY, MAP, STRUCT

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

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

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

  • Первый элемент массива, удовлетворяющий условию лямбда-выражения
  • 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