JSON_QUERY (Transact-SQL)

  • Статья

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

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

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

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

Синтаксис

JSON_QUERY ( expression [ , path ] )

Аргументы

выражение

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

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

path

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

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

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

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

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

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

Возвращает фрагмент 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 параметра пути .

Примеры

Пример 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

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