JSON_MODIFY (Transact-SQL)
Se aplica a:
SQL Server 2016 (13.x) y versiones posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics
Actualiza el valor de una propiedad en una cadena JSON y devuelve la cadena JSON actualizada.
Convenciones de sintaxis de Transact-SQL
Sintaxis
JSON_MODIFY ( expression , path , newValue )
Argumentos
expression
Expresión. Suele ser el nombre de una variable o una columna con texto JSON.
JSON_MODIFY devuelve un error si expression no contiene un valor JSON válido.
path
Expresión de ruta de acceso JSON que especifica la propiedad que se va a actualizar.
path tiene la siguiente sintaxis:
[append] [ lax | strict ] $.<json path>
append
Modificador opcional que especifica que el nuevo valor se debe anexar a la matriz a la que hace referencia <json path>.lax
Especifica que la propiedad a la que hace referencia <json path> no tiene que existir necesariamente. Si la propiedad no está presente, JSON_MODIFY intenta insertar el nuevo valor en la ruta de acceso especificada. Es posible que la inserción no se realice si la propiedad no se puede insertar en la ruta de acceso. Si no se especifica lax o strict, lax es el modo predeterminado.strict
Especifica que la propiedad a la que hace referencia <json path> debe estar en la expresión JSON. Si la propiedad no está presente, JSON_MODIFY devuelve un error.<Ruta de acceso JSON>
Especifica la ruta de acceso de la propiedad que se va a actualizar. Para más información, vea Expresiones de ruta de acceso JSON (SQL Server).
En SQL Server 2017 (14.x) y en Azure SQL Database, puede proporcionar una variable como el valor de path.
JSON_MODIFY devuelve un error si el formato de path no es válido.
newValue
El nuevo valor de la propiedad especificada por path.
El nuevo valor debe ser de tipo [n]varchar o text.
En el modo lax, JSON_MODIFY elimina la clave especificada si el nuevo valor es NULL.
JSON_MODIFY convierte todos los caracteres especiales en el nuevo valor si el tipo del valor es NVARCHAR o VARCHAR. No se aplicará escape a un valor de texto si presenta un formato JSON correcto generado por FOR JSON, JSON_QUERY o JSON_MODIFY.
Valor devuelto
Devuelve el valor actualizado de expression como texto con formato JSON correcto.
Observaciones
La función JSON_MODIFY permite actualizar el valor de una propiedad existente, insertar un nuevo par clave-valor o eliminar una clave según una combinación de modos y valores proporcionados.
En la siguiente tabla se compara el comportamiento de JSON_MODIFY en modo lax y en modo strict. Para más información sobre la especificación del modo de ruta de acceso opcional (lax o strict), vea Expresiones de ruta de acceso JSON (SQL Server).
| Valor nuevo | La ruta de acceso existe | Modo lax | Modo strict |
|---|---|---|---|
| Not NULL | Sí | Se actualiza el valor existente. | Se actualiza el valor existente. |
| Not NULL | No | Se intenta crear un par clave-valor en la ruta de acceso especificada. Esto puede producir un error. Por ejemplo, si se especifica la ruta de acceso $.user.setting.theme, JSON_MODIFY no inserta la clave theme si los objetos $.user o $.user.settings no existen, o bien si la configuración es una matriz o un valor escalar. |
Error: INVALID_PROPERTY |
| NULL | Sí | Se elimina la propiedad existente. | El valor actual se establece en NULL. |
| NULL | No | No sucede nada. El primer argumento se devuelve como resultado. | Error: INVALID_PROPERTY |
En el modo lax, JSON_MODIFY intenta crear un par clave-valor, pero en algunos casos se podría producir un error.
Ejemplos
Ejemplo: operaciones básicas
En el siguiente ejemplo se muestran las operaciones básicas que se pueden realizar con texto JSON.
Consultar
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
Resultados
{
"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"
}
Ejemplo: varias actualizaciones
Con JSON_MODIFY solo se puede actualizar una propiedad. Si tiene que realizar varias actualizaciones, puede usar varias llamadas JSON_MODIFY.
Consultar
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
Resultados
{
"name": "John",
"skills": ["C#", "SQL"]
} {
"name": "Mike",
"skills": ["C#", "SQL", "Azure"],
"surname": "Smith"
}
Ejemplo: cambiar una clave de nombre
En el siguiente ejemplo se muestra cómo cambiar el nombre de una propiedad en texto JSON con la función JSON_MODIFY. En primer lugar, puede tomar el valor de una propiedad existente e insertarlo como un nuevo par clave-valor. Luego, puede eliminar la antigua clave estableciendo el valor de la propiedad anterior en NULL.
Consultar
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
Resultados
{
"price": 49.99
} {
"Price": 49.99
}
Si no convierte el nuevo valor a un tipo numérico, JSON_MODIFY lo considera como texto y lo coloca entre comillas dobles.
Ejemplo: aumentar un valor
En el siguiente ejemplo se muestra cómo aumentar el valor de una propiedad en texto JSON con la función JSON_MODIFY. En primer lugar, puede tomar el valor de la propiedad existente e insertarlo como un nuevo par clave-valor. Luego, puede eliminar la antigua clave estableciendo el valor de la propiedad anterior en NULL.
Consultar
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
Resultados
{
"click_count": 173
} {
"click_count": 174
}
Ejemplo: modificar un objeto JSON
JSON_MODIFY trata el argumento newValue como texto sin formato incluso cuando contiene texto con formato JSON correcto. Como resultado, la salida JSON de la función se inserta entre comillas dobles y todos los caracteres especiales son caracteres de escape, tal y como se muestra en el siguiente ejemplo.
Consultar
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
Resultados
{
"name": "John",
"skills": ["C#", "SQL"]
} {
"name": "John",
"skills": "[\"C#\",\"T-SQL\",\"Azure\"]"
}
Para evitar el escape automático, proporcione un newValue con la función JSON_QUERY. JSON_MODIFY sabe que el valor devuelto por JSON_QUERY tiene un formato JSON correcto, por lo que no escapa del valor.
Consultar
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
Resultados
{
"name": "John",
"skills": ["C#", "SQL"]
} {
"name": "John",
"skills": ["C#", "T-SQL", "Azure"]
}
Ejemplo: actualizar una columna JSON
En el siguiente ejemplo se actualiza el valor de una propiedad en una columna de tabla que contiene JSON.
UPDATE Employee
SET jsonCol=JSON_MODIFY(jsonCol,'$.info.address.town','London')
WHERE EmployeeID=17
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de