SQLファンクションおよび条件のエラー句

18.4 SQLファンクションおよび条件のエラー句

JSONデータに対する一部のSQL問合せファンクションおよび条件は、オプションでエラー句を受け入れます。この句によって、ファンクションまたは条件によって発生した実行時エラーの処理方法を指定します。この句についてと、デフォルト動作(エラー句なし)についてまとめます。

デフォルトでは、JSON用のSQLファンクションおよび条件により、実行時エラーの発生が回避されます。たとえば、JSONデータが構文的に無効な場合、json_existsおよびjson_equalはfalseを戻し、json_valueはNULLを戻します。

ただし、場合によってはデフォルト動作をオーバーライドするエラー句を指定することもできます。指定できるエラー処理は異なりますが、エラー処理を指定可能なJSON用の各SQLファンクションおよび条件では、少なくともエラー発生のERROR ON ERROR動作がサポートされます。

オプションのエラー句は次の形式を使用できます。

ERROR ON ERROR - エラーを発生させます(特別な処理なし)。
NULL ON ERROR - エラーを発生させるかわりにNULLを戻します。

json_existsに使用できません。
FALSE ON ERROR - エラーを発生させるかわりにfalseを戻します。

デフォルトであるjson_existsおよびjson_equalにのみ使用できます。
TRUE ON ERROR - エラーを発生させるかわりにtrueを戻します。

json_existsおよびjson_equalにのみ使用できます。
EMPTY OBJECT ON ERROR - エラーを発生させるかわりに空のオブジェクト({})を戻します。

json_queryにのみ使用できます。
EMPTY ARRAY ON ERROR - エラーを発生させるかわりに空の配列([])を戻します。

json_queryにのみ使用できます。
EMPTY ON ERROR – EMPTY ARRAY ON ERRORと同じ。
DEFAULT 'literal_return_value' ON ERROR - エラーを発生させるかわりに指定した値を戻します。値は、問合せのコンパイル時に定数である必要があります。

使用不可:
- json_exists、json_equal、json_serialize、json_scalar、json_mergepatch、またはjson_exists動作が含まれたjson_table列値句の場合
- json_query、またはjson_query動作を含むjson_table列値句
- json_tableの低レベル・エラー処理
- SDO_GEOMETRYがjson_valueのRETURNING句データ・タイプとして、またはjson_table列データ・タイプとして指定されている場合

デフォルト動作は、NULL ON ERRORですが、条件json_existsおよびjson_equalの場合は該当しません。

ただし、パラメータJSON_BEHAVIORを使用して、特定のデータベース・セッションのデフォルトの動作を変更できます。これは、デフォルトの動作としてNULL ON ERRORが指定されたSQL演算子のエラー・ハンドラにのみ影響します。つまり、キーワードEXISTSを使用する列(json_existsセマンティクスを持つ列)のSQL条件json_existsおよびjson_equalまたはSQLファンクションjson_tableには影響しません。影響するのは、EXISTSのないファンクションjson_value、json_queryおよびjson_tableのみです。

JSON_BEHAVIORに指定する値は、次のように、現在のセッションに使用するデフォルトの動作を指定します:

ON_ERROR:ERROR — ERROR ON ERROR動作がセッションのデフォルトです。
ON_ERROR:NULL — NULL ON ERROR動作がセッションのデフォルトです。

一般的なユースケースは、デバッグの目的でパラメータをON_ERROR:ERRORに設定し、パス式の評価で問合せされたJSONデータで一致する値が見つからない場合にエラーを発生させることです。例18-1に、これを示します。

ノート:

json_tableのエラー処理には2つのレベルがありますが、これらは、パス式の2つのレベルである行と列に対応しています。存在する場合、列のエラー・ハンドラにより、行レベルのエラー処理がオーバーライドされます。両レベルのデフォルトのエラー・ハンドラはNULL ON ERRORです。

ノート:

欠落フィールドの照合を試行したことによるエラーの場合、ON EMPTY句はON ERRORで指定された動作より優先されます。

ノート:

ON ERROR句は、構文的に正しいSQL/JSONパス式がJSONデータに対して照合されたときに発生する実行時エラーに対してのみ有効です。構文的に正しくないパス式の場合、コンパイル時エラーが発生します。これは、ON ERROR句によっては処理されません。

例18-1 パラメータJSON_BEHAVIORを使用したERROR ON ERROR動作の指定

デフォルトでは、json_valueはエラー時にNULLを返し、エラーのある問合せに気付きにくくなる可能性があります。この問合せは、パス式$.aが単一のスカラー値と一致せず、複数の値1および2と一致するため、NULLを返します。

SELECT json_value('[{a:1},{a:2}]', '$.a');

このコードは、現在のセッションのパラメータJSON_BEHAVIORの値を変更するので、同じエラーが検出されるとNULLを返すのではなく、実際にエラーが発生します:

ALTER SESSION SET JSON_BEHAVIOR="ON_ERROR:ERROR"

SELECT json_value('[{a:1},{a:2}]', '$.a');

ORA-40470: JSON query '$.a' evaluated to multiple values.

このコードは、パラメータをデフォルト値にリセットします:

ALTER SESSION SET JSON_BEHAVIOR="ON_ERROR:NULL"