JSON_VALUE (Transact-SQL)

Gilt für: SQL Server 2016 (13.x) und höhere Versionen von Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics SQL Analytics-Endpunktin Microsoft FabricWarehouse in Microsoft FabricSQL-Datenbank in Microsoft Fabric SQL-Datenbank in Microsoft Fabric

Die JSON_VALUE Syntax extrahiert einen skalaren Wert aus einer JSON-Zeichenfolge.

Informationen zum Extrahieren eines Objekts oder eines Arrays aus einer JSON-Zeichenfolge anstelle eines skalaren Werts finden Sie unter JSON_QUERY. Informationen zu den Unterschieden zwischen JSON_VALUE und JSON_QUERY finden Sie unter Vergleichen von JSON_VALUE und JSON_QUERY.

Transact-SQL-Syntaxkonventionen

Syntax

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Arguments

expression

Ein Ausdruck. In der Regel der Name einer Variablen oder einer Spalte, die JSON-Text enthält.

Wenn JSON_VALUE JSON gefunden wird, die im Ausdruck nicht gültig ist, bevor der durch Pfad identifizierte Wert gefunden wird, gibt die Funktion einen Fehler zurück. Wenn JSON_VALUE der durch Pfad identifizierte Wert nicht gefunden wird, überprüft er den gesamten Text und gibt einen Fehler zurück, wenn er JSON findet, der in einem Ausdruck nicht gültig ist.

path

Ein JSON-Pfad, der die zu extrahierende Eigenschaft angibt. Weitere Informationen finden Sie unter JSON-Pfadausdrücke im SQL-Datenbankmodul.

In SQL Server 2017 (14.x) und in der Azure SQL-Datenbank können Sie eine Variable als Pfadwert bereitstellen.

Wenn das Format des Pfads ungültig ist, JSON_VALUE wird ein Fehler zurückgegeben.

data_type

Gibt den im SQL-Typ angegebenen Wert zurück. Wird nur unterstützt, wenn die Eingabe ein JSON-Typ ist. Die unterstützten SQL-Typen sind : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 und datetimeoffset.

Rückgabewert

Wenn RETURNING nicht enthalten ist:

• Gibt einen einzelnen Textwert vom Typ nvarchar(4000) zurück. Die Sortierung des zurückgegebenen Werts ist identisch mit der Sortierung des Eingabeausdrucks.

• Wenn der Wert 4000 Zeichen überschreitet:

  • JSON_VALUE gibt im Lax-Modus NULL zurück.
  • Im Strict-Modus gibt JSON_VALUE einen Fehler zurück.

  Wenn Sie skalare Werte zurückgeben müssen, die größer als 4000 Zeichen sind, verwenden Sie OPENJSON anstelle von JSON_VALUE. Weitere Informationen finden Sie unter OPENJSON.

Wenn RETURNING enthalten:

Gibt den im SQL-Typ angegebenen Wert zurück. Die unterstützten SQL-Typen sind : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 und datetimeoffset.

JSON-Funktionen funktionieren gleich, ob das JSON-Dokument in varchar, nvarchar oder dem nativenJSON-Datentyp gespeichert ist.

Remarks

Lax- und Strict-Modus

Betrachten Sie folgenden JSON-Text:

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

Die folgende Tabelle vergleicht das Verhalten von JSON_VALUE im Lax-Modus und im Strict-Modus. Weitere Informationen zur optionalen Pfadmodusspezifikation (lax oder streng) finden Sie unter JSON-Pfadausdrücke im SQL-Datenbankmodul.

Path	Rückgabewert im Lax-Modus	Rückgabewert im Strict-Modus	Weitere Informationen
$	NULL	Error	Kein Skalarwert. Verwenden Sie stattdessen JSON_QUERY.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	Kein Skalarwert. Verwenden Sie stattdessen JSON_QUERY.
$.info.tags	NULL	Error	Kein Skalarwert. Verwenden Sie stattdessen JSON_QUERY.
$.info.type[0]	NULL	Error	Kein Array.
$.info.none	NULL	Error	Eigenschaft ist nicht vorhanden.

Examples

Beispiel 1

Im folgenden Beispiel werden die Werte der JSON-Eigenschaften town und state in Abfrageergebnissen verwendet. Da JSON_VALUE die Sortierung der Quelle beibehält, hängt die Sortierreihenfolge der Ergebnisse von der Sortierung der jsonInfo-Spalte ab.

Note

(In diesem Beispiel wird davon ausgegangen, dass eine Tabelle Person.Person mit JSON-Text eine jsonInfo Spalte enthält und dass diese Spalte die Struktur aufweist, die zuvor in der Diskussion über den Lax-Modus und den strengen Modus gezeigt wurde. In der AdventureWorks Beispieldatenbank enthält Person die jsonInfo Tabelle tatsächlich keine Spalte.)

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

Beispiel 2

Im folgenden Beispiel wird der Wert der JSON-Eigenschaft town in eine lokale Variable extrahiert.

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

Beispiel 3

Im folgenden Beispiel werden berechnete Spalten erstellt, die auf den Werten der JSON-Eigenschaften basieren.

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

Beispiel 4

Im folgenden Beispiel wird ein Wert aus JSON-Array extrahiert JSON_VALUE und der Wert als Datumstypwert zurückgegeben.

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

Verwandte Inhalte

• JSON-Pfadausdrücke im SQL-Datenbankmodul
• JSON-Daten in SQL Server