Форматирование результатов запроса как JSON с помощью предложения FOR JSON (SQL Server)Format Query Results as JSON with FOR JSON (SQL Server)

Применимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL DatabaseПрименимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL Database

Вы можете отформатировать результаты запроса как JSON или экспортировать данные из SQL Server в формате JSON, добавив предложение FOR JSON к инструкции SELECT.Format query results as JSON, or export data from SQL Server as JSON, by adding the FOR JSON clause to a SELECT statement. Предложение FOR JSON упрощает клиентские приложения, делегируя форматирование выходных данных JSON из приложения в SQL ServerSQL Server.Use the FOR JSON clause to simplify client applications by delegating the formatting of JSON output from the app to SQL ServerSQL Server. Azure Data Studio является рекомендуемым редактором запросов JSON, так как он позволяет выполнять автоматическое форматирование результатов JSON (как показано в этой статье) вместо отображения плоской строки.Azure Data Studio is the recommended query editor for JSON queries because it auto-formats the JSON results (as seen in this article) instead of displaying a flat string.

При использовании предложения FOR JSON вы можете в явном виде указать структуру выходных данных JSON или дать определить ее структуре инструкции SELECT.When you use the FOR JSON clause, you can specify the structure of the JSON output explicitly, or let the structure of the SELECT statement determine the output.

  • Чтобы сохранить полный контроль над форматом выходных данных JSON, используйте FOR JSON PATH.To maintain full control over the format of the JSON output, use FOR JSON PATH. Вы можете создавать объекты-оболочки и вкладывать сложные свойства друг в друга.You can create wrapper objects and nest complex properties.

  • Используйте FOR JSON AUTO, чтобы отформатировать выходные данные JSON автоматически на основе структуры инструкции SELECT.To format the JSON output automatically based on the structure of the SELECT statement, use FOR JSON AUTO.

Ниже приведен пример инструкции SELECT с предложением FOR JSON и ее выходные данные.Here's an example of a SELECT statement with the FOR JSON clause and its output.

FOR JSON

Вариант 1. Вы управляете выходными данными с помощью FOR JSON PATHOption 1 - You control output with FOR JSON PATH

В режиме PATH можно использовать синтаксис с точкой — например, 'Item.UnitPrice' — для форматирования вложенных выходных данных.In PATH mode, you can use the dot syntax - for example, 'Item.UnitPrice' - to format nested output.

Ниже приведен пример запроса, где режим PATH с предложением FOR JSON .Here's a sample query that uses PATH mode with the FOR JSON clause. В следующем примере также используется параметр ROOT для указания именованного корневого элемента.The following example also uses the ROOT option to specify a named root element.

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

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

Более подробные сведения и примеры см. в разделе Форматирование вложенных выходных данных JSON с помощью режима PATH (SQL Server).For more detailed info and examples, see Format Nested JSON Output with PATH Mode (SQL Server).

Сведения о синтаксисе и использовании см. в разделе Предложение FOR (Transact-SQL).For syntax and usage, see FOR Clause (Transact-SQL).

Вариант 2. Инструкция SELECT управляет выходными данными с помощью FOR JSON AUTOOption 2 - SELECT statement controls output with FOR JSON AUTO

В режиме AUTO структура инструкции SELECT определяет формат выходных данных JSON.In AUTO mode, the structure of the SELECT statement determines the format of the JSON output.

По умолчанию значения NULL не включаются в выходные данные.By default, null values are not included in the output. Это поведение можно изменить с помощью INCLUDE_NULL_VALUES .You can use the INCLUDE_NULL_VALUES to change this behavior.

Ниже приведен пример запроса, где режим AUTO используется с предложением FOR JSON .Here's a sample query that uses AUTO mode with the FOR JSON clause.

SELECT name, surname  
FROM emp  
FOR JSON AUTO;

А вот возвращаемый JSON.And here is the returned JSON.

[{
    "name": "John"
}, {
    "name": "Jane",
    "surname": "Doe"
}]

2.b — пример с JOIN и NULL2.b - Example with JOIN and NULL

В следующем примере SELECT...FOR JSON AUTO включает результаты JSON при соотношении связи "один ко многим" между данными из таблиц JOIN.The following example of SELECT...FOR JSON AUTO includes a display of what the JSON results look like when there is a 1:Many relationship between data from JOIN'ed tables.

Отсутствие значения NULL в возвращаемом JSON также показано.The absence of the null value from the returned JSON is also illustrated. Тем не менее можно переопределить это поведение по умолчанию с помощью ключевого слова INCLUDE_NULL_VALUES в предложении FOR.However, you can override this default behavior by use of the INCLUDE_NULL_VALUES keyword on the FOR clause.

go

DROP TABLE IF EXISTS #tabStudent;
DROP TABLE IF EXISTS #tabClass;

go

CREATE TABLE #tabClass
(
   ClassGuid   uniqueIdentifier  not null  default newid(),
   ClassName   nvarchar(32)      not null
);

CREATE TABLE #tabStudent
(
   StudentGuid   uniqueIdentifier  not null  default newid(),
   StudentName   nvarchar(32)      not null,
   ClassGuid     uniqueIdentifier      null   -- Foreign key.
);

go

INSERT INTO #tabClass
      (ClassGuid, ClassName)
   VALUES
      ('DE807673-ECFC-4850-930D-A86F921DE438', 'Algebra Math'),
      ('C55C6819-E744-4797-AC56-FF8A729A7F5C', 'Calculus Math'),
      ('98509D36-A2C8-4A65-A310-E744F5621C83', 'Art Painting')
;

INSERT INTO #tabStudent
      (StudentName, ClassGuid)
   VALUES
      ('Alice Apple', 'DE807673-ECFC-4850-930D-A86F921DE438'),
      ('Alice Apple', 'C55C6819-E744-4797-AC56-FF8A729A7F5C'),
      ('Betty Boot' , 'C55C6819-E744-4797-AC56-FF8A729A7F5C'),
      ('Betty Boot' , '98509D36-A2C8-4A65-A310-E744F5621C83'),
      ('Carla Cap'  , null)
;

go

SELECT
      c.ClassName,
      s.StudentName
   from
                       #tabClass   as c
      RIGHT OUTER JOIN #tabStudent as s ON s.ClassGuid = c.ClassGuid
   --where
   --   c.ClassName LIKE '%Math%'
   order by
      c.ClassName,
      s.StudentName
   FOR
      JSON AUTO
      --, INCLUDE_NULL_VALUES
;

go

DROP TABLE IF EXISTS #tabStudent;
DROP TABLE IF EXISTS #tabClass;

go

Вот JSON, который выводится предыдущей инструкцией SELECT.And next is the JSON that is output by the preceding SELECT.

JSON_F52E2B61-18A1-11d1-B105-00805F49916B

[
   {"s":[{"StudentName":"Carla Cap"}]},
   {"ClassName":"Algebra Math","s":[{"StudentName":"Alice Apple"}]},
   {"ClassName":"Art Painting","s":[{"StudentName":"Betty Boot"}]},
   {"ClassName":"Calculus Math","s":[{"StudentName":"Alice Apple"},{"StudentName":"Betty Boot"}]}
]

Дополнительные сведения о FOR JSON AUTOMore info about FOR JSON AUTO

Более подробные сведения и примеры см. в разделе Автоматическое форматирование выходных данных JSON с помощью режима AUTO (SQL Server).For more detailed info and examples, see Format JSON Output Automatically with AUTO Mode (SQL Server).

Сведения о синтаксисе и использовании см. в разделе Предложение FOR (Transact-SQL).For syntax and usage, see FOR Clause (Transact-SQL).

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

Управление выходными данными из FOR JSON предложения, используя следующие дополнительные параметры.Control the output of the FOR JSON clause by using the following additional options.

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

Выходные данные предложения FOR JSON имеют следующие характеристики:The output of the FOR JSON clause has the following characteristics:

  1. Результирующий набор содержит один столбец.The result set contains a single column.

    • Небольшой результирующий набор может содержать одну строку.A small result set may contain a single row.
    • Большой результирующий набор разбивает длинную строку JSON по нескольким строкам.A large result set splits the long JSON string across multiple rows.
      • По умолчанию SQL Server Management Studio (SSMS) сцепляет результаты в одну строку, если выходной параметр В виде сетки.By default, SQL Server Management Studio (SSMS) concatenates the results into a single row when the output setting is Results to Grid. В строке состояния SSMS отображается действительное число строк.The SSMS status bar displays the actual row count.
      • В других клиентских приложениях может потребоваться внести код, который будет перераспределять большой объем результатов в одну общую допустимую строку JSON, объединяя содержимое множества записей.Other client applications may require code to recombine lengthy results into a single, valid JSON string by concatenating the contents of multiple rows. Пример этого кода в приложении C# см. в разделе Использование выходных данных FOR JSON в клиентском приложении C#.For an example of this code in a C# application, see Use FOR JSON output in a C# client app.

    Пример выходных данных FOR JSON

  2. Результаты форматируются в виде массива объектов JSON.The results are formatted as an array of JSON objects.

    • Число элементов в массиве JSON равно числу строк в результатах инструкции SELECT (до применения предложения FOR JSON).The number of elements in the JSON array is equal to the number of rows in the results of the SELECT statement (before the FOR JSON clause is applied).

    • Каждая строка в результатах инструкции SELECT (до применения предложения FOR JSON) становится отдельным объектом JSON в массиве.Each row in the results of the SELECT statement (before the FOR JSON clause is applied) becomes a separate JSON object in the array.

    • Каждый столбец в результатах инструкции SELECT (до применения предложения FOR JSON) становится свойством объекта JSON.Each column in the results of the SELECT statement (before the FOR JSON clause is applied) becomes a property of the JSON object.

  3. Как имена столбцов, так и их значения экранируются согласно синтаксису JSON.Both the names of columns and their values are escaped according to JSON syntax. Дополнительные сведения см. в разделе Как FOR JSON экранирует специальные и управляющие символы (SQL Server).For more info, see How FOR JSON escapes special characters and control characters (SQL Server).

ПримерExample

Приведенный ниже пример показывает, каким образом предложение FOR JSON форматирует выходные данные JSON.Here's an example that demonstrates how the FOR JSON clause formats the JSON output.

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

ОбъектA BB CC DD
1010 1111 1212 XX
2020 2121 2222 ДаY
3030 3131 3232 ZZ
       

Выходные данные JSONJSON output

[{
    "A": 10,
    "B": 11,
    "C": 12,
    "D": "X"
}, {
    "A": 20,
    "B": 21,
    "C": 22,
    "D": "Y"
}, {
    "A": 30,
    "B": 31,
    "C": 32,
    "D": "Z"
}] 

Дополнительные сведения о том, какое содержимое отображается в выходных данных предложения FOR JSON, см. в следующих статьях.For more info about what you see in the output of the FOR JSON clause, see the following topics.

Дополнительные сведения о JSON в SQL Server и базе данных SQL AzureLearn more about JSON in SQL Server and Azure SQL Database

Видео МайкрософтMicrosoft videos

Наглядные инструкции по встроенной поддержке JSON в SQL Server и базе данных SQL Azure см. в следующих видео.For a visual introduction to the built-in JSON support in SQL Server and Azure SQL Database, see the following videos:

См. также:See Also

Предложение FOR (Transact-SQL) FOR Clause (Transact-SQL)
Использование выходных данных FOR JSON в SQL Server и клиентских приложениях (SQL Server)Use FOR JSON output in SQL Server and in client apps (SQL Server)