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

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, confira Comparar JSON_VALUE e JSON_QUERY.

Convenções de sintaxe de Transact-SQL

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 o 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

Um demarcador 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

Retorne o valor especificado no tipo SQL. Só terá suporte se a entrada for um tipo JSON. Os tipos sql 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

Se RETURNING não estiver incluído:

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

• Se o valor tiver mais que 4000 caracteres:

  • No modo lax, JSON_VALUE 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 sql 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 esta 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 de fato 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