JSON_VALUE (Transact-SQL)

Si applica a: SQL Server 2016 (13.x) e versioni successive di Istanza gestita di SQL diAzure Istanza gestita di SQL diAzure Azure Synapse Analyticsin Microsoft FabricWarehouse nel database SQL diMicrosoft Fabricin Microsoft Fabric

La JSON_VALUE sintassi estrae un valore scalare da una stringa JSON.

Per estrarre un oggetto o una matrice da una stringa JSON anziché da un valore scalare, vedere JSON_QUERY. Per informazioni sulle differenze tra JSON_VALUE e JSON_QUERY, si veda Confronto tra JSON_VALUE e JSON_QUERY.

Convenzioni relative alla sintassi Transact-SQL

Syntax

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Arguments

expression

Espressione. In genere il nome di una variabile o di una colonna che contiene testo JSON.

Se JSON_VALUE trova JSON non valido nell'espressione prima di trovare il valore identificato dal percorso, la funzione restituisce un errore. Se JSON_VALUE non trova il valore identificato dal percorso, analizza l'intero testo e restituisce un errore se trova JSON non valido in qualsiasi punto dell'espressione.

path

Percorso JSON che specifica la proprietà da estrarre. Per altre informazioni, vedere Espressioni di percorso JSON nel motore di database SQL.

In SQL Server 2017 (14.x) e nel database SQL di Azure è possibile specificare una variabile come valore di path.

Se il formato del percorso non è valido, JSON_VALUE restituisce un errore.

data_type

Restituisce il valore specificato nel tipo SQL. Supportato solo se l'input è un tipo JSON. I tipi SQL supportati sono: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 e datetimeoffset.

Valore restituito

Se RETURNING non è incluso:

• Restituisce un valore di testo singolo di tipo nvarchar (4000). Le regole di confronto del valore restituito sono le stesse di quelle dell'espressione di input.

• Se il valore è maggiore di 4000 caratteri:

  • In modalità lax, JSON_VALUE restituisce NULL.
  • In modalità strict, JSON_VALUE restituisce un errore.

  Se è necessario restituire valori scalari maggiori di 4000 caratteri, usare OPENJSON anziché JSON_VALUE. Per altre info, vedi OPENJSON.

Se RETURNING è incluso:

Restituisce il valore specificato nel tipo SQL. I tipi SQL supportati sono: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 e datetimeoffset.

Le funzioni JSON funzionano allo stesso modo se il documento JSON viene archiviato in varchar, nvarchar o nel tipo di dati JSON nativo.

Remarks

Modalità lax e modalità strict

Si consideri il testo JSON seguente:

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"
 }';

Nella tabella seguente viene confrontato il comportamento di JSON_VALUE in modalità lax e in modalità strict. Per altre informazioni sulla specifica facoltativa della modalità percorso (lax o strict), vedere Espressioni di percorso JSON nel motore di database SQL.

Path	Valore restituito in modalità lax	Valore restituito in modalità strict	Altre informazioni
$	NULL	Error	Non è un valore scalare. Utilizzare invece JSON_QUERY.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	Non è un valore scalare. Utilizzare invece JSON_QUERY.
$.info.tags	NULL	Error	Non è un valore scalare. Utilizzare invece JSON_QUERY.
$.info.type[0]	NULL	Error	Non è una matrice.
$.info.none	NULL	Error	La proprietà non esiste.

Examples

Esempio 1

L'esempio seguente usa i valori delle proprietà JSON town e state nei risultati della query. Poiché JSON_VALUE mantiene le regole di confronto dell'origine, l'ordinamento dei risultati dipende dalle regole di confronto della colonna jsonInfo.

Note

In questo esempio si presuppone che una tabella denominata Person.Person contenga una jsonInfo colonna di testo JSON e che questa colonna abbia la struttura illustrata in precedenza nella discussione della modalità lax e della modalità strict. AdventureWorks Nel database di esempio la Person tabella non contiene infatti una jsonInfo colonna.

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

Esempio 2

Nell'esempio seguente viene estratto il valore della proprietà JSON town in una variabile locale.

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

Esempio 3

Nell'esempio seguente vengono create le colonne calcolate in base ai valori delle proprietà 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')
);

Esempio 4

L'esempio seguente estrae un valore dalla matrice JSON usando JSON_VALUE e restituisce il valore come valore di tipo data.

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

Contenuti correlati

• Espressioni di percorso JSON nel motore di database SQL
• Dati JSON in SQL Server