JSON_CONTAINS (Transact-SQL)

Se aplica a: SQL Server 2025 (17.x)

Busca un valor SQL en una ruta en un documento JSON.

Note

La JSON_CONTAINS función está actualmente en vista previa y solo disponible en SQL Server 2025 (17.x).

Convenciones de sintaxis de Transact-SQL

Syntax

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

Arguments

target_expression

Expresión que devuelve un documento JSON de destino que se va a buscar. El valor puede ser un tipo json o un valor de cadena de caracteres que contiene un documento JSON.

search_value_expression

Expresión que devuelve un valor escalar de SQL o un valor de tipo json para buscar en el documento SQL/JSON especificado.

path

Ruta de acceso SQL/JSON que especifica el destino de búsqueda en el documento JSON. Este parámetro es opcional.

Puede proporcionar una variable como valor de ruta. La ruta de acceso JSON puede especificar el modo lax o strict para el análisis. Si no se especifica el modo de análisis, el modo lax es el valor predeterminado. Para obtener más información, consulte Expresiones de ruta de acceso JSON en el motor de base de datos SQL.

El valor predeterminado de path es $. Como resultado, si no proporciona un valor para la ruta de acceso, JSON_CONTAINS busca el valor en todo el documento JSON.

Si el formato de la ruta de acceso no es válido, JSON_CONTAINS devuelve un error.

search_mode

Indica si el modo de búsqueda del valor debe usar una semántica de predicado LIKE o igualdad. Este parámetro solo se aplica cuando el search_value_expression es un valor de cadena de caracteres. El valor predeterminado de search_mode es 0, que indica la semántica del predicado de igualdad. Si el search_mode es 1, indica que se debe usar la semántica del predicado LIKE.

Valor devuelto

Devuelve un valor int de 0, 1o NULL. Un valor de 1 indica que el valor de búsqueda especificado estaba incluido en el documento JSON de destino, o 0 en caso contrario. La JSON_CONTAINS función devuelve NULL si alguno de los argumentos es NULLo si la ruta de acceso SQL/JSON especificada no se encuentra en el documento JSON.

Remarks

La JSON_CONTAINS función sigue estas reglas para buscar si un valor está contenido en un documento JSON:

Un valor de búsqueda escalar se incluye en un escalar de destino si y solo si son comparables y son iguales. Dado que los tipos json solo tienen un número JSON o un valor true/false, los posibles tipos escalares de SQL que se pueden especificar como valor de búsqueda se limitan a los tipos numéricos de SQL, los tipos de cadena de caracteres y el tipo de bits .
El tipo SQL del valor de búsqueda escalar se utiliza para comparar con el valor tipo json en la ruta especificada. Esto es diferente del predicado basado en JSON_VALUE, donde JSON_VALUE función siempre devuelve un valor de cadena de caracteres.
Un valor de búsqueda de matriz JSON se incluye en una matriz de destino si y solo si cada elemento de la matriz de búsqueda está contenido en algún elemento de la matriz de destino.
Un valor de búsqueda escalar se incluye en una matriz de destino si y solo si el valor de búsqueda está contenido en algún elemento de la matriz de destino.
Un valor de búsqueda de objetos JSON se encuentra en un objeto de destino si y solo si cada clave/valor del objeto de búsqueda se encuentra en el objeto de destino.

Limitations

El uso de la JSON_CONTAINS función tiene las siguientes limitaciones:

El tipo json no se admite como valor de búsqueda.
El objeto JSON o matriz devuelto de JSON_QUERY no se admite como valor de búsqueda.
El parámetro path es necesario actualmente.
Si la ruta de acceso de SQL/JSON apunta a una matriz, se requiere un comodín en la expresión de ruta de acceso de SQL/JSON. La desencapsulación automática de matrices solo está actualmente en el primer nivel.

La compatibilidad con índices JSON incluye el JSON_CONTAINS predicado y los operadores siguientes:

Operadores de comparación (=)
Predicado IS [NOT] NULL (no admitido actualmente)

Examples

A. Búsqueda de un valor entero de SQL en una ruta JSON

En el ejemplo siguiente se muestra cómo buscar un valor int de tipo SQL en una matriz JSON en un camino 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;