Categorias:: Funções de dados semiestruturados e estruturados (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.

Para OBJECTs estruturados:

Para os argumentos que são chaves, você deve especificar constantes.

Quando o argumento updateFlag é FALSE (quando você está inserindo um novo par chave-valor):

Se você especificar uma chave que já existe em OBJECT, ocorrerá um erro.

SELECT OBJECT_INSERT(
  {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
  'city',
  'San Jose',
  false
);

Copy

093202 (23001): Function OBJECT_INSERT:
  expected structured object to not contain field city but it did.

A função retorna um OBJECT estruturado. O tipo de OBJECT inclui a chave recém-inserida. Por exemplo, suponha que você adicione a chave zipcode com o valor DOUBLE 94402:

SELECT
  OBJECT_INSERT(
    {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
    'zip_code',
    94402::DOUBLE,
    false
  ) AS new_object,
  SYSTEM$TYPEOF(new_object);

Copy

A função retorna um OBJECT do tipo OBJECT(cidade VARCHAR, estado VARCHAR, CEP DOUBLE):

+-------------------------------------+---------------------------------------------------------------------------------------+
| NEW_OBJECT                          | SYSTEM$TYPEOF(NEW_OBJECT)                                                             |
|-------------------------------------+---------------------------------------------------------------------------------------|
| {                                   | OBJECT(city VARCHAR(16777216), state VARCHAR(16777216), zip_code FLOAT NOT NULL)[LOB] |
|   "city": "San Mateo",              |                                                                                       |
|   "state": "CA",                    |                                                                                       |
|   "zip_code": 9.440200000000000e+04 |                                                                                       |
| }                                   |                                                                                       |
+-------------------------------------+---------------------------------------------------------------------------------------+

O tipo do valor inserido determina o tipo adicionado à definição de tipo OBJECT. Nesse caso, o valor de zipcode é um valor convertido em DOUBLE, portanto, o tipo de zipcode é DOUBLE.

Quando o argumento updateFlag é TRUE (quando você está substituindo um par chave-valor existente):
- Se você especificar uma chave que não existe em OBJECT, ocorrerá um erro.
- A função retorna um OBJECT estruturado do mesmo tipo.
- O tipo do valor inserido é imposto ao tipo da chave existente.

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