JSON_VALUE

構文

図json_value.epsの説明

JSON_basic_path_expression::=

(JSON_basic_path_expression: SQL/JSONパス式を参照)

JSON_value_returning_clause::=

図json_value_returning_clause.epsの説明

JSON_value_return_type::=

図json_value_return_type.epsの説明

JSON_value_return_object_instance ::=

図json_value_return_object_instance.epsの説明

JSON_value_mapper_clause ::=

図json_value_mapper_clause.epsの説明

JSON_value_on_error_clause::=

図json_value_on_error_clause.epsの説明

JSON_value_on_empty_clause::=

図json_value_on_empty_clause.epsの説明

JSON_value_on_mismatch_clause::=

図json_value_on_mismatch_clause.epsの説明

目的

SQL/JSONファンクションJSON_VALUEは、JSONデータの指定されたスカラーJSON値を確認し、SQL値として戻します。

関連項目:

概念の理解には、SQL/JSON Function JSON_VALUE。
前述のデータ型の詳細は、「データ型」を参照してください。
データ型が戻り値を保持できる十分な大きさでない場合、このファンクションはデフォルトでnullを戻します。JSON_value_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_value_on_error_clauseを参照してください。

ASCII

標準のASCII Unicodeエスケープ・シーケンスを使用して戻り値の非ASCII Unicode文字を自動的にエスケープするには、ASCIIを指定します。

JSON_value_on_error_clause

この句を使用して、次のエラーが発生した場合にこのファンクションで戻される値を指定します。

exprが厳密なまたは緩いJSON構文を使用した整形式のJSONデータではありません。
JSONデータがSQL/JSONパス式を使用して評価される場合に非スカラー値が見つかります。
SQL/JSONパス式を使用してJSONデータを評価した場合に一致が見つかりません。JSON_value_on_empty_clauseを指定して、このタイプのエラーに対する動作を上書きできます。
戻り値のデータ型が戻り値を保持する十分な大きさではありません。

次の句を指定できます。

NULL ON ERROR - エラーが発生した場合にnullを戻します。これはデフォルトです。
ERROR ON ERROR - エラーが発生した場合に適切なOracleエラーを戻します。
DEFAULT literal ON ERROR - エラーが発生した場合にliteralを戻します。literalのデータ型は、このファンクションにより戻される値のデータ型と一致する必要があります。

JSON_value_on_empty_clause

この句を使用して、JSONデータがSQL/JSONパス式を使用して評価されるときに一致が見つからない場合にこのファンクションで戻される値を指定します。この句により、JSON_value_on_error_clauseで指定された結果とは異なる、このタイプのエラーに対する結果を指定できます。

次の句を指定できます。

NULL ON EMPTY - 一致が見つからない場合にNULLを戻します。
ERROR ON EMPTY - 一致が見つからない場合に適切なOracleエラーを戻します。
DEFAULT literal ON EMPTY - 一致が見つからない場合にliteralを戻します。literalのデータ型は、このファンクションにより戻される値のデータ型と一致する必要があります。

この句を省略すると、JSON_value_on_error_clauseによって、一致が見つからない場合に戻される値が決まります。

JSON_value_on_mismatch_clause

JSON_value_on_mismatch_clauseには、一般と個別の2つの使用方法があります。

追加データ、欠落データ、入力エラーなどのエラー・ケースすべてに適用する場合は一般の使用方法です。

ケースごとに異なるON MISMATCH句を指定するのが、個別の使用方法です。たとえば:

IGNORE ON MISMATCH (EXTRA DATA)

ERROR ON MISMATCH ( MISSING DATA, TYPE ERROR)

例

次の問合せは、プロパティ名aのメンバーの値を戻します。RETURNING句が指定されていないため、値がVARCHAR2(4000)データ型として戻されます。

SELECT JSON_VALUE('{a:100}', '$.a') AS value
  FROM DUAL;

VALUE
-----
100

次の問合せは、プロパティ名aのメンバーの値を戻します。RETURNING NUMBER句が指定されているため、値がNUMBERデータ型として戻されます。

SELECT JSON_VALUE('{a:100}', '$.a' RETURNING NUMBER) AS value
  FROM DUAL;

     VALUE
----------
       100

次の問合せは、プロパティ名aを使用したメンバーの値にあるプロパティ名bを使用したメンバーの値を戻します。

SELECT JSON_VALUE('{a:{b:100}}', '$.a.b') AS value
  FROM DUAL;

VALUE
-----
100

次の問合せは、任意のオブジェクトのプロパティ名dのメンバーの値を戻します。

SELECT JSON_VALUE('{a:{b:100}, c:{d:200}, e:{f:300}}', '$.*.d') AS value
  FROM DUAL;

VALUE
-----
200

次の問合せは、配列の最初の要素の値を戻します。

SELECT JSON_VALUE('[0, 1, 2, 3]', '$[0]') AS value
  FROM DUAL;

VALUE
-----
0

次の問合せは、配列の3番目の要素の値を戻します。配列は、プロパティ名aのメンバーの値です。

SELECT JSON_VALUE('{a:[5, 10, 15, 20]}', '$.a[2]') AS value
  FROM DUAL;

VALUE
-----
15

次の問合せは、配列の2番目のオブジェクトのプロパティ名aのメンバーの値を戻します。

SELECT JSON_VALUE('[{a:100}, {a:200}, {a:300}]', '$[1].a') AS value
  FROM DUAL;

VALUE
-----
200

次の問合せは、配列の任意のオブジェクトのプロパティ名cのメンバーの値を戻します。

SELECT JSON_VALUE('[{a:100}, {b:200}, {c:300}]', '$[*].c') AS value
  FROM DUAL;

VALUE
-----
300

次の問合せは、プロパティ名lastnameのメンバーの値を戻そうとします。ただし、そのメンバーは指定されたJSONデータに存在しないため、一致は見つかりません。ON ERROR句が指定されていないため、この文はデフォルトのNULL ON ERRORを使用し、nullを戻します。

SELECT JSON_VALUE('{firstname:"John"}', '$.lastname') AS "Last Name"
  FROM DUAL;

Last Name
---------

指定されたJSONに存在しないプロパティ名lastnameのメンバーの値を戻そうとするため、次の問合せはエラーになります。ON ERROR句が指定されているため、この文は指定されたテキスト・リテラルを戻します。

SELECT JSON_VALUE('{firstname:"John"}', '$.lastname'
                  DEFAULT 'No last name found' ON ERROR) AS "Last Name"
  FROM DUAL;

Last Name
---------
No last name found