JSON_VALUE (Transact-SQL)

Статья
05/30/2023

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

Извлекает скалярное значение из строки JSON.

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

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

Синтаксис

JSON_VALUE ( expression , path )

Аргументы

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

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

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

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

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

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

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

Если длина значения превышает 4000 символов:

в нестрогом режиме JSON_VALUE возвращает значение NULL;
в строгом режиме JSON_VALUE возвращает сообщение об ошибке.

Если необходимо возвращать скалярные значения длиной более 4000 символов, используйте функцию OPENJSON вместо JSON_VALUE. Дополнительные сведения см. в разделе OPENJSON (Transact-SQL).

Remarks

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

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

DECLARE @jsonInfo NVARCHAR(MAX)

SET @jsonInfo=N'{  
     "info":{    
       "type":1,  
       "address":{    
         "town":"Bristol",  
         "county":"Avon",  
         "country":"England"  
       },  
       "tags":["Sport", "Water polo"]  
    },  
    "type":"Basic"  
 }'

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

путь	Возвращаемое значение в нестрогом режиме	Возвращаемое значение в строгом режиме	Дополнительные сведения
$	NULL	Error	Не является скалярным значением. Используйте вместо этого функцию JSON_QUERY.
$.info.type	N'1'	N'1'	Недоступно
$.info.address.town	N'Bristol'	N'Bristol'	Недоступно
$.info."address"	NULL	Error	Не является скалярным значением. Используйте вместо этого функцию JSON_QUERY.
$.info.tags	NULL	Error	Не является скалярным значением. Используйте вместо этого функцию JSON_QUERY.
$.info.type[0]	NULL	Error	Не является массивом.
$.info.none	NULL	Error	Свойство не существует.

Примеры

Пример 1

В приведенном ниже примере в результатах запроса используются значения свойств JSON town и state. Так как функция JSON_VALUE сохраняет параметры сортировки источника, порядок сортировки результатов зависит от параметров сортировки столбца jsonInfo.

Примечание

(В этом примере предполагается, что таблица с именем Person.Person содержит столбец jsonInfo с текстом JSON и что этот столбец имеет структуру, показанную ранее в обсуждении нестрогого и строгого режимов. В примере базы данных AdventureWorks таблица Person не содержит столбец jsonInfo.)

SELECT FirstName, LastName,
 JSON_VALUE(jsonInfo,'$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo,'$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo,'$.info.address.town')

Пример 2

В приведенном ниже примере извлекается значение свойства JSON town в локальную переменную.

DECLARE @jsonInfo NVARCHAR(MAX)
DECLARE @town NVARCHAR(32)

SET @jsonInfo=N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';

SET @town=JSON_VALUE(@jsonInfo,'$.info.address[0].town'); -- Paris
SET @town=JSON_VALUE(@jsonInfo,'$.info.address[1].town'); -- London

Пример 3

В приведенном ниже примере создаются вычисляемые столбцы на основе значений свойств JSON.

CREATE TABLE dbo.Store
 (
  StoreID INT IDENTITY(1,1) NOT NULL,
  Address VARCHAR(500),
  jsonContent NVARCHAR(4000),
  Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
  Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
 )

См. также

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