JSON_QUERY (Transact-SQL)

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores Banco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse Analytics

Extrai um objeto ou uma matriz de uma cadeia de caracteres JSON.

Para extrair um valor escalar de uma cadeia de caracteres JSON em vez de um objeto ou uma matriz, confira JSON_VALUE (Transact-SQL). 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

Sintaxe

JSON_QUERY ( expression [ , path ] )  

Argumentos

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

Se JSON_QUERY localizar um JSON que não seja válido na expressão antes de encontrar o valor identificado por path, a função retornará um erro. Se JSON_QUERY não encontrar o valor identificado por path, ele verificará todo o texto e retornará um erro se encontrar um JSON que não seja válido em algum lugar na expressão.

path
Um demarcador JSON que especifica o objeto ou a matriz a ser extraída.

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

O demarcador JSON pode especificar o modo incerto ou estrito para análise. Se você não especificar o modo de análise, o modo incerto será o padrão. Para obter mais informações, confira Expressões de demarcador JSON (SQL Server).

O valor padrão para path é '$'. Como resultado, se você não fornecer um valor para path, JSON_QUERY retornará a expressão de entrada.

Se o formato de path não for válido, JSON_QUERY retornará um erro.

Valor retornado

Retorna um fragmento JSON do tipo nvarchar(max). A ordenação do valor retornado é a mesma que a ordenação da expressão de entrada.

Se o valor não for um objeto nem uma matriz:

• No modo incerto JSON_QUERY retornará nulo.

• No modo estrito, JSON_QUERY retornará um erro.

Comentários

Modo incerto e modo estrito

Considere o seguinte texto JSON:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
} 

A tabela a seguir compara o comportamento de JSON_QUERY no modo incerto e no modo estrito. 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).

Caminho	Valor retornado no modo incerto	Valor retornado no modo estrito	Obter mais informações
$	Retorna o texto JSON inteiro.	Retorna o texto JSON inteiro.	N/A
$.info.type	NULO	Erro	Não é um objeto nem uma matriz. Use JSON_VALUE nesse caso.
$.info.address.town	NULO	Erro	Não é um objeto nem uma matriz. Use JSON_VALUE nesse caso.
$.info."address"	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'	N/A
$.info.tags	N'[ "Sport", "Water polo"]'	N'[ "Sport", "Water polo"]'	N/A
$.info.type[0]	NULO	Erro	Não é uma matriz.
$.info.none	NULO	Erro	A propriedade não existe.

Usando JSON_QUERY com FOR JSON

JSON_QUERY retorna um fragmento JSON válido. Como resultado, FOR JSON não usa escape para caracteres especiais no valor retornado de JSON_QUERY.

Se você estiver retornando resultados com FOR JSON e estiver incluindo dados que já estejam no formato JSON (em uma coluna ou como resultado de uma expressão), encapsule os dados JSON com JSON_QUERY sem o parâmetro path.

Exemplos

Exemplo 1

O exemplo a seguir mostra como retornar um fragmento JSON de uma coluna CustomFields nos resultados da consulta.

SELECT PersonID,FullName,
  JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People

Exemplo 2

O exemplo a seguir mostra como incluir fragmentos JSON na saída da cláusula FOR JSON.

SELECT StockItemID, StockItemName,
         JSON_QUERY(Tags) as Tags,
         JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH

Confira também

• Expressões de demarcador JSON (SQL Server)
• Dados JSON (SQL Server)