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 を比較する」を参照してください。

Transact-SQL 構文表記規則

構文

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

関連するコンテンツ

• JSON パス式 (SQL Server)
• SQL Server の JSON データ