JSON_QUERY (Transact-SQL)

  • Статья

Применимо к: SQL Server 2016 (13.x) и более поздних версий Azure SQL Database Управляемый экземпляр SQL AzureAzure Synapse Analytics

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

Чтобы извлечь скалярное значение, а не объект или массив из строки JSON, см. раздел JSON_VALUE (Transact-SQL). Сведения о различиях между JSON_VALUE и JSON_QUERY см. в разделе Сравнение JSON_VALUE и JSON_QUERY.

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

Синтаксис

JSON_QUERY ( expression [ , path ] )

Аргументы

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

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

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

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

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

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

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

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

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

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

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

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

Remarks

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

Рассмотрим следующий текст 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 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 без параметра путь.

Примеры

Пример 1

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

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

Пример 2

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

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

См. также раздел