Поделиться через

JSON_QUERY (Transact-SQL)

Применимо к: SQL Server 2016 (13.x) и более поздние версии:конечная точка аналитики SQL AzureSynapse Analytics в хранилище MicrosoftFabric в базе данных SQL Microsoft Fabric в Microsoft Fabric

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

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

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

Syntax

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

Arguments

expression

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

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

path

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

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

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

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

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

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

Note

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

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

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

DECLARE @j AS JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@example.com",
    "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, '$.credit_cards[*].type' WITH ARRAY WRAPPER);

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

Path Возвращаемое значение
$.credit_cards[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 возвращает ошибку.

Remarks

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

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

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

В следующей таблице сравнивается поведение JSON_QUERY в нестрогом режиме и в строгом режиме. Дополнительные сведения о спецификации дополнительного режима пути (lax или strict) см. в выражениях пути JSON в ядре СУБД SQL.

Path Возвращаемое значение в нестрогом режиме Возвращаемое значение в строгом режиме Дополнительная информация
$ Возвращает весь текст JSON. Возвращает весь текст JSON.
$.info.type NULL Error Значение не является объектом или массивом.

Вместо этого используйте JSON_VALUE.
$.info.address.town NULL Error Значение не является объектом или массивом.

Вместо этого используйте 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 Error Не является массивом.
$.info.none NULL Error Свойство не существует.

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

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

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

Examples

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

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

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

B. Включение фрагментов 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;

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

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

DECLARE @j JSON = '
{"id":2, "first_name":"Mamie", "last_name":"Baudassi", "email":"mbaudassi1@example.com", "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"]

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

  • Last updated on