MariaDB JSON_SEARCH() expliqué

Dans MariaDB, JSON_SEARCH() est une fonction intégrée qui vous permet d'obtenir le chemin vers une valeur donnée dans un document JSON.

Il accepte le document JSON et une chaîne comme arguments, et renvoie le chemin d'accès à la chaîne donnée dans le document.

Syntaxe

La syntaxe ressemble à ceci :

JSON_SEARCH(
    json_doc, 
    return_arg, 
    search_str[, escape_char[, path] ...]
    ) 

Où :

• json_doc est le document JSON et search_str est la chaîne.
• return_arg est le mot-clé one ou all . Si vous en utilisez one , seul le premier chemin est renvoyé. Toutes les autres occurrences sont ignorées. Le chemin considéré comme "premier" n'est pas défini (selon la documentation de MariaDB). Si all est spécifié, les chemins de toutes les occurrences sont renvoyés. S'il existe plusieurs chemins, ils sont automatiquement regroupés sous forme de tableau.
• Le escape_char argument est un caractère facultatif à utiliser comme caractère d'échappement.
• Le path argument est un argument facultatif pour déterminer où commence le chemin de "niveau supérieur" dans le document JSON.

Exemple

Voici un exemple pour illustrer :

SET @json = '
    { 
        "name" : "Wag", 
        "type" : "Dog" 
    }';

SELECT JSON_SEARCH(@json, 'one', 'Wag'); 

Résultat :

+------------------------------------------------+| JSON_SEARCH(@json, 'un', 'Wag') |+----------------------------------+ | "$.nom" |+------------------------------------------------+

Voici un exemple de renvoi du chemin d'un élément dans un tableau :

SET @json = '
    { 
        "product" : "Left Handed Screwdriver", 
        "sizes" : [ "Small", "Medium", "Large" ],
    }';

SELECT JSON_SEARCH(@json, 'one', 'Medium'); 

Résultat :

+--------------------------------------------------+| JSON_SEARCH(@json, 'un', "Moyen") |+----------------------------------- --+| "$.tailles[1]" |+--------------------------------------------------+ 

 Les tableaux sont basés sur zéro, et donc $.sizes[1] fait référence au deuxième élément du tableau.
 
Occurrences multiples
 

 Si vous souhaitez renvoyer tous les chemins contenant la chaîne, utilisez all au lieu de one pour le deuxième argument.
 
SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'all', 'Dog'); 
 

 Résultat :
 
+------------------------------------------------+| JSON_SEARCH(@json, 'tous', "Chien") |+----------------------------------+ | ["$[0].type", "$[1].type"] |+----------------------------- -----+
 

 Si nous changeons all à one , voici ce qui se passe :
 
SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'one', 'Dog'); 
 

 Résultat :
 
+------------------------------------------------+| JSON_SEARCH(@json, 'un', "Chien") |+----------------------------------+ | "$[0].type" |+------------------------------------------------+
 

 Un seul chemin est renvoyé. 
 
Spécifier un chemin
 

 Voici un exemple qui spécifie un chemin à rechercher dans le document :
 
SET @json = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "NZ Dog Award" : "Top Dog", 
                "New York Marathon" : "Fastest Animal", 
                "Sumo 2021" : "Biggest Dog"
            }
        }
    }
';
SELECT JSON_SEARCH(
    @json, 
    'all',
    '%dog%',
    NULL,
    '$.details.awards'
    ) AS Result; 
 

 Résultat :
 
+------------------------------------------------------------ -------------------+| Résultat |+------------------------------------------------------------ ------------------+| ["$.details.awards.NZ Dog Award", "$.details.awards.Sumo 2021"] |+------------------------ -----------------------------------------+
 

 Dans ce cas, la chaîne dog se produit en fait trois fois dans le document, mais seulement deux fois en dessous du chemin spécifié.
 

 De plus, nous avons utilisé NULL pour l'argument du caractère d'échappement, ce qui entraîne l'utilisation du caractère d'échappement par défaut, qui est la barre oblique inverse (\ ). 
 
Caractère d'échappement par défaut
 

 Par défaut, le caractère d'échappement est une barre oblique inverse (\ ). 
 

 Exemple :
 
SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my\%pwd') AS "Escaped"; 
 

 Résultat :
 
+--------------------------------------------------+------- -----+| Pas échappé | Échappé |+--------------------------------------------------+-------- ----+| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |+-------------------------------------------+- -----------+
 

 Le signe de pourcentage (% ) est un caractère générique qui correspond à n'importe quel nombre de caractères. Par conséquent, si nous ne lui échappons pas, il correspondra à n'importe quel nombre de caractères, y compris les caractères qui ne sont pas des signes de pourcentage.
 

 Mais lorsque nous échappons au signe de pourcentage avec le caractère d'échappement, cela ne correspondra que s'il y a exactement un signe de pourcentage à cet endroit. 
 

 Les résultats ci-dessus en témoignent.
 
Spécifiez un caractère d'échappement personnalisé
 

 Vous pouvez spécifier un caractère d'échappement personnalisé si nécessaire. Pour ce faire, indiquez-le comme quatrième argument.
 

 Exemple :
 
SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd', '!') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my!%pwd', '!') AS "Escaped"; 
 

 Résultat :
 
+--------------------------------------------------+------- -----+| Pas échappé | Échappé |+--------------------------------------------------+-------- ----+| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |+-------------------------------------------+- -----------+
 

 Nous obtenons donc le même résultat que dans l'exemple précédent. La seule différence est que nous avons spécifié un caractère d'échappement différent. Dans ce cas, nous avons précisé que le point d'exclamation (! ) est le caractère d'échappement.
 
Arguments nuls
 

 Si l'un des arguments de chaîne de recherche, de chaîne de recherche ou de chemin est NULL , le résultat est NULL :
 
SELECT 
    JSON_SEARCH(null, 'all', 's', '', '$') AS a,
    JSON_SEARCH('{"a":1}', 'all', null, '', '$') AS b,
    JSON_SEARCH('{"a":1}', 'all', 's', '', null) AS c; 
 

 Résultat :
 
+------+------+------+| un | b | c |+------+------+------+| NUL | NUL | NULL |+------+------+------+
 
Nombre de paramètres incorrect
 

 Ne fournir aucun argument génère une erreur :
 
SELECT JSON_SEARCH(); 
 

 Résultat :
 
ERREUR 1582 (42000) :Nombre de paramètres incorrect dans l'appel à la fonction native 'JSON_SEARCH'
 

 Il en va de même lorsque vous fournissez trop peu d'arguments :
 
SELECT JSON_SEARCH('{"a":1}', 'all'); 
 

 Résultat :
 
ERREUR 1582 (42000) :Nombre de paramètres incorrect dans l'appel à la fonction native 'JSON_SEARCH'