The syntax for enumeration methods is the same syntax as for any chained invocation:

input_coll.enum_method_name( [method_parameter [, method_parameter [,...]]])
	  .[ [enum_method_name(...) [...]] | property_name] 

Following the input_coll input collection (options outlined below), is the . (dot) operator and the enum_method_name enumeration method name. It follows in parenthesis a comma-separated list of method parameter expressions. Additional enumeration methods can be chained thereafter. An event property name can follow for those enumeration methods returning an event-typed (non-scalar) element.

If the method parameter is a lambda expression with a single lambda-parameter, specify the lambda-parameter name followed by the => lambda operator and followed by the expression. The synopsis for use with a single lambda-parameter is:

method_parameter: lambda_param => lambda_expression

If the method parameter is a lambda expression with two or more lambda-parameters, specify the lambda parameter names in parenthesis followed by the => lambda operator followed by the expression. The synopsis for use with multiple lambda-parameters is:

method_parameter: (lambda_param [,lambda_param [,...]]) => lambda_expression

Generally for lambda expressions, the runtime applies the lambda expression to each element in the input collection. The expression yields a result that, depending on the particular enumeration method, is used for aggregation, as a filter or for output, for example.

Let's look at a statement that employs the where enumeration method and a lambda expression. This example returns items that have a (x, y) location of (0, 0):

select items.where(i => i.location.x = 0 and i.location.y = 0) as zeroloc
from LocationReport

As enumeration methods can be chained, this selection is equivalent:

select items.where(i => i.location.x = 0).where(i => i.location.y = 0) as zeroloc
from LocationReport

According to above statement the runtime outputs in field zeroloc a collection of Item objects matching the condition.

The where enumeration method has a second version that has two lambda-parameters. The second parameter is the name of the index property which represents the current index of the element within the collection.

This sample statement returns a collection that consists of the first 3 items. This sample statement does not use the item lambda parameter:

select items.where( (item, indexElement) => indexElement < 3) as firstThreeItems
from LocationReport

All enumeration methods that have a lambda expression as a parameter allow the lambda expression to declare index and size formal parameters. Index is always the second formal parameter. Size is always the third formal parameter and must appear with the index formal parameter.

The synopsis for passing the index of each collection element to the lambda expression is:

method_parameter: (lambda_param,index_lambda_param) => lambda_expression

The index value starts at zero for the first item.

For example, the next lambda expression concatenates to each element an underscore and the index of each element:

{'A', 'B', 'C'}.selectFrom( (v, i) => v || '_' || Integer.toString(i))   // Returns {'A_0', 'B_1', 'C_2'}

The synopsis for passing the index of each collection element as well as the size of the collection to the lambda expression is:

method_parameter: (lambda_param, index_lambda_param, size_lambda_param) => lambda_expression

The following lambda expression concatenates to each element the index and size separated by underscore:

{'A', 'B', 'C'}.selectFrom( (v, i, s) => v || '_' || Integer.toString(i) || '_' || Integer.toString(s))   // Returns {'A_0_3', 'B_1_3', 'C_2_3'}

It is not necessary to use classes for event representation. The example above applies the same to Object-array, Map or XML underlying events.

For most enumeration methods the input can be any collection of events, scalar values or objects. For some enumeration methods limitations apply that are documented below. For example, the sumOf enumeration method requires a collection of numeric scalar values if used without parameters. If the input to sumOf is a collection of events or scalar values the enumeration method requires a lambda expression as parameter that yields the numeric value to use to compute the sum.

Many examples of this section operate on the collection returned by the event property items in the LocationReport event class. There are many other inputs yielding collections as listed below. Most examples herein use an event property as a input simply because the example can thus be brief and does not need to refer to a subquery, named window, table or other concept.

For enumeration methods that return a collection, for example where and orderBy, the runtime outputs an implementation of the Collection interface that contains the selected value(s). The collection returned must be considered read-only. As Java does not allow resettable iterators, the Collection interface allows more flexibility to query size and navigate among collection elements. We recommend against down-casting a collection returned by the runtime to a more specific subclass of the Collection interface.

For enumeration methods that return an element, for example firstOf, lastOf, minBy and maxBy the runtime outputs the scalar value or the underlying event if operating on events. You may add an event property name after the enumeration method to return a property value.

Enumeration methods generally retain the order of elements provided by the collection.

The following restrictions apply to enumeration methods:

Subqueries can return the rows of another stream's data window or rows from a named window or table. By providing a where-clause the rows returned by a subquery can be correlated to data provided by stream(s) in the from-clause. See Section 5.11, “Subqueries”.

A subquery that selects (*) wildcard provides a collection of events as input. A subquery that selects a single value expression provides a collection of scalar values as input. Subqueries that select multiple value expressions are not allowed as input to enumeration methods.

The following example uses a subquery to retrieve all zones for each location report item where the location falls within the rectangle of the zone. Please see a description of example events and functions above.

select assetId,
  (select * from Zone#unique(name)).where(z => inrect(z.rectangle, location)) as zones
from Item

You may place the subquery in an expression declaration to reuse the subquery in multiple places of the same statement.

This sample EPL declares the same statement as above in an expression declaration:

expression myquery {itm =>
  (select * from Zone#unique(name)).where(z => inrect(z.rectangle, itm.location))
}
select assetId, myquery(item) as subq, 
    myquery(item).where(z => z.zone = 'Z01') as assetItem
from Item as item

The above statement also demonstrates how an enumeration method, in the example the where-method, can be run across the results returned by a subquery in an expression declaration.

Place a single column in the subquery select-clause to provide a collection of scalar values as input.

The next example selects all names of zones and orders the names returning an order collection of string names every 30 seconds:

select (select name from Zone#unique(name)).orderBy() as orderedZones
from pattern[every timer:interval(30)]

The next example utilizes a subquery that counts zone events per name and finds those that have a count greater than 1:

select (select name, count(*) as cnt from Zone#keepall group by name)
  .where(v => cnt > 1) from LocationReport]

When the subquery selects a single column that is itself an event, the result of the subquery is a collection of events of that type and can provide input to enumeration methods.

For example:

create schema SettlementEvent (symbol string);

create schema PriceEvent (symbol string, price double);

create schema OrderEvent (orderId string, pricedata PriceEvent);

select (select pricedata from OrderEvent#unique(orderId))
  .anyOf(v => v.symbol = 'GE') as has_ge from SettlementEvent(symbol = 'GE')

Note that the runtime can cache intermediate results thereby is not forced to re-evaluate the subquery for each occurrence in the select-clause.

Named windows are globally-visible data windows. See Section 6.2, “Named Window Usage”.

You may specify the named window name as input for an enumeration method and can optionally provide a correlation where-clause. The syntax is equivalent to a sub-query against a named window but much shorter.

Synopsis:

named-window-name[(correlation-expression)].enum-method-name(...)

When selecting all events in a named window you do not need the correlation-expression. To select a subset of data in the named window, specify a correlation-expression. From the perspective of best runtime performance, a correlation expression is preferred to reduce the number of rows returned.

The following example first declares a named window to hold the last zone event per zone name:

create window ZoneWindow#unique(name) as Zone

Then you create a statement to insert zone events that arrive to the named window:

insert into ZoneWindow select * from Zone

Finally this statement queries the named window to retrieve all zones for each location report item where the location falls within the rectangle of the zone:

select ZoneWindow.where(z => inrect(z.rectangle, location)) as zones from Item

If you have a filter or correlation expression, append the expression to the named window name and place in parenthesis.

This slightly modified statement is the example above except that it adds a filter expression such that only zones with name Z1, Z2 or Z3 are considered:

select ZoneWindow(name in ('Z1', 'Z2', 'Z3')).where(z => inrect(z.rectangle, location)) as zones 
from Item

You may prefix property names provided by the named window with the name to disambiguate property names.

This sample statement prefixed the name property and returns the count of matching zones:

select ZoneWindow(ZoneWindow.name in ('Z1', 'Z2', 'Z3')).countof()) as zoneCount
from Item

The runtime internally interprets the shortcut syntax and creates a subquery from it. Thus all indexing and query planning for subqueries against named windows apply here as well.

Tables are globally-visible data structures. See Section 6.3, “Table Usage”.

Tables can hold aggregation state such as the window and sorted aggregation state.

The example EPL below declares a table to hold StockTick events in a column named theTicks:

create table MyTable(theTicks window(*) @type(StockTick))

The table column can be input to an enumeration method, for example:

select MyTable.theTicks.anyOf(v=> price > 100) from MyEvent

Event properties that are a collection, array or iterable of scalar values or objects can be an input to enumeration methods. Event properties that hold a collection or array of events can be an input to enumeration methods. Use @eventbean in the select-clause with insert into to select events.

The LocationReport event from the example contains a list of Item events. Any indexed property (list, array, collection, iterable) is eligible for use as input to an enumeration method. If the indexed property contains non-scalar objects the objects are treated as events and can be used as input to enumeration methods as a collection of events.

The next sample statement returns items that are less than 20 units away from the center, taking the items event property provided by each LocationReport event as input:

select items.where(p => distance(0, 0, p.location.x, p.location.y) < 20) as centeritems
from LocationReport

The next three statements declare an OrderEvent type that contains OrderDetail events and a statement that enumerates order detail:

create schema OrderDetail(itemId string)

create schema OrderEvent(details OrderDetail[])

select details.where(i => i.itemId = '001') from OrderEvent

The first statement in this two-statement explanation selects the events that have a price of greater than 100 from a 10-second time window if the count of events is at least 10. It inserts the events into stream TicksLarge. The use of @eventbean means that the event property ticksLargePrice holds events (and not underlying objects). The second statement further filters the events and returns a collection of events that have price of less than 100.

insert into TicksLarge select window(*).where(e => e.price > 100) @eventbean as ticksLargePrice
from StockTick#time(10) having count(*) > 10

select ticksLargePrice.where(e => e.price < 200) as ticksLargeLess200 from TicksLarge

Event aggregation functions return an event or multiple events. They are aggregation functions and as such sensitive to the presence of group by. See Section 10.2.2, “Event Aggregation Functions”.

You can use window, first or last event aggregation functions as input to an enumeration method. Specify the * wildcard as the parameter to the event aggregation function to provide a collection of events as input. Or specify a property name as the parameter to event aggregation function to provide a collection of scalar values as input.

You can use the sorted, maxby, minby, maxbyever or minbyever event aggregation functions as input to an enumeration method. Specify one or more criteria expressions that provide the sort order as parameters to the event aggregation function.

Aggregation methods are used in conjunction with aggregations and can also provide input to an enumeration method. Please go to Section 13.2.5, “Using Dot to Enumerate Events”.

In this example statement the window(*) aggregation function returns the last 10 seconds of item location reports for the same asset id as the incoming event. Among that last 10 seconds of events for the same asset id, the enumeration method returns those item location reports where the distance to center is less than 20, for each arriving Item event.

Sample statement:

select window(*).where(p => distance(0, 0, p.location.x, p.location.y) < 20) as centeritems
from Item(type='P')#time(10) group by assetId

The next sample statement instead selects the asset id property of all events and returns an ordered collection:

select window(assetId).orderBy() as orderedAssetIds
from Item#time(10) group by assetId

The following example outputs the 5 highest prices per symbol among the last 10 seconds of stock ticks:

select sorted(price desc).take(5) as highest5PricesPerSymbol
from StockTick#time(10) group by symbol

The prev, prevwindow and prevtail single-row functions allow access into a stream's data window however are not aggregation functions and and as such not sensitive to the presence of group by. See Section 10.1.15, “The Previous-Window Function”.

When using any of the prev single-row functions as input to a built-in enumeration method you can specify the stream name as a parameter to the function or an event property. The input to the enumeration method is a collection of events if you specify the stream name, or a collection of scalar value if you specify an event property.

In this example statement the prevwindow(stream) single-row function returns the last 10 seconds of item location reports, among which the enumeration method filters those item location reports where the distance to center is less than 20, for each Item event that arrived in the last 10 seconds considering passenger-type Item events only (see filter type = 'P').

Sample statement:

select prevwindow(items)
    .where(p => distance(0, 0, p.location.x, p.location.y) < 20) as centeritems
from Item(type='P')#time(10) as items

This sample statement demonstrates the use of the prevwindow function to return a collection of scalar values (collection of asset id) as input to orderby:

select prevwindow(assetId).orderBy() as orderedAssetIds
from Item#time(10) as items

Your single-row or user-defined function can return either an array or any collection that implements either the Collection or Iterable interface. For arrays, the array component type and for collections, the collection or iterable generic type should be the class providing event properties.

As an example, assume a ZoneFactory class exists and a static method getZones() returns a list of zones to filter items, for example:

public class ZoneFactory {
  public static Iterable<Zone> getZones() {
    List<Zone> zones = new ArrayList<Zone>();
    zones.add(new Zone("Z1", new Rectangle(0, 0, 20, 20)));
    return zones;
  }
}

Import the class through runtime or static configuration, or add the method above as a plug-in single-row function.

The following statement returns for each Item event all zones that the item belongs to:

select ZoneFactory.getZones().where(z => inrect(z.rectangle, item.location)) as zones
from Item as item

If the class and method were registered as a plug-in single-row function, you can leave the class name off, for example:

select getZones().where(z => inrect(z.rectangle, item.location)) as zones
from Item as item

Your single-row or user-defined function can also return an array, collection or iterable or scalar values.

For example, the static method getZoneNames() returns a list of zone names:

public static String[] getZoneNames() { 
  return new String[] { "Z1", "Z2"};
}

The following statement returns zone names every 30 seconds and excludes zone Z1:

select getZoneNames().where(z => z != "Z1")
from pattern[every timer:interval(30)]

An enum type can also be a useful source for enumerable values.

The following sample Java declares an enum type EnumOfZones:

public enum EnumOfZones {
  ZONES_OUTSIDE(new String[] {"z1", "z2"}),
  ZONES_INSIDE(new String[] {"z3", "z4"})

  private final String[] zones;

  private EnumOfZones(String[] zones) {
	  this.zones = zones;
  }

  public String[] getZones() {
    return zones;
  }
}

A sample statement that utilizes the enum type is shown next:

select EnumOfZones.ZONES_OUTSIDE.getZones().anyOf(v => v = zone) from Item

A declared expression may return input data for an enumeration method.

The below statement declares an expression that returns all passenger location reports among the items in the location report event in a column named passengerCollection. The statement uses the result returned by the declared expression a second time to filter through the list returning the passenger location report where the asset id is a given value in a column named passengerP01.

Sample statement:

expression passengers {
  lr => lr.items.where(l => l.type='P')
}
select passengers(lr) as passengerCollection,
  passengers(lr).where(x => assetId = 'P01') as passengerP01
from LocationReport lr

The runtime applies caching techniques to avoid re-evaluating the declared expression multiple times.

A variable may provide input data for an enumeration method.

This constant of array type carries a list of invalid zones:

create constant variable string[] invalid_zones = { 'Z1', 'Z2' };

Sample statement:

select invalid_zones.anyOf(v => v = name) as flagged from Zone

A substitution parameter may provide input data for an enumeration method. The value of the parameter must be array-typed.

Sample statement:

select ?.anyOf(v => v = name) as flagged from Zone

In a match-recognize pattern, the term group variables refers to identifiers that can collect multiple events.

This example assumes an order event type and each order has an item id. This sample match-recognize pattern finds a sequence of order events that concludes with an item id matching any of the collected item ids since the last pattern match:

select * from Order
match_recognize (
  measures A as a_array, B as b
  pattern (A* B)
  define
  B as A.anyOf(v=> v.itemId = B.itemId)
)

Both the define and the measures clause can contain expressions utilizing enumeration methods.

In an EPL pattern, the repeat and repeat-until pattern operators may collect multiple events.

The following pattern fires when two order events arrive followed by an order amendment event that has an amount larger than the largest amount of any of the preceding order events:

select * from pattern [
  ([2] a=Order) -> b=OrderAmendment(amount > a.max(i => i.amount))
]

The aggregate enumeration method takes an expression providing the initialization value (seed) and an accumulator lambda expression. The return value is the final accumulator value.

Via the aggregate method you may perform a calculation over elements. The method initializes the aggregated value by evaluating the expression provided in the first parameter. The method then calls the lambda expression of the second parameter once for each element in the input. The lambda expression receives the last aggregated value and the element from the input. The result of the expression replaces the previous aggregated value and returns the final result after completing all elements. The collection element index and collection size are additional optional formal parameters.

Some expression examples with scalar values as input and with the optional collection element index and collection size formal parameters are:

{1, 2, 3}.aggregate(0, (result, value) => result + value)  // Returns 6
{1, 2, 3}.aggregate(0, (result, value, index) => result + value + index*10)  // Returns 36 = 1 + 12 + 23
{1, 2, 3}.aggregate(0, (result, value, index, size) => result + value + index*10 + size*100)  // Returns 936 = 301 + 312 + 323

The example below aggregates price of each OrderEvent in the last 10 seconds computing a total price:

// Initialization value is zero.
// Aggregate by adding up the price.
select window(*).aggregate(0, (result, order) => result + order.price) as totalPrice
from OrderEvent#time(10)

In the statement above, the initialization value is zero, result is used for the last aggregated value and order denotes the element that the expression adds the value of the price property.

This example aggregation builds a comma-separated list of all asset ids of all items:

select items.aggregate('', 
  (result, item) => result || (case when result='' then '' else ',' end) || item.assetId) as assets			
from LocationReport

In above statement, the empty string represents the initialization value. The name result is used for the last aggregated value and the name item is used to denote the element.

The type value returned by the initialization expression must match to the type of value returned by the accumulator lambda expression.

If the input is null the method returns null. If the input is empty the method returns the initialization value.

The allof enumeration method determines whether all elements satisfy the predicate condition.

The method takes a single parameter: The predicate lambda expression that must yield a Boolean result. The enumeration method applies the lambda expression to each element and if the expression returns true for all elements, the method returns true.

An expression example with scalar values:

{1, 2, 3}.allOf(v => v > 0)    // Returns true as all values are > 0
{1, 2, 3}.allOf(v => v > 1)    // Returns false
{1, 2, 3}.allOf( (v, index) => case when index < 2 then true else v > 1 end)    // Returns true
{1, 2, 3}.allOf( (v, index, size) => v > 1 or size >= 3)    // Returns true

The statement below returns true when all items are within 1000 unit distance of center:

select items.allof(i => distance(i.location.x, i.location.y, 0, 0) < 1000) as centered			
from LocationReport

If the input is null the method returns null. If the input is empty the method returns true.

The anyof enumeration method determines whether any element satisfies the predicate condition.

The only parameter is the predicate lambda expression that must yield a Boolean result. The enumeration method applies the lambda expression to each element and if the expression returns true for all elements, the method returns true.

An expression example with scalar values:

{1, 2, 3}.anyOf(v => v > 0)    // Returns true
{1, 2, 3}.anyOf(v => v > 1)    // Returns true
{1, 2, 3}.anyOf(v => v > 3)    // Returns false
{1, 2, 3}.anyOf( (v, index) => case when index < 2 then false else v = 3 end)    // Returns true
{1, 2, 3}.anyOf( (v, index, size) => v > 100 or size >= 3)    // Returns true

The statement below return true when any of the items are within 10 unit distance of center:

select items.anyof(i => distance(i.location.x, i.location.y, 0, 0) < 10) as centered			
from LocationReport

If the input is null the method returns null. If the input is empty the method returns false.

The arrayOf enumeration method returns values as an array.

If no value-selector lambda expression is provided, the method accepts only scalar input and returns the array of scalar values.

If a value-selector lambda expression is provided, the enumeration method invokes a value-selector lambda expression on each element and returns the result values as an array. The type of array returned follows the return type of the lambda expression that was provided as the sole parameter.

The next expressions are examples with scalar input:

{1, 2, 3}.arrayOf()   // Returns [1, 2, 3] as an array of Integer
{1, 2, 3}.arrayOf(v => v+1)   // Returns [2, 3, 4] as an array of Integer
{1, 2, 3}.arrayOf((v, index) => v+index)   // Returns [1, 3, 5] as an array of Integer
{1, 2, 3}.arrayOf((v, index, size) => v+index+size)   // Returns [4, 6, 8] as an array of Integer

The next statement returns the array of distances of any item from center:

select items.arrayOf(i => distance(i.location.x, i.location.y, 0, 0)) as distancesArray
from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty array.

The average enumeration method computes the average of scalar values. If passing a projection lambda expression the method computes the average obtained by invoking the projection lambda expression on each element.

The method takes a projection lambda expression yielding a numeric value as a parameter. It applies the lambda expression to each element and computes the average of the result, returning a Double value. A BigDecimal is returned for expressions returning BigInteger or BigDecimal.

The following are expression examples with scalar values:

{1, 2, 3}.average()    // Returns 2
{1, 2, 3}.average(v => v+1)    // Returns 3
{1, 2, 3}.average((v, index) => v+10*index)    // Returns 12 = (1+12+23)/3
{1, 2, 3}.average((v, index, size) => v+10*index + 100*size)    // Returns 312 = (301+312+323)/3

The statement as shown next computes the average distance from center among all items in the location report event:

select items.average(i => distance(i.location.x, i.location.y, 0, 0)) as avgdistance
from LocationReport

If the input is null the method returns null. If the input is empty the method returns double zero or BigDecimal zero. For BigDecimal precision and rounding, please see Section 17.5.6.5, “Math Context”.

The countof enumeration method returns the number of elements, or the number of elements that satisfy a condition.

The enumeration method has two versions: The first version takes no parameters and computes the number of elements. The second version takes a predicate lambda expression that must yield Boolean true or false, and computes the number of elements that satisfy the condition.

An expression example with scalar values:

{1, 2, 3}.countOf()    // Returns 3
{1, 2, 3}.countOf(v => v < 2)    // Returns 1
{1, 2, 3}.countOf( (v, index) => v > index)    // Returns 3
{1, 2, 3}.countOf( (v, index, size) => v >= size)    // Returns 1

The next sample statement counts the number of items:

select items.countOf() as cnt from LocationReport

This example statement counts the number of items that have a distance to center that is less than 20 units:

select items.countOf(i => distance(i.location.x, i.location.y, 0, 0) < 20) as cntcenter
from LocationReport

If the input is null the method returns null. If the input is empty the method returns integer zero.

The distinctOf enumeration method returns distinct elements.

The enumeration method can take a single key-selector lambda expression as parameter and returns distinct elements according to the key yielded by the expression. For same-value keys, distinct returns the first element for that key. Further detail on key expressions can be found at Section 5.2.13, “Composite Keys and Array Values as Keys”.

An expression example with scalar values:

{2, 3, 2, 1}.distinctOf()   // Returns {2, 3, 1}
{2, 3, 2, 1}.distinctOf(v => case when v > 1 then 0 else -1 end)   // Returns {2, 1}
{2, 3, 2, 1}.distinctOf((v, index) => case when index = 0 then 1 else 2 end)   // Returns {2, 3}
{2, 3, 2, 1}.distinctOf((v, index, size) => case when index+1=size then 1 else 2 end)   // Returns {2, 1}

This example returns items distinct by item id returning the first item for each distinct item id:

select items.distinctOf(i => itemId) as itemsNearFirst
from LocationReport

The key-selector lambda expression, when provided, must return a comparable type: Any primitive or boxed or Comparable type is permitted.

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The except enumeration method forms a set difference of the input elements with the elements that the parameter expression yields.

The enumeration method takes a single parameter that must itself return a collection of events, objects or scalar values. The method returns the elements of the first collection that do not appear in the second collection.

An expression example with scalar values:

{1, 2, 3}.except({1})   // Returns {2, 3}

The following statement compares the items of the last location report against all items in the previous 10 location reports, and reports for each combination only those items in the current item report that are not also in the location report compared to:

select za.items.except(zb.items) as itemsCompared 
from LocationReport as za unidirectional, LocationReport#length(10) as zb

If the input is null the method returns null. For scalar values and objects equals-semantics apply.

The firstOf enumeration method returns the first element or the first element that satisfies a condition.

The method has two versions: The first version takes no parameters and returns the first element. The second version takes a predicate lambda expression yielding true or false. It applies the lambda expression to each element and returns the first element for which the expression returns true. The return type is the element itself and not a collection. You may append a property name to return the property value for the first element.

The example expressions with scalar values are:

{1, 2, 3}.firstOf()   // Returns 1
{1, 2, 3}.firstOf(v => v / 2 > 1)   // Returns 3
{1, 2, 3}.firstOf((v, index) => index = 1)   // Returns 2
{1, 2, 3}.firstOf((v, index, size) => v = size-1)   // Returns 2

In the following EPL sample the statement returns the first item that has a distance to center that is less than 20 units:

select items.firstof(i => distance(i.location.x, i.location.y, 0, 0) < 20) as firstcenter
from LocationReport

The next sample EPL returns the first item's asset id:

select items.firstof().assetId as firstAssetId from LocationReport

If the input is null, empty or if none of the elements match the condition the method returns null.

The groupby enumeration method groups the elements according to a specified key-selector lambda expression. There are two version of the groupby method.

The first version of the method takes a key-selector lambda expression and returns a Map of key with each value a list of objects, one for each distinct key that was encountered. The result is a Map<Object, Collection<Object>> wherein object is the event underlying object.

The second version of the method takes a key-selector lambda expression and value-selector lambda expression and returns a Map of key with each value a list of values, one for each distinct key that was encountered. The result is a Map<Object, Collection<Object>> wherein object is the result of applying the value-selector expression.

The example expressions with scalar values are:

{1, 2, 3}.groupby(k => 'K' || Integer.toString(k))   // Returns map {K1=[1], K2=[2], K3=[3]}
{1, 2, 3}.groupby(k => 'K' || Integer.toString(k), v => 'V' || Integer.toString(v))   // Returns map {K1=[V1], K2=[V2], K3=[V3]}
{1, 2, 3}.groupby(
  (k, i) => 'K' || Integer.toString(k) || "_" || Integer.toString(i), 
  (v, i) => 'V' || Integer.toString(v) || "_" || Integer.toString(i)
  )  // Returns map {K1_0=[V1_0], K2_1=[V2_1], K3_2=[V3_2]}
{1, 2, 3}.groupby(
  (k, i, s) => 'K' || Integer.toString(k) || "_" || Integer.toString(s), 
  (v, i, s) => 'V' || Integer.toString(v) || "_" || Integer.toString(s)
  )  // Returns map {K1_3=[V1_3], K2_3=[V2_3], K3_3=[V3_3]}

The next statement filters out all luggage items using a where method and then groups by the luggage's passenger asset id. It returns a map of passenger asset id and the collection of luggage items for each passenger:

select items.where(type='L').groupby(i => assetIdPassenger) as luggagePerPerson
from LocationReport

The statement shown below generates a map of item asset id and distance to center:

select items.groupby(
    k => assetId, v => distance(v.location.x, v.location.y, 0, 0)) as distancePerItem
from LocationReport

If the input is null the method returns null. Null values as key and value are allowed.

The intersect enumeration method forms a set intersection of the input elements with the elements that the parameter expression yields.

The enumeration method takes a single parameter that must itself return a collection of events, objects or scalar values. The method returns the elements of the first collection that also appear in the second collection.

An expression example with scalar values:

{1, 2, 3}.intersect({2, 3})   // Returns {2, 3}

The following statement compares the items of the last location report against all items in the previous 10 location reports, and reports for each combination all items in the current item report that also occur in the other location report:

select za.items.intersect(zb.items) as itemsCompared 
from LocationReport as za unidirectional, LocationReport#length(10) as zb

If the input is null the method returns null. For scalar values and objects equals-semantics apply.

The lastOf enumeration method returns the last element or the last element that satisfies a condition.

The method has two versions: The first version takes no parameters and returns the last element. The second version takes a predicate lambda expression yielding true or false. It applies the lambda expression to each element and returns the last element for which the expression returns true. The return type is the element itself and not a collection. You may append a property name to return the property value for the last element.

An expression example with scalar values:

{1, 2, 3}.lastOf()   // Returns 3
{1, 2, 3}.lastOf(v => v < 3)   // Returns 2
{1, 2, 3}.lastOf((v, index) => index < 2 )   // Result 2
{1, 2, 3}.lastOf((v, index, size) => index < size - 2 )   // Result 1

In the following EPL sample the statement returns the last item that has a distance to center that is less than 20 units:

select items.lastof(i => distance(i.location.x, i.location.y, 0, 0) < 20) as lastcenter 
from LocationReport

The next sample EPL returns the last item's asset id:

select items.lastof().assetId as lastAssetId from LocationReport

If the input is null, empty or if none of the elements match the condition the method returns null.

The leastFrequent enumeration method returns the least frequent value among a collection of values, or the least frequent value after applying a transform expression to each element.

The method has two versions: The first version takes no parameters and returns the least frequent value. The second version takes a transform lambda expression yielding the value to count occurrences for. The method applies the lambda expression to each element and returns the expression result value with the least number of occurrences. The return type is the type of value in the collection or the type of value returned by the transform lambda expression if one was provided.

An expression example with scalar values:

{1, 2, 3, 2, 1}.leastFrequent()   // Returns 3
{1, 2, 3, 2, 1}.leastFrequent(v => case when v = 3 then 4 else v end)   // Returns 4
{1, 2, 3, 2, 1}.leastFrequent((v, index) => case when index = 2 then 4 else v end)   // Returns 4
{1, 2, 3, 2, 1}.leastFrequent((v, index, size) => case when index = size - 2 then 4 else v end)  // Returns 2

The example EPL below returns the least frequent item type, counting the distinct item types among all items for the current LocationReport event:

select items.leastFrequent(i => type) as leastFreqType from LocationReport

If the input is null or empty the method returns null. The transform expression may also yield null. A null value can be returned as the most frequent value if the most frequent value is null. If multiple values have the same number of occurrences the method returns the first value with the least number of occurrences considering the ordering of the collection.

The max enumeration method returns the maximum value among a collection of values.

If no value-selector lambda expression is provided, the method finds the maximum.

If a value-selector lambda expression is provided, the enumeration method invokes a value-selector lambda expression on each element and returns the maximum value. The type of value returned follows the return type of the lambda expression that was provided as parameter.

An expression example with scalar values:

{1, 2, 3, 2, 1}.max()   // Returns 3
{1, 2, 3, 2, 1}.max(v => case when v >= 3 then 0 else v end)   // Returns 2
{1, 2, 3, 2, 1}.max((v, index) => case when index = 2 then 0 else v end)   // Returns 2
{1, 2, 3, 2, 1}.max((v, index, size) => case when index > size - 4 then 0 else v end)   // Returns 2

The next statement returns the maximum distance of any item from center:

select items.max(i => distance(i.location.x, i.location.y, 0, 0)) as maxcenter 
from LocationReport

The value-selector lambda expression must return a comparable type: Any primitive or boxed type or Comparable type is permitted.

If the input is null, empty or if none of the elements when transformed return a non-null value the method returns null.

The maxBy enumeration method returns the element that provides the maximum value returned by the value-selector lambda expression when applied to each element.

The enumeration method returns the element itself. You may append an event property name to return a property value of the element.

An expression example with scalar values:

{1, 2, 3, 2, 1}.maxby(v => v)   // Result 3
{1, 2, 3, 2, 1}.maxby((v, index) => case when index < 3 then -1 else 0 end)   // Result 2
{1, 2, 3, 2, 1}.maxby((v, index, size) => case when index < size - 2 then -1 else 0 end)   // Result 2

The next statement returns the first item with the maximum distance to center:

select items.maxBy(i => distance(i.location.x, i.location.y, 0, 0)) as maxItemCenter 
from LocationReport

The next sample returns the type of the item with the largest asset id (string comparison) among all items:

select items.maxBy(i => assetId).type as minAssetId from LocationReport

The transform expression must return a comparable type: Any primitive or boxed type or Comparable type is permitted.

If the input is null, empty or if none of the elements when transformed return a non-null value the method returns null.

The min enumeration method returns the minimum value among a collection of values.

If no value-selector lambda expression is provided, the method finds the minimum.

If a value-selector lambda expression is provided, the enumeration method invokes a value-selector lambda expression on each element and returns the minimum value. The type of value returned follows the return type of the lambda expression that was provided as parameter.

Some expression examples with scalar values are:

{1, 2, 3, 2, 1}.min()   // Returns 1
{1, 2, 3, 2, 1}.min(v => v + 1)  // Returns 2
{1, 2, 3, 2, 1}.min((v, index) => v - index)   // Returns -3
{1, 2, 3, 2, 1}.min((v, index, size) => v - size)   // Returns -4

The next statement returns the minimum distance of any item to center:

select items.min(i => distance(i.location.x, i.location.y, 0, 0)) as mincenter 
from LocationReport

The transform expression must return a comparable type: Any primitive or boxed type or Comparable type is permitted.

If the input is null, empty or if none of the elements when transformed return a non-null value the method returns null.

The minBy enumeration method returns the element that provides the minimum value returned by the value-selector lambda expression when applied to each element.

The enumeration method returns the element itself. You may append an event property name to return a property value of the element.

Some expression examples with scalar values are:

{1, 2, 3, 2, 1}.minby(v => v)   // Result 1
{1, 2, 3, 2, 1}.minby((v, index) => case when index < 3 then -1 else 0 end)   // Result 1
{1, 2, 3, 2, 1}.minby((v, index, size) => case when index < size - 2 then -1 else 0 end)   // Result 1

The next statement returns the first item with the minimum distance to center:

select items.minBy(i => distance(i.location.x, i.location.y, 0, 0)) as minItemCenter 
from LocationReport

The next sample returns the type of the item with the smallest asset id (string comparison) among all items:

select items.minBy(i => assetId).type as minAssetId from LocationReport

The transform expression must return a comparable type: Any primitive or boxed or Comparable type is permitted.

If the input is null, empty or if none of the elements when transformed return a non-null value the method returns null.

The mostFrequent enumeration method returns the most frequent value among a collection of values, or the most frequent value after applying a transform expression to each element.

The method has two versions: The first version takes no parameters and returns the most frequent value. The second version takes a transform lambda expression yielding the value to count occurrences for. The method applies the lambda expression to each element and returns the expression result value with the most number of occurrences. The return type is the type of value in the collection or the type of value returned by the transform lambda expression if one was provided.

An expression example with scalar values:

{1, 2, 3, 2, 1, 2}.mostFrequent()   // Returns 2
{1, 2, 3, 2, 1, 2}.mostFrequent(v => case when v = 2 then 10 else v end)   // Returns 10
{1, 2, 3, 2, 1, 2}.mostFrequent((v, index) => case when index > 2 then 4 else v end)   // Returns 4
{1, 2, 3, 2, 1, 2}.mostFrequent((v, index, size) => case when size > 3 then 0 else v end)   // Returns 0

The example EPL below returns the least frequent item type, counting the distinct item types among all items for the current LocationReport event:

select items.leastFrequent(i => type) as leastFreqType from LocationReport

If the input is null or empty the method returns null. The transform expression may also yield null. A null value can be returned as the most frequent value if the most frequent value is null. If multiple values have the same number of occurrences the method returns the first value with the most number of occurrences considering the ordering of the collection.

The orderBy enumeration method sorts elements in ascending order according to a key. The orderByDesc enumeration method sorts elements in descending order according to a key.

The enumeration method takes a single key-selector lambda expression as parameter and orders elements according to the key yielded by the expression. For same-value keys, it maintains the existing order.

An expression example with scalar values:

{2, 3, 2, 1}.orderBy()   // Returns {1, 2, 2, 3}
{2, 3, 2, 1}.orderBy(v => -v)    // Returns {3, 2, 2, 1}
{2, 3, 2, 1}.orderBy((v, index) => index)   // Returns {2, 3, 2, 1}
{2, 3, 2, 1}.orderBy((v, index, size) => case when index < size - 2 then v else -v end)   // Returns {2, 1, 2, 3}

This example orders all items from a location report according to their distance from center:

select items.orderBy(i => distance(i.location.x, i.location.y, 0, 0)) as itemsNearFirst,
  items.orderByDesc(i => distance(i.location.x, i.location.y, 0, 0)) as itemsFarFirst
from LocationReport

The key-selector lambda expression must return a comparable type: Any primitive or boxed or Comparable type is permitted.

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The reverse enumeration method simply reverses the order of elements returning a collection.

An expression example with scalar values:

{2, 3, 2, 1}.reverse()   // Returns {1, 2, 3, 2}

The following EPL reverses the items:

select items.reverse() as reversedItems from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The selectFrom enumeration method transforms each element resulting in a collection of transformed elements.

The enumeration method has two versions. The first version takes only a transformation lambda expression and applies that to each element and returns the result of each transformation as a collection. The second version takes a transformation lambda expression and index for use within the transformation expression.

Use the new operator to yield multiple values for each element, see Section 9.14, “The 'New' Keyword”.

The following are expression examples with scalar values:

{'A','B','C'}.selectFrom(v => '<' || v || '>')   // Returns [<A>, <B>, <C>]
{'A','B','C'}.selectFrom((v, index) => v || '_' || Integer.toString(index))   // Returns [A_0, B_1, C_2]
{'A','B','C'}.selectFrom((v, index, size) => v || '_' || Integer.toString(size))   // Returns [A_3, B_3, C_3]

The next statement returns a collection of asset ids:

select items.selectFrom(i => assetId) as itemAssetIds from LocationReport

This sample statement evaluates each item and returns the asset id as well as the distance from center for each item:

select items.selectFrom(i => 
  new {
    assetId, 
    distanceCenter = distance(i.location.x, i.location.y, 0, 0)
  } ) as itemInfo from LocationReport

The second version of the selectFrom enumeration method also represents the index of the input element starting at zero for the first element.

The example appends the passenger-type and the index returning a string-type value for each item:

select items.selectFrom((p, ind) => p.type || Integer.toString(ind)) from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The sequenceEqual enumeration method determines whether two collections are equal by comparing each element.

The method enumerates the two source collections in parallel and compares corresponding elements by using the equals method to compare. The method takes a single parameter expression that must return a collection containing elements of the same type as the input. The method returns true if the two source sequences are of equal length and their corresponding elements are equal.

An expression example with scalar values:

{1, 2, 3}.sequenceEqual({1})   // Returns false
{1, 2, 3}.sequenceEqual({1, 2, 3})   // Returns true

The following example compares the asset id of all items to the asset ids returned by a method ItemUtil.redListed() which is assumed to return a list of asset id of string type:

select items.selectFrom(i => assetId).sequenceEquals(ItemUtil.redListed()) from LocationReport

If the input is null the method returns null.

The sumOf enumeration method computes the sum. If a projection lambda expression is provided, the method invokes the projection lambda expression on each element and computes the sum on each returned value.

The projection lambda expression should yield a numeric value, BigDecimal or BigInteger value. Depending on the type returned by the projection lambda expression the method returns either Integer, Long, Double, BigDecimal or BigInteger.

An expression example with scalar values:

{1, 2, 3}.sumOf()   // Returns 6
{1, 2, 3}.sumOf(v => v+1)    // Returns 9 = 2+3+4
{1, 2, 3}.sumOf((v, index) => v+index)    // Returns 9 = 1+3+5
{1, 2, 3}.sumOf((v, index, size) => v+index+size)    // Returns 18 = 4+6+8

The following example computes the sum of the distance of each item to center:

select items.sum(i => distance(i.location.x, i.location.y, 0, 0) as totalAllDistances
from LocationReport

If the input is null or empty the method returns null.

The take enumeration method returns a specified number of contiguous elements from the start.

The enumeration method takes a single size (non-lambda) expression that returns an Integer value.

An expression example with scalar values:

{1, 2, 3}.take(2)   // Returns {1, 2}

The following example returns the first 5 items:

select items.take(5) as first5Items from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The takeLast enumeration method returns a specified number of contiguous elements from the end.

The enumeration method takes a single size (non-lambda) expression that returns an Integer value.

An expression example with scalar values:

{1, 2, 3}.takeLast(2)   // Returns {2, 3}

The following example returns the last 5 items:

select items.takeLast(5) as last5Items from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The takeWhile enumeration method returns elements from the start as long as a specified condition is true.

The enumeration method has two versions. The first version takes a predicate lambda expression and the second version takes a predicate lambda expression and index for use within the predicate expression. Both versions return elements from the start as long as the specified condition is true.

An expression example with scalar values:

{1, 2, 3}.takeWhile(v => v < 3)   // Returns {1, 2}
{1, 2, 3}.takeWhile((v,ind) => ind > 2)   // Returns {1, 2}
{1, 2, -1, 4, 5, 6}.takeWhile((v,ind,sz) => ind < sz - 5 and v > 0)   // Returns {1}

This example selects all items from a location report in the order provided until the first item that has a distance to center greater than 20 units:

select items.takeWhile(i => distance(i.location.x, i.location.y, 0, 0) < 20)
from LocationReport

The second version of the where represents the index of the input element starting at zero for the first element.

The next example is similar to the statement above but also limits the result to the first 10 items:

select items.takeWhile((i, ind) => distance(i.location.x, i.location.y, 0, 0) < 20) and ind < 10)
from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The takeWhileLast enumeration method returns elements from the end as long as a specified condition is true.

The enumeration method has two versions. The first version takes a predicate lambda expression and the second version takes a predicate lambda expression and index for use within the predicate expression. Both versions return elements from the end as long as the specified condition is true.

The expression examples with scalar values are:

{1, 2, 3}.takeWhileLast(v => v < 3)   // Returns {} (empty collection)
{1, 2, 3}.takeWhileLast(v => v > 1)   // Returns {2, 3}
{1, 2, 3}.takeWhileLast((v,ind) => ind > 2)   // Returns {2, 3}
{1, 2, -1, 4, 5, 6}.takeWhileLast((v,ind) => ind < 5 and v > 0)  // Returns {4, 5, 6} (Take while index<5 amd value>0)
{1, 2, -1, 4, 5, 6}.takeWhileLast((v,ind,sz) => ind < sz-4 and v > 0)   // Returns {5, 6}

This example selects all items from a location report, starting from the last element and proceeding backwards, until the first item that has a distance to center greater than 20 units:

select items.takeWhile(i => distance(i.location.x, i.location.y, 0, 0) < 20)
from LocationReport

The second version provides the index of the input element starting at zero for the last element (reverse index).

The next example is similar to the statement above but also limits the result to the last 10 items:

select items.takeWhile((i, ind) => distance(i.location.x, i.location.y, 0, 0) < 20) and ind < 10)
from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.

The toMap enumeration method returns a Map according to specified key-selector lambda expression and value-selector lambda expression.

The enumeration method takes a key-selector expression and a value-selector expression. For each element the method applies the key-selector expression to determine the map key and the value-selector expression to determine the map value. If the key already exists in the map the value is overwritten.

The expression examples with scalar values are:

{1, 2, 3}.toMap(k => 'K' || Integer.toString(k), v => 'V' || Integer.toString(v))   // Returns map {K1=V], K2=V2, K3=V3}
{1, 2, 3}.toMap(
  (k, i) => 'K' || Integer.toString(k) || "_" || Integer.toString(i), 
  (v, i) => 'V' || Integer.toString(v) || "_" || Integer.toString(i)
  )  // Returns map {K1_0=V1_0, K2_1=V2_1, K3_2=V3_2}
{1, 2, 3}.toMap(
  (k, i, s) => 'K' || Integer.toString(k) || "_" || Integer.toString(s), 
  (v, i, s) => 'V' || Integer.toString(v) || "_" || Integer.toString(s)
  )  // Returns map {K1_3=V1_3, K2_3=V2_3, K3_3=V3_3}

The next example EPL outputs a map of item asset id and distance to center for each item:

select items.toMap(k => k.assetId, v => distance(v.location.x, v.location.y, 0, 0)) as assetDistance
from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty map.

The union enumeration method forms a union of the input elements with the elements that the parameter expression yields.

The enumeration method takes a single parameter that must itself return a collection of events (input), objects or scalar values. It appends the collection to the input elements and returns the appended collection of elements.

An expression example with scalar values:

{1, 2, 3}.union({4, 5})   // Returns {1, 2, 3, 4, 5}

This example selects a union of all items that have an asset id of L001 or that are of type passenger:

select items.where(i => i.assetId = 'L001')
    .union(items.where(i => i.type = 'P')) as itemsUnion
from LocationReport

If the input is null the method returns null.

The where enumeration method filters elements based on a predicate.

The enumeration method has two versions. The first version takes a predicate lambda expression and the second version takes a predicate lambda expression and index for use within the predicate expression. Both versions return all elements for which the predicate expression is true.

An expression example with scalar values:

{1, 2, 3}.where(v => v != 2)   // Returns {1, 3}
{1, 2, 3}.where((v, index) => v != 2 and index < 2)   // Returns {1}
{1, 2, 3}.where((v, index, size) => v != 2 and index < size - 2)   // Returns {1}

This example selects all items from a location report that are passenger-type:

select items.where(p => p.type = 'P') from LocationReport

The second version of the where represents the index of the input element starting at zero for the first element.

The example below selects all items from a location report that are passenger-type but ignores the first 3 elements:

select items.where((p, ind) => p.type = 'P' and ind > 2) from LocationReport

If the input is null the method returns null. If the input is empty the method returns an empty collection.