MariaDB JSON_SEARCH（）の説明

MariaDBでは、JSON_SEARCH() は、JSONドキュメント内の特定の値へのパスを取得できる組み込み関数です。

JSONドキュメントと文字列を引数として受け入れ、ドキュメント内の指定された文字列へのパスを返します。

構文

構文は次のようになります：

JSON_SEARCH(
    json_doc, 
    return_arg, 
    search_str[, escape_char[, path] ...]
    )

場所：

json_doc JSONドキュメントとsearch_str 文字列です。
return_arg キーワードone またはall 。 oneを使用する場合、最初のパスのみが返されます。その他の発生は無視されます。どのパスが「最初」と見なされるかは未定義です（MariaDBのドキュメントによる）。 allの場合を指定すると、すべてのオカレンスのパスが返されます。複数のパスがある場合、それらは配列として自動ラップされます。
escape_char 引数は、エスケープ文字として使用するオプションの文字です。
path 引数は、JSONドキュメント内の「トップレベル」パスがどこから始まるかを決定するためのオプションの引数です。

例

デモンストレーションの例を次に示します。

SET @json = '
    { 
        "name" : "Wag", 
        "type" : "Dog" 
    }';

SELECT JSON_SEARCH(@json, 'one', 'Wag');

結果：

+----------------------------------+
| JSON_SEARCH(@json, 'one', 'Wag') |
+----------------------------------+
| "$.name"                         |
+----------------------------------+

配列内の要素のパスを返す例を次に示します。

SET @json = '
    { 
        "product" : "Left Handed Screwdriver", 
        "sizes" : [ "Small", "Medium", "Large" ],
    }';

SELECT JSON_SEARCH(@json, 'one', 'Medium');

結果：

+-------------------------------------+
| JSON_SEARCH(@json, 'one', "Medium") |
+-------------------------------------+
| "$.sizes[1]"                        |
+-------------------------------------+

配列はゼロベースであるため、$.sizes[1] 配列の2番目の要素を参照します。

複数回発生

文字列を含むすべてのパスを返す場合は、allを使用します oneの代わりに 2番目の引数について。

SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'all', 'Dog');

結果：

+----------------------------------+
| JSON_SEARCH(@json, 'all', "Dog") |
+----------------------------------+
| ["$[0].type", "$[1].type"]       |
+----------------------------------+

allを変更した場合 one 、次のようになります：

SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'one', 'Dog');

結果：

+----------------------------------+
| JSON_SEARCH(@json, 'one', "Dog") |
+----------------------------------+
| "$[0].type"                      |
+----------------------------------+

1つのパスのみが返されます。

パスを指定

ドキュメント内で検索するパスを指定する例を次に示します。

SET @json = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "NZ Dog Award" : "Top Dog", 
                "New York Marathon" : "Fastest Animal", 
                "Sumo 2021" : "Biggest Dog"
            }
        }
    }
';
SELECT JSON_SEARCH(
    @json, 
    'all',
    '%dog%',
    NULL,
    '$.details.awards'
    ) AS Result;

結果：

+-----------------------------------------------------------------+
| Result                                                          |
+-----------------------------------------------------------------+
| ["$.details.awards.NZ Dog Award", "$.details.awards.Sumo 2021"] |
+-----------------------------------------------------------------+

この場合、文字列dog 実際にはドキュメント内で3回発生しますが、指定されたパスの下では2回だけ発生します。

また、NULLを使用しましたエスケープ文字引数の場合、デフォルトのエスケープ文字が使用されます。これはバックスラッシュ（\）です。）。

デフォルトのエスケープ文字

デフォルトでは、エスケープ文字は円記号（\）です。）。

例：

SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my\%pwd') AS "Escaped";

結果：

+--------------------------------------+------------+
| Not Escaped                          | Escaped    |
+--------------------------------------+------------+
| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |
+--------------------------------------+------------+

パーセント記号（% ）は、任意の数の文字に一致するワイルドカード文字です。したがって、エスケープしないと、パーセント記号ではない文字を含め、任意の数の文字と一致します。

ただし、パーセント記号をエスケープ文字でエスケープすると、その場所にパーセント記号が1つだけある場合にのみ一致します。

上記の結果はこれを反映しています。

カスタムエスケープ文字を指定する

必要に応じて、カスタムエスケープ文字を指定できます。これを行うには、4番目の引数として指定します。

例：

SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd', '!') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my!%pwd', '!') AS "Escaped";

結果：

+--------------------------------------+------------+
| Not Escaped                          | Escaped    |
+--------------------------------------+------------+
| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |
+--------------------------------------+------------+

したがって、前の例と同じ結果が得られます。唯一の違いは、別のエスケープ文字を指定したことです。この場合、感嘆符（!）を指定しました）はエスケープ文字です。

ヌル引数

検索文字列、検索文字列、またはパス引数のいずれかがNULLの場合、結果はNULLです：

SELECT 
    JSON_SEARCH(null, 'all', 's', '', '$') AS a,
    JSON_SEARCH('{"a":1}', 'all', null, '', '$') AS b,
    JSON_SEARCH('{"a":1}', 'all', 's', '', null) AS c;

結果：

+------+------+------+
| a    | b    | c    |
+------+------+------+
| NULL | NULL | NULL |
+------+------+------+

パラメータカウントが正しくありません

引数を指定しないとエラーが発生します：

SELECT JSON_SEARCH();

結果：

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_SEARCH'

提供する引数が少なすぎる場合も同じです：

SELECT JSON_SEARCH('{"a":1}', 'all');

結果：

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_SEARCH'