Aracılığıyla paylaş

JSON_QUERY (Transact-SQL)

Şunlar için geçerlidir: SQL Server 2016 (13.x) ve sonraki sürümleri Azure SQL VeritabanıAzure SQL Yönetilen ÖrneğiAzure Synapse AnalyticsSQL analiz uç noktası Microsoft Fabric'teki Microsoft FabricSQL veritabanında Microsoft Fabric'te

Söz JSON_QUERY dizimi bir JSON dizesinden bir nesne veya dizi ayıklar.

Nesne veya dizi yerine JSON dizesinden skaler değer ayıklamak için bkz. JSON_VALUE. ile JSON_VALUEarasındaki JSON_QUERY farklar hakkında bilgi için bkz. JSON_VALUE ve JSON_QUERY karşılaştırma.

Transact-SQL söz dizimi kuralları

Syntax

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

Arguments

expression

Bir ifade. Genellikle JSON metni içeren bir değişkenin veya sütunun adıdır.

JSON_QUERY tarafından tanımlanan değeri bulmadan önce ifadede geçerli olmayan JSON bulursa işlev bir hata döndürür. JSON_QUERY Yol tarafından tanımlanan değeri bulamazsa, metnin tamamını tarar ve ifadenin herhangi bir yerinde geçerli olmayan JSON bulursa bir hata döndürür.

path

Ayıklanması gereken nesneyi veya diziyi belirten bir JSON yolu.

SQL Server 2017'de (14.x) ve Azure SQL Veritabanı'nda yol değeri olarak bir değişken sağlayabilirsiniz.

JSON yolu ayrıştırma için gevşek veya katı mod belirtebilir. Ayrıştırma modunu belirtmezseniz, lax modu varsayılandır. Daha fazla bilgi için bkz. SQL Veritabanı Altyapısı'nda JSON Yol İfadeleri.

Yol için varsayılan değer şeklindedir$. Sonuç olarak, yol için bir değer sağlamazsanız giriş JSON_QUERYifadesini döndürür.

Yol biçimi geçerli değilse bir JSON_QUERY hata döndürür.

DIZI SARMALAYıCı ILE

Note

WITH ARRAY WRAPPER şu anda önizleme aşamasında ve yalnızca SQL Server 2025 (17.x) sürümünde mevcuttur.

ANSI SQL JSON_QUERY işlevi şu anda belirtilen yolda bir JSON nesnesi veya dizisi döndürmek için kullanılır. SQL Server 2025 (17.x)'de sunulan SQL/JSON yol ifadesinde dizi joker kartları desteğiyle, JSON_QUERY her elemanın bir JSON nesnesi olduğu bir JSON dizisinde belirtilen öğelerin özelliklerini döndürmek için kullanılabilir. Joker karakter aramaları birden çok değer döndürebileceğinden, değerleri JSON dizisi olarak döndürmek için JSON sorgu ifadesinde yan tümcesini, joker karakter veya aralık veya liste içeren bir SQL/JSON yol ifadesiyle birlikte belirtin WITH ARRAY WRAPPER . WITH ARRAY WRAPPER yan tümcesi yalnızca giriş bir json türündeyse desteklenir.

Aşağıdaki JSON belgesini göz önünde bulundurun:

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

Yol $.credit_cards , her öğenin geçerli bir JSON nesnesi olduğu bir JSON dizisine işaret eder. Artık işlevi, özelliğin JSON_QUERY aşağıdaki gibi tüm veya belirli değerlerini type döndürmek için dizi joker karakter desteğiyle kullanılabilir:

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

Aşağıdaki tabloda joker karakterli SQL/JSON yol ifadesinin çeşitli örnekleri ve kullanılarak JSON_QUERY WITH ARRAY WRAPPERdöndürülen değer gösterilmektedir.

Path Dönüş değeri
$.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"]

Dönüş değeri

nvarchar(max) türünde bir JSON parçası döndürür. Döndürülen değerin harmanlanması, giriş ifadesinin harmanlaması ile aynıdır.

Değer bir nesne veya dizi değilse:

  • Lax modunda JSON_QUERY null döndürür.

  • Katı modda JSON_QUERY bir hata döndürür.

Remarks

Lax modu ve katı mod

Aşağıdaki JSON metnini göz önünde bulundurun:

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

Aşağıdaki tablo, JSON_QUERY davranışını gevşek modda ve katı modda karşılaştırır. İsteğe bağlı yol modu belirtimi (lax veya strict) hakkında daha fazla bilgi için bkz. SQL Veritabanı Altyapısı'nda JSON Yol İfadeleri.

Path Lax modunda dönüş değeri Katı modda değer döndürme Daha fazla bilgi
$ JSON metninin tamamını döndürür. JSON metninin tamamını döndürür.
$.info.type NULL Error Nesne veya dizi değil.

Bunun yerine JSON_VALUE kullanın.
$.info.address.town NULL Error Nesne veya dizi değil.

Bunun yerine JSON_VALUE kullanın.
$.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 Dizi değil.
$.info.none NULL Error Özellik yok.

FOR JSON ile JSON_QUERY kullanma

JSON_QUERY geçerli bir JSON parçası döndürür. Sonuç olarak, FOR JSON dönüş değerindeki özel karakterlerden JSON_QUERY kaçmaz.

FOR JSON ile sonuç döndürdüğünüzde zaten JSON biçimindeki verileri (bir sütunda veya ifadenin sonucu olarak) dahil ediyorsanız JSON verilerini JSON_QUERY parametresi olmadan ile sarmalarsınız.

Examples

A. JSON parçası döndürme

Aşağıdaki örnekte, sorgu sonuçlarında bir sütundan CustomFields JSON parçasının nasıl döndürüleceği gösterilmektedir.

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

B. FOR JSON çıkışına JSON parçalarını ekleme

Aşağıdaki örnekte, FOR JSON yan tümcesinin çıkışına JSON parçalarının nasıl dahil olduğu gösterilmektedir.

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

C. JSON_QUERY işleviyle DIZI SARMALAYıCı ile kullanma

Aşağıdaki örnekte, bir JSON dizisinden birden çok öğe döndürmek için işlevinin WITH ARRAY WRAPPER kullanımı JSON_QUERY gösterilmektedir:

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;

Sonuç kümesi aşağıdadır.

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

İlgili içerik

  • Last updated on