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