JSON_ARRAY_INSERT (Lakehouse v1)

Insere um valor numa matriz JSON no índice especificado e devolve a matriz JSON atualizada.

Sintaxe SQL

JSON_ARRAY_INSERT(<json_array>, <index>, <json_value>)

Parâmetro	Descrição
<json_array>	A matriz JSON a modificar.
<index>	A posição em que o valor será inserido. Os índices positivos inserem na posição especificada ou acrescentam no fim se estiverem fora do intervalo; os índices negativos inserem a partir do fim ou no início se estiverem fora do intervalo.
<json_value>	O valor JSON a inserir na matriz.

Tipo de retorno

Matriz JSON.

Exemplos de SQL

Quando <index> é um número inteiro não negativo, o novo elemento é inserido na posição especificada e os elementos existentes são deslocados para a direita.

-- The new element is inserted at position 0 (the beginning of the array), shifting all original elements to the right
SELECT JSON_ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, 0, '"new_task"'::VARIANT);

-[ RECORD 1 ]-----------------------------------
json_array_insert('["task1", "task2", "task3"]'::VARIANT, 0, '"new_task"'::VARIANT): ["new_task","task1","task2","task3"]

-- The new element is inserted at position 1, between task1 and task2
SELECT JSON_ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, 1, '"new_task"'::VARIANT);

-[ RECORD 1 ]-----------------------------------
json_array_insert('["task1", "task2", "task3"]'::VARIANT, 1, '"new_task"'::VARIANT): ["task1","new_task","task2","task3"]

-- If the index exceeds the length of the array, the new element is appended at the end of the array
SELECT JSON_ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, 6, '"new_task"'::VARIANT);

-[ RECORD 1 ]-----------------------------------
json_array_insert('["task1", "task2", "task3"]'::VARIANT, 6, '"new_task"'::VARIANT): ["task1","task2","task3","new_task"]

Um <index> negativo conta a partir do fim da matriz, em que -1 representa a posição anterior ao último elemento, -2 a anterior ao penúltimo, e assim sucessivamente.

-- The new element is inserted just before the last element (task3)
SELECT JSON_ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, -1, '"new_task"'::VARIANT);

-[ RECORD 1 ]-----------------------------------
json_array_insert('["task1", "task2", "task3"]'::VARIANT, - 1, '"new_task"'::VARIANT): ["task1","task2","new_task","task3"]

-- Since the negative index exceeds the array’s length, the new element is inserted at the beginning
SELECT JSON_ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, -6, '"new_task"'::VARIANT);

-[ RECORD 1 ]-----------------------------------
json_array_insert('["task1", "task2", "task3"]'::VARIANT, - 6, '"new_task"'::VARIANT): ["new_task","task1","task2","task3"]