Sdílet prostřednictvím

JSON_MODIFY (Transact-SQL)

  • Článek

platí pro: SQL Server 2016 (13.x) a novější Azure SQL Databaseazure SQL Managed Instancekoncový bod azure Synapse AnalyticsSQL Analytics v Microsoft FabricWarehouse v Microsoft Fabric

Aktualizuje hodnotu vlastnosti v řetězci JSON a vrátí aktualizovaný řetězec JSON.

Transact-SQL konvence syntaxe

Syntax

JSON_MODIFY ( expression , path , newValue )

Argumenty

výrazu

Výraz. Obvykle název proměnné nebo sloupce, který obsahuje text JSON.

JSON_MODIFY vrátí chybu, pokud výraz neobsahuje platný kód JSON.

cesty

Výraz cesty JSON, který určuje vlastnost, která se má aktualizovat.

cesta má následující syntaxi:

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

  • připojit

    Volitelný modifikátor, který určuje, že nová hodnota by měla být připojena k poli odkazovanému <json path>.

  • laxní

    Určuje, že vlastnost odkazovaná <json path> nemusí existovat. Pokud vlastnost není k dispozici, JSON_MODIFY se pokusí vložit novou hodnotu do zadané cesty. Vložení může selhat, pokud vlastnost nelze vložit do cesty. Pokud nezadáte laxní nebo striktní, laxní je výchozí režim.

  • striktní

    Určuje, že vlastnost odkazovaná <json path> musí být ve výrazu JSON. Pokud vlastnost není k dispozici, JSON_MODIFY vrátí chybu.

  • <json path>

    Určuje cestu, kterou má vlastnost aktualizovat. Další informace najdete v tématu výrazy cesty JSON (SQL Server).

    V SQL Serveru 2017 (14.x) a v Azure SQL Database můžete zadat proměnnou jako hodnotu cesty.

    JSON_MODIFY vrátí chybu, pokud formát cesty není platný.

newValue

Nová hodnota vlastnosti určené cesta.

Nová hodnota musí být varchar, nvarchar, char, tinyint, smallint,int, bigint, bit, desetinnéčíselnénebo skutečnéplovoucí. Datový typ se nepodporuje.

V laxní režimu JSON_MODIFY odstraní zadaný klíč, pokud je nová hodnota NULL.

JSON_MODIFY uchycuje všechny speciální znaky v nové hodnotě, pokud je typ hodnoty varchar nebo nvarchar. Textová hodnota není uchycená, pokud je správně formátovaný JSON vytvořený FOR JSON, JSON_QUERYnebo JSON_MODIFY.

Návratová hodnota

Vrátí aktualizovanou hodnotu výrazu jako správně formátovaný text JSON.

Poznámky

Funkce JSON_MODIFY umožňuje aktualizovat hodnotu existující vlastnosti, vložit nový pár klíč:hodnota nebo odstranit klíč na základě kombinace režimů a zadaných hodnot.

Následující tabulka porovnává chování JSON_MODIFY v laxním režimu a v přísném režimu. Další informace o volitelné specifikaci režimu cesty (lax nebo striktní) najdete v tématu výrazy cesty JSON (SQL Server).

Nová hodnota Cesta existuje. Laxní režim Striktní režim
NOT NULL Ano Aktualizujte existující hodnotu. Aktualizujte existující hodnotu.
NOT NULL Ne Pokuste se vytvořit nový pár klíč-hodnota v zadané cestě.

To může selhat. Pokud například zadáte cestu $.user.setting.theme, JSON_MODIFY nevloží klíč theme, pokud $.user nebo $.user.settings objekty neexistují, nebo pokud je nastavení matice nebo skalární hodnota.		 Chyba – INVALID_PROPERTY
NULL Ano Odstraňte existující vlastnost. Nastavte existující hodnotu na hodnotu null.
NULL Ne Žádná akce. První argument se vrátí jako výsledek. Chyba – INVALID_PROPERTY

V laxní režimu se JSON_MODIFY pokusí vytvořit nový pár klíč:hodnota, ale v některých případech může selhat.

Funkce JSON fungují stejně, jako když je dokument JSON uložený v varchar, nvarcharnebo nativní json datového typu.

Příklady

A. Základní operace

Následující příklad ukazuje základní operace, které je možné provést s textem JSON.

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;

Tady je sada výsledků.

{
    "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. Více aktualizací

S JSON_MODIFYmůžete aktualizovat pouze jednu vlastnost. Pokud potřebujete provést více aktualizací, můžete použít více JSON_MODIFY volání.

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;

Tady je sada výsledků.

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

C. Přejmenování klíče

Následující příklad ukazuje, jak přejmenovat vlastnost v textu JSON pomocí funkce JSON_MODIFY. Nejprve můžete vzít hodnotu existující vlastnosti a vložit ji jako nový pár klíč:hodnota. Starý klíč pak můžete odstranit nastavením hodnoty staré vlastnosti na 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;

Tady je sada výsledků.

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

Pokud novou hodnotu nepřetypujete na číselný typ, JSON_MODIFY ji považuje za text a uzavře ji do dvojitých uvozovek.

D. Zvýšení hodnoty

Následující příklad ukazuje, jak zvýšit hodnotu vlastnosti v textu JSON pomocí funkce JSON_MODIFY. Nejprve můžete vzít hodnotu existující vlastnosti a vložit ji jako nový pár klíč:hodnota. Starý klíč pak můžete odstranit nastavením hodnoty staré vlastnosti na 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;

Tady je sada výsledků.

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

E. Úprava objektu JSON

JSON_MODIFY považuje newValue argument za prostý text, i když obsahuje správně formátovaný text JSON. Výsledkem je, že výstup JSON funkce je obklopen dvojitými uvozovkami a všechny speciální znaky se uvozují, jak je znázorněno v následujícím příkladu.

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;

Tady je sada výsledků.

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

Pokud se chcete vyhnout automatickému zapouzdření, zadejte newValue pomocí funkce JSON_QUERY. JSON_MODIFY ví, že hodnota vrácená JSON_QUERY je správně naformátovaná ve formátu JSON, takže neunikne této hodnotě.

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;

Tady je sada výsledků.

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

F. Aktualizace sloupce JSON

Následující příklad aktualizuje hodnotu vlastnosti ve sloupci tabulky, který obsahuje JSON.

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

Související obsah