| Oracle® Database SQL言語リファレンス 12cリリース1 (12.1) B71278-13 |
|
 前 |
 次 |
|
注意: JSON_QUERYファンクションは、Oracle Database 12cリリース1(12.1.0.2)から使用可能です。 |
構文
object_step::=
array_step::=
JSON_query_returning_clause::=
JSON_query_return_type::=
用途
JSON_QUERYは、JSONデータの1つ以上の指定されたJSON値を確認し、文字列の値を戻します。
expr
この句は、評価の対象となるJSONデータを指定するために使用します。exprでは、テキスト・リテラルを評価する式を指定します。exprが列である場合、列のデータ型はVARCHAR2、CLOBまたはBLOBのいずれかである必要があります。exprがNULLの場合はNULLを戻します。
exprが厳密なまたは緩い構文を使用した整形式のJSONデータのテキスト・リテラルでない場合、このファンクションはデフォルトでnullを戻します。JSON_query_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_query_on_error_clauseを参照してください。
FORMAT JSON
exprがデータ・タイプBLOBの列の場合、FORMAT JSONを指定する必要があります。
JSON_path_expression
この句を使用して、JSONパス式を指定します。このファンクションはパス式を使用してexprを評価し、パス式と一致する(パス式を満たす)1つ以上のJSON値を確認します。パス式はテキスト・リテラルである必要があります。
パス式は、exprで指定される式であるコンテキスト項目を表すドル記号($)から始める必要があります。ドル記号の後、オブジェクト・ステップや配列ステップの可能性があるゼロ以上のステップが続きます。
このファンクションは、コンテキスト項目に対するパス式の最初のステップと一致するかどうかを試行します。最初のステップが一致した場合、このファンクションは最初のステップと一致したJSON値に対して2番目のステップと一致するかどうかを試行します。2番目のステップが一致した場合、このファンクションは2番目のステップと一致したJSON値に対して3番目のステップと一致するかどうかを試行し、以降も同様に続きます。このファンクションは、文字列のカンマ区切りのシーケンス値と一致する値を戻します。シーケンスの順序は非決定的です。元のJSONデータが厳密なまたは緩いJSON構文を使用しているかどうかに関係なく、すべての値が厳密なJSON構文を使用して戻されます。ドル記号とゼロのステップで構成されるパス式('$')は、全体のコンテキスト項目と一致します。
JSON_query_returning_clauseを指定して、戻り文字列のデータ型および書式を制御できます。JSON_query_returning_clauseを参照してください。
複数の値がパス式と一致するか、1つのスカラー値がパス式と一致する場合のみ、配列ラッパーの値をラップする必要があります。JSON_query_wrapper_clauseを参照してください。
パス式のいずれかのステップが一致しなかった場合、このファンクションはデフォルトでnullを戻します。JSON_query_on_error_clauseを使用して、このデフォルトの動作をオーバーライドできます。JSON_query_on_error_clauseを参照してください。
object_step この句を使用して、オブジェクト・ステップを指定します。
simple_nameまたはcomplex_nameを使用して、プロパティ名を指定します。このプロパティ名のメンバーが評価されるJSONオブジェクトにある場合、そのメンバーのプロパティ値が一致するオブジェクト・ステップになります。それ以外の場合、一致しないオブジェクト・ステップになります。両方のタイプの名前は大/小文字を区別します。このため、アルファベットの大/小文字がオブジェクト・ステップおよびJSONデータで一致する場合のみ、一致の結果になります。
simple_nameは、英数字のみで構成され、最初の文字はアルファベット文字にする必要があります。complex_nameは、英数字のみで構成され、最初の文字は英数字にする必要があります。complex_nameは、二重引用符で囲む必要があります。
ワイルド・カード記号であるアスタリスク(*)を使用して、すべてのプロパティ名を指定します。評価されるJSONオブジェクトに少なくとも1つのメンバーが含まれる場合、オブジェクト・ステップはすべてのメンバーの値と一致する結果になります。それ以外の場合、一致しないオブジェクト・ステップになります。
オブジェクト・ステップをJSON配列に適用すると、配列が暗黙的にアンラップされ、配列の要素がオブジェクト・ステップを使用して評価されます。これは、JSONパス式解除といいます。詳細は、『Oracle XML DB開発者ガイド』を参照してください。
評価されるJSONデータがJSONオブジェクトでない場合、オブジェクト・ステップは一致しません。
array_step この句を使用して、配列ステップを指定します。
integerを使用して、JSON配列の索引integerの要素を指定します。integer TO integerを使用して、2つのinteger索引値の間(これらの値を含む)の要素の範囲を指定します。指定された要素が評価されるJSON配列にある場合、配列ステップはそれらの要素と一致する結果になります。それ以外の場合、一致しない配列ステップになります。JSON配列の最初の要素は索引0です。
ワイルド・カード記号であるアスタリスク(*)を使用して、JSON配列のすべての要素を指定します。評価されるJSON配列に少なくとも1つの要素が含まれる場合、JSON配列のすべての要素が一致する配列ステップになります。それ以外の場合、一致しない配列ステップになります。
評価されるJSONデータがJSON配列でない場合、データが暗黙的に配列にラップされ、配列ステップを使用して評価されます。これは、JSONパス式解除といいます。詳細は、『Oracle XML DB開発者ガイド』を参照してください。
JSON_query_returning_clause
この句を使用して、このファンクションで戻される文字列のデータ型および書式を指定します。
RETURNING RETURNING句を使用して、文字列のデータ型を指定します。この句を省略すると、JSON_QUERYはVARCHAR2(4000)型の文字列を戻します。
JSON_return_type_clauseを使用して、次のデータ型を指定できます。
VARCHAR2[(size [BYTE,CHAR])]
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データではありません。
JSONデータがJSONパス式を使用して評価される場合に一致が見つかりません。
戻り値のデータ型が戻り文字列を保持する十分な大きさではありません。
ファンクションが単一のスカラー値または任意の型の複数の値と一致し、WITH [UNCONDITIONAL | CONDITIONAL] WRAPPER句が指定されていません。
次の句を指定できます。
NULL ON ERROR - エラーが発生した場合にnullを戻します。これはデフォルトです。
ERROR ON ERROR - エラーが発生した場合に適切なOracleエラーを戻します。
EMPTY ON ERROR - エラーが発生した場合に空のJSON配列('[]')を戻します。
例
次の問合せは、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
--------------------------------------------------------------------------------
[]
