FOR JSON を使用してクエリ結果を JSON として書式設定する

適用対象: SQL Server 2016 (13.x) 以降 Azure SQL データベース Azure SQL Managed Instance Azure Synapse Analytics (サーバーレスの SQL プールのみ)

FOR JSON 句を SELECT ステートメントに追加して、クエリ結果を JSON として書式設定するか、SQL Server から JSON としてデータをエクスポートします。 FOR JSON 句を使用して、JSON 出力の書式設定をアプリから SQL Server に委任することによって、クライアント アプリケーションを簡素化します。

Note

Azure Data Studio は、この記事に示されているように JSON の結果を自動的に書式設定するので、JSON クエリ用に推奨されるクエリ エディターです。 SQL Server Management Studio では、書式設定されていない文字列が表示されます。

クエリ結果を書式設定する

FOR JSON 句を使用すると、JSON 出力の構造を明示的に指定したり、SELECT ステートメントの構造によって出力を決定したりできます。

  • JSON 出力の形式を完全に制御するには、FOR JSON PATH を使用します。 ラッパー オブジェクトを作成して、複雑なプロパティを入れ子にすることができます。

  • SELECT ステートメントの構造に基づいて JSON 出力を自動的に書式設定するには、FOR JSON AUTO を使用します。

FOR JSON 句とその出力を使用した SELECT ステートメントの例を次に示します。

FOR JSON のしくみを示す図。

FOR JSON PATH で出力を制御する

PATH モードではドット構文を使用できます。たとえば、ネストした出力を書式設定するには、Item.Price と指定します。

FOR JSON 句で PATH モードを使用するサンプル クエリを以下に示します。 次の例では、ROOT オプションを使用して名前付きのルート要素を指定しています。

FOR JSON 出力のフローの図

FOR JSON PATH に関する詳細情報

詳細と例については、「PATH モードで入れ子になった JSON 出力を書式設定する (SQL Server)」を参照してください。

構文と使用法については、「FOR 句 (Transact-SQL)をご覧ください。

他の JSON 出力オプションを制御する

次の追加オプションを使用して、FOR JSON 句の出力を制御します。

  • ROOT

    JSON 出力に最上位の単一要素を追加するには、ROOT オプションを指定します。 このオプションを指定しないと、JSON 出力にはルート要素がありません。 詳細については、「ROOT オプションを使用して JSON 出力にルート ノードを追加する (SQL Server)をご覧ください。

  • INCLUDE_NULL_VALUES

    JSON 出力に null 値を含めるには、INCLUDE_NULL_VALUES オプションを指定します。 このオプションを指定しないと、出力にはクエリ結果の NULL 値に対する JSON プロパティは含まれません。 詳細については、「JSON に Null 値を含める - INCLUDE_NULL_VALUES オプション」をご覧ください。

  • WITHOUT_ARRAY_WRAPPER

    既定で FOR JSON 句の JSON 出力を囲む角かっこを削除するには、WITHOUT_ARRAY_WRAPPER オプションを指定します。 このオプションを使用して、1 行の結果からの出力として単一の JSON オブジェクトを生成します。 このオプションを指定しない場合、JSON 出力は配列としてフォーマットされるため、出力は角かっこで囲まれます。 詳細については、「WITHOUT_ARRAY_WRAPPER オプションを使用して JSON から角かっこを削除する」を参照してください。

FOR JSON 句の出力

FOR JSON 句の出力には、次の特徴があります。

  1. 結果セットには 1 つの列が含まれます。

    • 小さな結果セットには 1 つの行を含めることができます。
    • 大きな結果セットでは、長い JSON 文字列が複数行に分割されます。
      • 出力設定が結果をグリッドに表示の場合、SQL Server Management Studio (SSMS) は既定で結果を単一行に連結します。 SSMS のステータス バーに、実際の行数が表示されます。

      • 他のクライアント アプリケーションでは、複数の行の内容を連結することによって長い結果を単一の有効な JSON 文字列に結合し直すにはコードが必要になることがあります。 C# アプリケーションでのこのコードの例については、「C# クライアント アプリで FOR JSON 出力を使用する」をご覧ください。

        SQL Server Management Studio の FOR JSON 出力のスクリーンショット。

  2. 結果は JSON オブジェクトの配列として書式設定されます。

    • JSON 配列の要素の数は、(FOR JSON 句が適用される前の) SELECT ステートメントの結果の行数と同じです。

    • (FOR JSON 句が適用される前の) SELECT ステートメントの結果の各行は、配列内の個別の JSON オブジェクトになります。

    • (FOR JSON 句が適用される前の) SELECT ステートメントの結果の各列は、JSON オブジェクトのプロパティになります。

  3. 列の名前とその値は、JSON の構文に従ってエスケープされます。 詳細については、「FOR JSON が特殊文字と制御文字をエスケープする仕組み (SQL Server)」をご覧ください。

FOR JSON 句による JSON 出力の書式設定の例を次に示します。

Query results

A B 貸方 D
10 11 12 x
20 21 22
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"
}]