ELEMENT_AT

Назначение

Функция ELEMENT_AT извлекает значение элемента из ARRAY, MAP, STRUCT или 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: Строковый ключ.
  • Для массива VARIANT в Doris 5.0.0 и более поздних версиях: Целочисленный индекс; положительные индексы начинаются с 1, а отрицательные отсчитываются от конца.

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

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

Примечания

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

SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 1);  -- 10
SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 2);  -- 20
SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), -1); -- 30

4. Для VARIANT поле со значением JSON null в значении, вычисленном в запросе, возвращается как VARIANT null, который отличается от SQL NULL. В данных, считываемых из таблицы, поля со значением null в объектах вне массивов не сохраняются, поэтому такое же обращение возвращает SQL NULL. См. Семантика NULL.

Примеры

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, возвращается NULL.

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