SQL/JSONファンクションJSON

20 SQL/JSONファンクションJSON_VALUE

SQL/JSONファンクションjson_valueは、JSONデータを選択し、SQLスカラーやユーザー定義のSQLオブジェクト型またはSQLコレクション型(VARRAY、ネストした表)のインスタンスを返します。

json_valueが単一のスカラーJSON値を対象にする場合、対応するスカラーSQL値を返します。返されるスカラー値のSQLデータ型を指定できます。デフォルトは、VARCHAR2(4000)です。

json_valueの対象がJSONスカラー値nullである場合は、SQLの戻り型がどれであってもSQLのNULLが返されます。(たとえば、デフォルトの戻り型VARCHAR2(4000)の場合に、SQL文字列'null'は返されません。)つまり、特に、json_valueを使用してJSON値nullと値が存在しないことの区別はできません。この場合、SQLのNULLは両方の事例を表します。
json_valueがJSON配列を対象にしている場合、SQLコレクション型(VARRAYまたはネストした表)を戻り型として指定すると、json_valueはそのコレクション型のインスタンスを返します。

対象のJSON配列の要素は、返されたコレクション型インスタンスの要素を提供します。スカラーのJSON配列要素は、返されたコレクション・インスタンスにスカラーのSQL値を生成します(前を参照)。オブジェクトであるJSON配列要素(次を参照)または配列は再帰的に処理されます。
json_valueがJSONオブジェクトを対象にしている場合、ユーザー定義のSQLオブジェクト型を戻り型として指定すると、json_valueはそのオブジェクト型のインスタンスを返します。

対象のJSONオブジェクトのフィールド値は、返されたオブジェクト型インスタンスの属性値を提供します。対象のJSONオブジェクトのフィールド名は、SQLオブジェクト属性のSQL名と比較されます。スカラー・フィールド値は、返されたオブジェクト型インスタンスにスカラーのSQL値を生成します(前を参照)。配列であるフィールド値(前を参照)またはオブジェクトが再帰的に処理されます。

最終的に、これはスカラーのSQLオブジェクト属性の名前と比較されるスカラー値を持つJSONフィールドの名前です。大/小文字を区別して名前が正確に一致しない場合は、問合せコンパイル時に不一致エラーが処理されます。

また、json_valueを使用して、JSONデータで使用する関数ベースのBツリー索引を作成することもできます。JSONデータの索引を参照してください。

ファンクションjson_valueには、必須の引数が2つあり、いくつかのオプションの句を受け入れます。

json_valueの最初の引数は、スカラーのSQLデータ型のインスタンスを戻すSQL式です(つまり、オブジェクト・データ型でもコレクション・データ型でもありません)。json_valueから返されるスカラー値のデータ型は、BINARY_DOUBLE、BINARY_FLOAT、BOOLEAN、CHAR、CLOB、DATE、INTERVAL DAY TO SECOND、INTERVAL YEAR TO MONTH、NCHAR、NCLOB、NVARCHAR2、NUMBER、RAW^脚注1、SDO_GEOMETRY、TIMESTAMP、TIMESTAMP WITH TIME ZONE、VARCHAR2およびVECTORのいずれかにすることができます。

RETURNINGの型がVECTORの場合、動作は対象となる入力データに応じて次のように異なります:

対象となるデータがJSONスカラー・ベクター値の場合、その値はVECTORインスタンスとして返されます。
対象となるデータが数値要素のみを含むJSON配列の場合、配列はVECTORインスタンスに変換され、それが返されます。
対象となるデータがその他のJSON値(つまり、非ベクター・スカラー、数値以外の要素を含む配列、またはオブジェクト)である場合、エラーが発生します。

ノート:

一般に、JSON文字列からNVARCHAR2、NCLOBおよびNCHAR以外の型のSQL文字データを生成し、その変換先データ型の文字セットがUnicodeベースでない場合、その変換において、そのSQL型の文字セットで表せない文字については文字セット変換で情報の損失が発生する可能性があります。

最初の引数は、適切にキャストされた表またはビューの列の値、PL/SQL変数、バインド変数のいずれかになります。SQL式の評価の結果は、パス式を評価するためのコンテキスト項目として使用されます。

json_valueの2番目の引数はSQL/JSONパス式であり、その後にはオプションの句RETURNING、PASSING、ON ERROR、ON EMPTYおよびON MISMATCHが続きます。このパス式では単一のスカラー値を対象とする必要があり、そうでない場合、エラーが発生します。

デフォルトのエラー処理動作はNULL ON ERRORであり、これは、エラーが発生しても値が戻されない、つまり、エラーが発生しないことを意味します。特に、パス式が配列などの非スカラー値を対象としている場合、デフォルトではエラーは発生しません。エラーが発生するようにするには、ERROR ON ERRORを使用します。

パス式配列ステップで、指定されている位置が1つのみである場合、データと照合されます。それ以外の場合は一致しません(デフォルトではNULLが返されます)。

ノート:

特定のJSONオブジェクト内のフィールド名は、それぞれが一意である必要はありません。同じフィールド名を繰り返すことができます。Oracle Databaseで行われるストリーム評価では、特定のフィールド名を持つ1つのオブジェクト・メンバーのみが常に使用され、同じフィールド名を持つ他のメンバーは無視されます。このような複数のメンバーのうちどれが使用されるかは指定されていません。

JSONオブジェクトの一意フィールドと重複フィールドを参照してください。

_________________________________________________________