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 PATH で出力を制御する
PATH
モードではドット構文を使用できます。たとえば、ネストした出力を書式設定するには、Item.Price
と指定します。
FOR JSON
句で PATH
モードを使用するサンプル クエリを以下に示します。 次の例では、ROOT
オプションを使用して名前付きのルート要素を指定しています。
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 つの行を含めることができます。
- 大きな結果セットでは、長い JSON 文字列が複数行に分割されます。
出力設定が結果をグリッドに表示の場合、SQL Server Management Studio (SSMS) は既定で結果を単一行に連結します。 SSMS のステータス バーに、実際の行数が表示されます。
他のクライアント アプリケーションでは、複数の行の内容を連結することによって長い結果を単一の有効な JSON 文字列に結合し直すにはコードが必要になることがあります。 C# アプリケーションでのこのコードの例については、「C# クライアント アプリで FOR JSON 出力を使用する」をご覧ください。
結果は JSON オブジェクトの配列として書式設定されます。
JSON 配列の要素の数は、(FOR JSON 句が適用される前の) SELECT ステートメントの結果の行数と同じです。
(FOR JSON 句が適用される前の) SELECT ステートメントの結果の各行は、配列内の個別の JSON オブジェクトになります。
(FOR JSON 句が適用される前の) SELECT ステートメントの結果の各列は、JSON オブジェクトのプロパティになります。
列の名前とその値は、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"
}]