Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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_QUERY Syntax extrahiert ein Objekt oder ein Array aus einer JSON-Zeichenfolge.
Informationen zum Extrahieren eines skalaren Werts aus einer JSON-Zeichenfolge anstelle eines Objekts oder eines Arrays finden Sie unter JSON_VALUE. Informationen zu den Unterschieden zwischen JSON_VALUE und JSON_QUERY, siehe Vergleich JSON_VALUE und JSON_QUERY.
Transact-SQL-Syntaxkonventionen
Syntax
JSON_QUERY ( expression [ , path ] [ WITH ARRAY WRAPPER ] )
Arguments
expression
Ein Ausdruck. In der Regel der Name einer Variablen oder einer Spalte, die JSON-Text enthält.
Wenn JSON_QUERY 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_QUERY 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 das zu extrahierende Objekt oder Array angibt.
In SQL Server 2017 (14.x) und in der Azure SQL-Datenbank können Sie eine Variable als Pfadwert 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 im SQL-Datenbankmodul.
Der Standardwert für pfad ist $. Wenn Sie daher keinen Wert für den Pfad angeben, JSON_QUERY wird der Eingabeausdruck zurückgegeben.
Wenn das Format des Pfads ungültig ist, JSON_QUERY wird ein Fehler zurückgegeben.
MIT ARRAYWRAPPER
Note
WITH ARRAY WRAPPER derzeit in der Vorschau und nur in SQL Server 2025 (17.x) verfügbar.
Die ANSI SQL-Funktion JSON_QUERY wird derzeit verwendet, um ein JSON-Objekt oder array in einem angegebenen Pfad zurückzugeben. Mit der Unterstützung von Array-Wildcards in SQL/JSON-Pfadausdrücken, die in SQL Server 2025 (17.x) eingeführt wurde, kann verwendet werden, JSON_QUERY um bestimmte Eigenschaften von Elementen in einem JSON-Array zurückzugeben, bei denen jedes Element ein JSON-Objekt ist. Da Wildcardsuchen mehrere Werte zurückgeben können, geben Sie die WITH ARRAY WRAPPER Klausel in einem JSON-Abfrageausdruck zusammen mit einem SQL/JSON-Pfadausdruck mit Einem Wildcard- oder Bereich oder einer Liste an, um die Werte als JSON-Array zurückzugeben.
WITH ARRAY WRAPPER Klausel wird nur unterstützt, wenn es sich bei der Eingabe um einen JSON-Typ handelt.
Betrachten Sie das folgende JSON-Dokument:
DECLARE @j AS JSON = '{
"id": 2,
"first_name": "Mamie",
"last_name": "Baudassi",
"email": "mbaudassi1@example.com",
"gender": "Female",
"ip_address": "148.199.129.123",
"credit_cards": [
{
"type": "jcb",
"card#": "3545138777072343",
"currency": "Koruna"
},
{
"type": "diners-club-carte-blanche",
"card#": "30282304348533",
"currency": "Dong"
},
{
"type": "jcb",
"card#": "3585303288595361",
"currency": "Yuan Renminbi"
},
{
"type": "maestro",
"card#": "675984450768756054",
"currency": "Rupiah"
},
{
"type": "instapayment",
"card#": "6397068371771473",
"currency": "Euro"
}
]
}';
Der Pfad $.credit_cards verweist auf ein JSON-Array, bei dem jedes Element ein gültiges JSON-Objekt ist. Jetzt kann die JSON_QUERY Funktion mit Array-Wildcardunterstützung verwendet werden, um alle oder bestimmte Werte der type Eigenschaft wie folgt zurückzugeben:
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER);
In der folgenden Tabelle sind verschiedene Beispiele für den SQL/JSON-Pfadausdruck mit Einem Wildcard- und Rückgabewert dargestellt JSON_QUERY WITH ARRAY WRAPPER.
| Path | Rückgabewert |
|---|---|
$.credit_cards[0].type |
["jcb"] |
$.credit_cards[*].type |
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"] |
$.credit_cards[0, 2].type |
["jcb","jcb"] |
$.credit_cards[1 to 3].type |
["diners-club-carte-blanche","jcb","maestro"] |
$.credit_cards[last].type |
["instapayment"] |
$.credit_cards[last, 0].type |
["instapayment","jcb"] |
$.credit_cards[last, last].type |
["instapayment","instapayment"] |
$.credit_cards[ 0, 2, 4].type |
["jcb","jcb","instapayment"] |
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 ein Array ist:
Im Lax-Modus gibt
JSON_QUERYNull zurück.Im Strict-Modus gibt
JSON_QUERYeinen Fehler zurück.
Remarks
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 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 |
|---|---|---|---|
$ |
Gibt den gesamten JSON-Text zurück. | Gibt den gesamten JSON-Text zurück. | |
$.info.type |
NULL |
Error | Kein Objekt oder Array. Verwenden Sie stattdessen JSON_VALUE. |
$.info.address.town |
NULL |
Error | 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" }' |
|
$.info.tags |
N'[ "Sport", "Water polo"]' |
N'[ "Sport", "Water polo"]' |
|
$.info.type[0] |
NULL |
Error | Kein Array. |
$.info.none |
NULL |
Error | Eigenschaft ist nicht vorhanden. |
Verwenden von JSON_QUERY mit FOR JSON
JSON_QUERY gibt ein gültiges JSON-Fragment zurück. Daher werden FOR JSON sonderzeichen im JSON_QUERY Rückgabewert nicht escapeen.
Wenn Sie Ergebnisse mit FOR JSON zurückgeben und Daten einschließen, die sich bereits im JSON-Format (in einer Spalte oder als Ergebnis eines Ausdrucks) befinden, schließen Sie die JSON-Daten ohne den JSON_QUERY um.
Examples
A. Zurückgeben eines JSON-Fragments
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;
B. Einschließen von JSON-Fragmenten in die FOR JSON-Ausgabe
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, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;
C. Verwenden von WITH ARRAY WRAPPER mit JSON_QUERY-Funktion
Das folgende Beispiel zeigt die Verwendung der WITH ARRAY WRAPPERJSON_QUERY Funktion, um mehrere Elemente aus einem JSON-Array zurückzugeben:
DECLARE @j JSON = '
{"id":2, "first_name":"Mamie", "last_name":"Baudassi", "email":"mbaudassi1@example.com", "gender":"Female", "ip_address":"148.199.129.123", "credit_cards":[ {"type":"jcb", "card#":"3545138777072343", "currency":"Koruna"}, {"type":"diners-club-carte-blanche", "card#":"30282304348533", "currency":"Dong"}, {"type":"jcb", "card#":"3585303288595361", "currency":"Yuan Renminbi"}, {"type":"maestro", "card#":"675984450768756054", "currency":"Rupiah"}, {"type":"instapayment", "card#":"6397068371771473", "currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;
Hier ist das Ergebnis.
credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]