JSON_VALUE (Transact-SQL)

  • Article

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

Extrait une valeur scalaire d’une chaîne JSON.

Pour extraire un objet ou un tableau d’une chaîne JSON à la place d’une valeur scalaire, consultez JSON_QUERY (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_VALUE ( 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_VALUE trouve des données JSON non valides dans expression avant de rechercher la valeur identifiée par path, la fonction retourne une erreur. Si JSON_VALUE ne trouve pas la valeur identifiée par path, la fonction analyse l’intégralité du texte et retourne une erreur si elle trouve des données JSON non valides n’importe où dans expression.

path
Chemin JSON qui spécifie la propriété à extraire. Pour plus d’informations, consultez Expressions de chemin JSON (SQL Server).

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

Si le format de path n’est pas valide, JSON_VALUE retourne une erreur.

Valeur retournée

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_VALUE retourne la valeur NULL.

  • En mode strict, JSON_VALUE retourne une erreur.

Si vous devez renvoyer des valeurs scalaires de plus de 4 000 caractères, utilisez OPENJSON au lieu de JSON_VALUE. Pour plus d’informations, consultez OPENJSON (Transact-SQL).

Notes

Mode lax et mode strict

Considérons le texte JSON suivant :

DECLARE @jsonInfo NVARCHAR(MAX)

SET @jsonInfo=N'{  
     "info":{    
       "type":1,  
       "address":{    
         "town":"Bristol",  
         "county":"Avon",  
         "country":"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 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
$ 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.

Exemples

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.

Notes

(Cet exemple suppose qu’une table nommée Person.Person contient une jsonInfo colonne de texte JSON et que cette colonne a la structure affichée précédemment dans la discussion du mode lax et du mode strict. Dans l’exemple de base de données AdventureWorks, la Person table ne contient pas en fait 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 NVARCHAR(MAX)
DECLARE @town 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')
 )

Voir aussi

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