JSON_MODIFY (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_MODIFY dizimi, JSON dizesindeki bir özelliğin değerini güncelleştirir ve güncelleştirilmiş JSON dizesini döndürür.

Transact-SQL söz dizimi kuralları

Syntax

JSON_MODIFY ( expression , path , newValue )

Arguments

expression

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

JSON_MODIFY ifade geçerli JSON içermiyorsa bir hata döndürür.

path

Güncelleştirilecek özelliği belirten bir JSON yol ifadesi.

path aşağıdaki söz dizimine sahiptir:

[append] [ lax | strict ] $.<json path>

• append

  yeni değerin <json path>tarafından başvuruda bulunılan diziye eklenmesi gerektiğini belirten isteğe bağlı değiştirici.

• lax

  <json path> tarafından başvuruda bulunılan özelliğin mevcut olması gerekmeyen bir özellik olduğunu belirtir. Özelliği yoksa, JSON_MODIFY yeni değeri belirtilen yola eklemeyi dener. Özellik yola eklenemiyorsa ekleme başarısız olabilir. Gevşek veyakatı belirtmezseniz, lax varsayılan moddur.

• strict

  <json path> tarafından başvuruda bulunılan özelliğin JSON ifadesinde olması gerektiğini belirtir. Özelliği yoksa, JSON_MODIFY bir hata döndürür.

• <json path>

  Güncelleştirilecek özelliğin yolunu belirtir. Daha fazla bilgi için bkz. JSON Yol İfadeleri.

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

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

newValue

Yol tarafından belirtilen özelliğin yeni değeri.

Yeni değer varchar, nvarchar, char, tinyint, smallint, int, bigint, bit, ondalık/sayısal veya gerçek/float olmalıdır. Metin veri türü desteklenmez.

Lax modunda, yeni değer JSON_MODIFYNULL belirtilen anahtarı siler.

JSON_MODIFY değerin türü varchar veya nvarchar ise, yeni değerdeki tüm özel karakterlerin kaçışını verir. FOR JSON, JSON_QUERYveya JSON_MODIFYtarafından üretilen JSON düzgün biçimlendirilmiş bir metin değerinden kaçış yoktur.

Dönüş değeri

İfadenin güncelleştirilmiş değerini düzgün biçimlendirilmiş JSON metni olarak döndürür.

Remarks

JSON_MODIFY işlevi mevcut bir özelliğin değerini güncelleştirmenize, yeni bir anahtar:değer çifti eklemenize veya modlarla sağlanan değerlerin birleşimine göre bir anahtarı silmenize olanak tanır.

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

Yeni değer	Yol var	Lazim mod	Katı mod
NOT NULL	Yes	Mevcut değeri güncelleştirin.	Mevcut değeri güncelleştirin.
NOT NULL	No	Belirtilen yolda yeni bir anahtar-değer çifti oluşturmayı deneyin. Bu başarısız olabilir. Örneğin, $.user.setting.themeyolunu belirtirseniz JSON_MODIFYtheme veya $.user nesneleri yoksa veya ayarlar bir dizi veya skaler değerse anahtar $.user.settings eklemez.	Hata - INVALID_PROPERTY
NULL	Yes	Mevcut özelliği silin.	Mevcut değeri null olarak ayarlayın.
NULL	No	Eylem yok. İlk bağımsız değişken sonuç olarak döndürülür.	Hata - INVALID_PROPERTY

Gevşek modda, JSON_MODIFY yeni bir anahtar:değer çifti oluşturmaya çalışır, ancak bazı durumlarda başarısız olabilir.

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

Examples

A. Temel işlemler

Aşağıdaki örnekte JSON metniyle yapılabilecek temel işlemler gösterilmektedir.

DECLARE @info NVARCHAR(100) = '{"name":"John","skills":["C#","SQL"]}';
PRINT @info;

-- Update name
SET @info = JSON_MODIFY(@info, '$.name', 'Mike');
PRINT @info;

-- Insert surname
SET @info = JSON_MODIFY(@info, '$.surname', 'Smith');
PRINT @info;

-- Set name NULL
SET @info = JSON_MODIFY(@info, 'strict $.name', NULL);
PRINT @info;

-- Delete name
SET @info = JSON_MODIFY(@info, '$.name', NULL);
PRINT @info;

-- Add skill
SET @info = JSON_MODIFY(@info, 'append $.skills', 'Azure');
PRINT @info;

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

{
    "name": "John",
    "skills": ["C#", "SQL"]
} {
    "name": "Mike",
    "skills": ["C#", "SQL"]
} {
    "name": "Mike",
    "skills": ["C#", "SQL"],
    "surname": "Smith"
} {
    "skills": ["C#", "SQL"],
    "surname": "Smith"
} {
    "skills": ["C#", "SQL", "Azure"],
    "surname": "Smith"
}

B. Birden fazla güncelleme

JSON_MODIFYile yalnızca bir özelliği güncelleştirebilirsiniz. Birden çok güncelleştirme yapmanız gerekiyorsa, birden çok JSON_MODIFY çağrısı kullanabilirsiniz.

DECLARE @info NVARCHAR(100) = '{"name":"John","skills":["C#","SQL"]}';
PRINT @info;

-- Multiple updates
SET @info = JSON_MODIFY(JSON_MODIFY(JSON_MODIFY(@info, '$.name', 'Mike'), '$.surname', 'Smith'), 'append $.skills', 'Azure');
PRINT @info;

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

{
    "name": "John",
    "skills": ["C#", "SQL"]
} {
    "name": "Mike",
    "skills": ["C#", "SQL", "Azure"],
    "surname": "Smith"
}

C. Anahtarı yeniden adlandırma

Aşağıdaki örnekte JSON metnindeki bir özelliğin JSON_MODIFY işleviyle nasıl yeniden adlandırılası gösterilmektedir. İlk olarak mevcut bir özelliğin değerini alıp yeni anahtar:değer çifti olarak ekleyebilirsiniz. Ardından eski özelliğin değerini NULLolarak ayarlayarak eski anahtarı silebilirsiniz.

DECLARE @product NVARCHAR(100) = '{"price":49.99}';
PRINT @product;

-- Rename property
SET @product = JSON_MODIFY(JSON_MODIFY(@product, '$.Price', CAST(JSON_VALUE(@product, '$.price') AS NUMERIC(4, 2))), '$.price', NULL);
PRINT @product;

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

{
    "price": 49.99
} {
    "Price": 49.99
}

Yeni değeri sayısal bir türe atamazsanız, JSON_MODIFY bunu metin olarak değerlendirir ve çift tırnak içine alır.

D. Değeri artırma

Aşağıdaki örnekte, JSON_MODIFY işleviyle JSON metnindeki bir özelliğin değerini artırma gösterilmektedir. İlk olarak mevcut özelliğin değerini alıp yeni bir key:value çifti olarak ekleyebilirsiniz. Ardından eski özelliğin değerini NULLolarak ayarlayarak eski anahtarı silebilirsiniz.

DECLARE @stats NVARCHAR(100) = '{"click_count": 173}';
PRINT @stats;

-- Increment value
SET @stats = JSON_MODIFY(@stats, '$.click_count', CAST(JSON_VALUE(@stats, '$.click_count') AS INT) + 1);
PRINT @stats;

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

{
    "click_count": 173
} {
    "click_count": 174
}

E. JSON nesnesini değiştirme

JSON_MODIFY düzgün biçimlendirilmiş JSON metni içerse bile newValue bağımsız değişkenini düz metin olarak ele alır. Sonuç olarak, işlevin JSON çıkışı çift tırnak içine alınır ve aşağıdaki örnekte gösterildiği gibi tüm özel karakterlerden çıkış yapılır.

DECLARE @info NVARCHAR(100) = '{"name":"John","skills":["C#","SQL"]}';
PRINT @info;

-- Update skills array
SET @info = JSON_MODIFY(@info, '$.skills', '["C#","T-SQL","Azure"]');
PRINT @info;

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

{
    "name": "John",
    "skills": ["C#", "SQL"]
} {
    "name": "John",
    "skills": "[\"C#\",\"T-SQL\",\"Azure\"]"
}

Otomatik kaçışı önlemek için işlevini kullanarak newValue değerini JSON_QUERY sağlayın. JSON_MODIFY, JSON_QUERY tarafından döndürülen değerin düzgün biçimlendirilmiş JSON olduğunu bilir, bu nedenle değerden kaçamaz.

DECLARE @info NVARCHAR(100) = '{"name":"John","skills":["C#","SQL"]}';
PRINT @info;

-- Update skills array
SET @info = JSON_MODIFY(@info, '$.skills', JSON_QUERY('["C#","T-SQL","Azure"]'));
PRINT @info;

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

{
    "name": "John",
    "skills": ["C#", "SQL"]
} {
    "name": "John",
    "skills": ["C#", "T-SQL", "Azure"]
}

F. JSON sütununu güncelleştirme

Aşağıdaki örnek, JSON içeren bir tablo sütunundaki bir özelliğin değerini güncelleştirir.

UPDATE Employee
SET jsonCol = JSON_MODIFY(jsonCol, '$.info.address.town', 'London')
WHERE EmployeeID = 17;

İlgili içerik

• JSON Yol İfadeleri
• SQL Server'da JSON verilerini