Categorias:

Funções de dados semiestruturados (Matriz/objeto)

OBJECT_INSERT

Retorna um objeto que consiste no objeto de entrada com um novo par chave-valor inserido (ou uma chave existente atualizada com um novo valor).

Sintaxe

OBJECT_INSERT( <object> , <key> , <value> [ , <updateFlag> ] )
Copy

Argumentos

Obrigatório:

object

O objeto de origem no qual o novo par chave-valor é inserido.

key

A nova chave a ser inserida no objeto. Deve ser diferente de todas as chaves existentes no objeto, a menos que updateFlag esteja definido como TRUE.

value

O valor associado à chave.

Opcional:

updateFlag

Sinalizador booleano que, quando definido como TRUE, especifica o valor de entrada usado para atualizar/substituir uma chave existente no objeto, em vez de inserir um novo par chave-valor.

O padrão é FALSE.

Notas de uso

  • A função oferece suporte a valores JSON NULL, mas não a valores ou chaves SQL NULL:

    • Se key for qualquer cadeia de caracteres diferente de NULL e value for um JSON NULL (por exemplo, PARSE_JSON('NULL')), o par chave-valor é inserido no objeto retornado.

    • Se key ou value for um SQL NULL, o par chave-valor é omitido do objeto retornado.

  • Se o argumento opcional updateFlag for definido como TRUE, a entrada existente key será atualizada para a entrada value. Se updateFlag for omitido ou definido como FALSE, chamar esta função com uma chave de entrada que já existe no objeto resulta em um erro.

  • Se o sinalizador de atualização for definido como verdadeiro, mas a chave correspondente ainda não existir no objeto, então o par chave-valor será adicionado.

Exemplos

Insira um terceiro par chave-valor em um objeto que contenha dois pares chave-valor:

SELECT OBJECT_INSERT(OBJECT_CONSTRUCT('a',1,'b',2),'c',3);

----------------------------------------------------+
 OBJECT_INSERT(OBJECT_CONSTRUCT('A',1,'B',2),'C',3) |
----------------------------------------------------+
 {                                                  |
   "a": 1,                                          |
   "b": 2,                                          |
   "c": 3                                           |
 }                                                  |
----------------------------------------------------+
Copy

Insira dois novos pares chave-valor, omitindo um par chave-valor, em um objeto vazio:

  • Key_One consiste em um valor JSON NULL.

  • Key_Two consiste de um valor SQL NULL e é, portanto, omitido.

  • Key_Three consiste em uma cadeia de caracteres contendo “nulo”.

SELECT
  OBJECT_INSERT(OBJECT_INSERT(OBJECT_INSERT(OBJECT_CONSTRUCT(), 'Key_One', PARSE_JSON('NULL')), 'Key_Two', NULL), 'Key_Three', 'null')
  AS obj;

-----------------------+
          OBJ          |
-----------------------+
 {                     |
   "Key_One": null,    |
   "Key_Three": "null" |
 }                     |
-----------------------+
Copy

Atualizar um par chave-valor existente ("k1": 100) com um novo valor ("string-value"):

SELECT OBJECT_INSERT(OBJECT_INSERT(OBJECT_CONSTRUCT(),'k1', 100),'k1','string-value', TRUE) AS obj;

------------------------+
          OBJ           |
------------------------+
 {                      |
   "k1": "string-value" |
 }                      |
------------------------+
Copy