Formatar os resultados da consulta como JSON com FOR JSON
Aplica-se a: SQL Server 2016 (13.x) e posteriores
Banco de Dados SQL do Azure
Instância Gerenciada de SQL do Azure
Azure Synapse Analytics (somente pool de SQL sem servidor)
Formate os resultados da consulta como JSON ou exporte dados do SQL Server como JSON, adicionando a cláusula FOR JSON
a uma instrução SELECT
. Use a cláusula FOR JSON
para simplificar os aplicativos cliente ao delegar a formatação da saída JSON do aplicativo para o SQL Server.
Observação
O Azure Data Studio é o editor de consulta recomendado para consultas JSON porque ele formata automaticamente os resultados JSON, como visto neste artigo. O SQL Server Management Studio exibe uma cadeia de caracteres não formatada.
Formatar resultados de consulta
Ao usar a cláusula FOR JSON
, você pode especificar explicitamente a estrutura da saída JSON ou permitir que a estrutura da instrução SELECT
determine a saída.
Para manter o controle total sobre o formato da saída JSON, use
FOR JSON PATH
. Você pode criar objetos wrapper e aninhar propriedades complexas.Formate a saída JSON automaticamente com base na estrutura da instrução
SELECT
, useFOR JSON AUTO
.
Veja abaixo um exemplo de uma instrução SELECT
com a cláusula FOR JSON
e a respectiva saída.
Controle de saída com FOR JSON PATH
No modo PATH
, você pode usar a sintaxe de ponto, por exemplo,Item.Price
para formatar a saída aninhada.
Veja um exemplo de consulta que usa o modo PATH
com a cláusula FOR JSON
. O exemplo a seguir também usa a opção ROOT
para especificar um elemento de raiz nomeado.
Mais informações sobre o FOR JSON PATH
Para mais informações detalhadas e exemplos, confira Formatar a Saída JSON Aninhada com o Modo PATH (SQL Server).
Para sintaxe e uso, veja Cláusula FOR (Transact-SQL).
Controlar outras opções de saída JSON
Controle a saída da cláusula FOR JSON
usando as opções adicionais a seguir.
ROOT
Para adicionar um único elemento de nível superior à saída JSON, especifique a opção
ROOT
. Se você não especificar essa opção, a saída JSON não terá um elemento raiz. Para obter mais informações, consulte Adicionar um nó raiz à saída JSON com a opção ROOT (SQL Server).INCLUDE_NULL_VALUES
Para incluir valores nulos na saída JSON, especifique a opção
INCLUDE_NULL_VALUES
. Se você não especificar essa opção, a saída não incluirá propriedades JSON para valoresNULL
nos resultados da consulta. Veja mais informações em Incluir valores Null em JSON - opção INCLUDE_NULL_VALUES.WITHOUT_ARRAY_WRAPPER
Para remover, por padrão, os colchetes que envolvem a saída JSON da cláusula
FOR JSON
, especifique a opçãoWITHOUT_ARRAY_WRAPPER
. Use esta opção para gerar um único objeto JSON como saída de um resultado de linha única. Se você não especificar essa opção, a saída JSON será formatada como uma matriz, ou seja, a saída será colocada entre colchetes. Veja mais informações em Remover os colchetes da saída JSON - opção WITHOUT_ARRAY_WRAPPER.
Saída da cláusula FOR JSON
A saída da cláusula FOR JSON
tem as seguintes características:
O conjunto de resultados contém uma única coluna.
- Um conjunto de resultados pequeno pode conter uma única linha.
- Um conjunto de resultados grande divide a cadeia de caracteres JSON longa em várias linhas.
Por padrão, o SSMS (SQL Server Management Studio) concatena os resultados em uma única linha quando a configuração de saída é Resultados em Grade. A barra de status do SSMS exibe a contagem de linhas real.
Outros aplicativos cliente podem exigir o código para recombinar os resultados longos em uma cadeia de caracteres JSON única e válida, concatenando os conteúdos de várias linhas. Para obter um exemplo do código em um aplicativo C#, consulte Usar a saída FOR JSON em um aplicativo cliente C#.
Os resultados são formatados como uma matriz de objetos JSON.
O número de elementos na matriz JSON é igual ao número de linhas nos resultados da instrução SELECT (antes da cláusula FOR JSON ser aplicada).
Cada linha nos resultados da instrução SELECT (antes da cláusula FOR JSON ser aplicada) se torna um objeto JSON separado na matriz.
Cada coluna nos resultados da instrução SELECT (antes da cláusula FOR JSON ser aplicada) se torna uma propriedade do objeto JSON.
Os dois os nomes das colunas e seus valores são escapados de acordo com a sintaxe JSON. Para obter mais informações, veja Como o FOR JSON ignora os caracteres especiais e os caracteres de controle (SQL Server).
Exemplo
Veja abaixo um exemplo que demonstra como a cláusula FOR JSON
formata a saída JSON.
Resultados da consulta
A | B | C | D |
---|---|---|---|
10 | 11 | 12 | X |
20 | 21 | 22 | Y |
30 | 31 | 32 | Z |
Saída em JSON
[{
"A": 10,
"B": 11,
"C": 12,
"D": "X"
}, {
"A": 20,
"B": 21,
"C": 22,
"D": "Y"
}, {
"A": 30,
"B": 31,
"C": 32,
"D": "Z"
}]
Conteúdo relacionado
- Como FOR JSON converte tipos de dados do SQL Server para tipos de dados JSON (SQL Server)
- Como o FOR JSON ignora os caracteres especiais e os caracteres de controle (SQL Server)
- JSON é uma ponte entre o NoSQL e mundos relacionais
- SELECT – Cláusula FOR (Transact-SQL)
- Usar a saída FOR JSON no SQL Server e em aplicativos cliente (SQL Server)