Compartir a través de

Expresiones de ruta JSON en el motor de bases de datos SQL

Aplica a: SQL Server 2016 (13.x) y versiones posteriores, Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (solo SQL pool sin servidor)base de datos SQL en Microsoft Fabric

Use expresiones de rutas de acceso JSON para hacer referencia a las propiedades de los objetos JSON.

Al llamar a las siguientes funciones, hay que proporcionar una expresión de ruta de acceso.

  • Al llamar a OPENJSON para crear una vista relacional de datos JSON.
  • Al llamar a JSON_VALUE para extraer un valor del texto JSON.
  • Cuando llamas a JSON_QUERY para extraer un objeto JSON o una matriz.
  • Cuando llamas a JSON_MODIFY para actualizar el valor de una propiedad en una cadena JSON,

Partes de una expresión de ruta de acceso

Una expresión de ruta de acceso tiene dos componentes.

  1. Modo opcional de ruta, con un valor de lax o strict.

  2. La ruta en sí misma.

Modo de ruta

Al principio de la expresión de ruta de acceso, opcionalmente declare el modo de ruta de acceso especificando la palabra clave lax o strict. El valor predeterminado es lax.

  • En el modo lax, la función devuelve valores vacíos si la expresión de ruta de acceso contiene un error. Por ejemplo, si solicita el valor $.namey el texto JSON no contiene una name clave, la función devuelve null, pero no genera un error.

  • En strict modo, la función genera un error si la expresión de ruta contiene un error.

La consulta siguiente especifica explícitamente el modo lax en la expresión de ruta de acceso.

DECLARE @json AS NVARCHAR (MAX);

SET @json = N'{ ... }';

SELECT *
FROM OPENJSON (@json, N'lax $.info');

Path

Después de declarar (opcionalmente) el modo de ruta de acceso, se especifica la ruta de acceso.

  • El signo de dólar ($) representa el elemento de contexto.

  • La ruta de acceso de propiedad es un conjunto de pasos de ruta de acceso. Los pasos de ruta de acceso pueden contener los siguientes elementos y operadores.

    • Nombres de clave. Por ejemplo, $.name y $."first name". Si el nombre de clave comienza por un signo de dólar o contiene caracteres especiales, como espacios u operadores de punto (.), insértelo entre comillas.

    • Elementos de matriz. Por ejemplo, $.product[3]. Las matrices tienen una base cero.

    • El operador de punto (.) indica un miembro de un objeto. Por ejemplo, en $.people[1].surname, surname es un elemento secundario de people.

    • También se admiten las búsquedas de caracteres comodín y intervalo de matriz si la entrada es un valor de tipo JSON.

Compatibilidad con caracteres comodín e intervalo de matrices

Note

La compatibilidad con caracteres comodín y intervalo de matrices está actualmente en versión preliminar y solo está disponible en SQL Server 2025 (17.x).

SQL Server 2025 (17.x) amplía la expresión de ruta de acceso ANSI SQL/JSON para admitir un carácter comodín para matrices. El carácter comodín Array permite especificar todos los elementos, el intervalo de elementos, la lista de elementos o el token especial "last" para indicar el último valor de una matriz JSON. Las matrices SQL/JSON usan el índice de base cero. La ruta de acceso SQL/JSON con caracteres comodín se puede usar en JSON_QUERY, JSON_PATH_EXISTS y JSON_CONTAINS.

Aunque JSON_VALUE la función admite la expresión de ruta de acceso SQL/JSON, el valor devuelto de una JSON_VALUE función es un escalar de SQL y, por tanto, la función siempre devuelve NULL para cualquier ruta de acceso SQL/JSON que apunte a un objeto o matriz JSON. Los caracteres comodín de matriz solo se admiten si la entrada es un tipo json .

La sintaxis siguiente muestra cómo se puede usar el carácter comodín, el intervalo y el token last especial:

path[elements ]

elements ::= {
*
| number
| number to number
| last
| {number...[, number] }
}

El token last especial se puede usar en lugar del valor numérico. Si se especifica un intervalo, el intervalo debe especificarse en orden creciente.

Ejemplos de algunas expresiones válidas de camino SQL/JSON.

Path Description
$[*] Todos los elementos
$[0] Primer elemento
$[0 to 2] Tres primeros elementos
$[last] Último elemento
$[last, 0] Invalid
$[last, 2, 0, last] Invalid
$.creditcards[0].type Devuelve el valor de la propiedad type del primer elemento en la matriz creditcards.
$.credit_cards[*].type Devuelve el valor de la propiedad type de todos los elementos en la matriz creditcards.
$.credit_cards[0, 2].type Devuelve el valor de la propiedad type del primer y tercer elemento en la matriz creditcards.
$.credit_cards[1 to 3].type Devuelve el valor de la propiedad type del segundo al cuarto elemento de la matriz creditcards
$.credit_cards[last].type Devuelve el valor de la propiedad type del último elemento de la matriz creditcards.
$.credit_cards[last, 0].type Devuelve el valor de la propiedad type del último y del primer elemento en la matriz creditcards.

Examples

Los ejemplos de esta sección hacen referencia al siguiente texto JSON.

{
    "people": [{
        "name": "John",
        "surname": "Doe"
    }, {
        "name": "Jane",
        "surname": null,
        "active": true
    }]
}

En la siguiente tabla se muestran algunos ejemplos de expresiones de ruta de acceso.

Expresión de ruta Value
$.people[0].name John
$.people[1] { "name": "Jane", "surname": null, "active": true }
$.people[1].surname NULL
$ { "people": [ { "name": "John", "surname": "Doe" },{ "name": "Jane", "surname": null, "active": true } ] }
$.people[last].name ["Jane"]
$.people[0 to 1].name ["John","Jane"]
$.people[0, 1].name ["John","Jane"]

Control de las rutas de acceso duplicadas por las funciones integradas

Si el texto JSON contiene propiedades duplicadas (por ejemplo, dos claves con el mismo nombre en el mismo nivel), las JSON_VALUE funciones y JSON_QUERY devuelven solo el primer valor que coincide con la ruta de acceso. Para analizar un objeto JSON que contiene claves duplicadas y devolver todos los valores, use OPENJSON, como se muestra en el ejemplo siguiente.

DECLARE @json AS NVARCHAR (MAX);

SET @json = N'{"person":{"info":{"name":"John", "name":"Jack"}}}';

SELECT value
FROM OPENJSON (@json, '$.person.info');

Más información sobre JSON

Para obtener una introducción visual a la compatibilidad integrada con JSON, consulte el vídeo siguiente:

Contenido relacionado

  • Last updated on