Dans MySQL, le JSON_SEARCH()
renvoie le chemin d'accès à une chaîne donnée dans un document JSON.
Vous fournissez le document JSON comme argument à la fonction. Vous fournissez également l'argument qui détermine la chaîne réelle à rechercher (y compris les caractères d'échappement), ainsi qu'un mot-clé pour indiquer s'il faut renvoyer le chemin de toutes les instances ou d'une seule.
Syntaxe
La syntaxe ressemble à ceci :
JSON_SEARCH(json_doc, one_or_all, search_str[, escape_char[, path] ...])
L'explication de chaque argument suit.
json_doc
est le document JSON à rechercherone_or_all
est le mot-cléone
ouall
. Si vous en utilisezone
, la recherche s'arrête dès que la première occurrence est trouvée. Autrement dit, la fonction ne renvoie que le chemin de la première instance de la chaîne de recherche. Siall
est spécifié, les chemins de toutes les occurrences sont renvoyés de sorte qu'aucun chemin en double n'est inclus. S'il existe plusieurs chemins, ils sont automatiquement regroupés sous forme de tableau.search_str
est la chaîne réelle dont le chemin doit être renvoyé.escape_char
est un caractère facultatif à utiliser comme caractère d'échappement. Il doit s'agir d'une constante vide ou d'un caractère. Si vous ne spécifiez pas cet argument (ou s'il est NULL), le caractère d'échappement est la barre oblique inverse (\
).path
est un argument facultatif pour déterminer où commence le chemin "de niveau supérieur" dans le document JSON.
Dans la search_str
argument, le %
et _
les caractères fonctionnent exactement comme ils le font lorsqu'ils sont utilisés avec le LIKE
opérateur :%
correspond à n'importe quel nombre de caractères (y compris zéro caractère) et _
correspond exactement à un caractère.
Pour spécifier un %
littéral ou _
caractère dans la chaîne de recherche, faites-le précéder du caractère d'échappement.
Exemple 1 - Utilisation de base
Voici un exemple pour illustrer.
SELECT JSON_SEARCH('{"Name":"Bart", "Age":10}', 'one', 'Bart') Résultat ;
Résultat :
+----------+| Résultat |+----------+| "$.Nom" |+----------+
Exemple 2 – Tableaux
Voici un exemple de recherche d'une chaîne dans un tableau.
SET @doc ='{"Name":"Bart", "Hobbies":["Skateboard", "Mischief"]}';SELECT JSON_SEARCH(@doc, 'one', 'Mischief') Result;Résultat :
+----------------+| Résultat |+----------------+| "$.Loisirs[1]" |+----------------+Les tableaux utilisent une numérotation de base zéro, donc ce résultat indique le deuxième élément.
Exemple 3 - Chaîne inexistante
Si vous spécifiez une chaîne qui n'existe pas, une valeur NULL est renvoyée.
SET @doc ='{"Name":"Bart", "Hobbies":["Skateboard", "Mischief"]}';SELECT JSON_SEARCH(@doc, 'one', 'Homer') Résultat ;Résultat :
+--------+| Résultat |+--------+| NULL |+--------+Vous obtiendrez également une valeur NULL si l'un des
json_doc
,search_str
, oupath
les arguments sontNULL
ou si aucun chemin n'existe dans l'objet JSON.Exemple 4 - Occurrences multiples d'une chaîne
Si le document JSON contient plusieurs occurrences de la même chaîne, le résultat dépendra si vous spécifiez
one
ouall
comme deuxième argument.Si vous en utilisez
one
, seule la première occurrence est renvoyée (en supposant qu'il y en ait au moins une) :SET @doc ='{"Name":"Bart", "Friends":["Bart", "Milhouse"]}';SELECT JSON_SEARCH(@doc, 'one', 'Bart') Résultat ;Résultat :
+----------+| Résultat |+----------+| "$.Nom" |+----------+Si vous utilisez
all
, les chemins de toutes les occurrences sont renvoyés. S'il y a plus d'un chemin, ils sont automatiquement enveloppés dans un tableau.SET @doc ='{"Name":"Bart", "Friends":["Bart", "Milhouse"]}';SELECT JSON_SEARCH(@doc, 'all', 'Bart') Résultat ;Résultat :
+----------------------------+| Résultat |+----------------------------+| ["$.Name", "$.Friends[0]"] |+----------------------------+Vous pouvez également spécifier un chemin qui renvoie uniquement les résultats d'un chemin spécifié. Plus d'informations à ce sujet ci-dessous (sous Exemple 8 - Spécifier un chemin ).
Exemple 5 – Caractères génériques
Vous pouvez utiliser des caractères génériques comme spécifié dans la syntaxe ci-dessus. Par exemple, vous pouvez utiliser le
%
pour correspondre à n'importe quel nombre de caractères.SET @doc ='{"Name":"Bart", "Hobbies":["Skateboard", "Mischief"]}';SELECT JSON_SEARCH(@doc, 'one', 'Skate%') Résultat ;Résultat :
+----------------+| Résultat |+----------------+| "$.Loisirs[0]" |+----------------+Et vous pouvez utiliser
_
pour correspondre à un seul caractère.SET @doc ='{"Name":"Bart", "Hobbies":["Skateboard", "Mischief"]}';SELECT JSON_SEARCH(@doc, 'one', 'Bar_') Result;Résultat :
+----------+| Résultat |+----------+| "$.Nom" |+----------+Si nous devions utiliser le
_
dans l'exemple précédent, nous obtiendrions un résultat NULL.SET @doc ='{"Name":"Bart", "Hobbies":["Skateboard", "Mischief"]}';SELECT JSON_SEARCH(@doc, 'one', 'Skate_') Résultat ;Résultat :
+--------+| Résultat |+--------+| NULL |+--------+Exemple 6 - Caractère d'échappement par défaut
Si vous devez rechercher une chaîne qui contient en fait l'un des caractères génériques ci-dessus, vous devrez échapper le caractère. Cela indique à MySQL de l'utiliser comme un littéral de chaîne (au lieu de l'interpréter comme un caractère générique).
SET @doc ='{"userid":"bart_simpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'pass\%word') Résultat ;Résultat :
+---------+| Résultat |+---------+| "$.pwd" |+---------+À première vue, vous pensez peut-être que la barre oblique inverse n'était pas nécessaire, car après tout, nous obtiendrions le même résultat si nous faisions cela :
SET @doc ='{"userid":"bart_simpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'pass%word') Résultat ;Résultat :
+---------+| Résultat |+---------+| "$.pwd" |+---------+Mais le problème avec cette approche est que nous obtenons également le même résultat si nous faisons ceci :
SET @doc ='{"userid":"bart_simpson", "pwd":"pass%BLAH-BLAH-BLAH-word"}';SELECT JSON_SEARCH(@doc, 'one', 'pass%word' ) 'Résultat';Résultat :
+---------+| Résultat |+---------+| "$.pwd" |+---------+Ainsi, la barre oblique inverse informe MySQL que nous ne recherchons qu'une seule instance de
%
en tant que littéral de chaîne, et non pour n'importe quel nombre d'autres caractères.Le même concept s'applique au caractère de soulignement.
Si nous faisons ceci :
SET @doc ='{"userid":"bart_simpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'bart\_simpson') 'Escaped', JSON_SEARCH (@doc, 'one', 'bart_simpson') 'Non échappé';Nous obtenons ceci :
+------------+-------------+| Échappé | Non échappé |+------------+-------------+| "$.userid" | "$.userid" |+------------+---------------------+Les deux approches renvoient le même résultat.
Mais si nous faisons cela (remplacez le _ par J dans l'ID utilisateur) :
SET @doc ='{"userid":"bartJsimpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'bart\_simpson') 'Escaped', JSON_SEARCH (@doc, 'one', 'bart_simpson') 'Non échappé';Nous obtenons ceci :
+---------+-------------+| Échappé | Non échappé |+---------+-------------+| NUL | "$.userid" |+---------+---------------------+Exemple 7 - Caractère d'échappement personnalisé
Vous pouvez spécifier votre propre caractère d'échappement si nécessaire. Vous faites cela en l'incluant comme quatrième argument facultatif.
Voici l'exemple précédent réécrit pour utiliser un caractère d'échappement différent (l'ID utilisateur inclut un
_
caractère).SET @doc ='{"userid":"bart_simpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'bart$_simpson', '$') ' Échappé', JSON_SEARCH(@doc, 'un', 'bart_simpson') 'Non échappé';Résultat :
+------------+-------------+| Échappé | Non échappé |+------------+-------------+| "$.userid" | "$.userid" |+------------+---------------------+Et si on remplaçait le
_
avecJ
dans l'ID utilisateur :SET @doc ='{"userid":"bartJsimpson", "pwd":"pass%word"}';SELECT JSON_SEARCH(@doc, 'one', 'bart$_simpson', '$') ' Échappé', JSON_SEARCH(@doc, 'un', 'bart_simpson') 'Non échappé';Résultat :
+---------+-------------+| Échappé | Non échappé |+---------+-------------+| NUL | "$.userid" |+---------+---------------------+Exemple 8 - Spécifier un chemin
Vous pouvez également spécifier un chemin à partir duquel commencer la recherche. Voici un exemple.
SET @data ='{ "Person":{ "Name":"Bart", "Age":10, "Friends":["Bart", "Milhouse"] } }';SELECT JSON_SEARCH(@data , 'all', 'Bart', NULL, '$.Person.Friends') AS 'Result';Résultat :
+-----------------------+| Résultat |+-----------------------+| "$.Person.Amis[0]" |+-----------------------+Si nous n'avions pas spécifié de chemin, nous obtiendrions le résultat suivant.
SET @data ='{ "Person":{ "Name":"Bart", "Age":10, "Friends":["Bart", "Milhouse"] } }';SELECT JSON_SEARCH(@data , 'tous', 'Bart') AS 'Résultat';Résultat :
+-------------------------------------------------------+| Résultat |+------------------------------------------+| ["$.Person.Name", "$.Person.Friends[0]"] |+---------------------------- --------------+De plus, si nous avions spécifié
one
comme deuxième argument (en plus d'omettre l'argument de chemin), nous nous retrouverions avec ce qui suit :SET @data ='{ "Person":{ "Name":"Bart", "Age":10, "Friends":["Bart", "Milhouse"] } }';SELECT JSON_SEARCH(@data , 'un', 'Bart') AS 'Résultat';Résultat :
+-----------------+| Résultat |+-----------------+| "$.Person.Name" |+-----------------+Exemple 9 – Document vide
Si le document ne contient aucun chemin, vous obtiendrez une valeur NULL.
SELECT JSON_SEARCH('{}', 'all', 'Bart') 'Result';Résultat :
+--------+| Résultat |+--------+| NULL |+--------+