JSON_CONTAINS (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure banco de dados SQL no Microsoft Fabric

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

Convenções de sintaxe Transact-SQL

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.

A JSON_CONTAINS função não é suportada em Fabric Data Warehouse.

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;