JSON_CONTAINS (Transact-SQL)

S’applique à : SQL Server 2025 (17.x)

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

Note

La JSON_CONTAINS fonction est actuellement en version avant-première et disponible uniquement dans SQL Server 2025 (17.x).

Conventions de la syntaxe Transact-SQL

Syntax

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ]  [ , search_mode ] )

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.

search_value_expression

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

path

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 les expressions de chemin JSON dans le moteur de base de données SQL.

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 du chemin d’accès n’est pas valide, JSON_CONTAINS retourne une erreur.

search_mode

Indique si le mode de recherche de la valeur doit utiliser une sémantique d’égalité ou de prédicat LIKE. Ce paramètre s’applique uniquement lorsque l’search_value_expression est une valeur de chaîne de caractères. La valeur par défaut de search_mode est 0, ce qui indique la sémantique de prédicat d’égalité. Si la search_mode est 1, elle indique que la sémantique de prédicat LIKE doit être utilisée.

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.

Remarks

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.

Limitations

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 path est actuellement obligatoire.
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ésenveloppement automatique des tableaux ne s’effectue actuellement qu’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)

Examples

A. 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;