JSON_QUERY (Transact-SQL)

Gäller för: SQL Server 2016 (13.x) och senare versioner Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL Analytics-slutpunkt i Microsoft Fabric Warehouse i Microsoft FabricSQL Database i Förhandsversion av Microsoft Fabric

Syntaxen JSON_QUERY extraherar ett objekt eller en matris från en JSON-sträng.

Information om hur du extraherar ett skalärt värde från en JSON-sträng i stället för ett objekt eller en matris finns i JSON_VALUE. Information om skillnaderna mellan JSON_VALUE och JSON_QUERYfinns i Jämför JSON_VALUE och JSON_QUERY.

Transact-SQL syntaxkonventioner

Syntax

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

Arguments

expression

Ett uttryck. Vanligtvis namnet på en variabel eller en kolumn som innehåller JSON-text.

Om JSON_QUERY hittar JSON som inte är giltigt i uttrycket innan det hittar värdet som identifieras av sökvägen returnerar funktionen ett fel. Om JSON_QUERY inte hittar det värde som identifieras av sökvägen söker den igenom hela texten och returnerar ett fel om det hittar JSON som inte är giltigt någonstans i uttrycket.

path

En JSON-sökväg som anger objektet eller matrisen som ska extraheras.

I SQL Server 2017 (14.x) och i Azure SQL Database kan du ange en variabel som värdet för sökvägen.

JSON-sökvägen kan ange släpphänt eller strikt läge för parsning. Om du inte anger parsningsläget är läget lax standard. Mer information finns i JSON Path Expressions in the SQL Database Engine (JSON Path Expressions in the SQL Database Engine).

Standardvärdet för sökvägen är $. Därför returnerar indatauttrycket om du inte anger något värde för JSON_QUERY.

Om sökvägens format inte är giltigt JSON_QUERY returnerar ett fel.

MED MATRISOMSLUTNING

Funktionen ANSI SQL JSON_QUERY används för närvarande för att returnera ett JSON-objekt eller en matris i en angiven sökväg. Med stöd för matris jokertecken i SQL/JSON-sökvägsuttrycket som introducerades i SQL Server 2025 (17.x) Förhandsversion, JSON_QUERY kan användas för att returnera angivna egenskaper för element i en JSON-matris där varje element är ett JSON-objekt. Eftersom jokerteckensökningar kan returnera flera värden anger du WITH ARRAY WRAPPER satsen i ett JSON-frågeuttryck tillsammans med ett SQL/JSON-sökvägsuttryck med jokertecken eller intervall eller lista för att returnera värdena som en JSON-matris. WITH ARRAY WRAPPER -satsen stöds endast om indata är en json-typ .

Överväg följande 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"
        }
    ]
}';

Sökvägen $.credit_cards pekar på en JSON-matris där varje element är ett giltigt JSON-objekt. JSON_QUERY Nu kan funktionen användas med stöd för matris jokertecken för att returnera alla eller specifika värden för type egenskapen, till exempel:

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

I följande tabell visas olika exempel på SQL/JSON-sökvägsuttryck med jokertecken och returvärdet med hjälp av JSON_QUERY WITH ARRAY WRAPPER.

Returvärde

Returnerar ett JSON-fragment av typen nvarchar(max). Sortering av det returnerade värdet är samma som sortering av indatauttrycket.

Om värdet inte är ett objekt eller en matris:

• I släpphänt läge returnerar JSON_QUERY null.

• I strikt läge returnerar JSON_QUERY ett fel.

Remarks

Släpphänt läge och strikt läge

Tänk på följande JSON-text:

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

I följande tabell jämförs beteendet för JSON_QUERY i slappt läge och i strikt läge. Mer information om den valfria sökvägslägesspecifikationen (slapp eller strikt) finns i JSON Path Expressions in the SQL Database Engine (JSON Path Expressions in the SQL Database Engine).

Använda JSON_QUERY med FOR JSON

JSON_QUERY returnerar ett giltigt JSON-fragment. Därför undflyr FOR JSON inte specialtecken i det JSON_QUERY returvärdet.

Om du returnerar resultat med FOR JSON och du inkluderar data som redan är i JSON-format (i en kolumn eller som resultat av ett uttryck), omsluter du JSON-data med JSON_QUERY utan sökvägsparametern .

Examples

A. Returnera ett JSON-fragment

I följande exempel visas hur du returnerar ett JSON-fragment från en CustomFields kolumn i frågeresultatet.

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

B. Inkludera JSON-fragment i FOR JSON-utdata

I följande exempel visas hur du inkluderar JSON-fragment i utdata från FOR JSON-satsen.

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

C. Använda WITH ARRAY WRAPPER med funktionen JSON_QUERY

I följande exempel visas användningen av WITH ARRAY WRAPPER med JSON_QUERY funktionen för att returnera flera element från en JSON-matris:

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;

Här är resultatet.

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

Relaterat innehåll

• JSON-sökvägsuttryck i SQL Database Engine
• JSON-data i SQL Server