JSON_QUERY (Transact-SQL)

2025-05-19

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

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 Compare JSON_VALUE and JSON_QUERY.

Transact-SQL konwencje składni

Składnia

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

Argumenty

wyrażenia

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.

ścieżka

Ś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 (SQL Server).

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

Uwaga / Notatka

WITH ARRAY WRAPPER jest obecnie dostępna w wersji zapoznawczej i jest dostępna tylko w wersji zapoznawczej programu 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 obsłudze symboli wieloznacznych tablicy w wyrażeniu ścieżki SQL/JSON wprowadzonym w programie SQL Server 2025 (17.x) (wersja zapoznawcza) można użyć do zwrócenia określonych właściwości elementów w tablicy JSON, JSON_QUERY 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 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"
        }
    ]
}';

Ś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, '$.creditcards[*].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.

Ścieżka	Wartość zwracana
`$.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"]`

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.

Uwagi

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 (SQL Server).

Ścieżka	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`	Błąd	Nie jest obiektem ani tablicą. Zamiast tego użyj `JSON_VALUE`.
`$.info.address.town`	`NULL`	Błąd	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`	Błąd	Nie tablica.
`$.info.none`	`NULL`	Błąd	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 za pomocą JSON_QUERY bez ścieżki parametru.

Przykłady

Odp. 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@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;

Oto zestaw wyników.

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

Udostępnij za pośrednictwem