JSON_VALUE (Transact-SQL)

Se aplica a: SQL Server 2016 (13.x) y versiones posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

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, vea JSON_QUERY (Transact-SQL). 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

Sintaxis

JSON_VALUE ( expression , path )  

Argumentos

expression
Expresión. Suele ser el nombre de una variable o una columna con texto JSON.

Si JSON_VALUE detecta JSON que no es válido en expression antes de encontrar el valor identificado por path, la función devuelve un error. Si JSON_VALUE no encuentra el valor identificado por path, examina todo el texto y devuelve un error si detecta un JSON que no sea válido en cualquier lugar de expression.

path
Ruta de acceso JSON que especifica la propiedad que se va a extraer. 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.

Si el formato de path no es válido, JSON_VALUE devuelve un error.

Valor devuelto

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 que 4000 caracteres, use OPENJSON en lugar de JSON_VALUE. Para obtener más información, consulte OPENJSON (Transact-SQL).

Observaciones

Modo lax y modo strict

Observe el siguiente texto JSON:

DECLARE @jsonInfo NVARCHAR(MAX)

SET @jsonInfo=N'{  
     "info":{    
       "type":1,  
       "address":{    
         "town":"Bristol",  
         "county":"Avon",  
         "country":"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 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).

Path	Valor devuelto en el modo lax	Valor devuelto en el modo strict	Más información
$	NULL	Error	No es un valor escalar. Use JSON_QUERY en su lugar.
$.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. Use JSON_QUERY en su lugar.
$.info.tags	NULL	Error	No es un valor escalar. Use JSON_QUERY en su lugar.
$.info.type[0]	NULL	Error	No es una matriz.
$.info.none	NULL	Error	La propiedad no existe.

Ejemplos

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.

Nota

(En este ejemplo se da por supuesto que una tabla denominada Person.Person contiene una columna de texto JSON jsonInfo y que esta columna tiene la estructura que se ha mostrado anteriormente en el análisis del modo lax y el modo strict. En la base de datos de ejemplo de AdventureWorks, la tabla Person realmente no contiene una columna jsonInfo).

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 NVARCHAR(MAX)
DECLARE @town 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')
 )

Vea también

Expresiones de ruta de acceso JSON (SQL Server)
Datos JSON (SQL Server)