JSON_VALUE

説明

この関数は、指定されたパスからJSONドキュメント内の値を抽出し、抽出した値を返します。また、必要なデータ型に変換することもできます。

構文

JSON_VALUE(json_doc, path [RETURNING type] [on_empty] [on_error])

on_empty:
    {NULL | ERROR | DEFAULT value} ON EMPTY

on_error:
    {NULL | ERROR | DEFAULT value} ON ERROR

説明

パラメータの説明

関連するパラメータの説明は以下の通りです：

• json_doc パラメータは、有効なJSONドキュメントを指定します。

• path パラメータは、ドキュメント内の特定の位置を示すJSONパスであり、文字列である必要があります。

• type パラメータは、次のデータ型をサポートしています：

  • FLOAT

  • DOUBLE

  • DECIMAL

  • SIGNED

  • UNSIGNED

  • DATE

  • TIME

  • DATETIME

  • YEAR (YEAR(1) および YEAR(2) はサポートされていません)

  • CHAR

  • JSON

• RETURNING 句を使用しない場合、この関数の戻り値の型は VARCHAR(512) です。 戻り値の型に文字セットを指定しない場合、JSON_VALUE() はutf8mb4とバイナリソート規則を使用し、大文字と小文字を区別します。 結果の文字セットとしてutf8mb4を指定した場合、サーバーはこの文字セットのデフォルトのソート規則を使用し、大文字と小文字を区別しません。

• 指定されたパスでデータが見つからない場合、on_empty 句は JSON_VALUE() の動作を指定するために使用されます。この句の値は以下のとおりです：

  • NULL ON EMPTY：JSON_VALUE() は NULL を返します。これは ON EMPTY のデフォルトの動作です。

  • DEFAULT value ON EMPTY'：提供された value 値を返します。この値の型は、返り値の型と一致している必要があります。

  • ERROR ON EMPTY：関数はエラーをスローします。

• エラー発生時、on_error の値は以下のとおりです：

  • NULL ON ERROR：JSON_VALUE() は NULL を返します。ON ERROR 句を使用しない場合、これがデフォルトの動作です。

  • DEFAULT value ON ERROR：提供された value 値を返します。この値の型は、返り値の型と一致している必要があります。

  • ERROR ON ERROR：エラーをスローします。

  注意

  ON EMPTY の位置（使用する場合）は、すべての ON ERROR 句の前でなければなりません。エラーの順序が誤ると構文エラーが発生します。

エラー処理

通常、JSON_VALUE() はすべてのJSON入力（ドキュメントとパス）の有効性をチェックします。いずれかが無効である場合、SQLエラーがスローされ、ON ERROR 句はトリガーされません。

次のいずれかのイベントが発生した場合、ON ERROR がトリガーされます：

• オブジェクトまたは配列を抽出しようとした際に、入力パスがJSONドキュメント内で複数のパスに解釈された場合。

• 変換エラー。例えば、'asdf' を UNSIGNED 値に変換しようとした場合。

• データの切り捨て。

NULL ON ERROR または DEFAULT ... ON ERROR を指定していても、変換エラーは常にアラートをトリガーします。

ソースJSONドキュメント（json_doc）が指定された位置（path）にデータを含まない場合、ON EMPTY 句がトリガーされます。

例

obclient> SELECT JSON_VALUE('{"fname": "Smith", "lname": "Will"}', '$.fname');
+--------------------------------------------------------------+
| JSON_VALUE('{"fname": "Smith", "lname": "Will"}', '$.fname') |
+--------------------------------------------------------------+
| Smith                                                        |
+--------------------------------------------------------------+
1 row in set

obclient> SELECT JSON_VALUE('{"item": "shoes", "price": "69.73"}', '$.price'
     RETURNING DECIMAL(4,2)) AS price;
+-------+
| price |
+-------+
| 69.73 |
+-------+
1 row in set