JSON_QUERY

Syntaxe

Paramètres

Description

Cette fonction permet d'extraire une partie d'un document JSON sous forme de texte JSON, en respectant la hiérarchie JSON. Elle est souvent utilisée pour naviguer dans des structures JSON complexes.

Remarques

• Extraction hiérarchique précise : La fonction JSON_QUERY permet une extraction ciblée à l'intérieur d'un document JSON, en conservant la structure hiérarchique des objets et des tableaux. Cela la rend particulièrement utile lorsqu'on veut manipuler des blocs entiers de JSON, comme des sous-objets imbriqués, sans les aplatir.
• Utilisation fréquente avec des documents JSON complexes : Dans les cas où une colonne contient du JSON semi-structuré, JSON_QUERY est préférable à JSON_VALUE, car elle permet de récupérer non pas une valeur scalaire, mais un fragment JSON complet, souvent représenté par des accolades ou des crochets ({}, []).
• Respect de la validité JSON du résultat : Le résultat retourné par JSON_QUERY est toujours une chaîne JSON bien formée. Oracle s'assure que l'extrait renvoyé respecte les règles du format JSON (par exemple, pas de simple valeur scalaire isolée comme 42, mais un tableau [42] ou un objet {"val":42} si besoin).
• Importance du chemin JSON (path expression) : Le paramètre JSON_basic_path_expression est central : il détermine ce qui sera extrait du document. Une mauvaise expression peut retourner un résultat vide ou déclencher des erreurs, surtout si la structure du document varie selon les lignes.
• Résultat toujours sous forme de texte : Le retour de JSON_QUERY est une chaîne JSON textuelle, et non une structure manipulable directement comme un objet. Cela signifie qu'elle est souvent utilisée comme intermédiaire, par exemple pour transmettre un sous-document à une application ou à une autre fonction SQL.
• Utilisation de FORMAT JSON avec prudence : Lorsque le paramètre FORMAT JSON est activé, Oracle considère que l'entrée est déjà un document JSON valide. Cela évite une double validation ou une transformation implicite, mais cela peut aussi causer une erreur si la chaîne n'est pas correctement formatée.
• Contrôle du comportement en cas d'erreur (ON ERROR) : Le paramètre JSON_query_on_error_clause est essentiel en production. Il permet d'éviter qu'un document mal formé ou une mauvaise requête JSON provoque l'échec complet de la requête SQL. En choisissant NULL ON ERROR, l'exécution peut se poursuivre proprement.
• Gestion des cas vides avec ON EMPTY : Lorsque le chemin JSON ciblé ne correspond à aucune donnée, il est possible d'indiquer à Oracle de renvoyer NULL, un tableau vide ([]), ou un objet vide ({}). Cela offre une flexibilité intéressante dans les cas où les données JSON sont partiellement structurées.
• Encapsulation avec WRAPPER utile pour homogénéiser les résultats : En forçant l'encapsulation (WITH WRAPPER), on peut s'assurer que même une valeur unique sera retournée sous forme de tableau JSON. Cela facilite le traitement automatique côté application, en évitant des résultats incohérents (valeur seule vs tableau).
• Prise en charge des grands volumes avec le clause RETURNING : La clause JSON_query_returning_clause permet de spécifier un type retour comme CLOB, ce qui est utile pour les extraits JSON de grande taille. En l'absence de cette clause, le système utilise une valeur par défaut (VARCHAR2), pouvant tronquer le résultat si celui-ci est trop volumineux.
• Complémentarité avec JSON_TABLE et JSON_VALUE : Bien que JSON_QUERY soit puissante pour extraire des fragments, elle est souvent utilisée en combinaison avec JSON_TABLE (pour projeter sous forme de table) ou JSON_VALUE (pour extraire des scalaires), selon le type d'analyse souhaitée.
• Utilité dans les API REST ou les échanges JSON : Dans un contexte de base de données exposée via des API REST (comme Oracle REST Data Services), JSON_QUERY est pratique pour renvoyer directement un sous-ensemble structuré du document stocké, tout en s'assurant de la conformité au standard JSON.