JSON_QUERY (Transact-SQL)
適用対象: SQL Server 2016 (13.x) 以降
Azure SQL Database
Azure SQL Managed Instance
Azure Synapse Analytics
JSON 文字列からオブジェクトまたは配列を抽出します。
オブジェクトまたは配列ではなく JSON 文字列からスカラー値を抽出する場合は、「JSON_VALUE (Transact-SQL)」を参照してください。 JSON_VALUE と JSON_QUERY
の違いについては、「JSON_VALUE と JSON_QUERY を比較する」を参照してください。
構文
JSON_QUERY ( expression [ , path ] )
引数
式 (expression)
式。 通常、変数または JSON テキストを含む列の名前。
JSON_QUERY
が、path によって識別される値を検出する前に expression で無効な JSON を検出した場合、関数はエラーを返します。 JSON_QUERY
が path によって識別される値を検出できない場合、テキスト全体がスキャンされ、expression のどこかで無効な JSON を検出した場合はエラーを返します。
path
抽出するオブジェクトまたは配列を指定する JSON のパス。
SQL Server 2017 (14.x) と Azure SQL データベース では、path の値として変数を指定できます。
JSON のパスを解析するための厳密でないまたは strict モードを指定できます。 解析モードの指定がない場合は、厳密でないモードが既定で指定されます。 詳細については、「JSON パス式 (SQL Server)」を参照してください。
path の既定値は '$' です。 この結果、path の値を指定しない場合、JSON_QUERY
は、入力された expression を返します。
path の書式が有効でない場合、JSON_QUERY
からエラーが返されます。
戻り値
nvarchar(max) 型の JSON フラグメントを返します。 返される値の照合順序は、入力された式の照合順序と同じです。
値が、オブジェクトまたは配列ではなかった場合:
lax モードでは、
JSON_QUERY
は null を返します。厳格モードでは、
JSON_QUERY
はエラーを返します。
解説
厳密でないモードと厳格モード
次の JSON テキストを考えてみます。
{
"info": {
"type": 1,
"address": {
"town": "Cheltenham",
"county": "Gloucestershire",
"country": "England"
},
"tags": ["Sport", "Water polo"]
},
"type": "Basic"
}
次の表は、厳密でないモードと厳格モードでの JSON_QUERY
の動作を比較します。 省略可能なパス モード (厳密でない、または厳格) の指定について詳しくは、「JSON パス式 (SQL Server)」を参照してください。
Path | 厳密でないモードでの戻り値 | 厳格モードでの戻り値 | 詳細情報 |
---|---|---|---|
$ | 全体の JSON テキストを返します | 全体の JSON テキストを返します | 該当なし |
$.info.type | NULL | エラー | オブジェクトまたは配列されません。 代わりに JSON_VALUE を使用します。 |
$.info.address.town | NULL | エラー | オブジェクトまたは配列されません。 代わりに JSON_VALUE を使用します。 |
$.info."address" | N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' | N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' | 該当なし |
$.info.tags | N'[ "Sport", "Water polo"]' | N'[ "Sport", "Water polo"]' | 該当なし |
$.info.type[0] | NULL | エラー | 配列ではありません。 |
$.info.none | NULL | エラー | プロパティが存在しません。 |
JSON_QUERY と FOR JSON を使用します
JSON_QUERY
は、有効な JSON フラグメントを返します。 その結果、FOR JSON は、JSON_QUERY
戻り値内の特殊文字をエスケープしません。
FOR JSON を使用して結果を返すときに (列内または式の結果として) 既に JSON 形式になっているデータを含める場合は、path パラメーターなしで JSON_QUERY
を使用して JSON データをラップします。
例
例 1
次の例では、クエリの結果内の CustomFields
列から JSON フラグメントを返す方法を示します。
SELECT PersonID,FullName,
JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People
例 2
FOR JSON 句の出力に JSON フラグメントを含める方法を次の例に示します。
SELECT StockItemID, StockItemName,
JSON_QUERY(Tags) as Tags,
JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH