JSON_VALUE (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

JSON_VALUE JSON dizesinden skaler değer ayıklamak için söz dizimini kullanın.

Skaler değer yerine JSON dizesinden nesne veya dizi ayıklamak için bkz. JSON_QUERY. 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

SQL Server 2025 (17.x) ve sonraki sürümleri için söz dizimi.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

SQL Server 2022 (16.x) ve önceki sürümlerde , RETURNING dahil değildir.

Arguments

expression

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

JSON_VALUE tarafından tanımlanan değeri bulmadan önce ifadede geçerli olmayan JSON bulursa işlev bir hata döndürür. JSON_VALUE 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

A JSON ayıklanan özelliği belirten yol. Daha fazla bilgi için bkz. SQL Veritabanı Altyapısı'ndaki JSON yol ifadeleri.

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

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

data_type

Dönüş değeri için kullanmak istediğiniz veri türü. Bu tür yalnızca giriş bir JSON türüyse desteklenir. Desteklenen veri türleri şunlardır: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 ve datetimeoffset.

Dönüş değeri

SQL Server 2025 (17.x) ve sonraki sürümler için geçerlidir.

eklemezseniz RETURNING:

• nvarchar(4000) türünde tek bir metin değeri döndürür. Döndürülen değerin harmanlaması, giriş ifadesinin harmanlaması ile eşleşir.

• Değer 4.000 karakterden büyükse:

  • Lax modunda döndürür JSON_VALUENULL.
  • Katı modda JSON_VALUE bir hata döndürür.

  4.000 karakterden büyük skaler değerler döndürmeniz gerekiyorsa yerine kullanın OPENJSONJSON_VALUE. Daha fazla bilgi için bkz. OPENJSON.

eklerseniz RETURNING:

data_type içinde belirtilen değeri döndürür. Desteklenen veri türleri şunlardır: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 ve datetimeoffset.

JSON işlevleri, JSON belgesinin varchar, nvarchar veya yerel json veri türünde depolanmasıyla aynı şekilde çalışır.

Remarks

Lax modu ve katı mod

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

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

Aşağıdaki tablo, JSON_VALUE 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 ifadeleri.

Path	Lax modunda dönüş değeri	Katı modda değer döndürme	Daha fazla bilgi
$	NULL	Error	Skaler değer değil. Bunun yerine JSON_QUERY kullanın.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info." adres"	NULL	Error	Skaler değer değil. Bunun yerine JSON_QUERY kullanın.
$.info.tags	NULL	Error	Skaler değer değil. Bunun yerine JSON_QUERY kullanın.
$.info.type[0]	NULL	Error	Dizi değil.
$.info.none	NULL	Error	Özellik yok.

Examples

Örnek 1

Aşağıdaki örnek, JSON özelliklerinin town değerlerini ve state sorgu sonuçlarında kullanır. Kaynağın JSON_VALUE harmanlamasını koruduğundan, sonuçların sıralama düzeni sütunun harmanlama düzenine jsonInfo bağlıdır.

Note

Bu örnekte adlı Person.Person tablonun bir jsonInfo JSON metni sütunu içerdiği ve bu sütunun daha önce lax modu ve katı mod tartışmasında gösterilen yapıya sahip olduğu varsayılır. AdventureWorks Örnek veritabanında Person tablo bir jsonInfo sütun içermez.

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');

Örnek 2

Aşağıdaki örnek, JSON özelliğinin town değerini yerel bir değişkene ayıklar.

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

Örnek 3

Aşağıdaki örnek, JSON özelliklerinin değerlerine göre hesaplanan sütunlar oluşturur.

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')
);

Örnek 4

Aşağıdaki örnek kullanarak JSON_VALUE JSON dizisinden bir değer ayıklar ve değeri tarih türü değeri olarak döndürür.

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

İlgili içerik

• SQL Veritabanı Altyapısı'nda JSON yol ifadeleri
• SQL Server içindeki JSON verileri