JSON_CONTAINS (Transact-SQL)

Se aplica a: VERSIÓN PRELIMINAR de SQL Server 2025 (17.x)

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

Convenciones de sintaxis de Transact-SQL

Sintaxis

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )

Argumentos

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.

ruta

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 más información, vea Expresiones de ruta de acceso JSON (SQL Server).

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 path no es válido, JSON_CONTAINS devuelve un error.

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.

Observaciones

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.

Limitaciones

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 (=)
• IS [NOT] NULL predicado (no admitido actualmente)

Ejemplos

Un. Búsqueda de un valor entero de SQL en una ruta de acceso 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;

Este es el conjunto de resultados.

is_value_found
--------
1

B. Buscar un valor de cadena SQL en un trayecto JSON

Este ejemplo muestra cómo buscar un valor de cadena SQL en un array JSON dentro de una ruta 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, 'dd', '$.c.ce[*]') AS is_value_found;

Este es el conjunto de resultados.

is_value_found
--------
1

C. Búsqueda de un valor de bit SQL en un array JSON en una ruta JSON

En el ejemplo siguiente se muestra cómo buscar un valor de bit sql en una matriz JSON en una ruta 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, CAST (0 AS BIT), '$.d[*]') AS is_value_found;

Este es el conjunto de resultados.

is_value_found
--------
1

D. Búsqueda de un valor entero de SQL incluido en una matriz JSON anidada

En el ejemplo siguiente se muestra cómo buscar un valor int de SQL contenido en una matriz JSON anidada en una ruta 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, 89, '$.d[*].df[*]') AS is_value_found;

Este es el conjunto de resultados.

is_value_found
--------
1

E. Búsqueda de un valor entero de SQL incluido en un objeto JSON en una matriz JSON

En el siguiente ejemplo se muestra cómo buscar un valor de SQL int contenido dentro de un objeto JSON en una matriz JSON en un camino JSON.

DECLARE @j AS JSON = '[{"a": 1}, {"b": 2}, {"c": 3}, {"a": 56}]';

SELECT json_contains(@j, 56, '$[*].a') AS is_value_found;

Este es el conjunto de resultados.

is_value_found
--------
1

Contenido relacionado

• Expresiones de ruta de acceso JSON (SQL Server)
• Datos JSON en SQL Server