JSON_CONTAINS (Transact-SQL)

2025-05-19

S’applique à : Préversion de SQL Server 2025 (17.x)

Recherche une valeur SQL dans un chemin dans un document JSON.

Remarque

La JSON_CONTAINS fonction est actuellement en préversion et disponible uniquement dans SQL Server 2025 (17.x) Preview.

Conventions de la syntaxe Transact-SQL

Syntaxe

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )

Les arguments

target_expression

Expression qui retourne un document JSON cible à rechercher. La valeur peut être un type json ou une valeur de chaîne de caractères qui contient un document JSON.

expression_de_valeur_de_recherche

Expression qui retourne une valeur scalaire SQL ou une valeur de type json à rechercher dans le document SQL/JSON spécifié.

chemin d'accès

Chemin d’accès SQL/JSON qui spécifie la cible de recherche dans le document JSON. Ce paramètre est facultatif.

Vous pouvez fournir une variable comme valeur de chemin d’accès. Le chemin JSON peut spécifier le mode lax ou strict pour l’analyse. Si vous ne spécifiez pas le mode d’analyse, le mode lax est utilisé par défaut. Pour plus d’informations, consultez Expressions de chemin JSON (SQL Server).

La valeur par défaut du chemin d’accès est $. Par conséquent, si vous ne fournissez pas de valeur pour le chemin d’accès, JSON_CONTAINS recherche la valeur dans l’ensemble du document JSON.

Si le format de chemin d'accès n’est pas valide, JSON_CONTAINS retourne une erreur.

Valeur retournée

Retourne une valeur int de 0, 1ou NULL. Une valeur indiquant 1 que la valeur de recherche spécifiée était contenue dans le document JSON cible ou 0 dans le cas contraire. La JSON_CONTAINS fonction retourne NULL si l’un des arguments est NULL, ou si le chemin SQL/JSON spécifié n’est pas trouvé dans le document JSON.

Remarques

La JSON_CONTAINS fonction suit ces règles pour rechercher si une valeur est contenue dans un document JSON :

Une valeur de recherche scalaire est contenue dans un scalaire cible si et seulement s’ils sont comparables et sont égaux. Étant donné que les types JSON ont uniquement un nombre JSON ou une valeur true/false, les types scalaires SQL possibles qui peuvent être spécifiés en tant que valeur de recherche sont limités aux types numériques SQL, aux types de chaîne de caractères et au type de bits .
Le type SQL de la valeur de recherche scalaire est utilisé pour effectuer la comparaison avec la valeur de type json dans le chemin d’accès spécifié. Cela diffère du prédicat JSON_VALUE dans lequel la fonction JSON_VALUE retourne toujours une valeur de chaîne de caractères.
Une valeur de recherche de tableau JSON est contenue dans un tableau cible si et seulement si chaque élément du tableau de recherche est contenu dans un élément du tableau cible.
Une valeur de recherche scalaire est contenue dans un tableau cible si et uniquement si la valeur de recherche est contenue dans un élément du tableau cible.
Une valeur de recherche d’objet JSON est contenue dans un objet cible si et seulement si chaque clé/valeur de l’objet de recherche se trouve dans l’objet cible.

Limites

L’utilisation de la JSON_CONTAINS fonction présente les limitations suivantes :

Le type json n’est pas pris en charge comme valeur de recherche.
L’objet JSON ou le tableau retourné par JSON_QUERY n’est pas pris en charge comme valeur de recherche.
Le paramètre de chemin d’accès est actuellement requis.
Si le chemin SQL/JSON pointe vers un tableau, un caractère générique doit être utilisé dans l'expression du chemin SQL/JSON. Le déréférencement automatique des tableaux s’effectue actuellement uniquement au premier niveau.

La prise en charge des index JSON inclut le JSON_CONTAINS prédicat et les opérateurs suivants :

Opérateurs de comparaison (=)
IS [NOT] NULL prédicat (actuellement non pris en charge)

Exemples

Un. Rechercher une valeur entière SQL dans un chemin JSON

L’exemple suivant montre comment rechercher une valeur d’int SQL dans un tableau JSON dans un chemin JSON.

DECLARE @j AS JSON = '{"a": 1, "b": 2, "c": {"d": 4, "ce":["dd"]}, "d": [1, 3, {"df": [89]}, false], "e":null, "f":true}';

SELECT json_contains(@j, 1, '$.a') AS is_value_found;