JSON_QUERY (Transact-SQL)

Artikel
05/30/2023

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

Extrahiert ein Objekt oder ein Array aus einer JSON-Zeichenfolge.

Informationen zum Extrahieren eines Skalarwerts aus einer JSON-Zeichenfolge anstelle eines Objekts oder eines Array finden Sie unter JSON_VALUE (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_QUERY ( expression [ , path ] )

Argumente

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

Wenn JSON_QUERY 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_QUERY 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 das zu extrahierende Objekt oder Array angibt.

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

Der JSON-Pfad kann den Lax- oder Strict-Modus für die Analyse angeben. Wenn Sie den Analysemodus nicht angeben, ist der Lax-Modus die Standardeinstellung. Weitere Informationen finden Sie unter JSON-Pfadausdrücke (SQL Server).

Der Standardwert für path lautet „$“. Wenn Sie also keinen Wert für path bereitstellen, gibt JSON_QUERY den Eingabe-Ausdruck zurück.

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

Rückgabewert

Gibt ein JSON-Fragment vom Typ nvarchar(max) zurück. Die Sortierung des zurückgegebenen Werts ist identisch mit der Sortierung des Eingabeausdrucks.

Wenn der Wert kein Objekt oder Array ist:

Im Lax-Modus gibt JSON_QUERY NULL zurück.
Im Strict-Modus gibt JSON_QUERY einen Fehler zurück.

Bemerkungen

Lax- und Strict-Modus

Betrachten Sie folgenden JSON-Text:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

Die folgende Tabelle vergleicht das Verhalten von JSON_QUERY 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
$	Gibt den gesamten JSON-Text zurück.	Gibt den gesamten JSON-Text zurück.	Nicht zutreffend
$.info.type	NULL	Fehler	Kein Objekt oder Array. Verwenden Sie stattdessen JSON_VALUE.
$.info.address.town	NULL	Fehler	Kein Objekt oder Array. Verwenden Sie stattdessen JSON_VALUE.
$.info."address"	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	Nicht zutreffend
$.info.tags	N'[ "Sport", "Water polo"]'	N'[ "Sport", "Water polo"]'	Nicht zutreffend
$.info.type[0]	NULL	Fehler	Kein Array.
$.info.none	NULL	Fehler	Die Eigenschaft ist nicht vorhanden.

Verwenden von JSON_QUERY mit FOR JSON

JSON_QUERY gibt ein gültiges JSON-Fragment zurück. Folglich versieht FOR JSON Sonderzeichen im Rückgabewert JSON_QUERY nicht mit Escapezeichen.

Wenn Sie verschiedene Ergebnisse mit FOR JSON zurückgeben und Sie Daten einschließen, die bereits im JSON-Format (in einer Spalte oder als Ergebnis eines Ausdrucks) vorhanden sind, dann umschließen Sie die JSON-Daten mit JSON_QUERY ohne den path-Parameter.

Beispiele

Beispiel 1

Im folgenden Beispiel wird gezeigt, wie ein JSON-Fragment einer CustomFields-Spalte in den Abfrageergebnissen zurückgegeben wird.

SELECT PersonID,FullName,
  JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People

Beispiel 2

Im folgende Beispiel wird gezeigt, wie JSON-Fragmente in die Ausgabe der FOR JSON-Klausel eingeschlossen werden.

SELECT StockItemID, StockItemName,
         JSON_QUERY(Tags) as Tags,
         JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH