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

ARRAY_POSITION

array_position​

SinceVersion 2.0.0

Описание​

Находит индекс (нумерация начинается с 1) первого вхождения указанного элемента в массиве. Функция просматривает массив слева направо, находит первый совпадающий элемент и возвращает его индекс.

Синтаксис​

array_position(ARRAY<T> arr, T element)

Параметры​

  • arr：тип ARRAY, массив, в котором выполняется поиск
  • element：тип T, искомый элемент

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

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

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

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

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

  • Возвращает индекс первого вхождения указанного элемента в массиве. Нумерация возвращаемого значения начинается с 1, а не с 0. Если искомый элемент является первым элементом массива, функция возвращает 1, а не 0
  • 0: если совпадающий элемент не найден или входной массив равен NULL
  • NULL: если входной массив равен NULL

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

  • Функция просматривает массив слева направо и находит первый совпадающий элемент. Если совпадающий элемент не найден, возвращает 0
  • Для пустых массивов возвращается 0
  • Значения null в элементах массива: элементы null можно находить обычным образом

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

Поиск позиции строки в массиве:

SELECT array_position(['apple', 'banana', 'cherry', 'apple'], 'apple');
+-----------------------------------------------------------------+
| array_position(['apple', 'banana', 'cherry', 'apple'], 'apple') |
+-----------------------------------------------------------------+
|                                                               1 |
+-----------------------------------------------------------------+

Поиск позиции числа с плавающей точкой в массиве:

SELECT array_position([1.1, 2.2, 3.3, 4.4, 5.5], 3.3);
+------------------------------------------------+
| array_position([1.1, 2.2, 3.3, 4.4, 5.5], 3.3) |
+------------------------------------------------+
|                                              3 |
+------------------------------------------------+

Поиск отсутствующего элемента:

SELECT array_position([1, 2, 3, 4, 5], 10);
+-------------------------------------+
| array_position([1, 2, 3, 4, 5], 10) |
+-------------------------------------+
|                                   0 |
+-------------------------------------+

Поиск элемента null:

SELECT array_position([1, null, 3, null, 5], null);
+---------------------------------------------+
| array_position([1, null, 3, null, 5], null) |
+---------------------------------------------+
|                                           2 |
+---------------------------------------------+

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

SELECT array_position([], 1);
+-----------------------+
| array_position([], 1) |
+-----------------------+
|                     0 |
+-----------------------+

Если входной массив равен NULL, возвращается NULL:

SELECT array_position(NULL, 1);
+-------------------------+
| array_position(NULL, 1) |
+-------------------------+
|                    NULL |
+-------------------------+

Поиск элемента типа даты:

SELECT array_position(cast(['2023-01-01', '2022-12-31', '2023-06-15'] as array<datetime>), '2023-01-01');
+---------------------------------------------------------------------------------------------------+
| array_position(cast(['2023-01-01', '2022-12-31', '2023-06-15'] as array<datetime>), '2023-01-01') |
+---------------------------------------------------------------------------------------------------+
|                                                                                                 1 |
+---------------------------------------------------------------------------------------------------+

Поиск IP-адреса:

SELECT array_position(CAST(['192.168.1.1', '192.168.1.2', '192.168.1.3'] AS ARRAY<IPV4>), '192.168.1.2');
+---------------------------------------------------------------------------------------------------+
| array_position(CAST(['192.168.1.1', '192.168.1.2', '192.168.1.3'] AS ARRAY<IPV4>), '192.168.1.2') |
+---------------------------------------------------------------------------------------------------+
|                                                                                                 2 |
+---------------------------------------------------------------------------------------------------+

SELECT array_position(CAST(['2001:db8::1', '2001:db8::2', '2001:db8::0'] AS ARRAY<IPV6>), '2001:db8::0');
+---------------------------------------------------------------------------------------------------+
| array_position(CAST(['2001:db8::1', '2001:db8::2', '2001:db8::0'] AS ARRAY<IPV6>), '2001:db8::0') |
+---------------------------------------------------------------------------------------------------+
|                                                                                                 3 |
+---------------------------------------------------------------------------------------------------+

Примеры со сложными типами:

Вложенные массивы не поддерживаются, поэтому возникает ошибка:

SELECT array_position([[1,2], [3,4], [5,6]], [3,4]);
ERROR 1105 (HY000): errCode = 2, detailMessage = array_position does not support type ARRAY<ARRAY<TINYINT>>, expression is array_position([[1, 2], [3, 4], [5, 6]])

Поиск элемента типа Map:

SELECT array_position([{'k':1}, {'k':2}, {'k':3}], {'k':2});
ERROR 1105 (HY000): errCode = 2, detailMessage = array_position does not support type ARRAY<MAP<VARCHAR(1),TINYINT>>, expression is array_position([map('k', 1), map('k', 2), map('k', 3)])

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

SELECT array_position([1,2,3]);
ERROR 1105 (HY000): errCode = 2, detailMessage = Can not found function 'array_position' which has 1 arity. Candidate functions are: [array_position(Expression, Expression)]

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

SELECT array_position('not_an_array', 1);
ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the compatibility function signature: array_position(VARCHAR(12), TINYINT)

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

ARRAY, POSITION, ARRAY_POSITION

Report issue