JSON_CONTAINS (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x)

Pesquisa um valor SQL em um caminho em um documento JSON.

Note

A JSON_CONTAINS função está atualmente em pré-visualização e disponível apenas no SQL Server 2025 (17.x).

Syntax

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

Arguments

target_expression

Uma expressão que retorna um documento JSON de destino a ser pesquisado. O valor pode ser um tipo json ou um valor de cadeia de caracteres que contém um documento JSON.

search_value_expression

Uma expressão que retorna um valor escalar SQL ou um valor de tipo json para pesquisar no documento SQL/JSON especificado.

path

Um caminho SQL/JSON que especifica o destino de pesquisa no documento JSON. Esse parâmetro é opcional.

Você pode fornecer uma variável como o valor do caminho. O demarcador JSON pode especificar o modo incerto ou estrito para análise. Se você não especificar o modo de análise, o modo incerto será o padrão. Para obter mais informações, consulte Expressões de caminho JSON no Mecanismo de Banco de Dados SQL.

O valor padrão do caminho é $. Como resultado, se você não fornecer um valor para o caminho, JSON_CONTAINS pesquisará o valor em todo o documento JSON.

Se o formato do caminho não for válido, JSON_CONTAINS retornará um erro.

search_mode

Indica se o modo de pesquisa para o valor deve usar uma semântica de predicado LIKE ou igualdade. Esse parâmetro só se aplica quando o search_value_expression é um valor de cadeia de caracteres. O valor padrão para search_mode é 0, o que indica semântica de predicado de igualdade. Se o search_mode for 1, indicará que a semântica do predicado LIKE deve ser usada.

Valor de retorno

Retorna um valor int de 0, 1ou NULL. Um valor de 1 indica que o valor de pesquisa especificado estava contido no documento JSON de destino, ou 0 caso contrário. A função JSON_CONTAINS retorna NULL se algum dos argumentos for NULL, ou se o caminho SQL/JSON especificado não for encontrado no documento JSON.

Remarks

A JSON_CONTAINS função segue estas regras para pesquisar se um valor está contido em um documento JSON:

Um valor de pesquisa escalar está contido em um escalar de destino se e somente se eles forem comparáveis e são iguais. Como os tipos json têm apenas número, string ou valor verdadeiro/falso JSON, os possíveis tipos escalares SQL que podem ser especificados como valor de pesquisa são limitados aos tipos numéricos do SQL, tipos de cadeia de caracteres e o tipo bit.
O tipo SQL do valor de pesquisa escalar é usado para executar a comparação com o valor do tipo json no caminho especificado. Isto é diferente de um predicado baseado em JSON_VALUE, onde a função JSON_VALUE sempre retorna um valor do tipo cadeia de caracteres.
Um valor de pesquisa de matriz JSON está contido em uma matriz de destino se e somente se cada elemento na matriz de pesquisa estiver contido em algum elemento da matriz de destino.
Um valor de pesquisa escalar está contido em uma matriz de destino se e somente se o valor da pesquisa estiver contido em algum elemento da matriz de destino.
Um valor de pesquisa de objeto JSON está contido em um objeto de destino se e somente se cada chave/valor no objeto de pesquisa for encontrado no objeto de destino.

Limitations

Usar a JSON_CONTAINS função tem as seguintes limitações:

Não há suporte para o tipo json como valor de pesquisa.
Não há suporte para o objeto JSON ou a matriz retornada de JSON_QUERY como valor de pesquisa.
O parâmetro de caminho é necessário no momento.
Se o caminho SQL/JSON apontar para uma matriz, o curinga será necessário na expressão de caminho SQL/JSON. Atualmente, o desdobramento automático da matriz está apenas no primeiro nível.

O suporte ao índice JSON inclui o JSON_CONTAINS predicado e os seguintes operadores:

Operadores de comparação (=)
IS [NOT] NULL predicado (sem suporte no momento)

Examples

A. Pesquisar um valor inteiro do SQL em um caminho JSON

O exemplo a seguir mostra como pesquisar um valor int SQL em uma matriz JSON dentro de um caminho 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;