JSON_QUERY (Transact-SQL)

Berlaku untuk: SQL Server 2016 (13.x) dan versi yang lebih baru Azure SQL Database Azure SQL Managed Instance Titik akhir analitik SQLAzure Synapse Analytics di Microsoft Fabric Warehouse dalam database Microsoft Fabric SQL di Microsoft Fabric

JSON_QUERY Sintaks mengekstrak objek atau array dari string JSON.

Untuk mengekstrak nilai skalar dari string JSON, bukan objek atau array, lihat JSON_VALUE. Untuk informasi tentang perbedaan antara JSON_VALUE dan JSON_QUERY, lihat Membandingkan JSON_VALUE dan JSON_QUERY.

Konvensi sintaks transact-SQL

Syntax

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

Arguments

expression

Ekspresi. Biasanya nama variabel atau kolom yang berisi teks JSON.

Jika JSON_QUERY menemukan JSON yang tidak valid dalam ekspresi sebelum menemukan nilai yang diidentifikasi berdasarkan jalur, fungsi mengembalikan kesalahan. Jika JSON_QUERY tidak menemukan nilai yang diidentifikasi berdasarkan jalur, nilai akan memindai seluruh teks dan mengembalikan kesalahan jika menemukan JSON yang tidak valid di mana saja dalam ekspresi.

path

Jalur JSON yang menentukan objek atau array yang akan diekstrak.

Di SQL Server 2017 (14.x) dan di Azure SQL Database, Anda dapat memberikan variabel sebagai nilai jalur.

Jalur JSON dapat menentukan mode laks atau ketat untuk penguraian. Jika Anda tidak menentukan mode penguraian, mode lax adalah default. Untuk informasi selengkapnya, lihat Ekspresi Jalur JSON di Mesin Database SQL.

Nilai default untuk jalur adalah $. Akibatnya, jika Anda tidak memberikan nilai untuk jalur, JSON_QUERY mengembalikan ekspresi input.

Jika format jalur tidak valid, JSON_QUERY mengembalikan kesalahan.

DENGAN PEMBUNGKUS ARRAY

Note

WITH ARRAY WRAPPER saat ini dalam pratinjau dan hanya tersedia di SQL Server 2025 (17.x).

Fungsi ANSI SQL JSON_QUERY saat ini digunakan untuk mengembalikan objek atau array JSON dalam jalur tertentu. Dengan dukungan untuk wildcard array dalam ekspresi jalur SQL/JSON yang diperkenalkan di SQL Server 2025 (17.x), JSON_QUERY dapat digunakan untuk mengembalikan properti elemen yang ditentukan dalam array JSON di mana setiap elemen adalah objek JSON. Karena pencarian kartubebas dapat mengembalikan beberapa nilai, tentukan WITH ARRAY WRAPPER klausa dalam ekspresi kueri JSON bersama dengan ekspresi jalur SQL/JSON dengan kartubebas atau rentang atau daftar untuk mengembalikan nilai sebagai array JSON. WITH ARRAY WRAPPER klausa hanya didukung jika input adalah jenis json .

Pertimbangkan dokumen JSON berikut:

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

Jalur $.credit_cards menunjuk ke array JSON di mana setiap elemen adalah objek JSON yang valid. Sekarang, JSON_QUERY fungsi dapat digunakan dengan dukungan kartubebas array untuk mengembalikan semua atau nilai tertentu dari type properti seperti:

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

Tabel berikut ini memperlihatkan berbagai contoh ekspresi jalur SQL/JSON dengan kartubebas dan nilai pengembalian menggunakan JSON_QUERY WITH ARRAY WRAPPER.

Path	Mengembalikan nilai
`$.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"]`

Mengembalikan nilai

Mengembalikan fragmen JSON jenis nvarchar(maks). Kolase nilai yang dikembalikan sama dengan kolase ekspresi input.

Jika nilai bukan objek atau array:

Dalam mode laks, JSON_QUERY mengembalikan null.
Dalam mode ketat, JSON_QUERY mengembalikan kesalahan.

Remarks

Mode laks dan mode ketat

Pertimbangkan teks JSON berikut:

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

Tabel berikut membandingkan perilaku JSON_QUERY dalam mode lax dan dalam mode ketat. Untuk informasi selengkapnya tentang spesifikasi mode jalur opsional (lax atau ketat), lihat Ekspresi Jalur JSON di Mesin Database SQL.

Path	Mengembalikan nilai dalam mode laks	Mengembalikan nilai dalam mode ketat	Info lebih lanjut
`$`	Mengembalikan seluruh teks JSON.	Mengembalikan seluruh teks JSON.
`$.info.type`	`NULL`	Error	Bukan objek atau array. Gunakan `JSON_VALUE` sebagai gantinya.
`$.info.address.town`	`NULL`	Error	Bukan objek atau array. Gunakan `JSON_VALUE` sebagai gantinya.
`$.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	Bukan array.
`$.info.none`	`NULL`	Error	Properti tidak ada.

Menggunakan JSON_QUERY dengan FOR JSON

JSON_QUERY mengembalikan fragmen JSON yang valid. Akibatnya, FOR JSON tidak lolos dari karakter khusus dalam nilai pengembalian JSON_QUERY.

Jika Anda mengembalikan hasil dengan FOR JSON, dan Anda menyertakan data yang sudah dalam format JSON (dalam kolom atau sebagai hasil ekspresi), bungkus data JSON dengan JSON_QUERY tanpa parameter jalur .

Examples

A. Mengembalikan fragmen JSON

Contoh berikut menunjukkan cara mengembalikan fragmen JSON dari CustomFields kolom dalam hasil kueri.

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

B. Sertakan fragmen JSON dalam output FOR JSON

Contoh berikut menunjukkan cara menyertakan fragmen JSON dalam output klausul FOR JSON.

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

C. Gunakan WITH ARRAY WRAPPER dengan fungsi JSON_QUERY

Contoh berikut menunjukkan penggunaan WITH ARRAY WRAPPER dengan JSON_QUERY fungsi untuk mengembalikan beberapa elemen dari array 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;

Berikut kumpulan hasilnya.

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-18