適用対象:
SQL Server 2025 (17.x) プレビュー
JSON ドキュメント内のパス内の SQL 値を検索します。
注
JSON_CONTAINS関数は現在プレビュー段階であり、SQL Server 2025 (17.x) プレビューでのみ使用できます。
構文
JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )
論争
target_expression
検索するターゲット JSON ドキュメントを返す式。 値には、JSON 型または JSON ドキュメントを含む文字列値を指定できます。
サーチ値表現
指定した SQL/JSON ドキュメントで検索する SQL スカラー値または json 型の値を返す式。
パス
JSON ドキュメント内の検索ターゲットを指定する SQL/JSON パス。 このパラメーターは省略可です。
パスの値として変数を指定できます。 JSON のパスを解析するための厳密でないまたは strict モードを指定できます。 解析モードの指定がない場合は、厳密でないモードが既定で指定されます。 詳細については、「JSON パス式 (SQL Server)」を参照してください。
path の既定値は$です。 その結果、パスの値を指定しない場合は、 JSON ドキュメント全体の値を検索します。
path の書式が有効でない場合、JSON_CONTAINS からエラーが返されます。
戻り値
、0、または1の NULL 値を返します。
1の値は、指定した検索値がターゲット JSON ドキュメント内に含まれていたことを示します。それ以外の場合は0。
JSON_CONTAINS関数は、引数のいずれかがNULLされている場合、または指定された SQL/JSON パスが JSON ドキュメントに見つからない場合に、NULLを返します。
注釈
JSON_CONTAINS関数は、JSON ドキュメントに値が含まれているかどうかを検索するための次の規則に従います。
スカラー検索値は、比較可能で等しい場合にのみ、ターゲット スカラーに含まれます。 JSON 型には JSON 番号または文字列または true/false 値しかないため、検索値として指定できる SQL スカラー型は、SQL 数値型、文字列型、ビット型に制限されます。
スカラー検索値の SQL 型は、指定されたパスの json 型の値との比較を実行するために使用されます。 これは、
JSON_VALUE関数が常に文字列値を返すJSON_VALUEベースの述語とは異なります。JSON 配列の検索値は、検索配列内のすべての要素がターゲット配列の一部の要素に含まれている場合にのみ、ターゲット配列に含まれます。
検索値がターゲット配列の一部の要素に含まれている場合にのみ、スカラー検索値がターゲット配列に含まれます。
検索オブジェクト内の各キー/値がターゲット オブジェクトで見つかった場合にのみ、JSON オブジェクトの検索値がターゲット オブジェクトに含まれます。
制限事項
JSON_CONTAINS関数の使用には、次の制限があります。
- json 型は検索値としてサポートされていません。
-
JSON_QUERYから返される JSON オブジェクトまたは配列は、検索値としてサポートされていません。 - path パラメーターは現在必須です。
- SQL/JSON パスが配列を指している場合は、SQL/JSON パス式でワイルドカードが必要です。 自動配列のラップ解除は、現在、最初のレベルでのみ行われます。
JSON インデックスのサポートには、 JSON_CONTAINS 述語と次の演算子が含まれます。
- 比較演算子 (
=) -
IS [NOT] NULL述語 (現在サポートされていません)
例示
Ａ。 JSON パスで SQL 整数値を検索する
次の例は、JSON パス内の JSON 配列で SQL int 値を検索する方法を示しています。
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;
結果セットは次のとおりです。
is_value_found
--------
1
B. JSON パスで SQL 文字列値を検索する
次の例は、JSON パス内の JSON 配列で SQL 文字列値を検索する方法を示しています。
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;
結果セットは次のとおりです。
is_value_found
--------
1
C. JSON パス内の JSON 配列で SQL ビット値を検索する
次の例は、JSON パス内の JSON 配列で SQL ビット値を検索する方法を示しています。
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;
結果セットは次のとおりです。
is_value_found
--------
1
D. 入れ子になった JSON 配列内に含まれる SQL 整数値を検索する
次の例は、JSON パス内の入れ子になった JSON 配列内に含まれる SQL int 値を検索する方法を示しています。
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;
結果セットは次のとおりです。
is_value_found
--------
1
E. JSON 配列内の JSON オブジェクト内に含まれる SQL 整数値を検索する
次の例は、JSON パス 内の JSON 配列内の JSON オブジェクト内に含まれる SQL int 値を検索する方法を示しています。
DECLARE @j AS JSON = '[{"a": 1}, {"b": 2}, {"c": 3}, {"a": 56}]';
SELECT json_contains(@j, 56, '$[*].a') AS is_value_found;
結果セットは次のとおりです。
is_value_found
--------
1