JSON_QUERY (Transact-SQL)

Artículo
05/30/2023

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

Extrae un objeto o una matriz desde una cadena JSON.

Para extraer un valor escalar de una cadena JSON en lugar de un objeto o una matriz, vea JSON_VALUE (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_QUERY ( expression [ , path ] )

Argumentos

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

Si JSON_QUERY detecta JSON que no es válido en expresión antes de encontrar el valor identificado por path, la función devuelve un error. Si JSON_QUERY 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 expresión.

path
Ruta de acceso JSON que especifica el objeto o la matriz que se va a extraer.

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

La ruta de acceso JSON puede especificar el modo lax o strict para el análisis. Si no se especifica el modo de análisis, el modo lax es el valor predeterminado. Para más información, vea Expresiones de ruta de acceso JSON (SQL Server).

El valor predeterminado para path es "$". Como resultado, si no se proporciona un valor para path, JSON_QUERY devuelve la expresión de entrada.

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

Valor devuelto

Devuelve un fragmento de JSON de tipo nvarchar(max). La intercalación del valor devuelto es la misma que la intercalación de la expresión de entrada.

Si el valor no es un objeto o una matriz:

En el modo lax, JSON_QUERY devuelve NULL.
En el modo strict, JSON_QUERY devuelve un error.

Observaciones

Modo lax y modo strict

Observe el siguiente texto JSON:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

En la tabla siguiente se compara el comportamiento de JSON_QUERY 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
$	Devuelve todo el texto JSON.	Devuelve todo el texto JSON.	N/a
$.info.type	NULL	Error	No es un objeto o una matriz. Use JSON_VALUE en su lugar.
$.info.address.town	NULL	Error	No es un objeto o una matriz. Use JSON_VALUE en su lugar.
$.info."address"	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N/a
$.info.tags	N"[ "Sport", "Water polo"]"	N"[ "Sport", "Water polo"]"	N/a
$.info.type[0]	NULL	Error	No es una matriz.
$.info.none	NULL	Error	La propiedad no existe.

Uso de JSON_QUERY con FOR JSON

JSON_QUERY devuelve un fragmento de JSON válido. Como resultado, FOR JSON no incluye entre caracteres de escape los caracteres especiales del valor devuelto de JSON_QUERY.

Si se van a devolver resultados con FOR JSON y se van a incluir datos que ya están en formato JSON (en una columna o como resultado de una expresión), encapsule los datos JSON con JSON_QUERY sin el parámetro path.

Ejemplos

Ejemplo 1

En el ejemplo siguiente se muestra cómo devolver un fragmento de JSON de una columna CustomFields en los resultados de la consulta.

SELECT PersonID,FullName,
  JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People

Ejemplo 2

En el ejemplo siguiente se muestra cómo incluir fragmentos de JSON en la salida de la cláusula FOR JSON.

SELECT StockItemID, StockItemName,
         JSON_QUERY(Tags) as Tags,
         JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH