Freigeben über

JSON_QUERY (Transact-SQL)

Gilt für: SQL Server 2016 (13.x) und später Azure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsSQL-Analyse-Endpunkt in Microsoft FabricWarehouse in Microsoft Fabric

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 finden Sie unter Vergleichen von JSON_VALUE und JSON_QUERY.

Transact-SQL-Syntaxkonventionen

Syntax

JSON_QUERY ( expression [ , path ] [WITH ARRAY WRAPPER])

Argumente

Ausdruck

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.

Pfad

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 pfad ist $. Wenn Sie also keinen Wert für path bereitstellen, gibt JSON_QUERY den Eingabe-Ausdruck zurück.

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

MIT ARRAYWRAPPER

Hinweis

WITH ARRAY WRAPPER ist derzeit in der Vorschau verfügbar und nur in SQL Server 2025 (17.x) Preview 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 im SQL/JSON-Pfadausdruck, der in SQL Server 2025 (17.x) Preview eingeführt wurde, kann verwendet werden, um angegebene Eigenschaften von Elementen in einem JSON-Array zurückzugeben, JSON_QUERY wobei 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 JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "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, '$.creditcards[*].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
$.creditcards[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_QUERY Null zurück.

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

Hinweise

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.
$.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" }'
$.info.tags N'[ "Sport", "Water polo"]' N'[ "Sport", "Water polo"]'
$.info.type[0] NULL Fehler Kein Array.
$.info.none NULL Fehler 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 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

Ein. 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@abc.net.au","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"]

Zugehöriger Inhalt