JSON_QUERY (Transact-SQL)

Область применения: SQL Server 2016 (13.x) и более поздних версий База данных SQL Azure Управляемый экземпляр SQL Azureконечную точку аналитики SQL Azure Synapse Analytics в хранилище Microsoft Fabricв Microsoft Fabric

Извлекает объект или массив из строки JSON.

Чтобы извлечь скалярное значение из строки JSON вместо объекта или массива, см. JSON_VALUE. Дополнительные сведения о различиях между JSON_VALUE и JSON_QUERY см. в разделе JSON_QUERY и JSON_QUERY".

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

Синтаксис

JSON_QUERY ( expression [ , path ] [WITH ARRAY WRAPPER])

Аргументы

выражение

Выражение . Обычно имя переменной или столбца, содержащего текст JSON.

Если JSON_QUERY объект JSON недействителен в выражении перед поиском значения, определяемого по пути, функция возвращает ошибку. Если JSON_QUERY значение, определенное по пути, не найдено, он сканирует весь текст и возвращает ошибку, если он находит JSON, который не является допустимым в выражении.

путь

Путь JSON, который указывает объект или массив для извлечения.

В SQL Server 2017 (14.x) и в База данных SQL Azure можно указать переменную в качестве значения пути.

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

Значением по умолчанию для пути является $. В результате, если вы не предоставляете значение пути, JSON_QUERY возвращает входное выражение.

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

С ОБОЛОЧКОЙ МАССИВА

Замечание

WITH ARRAY WRAPPER В настоящее время доступна предварительная версия и доступна только в SQL Server 2025 (17.x) (предварительная версия).

Функция ANSI SQL JSON_QUERY в настоящее время используется для возврата объекта ИЛИ массива JSON в указанном пути. С поддержкой подстановочных знаков массива в выражении пути SQL/JSON, представленном в предварительной версии JSON_QUERY SQL Server 2025 (17.x), можно использовать для возврата указанных свойств элементов в массиве JSON, где каждый элемент является объектом JSON. Так как поиск по подстановочным знакам может возвращать несколько значений, укажите WITH ARRAY WRAPPER предложение в выражении запроса JSON вместе с выражением пути SQL/JSON с подстановочным знаком или диапазоном или списком, чтобы вернуть значения в виде массива JSON. WITH ARRAY WRAPPER предложение поддерживается только в том случае, если входные данные являются типом json .

Рассмотрим следующий документ JSON:

declare @j JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "gender": "Female",
    "ip_address": "148.199.129.123",
    "credit_cards": [
        {
            "type": "jcb",
            "card#": "3545138777072343",
            "currency": "Koruna"
        },
        {
            "type": "diners-club-carte-blanche",
            "card#": "30282304348533",
            "currency": "Dong"
        },
        {
            "type": "jcb",
            "card#": "3585303288595361",
            "currency": "Yuan Renminbi"
        },
        {
            "type": "maestro",
            "card#": "675984450768756054",
            "currency": "Rupiah"
        },
        {
            "type": "instapayment",
            "card#": "6397068371771473",
            "currency": "Euro"
        }
    ]
}';

Путь $.credit_cards указывает на массив JSON, где каждый элемент является допустимым объектом JSON. JSON_QUERY Теперь функцию можно использовать с поддержкой подстановочных знаков массива для возврата всех или определенных значений type свойства, например:

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

В следующей таблице показаны различные примеры выражения пути SQL/JSON с подстановочным знаком и возвращаемым значением.JSON_QUERY WITH ARRAY WRAPPER

Путь	Возвращаемое значение
$.creditcards[0].type	["jcb"]
$.credit_cards[*].type	["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]
$.credit_cards[0, 2].type	["jcb","jcb"]
$.credit_cards[1 to 3].type	["diners-club-carte-blanche","jcb","maestro"]
$.credit_cards[last].type	["instapayment"]
$.credit_cards[last, 0].type	["instapayment","jcb"]
$.credit_cards[last, last].type	["instapayment","instapayment"]
$.credit_cards[ 0, 2, 4].type	["jcb","jcb","instapayment"]

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

Возвращает фрагмент JSON типа nvarchar(max). Параметры сортировки для возвращаемого значения совпадают с параметрами сортировки входного выражения.

Если значение не является объектом или массивом:

• В режиме JSON_QUERY lax возвращает значение NULL.

• В строгом режиме JSON_QUERY возвращает ошибку.

Замечания

Нестрогий и строгий режимы

Рассмотрим следующий текст JSON:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

В следующей таблице сравнивается поведение JSON_QUERY в нестрогом режиме и в строгом режиме. Дополнительные сведения о необязательном режиме пути (строгий или нестрогий) см. в статье Выражения пути JSON (SQL Server).

Путь	Возвращаемое значение в нестрогом режиме	Возвращаемое значение в строгом режиме	Дополнительная информация
$	Возвращает весь текст JSON.	Возвращает весь текст JSON.
$.info.type	NULL	Ошибка	Значение не является объектом или массивом. Вместо этого используйте JSON_VALUE.
$.info.address.town	NULL	Ошибка	Значение не является объектом или массивом. Вместо этого используйте JSON_VALUE.
$.info."address"	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'
$.info.tags	N'[ "Sport", "Water polo"]'	N'[ "Sport", "Water polo"]'
$.info.type[0]	NULL	Ошибка	Не является массивом.
$.info.none	NULL	Ошибка	Свойство не существует.

Использование JSON_QUERY с FOR JSON

JSON_QUERY возвращает допустимый фрагмент JSON. В результате FOR JSON не экранирует специальные символы в возвращаемом значении JSON_QUERY.

Если вы возвращаете результаты с помощью FOR JSON, и вы включаете данные, которые уже есть в формате JSON (в столбце или в результате выражения), заключите данные JSON без JSON_QUERYпараметра пути .

Примеры

А. Возврат фрагмента JSON

В следующем примере показано, как можно вернуть фрагмент JSON из столбца CustomFields в результатах запроса.

SELECT PersonID,
       FullName,
       JSON_QUERY(CustomFields, '$.OtherLanguages') AS Languages
FROM Application.People;

В. Включение фрагментов JSON в выходные данные FOR JSON

В следующем примере показано, как включить фрагменты JSON в выходные данные предложения FOR JSON.

SELECT StockItemID,
       StockItemName,
       JSON_QUERY(Tags) AS Tags,
       JSON_QUERY(CONCAT('["', ValidFrom, '","', ValidTo, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;

С. Использование WITH ARRAY WRAPPER с функцией JSON_QUERY

В следующем примере показано использование WITH ARRAY WRAPPERJSON_QUERY функции для возврата нескольких элементов из массива JSON:

DECLARE @j JSON = ' {"id":2,"first_name":"Mamie","last_name":"Baudassi","email":"mbaudassi1@abc.net.au","gender":"Female","ip_address":"148.199.129.123","credit_cards":[{"type":"jcb","card#":"3545138777072343","currency":"Koruna"},{"type":"diners-club-carte-blanche","card#":"30282304348533","currency":"Dong"},{"type":"jcb","card#":"3585303288595361","currency":"Yuan Renminbi"},{"type":"maestro","card#":"675984450768756054","currency":"Rupiah"},{"type":"instapayment","card#":"6397068371771473","currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;

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

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

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

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