JSON_QUERY (Transact-SQL)

Dotyczy: SQL Server 2016 (13.x) i nowsze wersje usługi Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics— punkt końcowy analizy SQL w usłudze Microsoft FabricWarehouse 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

Funkcja SQL JSON_QUERY ANSI zwraca obiekt lub tablicę JSON na określonej ścieżce. Dzięki wsparciu dzikich kart tablic w wyrażeniach ścieżek SQL/JSON, JSON_QUERY można zwracać określone właściwości elementów w tablicy JSON, gdzie każdy element jest obiektem JSON. Ponieważ wyszukiwania dziki mogą zwracać wiele wartości, określ klauzulę WITH ARRAY WRAPPER za pomocą wyrażenia ścieżki SQL/JSON, która zawiera dziki, zakres lub listę, aby zwrócić wartości jako tablicę JSON. Klauzula jest WITH ARRAY WRAPPER obsługiwana tylko wtedy, gdy wejście jest 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"]

Treści powiązane

• Wyrażenia ścieżki JSON w a aparatze bazy danych SQL
• danych JSON w programie SQL Server