Compartir a través de

JSON_QUERY (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 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, consulte 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 expression 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 expression.

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.

Comentarios

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

Contenido relacionado