Freigeben über

JSON_VALUE (Transact-SQL)

  • Artikel

Gilt für: SQL Server 2016 (13.x) und höher Azure SQL-Datenbank Azure SQL verwaltete Instanz Azure Synapse Analytics

Extrahiert einen Skalarwert aus einer JSON-Zeichenfolge.

Informationen zum Extrahieren eines Objekts oder eines Arrays aus einer JSON-Zeichenfolge anstelle eines Skalarwerts finden Sie unter JSON_QUERY (Transact-SQL). 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 )

Argumente

expression

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

Wenn JSON_VALUE sieht, dass JSON in expression ungültig ist, bevor sie den von path identifizierten Wert findet, gibt die Funktion einen Fehler zurück. Wenn JSON_VALUE den von path identifizierten Wert nicht ermittelt, wird der gesamte Text durchsucht und ein Fehler zurückgegeben, wenn JSON nirgendwo in expression gültig ist.

path

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

In SQL Server 2017 (14.x) und Azure SQL-Datenbank können Sie eine Variable als Wert von path bereitstellen.

JSON_VALUE gibt einen Fehler zurück, wenn das Format von path ungültig ist.

Rückgabewert

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 (Transact-SQL).

JSON-Funktionen funktionieren gleich, unabhängig davon, ob das JSON-Dokument in varchar, nvarchar oder dem nativen json-Datentyp gespeichert ist.

Hinweise

Lax- und Strict-Modus

Betrachten Sie folgenden JSON-Text:

DECLARE @jsonInfo NVARCHAR(MAX)

SET @jsonInfo=N'{  
     "info":{    
       "type":1,  
       "address":{    
         "town":"Bristol",  
         "county":"Avon",  
         "country":"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 zu den optionalen Pfadmodusangaben („Lax“ oder „Strict“) finden Sie unter JSON-Pfadausdrücke (SQL Server).

`Path` Rückgabewert im Lax-Modus Rückgabewert im Strict-Modus Weitere Informationen
$ NULL Fehler Kein Skalarwert.

Verwenden Sie stattdessen JSON_QUERY.
$.info.type N'1' N'1' Nicht zutreffend
$.info.address.town N'Bristol' N'Bristol' Nicht zutreffend
$.info."address" NULL Fehler Kein Skalarwert.

Verwenden Sie stattdessen JSON_QUERY.
$.info.tags NULL Fehler Kein Skalarwert.

Verwenden Sie stattdessen JSON_QUERY.
$.info.type[0] NULL Fehler Kein Array.
$.info.none NULL Fehler Die Eigenschaft ist nicht vorhanden.

Beispiele

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.

Hinweis

(In diesem Beispiel wird davon ausgegangen, dass eine Tabelle namens Person.Person eine jsonInfo-Spalte mit JSON-Text enthält und dass diese Spalte die zuvor in der Beschreibung der Lax- und Strict-Modi gezeigte Struktur aufweist. In der AdventureWorks-Beispieldatenbank enthält die Tabelle Person keine jsonInfo-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 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

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

Zugehöriger Inhalt