JSON_QUERY (Transact-SQL)

適用対象: SQL Server 2016 (13.x) 以降 Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsMicrosoft Fabric の SQL 分析エンドポイントMicrosoft Fabric のウェアハウス

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

オブジェクトまたは配列の代わりに JSON 文字列からスカラー値を抽出するには、 JSON_VALUEを参照してください。 JSON_VALUE と JSON_QUERY の違いについては、「JSON_VALUE と JSON_QUERY を比較する」を参照してください。

Transact-SQL 構文表記規則

構文

JSON_QUERY ( expression [ , path ] [WITH ARRAY WRAPPER])

引数

式 (expression)

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

JSON_QUERYパスで識別される値を見つける前に、式で無効な JSON を見つけた場合、関数はエラーを返します。 JSON_QUERYパスで識別される値が見つからない場合は、テキスト全体をスキャンし、式のどこにも有効でない JSON が見つかった場合はエラーを返します。

パス

抽出するオブジェクトまたは配列を指定する JSON のパス。

SQL Server 2017 (14.x) と Azure SQL データベース では、path の値として変数を指定できます。

JSON のパスを解析するための厳密でないまたは strict モードを指定できます。 解析モードの指定がない場合は、厳密でないモードが既定で指定されます。 詳細については、「JSON パス式 (SQL Server)」を参照してください。

path の既定値は$です。 この結果、path の値を指定しない場合、JSON_QUERY は、入力された expression を返します。

path の書式が有効でない場合、JSON_QUERY からエラーが返されます。

WITH ARRAY ラッパー

ANSI SQL JSON_QUERY 関数は、現在、指定されたパス内の JSON オブジェクトまたは配列を返すために使用されています。 SQL Server 2025 (17.x) プレビューで導入された SQL/JSON パス式での 配列ワイルドカード のサポートにより、 JSON_QUERY を使用して、各要素が JSON オブジェクトである JSON 配列内の要素の指定されたプロパティを返すことができます。 ワイルドカード検索は複数の値を返すことができるので、JSON クエリ式に WITH ARRAY WRAPPER 句を指定し、値を JSON 配列として返すワイルドカードまたは範囲またはリストを含む SQL/JSON パス式を指定します。 WITH ARRAY WRAPPER 句は、入力が json 型の場合にのみサポートされます。

次の JSON ドキュメントについて考えてみましょう。

declare @j JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "gender": "Female",
    "ip_address": "148.199.129.123",
    "credit_cards": [
        {
            "type": "jcb",
            "card#": "3545138777072343",
            "currency": "Koruna"
        },
        {
            "type": "diners-club-carte-blanche",
            "card#": "30282304348533",
            "currency": "Dong"
        },
        {
            "type": "jcb",
            "card#": "3585303288595361",
            "currency": "Yuan Renminbi"
        },
        {
            "type": "maestro",
            "card#": "675984450768756054",
            "currency": "Rupiah"
        },
        {
            "type": "instapayment",
            "card#": "6397068371771473",
            "currency": "Euro"
        }
    ]
}';

$.credit_cardsパスは、各要素が有効な JSON オブジェクトである JSON 配列を指します。 これで、 JSON_QUERY 関数を配列ワイルドカードのサポートと共に使用して、次のような type プロパティのすべての値または特定の値を返すことができます。

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

次の表に、ワイルドカードを使用した SQL/JSON パス式の例と、 JSON_QUERY WITH ARRAY WRAPPERを使用した戻り値を示します。

戻り値

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)」を参照してください。

JSON_QUERY と FOR JSON を使用します

JSON_QUERY は、有効な JSON フラグメントを返します。 その結果、FOR JSON は JSON_QUERY 戻り値の特殊文字をエスケープしません。

FOR JSON を使用して結果を返すときに (列内または式の結果として) 既に JSON 形式になっているデータを含める場合は、JSON_QUERY パラメーターなしで を使用して JSON データをラップします。

例

Ａ。 JSON フラグメントを返す

次の例では、クエリの結果内の CustomFields 列から JSON フラグメントを返す方法を示します。

SELECT PersonID,
       FullName,
       JSON_QUERY(CustomFields, '$.OtherLanguages') AS Languages
FROM Application.People;

B. FOR JSON 出力に JSON フラグメントを含める

FOR JSON 句の出力に JSON フラグメントを含める方法を次の例に示します。

SELECT StockItemID,
       StockItemName,
       JSON_QUERY(Tags) AS Tags,
       JSON_QUERY(CONCAT('["', ValidFrom, '","', ValidTo, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;

C. JSON_QUERY関数で WITH ARRAY ラッパーを使用する

次の例は、json 配列から複数の要素を返すために、WITH ARRAY WRAPPER関数でJSON_QUERYを使用する方法を示しています。

DECLARE @j JSON = ' {"id":2,"first_name":"Mamie","last_name":"Baudassi","email":"mbaudassi1@abc.net.au","gender":"Female","ip_address":"148.199.129.123","credit_cards":[{"type":"jcb","card#":"3545138777072343","currency":"Koruna"},{"type":"diners-club-carte-blanche","card#":"30282304348533","currency":"Dong"},{"type":"jcb","card#":"3585303288595361","currency":"Yuan Renminbi"},{"type":"maestro","card#":"675984450768756054","currency":"Rupiah"},{"type":"instapayment","card#":"6397068371771473","currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;

結果セットは次のとおりです。

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

関連するコンテンツ

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