JSON_VALUE (Transact-SQL)

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL analytics endpoint in Microsoft FabricWarehouse em Microsoft FabricSQL database in Microsoft Fabric

A JSON_VALUE sintaxe extrai 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, consulte Comparar JSON_VALUE e JSON_QUERY.

Transact-SQL convenções de sintaxe

Syntax

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Arguments

expression

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

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

path

Um caminho JSON 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

Retornar o valor especificado no tipo SQL. Suportado apenas se a entrada for do tipo JSON. Os tipos de SQL suportados 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

Se RETURNING não estiver incluído:

• Retorna um único valor de texto do tipo nvarchar(4000). O agrupamento do valor retornado é o mesmo que o agrupamento da expressão de entrada.

• Se o valor for maior que 4000 caracteres:

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

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

Se RETURNING estiver incluído:

Retorna o valor especificado no tipo SQL. Os tipos de SQL suportados 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 estiver armazenado em varchar, nvarchar ou no tipo de dados json nativo.

Remarks

Modo lax 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 lax e no modo estrito. Para obter mais informações sobre a especificação do modo de caminho opcional (lax ou strict), consulte Expressões de caminho JSON no Mecanismo de Banco de Dados SQL.

Path	Valor de retorno no modo lax	Valor de retorno no modo estrito	Mais informações
$	NULL	Error	Não é um valor escalar. Utilize JSON_QUERY em substituição.
$.info.type	N'1'	N'1'	N/a
$.info.endereço.cidade	N'Bristol'	N'Bristol'	N/a
$.info." endereço"	NULL	Error	Não é um valor escalar. Utilize JSON_QUERY em substituição.
$.info.tags	NULL	Error	Não é um valor escalar. Utilize JSON_QUERY em substituição.
$.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 town JSON e state nos resultados da consulta. Como JSON_VALUE preserva o agrupamento da fonte, a ordem de classificação dos resultados depende do agrupamento da jsonInfo coluna.

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 lax 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 town JSON em 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 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