Formatar os resultados da consulta como JSON com FOR JSON

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 (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, use FOR JSON AUTO.

Veja abaixo um exemplo de uma instrução SELECT com a cláusula FOR JSON e a respectiva saída.

Diagram showing how FOR JSON works.

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.

Diagram of flow of FOR JSON output.

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 valores NULL 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ção WITHOUT_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:

  1. 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#.

        Screenshot of FOR JSON output in SQL Server Management Studio.

  2. 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.

  3. 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"
}]