JSON_QUERY (Transact-SQL)

Dotyczy: SQL Server 2016 (13.x) i nowsze wersje usługi Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics — punkt końcowy analizy SQL w usłudze Microsoft Fabric Warehouse wbazie danych Microsoft Fabric SQL Database w usłudze Microsoft Fabric

Składnia JSON_QUERY wyodrębnia obiekt lub tablicę z ciągu JSON.

Aby wyodrębnić wartość skalarną z ciągu JSON zamiast obiektu lub tablicy, zobacz JSON_VALUE. Aby uzyskać informacje o różnicach między JSON_VALUE i JSON_QUERY, zobacz Porównanie JSON_VALUE i JSON_QUERY.

Transact-SQL konwencje składni

Syntax

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

Arguments

expression

Wyrażenie. Zazwyczaj nazwa zmiennej lub kolumny zawierającej tekst JSON.

Jeśli JSON_QUERY znajdzie kod JSON, który nie jest prawidłowy w wyrażeniu , zanim znajdzie wartość zidentyfikowaną przez ścieżkę, funkcja zwróci błąd. Jeśli JSON_QUERY nie znajdzie wartości zidentyfikowanej przez ścieżkę, skanuje cały tekst i zwraca błąd, jeśli znajdzie kod JSON, który nie jest prawidłowy nigdzie w wyrażeniu.

path

Ścieżka JSON określająca obiekt lub tablicę do wyodrębnienia.

W programie SQL Server 2017 (14.x) i usłudze Azure SQL Database można podać zmienną jako wartość ścieżki.

Ścieżka JSON może określać tryb lax lub ścisły na potrzeby analizowania. Jeśli nie określisz trybu analizowania, tryb lax jest domyślny. Aby uzyskać więcej informacji, zobacz Wyrażenia ścieżki JSON w a aparatu bazy danych SQL.

Wartość domyślna ścieżki to $. W związku z tym, jeśli nie podasz wartości dla ścieżki, JSON_QUERY zwraca wyrażenie wejściowe.

Jeśli format ścieżki jest nieprawidłowy, JSON_QUERY zwraca błąd.

ZA POMOCĄ OTOKI TABLICY

Note

WITH ARRAY WRAPPER obecnie jest w wersji podglądowej i dostępna tylko w SQL Server 2025 (17.x).

Funkcja SQL JSON_QUERY ANSI jest obecnie używana do zwracania obiektu JSON lub tablicy w określonej ścieżce. Dzięki wsparciu dla dzikich tablic w SQL/JSON w SQL Server 2025 (17.x), JSON_QUERY można je wykorzystać do zwracania określonych właściwości elementów w tablicy JSON, gdzie każdy element jest obiektem JSON. Ponieważ wyszukiwania wieloznaczne mogą zwracać wiele wartości, określ klauzulę WITH ARRAY WRAPPER w wyrażeniu zapytania JSON wraz z wyrażeniem ścieżki SQL/JSON z symbolami wieloznacznymi lub zakresem lub listą, aby zwrócić wartości jako tablicę JSON. WITH ARRAY WRAPPER Klauzula jest obsługiwana tylko wtedy, gdy dane wejściowe są typem json .

Rozważmy następujący dokument JSON:

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

Ścieżka $.credit_cards wskazuje tablicę JSON, w której każdy element jest prawidłowym obiektem JSON. Teraz funkcja może być używana z obsługą symboli wieloznacznych tablicy w JSON_QUERY celu zwrócenia wszystkich lub określonych wartości type właściwości, takich jak:

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

W poniższej tabeli przedstawiono różne przykłady wyrażenia ścieżki SQL/JSON z symbolami wieloznacznymi i wartością zwracaną przy użyciu polecenia JSON_QUERY WITH ARRAY WRAPPER.

Path	Wartość zwracana
`$.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"]`

Wartość zwracana

Zwraca fragment JSON typu nvarchar(max). Sortowanie zwróconej wartości jest takie samo jak sortowanie wyrażenia wejściowego.

Jeśli wartość nie jest obiektem lub tablicą:

W trybie lax JSON_QUERY zwraca wartość null.
W trybie ścisłym JSON_QUERY zwraca błąd.

Remarks

Tryb lax i tryb ścisły

Rozważ następujący tekst JSON:

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

W poniższej tabeli porównaliśmy zachowanie JSON_QUERY w trybie lax i w trybie ścisłym. Aby uzyskać więcej informacji na temat opcjonalnej specyfikacji trybu ścieżki (lax lub strict), zobacz Wyrażenia ścieżki JSON w a aparatu bazy danych SQL.

Path	Zwracana wartość w trybie lax	Zwracana wartość w trybie ścisłym	Więcej informacji
`$`	Zwraca cały tekst JSON.	Zwraca cały tekst JSON.
`$.info.type`	`NULL`	Error	Nie jest obiektem ani tablicą. Zamiast tego użyj `JSON_VALUE`.
`$.info.address.town`	`NULL`	Error	Nie jest obiektem ani tablicą. Zamiast tego użyj `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	Nie tablica.
`$.info.none`	`NULL`	Error	Właściwość nie istnieje.

Używanie JSON_QUERY z plikiem FOR JSON

JSON_QUERY zwraca prawidłowy fragment JSON. W związku z tym FOR JSON nie uniknie znaków specjalnych w JSON_QUERY zwracanej wartości.

Jeśli zwracasz wyniki w formacie JSON dla formatu JSON i uwzględniasz dane, które są już w formacie JSON (w kolumnie lub w wyniku wyrażenia), zawijaj dane JSON_QUERY JSON bez parametru path .

Examples

A. Zwracanie fragmentu JSON

W poniższym przykładzie pokazano, jak zwrócić fragment JSON z kolumny CustomFields w wynikach zapytania.

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

B. Dołączanie fragmentów JSON do danych wyjściowych JSON

W poniższym przykładzie pokazano, jak uwzględnić fragmenty JSON w danych wyjściowych klauzuli JSON FOR.

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

C. Używanie funkcji WITH ARRAY WRAPPER z funkcją JSON_QUERY

W poniższym przykładzie pokazano użycie funkcji WITH ARRAY WRAPPER z funkcją JSON_QUERY w celu zwrócenia wielu elementów z tablicy JSON:

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;

Oto zestaw wyników.

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-18