JSON_QUERY(Transact-SQL)

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

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

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

Transact-SQL 構文表記規則

Syntax

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

Arguments

expression

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

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

path

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

SQL Server 2017 (14.x) と Azure SQL Database では、 パスの値として変数を指定できます。

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

パスの既定値は $ です。 その結果、 パスの値を指定しない場合、 JSON_QUERY は入力 式を返します。

パスの形式が無効な場合、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 AS JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@example.com",
    "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 はエラーを返します。

Remarks

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

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

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

次の表は、厳密でないモードと厳格モードでの JSON_QUERY の動作を比較します。 省略可能なパス モードの仕様 (lax または strict) の詳細については、 SQL Database エンジンの JSON パス式を参照してください。

JSON_QUERY と FOR JSON を使用します

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

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

Examples

A. 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@example.com", "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"]

関連コンテンツ

• SQL データベース エンジンの JSON パス式
• SQL Server の JSON データ