Форматирование результатов запроса в формате JSON с помощью FOR JSON

Область применения: SQL Server 2016 (13.x) и более поздних версий База данных SQL Azure Управляемый экземпляр SQL Azure Azure Synapse Analytics (только бессерверный пул SQL)

Вы можете отформатировать результаты запроса в формате JSON или экспортировать данные из SQL Server в формате JSON, добавив предложение FOR JSON к инструкции SELECT. FOR JSON Используйте предложение для упрощения клиентских приложений путем делегирования форматирования выходных данных JSON из приложения в SQL Server.

Примечание.

Azure Data Studio — это рекомендуемый редактор запросов JSON, так как он автоматически форматирует результаты JSON, как показано в этой статье. СРЕДА SQL Server Management Studio отображает неформатированную строку.

Форматирование результатов запроса

При использовании FOR JSON предложения можно явно указать структуру выходных данных JSON или разрешить структуру инструкции SELECT определить выходные данные.

  • Чтобы сохранить полный контроль над форматом выходных данных JSON, используйте FOR JSON PATH. Вы можете создавать объекты-оболочки и вкладывать сложные свойства друг в друга.

  • Чтобы отформатировать выходные данные JSON автоматически на основе структуры инструкции SELECT , используйте FOR JSON AUTO.

Ниже приведен пример инструкции SELECT с FOR JSON предложением и его выходными данными.

Схема, показывающая, как работает FOR JSON.

Управление выходными данными с помощью FOR JSON PATH

В PATH режиме можно использовать синтаксис точки , например, Item.Price для форматирования вложенных выходных данных.

Ниже приведен пример запроса, использующего PATH режим с предложением FOR JSON . В следующем примере также используется ROOT параметр для указания именованного корневого элемента.

Схема потока выходных данных FOR JSON.

Дополнительные сведения о FOR JSON PATH

Дополнительные сведения и примеры см. в разделе "Формат вложенных выходных данных JSON" с режимом PATH (SQL Server).

Сведения о синтаксисе и использовании см. в предложении FOR (Transact-SQL).

Управление другими параметрами выходных данных JSON

Управление выходными данными FOR JSON предложения с помощью следующих дополнительных параметров.

  • ROOT

    Чтобы добавить один элемент верхнего уровня в выходные данные JSON, укажите ROOT этот параметр. Если не указать этот параметр, выходные данные JSON не будут поддерживать корневой элемент. Дополнительные сведения см. в разделе "Добавление корневого узла в выходные данные JSON" с параметром ROOT (SQL Server).

  • INCLUDE_NULL_VALUES

    Чтобы включить значения NULL в выходные данные JSON, укажите INCLUDE_NULL_VALUES параметр. Если этот параметр не указан, выходные данные не включают свойства JSON для NULL значений в результатах запроса. Дополнительные сведения см. в разделе "Включение значений NULL" в JSON — параметр INCLUDE_NULL_VALUES.

  • WITHOUT_ARRAY_WRAPPER

    Чтобы удалить квадратные скобки, которые окружают выходные данные FOR JSON JSON предложения по умолчанию, укажите WITHOUT_ARRAY_WRAPPER этот параметр. Используйте этот параметр, чтобы создать единый объект JSON в качестве выходных данных из одной строки результата. Если этот параметр не указан, выходные данные JSON форматируются в виде массива, то есть выходные данные заключены в квадратные скобки. Дополнительные сведения см. в разделе "Удалить квадратные скобки" из JSON — параметр WITHOUT_ARRAY_WRAPPER.

Выходные данные предложения FOR JSON

Выходные данные предложения FOR JSON имеют следующие характеристики:

  1. Результирующий набор содержит один столбец.

    • Небольшой результирующий набор может содержать одну строку.
    • Большой результирующий набор разбивает длинную строку JSON по нескольким строкам.
      • По умолчанию SQL Server Management Studio (SSMS) сцепляет результаты в одну строку, если выходной параметр В виде сетки. В строке состояния SSMS отображается действительное число строк.

      • Другим клиентским приложениям может потребоваться код для повторного объединения длинных результатов в одну допустимую строку JSON путем объединения содержимого нескольких строк. Пример этого кода в приложении C# см. в разделе Использование выходных данных FOR JSON в клиентском приложении C#.

        Снимок экрана: выходные данные FOR JSON в SQL Server Management Studio.

  2. Результаты форматируются в виде массива объектов JSON.

    • Число элементов в массиве JSON равно числу строк в результатах инструкции SELECT (до применения предложения FOR JSON).

    • Каждая строка в результатах инструкции SELECT (до применения предложения FOR JSON) становится отдельным объектом JSON в массиве.

    • Каждый столбец в результатах инструкции SELECT (до применения предложения FOR JSON) становится свойством объекта JSON.

  3. Как имена столбцов, так и их значения экранируются согласно синтаксису JSON. Дополнительные сведения см. в статье о том, как FOR JSON экранирует специальные символы и управляющие символы (SQL Server).

Пример

Приведенный ниже пример показывает, каким образом предложение FOR JSON форматирует выходные данные JSON.

Результаты запроса

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

Выходные данные 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"
}]