4 EPL リファレンス : 関数

この節では、以下の項目について説明します。

• 節 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	式で返される値の型が指定されたいずれかの値であるかどうかを示す boolean 値を返します。	節 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 CEP では、数学上の精密な定義の代わりに「標本標準偏差」と呼ばれる共通基準を STDDEV の内部実装に採用しています。Oracle CEP で使用されている STDDEV の定義は以下のとおりです。 stddev(x) = (1/(N-1) * SUM{i=1 ... n}(xi - xavg) ) ^ (1/2)
AVEDEV([ALL|DISTINCT] expression)	expression に含まれる (個別の) 値の平均偏差。double 型の値を返します。 Oracle CEP で使用されている 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 CEP では、単一行と集約の両方のユーザ定義関数をサポートします。

詳細については、『Oracle CEP IDE Eclipse 開発者ガイド』の「wlevs:function」を参照してください。