適用於：
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 檔中搜尋。
路徑
SQL/JSON 路徑，指定 JSON 檔中的搜尋目標。 這是選擇性參數。
您可以提供變數做為 路徑的值。 JSON 路徑可為剖析指定 lax 或 strict 模式。 若您未指定剖析模式，預設會使用 lax 模式。 如需詳細資訊，請參閱 JSON 路徑運算式 (SQL Server)。
路徑的預設值為 $。 因此，如果您沒有提供 路徑的值， JSON_CONTAINS 請在整個 JSON 檔中搜尋值。
如果 path 的格式無效，則 JSON_CONTAINS 會傳回錯誤。
返回值
傳回 、0 或 1 的 NULL 值。 的值 1 表示指定的搜尋值包含在目標 JSON 檔中，否則 0 為 。 如果任一自變數為 JSON_CONTAINS，或 JSON 檔中找不到指定的 SQL/JSON 路徑，則函NULL式會傳回 NULL 。
備註
函 JSON_CONTAINS 式會遵循下列規則來搜尋 JSON 檔中是否包含值：
純量搜尋值會包含在目標純量中，前提是它們可比較且相等。 因為 json 類型只有 JSON 數位或字串或 true/false 值，因此可以指定為搜尋值的可能 SQL 純量類型僅限於 SQL 數值類型、字元字串類型和 位 類型。
純量搜尋值的 SQL 類型是用來執行與指定路徑中 json 類型值的比較。 這與以
JSON_VALUE為基礎的述詞不同，其中JSON_VALUE函式一律傳回字串值。只有當搜尋陣列中的每一個元素都包含在目標陣列的一些元素中時，JSON 陣列搜尋值才會包含在目標陣列中。
只有在搜尋值包含在目標陣列的某些元素時，純量搜尋值才會包含在目標陣列中。
如果在目標物件中找到搜尋物件中的每個索引鍵/值，JSON 物件搜尋值才會包含在目標物件中。
局限性
使用 函 JSON_CONTAINS 式有下列限制：
- json 類型不支援作為搜尋值。
- 不支援從
JSON_QUERY傳回的 JSON 物件或數位作為搜尋值。 - 路徑參數目前是必要的。
- 如果 SQL/JSON 路徑指向陣列，則在 SQL/JSON 路徑表示式中需要使用通配符。 自動陣列解包目前僅限於第一層。
JSON 索引支援包括 JSON_CONTAINS 述詞和下列運算子：
- 比較運算子 （
=） -
IS [NOT] NULL謂詞（目前不支援）
範例
A。 在 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