JSON_VALUE (Transact-SQL)

Se aplica a: SQL Server 2016 (13.x) y versiones posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics sql analytics endpointin Microsoft FabricWarehouse in Microsoft FabricSQL Database in Microsoft Fabric SQL Database in Microsoft Fabric

Use la JSON_VALUE sintaxis para extraer un valor escalar de una cadena JSON.

Para extraer un objeto o una matriz de una cadena JSON en lugar de un valor escalar, consulte JSON_QUERY. Para información sobre las diferencias entre JSON_VALUE y JSON_QUERY, vea Comparación de JSON_VALUE y JSON_QUERY.

Convenciones de sintaxis de Transact-SQL

Syntax

Sintaxis para SQL Server 2025 (17.x) y versiones posteriores.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

En SQL Server 2022 (16.x) y versiones anteriores, NO se incluye RETURNING.

Arguments

expression

Expresión que suele ser el nombre de una variable o una columna que contiene texto JSON.

Si JSON_VALUE encuentra JSON que no es válido en la expresión antes de encontrar el valor identificado por ruta de acceso, la función devuelve un error. Si JSON_VALUE no encuentra el valor identificado por ruta de acceso, examina todo el texto y devuelve un error si encuentra JSON que no es válido en ninguna parte de la expresión.

path

A JSON ruta de acceso que especifica la propiedad que se va a extraer. Para obtener más información, consulte Expresiones de ruta de acceso JSON en el motor de base de datos sql.

En SQL Server 2017 (14.x) y en Azure SQL Database, puede proporcionar una variable como valor de ruta de acceso.

Si el formato de la ruta de acceso no es válido, JSON_VALUE devuelve un error.

data_type

Tipo de datos que desea usar para el valor devuelto. Este tipo solo se admite si la entrada es un tipo JSON. Los tipos de datos admitidos son : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 y datetimeoffset.

Valor devuelto

Aplica a: SQL Server 2025 (17.x) y versiones posteriores.

Si no incluye RETURNING:

• Devuelve un valor de texto único del tipo nvarchar(4000). La intercalación del valor devuelto coincide con la intercalación de la expresión de entrada.

• Si el valor es mayor que 4000 caracteres:

  • En el modo lax, JSON_VALUE devuelve NULL.
  • En el modo strict, JSON_VALUE devuelve un error.

  Si necesita devolver valores escalares superiores a 4000 caracteres, use OPENJSON en lugar de JSON_VALUE. Para obtener más información, consulte OPENJSON.

Si incluye RETURNING:

Devuelve el valor especificado en data_type. Los tipos de datos admitidos son : tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 y datetimeoffset.

Las funciones JSON funcionan de la misma manera si el documento JSON se almacena en varchar, nvarchar o en el tipo de datos json nativo.

Remarks

Modo lax y modo strict

Observe el siguiente texto JSON:

DECLARE @jsonInfo AS NVARCHAR (MAX);

SET @jsonInfo = N'{
     "info":{
       "type":1,
       "address":{
         "town":"Bristol",
         "county":"Avon",
         "country/region":"England"
       },
       "tags":["Sport", "Water polo"]
    },
    "type":"Basic"
 }';

En la tabla siguiente se compara el comportamiento de JSON_VALUE en modo lax y modo strict. Para obtener más información sobre la especificación del modo de ruta de acceso opcional (lax o strict), consulte Expresiones de ruta de acceso JSON en el motor de base de datos SQL.

Path	Valor devuelto en el modo lax	Valor devuelto en el modo strict	Más información
$	NULL	Error	No es un valor escalar. En su lugar, use JSON_QUERY.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	No es un valor escalar. En su lugar, use JSON_QUERY.
$.info.tags	NULL	Error	No es un valor escalar. En su lugar, use JSON_QUERY.
$.info.type[0]	NULL	Error	No es una matriz.
$.info.none	NULL	Error	La propiedad no existe.

Examples

Ejemplo 1

En el ejemplo siguiente se usan los valores de las propiedades JSON town y state en los resultados de la consulta. Puesto que JSON_VALUE conserva la intercalación del origen, el criterio de ordenación de los resultados depende de la intercalación de la columna jsonInfo.

Note

En este ejemplo se supone que una tabla denominada Person.Person contiene una jsonInfo columna de texto JSON y que esta columna tiene la estructura mostrada anteriormente en la explicación del modo lax y el modo strict. En la AdventureWorks base de datos de ejemplo, la Person tabla no contiene una jsonInfo columna.

SELECT FirstName,
       LastName,
       JSON_VALUE(jsonInfo, '$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo, '$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo, '$.info.address.town');

Ejemplo 2

En el ejemplo siguiente se extrae el valor de la propiedad JSON town en una variable local.

DECLARE @jsonInfo AS NVARCHAR (MAX);
DECLARE @town AS NVARCHAR (32);

SET @jsonInfo = N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[0].town'); -- Paris
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[1].town'); -- London

Ejemplo 3

En el ejemplo siguiente se crean columnas calculadas en función de los valores de propiedades JSON.

CREATE TABLE dbo.Store
(
    StoreID INT IDENTITY (1, 1) NOT NULL,
    Address VARCHAR (500),
    jsonContent NVARCHAR (4000),
    Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
    Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
);

Ejemplo 4

En el ejemplo siguiente se extrae un valor de la matriz JSON mediante JSON_VALUE y se devuelve el valor como un valor de tipo de fecha.

DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';

SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;

date_value
--------
2025-01-01

Contenido relacionado

• Expresiones de ruta de acceso JSON en el motor de base de datos de SQL
• Datos JSON en SQL Server