ELEMENT_AT

Функция

Функция ELEMENT_AT извлекает значение элемента из массива, отображения, структуры или значения типа variant по указанному индексу или ключу.

• Для ARRAY возвращает элемент в указанной позиции.
• Для MAP возвращает значение, соответствующее указанному ключу.
• Для STRUCT возвращает вложенное поле в указанной позиции (начиная с 1) или с указанным именем поля, аналогично STRUCT_ELEMENT.
• Для VARIANT возвращает значение указанного вложенного поля.

Синтаксис

ELEMENT_AT(container, key_or_index)

Параметры

• container: может иметь тип ARRAY, MAP, STRUCT или VARIANT.
• key_or_index:
  • Для ARRAY: целое число; индексация начинается с 1.
  • Для MAP: тип ключа (K) отображения MAP; допускается любой поддерживаемый примитивный тип.
  • Для STRUCT: константная целочисленная позиция поля (начиная с 1) или константное строковое имя поля (сопоставляется без учёта регистра).
  • Для VARIANT: строковый тип.

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

• Для ARRAY: возвращает элемент по указанному индексу (тип T).
• Для MAP: возвращает значение, соответствующее указанному ключу (тип V).
• Для STRUCT: возвращает значение указанного вложенного поля.
• Для VARIANT: возвращает значение типа VARIANT.
• Если индекс или ключ не существует, возвращает NULL (для STRUCT позиция за пределами допустимого диапазона или несуществующее имя поля вызывают ошибку).
• Если параметр равен NULL, возвращает NULL.

Примечания

1. Индексы массива начинаются с 1, а не с 0.
2. Поддерживаются отрицательные индексы: -1 обозначает последний элемент, -2 — предпоследний и так далее.
3. Функция ELEMENT_AT(container, key_or_index) работает так же, как container[key_or_index] (подробнее см. примеры).

Примеры

1. Функция ELEMENT_AT работает так же, как [].

   SELECT ELEMENT_AT([1, 2, 3], 2);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 2) |
   +--------------------------+
   |                        2 |
   +--------------------------+
   
   SELECT [1, 2, 3][2];
   +--------------+
   | [1, 2, 3][2] |
   +--------------+
   |            2 |
   +--------------+

2. Индексация массива начинается с 1; при выходе за границы возвращается NULL.

   SELECT ELEMENT_AT([1, 2, 3], 0);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 0) |
   +--------------------------+
   |                     NULL |
   +--------------------------+
   
   SELECT ELEMENT_AT([1, 2, 3], 4);
   +--------------------------+
   | ELEMENT_AT([1, 2, 3], 4) |
   +--------------------------+
   |                     NULL |
   +--------------------------+

3. Обращение к несуществующему ключу в MAP возвращает NULL.

   SELECT ELEMENT_AT({"a": 1, "b": 2}, "c");
   +-----------------------------------+
   | ELEMENT_AT({"a": 1, "b": 2}, "c") |
   +-----------------------------------+
   |                              NULL |
   +-----------------------------------+

4. Обращение к вложенному полю STRUCT по позиции или имени поля (аналогично STRUCT_ELEMENT).

   SELECT ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1);
   +------------------------------------------------------------+
   | ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1) |
   +------------------------------------------------------------+
   | Jack                                                       |
   +------------------------------------------------------------+
   
   SELECT NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'];
   +--------------------------------------------------+
   | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
   +--------------------------------------------------+
   |                                          1728923 |
   +--------------------------------------------------+

5. При обращении к вложенному полю VARIANT, если значение VARIANT не имеет тип OBJECT, возвращается пустое значение.

   SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");
   +------------------------------------------------------+
   | ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a") |
   +------------------------------------------------------+
   | 1                                                    |
   +------------------------------------------------------+
   
   SELECT ELEMENT_AT(CAST('123' AS VARIANT), "");
   +----------------------------------------+
   | ELEMENT_AT(CAST('123' AS VARIANT), "") |
   +----------------------------------------+
   |                                        |
   +----------------------------------------+