JSON_QUERY
構文
(JSON_basic_path_expression
: Oracle Database JSON開発者ガイドを参照)
JSON_query_returning_clause::=
JSON_query_return_type::=
JSON_query_wrapper_clause::=
JSON_query_on_error_clause::=
JSON_query_on_empty_clause::=
目的
JSON_QUERY
は、JSONデータから1つ以上の値を選択して返し、それらの値を返します。JSON_QUERY
を使用してJSONドキュメントのフラグメントを取得できます。
関連項目:
-
JSON_QUERY
によって戻される文字値に割り当てる照合を定義する照合導出ルールは、『Oracle Databaseグローバリゼーション・サポート・ガイド』の付録Cを参照してください。
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 -------------------------------------------------------------------------------- []