Freigeben über

JSON_CONTAINS (Transact-SQL)

Gilt für: SQL Server 2025 (17.x) Vorschau

Sucht nach einem SQL-Wert in einem Pfad in einem JSON-Dokument.

Hinweis

Die JSON_CONTAINS Funktion befindet sich derzeit in der Vorschau und ist nur in SQL Server 2025 (17.x) Vorschau verfügbar.

Transact-SQL-Syntaxkonventionen

Syntax

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )

Argumente

target_expression

Ein Ausdruck, der ein JSON-Zieldokument zur Suche zurückgibt. Der Wert kann ein JSON-Typ - oder Zeichenzeichenfolgenwert sein, der ein JSON-Dokument enthält.

Suchwert-Ausdruck

Ein Ausdruck, der einen SQL-Skalarwert oder json-Typwert zurückgibt, um im angegebenen SQL/JSON-Dokument zu suchen.

Pfad

Ein SQL/JSON-Pfad, der das Suchziel im JSON-Dokument angibt. Dieser Parameter ist optional.

Sie können eine Variable als Pfadwert angeben. Der JSON-Pfad kann den Lax- oder Strict-Modus für die Analyse angeben. Wenn Sie den Analysemodus nicht angeben, ist der Lax-Modus die Standardeinstellung. Weitere Informationen finden Sie unter JSON-Pfadausdrücke (SQL Server).

Der Standardwert für pfad ist $. Wenn Sie daher keinen Wert für den Pfad angeben, JSON_CONTAINS wird nach dem Wert im gesamten JSON-Dokument gesucht.

gibt einen Fehler zurück, wenn das Format von JSON_CONTAINS ungültig ist.

Rückgabewert

Gibt einen Int-Wert von 0, , 1oder NULL. Ein Wert von 1 gibt an, dass der angegebene Suchwert im JSON-Zieldokument enthalten war, oder andernfalls 0. Die JSON_CONTAINS Funktion gibt zurück NULL , wenn eines der Argumente lautet NULLoder der angegebene SQL/JSON-Pfad im JSON-Dokument nicht gefunden wird.

Bemerkungen

Die JSON_CONTAINS Funktion folgt den folgenden Regeln zum Suchen, wenn ein Wert in einem JSON-Dokument enthalten ist:

  • Ein skalarer Suchwert ist in einem Zielskalar enthalten, wenn und nur wenn sie vergleichbar und gleich sind. Da json-Typen nur JSON-Zahl oder -Zeichenfolge oder wahr/falsch-Wert aufweisen, sind die möglichen SQL-Skalartypen, die als Suchwert angegeben werden können, auf die numerischen SQL-Typen, Zeichenzeichenfolgentypen und den Bittyp beschränkt.

  • Der SQL-Typ des skalaren Suchwerts wird verwendet, um den Vergleich mit dem JSON-Typwert im angegebenen Pfad durchzuführen. Dies unterscheidet sich von JSON_VALUE-basierten Prädikaten, bei dem die JSON_VALUE Funktion immer einen Zeichenfolgenwert zurückgibt.

  • Ein JSON-Arraysuchwert ist in einem Zielarray enthalten, wenn und nur, wenn jedes Element im Sucharray in einem Element des Zielarrays enthalten ist.

  • Ein skalarer Suchwert ist in einem Zielarray enthalten, wenn und nur, wenn der Suchwert in einem Element des Zielarrays enthalten ist.

  • Ein JSON-Objektsuchwert ist in einem Zielobjekt enthalten, wenn und nur, wenn jeder Schlüssel/Wert im Suchobjekt im Zielobjekt gefunden wird.

Einschränkungen

Die Verwendung der JSON_CONTAINS Funktion hat die folgenden Einschränkungen:

  • Der JSON-Typ wird nicht als Suchwert unterstützt.
  • Das zurückgegebene JSON_QUERY JSON-Objekt oder Array wird nicht als Suchwert unterstützt.
  • Der Pfadparameter ist zurzeit erforderlich.
  • Wenn der SQL/JSON-Pfad auf ein Array verweist, ist im SQL/JSON-Pfadausdruck eine Wildcard erforderlich. Die automatische Arrayaufgliederung erfolgt aktuell nur auf der ersten Ebene.

Die JSON-Indexunterstützung umfasst das JSON_CONTAINS Prädikat und die folgenden Operatoren:

  • Vergleichsoperatoren (=)
  • IS [NOT] NULL Prädikat (derzeit nicht unterstützt)

Beispiele

Ein. Suchen nach einem SQL-Ganzzahlwert in einem JSON-Pfad

Das folgende Beispiel zeigt, wie Sie in einem JSON-Array in einem JSON-Pfad nach einem SQL-Int-Wert suchen.

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;

Hier ist das Ergebnis.

is_value_found
--------
1

B. Suchen nach einem SQL-Zeichenzeichenfolgenwert in einem JSON-Pfad

Das folgende Beispiel zeigt, wie Sie in einem JSON-Array in einem JSON-Pfad nach einem SQL-Zeichenzeichenfolgenwert suchen.

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;

Hier ist das Ergebnis.

is_value_found
--------
1

C. Suchen nach einem SQL-Bitwert in einem JSON-Array in einem JSON-Pfad

Das folgende Beispiel zeigt, wie Sie in einem JSON-Array in einem JSON-Pfad nach einem SQL-Bitwert suchen.

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;

Hier ist das Ergebnis.

is_value_found
--------
1

D. Suchen nach einem SQL-Ganzzahlwert, der in einem geschachtelten JSON-Array enthalten ist

Das folgende Beispiel zeigt, wie Sie in einem geschachtelten JSON-Array in einem JSON-Pfad nach einem SQL-Int-Wert suchen.

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;

Hier ist das Ergebnis.

is_value_found
--------
1

E. Suchen nach einem SQL-Ganzzahlwert, der in einem JSON-Objekt in einem JSON-Array enthalten ist

Das folgende Beispiel zeigt, wie Sie nach einem SQL-Int-Wert suchen, der in einem JSON-Objekt in einem JSON-Array in einem JSON-Pfad enthalten ist.

DECLARE @j AS JSON = '[{"a": 1}, {"b": 2}, {"c": 3}, {"a": 56}]';

SELECT json_contains(@j, 56, '$[*].a') AS is_value_found;

Hier ist das Ergebnis.

is_value_found
--------
1

Verwandte Inhalte