Partager via

Expressions de chemin JSON (SQL Server)

S’applique à : SQL Server 2016 (13.x) et versions ultérieures Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (pool SQL serverless uniquement)

Utilisez les expressions de chemins JSON pour référencer les propriétés des objets JSON.

Vous devez fournir une expression de chemin lorsque vous appelez les fonctions suivantes.

  • Lorsque vous appelez OPENJSON pour créer une vue relationnelle des données JSON.
  • Quand vous appelez JSON_VALUE pour extraire une valeur de texte JSON.
  • Quand vous appelez JSON_QUERY pour extraire un tableau ou un objet JSON.
  • Quand vous appelez JSON_MODIFY pour mettre à jour la valeur d’une propriété dans une chaîne JSON.

Parties d’une expression de chemin

Une expression de chemin comporte deux composants.

  1. Mode de chemin facultatif, avec une valeur de lax ou strict.

  2. Le chemin lui-même.

mode PATH

Au début de l’expression de chemin d’accès, déclarez éventuellement le mode chemin en spécifiant le mot clé lax ou strict. La valeur par défaut est lax.

  • En lax mode, la fonction retourne des valeurs vides si l’expression de chemin d’accès contient une erreur. Par exemple, si vous demandez la valeur $.nameet que le texte JSON ne contient pas de name clé, la fonction retourne null, mais ne génère pas d’erreur.

  • En strict mode, la fonction génère une erreur si l’expression de chemin d’accès contient une erreur.

La requête suivante spécifie explicitement le mode lax dans l’expression de chemin.

DECLARE @json AS NVARCHAR (MAX);

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

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

Chemin d’accès

Après la déclaration de mode de chemin facultatif, spécifiez le chemin lui-même.

  • Le signe dollar ($) représente l’élément de contexte.

  • Le chemin de la propriété est un ensemble d’étapes de chemin. Les étapes de chemin peuvent contenir les éléments et les opérateurs suivants.

    • Noms de clés. Par exemple : $.name et $."first name". Si le nom de clé commence par un signe dollar ou contient des caractères spéciaux tels que des espaces ou des opérateurs point (.), placez-le entre guillemets.

    • Éléments du tableau. Par exemple : $.product[3]. Les tableaux sont de base zéro.

    • L’opérateur point (.) indique un membre d’un objet. Par exemple, dans $.people[1].surname, surname est un enfant de people.

    • Les recherches de caractères génériques et de plages de tableau sont également prises en charge si l’entrée est une valeur de type JSON.

Prise en charge des caractères génériques et des plages de tableaux

Remarque

La prise en charge des caractères génériques et des plages de tableaux est actuellement en préversion et disponible uniquement dans SQL Server 2025 (17.x) Preview.

SQL Server 2025 (17.x) Préversion développe l’expression de chemin d’accès ANSI SQL/JSON pour prendre en charge un caractère générique de tableau. Le caractère générique tableau vous permet de spécifier tous les éléments, plages d’éléments, liste d’éléments ou jeton spécial « last » pour indiquer la dernière valeur dans un tableau JSON. Les tableaux SQL/JSON utilisent un index de base zéro. Le chemin SQL/JSON avec des caractères génériques peut être utilisé dans JSON_QUERY, JSON_PATH_EXISTS et JSON_CONTAINS.

Bien que JSON_VALUE la fonction prenne en charge l’expression de chemin d’accès SQL/JSON, la valeur de retour d’une JSON_VALUE fonction est une scalaire SQL et, par conséquent, la fonction retourne NULL toujours pour n’importe quel chemin SQL/JSON qui pointe vers un objet ou un tableau JSON. Les caractères génériques de tableau sont pris en charge uniquement pour les entrées de type json.

La syntaxe suivante montre comment utiliser le caractère générique, la plage et le jeton last spécial :

path[elements ]

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

Le jeton last spécial peut être utilisé à la place de la valeur numérique. Si une plage est spécifiée, la plage doit être spécifiée dans l’ordre croissant.

Exemples d’expressions de chemin d’accès SQL/JSON valides :

Chemin d’accès Descriptif
$[*] Tous les éléments
$[0] Premier élément
$[0 to 2] Trois premiers éléments
$[last] Dernier élément
$[last, 0] non valide
$[last, 2, 0, last] non valide
$.creditcards[0].type Retourne la valeur de la propriété de type du premier élément dans le tableau creditcards.
$.credit_cards[*].type Retourne la valeur de propriété de type de tous les éléments du creditcards tableau
$.credit_cards[0, 2].type Retourne la valeur de la propriété de type du premier et du troisième élément dans le tableau creditcards.
$.credit_cards[1 to 3].type Retourne la valeur de la propriété de type des deuxième, troisième et quatrième éléments dans le tableau creditcards.
$.credit_cards[last].type Retourne la valeur de propriété de type du dernier élément dans le creditcards tableau
$.credit_cards[last, 0].type Retourne la valeur de propriété de type du dernier et du premier élément dans creditcards le tableau

Exemples

Les exemples de cette section font référence au texte JSON suivant.

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

Le tableau suivant présente des exemples d’expressions de chemin.

Expression de chemin Valeur
$.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"]

Comment les fonctions intégrées gèrent-elles les chemins en double ?

Si le texte JSON contient des propriétés dupliquées - par exemple, deux clés portant le même nom au même niveau - les fonctions JSON_VALUE et JSON_QUERY retournent uniquement la première valeur qui correspond au chemin d’accès. Pour analyser un objet JSON qui contient des clés en double et retourner toutes les valeurs, utilisez OPENJSON, comme illustré dans l’exemple suivant.

DECLARE @json AS NVARCHAR (MAX);

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

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

En savoir plus sur JSON dans SQL Server et Azure SQL Database

Pour une présentation visuelle de la prise en charge JSON intégrée dans SQL Server et Azure SQL Database, consultez la vidéo suivante :

Contenu connexe