MariaDB JSON_EXTRACT() expliqué

Dans MariaDB, JSON_EXTRACT() est une fonction intégrée qui extrait les données d'un document JSON, en fonction d'un ou plusieurs chemins donnés.

Il peut renvoyer des valeurs uniques et plusieurs valeurs. Si une seule valeur correspond, une seule valeur est renvoyée. Si plusieurs valeurs correspondent, ces valeurs sont renvoyées dans un tableau.

Syntaxe

La syntaxe ressemble à ceci :

JSON_EXTRACT(json_doc, path[, path] ...)

Où json_doc est le document JSON, et chaque path argument est un chemin dans le document.

Exemple

Voici un exemple pour illustrer.

SET @json_document = '
    { 
        "name": "Wag", 
        "type": "Dog", 
        "weight": 20 
    }
';
SELECT JSON_EXTRACT(@json_document, '$.name');

Résultat :

+----------------------------------------+
| JSON_EXTRACT(@json_document, '$.name') |
+----------------------------------------+
| "Wag"                                  |
+----------------------------------------+

Chemins multiples

Voici un exemple de spécification de plusieurs chemins afin de renvoyer plusieurs valeurs à partir du document JSON.

Lorsque vous renvoyez plusieurs valeurs, elles sont renvoyées dans un tableau.

SET @json_document = '
    { 
        "name": "Wag", 
        "type": "Dog", 
        "weight": 20 
    }
';
SELECT JSON_EXTRACT(@json_document, '$.name', '$.weight');

Résultat :

+----------------------------------------------------+
| JSON_EXTRACT(@json_document, '$.name', '$.weight') |
+----------------------------------------------------+
| ["Wag", 20]                                        |
+----------------------------------------------------+

Chemins inexistants

Passer un chemin qui n'existe pas dans le document JSON donne NULL .

Exemple :

SET @json_document = '
    { 
        "name": "Wag", 
        "type": "Dog", 
        "weight": 20 
    }
';
SELECT JSON_EXTRACT(@json_document, '$.color');

Résultat :

+-----------------------------------------+
| JSON_EXTRACT(@json_document, '$.color') |
+-----------------------------------------+
| NULL                                    |
+-----------------------------------------+

Cependant, si plusieurs chemins sont transmis et qu'au moins l'un d'entre eux correspond, la valeur correspondante est extraite et renvoyée dans un tableau. Cela est vrai même si une seule valeur est extraite.

Exemple :

SET @json_document = '
    { 
        "name": "Wag", 
        "type": "Dog", 
        "weight": 20 
    }
';
SELECT JSON_EXTRACT(@json_document, '$.name', '$.color');

Résultat :

+---------------------------------------------------+
| JSON_EXTRACT(@json_document, '$.name', '$.color') |
+---------------------------------------------------+
| ["Wag"]                                           |
+---------------------------------------------------+

Tableaux

Voici un exemple d'extraction de données d'un tableau :

SET @json_document = '
    { 
        "_id" : 1, 
        "awards" : [ "Top Dog", "Best Dog", "Biggest Dog" ] 
    }
';
SELECT JSON_EXTRACT(@json_document, '$.awards[0]');

Résultat :

+---------------------------------------------+
| JSON_EXTRACT(@json_document, '$.awards[0]') |
+---------------------------------------------+
| "Top Dog"                                   |
+---------------------------------------------+

Les tableaux sont basés sur zéro, et donc $.awards[0] extrait le premier élément des awards tableau.

Objets imbriqués

Voici un exemple d'extraction de données d'un objet imbriqué dans un autre objet :

SET @json_document = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "Florida Dog Awards" : "Top Dog", 
                "New York Marathon" : "Fastest Dog", 
                "Sumo 2020" : "Biggest Dog"
            }
        }
    }
';
SELECT JSON_EXTRACT(
    @json_document, 
    '$.details.awards.New York Marathon'
    ) AS Result;

Résultat :

+---------------+
| Result        |
+---------------+
| "Fastest Dog" |
+---------------+

Cependant, si nous voulions extraire toutes les récompenses, nous pourrions raccourcir le chemin vers $.details.awards :

SET @json_document = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "Florida Dog Awards" : "Top Dog", 
                "New York Marathon" : "Fastest Dog", 
                "Sumo 2020" : "Biggest Dog"
            }
        }
    }
';
SELECT JSON_EXTRACT(
    @json_document, 
    '$.details.awards'
    ) AS Result;

Résultat :

+---------------------------------------------------------------------------------------------------+
| Result                                                                                            |
+---------------------------------------------------------------------------------------------------+
| {"Florida Dog Awards": "Top Dog", "New York Marathon": "Fastest Dog", "Sumo 2020": "Biggest Dog"} |
+---------------------------------------------------------------------------------------------------+

Embellissez le résultat

Nous pouvons rendre le résultat plus facile à lire en passant JSON_EXTRACT() au JSON_DETAILED() fonction :

SET @json_document = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "Florida Dog Awards" : "Top Dog", 
                "New York Marathon" : "Fastest Dog", 
                "Sumo 2020" : "Biggest Dog"
            }
        }
    }
';
SELECT 
    JSON_DETAILED(
        JSON_EXTRACT(
            @json_document, 
            '$.details.awards'
            ) 
    ) AS Result;

Résultat :

+------------------------------------------------+
| Result                                         |
+------------------------------------------------+
| {
    "Florida Dog Awards": "Top Dog",
    "New York Marathon": "Fastest Dog",
    "Sumo 2020": "Biggest Dog"
} |
+------------------------------------------------+

Arguments nuls

Si un argument est NULL , le résultat est NULL :

SELECT 
    JSON_EXTRACT(null, '$.type'),
    JSON_EXTRACT('{"a":1}', null);

Résultat :

+------------------------------+-------------------------------+
| JSON_EXTRACT(null, '$.type') | JSON_EXTRACT('{"a":1}', null) |
+------------------------------+-------------------------------+
| NULL                         | NULL                          |
+------------------------------+-------------------------------+

Nombre de paramètres incorrect

Ne fournir aucun argument génère une erreur :

SELECT JSON_EXTRACT();

Résultat :

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_EXTRACT'

Il en va de même lorsque vous fournissez trop ou trop peu d'arguments :

SELECT JSON_EXTRACT('{ "a": 1}');

Résultat :

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_EXTRACT'