Muokkaa

Jaa

Format nested JSON output with PATH mode

Applies to: SQL Server 2016 (13.x) and later versions Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics (serverless SQL pool only) SQL analytics endpoint in Microsoft Fabric Warehouse in Microsoft Fabric SQL database in Microsoft Fabric

To maintain full control over the output of the FOR JSON clause, specify the PATH option.

PATH mode lets you create wrapper objects and nest complex properties. The results are formatted as an array of JSON objects.

The alternative is to use the AUTO option to format the output automatically based on the structure of the SELECT statement.

The following examples show how to use the FOR JSON clause with the PATH option. Format nested results by using dot-separated column names or by using nested queries, as shown in the examples. By default, null values aren't included in FOR JSON output.

Note

The MSSQL extension for Visual Studio Code can auto-format the JSON results (as seen in this article) instead of displaying an unformatted string.

Examples

The code samples in this article use the AdventureWorks2025 or AdventureWorksDW2025 sample database, which you can download from the Microsoft SQL Server Samples and Community Projects home page.

A. Dot-separated column names

The following query formats the first five rows from the AdventureWorks Person table as JSON.

The FOR JSON PATH clause uses the column alias or column name to determine the key name in the JSON output. If an alias contains dots, the PATH option creates nested objects.

SELECT TOP 5 BusinessEntityID AS Id,
             FirstName,
             LastName,
             Title AS 'Info.Title',
             MiddleName AS 'Info.MiddleName'
FROM Person.Person
FOR JSON PATH;

Here's the result set.

[{
    "Id": 1,
    "FirstName": "Ken",
    "LastName": "Sanchez",
    "Info": {
        "MiddleName": "J"
    }
}, {
    "Id": 2,
    "FirstName": "Terri",
    "LastName": "Duffy",
    "Info": {
        "MiddleName": "Lee"
    }
}, {
    "Id": 3,
    "FirstName": "Roberto",
    "LastName": "Tamburello"
}, {
    "Id": 4,
    "FirstName": "Rob",
    "LastName": "Walters"
}, {
    "Id": 5,
    "FirstName": "Gail",
    "LastName": "Erickson",
    "Info": {
        "Title": "Ms.",
        "MiddleName": "A"
    }
}]

B. Multiple tables

If you reference more than one table in a query, FOR JSON PATH nests each column using its alias. The following query creates one JSON object for each (OrderHeader, OrderDetails) pair that the query joins.

SELECT TOP 2 H.SalesOrderNumber AS 'Order.Number',
             H.OrderDate AS 'Order.Date',
             D.UnitPrice AS 'Product.Price',
             D.OrderQty AS 'Product.Quantity'
FROM Sales.SalesOrderHeader AS H
     INNER JOIN Sales.SalesOrderDetail AS D
         ON H.SalesOrderID = D.SalesOrderID
FOR JSON PATH;

Here's the result set.

[{
    "Order": {
        "Number": "SO43659",
        "Date": "2011-05-31T00:00:00"
    },
    "Product": {
        "Price": 2024.9940,
        "Quantity": 1
    }
}, {
    "Order": {
        "Number": "SO43659"
    },
    "Product": {
        "Price": 2024.9940
    }
}]

Learn more about JSON in the SQL Database Engine

For a visual introduction to the built-in JSON support, see JSON as a bridge between NoSQL and relational worlds.

Related content

  • Last updated on