Partager via

JSON_QUERY (Transact-SQL)

  • Article

S’applique à : SQL Server 2016 (13.x) et versions ultérieures Base de données Azure SQL Azure SQL Managed Instance Azure Synapse Analytics SQL analytics endpoint dans Microsoft Fabric Warehouse dans Microsoft Fabric

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 chemin d'accès, la fonction renvoie une erreur. Si JSON_QUERY ne trouve pas la valeur identifiée par chemin d'accès, 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 du chemin d’accès est $. Par conséquent, si vous ne fournissez pas de valeur pour chemin d'accès, JSON_QUERY renvoie l’entrée expression.

Si le format de chemin d'accès n’est pas valide, JSON_QUERY retourne 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 retourne null.

  • En mode strict, JSON_QUERY retourne 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 facultatif (lax ou strict), consultez Expressions de chemin JSON (SQL Server).

Path Valeur renvoyée en mode lax Valeur renvoyée en mode strict En savoir plus
$ Renvoie l’intégralité du texte JSON. Renvoie l’intégralité du texte JSON. n/a
$.info.type NULL Error Ni un objet, ni un tableau.

Utilisez JSON_VALUE à la place.
$.info.address.town NULL Error Ni un objet, ni un tableau.

Utilisez JSON_VALUE à la place.
$.info."address" N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' n/a
$.info.tags N'[ "Sport", "Water polo"]' N'[ "Sport", "Water polo"]' n/a
$.info.type[0] NULL Error Pas un tableau.
$.info.none NULL Error La propriété n’existe pas.

Utiliser 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 chemin d'accès.

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

Contenu connexe