JSON_VALUE (Transact-SQL)JSON_VALUE (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure simSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure SQL Data Warehouse noParallel Data Warehouse

Extrai um valor escalar de uma cadeia de caracteres JSON.Extracts a scalar value from a JSON string.

Para extrair um objeto ou uma matriz de uma cadeia de caracteres JSON em vez de um valor escalar, confira JSON_QUERY (Transact-SQL).To extract an object or an array from a JSON string instead of a scalar value, see JSON_QUERY (Transact-SQL). Para obter informações sobre as diferenças entre JSON_VALUE e JSON_QUERY, confira Comparar JSON_VALUE e JSON_QUERY.For info about the differences between JSON_VALUE and JSON_QUERY, see Compare JSON_VALUE and JSON_QUERY.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

JSON_VALUE ( expression , path )  

ArgumentosArguments

expressãoexpression
Uma expressão.An expression. Normalmente, o nome de uma variável ou de uma coluna que contém o texto JSON.Typically the name of a variable or a column that contains JSON text.

Se JSON_VALUE localizar um JSON que não seja válido na expressão antes de localizar o valor identificado por path, a função retornará um erro.If JSON_VALUE finds JSON that is not valid in expression before it finds the value identified by path, the function returns an error. Se JSON_VALUE não localizar o valor identificado por path, ele examinará todo o texto e retornará um erro se localizar um JSON que não seja válido em nenhum lugar na expressão.If JSON_VALUE doesn't find the value identified by path, it scans the entire text and returns an error if it finds JSON that is not valid anywhere in expression.

pathpath
Um demarcador JSON que especifica a propriedade a ser extraída.A JSON path that specifies the property to extract. Para obter mais informações, confira Expressões de demarcador JSON (SQL Server).For more info, see JSON Path Expressions (SQL Server).

No SQL Server 2017 (14.x)SQL Server 2017 (14.x) e no Banco de dados SQL do AzureAzure SQL Database, você pode fornecer uma variável como o valor de path.In SQL Server 2017 (14.x)SQL Server 2017 (14.x) and in Banco de dados SQL do AzureAzure SQL Database, you can provide a variable as the value of path.

Se o formato de path não for válido, JSON_VALUE retornará um erro.If the format of path isn't valid, JSON_VALUE returns an error .

Valor retornadoReturn value

Retorna um valor de texto único do tipo nvarchar(4000).Returns a single text value of type nvarchar(4000). A ordenação do valor retornado é a mesma que a ordenação da expressão de entrada.The collation of the returned value is the same as the collation of the input expression.

Se o valor tiver mais que 4000 caracteres:If the value is greater than 4000 characters:

  • No modo incerto JSON_VALUE retorna nulo.In lax mode, JSON_VALUE returns null.

  • No modo estrito, JSON_VALUE retorna um erro.In strict mode, JSON_VALUE returns an error.

Se você precisar retornar valores escalares com mais de 4000 caracteres, use OPENJSON em vez de JSON_VALUE.If you have to return scalar values greater than 4000 characters, use OPENJSON instead of JSON_VALUE. Para obter mais informações, veja OPENJSON (Transact-SQL).For more info, see OPENJSON (Transact-SQL).

RemarksRemarks

Modo incerto e modo estritoLax mode and strict mode

Considere o seguinte texto JSON:Consider the following JSON text:

DECLARE @jsonInfo NVARCHAR(MAX)

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

A tabela a seguir compara o comportamento de JSON_VALUE no modo incerto e no modo estrito.The following table compares the behavior of JSON_VALUE in lax mode and in strict mode. Para obter mais informações sobre a especificação de modo de demarcador opcional (incerto ou estrito), confira Expressões de demarcador JSON (SQL Server).For more info about the optional path mode specification (lax or strict), see JSON Path Expressions (SQL Server).

CaminhoPath Valor retornado no modo incertoReturn value in lax mode Valor retornado no modo estritoReturn value in strict mode Obter mais informaçõesMore info
$ NULLNULL ErroError Não é um valor escalar.Not a scalar value.

Use JSON_QUERY nesse caso.Use JSON_QUERY instead.
$.info.type$.info.type N'1'N'1' N'1'N'1' N/AN/a
$.info.address.town$.info.address.town N'Bristol'N'Bristol' N'Bristol'N'Bristol' N/AN/a
$.info."address"$.info."address" NULLNULL ErroError Não é um valor escalar.Not a scalar value.

Use JSON_QUERY nesse caso.Use JSON_QUERY instead.
$.info.tags$.info.tags NULLNULL ErroError Não é um valor escalar.Not a scalar value.

Use JSON_QUERY nesse caso.Use JSON_QUERY instead.
$.info.type[0]$.info.type[0] NULLNULL ErroError Não é uma matriz.Not an array.
$.info.none$.info.none NULLNULL ErroError A propriedade não existe.Property does not exist.
       

ExemplosExamples

Exemplo 1Example 1

O exemplo a seguir usa os valores das propriedades JSON town e state nos resultados da consulta.The following example uses the values of the JSON properties town and state in query results. Como JSON_VALUE preserva a ordenação da origem, a ordem de classificação dos resultados depende da ordenação da coluna jsonInfo.Since JSON_VALUE preserves the collation of the source, the sort order of the results depends on the collation of the jsonInfo column.

Observação

(Este exemplo assume que uma tabela denominada Person.Person contém uma coluna jsonInfo de texto JSON e que essa coluna tem a estrutura mostrada anteriormente na discussão sobre modo incerto e modo estrito.(This example assumes that a table named Person.Person contains a jsonInfo column of JSON text, and that this column has the structure shown previously in the discussion of lax mode and strict mode. No banco de dados AdventureWorks de exemplo, a tabela Person realmente não contém uma coluna jsonInfo.)In the AdventureWorks sample database, the Person table does not in fact contain a jsonInfo column.)

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

Exemplo 2Example 2

O exemplo a seguir extrai o valor da propriedade JSON town para uma variável local.The following example extracts the value of the JSON property town into a local variable.

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

Exemplo 3Example 3

O exemplo a seguir cria as colunas computadas com base nos valores das propriedades JSON.The following example creates computed columns based on the values of JSON properties.

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

Confira tambémSee also

Expressões de demarcador JSON (SQL Server) JSON Path Expressions (SQL Server)
Dados JSON (SQL Server)JSON Data (SQL Server)