JSON_QUERY (Transact-SQL)

S’applique à : SQL Server 2016 (13.x) et versions ultérieures Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

Extrait un objet ou un tableau à partir d’une chaîne JSON.

Pour extraire une valeur scalaire à partir d’une chaîne JSON à la place d’un objet ou d’un tableau, consultez JSON_VALUE (Transact-SQL). Pour obtenir des informations sur les différences entre JSON_VALUE et JSON_QUERY, consultez Comparer JSON_VALUE et JSON_QUERY.

Conventions de la syntaxe Transact-SQL

Syntaxe

JSON_QUERY ( expression [ , path ] )  

Arguments

expression
Expression. En règle générale, nom d’une variable ou d’une colonne qui contient du texte JSON.

Si JSON_QUERY trouve des données JSON non valides dans expression avant de trouver la valeur identifiée par path, la fonction renvoie une erreur. Si JSON_QUERY ne trouve pas la valeur identifiée par path, elle analyse l’intégralité du texte et renvoie une erreur si elle trouve des données JSON non valides, n’importe où dans expression.

path
Chemin JSON qui spécifie l’objet ou le tableau à extraire.

Dans SQL Server 2017 (14.x) et Azure SQL Database, vous pouvez fournir une variable comme valeur de path.

Le chemin JSON peut spécifier le mode lax ou strict pour l’analyse. Si vous ne spécifiez pas le mode d’analyse, le mode lax est utilisé par défaut. Pour plus d’informations, consultez Expressions de chemin JSON (SQL Server).

La valeur par défaut de path est '$'. Par conséquent, si vous ne fournissez pas de valeur pour path, JSON_QUERY renvoie l’entrée expression.

Si le format de path n’est pas valide, JSON_QUERY renvoie une erreur.

Valeur retournée

Renvoie un fragment JSON de type nvarchar(max). Le classement de la valeur renvoyée est le même que le classement de l’expression d’entrée.

Si la valeur n’est pas un objet ni un tableau :

• En mode lax, JSON_QUERY renvoie la valeur Null.

• En mode strict, JSON_QUERY renvoie une erreur.

Notes

Mode lax et mode strict

Considérons le texte JSON suivant :

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
} 

Le tableau suivant compare le comportement de JSON_QUERY en mode lax et en mode strict. Pour plus d’informations sur la spécification du mode de chemin d’accès facultatif (lax ou strict), consultez Expressions de chemin d’accès JSON (SQL Server).

Utilisation de JSON_QUERY avec FOR JSON

JSON_QUERY renvoie un fragment JSON valide. Par conséquent, FOR JSON n’échappe pas les caractères spéciaux dans la valeur renvoyée JSON_QUERY.

Si vous renvoyez les résultats avec FOR JSON, et que vous insérez des données qui sont déjà au format JSON (dans une colonne ou comme résultat d’une expression), incluez dans un wrapper les données JSON avec JSON_QUERY sans le paramètre path.

Exemples

Exemple 1

L’exemple suivant montre comment renvoyer un fragment JSON à partir d’une colonne CustomFields dans les résultats de la requête.

SELECT PersonID,FullName,
  JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People

Exemple 2

L’exemple suivant montre comment inclure les fragments JSON dans la sortie de la clause FOR JSON.

SELECT StockItemID, StockItemName,
         JSON_QUERY(Tags) as Tags,
         JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH

Voir aussi

• Expressions de chemin JSON (SQL Server)
• Données JSON (SQL Server)