JSON_CONTAINS (Transact-SQL)

Применимо к: Предварительная версия SQL Server 2025 (17.x)

Выполняет поиск значения SQL в JSON-документе по заданному пути.

Соглашения о синтаксисе Transact-SQL

Syntax

JSON_CONTAINS( target_expression , search_value_expression [ , path_expression ] )

Arguments

target_expression

Выражение, возвращающее целевой документ JSON для поиска. Это значение может быть типом json или строковым значением символа, содержащим документ JSON.

search_value_expression

Выражение, возвращающее скалярное значение SQL или значение типа JSON для поиска в указанном документе SQL/JSON.

path

SQL/JSON путь, указывающий цель поиска в документе JSON. Это необязательный параметр.

Можно указать переменную в качестве значения пути. В пути JSON можно указать режим синтаксического анализа: нестрогий или строгий режим. Если режим анализа не указан явно, по умолчанию используется нестрогий режим. Дополнительные сведения см. в разделе "Выражения пути JSON".

Значением по умолчанию для пути является $. В результате, если вы не предоставляете значение для пути, JSON_CONTAINS выполняется поиск значения во всем документе JSON.

Если формат пути недействителен, JSON_CONTAINS возвращает ошибку.

Возвращаемое значение

Возвращает целое значение 0, 1, или NULL. Значение 1 указывает, что указанное значение поиска содержится в целевом документе JSON или в 0 противном случае. Функция JSON_CONTAINS возвращается NULL , если какой-либо из аргументов имеет NULLзначение, или если указанный путь SQL/JSON не найден в документе JSON.

Remarks

Функция JSON_CONTAINS следует этим правилам для поиска значения, содержащегося в документе JSON:

• Скалярное значение поиска содержится в целевом скаляре, если и только в том случае, если они сопоставимы и равны. Так как типы JSON имеют только число JSON или строковое или значение true/false, возможные скалярные типы SQL, которые можно указать в качестве значения поиска, ограничены числовыми типами SQL, типами строк символов и битовым типом.

• Тип SQL скалярного поискового значения используется для сравнения со значением типа JSON в указанном пути. Это отличается от предиката, основанного на JSON_VALUE, где функция JSON_VALUE всегда возвращает символьное строковое значение.

• Значение поиска массива JSON содержится в целевом массиве, если каждый элемент в массиве поиска содержится в определенном элементе целевого массива.

• Скалярное значение поиска содержится в целевом массиве, если и только если значение поиска содержится в определенном элементе целевого массива.

• Значение поиска объекта JSON содержится в целевом объекте, если и только если каждый ключ или значение в объекте поиска найден в целевом объекте.

Limitations

JSON_CONTAINS Использование функции имеет следующие ограничения:

• Тип json не поддерживается в качестве значения поиска.
• Объект JSON или массив, возвращаемый из JSON_QUERY, не поддерживается в качестве значения поиска.
• В настоящее время требуется параметр пути.
• Если путь SQL/JSON указывает на массив, то в выражении пути SQL/JSON требуется подстановочный знак. Автоматическая распаковка массивов в настоящее время выполняется только на первом уровне.

Поддержка индекса JSON включает JSON_CONTAINS предикат и следующие операторы:

• Операторы сравнения (=)
• IS [NOT] NULL предикат (в настоящее время не поддерживается)

Examples

A. Поиск целочисленного значения SQL в пути JSON

В следующем примере показано, как искать значение int SQL в массиве JSON в пути 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;

Вот результат.

is_value_found
--------
1

B. Поиск значения строки символа SQL в пути JSON

В следующем примере показано, как искать строковое значение SQL в массиве JSON, используя путь 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, 'dd', '$.c.ce[*]') AS is_value_found;

Вот результат.

is_value_found
--------
1

C. Поиск битового значения SQL в JSON-массиве по JSON-пути

В следующем примере показано, как выполнить поиск битового значения SQL в массиве JSON в пути 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, CAST (0 AS BIT), '$.d[*]') AS is_value_found;

Вот результат.

is_value_found
--------
1

D. Поиск целочисленного значения SQL, содержащегося в вложенном массиве JSON

В следующем примере показано, как выполнить поиск значения SQL int, содержащегося во вложенном массиве JSON в пути 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, 89, '$.d[*].df[*]') AS is_value_found;

Вот результат.

is_value_found
--------
1

E. Поиск целочисленного значения SQL, содержащегося в объекте JSON в массиве JSON

В следующем примере показано, как искать значение SQL int, содержащееся в объекте JSON внутри массива JSON на пути JSON.

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

Связанный контент

• Выражения пути JSON
• Данные JSON в SQL Server