JSON_CONTAINS (Transact-SQL)

2025-10-28

Van toepassing op: SQL Server 2025 (17.x) Preview

Zoekt naar een SQL-waarde in een pad in een JSON-document.

Note

De JSON_CONTAINS functie is momenteel beschikbaar als preview-versie en is alleen beschikbaar in SQL Server 2025 (17.x) Preview.

Transact-SQL syntaxis-conventies

Syntax

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

Arguments

target_expression

Een expressie die een doel-JSON-document retourneert om te zoeken. De waarde kan een json-type of tekenreekswaarde zijn die een JSON-document bevat.

search_value_expression

Een expressie die een scalaire SQL-waarde of JSON-typewaarde retourneert voor zoekopdrachten in het opgegeven SQL/JSON-document.

path

Een SQL/JSON-pad dat het zoekdoel in het JSON-document aangeeft. Deze parameter is optioneel.

U kunt een variabele opgeven als de waarde van het pad. Het JSON-pad kan de lax- of strikte modus voor parseren opgeven. Als u de parseringsmodus niet opgeeft, is de lax-modus de standaardmodus. Zie JSON-padexpressies in de SQL Database Engine voor meer informatie.

De standaardwaarde voor pad is $. Als u dus geen waarde voor het pad opgeeft, JSON_CONTAINS zoekt u naar de waarde in het hele JSON-document.

Als de indeling van het pad niet geldig is, JSON_CONTAINS wordt een fout geretourneerd.

search_mode

Geeft aan of in de zoekmodus voor de waarde een gelijkheids- of LIKE-predicaatsemantiek moet worden gebruikt. Deze parameter is alleen van toepassing wanneer de search_value_expression een tekenreekswaarde is. De standaardwaarde voor search_mode is 0, wat aangeeft dat de semantiek van het gelijkheidspredicaat is. Als de search_mode 1 is, geeft het aan dat LIKE predicaat semantiek moet worden gebruikt.

Retourwaarde

Retourneert een int-waarde van 0, 1of NULL. Een waarde van 1 geeft aan dat de opgegeven zoekwaarde is opgenomen in het JSON-doeldocument of 0 anderszins. De JSON_CONTAINS functie retourneert NULL of een van de argumenten is NULLof als het opgegeven SQL/JSON-pad niet wordt gevonden in het JSON-document.

Remarks

De JSON_CONTAINS functie volgt deze regels om te zoeken of een waarde is opgenomen in een JSON-document:

Een scalaire zoekwaarde is opgenomen in een doelschaalwaarde als en alleen als ze vergelijkbaar en gelijk zijn. Omdat json-typen slechts een getal, een tekenreeks of de waarde waar/onwaar hebben, zijn de mogelijke scalaire SQL-typen die kunnen worden opgegeven als zoekwaarde beperkt tot de numerieke SQL-typen, tekenreekstypen en het bittype.
Het SQL-type van de scalaire zoekwaarde wordt gebruikt om de vergelijking met de json-typewaarde in het opgegeven pad uit te voeren. Dit verschilt van het predicaat op basis van JSON_VALUE-waarbij de JSON_VALUE functie altijd een tekenreekswaarde retourneert.
Een JSON-matrixzoekwaarde bevindt zich in een doelmatrix als en alleen als elk element in de zoekmatrix zich in een bepaald element van de doelmatrix bevindt.
Een scalaire zoekwaarde bevindt zich in een doelmatrix als en alleen als de zoekwaarde zich in een bepaald element van de doelmatrix bevindt.
Een JSON-objectzoekwaarde bevindt zich in een doelobject als en alleen als elke sleutel/waarde in het zoekobject wordt gevonden in het doelobject.

Limitations

Het gebruik van de JSON_CONTAINS functie heeft de volgende beperkingen:

Het json-type wordt niet ondersteund als zoekwaarde.
Het JSON-object of de array die wordt geretourneerd van JSON_QUERY wordt niet ondersteund als zoekwaarde.
De padparameter is momenteel vereist.
Als het SQL/JSON-pad verwijst naar een matrix, is jokerteken vereist in de SQL/JSON-padexpressie. Automatisch uitpakken van arrays vindt momenteel alleen plaats op het eerste niveau.

Ondersteuning voor JSON-indexen omvat het JSON_CONTAINS predicaat en de volgende operators:

Vergelijkingsoperatoren (=)
IS [NOT] NULL predicaat (momenteel niet ondersteund)

Examples

A. Zoeken naar een SQL-geheel getal in een JSON-pad

In het volgende voorbeeld ziet u hoe u zoekt naar een SQL-int-waarde in een JSON-matrix in een JSON-pad.

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;