4 EPLリファレンス: 関数

この章では、イベント処理言語(EPL)の関数のリファレンスについて説明します。EPLは非推奨になったことに注意してください。新たな開発ではOracle Continuous Query Language (Oracle CQL)を使用する必要があります。

この章には次の項が含まれます:

4.1項「単一行関数」
4.2項「集約関数」
4.3項「ユーザー定義関数」

4.1 単一行関数

単一行関数は、文で生成された1つの結果行につき1つの値を返します。これらの関数は、式が許可されている任意の場所で使用することができます。

EPLでは静的Javaライブラリ・メソッドを単一行関数として使用できます。また、組込みの単一行関数も提供されます。

EPLでは、以下のJavaライブラリ・パッケージが自動的にインポートされます。

java.lang.*
java.math.*
java.text.*
java.util.*

このため、以下の例のように、すべての式でJava静的ライブラリ・メソッドを使用できます。

  SELECT symbol, Math.round(volume/1000)
  FROM StockTickEvent RETAIN 30 SECONDS

他の任意のJavaクラスを使用することもできますが、完全修飾名を使用するか、インポートのために構成する必要があります。詳細は、4.3項「ユーザー定義関数」を参照してください。

以下の表に、使用可能な組込みの単一行関数の概要を示します。

表4-1組込みの単一行関数

単一行関数	結果	参照先
`MAX`(expression, expression [, expression [,…])	カンマ区切りの複数の式の中で最大の数値を返します。	4.1.1項「MIN関数とMAX関数」
`MIN`(expression, expression [, expression [,…])	カンマ区切りの複数の式の中で最小の値を返します。	4.1.1項「MIN関数とMAX関数」
`COALESCE`(expression, expression [, expression [,…])	リスト内の最初のnull以外の値を返します。null以外の値がない場合は、nullを返します。	4.1.2項「COALESCE関数」
`CASE` value WHEN compare_value THEN result [WHEN compare_value THEN result …] [ELSE result] END	最初の値と一致する`compare_value`の結果を返します。	4.1.3項「CASE制御フロー関数」
`CASE` value WHEN condition THEN result [WHEN condition THEN result …] [ELSE result] END	最初の条件を満たす結果を返します。	4.1.3項「CASE制御フロー関数」
`PREV`(expression, event_property)	データ・ウィンドウ内のイベント順序に関して、前のイベントのプロパティ値を返します。	4.1.4項「PREV関数」
`PRIOR`(integer, event_property)	本来のイベント到着の順序に関して、前のイベントのプロパティ値を返します。	4.1.5項「PRIOR関数」
SELECT CASE WHEN `INSTANCEOF`(item, com.mycompany.Service) THEN serviceName? WHEN INSTANCEOF(item, com.mycompany.Product) THEN productName? END FROM OrderEvent	式で返される値の型が指定されたいずれかの値であるかどうかを示すブール値を返します。	4.1.6項「INSTANCEOF関数」
SELECT `CAST`(item.price?, double) FROM OrderEvent	指定した型に式の戻り値の型をキャストします。	4.1.7項「CAST関数」
SELECT `EXISTS`(item.serviceName?) FROM OrderEvent	関数へのパラメータで指定された動的プロパティがイベント内に存在するかどうかを示すブール値を返します。	4.1.8項「EXISTS関数」

ユーザー定義の単一行関数を作成することもできます。4.3項「ユーザー定義関数」を参照してください。

4.1.1 MIN関数とMAX関数

MINおよびMAX関数は複数の式パラメータを受け取ります。MIN関数はカンマで区切られたこれらの式の中で最小の数値を返し、MAX関数は最大の数値を返します。戻り値の型は、互換性のある、すべての戻り値の集約型です。

次の例では、MAX関数の戻り値の型はDoubleであり、値1.1が返されます。

  SELECT MAX(1, 1.1, 2 * 0.5) 
  FROM ...

MIN関数は最小値を返します。次の文は、2つのタイム・スタンプの小さい方の値を決定する関数を使用しています。

  SELECT symbol, MIN(ticks.timestamp, news.timestamp) AS minT
  FROM StockTickEvent AS ticks, NewsEvent AS news RETAIN 30 SECONDS
  WHERE ticks.symbol = news.symbol

MINおよびMAX関数は集約関数としても使用できます。この使用方法の説明は、4.2項「集約関数」を参照してください。

4.1.2 COALESCE関数

COALESCE関数の結果は、式のリストの中でnull以外の値を返す最初の式になります。戻り値の型は、互換性のある、すべての戻り値の集約型です。

次の例では、String型の値fooが返されます。

  SELECT COALESCE(NULL, 'foo') 
  FROM …

4.1.3 CASE制御フロー関数

CASE制御フロー関数には2つのバージョンがあります。最初のバージョンは、値およびこの値と比較される比較値のリストを受け取り、最初の値が比較値と一致した結果を返します。2つ目のバージョンは、条件リストを受け取り、最初の条件を満たす結果を返します。

CASE式の戻り値の型は、互換性のある、すべての戻り値の集約型です。

次の例はCASE文の最初のバージョンです。戻り値の型はStringであり、値oneが返されます。

  SELECT CASE 1 WHEN 1 THEN 'one' WHEN 2 THEN 'two' ELSE 'more' END 
  FROM …

CASE関数の2つ目のバージョンは条件リストを受け取ります。次の例では、戻り値の型はBooleanであり、Boolean値trueが返されます。

  SELECT CASE WHEN 1>0 THEN true ELSE false END 
  FROM …

4.1.4 PREV関数

PREV関数は前のイベントのプロパティ値を返します。最初のパラメータは、データ・ウィンドウで指定された順序で何番目の前のイベントであるかを指定します。第2パラメータは、関数により値が返される、前のイベントのプロパティ名です。

次の例では、現在のTradeイベントの2つ前のイベントのpriceプロパティの値が選択されます。

  SELECT PREV(2, price) 
  FROM Trade RETAIN 10 EVENTS

PREV関数ではデータ・ウィンドウで指定された順序が考慮されるため、並べ替えられたウィンドウでこの関数を使用すると便利です。次の例では、最大量、2番目に大きい量、および3番目に大きい量を持つ3つのTradeイベントの銘柄が選択されます。

  SELECT PREV(0, symbol), PREV(1, symbol), PREV(2, symbol)
  FROM Trade RETAIN 10 EVENTS WITH LARGEST volume

何番目の前のイベントであるかを指定するパラメータには、Integer型の値を返す式を使用することもできます。次の文では、Tradeデータ・ウィンドウが、並べ替えられたTradeデータ・ウィンドウ内の特定の位置を参照するrankプロパティを提供するRankSelectionEventイベントと結合されます。

  SELECT PREV(rank, symbol) 
  FROM Trade, RankSelectionEvent RETAIN 10 EVENTS WITH LARGEST volume

PREV関数は、指定されている何番目か前のイベントが現在のデータ・ウィンドウに含まれていない場合、NULL値を返します。次の例では、時間バッチ・ウィンドウを使用した例を示しています。このPREV関数では、前のイベントが同じイベント・バッチ内に存在しない任意のイベントに対してnull値が返されます。結果のnull値が適切でない場合は、下で説明しているPRIOR関数を使用できます。

  SELECT PREV(1, symbol) 
  FROM Trade RETAIN BATCH OF 1 MINUTE

4.1.4.1 各グループの前のイベント

PREV関数とPARTITION BY句を組み合せることにより、指定のグループに含まれている前のイベントのプロパティ値が返されます。

たとえば、現在のイベントと同じ銘柄の前のイベントの価格を取得すると想定します。

この問題を解決する文は以下のとおりです。1分の時間ウィンドウでsymbolプロパティに対してウィンドウが分割されます。これにより、これまでにない新しい銘柄値がエンジンで検出されると、その銘柄のイベントを個別に保持する新しいウィンドウが作成されます。この結果、PREV関数では、イベントの銘柄値が持つそれぞれの時間ウィンドウ内にある前のイベントが返されます。

  SELECT PREV(1, price) AS prevPrice 
  FROM Trade RETAIN 1 MIN PARTITION BY symbol

4.1.4.2 制限

PREV関数およびその結果に適用される制限は、次のとおりです。

関数は常に削除ストリーム(古いデータ)のイベントに対してnull値を返します。
関数はRETAIN句の制約のあるストリームでのみ使用できます。

4.1.5 PRIOR関数

PRIOR関数は前のイベントのプロパティ値を返します。最初のパラメータは、本来の到着順で何番目の前のイベントであるかを示す整数値です。第2パラメータは、関数により値が返される、前のイベントのプロパティ名です。

次の例では、現在のTradeイベントの2つ前のイベントのpriceプロパティの値が選択されます。

  SELECT PRIOR(2, price) 
  FROM Trade RETAIN ALL

PRIOR関数は任意のイベント・ストリームまたはビューに対して使用でき、PREV関数のようにRETAIN句の制約をストリームに付与する必要がありません。関数は、イベントを提供するイベント・ストリーム内のイベントの到着順に基づいて動作します。

次の文では、長さのバッチ・ウィンドウを使用してTradeイベント3件ごとの平均量を計算し、イベント3件ごとに結果をポストします。SELECT句では現在の平均およびその前の平均を選択するためにPRIOR関数を使用します。

  SELECT AVG(volume) AS avgVolume, AVG(PRIOR(3, volume))
  FROM Trade RETAIN BATCH OF 3 EVENTS

4.1.5.1 PREV関数との比較

PRIOR関数はPREV関数とほぼ同様です。2つの関数の主な違いは以下のとおりです。

PREV関数はウィンドウで指定された順序での前のイベントを返し、PRIOR関数はストリーム内の到着順序での前のイベントを返します。
PREV関数ではRETAIN句が必要ですが、PRIOR関数では必要ありません。
PREV関数はグループ化を考慮して前のイベントを返します。PRIOR関数はグループ化に関係なく前のイベントを返します。
PREV関数は削除ストリームのイベント(データ・ウィンドウを離れるイベント)に対しnull値を返します。PRIOR関数にこの制限はありません。

4.1.6 INSTANCEOF関数

INSTANCEOF関数は、式で返される値の型が指定されたいずれかの値であるかどうかを示すブール値を返します。INSTANCEOF関数の最初のパラメータは評価される式です。第2パラメータ以降はJava型名です。

INSTANCEOF関数は実行時に式を評価して戻り値の型を決定し、式で返されたオブジェクトの型を定義されている型と比較します。式で返されたオブジェクトの型が指定された型のいずれかと一致する場合は、trueを返します。式で返された値がnullまたは指定されたどの型とも一致しない型の場合は、falseを返します。

INSTANCEOF関数は多くの場合、動的な(チェックされていない)プロパティとともに使用されます。動的プロパティとはコンパイル時に型が不明なプロパティです。

次の例では、INSTANCEOF関数を使用して、型に基づいて異なるプロパティを選択します。

  SELECT 
    CASE 
      WHEN INSTANCEOF(item, com.mycompany.Service) THEN serviceName?
      WHEN INSTANCEOF(item, com.mycompany.Product) THEN productName? 
     END
  FROM OrderEvent

INSTANCEOF関数は、INSTANCEOFで調査した式がnullを返す場合はfalseを返します。

型パラメータに使用できる値は以下のとおりです。

int、long、byte、short、char、double、float、stringの任意のJava組込み型(stringは、java.lang.Stringの短縮表記です)。型名では大文字と小文字が区別されません。たとえば、次の関数は動的なpriceプロパティがfloat型またはdouble型であるかどうかを調べます。
```
  INSTANCEOF(price?, double, float)
```
調査するクラスの完全修飾クラス名。例:
```
  INSTANCEOF(product, org.myproducer.Product)
```

型パラメータ・リストに使用できる値は以下のとおりです。

INSTANCEOF関数ではイベント・クラスのスーパークラス、およびスーパークラスによって直接または間接的に実装されたすべてのインタフェースが考慮されます。

4.1.7 CAST関数

CAST関数は式の戻り値の型を目的の型にキャストします。関数は2つのパラメータを受け取ります。最初のパラメータはプロパティ名、またはキャストする値が返される式です。第2パラメータはキャストする型です。

第2の型パラメータに使用できる値は以下のとおりです。

int、long、byte、short、char、double、float、stringの任意のJava組込み型(stringは、java.lang.Stringの短縮表記です)。型名では大文字と小文字が区別されません。例:
```
  cast(price, double)
```
キャストするクラスの完全修飾クラス名。例:
```
  cast(product, org.myproducer.Product)
```

CAST関数は多くの場合、動的な(チェックされていない)プロパティの型を提供するために使用されます。動的プロパティとはコンパイル時に型が不明なプロパティです。これらのプロパティの型は常にjava.lang.Objectです。

次の例は、CAST関数を使用してOrderEventでitemの動的なpriceプロパティをdouble値にキャストする方法を示します。

  SELECT CAST(item.price?, double) 
  FROM OrderEvent

CAST関数は、式の結果を目的の型にキャストできない場合または式の結果自体がnullである場合、null値を返します。

CAST関数には、次の型変換ルールが適用されます。

すべての数値型の場合、CAST関数は必要であれば数値型の変換にjava.lang.Numberを使用します。
stringまたはjava.lang.Stringへのキャストの場合、CAST関数は式の結果に対してtoStringを呼び出します。
アプリケーション・オブジェクトを含む他のオブジェクトへのキャストの場合、CAST関数ではJavaクラスのスーパークラス、およびスーパークラスによって直接または間接的に実装されたすべてのインタフェースが考慮されます。

4.1.8 EXISTS関数

EXISTS関数は、関数へのパラメータで指定された動的プロパティがイベント内に存在するかどうかを示すブール値を返します。EXISTS関数は唯一のパラメータとして1つの動的プロパティ名を受け取ります。

動的な(チェックされていない)プロパティでEXISTS関数を使用します。動的プロパティとはコンパイル時に型が不明なプロパティです。動的プロパティは、動的プロパティがイベントに存在しない場合、または動的プロパティが存在しても値がnullである場合、null値を返します。

EXISTS関数を使用した次の例では、serviceNameプロパティを持つオブジェクトがitemプロパティに含まれている場合、trueが返されます。itemプロパティがnullである場合、またはserviceNameというプロパティを持つオブジェクトがitemプロパティに含まれていない場合は、falseが返されます。

  SELECT EXISTS(item.serviceName?) 
  FROM OrderEvent

4.2 集約関数

集約関数には、SUM、AVG、COUNT、MAX、MIN、MEDIAN、STDDEV、AVEDEVがあります。集約関数を使用してイベント・プロパティのデータを計算および要約できます。たとえば、直前の30秒間のすべての株価表示イベントの合計額を算出する場合は、以下のようになります。

  SELECT SUM(price) 
  FROM StockTickEvent RETAIN 30 SECONDS

集約関数の構文は、以下のとおりです。

  aggregate_function( [ALL | DISTINCT] expression)

イベント・ストリーム・ウィンドウや他のビュー内のすべてのイベント、または1つ以上のイベントのグループに集約関数を適用できます。EPLでは、集約関数が適用されるイベント・セットごとに1つの値が生成されます。

式は通常、イベント・プロパティ名です。ただし、定数、関数、または算術演算子でつながれたイベント・プロパティ名、定数、関数の任意の組み合わせを使用できます。

たとえば、価格が倍増したときに直前の30秒間のすべての株価表示イベントの平均額を算出する場合は、以下のようになります。

  SELECT AVG(price * 2) 
  FROM StockTickEvent RETAIN 30 SECONDS

省略可能なキーワードDISTINCTをすべての集約関数とともに使用して、集約関数が適用される前に重複値を消去できます。デフォルトは、すべてのイベントで操作を実行する省略可能なキーワードALLです。

MINおよびMAX集約関数は単一行関数と同様に使用できます。使用方法は、4.1.1項「MIN関数とMAX関数」を参照してください。

以下の表に、集約関数の構文および生成される結果を示します。

表4-2 集約関数

集約関数	結果
SUM([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の合計。式に応じて、`long`、`double`、`float`または`integer`型の値を返します。
AVG([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の平均。`double`型の値を返します。
COUNT([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)null以外の値の個数。`long`型の値を返します。
COUNT(*)	イベント数(`long`型の値を返します)。
MAX([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の最大値。式自体で返される値と同じ型の値を返します。
MIN([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の最小値。式自体で返される値と同じ型の値を返します。
MEDIAN([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の中央値。`double`型の値を返します。
STDDEV([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の標準偏差。`double`型の値を返します。 Oracle Event Processingでは、数学上の精密な定義のかわりに標本標準偏差と呼ばれる共通基準をSTDDEVの内部実装に採用しています。Oracle Event Processingで使用されているSTDDEVの定義は以下のとおりです。 stddev(x) = (1/(N-1) * SUM{i=1 ... n}(xi - xavg) ) ^ (1/2)
AVEDEV([ALL\|DISTINCT] expression)	`expression`に含まれる(個別の)値の平均偏差。`double`型の値を返します。 Oracle Event Processingで使用されているAVEDEVの定義は以下のとおりです。 avedev(x) = 1/n * SUM{i=1 .. . n} (x_i ? xavg)
TREND(expression)	`expression`の連続的な上昇ティック(正の数)、下降ティック(負の数)または変化なし(ゼロ)。

SELECT句およびHAVING句の中で集約関数を使用できます。WHERE句では集約関数を使用できませんが、WHERE句を使用して集約関数が適用されるイベントを制限できます。次の問合せでは、銘柄にかかわらず直前の10件の株価表示イベントについて、銘柄ACMEのみに対し株価表示イベントの平均額と合計額を計算します。

  SELECT 'ACME stats' AS title, AVG(price) AS avgPrice, SUM(price) AS sumPrice
  FROM StockTickEvent RETAIN 10 EVENTS
  WHERE symbol='ACME'

前述の例では、要素10の長さのウィンドウはWHERE句の影響を受けず、銘柄に関係なくすべてのイベントが長さのウィンドウに入れられ、ウィンドウから出されます。直前の10件のACMEイベントのみが必要な場合は、以下のようにMATCHING句を追加する必要があります。

  SELECT 'ACME stats' AS title, AVG(price) AS avgPrice, SUM(price) AS sumPrice
  FROM (SELECT * FROM StockTickEvent WHERE symbol='ACME') 
  RETAIN 10 EVENT

集約関数は任意の型のイベント・プロパティまたは式で使用できますが、以下の制限があります。

SUM、AVG、MEDIAN、STDDEV、AVEDEVは数値のイベント・プロパティのみで使用できます。

EPLでは、集約関数が動作するイベント・プロパティまたは式で返されるnull値はすべて無視されますが、例外的にCOUNT(*)関数ではnull値も考慮されます。データ・セットにイベントが含まれていない場合、またはデータ・セット内のすべてのイベントの集約式にnull値しか含まれていない場合、すべての集約関数はnullを返します。

集約ユーザー定義関数を作成することもできます。詳細は、4.3項「ユーザー定義関数」を参照してください。

4.3 ユーザー定義関数

ユーザー定義関数は、任意の場所で式自体として呼び出したり、式の内部で呼び出すことができます。関数は、文の作成時にクラス・ローダーによって解決可能なパブリック静的メソッドである必要があります。エンジンは文の作成時に関数の参照を解決し、パラメータの型を検証します。

注意:

EPL問合せでは多重呼出し不変のユーザー定義関数のみを使用できます。つまり、ユーザー定義関数を複数呼び出しても結果は変更されません。

次の例では、クラスMyClassで、2つのパラメータを受け取り、doubleなどの数値型を返すパブリック静的メソッドmyFunctionが公開されていると想定します。

  SELECT 3 * MyClass.myFunction(price, volume) as myValue
  FROM StockTick RETAIN 30 SECONDS

次の例で示すように、ユーザー定義関数では配列パラメータも使用できます。生成される配列の型の詳細は、3.6項「配列定義演算子」で説明しています。

  SELECT * 
  FROM RFIDEvent RETAIN 10 MINUTES
  WHERE com.mycompany.rfid.MyChecker.isInZone(zone, {10, 20, 30})

Oracle Event Processingは単一行および集約ユーザー定義関数の両方をサポートします。

詳細は、『Oracle Fusion Middleware Oracle Event Processing for Eclipse開発者ガイド』のwlevs:functionに関する項を参照してください。