JSON_VALUE (Transact-SQL)

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

JSON_VALUE Gunakan sintaks untuk mengekstrak nilai skalar dari string JSON.

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

Konvensi sintaks transact-SQL

Syntax

Sintaks untuk SQL Server 2025 (17.x) dan versi yang lebih baru.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

Di SQL Server 2022 (16.x) dan versi yang lebih lama, RETURNING tidak disertakan.

Arguments

expression

Ekspresi yang biasanya merupakan nama variabel atau kolom yang berisi teks JSON.

Jika JSON_VALUE menemukan JSON yang tidak valid dalam ekspresi sebelum menemukan nilai yang diidentifikasi berdasarkan jalur, fungsi mengembalikan kesalahan. Jika JSON_VALUE 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

A JSON jalur yang menentukan properti yang akan diekstrak. Untuk informasi selengkapnya, lihat Ekspresi jalur JSON di SQL Database Engine.

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

Jika format jalur tidak valid, JSON_VALUE mengembalikan kesalahan.

data_type

Jenis data yang ingin Anda gunakan untuk nilai yang dikembalikan. Jenis ini hanya didukung jika input adalah jenis JSON. Jenis data yang didukung adalah: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2, dan datetimeoffset.

Mengembalikan nilai

Berlaku untuk: SQL Server 2025 (17.x) dan versi yang lebih baru.

Jika Anda tidak menyertakan RETURNING:

• Mengembalikan nilai teks tunggal jenis nvarchar(4000). Kolase nilai yang dikembalikan cocok dengan kolase ekspresi input.

• Jika nilainya lebih besar dari 4.000 karakter:

  • Dalam mode laks, JSON_VALUE mengembalikan NULL.
  • Dalam mode ketat, JSON_VALUE mengembalikan kesalahan.

  Jika Anda perlu mengembalikan nilai skalar yang lebih besar dari 4.000 karakter, gunakan OPENJSON alih-alih JSON_VALUE. Untuk informasi selengkapnya, lihat OPENJSON.

Jika Anda menyertakan RETURNING:

Mengembalikan nilai yang ditentukan dalam data_type. Jenis data yang didukung adalah: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2, dan datetimeoffset.

Fungsi JSON bekerja dengan cara yang sama apakah dokumen JSON disimpan dalam varchar, nvarchar, atau jenis data json asli.

Remarks

Mode laks dan mode ketat

Pertimbangkan teks JSON berikut:

DECLARE @jsonInfo AS NVARCHAR (MAX);

SET @jsonInfo = N'{
     "info":{
       "type":1,
       "address":{
         "town":"Bristol",
         "county":"Avon",
         "country/region":"England"
       },
       "tags":["Sport", "Water polo"]
    },
    "type":"Basic"
 }';

Tabel berikut membandingkan perilaku JSON_VALUE dalam mode lax dan dalam mode ketat. Untuk informasi selengkapnya tentang spesifikasi mode jalur opsional (lax atau ketat), lihat ekspresi jalur JSON di SQL Database Engine.

Path	Mengembalikan nilai dalam mode laks	Mengembalikan nilai dalam mode ketat	Info lebih lanjut
$	NULL	Error	Bukan nilai skalar. Gunakan JSON_QUERY sebagai gantinya.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	Bukan nilai skalar. Gunakan JSON_QUERY sebagai gantinya.
$.info.tags	NULL	Error	Bukan nilai skalar. Gunakan JSON_QUERY sebagai gantinya.
$.info.type[0]	NULL	Error	Bukan array.
$.info.none	NULL	Error	Properti tidak ada.

Examples

Contoh 1

Contoh berikut menggunakan nilai properti town JSON dan state dalam hasil kueri. Karena JSON_VALUE mempertahankan kolase sumber, urutan pengurutan hasil tergantung pada kolase jsonInfo kolom.

Note

Contoh ini mengasumsikan bahwa tabel bernama Person.Person berisi jsonInfo kolom teks JSON, dan bahwa kolom ini memiliki struktur yang ditunjukkan sebelumnya dalam diskusi mode laks dan mode ketat. AdventureWorks Dalam database sampel, Person tabel tidak berisi jsonInfo kolom.

SELECT FirstName,
       LastName,
       JSON_VALUE(jsonInfo, '$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo, '$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo, '$.info.address.town');

Contoh 2

Contoh berikut mengekstrak nilai properti town JSON ke dalam variabel lokal.

DECLARE @jsonInfo AS NVARCHAR (MAX);
DECLARE @town AS NVARCHAR (32);

SET @jsonInfo = N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[0].town'); -- Paris
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[1].town'); -- London

Contoh 3

Contoh berikut membuat kolom komputasi berdasarkan nilai properti JSON.

CREATE TABLE dbo.Store
(
    StoreID INT IDENTITY (1, 1) NOT NULL,
    Address VARCHAR (500),
    jsonContent NVARCHAR (4000),
    Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
    Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
);

Contoh 4

Contoh berikut mengekstrak nilai dari array JSON menggunakan JSON_VALUE dan mengembalikan nilai sebagai nilai jenis tanggal.

DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';

SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;

date_value
--------
2025-01-01

Konten terkait

• Ekspresi jalur JSON di Mesin Database SQL
• Data JSON dalam SQL Server