JSON_QUERY (Transact-SQL)

適用対象: はいSQL Server 2016 (13.x) 以降 はいAzure SQL データベース はいAzure SQL Managed Instance はいAzure Synapse Analytics

JSON 文字列からオブジェクトまたは配列を抽出します。

オブジェクトまたは配列ではなく JSON 文字列からスカラー値を抽出する場合は、「JSON_VALUE (Transact-SQL)」を参照してください。 JSON_VALUEJSON_QUERY の違いについては、「JSON_VALUE と JSON_QUERY を比較する」を参照してください。

トピック リンク アイコン Transact-SQL 構文表記規則

構文

JSON_QUERY ( expression [ , path ] )  

引数

式 (expression)
式。 通常、変数または JSON テキストを含む列の名前。

JSON_QUERY が、path によって識別される値を検出する前に expression で無効な JSON を検出した場合、関数はエラーを返します。 JSON_QUERYpath によって識別される値を検出できない場合、テキスト全体がスキャンされ、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 フラグメントを返します。 返される値の照合順序は、入力された式の照合順序と同じです。

値が、オブジェクトまたは配列ではなかった場合:

  • 厳密でないモードで JSON_QUERY は null を返します。

  • 厳格モードで JSON_QUERY はエラーを返します。

解説

厳密でないモードと厳格モード

次の JSON テキストを考えてみます。

{
   "info": {
      "type": 1,
      "address": {
         "town": "Bristol",
         "county": "Avon",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
} 

次の表は、lax モードと strict モードでの JSON_MODIFY の動作を比較します。 省略可能なパス モード (厳密でない、または厳格) の指定について詳しくは、「JSON パス式 (SQL Server)」を参照してください。

Path 厳密でないモードでの戻り値 厳格モードでの戻り値 詳細情報
$ 全体の JSON テキストを返します 全体の JSON テキストを返します 該当なし
$.info.type NULL エラー オブジェクトまたは配列されません。

代わりに JSON_VALUE を使用します。
$.info.address.town NULL エラー オブジェクトまたは配列されません。

代わりに JSON_VALUE を使用します。
$.info."address" N'{ "town":"Bristol", "county":"Avon", "country":"England" }' N'{ "town":"Bristol", "county":"Avon", "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

関連項目