Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
S’applique à :
SQL Server 2016 (13.x) et versions ultérieures d’Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics SQL Analyticsdans Microsoft FabricWarehouse dans microsoft FabricSQL Database dans Microsoft Fabric SQL Database dans Microsoft Fabric
La JSON_VALUE syntaxe extrait une valeur scalaire d’une chaîne JSON.
Pour extraire un objet ou un tableau d’une chaîne JSON au lieu d’une valeur scalaire, consultez JSON_QUERY. 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
Syntax
JSON_VALUE ( expression , path [ RETURNING data_type ] )
Arguments
expression
Expression. En règle générale, nom d’une variable ou d’une colonne qui contient du texte JSON.
Si JSON_VALUE 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_VALUE 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.
path
Chemin JSON qui spécifie la propriété à extraire. Pour plus d’informations, consultez les expressions de chemin JSON dans le moteur de base de données SQL.
Dans SQL Server 2017 (14.x) et dans Azure SQL Database, vous pouvez fournir une variable comme valeur de chemin d’accès.
Si le format du chemin d’accès n’est pas valide, JSON_VALUE retourne une erreur.
data_type
Retourne la valeur spécifiée dans le type SQL. Prise en charge uniquement si l’entrée est un type JSON. Les types SQL pris en charge sont : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar(max), date, heure, datetime2 et datetimeoffset.
Valeur retournée
S’il RETURNING n’est pas inclus :
Retourne une valeur de texte unique de type nvarchar(4000). Le classement de la valeur renvoyée est le même que le classement de l’expression d’entrée.
Si la valeur est supérieure à 4 000 caractères :
- En mode lax,
JSON_VALUEretourneNULL. - En mode strict,
JSON_VALUEretourne une erreur.
Si vous devez retourner des valeurs scalaires supérieures à 4 000 caractères, utilisez
OPENJSONplutôtJSON_VALUEque . Pour plus d’informations, consultez OPENJSON.- En mode lax,
S’il RETURNING est inclus :
Retourne la valeur spécifiée dans le type SQL. Les types SQL pris en charge sont : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar(max), date, heure, datetime2 et datetimeoffset.
Les fonctions JSON fonctionnent de la même façon que le document JSON soit stocké dans varchar, nvarchar ou le type de données json natif.
Remarks
Mode lax et mode strict
Considérons le texte JSON suivant :
DECLARE @jsonInfo AS NVARCHAR (MAX);
SET @jsonInfo = N'{
"info":{
"type":1,
"address":{
"town":"Bristol",
"county":"Avon",
"country/region":"England"
},
"tags":["Sport", "Water polo"]
},
"type":"Basic"
}';
Le tableau suivant compare le comportement de JSON_VALUE en mode lax et en mode strict. Pour plus d’informations sur la spécification facultative du mode de chemin d’accès (lax ou strict), consultez les expressions de chemin JSON dans le moteur de base de données SQL.
| Path | Valeur renvoyée en mode lax | Valeur renvoyée en mode strict | Plus d’informations |
|---|---|---|---|
| $ | NULL |
Error | Valeur non scalaire. Utilisez JSON_QUERY à la place. |
| $.info.type | N'1' | N'1' | N/a |
| $.info.address.town | N'Bristol' | N'Bristol' | N/a |
| $.info."address" | NULL |
Error | Valeur non scalaire. Utilisez JSON_QUERY à la place. |
| $.info.tags | NULL |
Error | Valeur non scalaire. Utilisez JSON_QUERY à la place. |
| $.info.type[0] | NULL |
Error | Pas un tableau. |
| $.info.none | NULL |
Error | La propriété n’existe pas. |
Examples
Exemple 1
L’exemple suivant utilise les valeurs des propriétés JSON town et state dans les résultats de la requête. Étant donné que JSON_VALUE conserve le classement de la source, l’ordre de tri des résultats dépend du classement de la colonne jsonInfo.
Note
(Cet exemple suppose qu’une table nommée Person.Person contient une jsonInfo colonne de texte JSON et que cette colonne a la structure indiquée précédemment dans la discussion du mode lax et du mode strict. Dans l’exemple AdventureWorks de base de données, la Person table ne contient pas de jsonInfo colonne.)
SELECT FirstName,
LastName,
JSON_VALUE(jsonInfo, '$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo, '$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo, '$.info.address.town');
Exemple 2
L’exemple suivant extrait la valeur de la propriété JSON dans une variable locale town.
DECLARE @jsonInfo AS NVARCHAR (MAX);
DECLARE @town AS NVARCHAR (32);
SET @jsonInfo = N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[0].town'); -- Paris
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[1].town'); -- London
Exemple 3
L’exemple suivant crée des colonnes calculées basées sur les valeurs des propriétés JSON.
CREATE TABLE dbo.Store
(
StoreID INT IDENTITY (1, 1) NOT NULL,
Address VARCHAR (500),
jsonContent NVARCHAR (4000),
Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
);
Exemple 4
L’exemple suivant extrait une valeur du tableau JSON à l’aide JSON_VALUE de la valeur et retourne la valeur sous forme de valeur de type date.
DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';
SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;
date_value
--------
2025-01-01