JSON_VALUE (Transact-SQL)

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

JSON_VALUE Используйте синтаксис для извлечения скалярного значения из строки JSON.

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

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

Syntax

Синтаксис для SQL Server 2025 (17.x) и более поздних версий.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

В SQL Server 2022 (16.x) и более ранних версиях функция RETURNING не включена.

Arguments

expression

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

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

path

A JSON путь, указывающий свойство для извлечения. Дополнительные сведения см. в выражениях пути JSON в ядре СУБД SQL.

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

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

data_type

Тип данных, используемый для возвращаемого значения. Этот тип поддерживается только в том случае, если входные данные являются типом JSON. Поддерживаемые типы данных: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max),nchar, nvarchar, nvarchar(max), date, time, datetime2 и datetimeoffset.

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

Относится к: SQL Server 2025 (17.x) и более поздним версиям.

Если вы не включаете RETURNING:

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

• Если значение больше 4000 символов:

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

  Если необходимо возвращать скалярные значения, превышающие 4000 символов, используйте OPENJSON вместо JSON_VALUEнего. Дополнительные сведения см. в разделе OPENJSON.

Если вы включаете RETURNING:

Возвращает значение, указанное в data_type. Поддерживаемые типы данных: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max),nchar, nvarchar, nvarchar(max), date, time, datetime2 и datetimeoffset.

Функции JSON работают так же, как документ JSON хранится в varchar, nvarchar или собственном типе данных JSON .

Remarks

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

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

DECLARE @jsonInfo AS NVARCHAR (MAX);

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

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

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

Examples

Пример 1

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

Note

В этом примере предполагается, что таблица с именем 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 AS NVARCHAR (MAX);
DECLARE @town AS 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')
);

Пример 4

В следующем примере извлекается значение из массива JSON и JSON_VALUE возвращается значение в качестве значения типа даты.

DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';

SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;

date_value
--------
2025-01-01

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

• Выражения пути JSON в ядре СУБД SQL
• Данные JSON в SQL Server