JSON_MODIFY (Transact-SQL)

Van toepassing op: SQL Server 2016 (13.x) en latere versies Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL Analytics-eindpunt in Microsoft Fabric,Warehouse in Microsoft Fabric,SQL Database in Microsoft Fabric Preview

De JSON_MODIFY syntaxis werkt de waarde van een eigenschap in een JSON-tekenreeks bij en retourneert de bijgewerkte JSON-tekenreeks.

Transact-SQL syntaxisconventies

Syntax

JSON_MODIFY ( expression , path , newValue )

Arguments

expression

An expression. Meestal de naam van een variabele of een kolom die JSON-tekst bevat.

JSON_MODIFY retourneert een fout als de expressie geen geldige JSON bevat.

path

Een JSON-padexpressie waarmee de eigenschap wordt opgegeven die moet worden bijgewerkt.

het pad heeft de volgende syntaxis:

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

• append

  Optionele wijziging die aangeeft dat de nieuwe waarde moet worden toegevoegd aan de matrix waarnaar wordt verwezen door <json path>.

• lax

  Hiermee geeft u op dat de eigenschap waarnaar wordt verwezen door <json path> niet hoeft te bestaan. Als de eigenschap niet aanwezig is, probeert JSON_MODIFY de nieuwe waarde op het opgegeven pad in te voegen. Invoegen kan mislukken als de eigenschap niet kan worden ingevoegd op het pad. Als u geen lax of strikt opgeeft, is lax de standaardmodus.

• strict

  Hiermee geeft u op dat de eigenschap waarnaar wordt verwezen door <json path> zich in de JSON-expressie moet bevinden. Als de eigenschap niet aanwezig is, retourneert JSON_MODIFY een fout.

• <json path>

  Hiermee geeft u het pad op voor de eigenschap die moet worden bijgewerkt. Zie JSON-padexpressies voor meer informatie.

  In SQL Server 2017 (14.x) en in Azure SQL Database kunt u een variabele opgeven als de waarde van het pad.

  JSON_MODIFY retourneert een fout als de indeling van het pad niet geldig is.

newValue

De nieuwe waarde voor de eigenschap die door het pad is opgegeven.

De nieuwe waarde moet varchar, nvarchar, char, tinyint, smallint, int, bigint, bit, decimale/numerieke of reële/float zijn. Het gegevenstype tekst wordt niet ondersteund.

In de laxmodus verwijdert JSON_MODIFY de opgegeven sleutel als de nieuwe waarde NULLis.

JSON_MODIFY escapes alle speciale tekens in de nieuwe waarde als het type van de waarde varchar of nvarchar is. Een tekstwaarde wordt niet escaped als deze JSON correct is opgemaakt door FOR JSON, JSON_QUERYof JSON_MODIFY.

Return value

Retourneert de bijgewerkte waarde van de expressie als juist opgemaakte JSON-tekst.

Remarks

Met de functie JSON_MODIFY kunt u de waarde van een bestaande eigenschap bijwerken, een nieuw sleutel:waardepaar invoegen of een sleutel verwijderen op basis van een combinatie van modi en opgegeven waarden.

In de volgende tabel wordt het gedrag van JSON_MODIFY in de lax-modus en in de strikte modus vergeleken. Zie JSON-padexpressies voor meer informatie over de specificatie van de optionele padmodus (lax of strikt).

In de lax-modus probeert JSON_MODIFY een nieuw sleutel:waardepaar te maken, maar in sommige gevallen kan dit mislukken.

JSON-functies werken hetzelfde, ongeacht of het JSON-document is opgeslagen in varchar, nvarchar of het systeemeigen json-gegevenstype .

Examples

A. Basic operations

In het volgende voorbeeld ziet u basisbewerkingen die kunnen worden uitgevoerd met JSON-tekst.

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;

Dit is de resultatenset.

{
    "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

Met JSON_MODIFYkunt u slechts één eigenschap bijwerken. Als u meerdere updates moet uitvoeren, kunt u meerdere JSON_MODIFY aanroepen gebruiken.

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;

Dit is de resultatenset.

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

C. De naam van een sleutel wijzigen

In het volgende voorbeeld ziet u hoe u de naam van een eigenschap in JSON-tekst wijzigt met de functie JSON_MODIFY. Eerst kunt u de waarde van een bestaande eigenschap gebruiken en invoegen als een nieuw sleutel:waardepaar. Vervolgens kunt u de oude sleutel verwijderen door de waarde van de oude eigenschap in te stellen op 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;

Dit is de resultatenset.

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

Als u de nieuwe waarde niet naar een numeriek type cast, JSON_MODIFY deze als tekst behandelt en tussen dubbele aanhalingstekens plaatst.

D. Een waarde verhogen

In het volgende voorbeeld ziet u hoe u de waarde van een eigenschap in JSON-tekst kunt verhogen met de functie JSON_MODIFY. Eerst kunt u de waarde van de bestaande eigenschap gebruiken en invoegen als een nieuw sleutel:waardepaar. Vervolgens kunt u de oude sleutel verwijderen door de waarde van de oude eigenschap in te stellen op 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;

Dit is de resultatenset.

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

E. Een JSON-object wijzigen

JSON_MODIFY behandelt het argument newValue als tekst zonder opmaak, zelfs als het JSON-tekst met de juiste opmaak bevat. Als gevolg hiervan wordt de JSON-uitvoer van de functie omgeven door dubbele aanhalingstekens en worden alle speciale tekens ontsnapt, zoals wordt weergegeven in het volgende voorbeeld.

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;

Dit is de resultatenset.

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

Als u automatisch ontsnappen wilt voorkomen, geeft u newValue op met behulp van de JSON_QUERY functie. JSON_MODIFY weet dat de waarde die door JSON_QUERY wordt geretourneerd, JSON correct is opgemaakt, zodat deze niet aan de waarde ontsnapt.

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;

Dit is de resultatenset.

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

F. Een JSON-kolom bijwerken

In het volgende voorbeeld wordt de waarde van een eigenschap in een tabelkolom bijgewerkt die JSON bevat.

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

Related content

• JSON-padexpressies
• JSON-gegevens in SQL Server