Fonction JSON_QUERY() dans Oracle

Dans Oracle Database, le JSON_QUERY() La fonction sélectionne et renvoie une ou plusieurs valeurs à partir des données JSON et renvoie ces valeurs.

Vous pouvez utiliser la fonction pour récupérer des fragments d'un document JSON.

Syntaxe

La syntaxe ressemble à ceci :

JSON_QUERY
  ( expr [ FORMAT JSON ], JSON_basic_path_expression
    [ JSON_query_returning_clause ] [ JSON_query_wrapper_clause ]
    [ JSON_query_on_error_clause ] [ JSON_query_on_empty_clause ]
  )

Où :

• expr est le document JSON que vous souhaitez interroger
• JSON_basic_path_expression est le chemin SQL/JSON que vous souhaitez renvoyer à partir de ce document JSON. La fonction utilise l'expression de chemin pour évaluer expr et recherchez une ou plusieurs valeurs JSON qui correspondent ou satisfont à l'expression de chemin. L'expression de chemin doit être un littéral de texte.
• JSON_query_returning_clause spécifie le type de données et le format de la chaîne de caractères renvoyée par la fonction.
• JSON_query_wrapper_clause contrôle si la fonction enveloppe les valeurs renvoyées dans un wrapper de tableau (crochets ([] )).
• JSON_query_on_error_clause spécifie la valeur renvoyée lorsque certaines erreurs se produisent.
• JSON_query_on_empty_clause spécifie la valeur renvoyée si aucune correspondance n'est trouvée lorsque les données JSON sont évaluées à l'aide de l'expression de chemin SQL/JSON.

Voir la documentation Oracle pour une explication détaillée des clauses facultatives.

Exemple

Voici un exemple pour montrer comment le JSON_QUERY() la fonction fonctionne :

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$')
FROM DUAL;

Résultat :

{"a":1,"b":2,"c":3}

L'utilisation du signe dollar seul renvoie la chaîne entière de données JSON.

Avec emballage

Vous pouvez utiliser le WITH WRAPPER clause pour envelopper le résultat dans un wrapper de tableau :

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH WRAPPER)
FROM DUAL;

Résultat :

[{"a":1,"b":2,"c":3}]

Vous devez spécifier cette clause si l'expression de chemin correspond à une seule valeur scalaire (une valeur qui n'est pas un objet JSON ou un tableau JSON) ou à plusieurs valeurs de n'importe quel type.

Par exemple, retourner la valeur scalaire suivante doit être fait avec le WITH WRAPPER clause :

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH WRAPPER)
FROM DUAL;

Résultat :

[2]

Omettre le WITH WRAPPER clause lors du renvoi d'une valeur scalaire entraîne le renvoi d'une valeur nulle :

SET NULL 'null';
SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b')
FROM DUAL;

Résultat :

null

Par défaut, SQLcl et SQL*Plus renvoient un espace vide chaque fois que null se produit à la suite d'un SQL SELECT déclaration.

Cependant, vous pouvez utiliser SET NULL pour spécifier une autre chaîne à renvoyer. Ici, j'ai précisé que la chaîne null doit être retourné.

Avec wrapper conditionnel

Alternativement, vous pouvez utiliser le WITH CONDITIONAL WRAPPER clause pour inclure le wrapper de tableau uniquement si l'expression de chemin correspond à une seule valeur scalaire ou à plusieurs valeurs de n'importe quel type. Si l'expression de chemin correspond à un seul objet JSON ou tableau JSON, le wrapper de tableau est omis :

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH CONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH CONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Résultat :

                    r1     r2 
______________________ ______ 
{"a":1,"b":2,"c":3}    [2]   

Dans ce cas, seule la valeur scalaire a le wrapper de tableau appliqué.

Juste pour être clair, le voici avec un wrapper inconditionnel :

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH UNCONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH UNCONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Résultat :

                      r1     r2 
________________________ ______ 
[{"a":1,"b":2,"c":3}]    [2]   

Cette fois, le wrapper est appliqué aux deux résultats.

Notez que WITH UNCONDITIONAL WRAPPER est l'équivalent de WITH WRAPPER .

Gestion des erreurs

Il existe cinq clauses que vous pouvez utiliser pour spécifier ce qu'il faut renvoyer chaque fois que certains types d'erreurs se produisent. Les clauses sont :

• NULL ON ERROR – Renvoie null lorsqu'une erreur se produit. C'est la valeur par défaut.
• ERROR ON ERROR – Renvoie l'erreur Oracle appropriée lorsqu'une erreur se produit.
• EMPTY ON ERROR – Spécifier cette clause équivaut à spécifier EMPTY ARRAY ON ERROR .
• EMPTY ARRAY ON ERROR – Retourne un tableau JSON vide ([] ) lorsqu'une erreur se produit.
• EMPTY OBJECT ON ERROR – Renvoie un objet JSON vide ({} ) lorsqu'une erreur se produit.

Voici un exemple :

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' NULL ON ERROR) AS "r1",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON ERROR) AS "r2",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY OBJECT ON ERROR) AS "r3"
FROM DUAL;

Résultat :

     r1    r2    r3 
_______ _____ _____ 
null    []    {}   

Le voici avec le ERROR ON ERROR clause :

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' ERROR ON ERROR)
FROM DUAL;

Résultat :

Error report -
ORA-40462: JSON_VALUE evaluated to no value

Ces clauses d'erreur permettent de gérer les erreurs suivantes :

• Le premier argument n'est pas une donnée JSON bien formée utilisant une syntaxe JSON stricte ou laxiste
• Aucune correspondance n'est trouvée lorsque les données JSON sont évaluées à l'aide de l'expression de chemin SQL/JSON. Vous pouvez remplacer le comportement de ce type d'erreur en spécifiant la JSON_query_on_empty_clause .
• Le type de données de la valeur de retour n'est pas assez grand pour contenir la chaîne de caractères de retour
• La fonction correspond à une seule valeur scalaire ou à plusieurs valeurs de n'importe quel type, et aucune clause wrapper n'est spécifiée

Gestion des résultats vides

Vous pouvez également utiliser une clause pour spécifier la valeur renvoyée si aucune correspondance n'est trouvée. Cette clause vous permet de spécifier un résultat différent pour ce type d'erreur que le résultat spécifié avec les clauses d'erreur.

Ces clauses sont :

• NULL ON EMPTY – Renvoie null lorsqu'aucune correspondance n'est trouvée.
• ERROR ON EMPTY – Renvoie l'erreur Oracle appropriée lorsqu'aucune correspondance n'est trouvée.
• EMPTY ON EMPTY – Spécifier cette clause équivaut à spécifier EMPTY ARRAY ON EMPTY .
• EMPTY ARRAY ON EMPTY – Retourne un tableau JSON vide ([] ) lorsqu'aucune correspondance n'est trouvée.
• EMPTY OBJECT ON EMPTY – Renvoie un objet JSON vide ({} ) lorsqu'aucune correspondance n'est trouvée.

Exemple :

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON EMPTY)
FROM DUAL;

Résultat :

[]

Si vous omettez cette clause, la clause d'erreur détermine la valeur renvoyée lorsqu'aucune correspondance n'est trouvée.