FOR JSON を使用してクエリ結果を JSON として書式設定する (SQL Server)Format Query Results as JSON with FOR JSON (SQL Server)

適用対象: ○SQL Server ○Azure SQL Database XAzure SQL Data Warehouse XParallel Data WarehouseAPPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

クエリ結果を 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.

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.

  • SELECT ステートメントの構造に基づいて JSON 出力を自動的に形式設定するには、FOR JSON AUTO を使用します。To format the JSON output automatically based on the structure of the SELECT statement, use FOR JSON AUTO.

FOR JSON 句とその出力を使用した SELECT ステートメントの例を次に示します。Here's an example of a SELECT statement with the FOR JSON clause and its output.

JSON の

オプション 1 - FOR JSON PATH でユーザーが出力を制御するOption 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.

FOR JSON 句で PATH モードを使用するサンプル クエリを次に示します。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 PATH に関する詳細情報More info about FOR JSON PATH

詳細と例については、「PATH モードで入れ子になった JSON 出力を書式設定する (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 AUTO を使用して出力を制御するOption 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.

FOR JSON 句で AUTO モードを使用するサンプル クエリを以下に示します。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 と NULL の例2.b - Example with JOIN and NULL

以下の SELECT...FOR JSON AUTO の例には、JOIN されたテーブルからのデータ間に 1 対多の関係がある場合に JSON の結果がどのように表示されるかが含まれています。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.

返された JSON に null 値が存在しないことも示されています。The absence of the null value from the returned JSON is also illustrated. ただし、この既定の動作は、FOR 句で INCLUDE_NULL_VALUES キーワードを使用することでオーバーライドできます。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

次に示すのは、上記の SELECT により出力される JSON です。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 AUTO に関する詳細情報More info about FOR JSON AUTO

詳細と例については、「AUTO モードで自動的に JSON 出力を書式設定する (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).

他の JSON 出力オプションを制御するControl other JSON output options

FOR JSON 句の出力を制御するには、次の追加オプションを使用します。Control the output of the FOR JSON clause by using the following additional options.

FOR JSON 句の出力Output of the FOR JSON clause

FOR JSON 句の出力には、次の特徴があります。The output of the FOR JSON clause has the following characteristics:

  1. 結果セットには 1 つの列が含まれます。The result set contains a single column.

    • 小さな結果セットには 1 つの行が含まれます。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# アプリケーションでのこのコードの例については、「C# クライアント アプリで FOR JSON 出力を使用する」をご覧ください。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 配列の要素の数は、(FOR JSON 句が適用される前の) SELECT ステートメントの結果の行数と同じです。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).

    • (FOR JSON 句が適用される前の) SELECT ステートメントの結果の各行は、配列内の個別の 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.

    • (FOR JSON 句が適用される前の) SELECT ステートメントの結果の各列は、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

AA BB CC DD
1010 1111 1212 ×X
2020 2121 2222 YY
3030 3131 3232 ZZ
       

JSON 出力JSON 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.

SQL Server と Azure SQL Database の JSON の詳細情報Learn more about JSON in SQL Server and Azure SQL Database

Microsoft ビデオMicrosoft videos

SQL Server と Azure SQL Database に組み込まれている JSON のサポートの視覚的な紹介は、次のビデオをご覧ください。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)
SQL Server およびクライアント アプリでの FOR JSON 出力の使用 (SQL Server)Use FOR JSON output in SQL Server and in client apps (SQL Server)