Partager via

JSON_VALUE (Transact-SQL)

  • Article

S’applique à : SQL Server 2016 (13.x) et versions ultérieures Azure SQL Database Azure SQL Managed Instance Azure 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 trouver la valeur identifiée par chemin d'accès, la fonction renvoie une erreur. Si JSON_VALUE 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 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 chemin d'accès 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 NULL.

  • En mode strict, JSON_VALUE retourne une erreur.

Si vous devez retourner des valeurs scalaires supérieures à 4 000 caractères, utilisez OPENJSON plutôt JSON_VALUEque . Pour plus d’informations, consultez OPENJSON (Transact-SQL).

Les fonctions JSON fonctionnent de la même façon que le document JSON soit stocké dans varchar, nvarchar ou dans le type de données json natif.

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 Erreur 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 Erreur Valeur non scalaire.

Utilisez JSON_QUERY à la place.
$.info.tags NULL Erreur Valeur non scalaire.

Utilisez JSON_QUERY à la place.
$.info.type[0] NULL Erreur Pas un tableau.
$.info.none NULL Erreur 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.

Remarque

(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 table Person ne contient pas en fait de colonne jsonInfo.)

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')
 )

Contenu connexe