Condividi tramite


Formattare i risultati delle query in formato JSON con FOR JSON

Si applica a: SQL Server 2016 (13.x) e alle sue versioni successive Database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics (solo pool SQL serverless)

È possibile formattare i risultati delle query come JSON o esportare i dati da SQL Server in formato JSON aggiungendo la clausola FOR JSON a un'istruzione SELECT. Usare la clausola FOR JSON per semplificare le applicazioni client delegando la formattazione dell'output JSON dell'app a SQL Server.

Nota

Azure Data Studio è l'editor di query consigliato per le query JSON perché formatta automaticamente i risultati JSON, come illustrato in questo articolo. SQL Server Management Studio visualizza una stringa non formattata.

Formattare i risultati delle query

Quando si usa la clausola FOR JSON, è possibile specificare la struttura dell'output JSON in modo esplicito o determinarla automaticamente in base alla struttura dell'istruzione SELECT.

  • Per mantenere il controllo completo sul formato dell'output JSON, usare FOR JSON PATH. È possibile creare oggetti wrapper e annidare proprietà complesse.

  • Per formattare automaticamente l'output JSON in base alla struttura dell'istruzione SELECT, usare FOR JSON AUTO.

Di seguito è riportato un esempio di istruzione SELECT con la clausola FOR JSON e il relativo output.

Diagramma che mostra il funzionamento di FOR JSON.

Controllo dell'output con FOR JSON PATH

In modalità PATH è possibile utilizzare la sintassi a punti, ad esempio Item.Price, per formattare l'output annidato.

Ecco una query di esempio che usa la modalità PATH con la clausola FOR JSON. L'esempio seguente usa anche l'opzione ROOT per specificare un elemento radice denominato.

Diagramma di flusso dell'output FOR JSON.

Altre informazioni su FOR JSON PATH

Per altre informazioni ed esempi, vedere Formattare l'output JSON annidato con la modalità PATH (SQL Server).

Per la sintassi e l'uso, vedere Clausola FOR (Transact-SQL).

Controllare altre opzioni di output JSON

Controllare l'output della clausola FOR JSON utilizzando le seguenti opzioni aggiuntive.

  • ROOT

    Per aggiungere un unico elemento di primo livello all'output JSON, specificare l'opzione ROOT. Se non si specifica questa opzione, l'output JSON non ha alcun elemento radice. Per altre informazioni, vedere Aggiungere un nodo radice all'output JSON con l'opzione ROOT (SQL Server).

  • INCLUDE_NULL_VALUES

    Per includere valori null nell'output JSON, specificare l'opzione INCLUDE_NULL_VALUES. Se non si specifica questa opzione, l'output non include le proprietà JSON per i valori NULL presenti nei risultati della query. Per altre informazioni, vedere Includere valori in JSON - Opzione INCLUDE_NULL_VALUES.

  • WITHOUT_ARRAY_WRAPPER

    Per rimuovere le parentesi quadre che racchiudono l'output JSON della clausola FOR JSON per impostazione predefinita, specificare l'opzione WITHOUT_ARRAY_WRAPPER. Usare questa opzione per generare un singolo oggetto JSON come output da un risultato a riga singola. Se non si specifica questa opzione, l'output JSON viene formattato come una matrice, ovvero è racchiuso tra parentesi quadre. Per altre informazioni, vedere Rimuovere le parentesi quadre da JSON - Opzione WITHOUT_ARRAY_WRAPPER.

Output della clausola FOR JSON

L'output della clausola FOR JSON ha le seguenti caratteristiche:

  1. Il set di risultati contiene un'unica colonna.

    • Un set di risultati di piccole dimensioni può contenere un'unica riga.
    • Un set di risultati di grandi dimensioni suddivide la stringa JSON su più righe.
      • Per impostazione predefinita, SQL Server Management Studio (SSMS) concatena i risultati in una singola riga quando l'impostazione dell'output è Risultati in formato griglia. La barra di stato di SQL Server Management Studio visualizza il conteggio effettivo delle righe.

      • Altre applicazioni client possono richiedere codice per ricombinare i risultati eccessivamente lunghi in un'unica stringa JSON valida concatenando i contenuti di più righe. Per un esempio di questo codice in un'applicazione C#, vedere Usare l'output FOR JSON in un'app client C#.

        Screenshot dell'output FOR JSON in SQL Server Management Studio.

  2. I risultati vengono formattati sotto forma di matrice di oggetti JSON.

    • Il numero di elementi nella matrice JSON è uguale al numero di righe nei risultati dell'istruzione SELECT (prima che venga applicata la clausola FOR JSON).

    • Ogni riga nei risultati dell'istruzione SELECT (prima che venga applicata la clausola FOR JSON) diventa un oggetto JSON separato nella matrice.

    • Ogni colonna nei risultati dell'istruzione SELECT (prima che venga applicata la clausola FOR JSON) diventa una proprietà dell'oggetto JSON.

  3. I nomi delle colonne e i valori corrispondenti vengono sottoposti a escape in base alla sintassi JSON. Per altre informazioni, vedere Sequenze di escape FOR JSON per i caratteri speciali e di controllo (SQL Server).

Esempio

Ecco un esempio che illustra come la clausola FOR JSON formatta l'output JSON.

Risultati query

Un B C D
10 11 12 X
20 21 22 Y
30 31 32 Z

Output 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"
}]