JSON_QUERY (Transact-SQL)

2025-05-19

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 d’une chaîne JSON au lieu d’un objet ou d’un tableau, consultez JSON_VALUE. 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 ] [WITH ARRAY WRAPPER])

Les 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 le code JSON n’est pas valide dans l’expression avant de trouver la valeur identifiée par le chemin d’accès, la fonction retourne une erreur. S’il JSON_QUERY ne trouve pas la valeur identifiée par le chemin d’accès, il analyse l’intégralité du texte et retourne une erreur si elle trouve JSON qui n’est pas valide n’importe où dans l’expression.

chemin d'accès

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.

WITH ARRAY WRAPPER

Remarque

WITH ARRAY WRAPPER est actuellement disponible en préversion et disponible uniquement dans SQL Server 2025 (17.x) Preview.

La fonction SQL JSON_QUERY ANSI est actuellement utilisée pour renvoyer un objet ou un tableau JSON dans un chemin d’accès spécifié. La prise en charge des caractères génériques de tableau dans l’expression de chemin SQL/JSON introduite dans SQL Server 2025 (17.x) Preview JSON_QUERY peut être utilisée pour retourner les propriétés spécifiées d’éléments dans un tableau JSON où chaque élément est un objet JSON. Étant donné que les recherches génériques peuvent retourner plusieurs valeurs, spécifiez la WITH ARRAY WRAPPER clause dans une expression de requête JSON, ainsi qu’une expression de chemin SQL/JSON avec un caractère générique ou une plage ou une liste pour retourner les valeurs sous forme de tableau JSON. WITH ARRAY WRAPPER la clause est prise en charge uniquement si l’entrée est un type json .

Considérez le document JSON suivant :

declare @j JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "gender": "Female",
    "ip_address": "148.199.129.123",
    "credit_cards": [
        {
            "type": "jcb",
            "card#": "3545138777072343",
            "currency": "Koruna"
        },
        {
            "type": "diners-club-carte-blanche",
            "card#": "30282304348533",
            "currency": "Dong"
        },
        {
            "type": "jcb",
            "card#": "3585303288595361",
            "currency": "Yuan Renminbi"
        },
        {
            "type": "maestro",
            "card#": "675984450768756054",
            "currency": "Rupiah"
        },
        {
            "type": "instapayment",
            "card#": "6397068371771473",
            "currency": "Euro"
        }
    ]
}';

Le chemin $.credit_cards pointe vers un tableau JSON où chaque élément est un objet JSON valide. À présent, la fonction peut être utilisée avec la JSON_QUERY prise en charge des caractères génériques de tableau pour retourner toutes ou certaines valeurs de la type propriété comme :

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

Le tableau suivant présente différents exemples d’expression de chemin SQL/JSON avec un caractère générique et la valeur de retour à l’aide JSON_QUERY WITH ARRAY WRAPPERde .

Chemin	Valeur retournée
`$.creditcards[0].type`	`["jcb"]`
`$.credit_cards[*].type`	`["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]`
`$.credit_cards[0, 2].type`	`["jcb","jcb"]`
`$.credit_cards[1 to 3].type`	`["diners-club-carte-blanche","jcb","maestro"]`
`$.credit_cards[last].type`	`["instapayment"]`
`$.credit_cards[last, 0].type`	`["instapayment","jcb"]`
`$.credit_cards[last, last].type`	`["instapayment","instapayment"]`
`$.credit_cards[ 0, 2, 4].type`	`["jcb","jcb","instapayment"]`

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 ou 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).

Chemin	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.
`$.info.type`	`NULL`	Erreur	Ni un objet, ni un tableau. Utilisez `JSON_VALUE` à la place.
`$.info.address.town`	`NULL`	Erreur	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" }'`
`$.info.tags`	`N'[ "Sport", "Water polo"]'`	`N'[ "Sport", "Water polo"]'`
`$.info.type[0]`	`NULL`	Erreur	Pas un tableau.
`$.info.none`	`NULL`	Erreur	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 de caractères spéciaux dans la valeur de retour 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

Un. Retourner un fragment JSON

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;

B. Inclure des fragments JSON dans la sortie FOR JSON

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, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;

Chapitre C. Utiliser WITH ARRAY WRAPPER avec JSON_QUERY fonction

L’exemple suivant montre l’utilisation de WITH ARRAY WRAPPER la JSON_QUERY fonction pour renvoyer plusieurs éléments à partir d’un tableau JSON :

DECLARE @j JSON = ' {"id":2,"first_name":"Mamie","last_name":"Baudassi","email":"mbaudassi1@abc.net.au","gender":"Female","ip_address":"148.199.129.123","credit_cards":[{"type":"jcb","card#":"3545138777072343","currency":"Koruna"},{"type":"diners-club-carte-blanche","card#":"30282304348533","currency":"Dong"},{"type":"jcb","card#":"3585303288595361","currency":"Yuan Renminbi"},{"type":"maestro","card#":"675984450768756054","currency":"Rupiah"},{"type":"instapayment","card#":"6397068371771473","currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;

Voici l'ensemble des résultats.

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

Partager via