Catégories :

Fonctions de conversion , Fonctions de données semi-structurées (conversion)

TO_JSON

Convertit une valeur VARIANT en une chaîne contenant la représentation JSON de la valeur. Si l’entrée est NULL, le résultat est également NULL.

Syntaxe

TO_JSON( <expr> )

Arguments

expr

Expression de type VARIANT contenant des informations valides JSON.

Renvoie

La valeur renvoyée est de type VARCHAR.

Notes sur l’utilisation

  • Si l’entrée est NULL, la sortie est NULL aussi. Si l’entrée est un VARIANT qui contient JSON null, alors la valeur retournée est la chaîne '"null"' (c’est-à-dire le mot « null » entouré de guillemets doubles). Un exemple est inclus dans la section Exemples ci-dessous.

  • Un objet JSON (également appelé « dictionnaire » ou « hachage ») est un ensemble non ordonné de paires clé-valeur. Lorsque TO_JSON génère une chaîne, l’ordre des paires clé-valeur dans cette chaîne n’est pas prévisible.

  • TO_JSON et PARSE_JSON sont des fonctions (presque) inverses ou réciproques.

    • La fonction PARSE_JSON prend une chaîne en entrée et renvoie une variante compatible avec JSON.

    • La fonction TO_JSON utilise une variante compatible avec JSON et renvoie une chaîne.

    Conceptuellement, ce qui suit est vrai si X est une chaîne contenant du code JSON valide :

    X = TO_JSON(PARSE_JSON(X));

    Par exemple, ce qui suit est vrai (conceptuellement) :

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

    Cependant, les fonctions ne sont pas parfaitement réciproques pour deux raisons :

    • L’ordre des paires clé-valeur dans la chaîne produite par TO_JSON n’est pas prévisible.

    • La chaîne produite par TO_JSON peut avoir moins d’espaces que la chaîne transmise à PARSE_JSON.

    Les éléments suivants sont des équivalents JSON, mais pas des chaînes équivalentes :

    • {"pi": 3.14, "e": 2.71}

    • {"e":2.71,"pi":3.14}

Exemples

Voici un bref exemple de TO_JSON et PARSE_JSON :

CREATE TABLE jdemo1 (v VARIANT);
INSERT INTO jdemo1 SELECT PARSE_JSON('{"food":"bard"}');
SELECT v, v:food, TO_JSON(v) FROM jdemo1;
+------------------+--------+-----------------+
| V                | V:FOOD | TO_JSON(V)      |
|------------------+--------+-----------------|
| {                | "bard" | {"food":"bard"} |
|   "food": "bard" |        |                 |
| }                |        |                 |
+------------------+--------+-----------------+

L’exemple suivant montre le traitement de NULL pour PARSE_JSON et 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               |
+---------------+--------------------------+------------------+--------------------+

Les exemples suivants illustrent la relation entre PARSE_JSON, TO_JSON et TO_VARIANT :

Créez une table et ajoutez des données VARCHAR, VARIANT génériques et VARIANT compatibles avec JSON. L’instruction INSERT insère une valeur VARCHAR et l’instruction UPDATE génère une valeur JSON qui correspond à ce 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);

Cette requête montre que TO_JSON et PARSE_JSON sont des fonctions conceptuellement réciproques :

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

Cependant, les fonctions ne sont pas exactement réciproques ; des différences dans les espaces ou l’ordre des paires clé-valeur peuvent empêcher la sortie de correspondre à l’entrée. Par exemple :

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

Bien que PARSE_JSON et TO_VARIANT puissent prendre une chaîne et renvoyer une variante, ils ne sont pas équivalents. Le code suivant utilise PARSE_JSON pour mettre à jour une colonne et TO_VARIANT pour mettre à jour l’autre colonne. (La mise à jour vers la colonne variant1 n’est pas nécessaire, car elle a déjà été mise à jour à l’aide d’un appel de fonction identique. Toutefois, le code ci-dessous le met à jour pour que vous puissiez voir côte à côte quelles fonctions sont appelées pour mettre à jour les colonnes).

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

La requête ci-dessous montre que la sortie de PARSE_JSON et la sortie de TO_VARIANT ne sont pas les mêmes. Outre les différences triviales d’espaces, il existe des différences plus importantes au niveau des guillemets.

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