JSON_QUERY (Transact-SQL)

Van toepassing op: SQL Server 2016 (13.x) en latere versies Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL Analytics-eindpunt in Microsoft Fabric,Warehouse in Microsoft Fabric,SQL Database in Microsoft Fabric Preview

De JSON_QUERY syntaxis extraheert een object of een matrix uit een JSON-tekenreeks.

Zie JSON_VALUE als u een scalaire waarde wilt extraheren uit een JSON-tekenreeks in plaats van een object of matrix. Zie JSON_VALUE voor meer informatie over de verschillen tussen JSON_QUERY en.

Transact-SQL syntaxisconventies

Syntax

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

Arguments

expression

Een expressie. Meestal de naam van een variabele of een kolom die JSON-tekst bevat.

Als JSON_QUERY JSON wordt gevonden die niet geldig is in de expressie voordat de waarde wordt gevonden die door het pad wordt geïdentificeerd, retourneert de functie een fout. Als JSON_QUERY de waarde die door het pad wordt geïdentificeerd, niet wordt gevonden, wordt de hele tekst gescand en wordt er een fout geretourneerd als JSON wordt gevonden die nergens in de expressie geldig is.

path

Een JSON-pad waarmee het object of de matrix wordt opgegeven die moet worden geëxtraheerd.

In SQL Server 2017 (14.x) en in Azure SQL Database kunt u een variabele opgeven als de waarde van het pad.

Het JSON-pad kan de lax- of strikte modus voor parseren opgeven. Als u de parseringsmodus niet opgeeft, is de lax-modus de standaardmodus. Zie JSON-padexpressies in de SQL Database Engine voor meer informatie.

De standaardwaarde voor pad is $. Als u dus geen waarde voor het pad opgeeft, JSON_QUERY wordt de invoerexpressie geretourneerd.

Als de indeling van het pad niet geldig is, JSON_QUERY wordt een fout geretourneerd.

MET MATRIX WRAPPER

De ANSI SQL-functie JSON_QUERY wordt momenteel gebruikt om een JSON-object of -matrix in een opgegeven pad te retourneren. Met de ondersteuning voor matrix-jokertekens in SQL/JSON-padexpressie die is geïntroduceerd in SQL Server 2025 (17.x) Preview, JSON_QUERY kan worden gebruikt om opgegeven eigenschappen van elementen in een JSON-matrix te retourneren waarbij elk element een JSON-object is. Omdat zoekopdrachten met jokertekens meerdere waarden kunnen retourneren, geeft u de WITH ARRAY WRAPPER component op in een JSON-queryexpressie samen met een SQL/JSON-padexpressie met jokertekens of -bereiken of lijsten om de waarden als een JSON-matrix te retourneren. WITH ARRAY WRAPPER component wordt alleen ondersteund als de invoer een json-type is.

Bekijk het volgende JSON-document:

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

Het pad $.credit_cards verwijst naar een JSON-matrix waarbij elk element een geldig JSON-object is. JSON_QUERY De functie kan nu worden gebruikt met ondersteuning voor matrix-jokertekens om alle of specifieke waarden van de type eigenschap te retourneren, zoals:

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

In de volgende tabel ziet u verschillende voorbeelden van sql/JSON-padexpressie met jokertekens en de retourwaarde met behulp van JSON_QUERY WITH ARRAY WRAPPER.

Retourwaarde

Retourneert een JSON-fragment van het type nvarchar(max). De sortering van de geretourneerde waarde is hetzelfde als de sortering van de invoerexpressie.

Als de waarde geen object of matrix is:

• In de lax-modus retourneert JSON_QUERY null.

• In de strikte modus retourneert JSON_QUERY een fout.

Remarks

Lax-modus en strikte modus

Houd rekening met de volgende JSON-tekst:

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

In de volgende tabel wordt het gedrag van JSON_QUERY in de lax-modus en in de strikte modus vergeleken. Zie JSON-padexpressies in de SQL Database Engine voor meer informatie over de specificatie van de optionele padmodus (lax of strikt).

Gebruik JSON_QUERY met FOR JSON

JSON_QUERY retourneert een geldig JSON-fragment. Als gevolg hiervan escapet FOR JSON geen speciale tekens in de JSON_QUERY retourwaarde.

Als u resultaten retourneert met FOR JSON en u gegevens opgeeft die al in JSON-indeling (in een kolom of als resultaat van een expressie) staan, verpakt u de JSON-gegevens met JSON_QUERY zonder de padparameter .

Examples

A. Een JSON-fragment retourneren

In het volgende voorbeeld ziet u hoe u een JSON-fragment uit een CustomFields kolom in queryresultaten kunt retourneren.

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

B. JSON-fragmenten opnemen in FOR JSON-uitvoer

In het volgende voorbeeld ziet u hoe u JSON-fragmenten opneemt in de uitvoer van de FOR JSON-component.

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

C. USE WITH ARRAY WRAPPER with JSON_QUERY function

In het volgende voorbeeld ziet u het gebruik van WITH ARRAY WRAPPER met de JSON_QUERY functie om meerdere elementen uit een JSON-matrix te retourneren:

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 is het resultatenoverzicht.

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

Verwante inhoud

• JSON-padexpressies in de SQL Database Engine
• JSON-gegevens in SQL Server