JSON_QUERY

構文

json_query.epsの説明が続きます
図json_query.epsの説明

(JSON_basic_path_expression: Oracle Database JSON開発者ガイドを参照)

JSON_query_returning_clause::=

json_query_returning_clause.epsの説明が続きます
図json_query_returning_clause.epsの説明

JSON_query_return_type::=

json_query_return_type.epsの説明が続きます
図json_query_return_type.epsの説明

JSON_query_wrapper_clause::=

json_query_wrapper_clause.epsの説明が続きます
図json_query_wrapper_clause.epsの説明

JSON_query_on_error_clause::=

json_query_on_error_clause.epsの説明が続きます
図json_query_on_error_clause.epsの説明

JSON_query_on_empty_clause::=

json_query_on_empty_clause.epsの説明が続きます
図json_query_on_empty_clause.epsの説明

目的

JSON_QUERYは、JSONデータから1つ以上の値を選択して返し、それらの値を返します。JSON_QUERYを使用してJSONドキュメントのフラグメントを取得できます。

関連項目:

expr

exprを使用して、問い合せるJSONデータを指定します。

exprは、SQLデータ型のインスタンス(JSON、VARCHAR2、CLOBまたはBLOBのいずれか)を返すSQL式です。これは、表またはビューの列の値、PL/SQL変数、または適切にキャストされたバインド変数のいずれかになります。

exprがNULLの場合はNULLを戻します。

exprが厳密なまたは緩い構文を使用した整形式のJSONデータのテキスト・リテラルでない場合、このファンクションはデフォルトでnullを戻します。JSON_query_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_query_on_error_clauseを参照してください。

FORMAT JSON

exprがデータ・タイプBLOBの列の場合、FORMAT JSONを指定する必要があります。

JSON_basic_path_expression

この句を使用して、SQL/JSONパス式を指定します。このファンクションはパス式を使用してexprを評価し、パス式と一致する(パス式を満たす)1つ以上のJSON値を確認します。パス式はテキスト・リテラルである必要があります。JSON_basic_path_expressionのセマンティクスの詳細は、Oracle Database JSON開発者ガイドを参照してください。

JSON_query_returning_clause

この句を使用して、このファンクションで戻される文字列のデータ型および書式を指定します。

RETURNING

RETURNING句を使用して、返されるインスタンスのデータ型(VARCHAR2、CLOBまたはBLOBのいずれか)を指定できます。

デフォルトの戻り型は、すべての入力データ型でVARCHAR2(4000)です。

SQLでVARCHAR2データ型を指定する場合、サイズを指定する必要があります。ただし、この句はサイズを省略できます。この場合、JSON_QUERYはVARCHAR2(4000)型の文字列を戻します。

詳細は、「VARCHAR2データ型」を参照してください。

データ型が戻り文字列を保持できる十分な大きさでない場合、このファンクションはデフォルトでnullを戻します。JSON_query_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_query_on_error_clauseを参照してください。

PRETTY

改行文字とインデントを挿入して戻り文字列を出力整形するには、PRETTYを指定します。

ASCII

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

JSON_query_wrapper_clause

この句を使用して、このファンクションが配列ラッパーのパス式と一致する値をラップするかどうか、つまり大カッコ([])で値のシーケンスを囲むかどうかを制御します。

  • WITHOUT WRAPPERを指定して、配列ラッパーを省略します。パス式が単一のJSONオブジェクトまたはJSON配列と一致する場合のみ、この句を指定できます。これはデフォルトです。

  • WITH WRAPPERを指定して、配列ラッパーを含めます。パス式が単一のスカラー値(JSONオブジェクトまたはJSON配列でない値)または任意の型の複数の値と一致する場合、この句を指定する必要があります。

  • WITH UNCONDITIONAL WRAPPER句の指定は、WITH WRAPPER句の指定と同じです。UNCONDITIONALキーワードはセマンティクスを明確にするためのものです。

  • パス式が単一のスカラー値または任意の型の複数の値と一致する場合のみ配列ラッパーに含めるには、WITH CONDITIONAL WRAPPERを指定します。パス式が単一のJSONオブジェクトまたはJSON配列と一致する場合、配列ラッパーが省略されます。

ARRAYキーワードはオプションで、意味を明確化するために使用されます。

ファンクションが単一のスカラー値または任意の型の複数の値を戻し、WITH [UNCONDITIONAL | CONDITIONAL] WRAPPERを指定しない場合、ファンクションはデフォルトでnullを戻します。JSON_query_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_query_on_error_clauseを参照してください。

JSON_query_on_error_clause

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

  • exprが厳密なまたは緩いJSON構文を使用した整形式のJSONデータではありません。

  • SQL/JSONパス式を使用してJSONデータを評価した場合に一致が見つかりません。JSON_query_on_empty_clauseを指定して、このタイプのエラーに対する動作を上書きできます。

  • 戻り値のデータ型が戻り文字列を保持する十分な大きさではありません。

  • ファンクションが単一のスカラー値または任意の型の複数の値と一致し、WITH [UNCONDITIONAL | CONDITIONAL] WRAPPER句が指定されていません。

次の句を指定できます。

  • NULL ON ERROR - エラーが発生した場合にnullを戻します。これはデフォルトです。

  • ERROR ON ERROR - エラーが発生した場合に適切なOracleエラーを戻します。

  • EMPTY ON ERROR - この句を指定することは、EMPTY ARRAY ON ERRORを指定することと同じです。

  • EMPTY ARRAY ON ERROR - エラーが発生した場合に空のJSON配列([])を戻します。

  • EMPTY OBJECT ON ERROR - エラーが発生した場合に空のJSONオブジェクト({})を戻します。

JSON_query_on_empty_clause

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

次の句を指定できます。

  • NULL ON EMPTY - 一致が見つからない場合にNULLを戻します。

  • ERROR ON EMPTY - 一致が見つからない場合に適切なOracleエラーを戻します。

  • EMPTY ON EMPTY - この句を指定することは、EMPTY ARRAY ON EMPTYを指定することと同じです。

  • EMPTY ARRAY ON EMPTY - 一致が見つからない場合に空のJSON配列([])を戻します。

  • EMPTY OBJECT ON EMPTY - 一致が見つからない場合に空のJSONオブジェクト({})を戻します。

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

例

次の問合せは、JSONデータの指定された文字列であるコンテキスト項目を戻します。パス式は、配列ラッパーを必要としない単一のJSONオブジェクトと一致します。JSONデータは戻り値で厳密なJSON構文に変換されません。つまり、オブジェクト・プロパティ名が二重引用符で囲まれます。

SELECT JSON_QUERY('{a:100, b:200, c:300}', '$') AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
{"a":100,"b":200,"c":300}

次の問合せは、プロパティ名aのメンバーの値を戻します。パス式は、配列ラッパーで囲む必要があるスカラー値と一致します。このため、WITH WRAPPER句が指定されます。 

SELECT JSON_QUERY('{a:100, b:200, c:300}', '$.a' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[100]

次の問合せは、すべてのオブジェクト・メンバーの値を戻します。パス式は、配列ラッパーで囲む必要がある複数の値と一致します。このため、WITH WRAPPER句が指定されます。 

SELECT JSON_QUERY('{a:100, b:200, c:300}', '$.*' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[100,200,300]

次の問合せは、JSONデータの指定された文字列であるコンテキスト項目を戻します。パス式は、配列ラッパーを必要としない単一のJSON配列と一致します。

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

VALUE
--------------------------------------------------------------------------------
[0,1,2,3,4]

WITH WRAPPER句が指定されている点を除いて、次の問合せは前の問合せと似ています。このため、JSON配列が配列ラッパーでラップされます。 

SELECT JSON_QUERY('[0,1,2,3,4]', '$' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[[0,1,2,3,4]]

次の問合せは、JSON配列のすべての要素を戻します。パス式は、配列ラッパーで囲む必要がある複数の値と一致します。このため、WITH WRAPPER句が指定されます。 

SELECT JSON_QUERY('[0,1,2,3,4]', '$[*]' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[0,1,2,3,4]

次の問合せは、JSON配列の索引0、3から5、7の要素を戻します。パス式は、配列ラッパーで囲む必要がある複数の値と一致します。このため、WITH WRAPPER句が指定されます。 

SELECT JSON_QUERY('[0,1,2,3,4,5,6,7,8]', '$[0, 3 to 5, 7]' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[0,3,4,5,7]

次の問合せは、JSON配列の4番目の要素を戻します。パス式は、配列ラッパーで囲む必要があるスカラー値と一致します。このため、WITH WRAPPER句が指定されます。 

SELECT JSON_QUERY('[0,1,2,3,4]', '$[3]' WITH WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[3]

次の問合せは、JSON配列の最初の要素を戻します。WITH CONDITIONAL WRAPPER句が指定され、パス式が単一のJSONオブジェクトと一致します。このため、戻される値は配列でラップされます。JSONデータは戻り値で厳密なJSON構文に変換されません。つまり、オブジェクト・プロパティ名が二重引用符で囲まれます。 

SELECT JSON_QUERY('[{a:100},{b:200},{c:300}]', '$[0]'
       WITH CONDITIONAL WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
{"a":100}

次の問合せは、JSON配列のすべての要素を戻します。WITH CONDITIONAL WRAPPER句が指定され、パス式が複数のJSONオブジェクトと一致します。このため、戻される値は配列でラップされます。 

SELECT JSON_QUERY('[{"a":100},{"b":200},{"c":300}]', '$[*]'
       WITH CONDITIONAL WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[{"a":100},{"b":200},{"c":300}]

戻される値のデータ型がVARCHAR2(100)である点を除いて、次の問合せは前の問合せと似ています。 

SELECT JSON_QUERY('[{"a":100},{"b":200},{"c":300}]', '$[*]'
       RETURNING VARCHAR2(100) WITH CONDITIONAL WRAPPER) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[{"a":100},{"b":200},{"c":300}]

次の問合せは、JSON配列の4番目の要素を戻します。ただし、指定されたJSON配列に結果としてエラーとなる4番目の要素は含まれません。EMPTY ON ERROR句が指定されます。このため、問合せは空のJSON配列を戻します。 

SELECT JSON_QUERY('[{"a":100},{"b":200},{"c":300}]', '$[3]'
       EMPTY ON ERROR) AS value
  FROM DUAL;

VALUE
--------------------------------------------------------------------------------
[]