Compartir a través de

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

La JSON_VALUE sintaxis extrae 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

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Arguments

expression

Expresión. Suele ser el nombre de una variable o una columna con 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

Ruta de acceso JSON 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

Devuelve el valor especificado en el tipo SQL. Solo se admite si la entrada es un tipo JSON. Los tipos sql 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

Si RETURNING no se incluye:

  • Devuelve un solo valor de texto de tipo nvarchar (4000). La intercalación del valor devuelto es la misma que 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 tiene que devolver valores escalares mayores de 4000 caracteres, use OPENJSON en lugar de JSON_VALUE. Para obtener más información, consulta OPENJSON.

Si RETURNING se incluye:

Devuelve el valor especificado en el tipo SQL. Los tipos sql 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 igual si el documento JSON se almacena en varchar, nvarchar o 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 de hecho 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

  • Last updated on