Compartilhar via

JSON_QUERY (Transact-SQL)

  • Artigo

Aplica-se a: SQL Server 2016 (13.x) e posterior Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure 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, consulte 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 encontrar JSON que não é 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, verificará todo o texto e retornará um erro se encontrar JSON que não é válido em algum lugar da expressão.

caminho

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 retorna nulo.

  • No modo estrito, JSON_QUERY retorna 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.

Usar 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 de retorno JSON_QUERY.

Se você estiver retornando resultados com FOR JSON e incluindo dados que já estão 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

Conteúdo relacionado