SQL/JSONパス式の項目メソッド

17.3 SQL/JSONパス式の項目メソッド

SQL/JSONパス式で使用可能なOracle項目メソッドを示します。ターゲットJSONデータに対する動作については、一般的な用語と各項目メソッドで説明します。

項目メソッドの一般的な動作

項目メソッドは、このメソッドで終了するパス式(の残り)が対象とするJSONデータに適用されます。メソッドは、目的のデータを変換するために使用されます。

対象となるデータは、メソッドの最初の引数(通常は唯一の引数)として機能し、暗黙的です。一部の項目メソッドでは、メソッド名の後に続くカッコ(())内に、1つ以上の明示的なカンマ区切りの引数が必要または受け入れられます。

たとえば、$.myArray.indexOf("car", 3, 20)となります。メソッドindexOfを4つの引数に適用すると、データ内の配列myArrayが対象となり、要素として値"car"が最初に出現する場所が検索されますが、最初の3つの要素はスキップされ、20個を超える要素は検索されません(したがって、位置23以降はチェックされません)。最初の明示的な引数("car")は必須ですが、他の2つはオプションです。

パス式に渡されたSQLファンクションまたは条件は、対象となるデータのかわりとして変換済データを使用します。項目メソッドの適用によって、パス式と照合できるデータが制限される場合があります。このような照合制限は、(1)エラーを発生させる(json_valueセマンティクスの場合)または(2)フィルタとして機能し(json_existsとともに使用する場合)、一致しない対象となるデータを結果セットから削除できます。

対象となるデータの型が間違っているなどのなんらかの理由で項目メソッドの変換が失敗した場合、パスは照合できない(データを参照しない)ため、パス式が渡されるSQLファンクションまたは条件にエラー処理が適用されます。json_valueセマンティクスの場合、デフォルトのエラー処理動作では、エラー時にSQL NULLを返します。json_existsセマンティクスの場合、デフォルトの動作ではFALSEを返します。これは、一致しないことがフィルタとして機能することを意味します。

項目メソッドは、対象のJSONデータを(おそらく別の) JSONデータに常に変換します(このデータは必ずスカラーになります)。ただし、パス式(項目メソッドの有無にかかわらず)を使用する問合せは、SQLスカラー・データ型としてデータを返すことができます。

これは、json_valueセマンティクスを使用する問合せの場合です。json_valueで明示的に指定するか、ドット表記法構文またはスカラーSQL値を返すjson_table列指定のいずれかで暗黙的に指定するかは関係ありません。項目メソッドは、これらのコンテキストで同じ動作をします。

json_query、またはjson_queryセマンティクスを持つjson_table列の式の戻り値は、常にSQLデータ型JSON、VARCHAR2、CLOBまたはBLOBのJSONデータです。対象データがJSON型である場合、デフォルトの戻りデータ型はJSONです。それ以外の場合はVARCHAR2です。
項目メソッドを使用するドット表記法問合せでは、RETURNING句を使用してjson_valueを暗黙的に適用します。この句は、項目メソッドの対象となる(場合によっては変換される) JSONデータに対してスカラーSQL型を指定します。このため、項目メソッドを使用するドット表記法問合せは、常にSQLスカラー値を返します。
json_valueセマンティクスを持つ問合せ(json_query、json_table列の式またはドット表記法のいずれからのものに関係なく)の戻り値は、常にJSON 以外のスカラーSQLデータ型です。^脚注1JSONデータを返しません。パス式はJSONデータを対象とし、項目メソッドは常に対象となるJSONデータをJSONデータに変換しますが、json_value問合せセマンティクスは、変換されたJSONデータを、必ずしもJSONデータをサポートしないデータ型のスカラーSQL値に変換します。

ノート:

項目メソッドは、JSONデータ内に特定の値が存在するかどうかをチェックするSQL/JSON条件json_existsとともに使用することもできます。このコンテキストでは、項目メソッドは常に、フィルタ条件の比較で使用されるSQL/JSONパス式の末尾に出現します。項目メソッドを使用した結果として変換されたJSON値は、SQL値として返されません。

配列への項目メソッドの適用

項目メソッドcount()、size()、size2()、type()およびvector()を除き、項目メソッドが配列を対象とする場合、このメソッドは配列自体ではなく各配列要素に適用されます。これらのアプリケーションの結果は、配列のかわりに複数の値として返されます。つまり、一致の結果セットには、対象の配列ではなく、変換された各配列要素が含まれています。

(このことは、実質的に、オブジェクト・ステップに対して非配列が想定される場合の配列の暗黙のアンラップと同様です。)

たとえば、$.a.method()は、項目メソッドmethod()を配列aの各要素に適用してその要素を変換し、配列のかわりに使用します。

戻り型としてSQLコレクション型(varrayまたはネストされた表)を指定するjson_value問合せの場合、そのコレクション型インスタンスが返されます。これは、コレクション型定義に関して型の不一致がある場合を除いて、各配列要素に項目メソッドを適用した結果のJSON配列に対応しています。
他のSQL型を返すjson_value問合せの場合、SQLのNULLが返されます。これは、項目メソッドを配列要素にマッピングすると複数の戻り値が生成され、それがjson_valueの不一致を表すためです。
json_queryまたはjson_queryセマンティクスを持つjson_table列式に対して、ラッパー句を使用すると変換されたすべての配列要素値を配列として取得できます。たとえば、次のような問合せになります。
```
SELECT json_query('[ "alpha", 42, "10.4" ]', '$[*].string()'
                  WITH ARRAY WRAPPER)
  FROM dual;
```
[ "alpha", "42", "10.4" ]というJSON配列を返します。返されるSQLデータ型は、対象がJSON、VARCHAR2(4000)、CLOBまたはBLOBであるJSONデータと同じです。

これに関して、項目メソッドcount()、size()、size2()、type()およびvector()は例外です。配列に適用する場合、これらの項目メソッドは、その要素を処理するかわりに配列をそのまま扱います。たとえば:

SELECT json_value('[ 19, "Oracle", {"a":1}, [1,2,3] ]', '$.type()')
  FROM dual;

単一のVARCHAR2値'array'を返します。json_valueはデフォルトでVARCHAR2(4000)を返します。

類似した問合せですが、json_valueではなくjson_queryを使用すると、入力JSONデータに使用されるSQLデータ型(JSON、VARCHAR2(4000)、CLOBまたはBLOB)の、単一のJSON文字列"array"を返します。ただし、json_queryでは、項目メソッドtype()を使用する場合、キーワードWITH ARRAY WRAPPERを使用する必要があります。

SELECT json_query('[ 19, "Oracle", {"a":1}, [1,2,3] ]', '$.type()'
                  WITH ARRAY WRAPPER)
  FROM dual;

[1,2,3]]'),'$.TYPE()'WITHARRAYWRAPPER)
--------------------------------------
["array"]

そうでない場合は、エラーが発生します:

SELECT json_query('[ 19, "Oracle", {"a":1}, [1,2,3] ]', '$.type()')
  FROM dual;

ERROR at line 2:
ORA-40480: JSON array wrapper needed for result of JSON query '$.type()'

json_value (オブジェクト型またはコレクション型以外のSQL戻り型)で行われる内容と同じことが、簡単なドット表記法問合せでも行われます。たとえば:


CREATE TABLE tab (data JSON);
INSERT INTO tab VALUES ('{a : [ 1, 2, 3.5 ]}');
SELECT t.data.a[*].sum() from tab t;

T.DATA.A[*].SUM()
-----------------
              6.5

ノート:

ドット表記法構文に項目メソッドが存在すると、常にjson_queryではなくjson_valueのセマンティックスとなります。これは単一のスカラーSQL値を生成します(SQLのORDER BY、GROUP BY、比較、または結合操作で使用できます)。ただし、配列値に適用される項目メソッドは、json_valueのセマンティクスによって拒否される複数の値を生成します。SQLのNULLが返されます。

データ型変換の項目メソッド

データ型変換メソッドである項目メソッドは、binary()、binaryOnly()、boolean()、booleanOnly()、date()、dateTimeOnly()、dateWithTime()、double()、dsInterval()、float()、idOnly()、number()、numberOnly()、string()、stringify()、stringOnly()、timestamp()、toBoolean()、toDateTime()、vector()^脚注2、およびymInterval()です。

前述したように、項目メソッドは常に対象のJSONデータを(おそらく別の) JSONデータに変換します。ただし、このメソッドがjson_value問合せ(またはSQLデータを返す別のファンクション)で使用されると、変換結果のJSONデータはSQL戻り値に変換されます。RETURNING句がある場合は、そのデータのSQL型を指定します。その句がない場合、各項目メソッドは特定のデフォルトのSQL型になります。たとえば、項目メソッドstring()のデフォルトのSQL型は、VARCHAR2(4000)です。

json_valueセマンティクスを持つ問合せでは、通常、データ型変換項目メソッドの対象となる値は、そのメソッドのデフォルトのSQLデータ型のSQL値として解釈されていると考えることができます。つまり、その値は、そのSQLデータ型を持つRETURNING句によって制御されたかのように処理されるということです。

たとえば、項目メソッドstring()は句RETURNING VARCHAR2(4000)を含むjson_valueと同じようにターゲットを解釈します。そのため、ブールJSON値は、string()によって"true"または"false"として扱われ、null値はstring()によって"null"として扱われ、数値はstring()によって正規の文字列形式の数値として扱われます。

ほとんどのデータ型変換メソッドは、SQL/JSONパス式の末尾で使用できます。つまり、json_valueセマンティクスを持つ問合せは、対応するSQLスカラー値を返すことができます。パスの末尾で使用できない型変換メソッドには、"to"で始まる名前が付いています。

名前に"only"が含まれていないデータ型変換メソッドは、可能であればJSON値を(場合によってはメソッドで指定された型ファミリに含まれない値でも)メソッドのJSON型に変換し、その結果をメソッドのデフォルトのSQL型の値として解釈します。

"only"データ型変換メソッドは、メソッドによって指名された型ファミリに含まれるJSON値のみを変換します。その他の対象となる値はパス式と照合されません。"only"メソッドは、そのメソッドのデフォルトのJSON言語型に値を変換し、その結果をメソッドのデフォルトのSQL型の値として解釈します。

numberOnly()の場合、ファミリ型は数値(数値JSON型)であり、ファミリのデフォルトのJSONタイプはnumberであり、デフォルトのSQL型はNUMBERです。dateTimeOnly()の場合、デフォルトのファミリ型はtimestampであり、デフォルトのSQL型はTIMESTAMPです。

("only"メソッドで配列を対象とする場合、変換は通常どおり、各配列要素に適用されます。)

avg()などの集計メソッドは、対象となる値をメソッドのデフォルトの型に変換し、メソッドのデフォルトのSQL型として解釈します。avg()の場合、対象となる値の型number、floatおよびdoubleは、すべてJSON型のnumberに変換され、SQLのNUMBER値として解釈されます。

abs()などの非集計メソッドは、関連する型ファミリの範囲内での変換は実施されません。そのため、abs()は文字列"-3.14"をJSONの数値に変換しますが、対象となるJSONの浮動小数点値または倍精度値をそのまま残し、それぞれSQLのBINARY_FLOATまたはBINARY_DOUBLE値として解釈します。

表17-1 項目メソッドのデータ型変換

項目メソッド	入力のJSON言語型	出力のJSON言語型	SQL型	ノート
`binary()`	バイナリ(識別子と非識別子の両方)	binary	`RAW`または`BLOB`	なし。
`binary()`	string	binary	`RAW`または`BLOB`	いずれかの入力文字が16進数値でない場合はエラーになります。
`binaryOnly()`	バイナリ(識別子と非識別子の両方)	binary	`RAW`または`BLOB`	なし。
`boolean()`	boolean	boolean	`BOOLEAN`	なし。
`boolean()`	string	boolean	`BOOLEAN`	入力が`"true"`または`"false"`でない場合はエラーになります
`booleanOnly()`	boolean	boolean	`BOOLEAN`	なし。
`date()`	date、timestampまたはtimestamp with time zone	date	`DATE`	JSON出力は、時間コンポーネントなしのUTCです。
`date()`	string	date	`DATE`	JSON出力は、時間コンポーネントなしのUTCです。入力が時間コンポーネントなしのISO UTCでない場合はエラーになります。
`dateTimeOnly()`	date、timestampまたはtimestamp with time zone	timestamp	`TIMESTAMP`	なし。
`dateWithTime()`	date、timestampまたはtimestamp with time zone	date	`DATE`	小数秒なしのUTC。
`dateWithTime()`	string	date	`DATE`	小数秒なしのUTC。入力がISOでない場合はエラーになります。
`double()`	number、doubleまたはfloat	double	`BINARY_DOUBLE`	なし。
`double()`	string	double	`BINARY_DOUBLE`	入力が数値表現でない場合はエラーになります。
`float()`	number、doubleまたはfloat	float	`BINARY_FLOAT`	入力が範囲外の場合はエラーになります。
`float()`	string	float	`BINARY_FLOAT`	入力が数値表現でない場合はエラーになります。
`idOnly()`	バイナリ識別子	バイナリ識別子	`RAW`	なし。
`number()`	number、doubleまたはfloat	number	`NUMBER`	入力が範囲外の場合はエラーになります。
`number()`	string	number	`NUMBER`	入力が数値表現でない場合はエラーになります。
`numberOnly()`	number、doubleまたはfloat	number	`NUMBER`	なし。
`string()`	任意。	string	`VARCHAR2`または`CLOB`	結果のSQL値は、出力のJSON言語文字列がUTF-8であっても、データベース文字セットになります。
`stringify()`	任意。	string	`CLOB`	SQL型を除き、`string()`と同じです。メソッド`stringify()`は、SQL/JSONパス式ではなく、単純なドット表記でのみ使用できます。
`stringOnly()`	string	string	`VARCHAR2`または`CLOB`	`string()`と同じです。
`timestamp()`	date、timestampまたはtimestamp with time zone	timestamp	`TIMESTAMP`	なし。
`timestamp()`	string	timestamp	`TIMESTAMP`	入力がISO UTCでない場合はエラーになります。
`toBoolean()`^脚注3	boolean	boolean	`BOOLEAN`	なし。
`toBoolean()`^脚注3	string	boolean	`BOOLEAN`	入力文字列が`"true"`または`"false"`でない場合はエラーになります
`toBoolean()`^脚注3	number、doubleまたはfloat	boolean	`BOOLEAN`	ゼロは`false`に変換されます。それ以外のすべての数値は`true`に評価されます。
`toDateTime()`^脚注3	date、timestampまたはtimestamp with time zone	timestamp	`TIMESTAMP`	なし。
`toDateTime()`^脚注3	string	timestamp	`TIMESTAMP`	入力がISO UTCでない場合はエラーになります。
`toDateTime()`^脚注3	number、doubleまたはfloat	timestamp	`TIMESTAMP`	数値は、1970-01-01からの秒数として解釈されます。負でない数値のみが一致します。
`vector()`	数値の配列またはJSONベクター・スカラー値。他のJSON値に適用すると、エラーが発生します。	vector	`VECTOR`	メソッド`vector()`は、SQL/JSONパス式ではなく、単純なドット表記でのみ使用できます。

^脚注3このメソッドは、SQL/JSONパス式の末尾では使用できません。

項目メソッドの説明

abs(): 対象となるJSONの数値の絶対値。SQLファンクションABSの使用に対応します。
atan(): 対象となるJSON数値(ラジアン単位)の三角法逆正接関数。SQLファンクションATANの使用に相当します。
avg(): 対象となるすべてのJSON数値の平均値。対象となる値が数値でない場合はエラーになります。SQLファンクションAVGの使用(オプションの動作なし)に相当します。これは集計メソッドです。
binary(): 対象となるJSON値(16進文字列またはJSONバイナリ値)のSQL RAW解釈。文字列の場合、SQLファンクションhextorawは、SQLのRAW値への変換に使用されます。この項目メソッドは、JSON型として格納されているJSONデータにのみ適用されます。
binaryOnly(): 対象となるJSON値のSQL RAW解釈。ただし、その値がJSONバイナリ値の場合にかぎられます。JSONバイナリ値に対してのみ照合を可能にします。(JSON型として格納されたJSONデータのみがJSONバイナリ値を保持できます)。
boolean(): 対象となるJSON値のSQL BOOLEAN解釈。

ノート:

リリース23aiより前では、SQL VARCHAR2(20)の解釈を使用していました。VARCHAR2値の取得が必要な場合(互換性の理由など)は、SQLファンクションto_charで値をラップできます。
booleanOnly(): 対象となるJSONデータのSQL BOOLEAN解釈。ただし、そのデータがJSONのブール値(trueまたはfalse)である場合にかぎられます。それ以外の場合は一致しません。JSONブール値に対してのみ照合を可能にします。

ノート:

リリース23aiより前では、SQL VARCHAR2(20)の解釈を使用していました。VARCHAR2値の取得が必要な場合(互換性の理由など)は、SQLファンクションto_charで値をラップできます。
ceiling(): 最も近い整数に切り上げられた対象となるJSONの数値。SQLファンクションCEILの使用に対応します。
concat(): 文字列引数(2つ以上)の連結。この項目メソッドは、json_transform操作の右側(RHS)パス式でのみ使用できます(それ以外の場合はエラーが発生します)。
cos(): 対象となるJSON数値(ラジアン単位)の三角法余弦関数。SQLファンクションCOSの使用に相当します。
cosh(): 対象となるJSON数値(ラジアン単位)の三角法双曲線余弦関数。SQLファンクションCOSHの使用に相当します。
count(): 対象のJSON値の数(型にかかわらず)。これは集計メソッドです。
date(): 対象となるJSON値のSQL DATE解釈。対象となる値は、(1)日付または日付時刻に対してサポートされているISO 8601形式のJSON string、または(2) (データがSQL型JSONの場合) date、timestampまたはtimestamp with time zone値であることが必要です。それ以外の場合は、一致しません。

SQL DATE値には、時間コンポーネントがありません(ゼロに設定されます)。ただし、時間の切捨てが行われる前に、ISO 8601の日時文字列で表される値にタイムゾーン・コンポーネントがある場合は、値は最初にUTCに変換され、タイムゾーン情報が考慮されます。

たとえば、JSON文字列"2021-01-01T05:00:00+08:00"は、UTC文字列"2020-12-31 00:00:00"に相当するSQL DATE値として解釈されます。

結果としての日付は、データのタイム・ゾーンを忠実に反映します(対象と結果が同じ日付を表します)が、結果は単純な時間の切捨てによって生成されるものとは異なることがあります。(この動作は、SQL/JSONファンクションjson_scalarの動作と似ています)。
dateTimeOnly(): 対象となるJSON値のSQL TIMESTAMP解釈。対象となる値は、date、timestampまたはtimestamp with time zone値であることが必要です。(JSON型として格納されたJSONデータのみが、そのような値を保持できます)。
dateWithTime(): ISO 8601の日時形式の時間コンポーネントがSQLのDATEインスタンスに保存されることを除き、date()と同様です。
double(): 対象となるJSON文字列または数値のSQL BINARY_DOUBLEでの解釈。
dsInterval(): 対象となるJSON文字列のSQLのINTERVAL DAY TO SECONDでの解釈。対象となる文字列データは、サポートされているISO 8601継続時間形式のいずれかである必要があります。それ以外の場合、一致はありません。
exp(): 対象となるJSON数値の数学的指数関数。つまり、数学定数e (オイラー数、2.71828183...)を、対象となるJSONの数値で累乗したものです。SQLファンクションEXPの使用に相当します。
float(): 対象となるJSON文字列または数値のSQL BINARY_FLOATでの解釈。
floor(): 最も近い整数に切り捨てられた対象となるJSONの数値。SQLファンクションFLOORの使用に対応します。
idOnly(): 対象となるJSON値のSQL RAW解釈。フィールド$rawidまたは$oidの拡張オブジェクトから導出されたものとして内部的にタグ付けされたJSONバイナリ値に対してのみ照合を可能にします。(JSON型として格納されたJSONデータのみがJSONバイナリ値を保持できます)。
indexOf(): 指定されたJSON配列の指定されたJSON値と等しい最初の要素の位置(索引)。

配列はメソッドの最初の暗黙的な引数(対象となるデータ)であり、配列内で検索する値は2番目の(最初の)明示的な引数です。どちらも必須です。この項目メソッドは、json_transform操作の右側(RHS)パス式でのみ使用できます(それ以外の場合はエラーが発生します)。

1つまたは2つのオプション引数も受け入れられます。2番目の明示的な引数は、チェックする最初の要素の配列位置です(それより前の位置はスキップされます)。3番目の明示的な引数は、チェックする配列要素の最大数です。たとえば、オプションの引数を使用すると、配列をループして一致する要素を配列順に見つけることができます。
- データがJSONデータ型の場合は、すべてのJSON言語の値が比較可能です。比較は正規のソート順に従って実施されます。
- JSON型ではないデータの場合は、スカラーJSON値のみが比較可能です。非スカラー・データ値は無視されます。また、場所の特定のために指定したJSON値はスカラーであることが必要です(それ以外の場合はエラーが発生します)。
length(): 対象となるJSON文字列内の文字数、または対象となるバイナリ値のバイト数。SQL NUMBERとして解釈されます。SQLファンクションLENGTHの使用に相当します。対象となる文字列値の場合、値が"chars"または"bytes"であるオプションの引数が許可され、それぞれ文字数またはバイト数で長さを指定します。
listagg(): 対象となるJSON値の連結。この値は、文字列であることが必要です(それ以外の場合はエラーが発生します)。オプションのデリミタ文字列引数を受け入れます。これは対象となる連続する文字列の間に挿入されます。SQLファンクションLISTAGGの使用に相当します。これは集計メソッドです。
log(): 対象となるJSON数値の数学的対数関数。SQLファンクションLOGの使用に相当します。オプションの数値引数(対数の底)を受け入れます。デフォルトの底は数学定数e (オイラー数、2.71828183...)です。これは、デフォルトでは自然対数が計算されることを意味します。
lower(): 対象となるJSON文字列内の文字に対応する小文字の文字列。SQLファンクションLOWERの使用に相当します。
max(): スカラーかどうかに関係なく、すべての対象となるJSON値の最大値。これは集計メソッドですが、他の集計メソッドとは異なり、パス式の末尾では使用できません。json_existsを使用したフィルタ条件、またはjson_queryセマンティクスを持つ問合せでのみ使用できます。json_valueセマンティクスを持つ問合せで使用すると、エラーが発生します。戻り値のデータ型は常にJSONです。

メソッドmax()およびmin()のみが、非スカラーJSON値(オブジェクトまたは配列)を返すことができるメソッドです。
- データがJSONデータ型の場合は、すべてのJSON言語の値が比較可能です。比較は正規のソート順に従って実施されます。
- JSON型ではないデータの場合は、スカラーJSON値のみが比較可能です。非スカラー・データ値は無視されます。また、指定したJSON値はすべてスカラーであることが必要です(それ以外の場合はエラーが発生します)。
maxDateTime(): すべての対象となるJSONの日付時刻の最大値です。最初に、項目メソッドdateWithTime()が複数の可能性がある値のそれぞれに暗黙的に適用されます。それらの最大値(単一のTIMESTAMP値)が返されます。日付時刻に変換できない対象となるJSON値は無視されます。これは集計メソッドです。
maxNumber(): 対象となるすべてのJSON数値の最大値です。項目メソッドnumber()が、場合によっては複数の各値に暗黙的にまず適用されます。それらの最大値(1つのNUMBER値)が返されます。数値に変換できない対象のJSON値は無視されます。これは集計メソッドです。
maxString(): 照合順序を使用した、対象となるすべてのJSON文字列の最大値。項目メソッドstring()が、場合によっては複数の各値に暗黙的にまず適用されます。これらの最大値(単一のVARCHAR2値)が返されます。文字列に変換できない対象のJSON値は無視されます。これは集計メソッドです。
min(): スカラーかどうかに関係なく、すべての対象となるJSON値の最小値。詳細は、max()を参照してください。min()でも同様ですが、最大値ではなく最小値を返します。
minDateTime(): すべての対象となるJSONの日付時刻の最小値です。最初に、項目メソッドdateWithTime()が複数の可能性がある値のそれぞれに暗黙的に適用されます。それらの最小値(単一のTIMESTAMP値)が返されます。日付時刻に変換できない対象となるJSON値は無視されます。これは集計メソッドです。
minNumber(): 対象となるすべてのJSON数値の最小値です。項目メソッドnumber()が、場合によっては複数の各値に暗黙的にまず適用されます。それらの最小値(1つのNUMBER値)が返されます。数値に変換できない対象のJSON値は無視されます。これは集計メソッドです。
minString(): 照合順序を使用した、対象となるすべてのJSON文字列の最小値。項目メソッドstring()が、場合によっては複数の各値に暗黙的にまず適用されます。これらの最小値(単一のVARCHAR2値)が返されます。文字列に変換できない対象のJSON値は無視されます。これは集計メソッドです。
nullOnly(): 対象となるデータがJSON nullの場合、JSON nullを返します。それ以外の場合、一致はなく、パス式が渡されるSQLファンクションまたは条件にエラー処理が適用されます。一般的な使用方法は、条件json_existsで、フィルタ処理に使用されます。例: json_exists(mytable.jcol, $?(@.a.nullOnly() == null))。
number(): 対象となるJSON文字列または数値のSQL NUMBERの解釈。
numberOnly(): JSONのブール値である場合、対象となるJSONデータのSQL NUMBERの解釈。それ以外の場合、一致はありません。JSON数値に対してのみ照合を可能にします。
pow(): 対象となるJSON数値の数学的べき乗関数。これにより、対象となるJSON数値が指定された指数(必須の数値引数)でべき乗されます。SQLファンクションPOWERの使用に相当します。
round(): SQLファンクションROUNDの使用に相当します。

オプションの整数引数Nは、最も近い10^-Nに丸めることを指定します。デフォルト(N = 0)では、小数点、つまり最も近い整数に丸められます。負でない場合は、小数点以下N桁に丸められます。負の場合は、小数点より前のN桁に丸められます。たとえば、round(31415.92653, 3) = 31415.927、round(31415.92653, 0) = 31415、round(31415.92653, -3) = 31400です。
sin(): 対象となるJSONの数値(ラジアン単位)の三角法正弦関数。SQLファンクションSINの使用に相当します。
sinh(): 対象となるJSONの数値(ラジアン単位)の三角法双曲線正弦関数。SQLファンクションSINHの使用に相当します。
size(): 複数のJSON値が対象である場合、各対象値にsize()を適用した結果です。そうでない場合:
- 単一の対象値がスカラーの場合は1です。(JSONベクター値はスカラーであることに注意してください。)
- 単一の対象値が配列の場合は、配列の要素数です。
- 単一の対象値がオブジェクトの場合は1です。
この項目メソッドは、json_valueセマンティクスとともに使用することに加えて、json_queryセマンティクスとともに使用できます。配列のデータに適用される場合、配列要素に対する暗黙的な反復は発生しません。結果の値は配列要素の数に一致します。(暗黙的反復のルールに対する例外。)
size2(): これは標準のメソッドsize()と同じですが、単一の対象となる値がオブジェクトの場合、値は(1ではなく)オブジェクト内のメンバー数になります。
stddev(): 対象となるJSON値の統計的標準偏差関数。この値は、数値であることが必要です(それ以外の場合はエラーが発生します)。SQLファンクションSTDDEVの使用に相当します。これは集計メソッドです。
stddevp(): 対象となるJSON値の統計的母集団標準偏差関数。この値は、数値であることが必要です(それ以外の場合はエラーが発生します)。SQLファンクションSTDDEV_POPの使用に相当します。これは集計メソッドです。
string(): 対象となるスカラーJSON値のSQL VARCHAR2(4000)またはCLOBの解釈。デフォルトはVARCHAR2(4000)です。
stringify(): 対象となるスカラーJSON値のSQL CLOBの解釈。メソッドstringify()は、SQL/JSONパス式ではなく単純なドット表記でのみ使用できるという点で例外的です。
stringOnly(): JSON文字列である場合のみ、対象となるスカラーJSON値のSQL VARCHAR2(4000)またはCLOBの解釈。それ以外の場合、一致はありません。JSON文字列に対してのみ照合を可能にします。デフォルトはVARCHAR2(4000)です。
substr(): 対象となるJSON文字列の部分文字列です。SQLファンクションSUBSTRの使用に相当しますが、1ベースではなく0ベースです。対象となる文字列内の部分文字列の開始位置は必須引数です。部分文字列の最大長は、オプションの(2番目の)引数になります。
sum(): 対象となるすべてのJSON数値の合計値です。対象となる値が数値でない場合はエラーになります。SQLファンクションSUMの使用(オプションの動作なし)に相当します。これは集計メソッドです。
tan(): 対象となるJSONの数値(ラジアン単位)の三角法正接関数。SQLファンクションTANの使用に相当します。
tanh(): 対象となるJSONの数値(ラジアン単位)の三角法双曲線正接関数。SQLファンクションTANHの使用に相当します。
timestamp(): 対象となるJSON値のSQL TIMESTAMP解釈。対象となる文字列データは、(1)日付または日付時刻に対してサポートされているISO 8601形式のJSON string、または(2) (データがSQL型JSONの場合) date、timestampまたはtimestamp with time zone値であることが必要です。それ以外の場合は一致しません。<a id="fn_4" name="fn_4" href="#fn_4" onclick='footdisplay(4, "Applying item method timestamp() to a supported ISO 8601 string <ISO-STRING> has the effect of SQL sys_extract_utc(to_utc_timestamp_tz(^脚注4
toBoolean(): 対象となるJSON値のSQL VARCHAR2(20)解釈。これは、メソッドboolean()と同じですが、対象となる値が数値であってもかまいません。その場合、ゼロはfalseに相当し、その他の数字はtrueに相当します。
toDateTime(): 対象となるJSON値のSQL TIMESTAMP解釈。対象となる文字列データは、(1)日付または日付時刻に対してサポートされているISO 8601形式のJSON string、(2)負でない数値、または(3) (データがSQL型JSONの場合) date、timestampまたはtimestamp with time zone値であることが必要です。それ以外の場合は一致しません。<a id="fn_5" name="fn_5" href="#fn_5" onclick='footdisplay(5, "Applying item method toDateTime() to a supported ISO 8601 string <ISO-STRING> has the effect of SQL sys_extract_utc(to_utc_timestamp_tz(^脚注5
truncate(): 切捨てで丸められた対象となるJSONの数値。SQLファンクションTRUNCの使用に相当します。

オプションの整数引数N (デフォルトは0)は、小数点の左(負の場合)または右(負でない場合)に保持する桁数を指定します。
type(): 対象となるデータのJSON言語データ型ファミリの名前、またはそのファミリ・メンバーの名前。SQLのVARCHAR2(20)値として解釈されます。たとえば、数値型ファミリの場合、返される値は"double"、"float"または"number"です。「JSONデータ型の値の比較とソート」を参照してください。

この項目メソッドは、json_valueセマンティクスに加えて、json_queryセマンティクスを持つ問合せで使用できます。配列であるデータに適用される場合、配列要素に対する暗黙的な反復は発生しません。結果の値は"array"となります。(暗黙的反復のルールに対する例外。)
- 配列の場合、"array"。
- ブール値(trueまたはfalse)の場合、"boolean"。
- SQLのRAW値に対応する値の場合、"binary"。(JSON型のデータの場合のみ。)
- SQLのDATE値に対応する値の場合、"date"(JSON型のデータの場合のみ。)
- SQLのINTERVAL DAY TO SECOND値に対応する値の場合、"daysecondInterval"。(JSON型のデータの場合のみ。)
- SQLのBINARY_DOUBLE値に対応する数値の場合、"double"。(JSON型のデータの場合のみ。)
- SQLのBINARY_FLOAT値に対応する数値の場合、"float"。(JSON型のデータの場合のみ。)
- null値の場合、"null"。
- 数値の場合、"number"。
- オブジェクトの場合、"object"。
- 文字列の場合、"string"。
- SQLのTIMESTAMP値に対応する値の場合、"timestamp"。(JSON型のデータの場合のみ。)
- SQLのTIMESTAMP WITH TIME ZONE値に対応する値の場合、"timestamp with time zone"。(JSON型のデータの場合のみ。)
- SQL VECTOR値に対応する値の場合、"vector"。
- SQLのINTERVAL YEAR TO MONTH値に対応する値の場合、"yearmonthInterval"。(JSON型のデータの場合のみ。)
upper(): 対象となるJSON文字列内の文字に対応する大文字の文字列。SQLファンクションUPPERの使用に相当します。
variance(): 対象となるJSON値の統計的分散関数。この値は、数値であることが必要です(それ以外の場合はエラーが発生します)。SQLファンクションVARIANCEの使用に相当します。これは集計メソッドです。
vector(): 対象となるJSON値のSQL VECTORの解釈。対象となるデータが数値のJSON配列の場合、その値はベクターに変換されます。対象となるデータがJSONスカラー・ベクター値である場合、その値が返されます。データがその他のJSON値(数値以外の要素を含む配列など)である場合、エラーが発生します。

メソッドvector()は、SQL/JSONパス式ではなく、単純なドット表記でのみ使用できます。
ymInterval(): 対象となるJSON文字列のSQLのINTERVAL YEAR TO MONTHでの解釈。対象となる文字列データは、サポートされているISO 8601継続時間形式のいずれかである必要があります。それ以外の場合、一致はありません。

項目メソッドのabs()、ceiling()、double()、floor()、size()およびtype()は、SQL/JSON標準の一部です。その他のメソッドはSQL/JSON標準に対するOracleの拡張機能です。該当するメソッドは、atan()、avg()、binary()、binaryOnly()、boolean()、booleanOnly()、concat()、cos()、cosh()、count()、date()、dateTimeOnly()、dateWithTime()、double(), dsInterval()、exp()、float()、idOnly()、indexOf()、length()、listagg()、log()、lower()、max()、maxDateTime()、maxNumber()、maxString()、min()、minDateTime()、minNumber()、minString()、nullOnly()、number()、numberOnly()、pow()、round()、sin()、sinh()、size2()、stddev()、stddevp()、string()、 stringify()、stringOnly()、substr()、sum()、tan()、tanh()、timestamp()、toBoolean()、toDateTime()、truncate()、upper()、variance()、vector()およびymInterval()です。

項目メソッドavg()、count()、listagg()、max()、maxDateTime()、maxNumber()、maxString()、min()、minDateTime()、minNumber()、minString()、stddev()、stddevp()、sum()およびvariance()は、集計項目メソッドです。各対象値に個別に作用するのではなく、対象値すべてに対して作用します。たとえば、パス式が数値に変換できる複数の値を対象としている場合、sum()はそれらの数値の合計を返します。

パス式が配列を対象としている場合、集計項目メソッドをその配列に適用すると、配列は単一の値として処理されます。配列要素が暗黙的に反復されることはありません。たとえば、count()は対象となる配列を1つの値としてカウントし、size()は配列要素のサイズではなく配列のサイズを返します。

集計項目メソッドを配列要素に適用する場合は、ワイルドカード*を使用して、それらの要素を明示的に反復処理する必要があります。たとえば、指定された文書のLineItemsフィールドの値が配列の場合、$.LineItems.count()は1を返しますが、$.LineItems[*].count()は配列要素の数を返します。

集計項目メソッドは、それが含まれるパス式(ドット表記法)と同様に、一度に1つのJSON文書に適用されます。パス式によってその文書内で対象となる複数の値を集計します。問合せは、各文書について1つの行を返します。複数の文書の情報を集計するのではなく、SQL集計関数と同様に、すべての文書に対して1つの行を返します。例17-1および例17-2を参照してください。

項目メソッド	互換性のあるSQL問合せ戻りデータ型
`lower()` `maxString()` `minString()` `string()` `stringOnly()` `upper()`	`VARCHAR2`または`CLOB` (`string()`がJSON `null`値に対してSQL `NULL`を返すことを除く)
`stringify()`	`CLOB` (JSON `null`値に対してSQL `NULL`を返すことを除く)
`avg()` `count()` `maxNumber()` `minNumber()` `number()` `numberOnly()` `stddev()` `stddevp()` `sum()`	`NUMBER`
`double()`	`BINARY_DOUBLE`
`float()`	`BINARY_FLOAT`
`date()` `dateTimeOnly()`	`DATE` (切り捨てられた時間コンポーネント(ゼロに設定)を含み、`RETURNING DATE TRUNCATE TIME`に相当)。 JSON値がタイムゾーン情報を含むISO文字列である場合、表された日付時刻は、最初にUTCに変換されてからタイムゾーンが考慮されます。
`dateWithTime()`	`DATE` (時間コンポーネントを含み、`RETURNING DATE PRESERVE TIME`に相当)
`maxDateTime()` `minDateTime()` `timestamp()`	`TIMESTAMP`
`ymInterval()`	`INTERVAL YEAR TO MONTH`
`dsInterval()`	`INTERVAL DAY TO SECOND`
`boolean()` `booleanOnly()`	`VARCHAR2`または`BOOLEAN`
`binary()` `binaryOnly()` `idOnly()`	`RAW`
`vector()`	`VECTOR`