TO_JSON¶

Sintaxe¶

TO_JSON( <expr> )

Argumentos¶

expr

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

Retornos¶

O valor retornado é do tipo VARCHAR.

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). Um exemplo está incluído na seção Exemplos 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) não é ''.

  • 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¶

Este é um pequeno exemplo de TO_JSON e PARSE_JSON:

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

Copy

SELECT v, v:food, TO_JSON(v) FROM jdemo1;
+------------------+--------+-----------------+
| V                | V:FOOD | TO_JSON(V)      |
|------------------+--------+-----------------|
| {                | "bard" | {"food":"bard"} |
|   "food": "bard" |        |                 |
| }                |        |                 |
+------------------+--------+-----------------+

Copy

O exemplo a seguir mostra o tratamento de NULL para PARSE_JSON e TO_JSON:

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               |
+---------------+--------------------------+------------------+--------------------+

Copy

Os exemplos a seguir demonstram a relação entre PARSE_JSON, TO_JSON e TO_VARIANT:

Criar uma tabela e adicionar dados VARCHAR, genéricos VARIANT e VARIANT compatíveis com JSON. A instrução INSERT insere um valor VARCHAR, e a instrução UPDATE gera um valor JSON que corresponde a esse VARCHAR.

CREATE or replace TABLE jdemo2 (varchar1 VARCHAR, variant1 VARIANT,
    variant2 VARIANT);
INSERT INTO jdemo2 (varchar1) VALUES ('{"PI":3.14}');
UPDATE jdemo2 SET variant1 = PARSE_JSON(varchar1);

Copy

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 |                   |                                 |                              |
|             | }                    | }            |                   |                                 |                              |
+-------------+----------------------+--------------+-------------------+---------------------------------+------------------------------+

Copy

No entanto, as funções não são exatamente recíprocas; diferenças no espaço 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                                                   |
+--------------------------------------+--------------------------------------------------------+--------------------------------------------------------+

Copy

Embora ambos PARSE_JSON e TO_VARIANT possam pegar uma cadeia de caracteres e retornar uma variante, eles não são equivalentes. O seguinte código usa PARSE_JSON para atualizar uma coluna e TO_VARIANT para atualizar a outra coluna. (A atualização da coluna variant1 é desnecessária porque foi atualizada anteriormente usando uma chamada de função idêntica; entretanto, o código abaixo a atualiza novamente para que você possa ver lado a lado quais funções são chamadas para atualizar as colunas).

UPDATE jdemo2 SET
    variant1 = PARSE_JSON(varchar1),
    variant2 = TO_VARIANT(varchar1);

Copy

A consulta abaixo mostra que a saída de PARSE_JSON e a saída de TO_VARIANT não são a mesma. Além da(s) diferença(s) trivial(is) no espaço em branco, existem diferenças significativas nas aspas.

SELECT variant1, variant2, variant1 = variant2 FROM jdemo2;
+--------------+-----------------+---------------------+
| VARIANT1     | VARIANT2        | VARIANT1 = VARIANT2 |
|--------------+-----------------+---------------------|
| {            | "{\"PI\":3.14}" | False               |
|   "PI": 3.14 |                 |                     |
| }            |                 |                     |
+--------------+-----------------+---------------------+

Copy