After partitioned by you can list the event properties that provide the key values that identify a unique partition. The synopsis is:

create context context_name partition [by]
  event_property [and event_property [and ...]] from stream_def [ [as] stream_name]
  [, event_property [...] from stream_def]   [, ...]

The event_property is the name(s) of the event properties that provide the value(s) to pick a unique partition. Multiple event property names are separated by the and keyword or by comma. Further detail on key expressions can be found at Section 5.2.13, “Composite Keys and Array Values as Keys”.

The stream_def is a stream definition which consists of an event type name optionally followed by parenthesis that contains filter expressions. If providing filter expressions, only events matching the provided filter expressions for that event type are considered by context partitions. The name of a named window or table is not allowed.

You may list multiple event properties for each stream definition. You may list multiple stream definitions. Please refer to usage guidelines below when specifying multiple event properties and/or multiple stream definitions.

You may specify the optional as-keyword and a stream name. This instructs the runtime to make the first event of a partition available in context built-in properties and for matching in terminated by. You may specify stream names either in partition by or in initiated by but not both.

The next statement creates a context SegmentedByCustomer that considers the value of the custId property of the BankTxn event type to pick the context partition to assign events to:

create context SegmentedByCustomer partition by custId from BankTxn

The following statement refers to the context created as above to compute a total withdrawal amount per account for each customer:

context SegmentedByCustomer
select custId, account, sum(amount) from BankTxn group by account

The following statement refers to the context created as above and detects a withdrawal of more than 400 followed by a second withdrawal of more than 400 that occur within 10 minutes of the first withdrawal, all for the same customer:

context SegmentedByCustomer
select * from pattern [
  every a=BankTxn(amount>400) -> b=BankTxn(amount>400) where timer:within(10 minutes)
]

The statement that refers to a keyed segmented context must have at least one filter expression, at any place within the statement that looks for events of any of the event types listed in the context declaration.

For example, the following is not valid:

// Neither LoginEvent nor LogoutEvent are listed in the context declaration
context SegmentedByCustomer
select * from pattern [every a=LoginEvent -> b=LogoutEvent where timer:within(10 minutes)]

When provided, initiated by lists the event type and filter criteria of events that can initiate new partitions. The synopsis is:

initiated by stream_def [ [as] stream_name]
  [, stream_def [ [as] stream_name]]   [, ...]

When initiated by is not provided, the partitioned by provides the event type and filter criteria for events that can initiate new partitions.

The stream_def is the stream definition which consists of an event type name optionally followed by parenthesis that contains filter expressions.

If providing filter expressions, only events matching the provided filter expressions for that event type initiate a new context partition. The name of a named window or table is not allowed.

You may use the as-keyword and a stream name to name the initiating event. That event becomes available in context built-in properties and for matching in terminated by. You may specify stream names either in partition by or in initiated by but not both.

This is a sample context and statement:

create context PerCustId_TriggeredByLargeAmount
  partition by custId from BankTxn 
  initiated by BankTxn(amount>100) as largeTxn

context PerCustId_TriggeredByLargeAmount select context.largeTxn, custId, sum(amount) from BankTxn

When a BankTxn event arrives with an amount value of greater than 100, the system starts the analysis (allocates a partition) for the specific custId value of the BankTxn event. The statement totals up the amount value of all BankTxn events for that same custId value (regardless of their amount). The sample assigns the name largeTxn to the initiating event and selects the event with context.largeTxn.

When provided, terminated by provides the condition that terminates partitions. The synopsis is:

terminated [by] terminating_condition

A list of possible conditions is provided in Section 4.2.7, “Context Conditions”. An event that causes termination does not also allocate a new partition.

Any event types that are listed in both the termination condition and partition by are implicitly correlated by key.

Consider the following two statements:

create context PerCustId_UntilExpired
  partition by custId from BankTxn 
  terminated by BankTxn(expired=true)

context PerCustId_UntilExpired select custId, sum(amount) from BankTxn output last when terminated

When a BankTxn event arrives, the system starts the analysis (allocates a partition) for the specific custId value of the BankTxn event only. The system stops the analysis (discards the partition) when a BankTxn event arrives, for that same custId value, that has an expired value of true. The output occurs when the analysis stops as the statement specifies output last when terminated.

The termination condition can be correlated to the initiating event provided that initiated by provides a stream name.

A context that correlates the terminating event to the initiating event is:

create context PerCustId_TriggeredByLargeAmount_UntilExpired
  partition by custId from BankTxn 
  initiated by BankTxn(amount>100) as txn
  terminated by BankTxn(expired=true and user=txn.user)

This example defines a context wherein the system starts the analysis when a BankTxn event arrives that has an amount value of greater than 100 (the initiating event). The analysis for the specific custId value only. It stops the analysis when a BankTxn event arrives that has an expired value of true and that the same custId value and that has a user value that matches the initiating event's user value.

If the context declaration lists multiple streams, each event type must be unrelated: You may not list the same event type twice and you may not list a sub- or super-type of any event type already listed.

The following is not a valid declaration since the BankTxn event type is listed twice:

// Not valid
create context SegmentedByCustomer partition by custId from BankTxn, account from BankTxn

If the context declaration lists multiple streams, the number of event properties provided for each event type must also be the same. The value type returned by event properties of each event type must match within the respective position it is listed in, i.e. the first property listed for each event type must have the same type, the second property listed for each event type must have the same type, and so on.

The following is not a valid declaration since the customer id of BankTxn and login time of LoginEvent is not the same type:

// Invalid: Type mismatch between properties
create context SegmentedByCustomer partition by custId from BankTxn, loginTime from LoginEvent

The next statement creates a context SegmentedByCustomer that also considers LoginEvent and LogoutEvent:

create context SegmentedByCustomer partition by 
  custId from BankTxn, loginId from LoginEvent, loginId from LogoutEvent

As you may have noticed, the above example refers to loginId as the event property name for LoginEvent and LogoutEvent events. The assumption is that the loginId event property of the login and logout events has the same type and carries the same exact value as the custId of bank transaction events, thereby allowing all events of the three event types to apply to the same customer-specific context partition.

You may add a filter expression to each of the event types. Filter criteria in partition by apply to all statements that refer to the context and to the same event type. Filter criteria in initiated by apply to initiating events only.

The below statements total up the amount of all BankTxn events per custId for only those BankTxn events that have an amount greater 100.

create context PerCust_AmountGreater100
  partition by custId from BankTxn(amount>100)
  initiated by BankTxn

context PerCust_AmountGreater100 select custId, sum(amount) from BankTxn

The below statements total up the amount of all BankTxn events per custId, but only when a first BankTxn event comes in that has an amount greater 100.

create context PerCust_TriggeredByLargeTxn
  partition by custId from BankTxn
  initiated by BankTxn(amount>100)

context PerCust_TriggeredByLargeTxn select custId, sum(amount) from BankTxn

You may assign events to context partitions based on the values of two or more event properties. The runtime thus uses the combination of values of these properties to pick a context partition.

An example context declaration follows:

create context ByCustomerAndAccount partition by custId and account from BankTxn

The next statement refers to the context and computes a total withdrawal amount, per account and customer:

context ByCustomerAndAccount select custId, account, sum(amount) from BankTxn

As you can see, the above statement does not need to specify group by clause to aggregate per customer and account, since events of each unique combination of customer id and account are assigned to separate context partitions.

The following context properties are available in your statement when it refers to a keyed segmented context:

create context ByCustomerAndAccount partition by custId and account from BankTxn

context ByCustomerAndAccount
  select context.name, context.id, context.key1, context.key2 from BankTxn

This section discusses the impact of contexts on joins to provide further samples of use and deepen the understanding of context partitions.

Consider a context declared as follows:

create context ByCust partition by custId from BankTxn

The following statement matches, within the same customer id, the current event with the last 30 minutes of events to determine those events that match amounts:

context ByCust 
  select * from BankTxn as t1 unidirectional, BankTxn#time(30) t2 
  where t1.amount = t2.amount

Note that the where-clause in the join above does not mention customer id. Since each BankTxn applies to a specific context partition the join evaluates within that single context partition.

Consider the next statement that matches a security event with the last 30 minutes of transaction events for each customer:

context ByCust
  select * from SecurityEvent as t1 unidirectional, BankTxn#time(30) t2 
  where t1.customerName = t2.customerName

When a security event comes in, it applies to all context partitions and not any specific context partition, since the SecurityEvent event type is not part of the context declaration.

If the context declaration lists multiple streams, each event type must be unrelated: You may not list the same event type twice and you may not list a sub- or super-type of any event type already listed.

If the context declaration lists multiple streams, the hash code function should return the same hash code for the related keys of all streams.

The next statement creates a context HashedByCustomer that also considers LoginEvent and LogoutEvent:

create context HashedByCustomer as coalesce
  consistent_hash_crc32(custId) from BankTxn,
  consistent_hash_crc32(loginId) from LoginEvent, 
  consistent_hash_crc32(loginId) from LogoutEvent
  granularity 32 preallocate

You may add a filter expression to each of the event types listed. The runtime applies the filter expression to the statement that refers to the context and to the same event type.

The next statement creates a context HashedByCustomer that does not consider login events that indicate that the login failed.

create context HashedByCustomer 
  coalesce consistent_hash_crc32(loginId) from LoginEvent(failed = false) 
  granularity 1024 preallocate

The following context properties are available in your statement when it refers to a keyed segmented context:

create context ByCustomerHash coalesce consistent_hash_crc32(custId) from BankTxn granularity 1024

context ByCustomerHash
  select context.name, context.id from BankTxn

The hash_code function based on the Java object hash code is generally faster than the CRC32 algorithm. The CRC32 algorithm, when used with a non-String parameter or with multiple parameters, requires the runtime to serialize all expression results to a byte array to compute the CRC32 hash code.

We recommend keeping the granularity small (1k and under) when using preallocate.

When specifying a granularity greater than 65536 (64k) the runtime switches to a Map-based lookup of context partition state which can slow down statement processing.

The following context properties are available in your statement when it refers to a category segmented context:

context CategoryByTemp
  select context.name, context.id, context.label from SensorEvent

If your initiating condition is a filter context condition, you may specify the distinct keyword followed by one or more distinct-value expressions. Further detail on key expressions can be found at Section 5.2.13, “Composite Keys and Array Values as Keys”.

The following sample EPL specifies a context that initiates a context partition for distinct order id values, remembering that order id until the time the context partition terminates:

create context OrderContext
  initiated by distinct(orderId) NewOrderEvent as newOrder 
  terminated by CloseOrderEvent(closeOrderId = newOrder.orderId)

The runtime allocates a new context partition only when a context partition does not already exist for a given orderId value of NewOrderEvent. When the context partition terminates at the time a CloseOrderEvent arrives, the runtime forgets about the orderId, allowing the next NewOrderEvent event for the same orderId to allocate a new context partition.

Please note the following limitations:

The following context properties are available in your statement when it refers to a context:

context NineToFive 
select context.name, context.startTime, context.endTime from TrafficEvent(speed >= 100)

context CtxTrainEnter
select *, context.te.trainId, context.id, context.name
from TrainLeaveEvent(trainId = context.te.trainId)

Define the stream that starts/initiates a context partition or that ends/terminates a context partition:

event_stream_name [(filter_criteria)] [as stream_name]

The event_stream_name is either the name of an event type or name of an event stream populated by an insert into statement. The filter_criteria is optional and consists of a list of expressions filtering the events of the event stream, within parenthesis after the event stream name.

Two examples are:

// A non-overlapping context that starts when MyStartEvent arrives and ends when MyEndEvent arrives
create context MyContext start MyStartEvent end MyEndEvent

// An overlapping context where each MyEvent with level greater zero 
// initiates a new context partition that terminates after 10 seconds
create context MyContext initiated MyEvent(level > 0) terminated after 10 seconds

You may correlate the start/initiating and end/terminating streams by providing a stream name following the as keyword, and by referring to that stream name in the filter criteria of the end condition.

Two examples that correlate the start/initiating and end/terminating condition are:

// A non-overlapping context that starts when MyEvent arrives
// and ends when a matching MyEvent arrives (same id)
create context MyContext 
start MyEvent as myevent
end MyEvent(id=myevent.id)

// An overlapping context where each MyInitEvent initiates a new context partition 
// that terminates when a matching MyTermEvent arrives 
create context MyContext 
initiated by MyInitEvent as e1 
terminated by MyTermEvent(id=e1.id, level <> e1.level) as e2

When specifying a stream name for the filter the context built-in properties carry the stream name. For example (termination is output only when using output when terminated):

context MyContext select context.e1, context.e1.propertyName, context.e2, context.e2.propertyName from SomeEvent

You can define a pattern that starts/initiates a context partition or that ends/terminates a context partition:

pattern [pattern_expression] [@inclusive] [as stream_name]

The pattern_expression is a pattern at Chapter 7, EPL Reference: Patterns.

Specify @inclusive after the pattern to have those same events that constitute the pattern match also count towards any statements that are associated to the context. You must also provide a tag for each event in a pattern that should be included.

Examples are:

// A non-overlapping context that starts when either StartEventOne or StartEventTwo arrive
// and that ends after 5 seconds.
// Here neither StartEventOne or StartEventTwo count towards any statements
// that are referring to the context.
create context MyContext 
  start pattern [StartEventOne or StartEventTwo] 
  end after 5 seconds

// Same as above. 
// Here both StartEventOne or StartEventTwo do count towards any statements
// that are referring to the context.
create context MyContext 
  start pattern [a=StartEventOne or b=StartEventTwo] @inclusive 
  end after 5 seconds

// An overlapping context where each distinct MyInitEvent initiates a new context 
// and each context partition terminates after 20 seconds
// Use @inclusive to say that the same MyInitEvent that fires the pattern
// also applies to statements that are associated to the context.
create context MyContext
  initiated by pattern [every-distinct(a.id, 20 sec) a=MyInitEvent]@inclusive
  terminated after 20 sec

// An overlapping context where each pattern match initiates a new context 
// and all context partitions terminate when MyTermEvent arrives.
// The MyInitEvent and MyOtherEvent that trigger the pattern are themselves not included 
// in any statements that are associated to the context.
create context MyContext
  initiated by pattern [every MyInitEvent -> MyOtherEvent where timer:within(5)]
  terminated by MyTermEvent

You may correlate the start and end streams by providing tags as part of the pattern, and by referring to the tag name(s) in the filter criteria of the end condition.

An example that correlates the start and end condition is:

// A non-overlapping context that starts when either StartEventOne or StartEventTwo arrive
// and that ends when either a matching EndEventOne or EndEventTwo arrive
create context MyContext 
  start pattern [a=StartEventOne or b=StartEventTwo]
  end pattern [EndEventOne(id=a.id) or EndEventTwo(id=b.id)]

You may correlate the start/initiating and end/terminating patterns by providing a stream name following the as keyword, and by referring to that stream name in the filter criteria of the end condition.

An example that correlates the start and end condition and that specifies a stream name for the pattern match follows:

create context MyContext 
  start pattern [a=StartEventOne or b=StartEventTwo] as startingPattern
  end pattern [c=EndEventOne(id=startingPattern.a.id) or d=EndEventTwo(id=startingPattern.b.id)] as endingPattern

When specifying a stream name for the pattern the context built-in properties carry the stream name. For example (termination is output only when using output when terminated):

context MyContext select context.startingPattern, context.startingPattern.a, context.startingPattern.a.propertyName, context.endingPattern, context.endingPattern.c, context.endingPattern.c.propertyName from SomeEvent

Crontab expressions are described in Section 7.6.4, “Crontab (timer:at)”.

Multiple crontab expressions may be provided that are separated by comma. When specifying multiple crontabs, the runtime determines the earliest time according to the crontabs.

Examples are:

// A non-overlapping context started daily between 9 am to 5 pm
// and not started outside of these hours:
create context NineToFive start (0, 9, *, *, *) end (0, 17, *, *, *)

// An overlapping context where crontab initiates a new context every 1 minute
// and each context partition terminates after 10 seconds:
create context MyContext initiated (*, *, *, *, *) terminated after 10 seconds

// From  8:00am (see start) to 9am (see end) and from 10am (see start) to 12pm (see end).
create context MyContext
  start (0, 8, *, *, *, *), (0, 10, *, *, *, *)
  end (0, 9, *, *, *, *), (0, 12, *, *, *, *)

// Monday to Friday from 8am to 11am, Saturday and Sunday from 8am to 8pm.
create context MyContext
  start (0, 8, *, *, *, *)
  end (0, 11, *, *, [1, 2, 3, 4, 5], *), (0, 20, *, *, [0, 6], *)

// Monday from 8am to 10am, Tuesday from 9am to 10am
create context MyContext
  start (0, 8, *, *, 1, *), (0, 9, *, *, 2, *)
  end (0, 10, *, *, *)

You may specify a time period that the runtime observes before the condition fires. Time period expressions are described in Section 5.2.1, “Specifying Time Periods”.

The syntax is:

after time_period_expression

Examples are:

// A non-overlapping context started after 10 seconds 
// that ends 1 minute after it starts and that again starts 10 seconds thereafter.
create context NonOverlap10SecFor1Min start after 10 seconds end after 1 minute

// An overlapping context that starts a new context partition every 5 seconds
// and each context partition lasts 1 minute
create context Overlap5SecFor1Min initiated after 5 seconds terminated after 1 minute