JSON_CONTAINS (Transact-SQL)

2025-05-19

Si applica a: Anteprima di SQL Server 2025 (17.x)

Cerca un valore SQL in un percorso in un documento JSON.

Annotazioni

La JSON_CONTAINS funzione è attualmente in anteprima e disponibile solo in SQL Server 2025 (17.x) Preview.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )

Argomenti

target_expression

Espressione che restituisce un documento JSON di destinazione da cercare. Il valore può essere un tipo JSON o un valore stringa di caratteri che contiene un documento JSON.

espressione_di_valore_di_ricerca

Espressione che restituisce un valore scalare SQL o un valore di tipo JSON da cercare nel documento SQL/JSON specificato.

percorso

Percorso SQL/JSON che specifica la destinazione di ricerca nel documento JSON. Questo parametro è facoltativo.

È possibile specificare una variabile come valore di path. Il percorso JSON può specificare la modalità lax o strict per l'analisi. Se non si specifica la modalità di analisi, la modalità predefinita è lax. Per altre informazioni, vedere Espressioni di percorso JSON (SQL Server).

Il valore predefinito per path è $. Di conseguenza, se non si specifica un valore per path, JSON_CONTAINS cerca il valore nell'intero documento JSON.

Se il formato di path non è valido, JSON_CONTAINS restituisce un errore.

Valore restituito

Restituisce un valore int di 0, 1o NULL. Un valore di 1 indica che il valore di ricerca specificato è contenuto all'interno del documento JSON di destinazione, o in caso contrario, di 0. La JSON_CONTAINS funzione restituisce NULL se uno degli argomenti è NULLo se il percorso SQL/JSON specificato non viene trovato nel documento JSON.

Osservazioni:

La JSON_CONTAINS funzione segue queste regole per la ricerca se un valore è contenuto in un documento JSON:

Un valore di ricerca scalare è contenuto in un scalare di destinazione se e solo se sono confrontabili e sono uguali. Poiché i tipi json hanno solo il numero JSON o la stringa o il valore true/false, i possibili tipi scalari SQL che possono essere specificati come valore di ricerca sono limitati ai tipi numerici SQL, ai tipi di stringa di caratteri e al tipo di bit .
Il tipo SQL del valore di ricerca scalare viene usato per eseguire il confronto con il valore del tipo json nel percorso specificato. Questo è diverso dal predicato basato su JSON_VALUE, in cui la funzione JSON_VALUE restituisce sempre un valore di tipo stringa.
Un valore di ricerca matrice JSON è contenuto in una matrice di destinazione se e solo se ogni elemento della matrice di ricerca è contenuto in un elemento della matrice di destinazione.
Un valore di ricerca scalare è contenuto in una matrice di destinazione se e solo se il valore di ricerca è contenuto in un elemento della matrice di destinazione.
Un valore di ricerca di oggetti JSON è contenuto in un oggetto di destinazione se e solo se ogni chiave/valore nell'oggetto di ricerca viene trovato nell'oggetto di destinazione.

Limitazioni

L'uso della JSON_CONTAINS funzione presenta le limitazioni seguenti:

Il tipo json non è supportato come valore di ricerca.
L'oggetto JSON o la matrice restituita da JSON_QUERY non è supportato come valore di ricerca.
Il parametro path è attualmente obbligatorio.
Se il percorso SQL/JSON punta a un array, è necessario utilizzare un wildcard nell'espressione di percorso SQL/JSON. L'annullamento automatico dell'incapsulamento degli array è attualmente solo al primo livello.

Il supporto dell'indice JSON include il JSON_CONTAINS predicato e gli operatori seguenti:

Operatori di confronto (=)
IS [NOT] NULL predicato (attualmente non supportato)

Esempi

Un. Cercare un valore intero SQL in un percorso JSON

L'esempio seguente illustra come cercare un valore SQL int in una matrice JSON in un percorso 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;