JSON_MODIFY (Transact-SQL)

Gäller för: SQL Server 2016 (13.x) och senare versioner Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL Analytics-slutpunkt i Microsoft Fabric Warehouse i Microsoft FabricSQL Database i Förhandsversion av Microsoft Fabric

Syntaxen JSON_MODIFY uppdaterar värdet för en egenskap i en JSON-sträng och returnerar den uppdaterade JSON-strängen.

Transact-SQL syntaxkonventioner

Syntax

JSON_MODIFY ( expression , path , newValue )

Arguments

expression

An expression. Vanligtvis namnet på en variabel eller en kolumn som innehåller JSON-text.

JSON_MODIFY returnerar ett fel om uttrycket inte innehåller giltig JSON.

path

Ett JSON-sökvägsuttryck som anger den egenskap som ska uppdateras.

sökvägen har följande syntax:

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

• append

  Valfri modifierare som anger att det nya värdet ska läggas till i matrisen som refereras av <json path>.

• lax

  Anger att egenskapen som refereras av <json path> inte behöver finnas. Om egenskapen inte finns försöker JSON_MODIFY infoga det nya värdet på den angivna sökvägen. Infogningen kan misslyckas om egenskapen inte kan infogas på sökvägen. Om du inte anger släpphänt eller strikt är lax standardläget.

• strict

  Anger att egenskapen som refereras av <json path> måste finnas i JSON-uttrycket. Om egenskapen inte finns returnerar JSON_MODIFY ett fel.

• <json path>

  Anger sökvägen för egenskapen som ska uppdateras. Mer information finns i JSON-sökvägsuttryck.

  I SQL Server 2017 (14.x) och i Azure SQL Database kan du ange en variabel som värdet för sökvägen.

  JSON_MODIFY returnerar ett fel om sökvägens format inte är giltigt.

newValue

Det nya värdet för egenskapen som anges av sökvägen.

Det nya värdet måste vara varchar, nvarchar, char, tinyint, smallint, int, bigint, bit, decimal/numeriskt eller verkligt/flyttal. Textdatatypen stöds inte.

I släpphänt läge tar JSON_MODIFY bort den angivna nyckeln om det nya värdet är NULL.

JSON_MODIFY escapes alla specialtecken i det nya värdet om typen av värdet är varchar eller nvarchar. Ett textvärde är inte undantaget om det är korrekt formaterat JSON som skapats av FOR JSON, JSON_QUERYeller JSON_MODIFY.

Return value

Returnerar det uppdaterade uttryckets värde som korrekt formaterad JSON-text.

Remarks

Med funktionen JSON_MODIFY kan du antingen uppdatera värdet för en befintlig egenskap, infoga ett nytt nyckel:värde-par eller ta bort en nyckel baserat på en kombination av lägen och angivna värden.

I följande tabell jämförs beteendet för JSON_MODIFY i slappt läge och i strikt läge. Mer information om den valfria sökvägslägesspecifikationen (slapp eller strikt) finns i JSON Path Expressions (JSON Path Expressions).

I släpphänt läge försöker JSON_MODIFY skapa ett nytt nyckel:värde-par, men i vissa fall kan det misslyckas.

JSON-funktioner fungerar på samma sätt oavsett om JSON-dokumentet lagras i varchar, nvarchar eller den interna json-datatypen .

Examples

A. Basic operations

I följande exempel visas grundläggande åtgärder som kan utföras med JSON-text.

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;

Här är resultatuppsättningen.

{
    "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. Multiple updates

Med JSON_MODIFYkan du bara uppdatera en egenskap. Om du behöver göra flera uppdateringar kan du använda flera JSON_MODIFY-anrop.

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;

Här är resultatuppsättningen.

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

C. Byt namn på en nyckel

I följande exempel visas hur du byter namn på en egenskap i JSON-text med funktionen JSON_MODIFY. Först kan du ta värdet för en befintlig egenskap och infoga den som ett nytt nyckel:värde-par. Sedan kan du ta bort den gamla nyckeln genom att ange värdet för den gamla egenskapen till NULL.

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;

Här är resultatuppsättningen.

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

Om du inte omvandlar det nya värdet till en numerisk typ behandlar JSON_MODIFY det som text och omger det med dubbla citattecken.

D. Öka ett värde

I följande exempel visas hur du ökar värdet för en egenskap i JSON-text med funktionen JSON_MODIFY. Först kan du ta värdet för den befintliga egenskapen och infoga den som ett nytt nyckel:värde-par. Sedan kan du ta bort den gamla nyckeln genom att ange värdet för den gamla egenskapen till NULL.

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;

Här är resultatuppsättningen.

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

E. Ändra ett JSON-objekt

JSON_MODIFY behandlar argumentet newValue som oformaterad text även om det innehåller korrekt formaterad JSON-text. Därför omges JSON-utdata av funktionen med dubbla citattecken och alla specialtecken är undantagna, vilket visas i följande exempel.

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;

Här är resultatuppsättningen.

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

För att undvika automatisk utrymning anger du newValue med hjälp JSON_QUERY av funktionen . JSON_MODIFY vet att värdet som returneras av JSON_QUERY är korrekt formaterat JSON, så att det inte tar bort värdet.

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;

Här är resultatuppsättningen.

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

F. Uppdatera en JSON-kolumn

I följande exempel uppdateras värdet för en egenskap i en tabellkolumn som innehåller JSON.

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

Related content

• JSON-sökvägsuttryck
• JSON-data i SQL Server