Compartir a través de

JSON_VALUE (Transact-SQL)

  • Artículo

Se aplica a: SQL Server 2016 (13.x) y versiones posteriores de Azure SQL Database Azure SQL Instancia administrada Azure 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 JSON que no es válido en algún 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 de 4000 caracteres, use OPENJSON en lugar de JSON_VALUE. Para obtener más información, consulte OPENJSON (Transact-SQL).

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

Comentarios

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.

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.

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')
 )

Contenido relacionado