Categorias:: Funções de conversão , Funções de dados semiestruturados e estruturados (Conversão)

TO_JSON¶

Converte um valor de VARIANT em uma cadeia de caracteres contendo a representação JSON do valor.

Sintaxe¶

TO_JSON( <expr> )

Argumentos¶

expr: Uma expressão do tipo VARIANT que contém informações JSON válidas.

Retornos¶

Retorna um valor do tipo VARCHAR.

Se a entrada for NULL, a função retorna NULL.

Notas de uso¶

Se a entrada for NULL, a saída também será NULL. Se a entrada for um VARIANT que contém JSON nulo, então o valor retornado será a cadeia de caracteres "null" (ou seja, a palavra “nulo” delimitada por aspas duplas). Consulte o exemplo abaixo.
Um objeto JSON (também chamado de “dicionário” ou “hash”) é um conjunto desordenado de pares chave-valor. Quando TO_JSON produz uma cadeia de caracteres, a ordem dos pares chave-valor nessa cadeia de caracteres não será previsível.

TO_JSON e PARSE_JSON são funções (quase) conversas ou recíprocas.
- A função PARSE_JSON usa uma cadeia de caracteres como entrada e retorna um VARIANT compatível com JSON.
- A função TO_JSON usa um VARIANT compatível com JSON e retorna uma cadeia de caracteres.
O seguinte é (conceitualmente) verdadeiro se X for uma cadeia de caracteres contendo JSON válido:

X = TO_JSON(PARSE_JSON(X));

Por exemplo, o seguinte é (conceitualmente) verdadeiro:

'{"pi":3.14,"e":2.71}' = TO_JSON(PARSE_JSON('{"pi":3.14,"e":2.71}'))

No entanto, as funções não são perfeitamente recíprocas porque:
- Cadeias de caracteres vazias e cadeias de caracteres com apenas espaço em branco não são tratadas reciprocamente. Por exemplo, o valor de retorno de PARSE_JSON('') é NULL, mas o valor de retorno de TO_JSON(NULL) é NULL, não o '' recíproco.
- A ordem dos pares chave-valor na cadeia de caracteres produzida por TO_JSON não é previsível.
- A cadeia de caracteres produzida por TO_JSON pode ter menos espaço em branco do que a cadeia de caracteres passada para PARSE_JSON.
Por exemplo, os seguintes são JSON equivalentes, mas não cadeias de caracteres equivalentes:
- {"pi": 3.14, "e": 2.71}
- {"e":2.71,"pi":3.14}

Exemplos¶

Os exemplos a seguir usam a função TO_JSON.

Inserção de valores VARIANT e conversão em cadeias de caracteres com uma consulta¶

Criar e preencher uma tabela. A instrução INSERT usa a função PARSE_JSON para inserir um valor VARIANT na coluna v da tabela.

CREATE OR REPLACE TABLE jdemo1 (v VARIANT);
INSERT INTO jdemo1 SELECT PARSE_JSON('{"food":"bard"}');

Consulte os dados e use a função TO_JSON para converter o valor VARIANT em uma cadeia de caracteres.

SELECT v, v:food, TO_JSON(v) FROM jdemo1;

+------------------+--------+-----------------+
| V                | V:FOOD | TO_JSON(V)      |
|------------------+--------+-----------------|
| {                | "bard" | {"food":"bard"} |
|   "food": "bard" |        |                 |
| }                |        |                 |
+------------------+--------+-----------------+

Manipulação de valores NULL com as funções PARSE_JSON e TO_JSON¶

O exemplo a seguir mostra como PARSE_JSON e TO_JSON manipula valores NULL:

SELECT TO_JSON(NULL), TO_JSON('null'::VARIANT),
       PARSE_JSON(NULL), PARSE_JSON('null');

+---------------+--------------------------+------------------+--------------------+
| TO_JSON(NULL) | TO_JSON('NULL'::VARIANT) | PARSE_JSON(NULL) | PARSE_JSON('NULL') |
|---------------+--------------------------+------------------+--------------------|
| NULL          | "null"                   | NULL             | null               |
+---------------+--------------------------+------------------+--------------------+

Comparação de PARSE_JSON e TO_JSON¶

Os exemplos a seguir demonstram a relação entre as funções PARSE_JSON e TO_JSON.

Este exemplo cria uma tabela com uma coluna VARCHAR e uma coluna VARIANT. A instrução INSERT insere um valor VARCHAR, e a instrução UPDATE gera um valor JSON que corresponde a esse valor VARCHAR.

CREATE OR REPLACE TABLE jdemo2 (
  varchar1 VARCHAR, 
  variant1 VARIANT);

INSERT INTO jdemo2 (varchar1) VALUES ('{"PI":3.14}');

UPDATE jdemo2 SET variant1 = PARSE_JSON(varchar1);

Esta consulta mostra que TO_JSON e PARSE_JSON são funções conceitualmente recíprocas:

SELECT varchar1, 
       PARSE_JSON(varchar1), 
       variant1, 
       TO_JSON(variant1),
       PARSE_JSON(varchar1) = variant1, 
       TO_JSON(variant1) = varchar1
  FROM jdemo2;

+-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------+
| VARCHAR1    | PARSE_JSON(VARCHAR1) | VARIANT1     | TO_JSON(VARIANT1) | PARSE_JSON(VARCHAR1) = VARIANT1 | TO_JSON(VARIANT1) = VARCHAR1 |
|-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------|
| {"PI":3.14} | {                    | {            | {"PI":3.14}       | True                            | True                         |
|             |   "PI": 3.14         |   "PI": 3.14 |                   |                                 |                              |
|             | }                    | }            |                   |                                 |                              |
+-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------+

Entretanto, as funções não são exatamente recíprocas. Diferenças nos espaços em branco ou na ordem dos pares chave-valor podem impedir que a saída corresponda à entrada. Por exemplo:

SELECT TO_JSON(PARSE_JSON('{"b":1,"a":2}')),
       TO_JSON(PARSE_JSON('{"b":1,"a":2}')) = '{"b":1,"a":2}',
       TO_JSON(PARSE_JSON('{"b":1,"a":2}')) = '{"a":2,"b":1}';

+--------------------------------------+--------------------------------------------------------+--------------------------------------------------------+
| TO_JSON(PARSE_JSON('{"B":1,"A":2}')) | TO_JSON(PARSE_JSON('{"B":1,"A":2}')) = '{"B":1,"A":2}' | TO_JSON(PARSE_JSON('{"B":1,"A":2}')) = '{"A":2,"B":1}' |
|--------------------------------------+--------------------------------------------------------+--------------------------------------------------------|
| {"a":2,"b":1}                        | False                                                  | True                                                   |
+--------------------------------------+--------------------------------------------------------+--------------------------------------------------------+