Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Aplica-se a:
SQL Server 2025 (17.x) Base de Dados SQL do AzureAzure SQL Managed InstanceSQL database in Microsoft Fabric
Procura um valor SQL em um caminho em um documento JSON.
Transact-SQL convenções de sintaxe
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 para pesquisar. 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. Este parâmetro é opcional.
Você pode fornecer uma variável como o valor do caminho. O caminho JSON pode especificar o modo lax ou strict para análise. Se você não especificar o modo de análise, o modo lax 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 para path é $. Como resultado, se você não fornecer um valor para caminho, JSON_CONTAINS procurará 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 igual ou LIKE. Este parâmetro só se aplica quando o search_value_expression é um valor de cadeia de caracteres. O valor padrão para search_mode é 0, que indica semântica de predicados de igualdade. Se o search_mode for 1, isso indica que a semântica de predicados LIKE deve ser usada.
Valor de retorno
Devolve 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 JSON_CONTAINS função retornará NULL se qualquer um 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 iguais. Como os tipos do JSON têm apenas número JSON ou uma cadeia de caracteres ou valor verdadeiro/falso, os possíveis tipos escalares SQL que podem ser especificados como valor de pesquisa são limitados aos tipos numéricos SQL, tipos de cadeia de caracteres e ao tipo de bit.
O tipo SQL do valor de pesquisa escalar é usado para executar a comparação com o valor do tipo json no caminho especificado. Isso é diferente de um predicado baseado em
JSON_VALUE, onde a funçãoJSON_VALUEsempre retorna um valor de string.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 de 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
O uso da JSON_CONTAINS função tem as seguintes limitações:
- O tipo json não é suportado como valor de pesquisa.
- O objeto JSON ou matriz retornada de
JSON_QUERYnão é suportado como valor de pesquisa. - O parâmetro path é atualmente necessário.
- Se o caminho SQL/JSON apontar para uma matriz, o curinga será necessário na expressão de caminho SQL/JSON. Atualmente, o desembrulhamento automático de matrizes está apenas no primeiro nível.
O suporte ao índice JSON inclui o predicado JSON_CONTAINS e os seguintes operadores:
- Operadores de comparação (
=) -
IS [NOT] NULLpredicado (não suportado atualmente)
Examples
A. Pesquisar um valor inteiro SQL em um caminho JSON
O exemplo a seguir mostra como procurar um valor int SQL em uma matriz JSON em 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;
Aqui está o conjunto de resultados.
is_value_found
--------
1
B. Pesquisar um valor de cadeia de caracteres SQL em um caminho JSON
O exemplo a seguir mostra como procurar um valor de cadeia de caracteres SQL em uma matriz JSON em 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, 'dd', '$.c.ce[*]') AS is_value_found;
Aqui está o conjunto de resultados.
is_value_found
--------
1
C. Pesquisar um valor de bit SQL em uma matriz JSON em um caminho JSON
O exemplo a seguir mostra como procurar por um valor de bit sql num vetor JSON num 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, CAST (0 AS BIT), '$.d[*]') AS is_value_found;
Aqui está o conjunto de resultados.
is_value_found
--------
1
D. Pesquisar um valor inteiro SQL contido em uma matriz JSON aninhada
O exemplo a seguir mostra como procurar um valor int SQL contido em uma matriz JSON aninhada em 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, 89, '$.d[*].df[*]') AS is_value_found;
Aqui está o conjunto de resultados.
is_value_found
--------
1
E. Pesquisar um valor inteiro SQL contido em um objeto JSON em uma matriz JSON
O exemplo a seguir mostra como procurar um valor int SQL contido em um objeto JSON em uma matriz JSON em um caminho JSON.
DECLARE @j AS JSON = '[{"a": 1}, {"b": 2}, {"c": 3}, {"a": 56}]';
SELECT json_contains(@j, 56, '$[*].a') AS is_value_found;
Aqui está o conjunto de resultados.
is_value_found
--------
1
F. Pesquisar um valor de cadeia de caracteres SQL em um caminho JSON usando um padrão curinga
O exemplo a seguir mostra como procurar um valor de cadeia de caracteres SQL usando um padrão em uma matriz JSON em 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, 'dd', '$.c.ce[*]') AS is_value_found;
Aqui está o conjunto de resultados.
is_value_found
--------
1