Compartir a través de

Expresiones de ruta de acceso JSON (SQL Server)

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

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.

  • Cuando se llama a OPENJSON para crear una vista relacional de los datos JSON.
  • Cuando se llama a JSON_VALUE para extraer un valor de texto JSON.
  • Cuando se llama a JSON_QUERY para extraer un objeto JSON o una matriz.
  • Cuando se llama 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 de acceso en sí.

modo de ruta de acceso

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

Ruta

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 y intervalo de matrices

Nota:

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

La versión preliminar de SQL Server 2025 (17.x) expande la expresión de ruta de acceso ANSI SQL/JSON para admitir un carácter comodín de matriz. 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.

Ruta Descripción
$[*] Todos los elementos
$[0] Primer elemento
$[0 to 2] Tres primeros elementos
$[last] Último elemento
$[last, 0] No válido
$[last, 2, 0, last] No válido
$.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 creditcards la matriz.
$.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.

Ejemplos

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 de acceso Valor
$.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 en SQL Server y Azure SQL Database

Para obtener una introducción visual a la compatibilidad integrada con JSON en SQL Server y Azure SQL Database, consulte el vídeo siguiente:

Contenido relacionado