JSON_VALUE (Transact-SQL)

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores do Banco de Dados SQL doAzure Azure Instância Gerenciada de SQLdo Azure Synapse Analytics ponto deextremidade de análise de SQL no Microsoft Fabric Warehouse no Banco de Dados SQLdo Microsoft Fabricno Microsoft Fabric

Use a JSON_VALUE sintaxe para extrair um valor escalar de uma cadeia de caracteres JSON.

Para extrair um objeto ou uma matriz de uma cadeia de caracteres JSON em vez de um valor escalar, consulte JSON_QUERY. Para obter informações sobre as diferenças entre JSON_VALUE e JSON_QUERY, confira Comparar JSON_VALUE e JSON_QUERY.

Convenções de sintaxe de Transact-SQL

Syntax

Sintaxe para SQL Server 2025 (17.x) e versões posteriores.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

No SQL Server 2022 (16.x) e em versões anteriores, RETURNING não está incluído.

Arguments

expression

Uma expressão que normalmente é o nome de uma variável ou uma coluna que contém texto JSON.

Se JSON_VALUE encontrar JSON que não seja válido na expressão antes de localizar o valor identificado pelo caminho, a função retornará um erro. Se JSON_VALUE não encontrar o valor identificado por caminho, ele examinará todo o texto e retornará um erro se encontrar JSON que não seja válido em qualquer lugar na expressão.

path

A JSON caminho que especifica a propriedade a ser extraída. Para obter mais informações, consulte expressões de caminho JSON no Mecanismo de Banco de Dados SQL.

No SQL Server 2017 (14.x) e no Banco de Dados SQL do Azure, você pode fornecer uma variável como o valor do caminho.

Se o formato do caminho não for válido, JSON_VALUE retornará um erro.

data_type

O tipo de dados que você deseja usar para o valor retornado. Esse tipo só terá suporte se a entrada for um tipo JSON. Os tipos de dados com suporte são: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 e datetimeoffset.

Valor de retorno

Aplica-se a: SQL Server 2025 (17.x) e versões posteriores.

Se você não incluir RETURNING:

• Retorna um único valor de texto do tipo nvarchar(4000). A ordenação do valor retornado corresponde à ordenação da expressão de entrada.

• Se o valor for maior que 4.000 caracteres:

  • No modo lax, JSON_VALUE retorna NULL.
  • No modo estrito, JSON_VALUE retorna um erro.

  Se você precisar retornar valores escalares maiores que 4.000 caracteres, use OPENJSON em vez de JSON_VALUE. Para obter mais informações, consulte OPENJSON.

Se você incluir RETURNING:

Retorna o valor especificado em data_type. Os tipos de dados com suporte são: tinyint, smallint, int, bigint, decimal, numeric, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 e datetimeoffset.

As funções JSON funcionam da mesma forma se o documento JSON é armazenado em varchar, nvarchar ou no tipo de dados json nativo.

Remarks

Modo incerto e modo estrito

Considere o seguinte texto 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"
 }';

A tabela a seguir compara o comportamento de JSON_VALUE no modo incerto e no modo estrito. Para obter mais informações sobre a especificação do modo de caminho opcional (frouxo ou estrito), consulte expressões de caminho JSON no Mecanismo de Banco de Dados SQL.

Path	Valor retornado no modo incerto	Valor retornado no modo estrito	Mais informações
$	NULL	Error	Não é um valor escalar. Use o JSON_QUERY em vez disso.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	Não é um valor escalar. Use o JSON_QUERY em vez disso.
$.info.tags	NULL	Error	Não é um valor escalar. Use o JSON_QUERY em vez disso.
$.info.type[0]	NULL	Error	Não é uma matriz.
$.info.none	NULL	Error	A propriedade não existe.

Examples

Exemplo 1

O exemplo a seguir usa os valores das propriedades JSON town e state nos resultados da consulta. Como JSON_VALUE preserva a ordenação da origem, a ordem de classificação dos resultados depende da ordenação da coluna jsonInfo.

Note

Este exemplo pressupõe que uma tabela nomeada Person.Person contenha uma jsonInfo coluna de texto JSON e que essa coluna tenha a estrutura mostrada anteriormente na discussão do modo frouxo e do modo estrito. AdventureWorks No banco de dados de exemplo, a Person tabela não contém uma jsonInfo coluna.

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');

Exemplo 2

O exemplo a seguir extrai o valor da propriedade JSON town para uma variável local.

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

Exemplo 3

O exemplo a seguir cria as colunas computadas com base nos valores das propriedades 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')
);

Exemplo 4

O exemplo a seguir extrai um valor da matriz JSON usando JSON_VALUE e retorna o valor como um valor de tipo de data.

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

Conteúdo relacionado

• Expressões de caminho JSON no Mecanismo de Banco de Dados SQL
• Dados JSON no SQL Server