Apama queries are deprecated and will be removed in a future release.
Apama’s Query Designer editor provides a graphical environment that business analysts can use to define and update Apama queries without the need to write source code. An Apama query monitors a very large number of real-world entities and processes events on a per-entity basis, for example, all events related to one credit card account.
Query Designer provides two views of a query definition:
Design — Business analysts define and update query definitions in this view. The Design tab provides an event palette and a canvas for defining an event pattern of interest. Toolbars, tooltips, and dialogs make it easy to define the events of interest to the query as well as any required parameters, conditions for finding matches, aggregate calculations and actions to take when a match set is found.
Source — Application developers can examine and update query definition source code in the EPL code editor available from the Source tab.
Query Designer keeps the two views synchronized. Any changes made in the Design view are reflected in the Source view and vice versa.
Apama queries are useful when you want to monitor incoming events that provide information updates about a very large set of real-world entities such as credit cards, bank accounts, cell phones. Typically, you want to independently examine the set of events associated with each entity, that is, all events related to a particular credit card account, bank account, or cell phone. A query application operates on a huge number of independent sets with a relatively small number of events in each set.
To add a query file to a project
In Project Explorer, right-click the project you want to add a query to and select New > Query File.
In the New Apama Query File dialog, the Containing folder field shows the name of the project you selected. Accept this or enter the name of the project you want to add the query to.
In the File name field, enter a name for the query file.
In the Query name field, when you enter the file name in the File name field, the same file name appears as a query name in the Query name field. You can either accept or edit the query name.
In the Package field, you can optionally specify the EPL package that contains this query. If you do not specify a package then the query file is in the default package which contains EPL files that do not specify a package name.
Click Finish.
The new query file is added to the project’s queries folder and the new query is opened in the Design tab of the Query Designer. Also, the Queries Support bundle is automatically added to your project, if your project does already contain this bundle. A query application project must contain the Queries Support bundle. After you add a query file to a project, you can view it along with the other EPL objects in your project. See Viewing all EPL objects in all projects.
Steps for using Apama Plugin for Eclipse to implement queries
After you add a query file to a project, the Query Designer appears. You can define the query in the Design tab.
Info
By default, the query designer notifies errors at table level for Inputs and Pattern sections before entering data. After entering data, if there are errors in any section, the errors are notified at the table level as well as row level of the table where there is an error.
Before you can define a query, you must define the events that you want the query to process. For information on how to write the event definitions, see Overview of query application components.
To defining a query in the Design tab of Query Designer
In the Inputs pane, click the plus sign to add an event type definition that you want the query to process. You must add one or more inputs before you can create the event pattern you are interested in. See Adding query inputs.
Optionally, in the Parameters pane, click the plus sign to add a query parameter. See Adding query parameters.
From the event Palette, select an input event and drag it onto the pattern canvas. See Adding query patterns.
In the Actions pane, click the plus sign to define an action that the query executes when it finds the specified event pattern. See Adding query actions.
Optionally, In the Conditions pane, click the plus sign to add a filter, time constraint or exclusion. Conditions let you identify the exact events you are interested in. You must add one or more inputs before you can add query conditions. See Adding query conditions.
Optionally, in the Aggregates pane, click the plus sign to add an aggregate expression to the find pattern. An aggregate expression aggregates event field values in order to find data based on many sets of events. See Adding query aggregates.
At any time, you can click the Source tab to view the code that defines your query.
Creating queries in Query Designer
As mentioned earlier, the Query Designer editor provides two views of a query definition:
Design — Business analysts define and update query definitions in this view. The Design tab provides an event palette and a canvas for defining an event pattern of interest. Toolbars, tooltips, and dialogs make it easy to define the events of interest to the query as well as any required parameters, conditions for finding matches, aggregate calculations and actions to take when a match set is found.
Source — Application developers can examine and update query definition source code in the EPL code editor available from the Source tab.
Query Designer keeps the two views synchronized. Any changes made in the Design view are reflected in the Source view and vice versa.
The following topics provide information and instructions for using Query Designer to create a query definition.
Configuring a query
In the Configure Query dialog, you can configure the query to import event types and aggregate functions, query name and package, and metadata information.
Importing event types and aggregate functions lets you use the short name of an event type or an aggregate function instead of the full name. For example, when you are writing an aggregate:
If you have imported the built-in aggregate function avg (), to calculate the average value ‘x’ for all events ‘e’, you can write avg (e.x) instead of the fully qualified package name com.apama.aggregates.avg(e.x).
If you have not imported the built-in aggregate function avg (), to calculate the average value ‘x’ for all events ‘e’, you have to write the fully qualified package name com.apama.aggregates.avg(e.x).
Info
You can use the Configure Query dialog to clear the elements that are missing from the package.
To configure a query
In the Inputs toolbar, click the Configure Query icon . The Configure Query dialog appears with the list of event types and aggregate functions.
Optionally, in the Import definitions tab, you can filter the event types and aggregate functions in the list using the drop down list at the text box.
Select Show Events to view only the event types.
Select Show Aggregates to view only the aggregates.
Select Show Both to view all the event types and aggregates.
In the Import definitions tab, select the required event type or the aggregate function.
In the text box, you can also type the name of the event type or the aggregate function that you want the query to import.
Info
You cannot select the event types or aggregate functions that are selected by default. These event types and aggregates are implicitly available as they share the same package as the query file.
In the Name & Package tab, you can edit the query name and package for an existing query file. If you do not specify a package in the Package (optional): field, then the query file is in the default package which contains EPL files that do not specify a package name.
In the Metadata tab, you can add, edit, or delete query metadata.
To add a metadata entry, click (). The Add metadata dialog appears. Enter the Key and Value, and click OK.
To edit a metadata entry, select the entry you want to edit and click (). The Edit metadata dialog appears. Edit the Key and Value, and click OK.
To delete a metadata entry, select the entry you want to delete and click ().
For more information on defining metadata, see Defining metadata in a query.
Click OK.
Optionally, when an event has been renamed or removed from the event definition file, then the missing events or aggregates appear in the Configure Query dialog. You can clear the missing events or aggregates in the Configure Query dialog by clicking Clear List.
Adding query inputs
To specify the event pattern that you want your query to find, you must first define the event types that your query processes. The input definitions identify the events that you want the query to operate on. Perform these tasks in the Inputs pane in the Design tab of the Query Designer.
To add a query input
In the Inputs toolbar, click () to select an event type. The New Query Input dialog appears.
In the Choose Event Input, click Choose button to select the event type you want to add in the Event Type Selection. Click OK.
Info
The Event Type Selection dialog displays the automatically generated query output event definition from other queries in the project. You can select the automatically generated query output event definition as an input to the query. For more information, see Using the output of another query as query input.
In the Window tab:
Event Window
In the Within field, optionally specify a float expression or time literal that specifies the duration of time that an event remains as a current event that the query operates on. The query operates on the events that have been received within the time specified.
For example, Within: 7 days implies that an event remains in the event window for 7 days.
In the Retain field, optionally specify an integer expression that specifies the number of events to be retained in the window.
For example, Retain: 100 implies that a maximum of 100 events can be retained in the event window. If the number of events exceed 100, the older events are replaced by new events.
Info
You must specify a value in either the Within field or in the Retain field or both.
Partition
In the Keys field, optionally you can select one or more fields to be the query key. A query key identifies one or more fields in the events being operated on. Each input definition for a given query must specify the same key. Apama uses the key to partition the incoming events. A partition contains a set of events that have the same key value. The query processes the set of events in a given partition independently of every other partition. All the input events must have the same key names. If an event field does not have the same name as an existing input event, alias the key to the same name as the existing input key. For example, you can partition Withdrawal events according to their account numbers. To arrange the keys in a required order, you must select the key and use the up and down arrows to arrange accordingly.
You can also specify an action expression for an event in the Keys field. You can add, edit, and delete an action expression for an event in the Keys field.
Info
Adding, editing, and deleting an action expression is supported only for actions in the Keys field.
To add an action expression, click (). Specify the action expression in the Action expression field using the completion proposals. You must also specify an alias for the action expression in the Alias field. This alias must be unique for that specific event.
To edit an action expression, click (). Edit the action expression.
To delete an action expression, click ().
In the Filtering tab:
Pre-Filtering (optional)
In the Filter field, optionally specify an expression that filters the events you want the query to process. In the filter expression, you can specify event fields of type boolean, decimal, float, integer, string or location.
For example, if you want to filter Withdrawal events whose amount field is greater than 10, type amount > 10.0.
If you want to refer to a parameter in a filter, then you must first add the parameter. see Adding query parameters.
Discard repeating values (optional)
If there are multiple events with the same value for a field, the With unique functionality retains the latest value and discards the previous events with the same value.
Select Do not discard repeating values if you want to retain events with repeating values.
Source Timestamps — time at which an event happened at the event source that is available in the event. Use the Timestamps (optional) tab to configure the query to use Source Timestamps. The Timestamps (optional) tab controls whether the query runtime processes the events as they occur or whether the events contain some information about the time they occurred. This process of Timestamps tab requires you to specify the Wait, Time from, and Heartbeat fields.
To configure the query to use source timestamps
Select No Timestamps - Process events at arrival time to process the events as they arrive. You cannot specify the Wait, Time from, and Heartbeat fields if you select this option.
Select Use Timestamps - Wait for delayed events to process the events according to the timestamps of the events.
Info
If events are delayed or re-ordered between the event source and the queries, then using the source timestamps where available yields more accurate results.
Event definition settings — select this option if you want the query to use the Time from and Heartbeat settings provided by the event definition through annotations. If the annotation has a DefaultWait annotation, then the Wait field is initially set by copying the value from the DefaultWait annotation (if defined). But, you can still configure the Wait field.
Specify a float expression or a time literal in the Wait field that specifies the maximum delay for an event. For a query that uses source timestamps, you must specify the maximum time for the queries runtime to wait for an event before it can process. If the event does not define a TimeFrom annotation, use Custom settings.
Custom settings — select this option if you have different queries using different settings or if there are no annotations. This ensures that not all queries are using the same Time from or Heartbeat. You can specify the Wait, Time from, and Heartbeat fields after selecting this option.
Wait — specify a float expression or a time literal that specifies the maximum time for the queries runtime to wait for an event before it can process.
Time from — select an action that returns source timestamps of the event to the query. The Time from drop-down lists actions that are legal and can be used time-from actions. The actions must not have any parameters and must return a float value.
Heartbeat (optional) — select the check box Use heartbeat event (optional) if you wish to configure an heartbeat settings. Click Choose… to select the Heartbeat event type. Select the event type and click OK. The selected event type must have the same key fields and time-from actions as the input event type. The heartbeat events with timestamps signal that the communication from the source to the queries system is working correctly.
Info
The heartbeat events can be used only if a query is using source timestamps.
Click OK to add this input definition to your query.
Query Designer displays the new input definition in a row in the Inputs section and the event type you specified appears in the Palette.
Repeat these steps for each event type you want your query to process. Apama recommends no more than four input definitions in a query. You cannot add the same event type as a query input more than once. The input event type must be unique.
Before you can add a pattern to a query, you must add input definitions to the query. see Adding query inputs.
To add a query pattern to a query
If the query definition is not already displayed in Query Designer, expand the project’s queries folder and double-click the query file you want to edit.
In the Query Designer Design tab, from the Palette, drag and drop an event onto the canvas to the right.
To add a second event to the pattern, drag the event type from the Palette onto the canvas so that it hovers over the event that is already there.
The same event type can appear multiple times in a pattern. Query Designer automatically gives each event in the pattern a unique identifier.
Query Designer displays the followed-by (->), or and and operators before and after the event that is already in the pattern.
Drag the event you are adding to the appropriate operator so that it is highlighted and drop it.
Query Designer displays the updated pattern.
To add another event to the pattern, drag it from the Palette onto the canvas.
To relate the event being added to one of the events already in the pattern, hover the event being added over the event that is already in the pattern.
To relate the event being added to two or more events already in the pattern, hover the event being added over the space between those events.
Query Designer displays the followed-by (->), or and and operators before and after the event(s) that is (are) already in the pattern.
Drag the event you are adding to the appropriate operator so that it is highlighted and drop it.
Query Designer displays the updated pattern.
Repeat the previous three steps to add each additional event in the pattern you are looking for.
To add a period of time that must elapse before or after the event pattern occurs, drag Wait (()) from the palette onto the canvas and hover over the pattern for prompts to indicate where you can drop it.
A waiting period is allowed at the beginning or end of an event pattern; it is not allowed between events.
Drag the Wait operator to the followed-by (->) operator at the beginning of the pattern or at the end of the pattern so that -> is highlighted and drop it.
Query Designer displays the updated pattern. The Wait operator has a blue color in contrast to the green color of the events. Inside the Wait operator, Query Designer assigns a unique identifier and default time period of 10 seconds.
If you need to delete an event or Wait operator from a pattern, right-click it and select Delete.
If you want to change the name of an event identifier in the pattern, double-click that identifier and enter a new one. For information on the characters that an identifier may contain, see Identifiers.
After you define the query’s event pattern, you might want to add conditions that determine when the query successfully finds a match for the pattern. See Adding query conditions.
Adding query parameters
A query can specify one or more parameters. Parameters enable a query definition to function as a template for multiple query instances. A query that defines parameters is referred to as a parameterized query. An instance of a parameterized query is referred to as a parameterization.
A parameterized query offers the following benefits:
Patterns of interest may be customized from a single generic query. This can significantly reduce the amount of code that needs to be written and maintained.
Parameterizations exist only at runtime. There is no need to maintain a file for each instance.
Parameters can be used throughout the query in which they are defined. For example, you can use them in the definition of inputs, in find actions, and in user-defined actions. Values do not need to be hardcoded.
You can add zero, one, or more parameters to a query.
For more information about how the use of parameters affect queries, see Query lifetime.
To add a parameter to a query
In the Query Designer Parameters pane, click () to add a new parameter.
In the Parameters pane, in the Name field, enter an identifier for the parameter.
An identifier can include lowercase a-z, uppercase A-Z, digits, dollar sign, and underscore. An identifier cannot start with a digit and cannot include any other special characters.
Select the type of the parameter. A drop down in the Parameters pane provides the list of valid types applicable.
Query Designer displays the new parameter in a row in the Parameters pane. To modify the parameter, select it and then click the field to edit in the Parameters pane. To remove the parameter, select it and then click the Delete icon (). Also, the new parameter is immediately added to the source code in the parameters section of the query definition. If you modify the parameter definition in the Source tab this is reflected in the Parameters pane in the Design tab.
An Apama query can specify conditions that must be satisfied for there to be a match for the event pattern of interest. You can specify the following kinds of conditions:
Filter — This is a Boolean expression that refers to the events in the specified pattern of interest. This expression must evaluate to true for there to be a match. There can be zero, one, or more query filter conditions. Adding a query filter condition inserts a where clause in the source view of the query.
Time constraint — This is a time period during which some or all events in the pattern must have been received. There can be zero, one, or more time constraints. Adding a time constraint inserts a within clause in the source view of the query.
Exclusion — This is the specification of an event whose presence prevents a match. If you need to prevent a match only when instances of this event have certain values you can add a filter that qualifies which instances of the specified event prevent a match. You can add zero, one or more exclusions. Adding an exclusion inserts a without clause in the source view of the query.
You add query conditions in the Conditions pane of the Design view. Click the down arrow to the right of the plus sign () and select the kind of condition you want to add. Query Designer displays a dialog in which you define the condition.
After you add a condition in the Design view, it appears in a row in the Conditions pane that shows the condition type, the expression that specifies the condition, and the range that the condition applies to if one was specified. Select the condition to edit or delete it.
When you add a condition it is immediately added to the source code. Any changes you make in the Source tab will be shown in the Design tab, and vice versa. If you introduce any errors into the query source code then you must resolve them in the Source tab before you can view the query in the Design tab.
For more details about the EPL code for query conditions, see Query conditions.
Adding query condition filters (where)
A query can specify a Boolean expression that must evaluate to true for the query to find a match. This is referred to as a query condition filter. You can add zero, one, or more condition filters to a query.
Info
where clauses are only able to use coassignments on one side of an or operator in the pattern. To place conditions on events on either side of an or operator, write separate where clauses for each side of the or operator.
In the Query Designer Conditions pane, click the down arrow next to the plus sign () and select Filter (where).
In the New Query Condition Filter (where) dialog, enter a Boolean expression that refers to the events in the pattern of interest.
For example, consider a Withdrawal event followed by another Withdrawal event, both for the same account. You are interested in this pattern only when the country fields in the two events are different. Using the aliases w1 and w2 for the two Withdrawal events, the following Boolean expression specifies the filter: w2.country != w1.country.
Click OK.
The Query Designer displays the new filter in a row in the Conditions pane. To modify the filter, select it and click (). Also, the new filter is immediately added to the source code as a where clause in the find statement. If you modify the filter in the Source tab, this is reflected in the Conditions pane in the Design tab.
Adding query time constraints (within)
A query time constraint sets the time period during which the set of events that match the pattern of interest must have been received. A query can specify zero, one or more time constraints. A time constraint can apply to the whole pattern or a portion of the pattern.
In the Query Designer Conditions pane, click the down arrow next to the plus sign () and select Time constraint (within).
In the New Time Constraint dialog, if the time constraint applies to all events in the pattern then leave All events in the pattern selected and skip the next step. Otherwise, select Only specific events.
For example, suppose you want to flag consecutive Withdrawal events for the same account that have different country field values. However, this is of interest only when the consecutive events both arrive within an hour. In this case, the time constraint applies to all events in the pattern.
To apply the time constraint to a portion of the pattern, select at least two events. The time constraint applies to only the events you select.
For example, suppose that the pattern of interest is an A event followed by a B event followed by a C event. However, this pattern is of interest only when the C event is received within 10 seconds after the B event. You want the time constraint to apply only to the B and C events and so you need to select those two events.
In the field at the bottom of the dialog, specify the period of time during which the selected events must be received. The elapsed time from when the first selected event is received to when the last selected event is received must be less than the time period you specify. see Specifying a time period in Query Designer.
Click OK.
Query Designer displays the new time constraint in a row in the Conditions pane. To modify this time constraint, select it and then click (). Also, the new time constraint is immediately added to the source code as a within clause in the find statement. If you modify the time constraint in the Source tab this is reflected in the Conditions pane in the Design tab.
Adding query exclusions (without)
A query exclusion specifies that the presence of a particular event prevents a match. A query can specify zero, one or more exclusions. An exclusion can include a filter and/or a range to limit which instances of the identified event prevent a match.
Info
The information on the options in the New Query Exclusion (without) dialog which is provided below also applies when you modify an existing exclusion in the Edit Query Exclusion (without) dialog.
In the Query Designer Conditions pane, click the down arrow next to the plus sign () and select Exclusion (without).
In the New Query Exclusion dialog, in the Event Type field, select the event whose presence prevents a match. You can select only an event type that has been added as a query input. If the type you want to select is not listed then you must first add it as a query input.
For example, consider consecutive Withdrawal events that have different country field values. You want an alert when this occurs except when a TravelNotification event is received before the second Withdrawal event. In this case, select TravelNotification as the event type that prevents a match.
In the Name field, Query Designer displays a name that it automatically generates. This is an alias for the selected event and is unique across all aliases in the query. You have the option of using this alias in the next step.
In the field in the middle of the dialog, you can optionally specify a Boolean expression that limits which event instances prevent a match. In this Boolean expression, you can optionally refer to the alias that appears in the Name field. When the specified Boolean expression evaluates to true, the presence of the specified event prevents a match. When this expression evaluates to false, the presence of the specified event allows a match.
For example, you might want a TravelNotification event to prevent a match only when its date field has the same value as the date field of the first Withdrawal event. If the event aliases w1, w2, and t1 are used, the following Boolean expression defines the exclusion filter: w1.date = t1.date. When the date fields of the first Withdrawal event and the TravelNotification event have the same value then the presence of the TravelNotification event between two consecutive Withdrawal events will prevent a match and an alert will not be sent. When the date fields of the first Withdrawal event and the TravelNotification event have different values then the presence of the TravelNotification event between two consecutive Withdrawal events will allow a match and an alert will be sent.
At the bottom of the dialog, indicate when the presence of the selected event prevents a match. If you accept During the whole pattern, then you can select OK and you are done adding an exclusion. If the presence of the selected event prevents a match only when it is received In between specific events, then select that option and then select at least two events.
Click OK to save the query exclusion.
Query Designer displays the new exclusion in a row in the Conditions pane. Also, the new exclusion is immediately added to the source code as a without clause in the find statement. You can click the Source tab to view the exclusion in the source code. Any changes you make in the Design tab are reflected in the Source tab, and vice versa.
To modify the exclusion, select it in the Conditions pane and then click ().
To remove the exclusion, select it in the Conditions pane and then click ().
An Apama query can specify aggregates that let the query find data based on many sets of events. You can add one or more of each of the following to your query definition:
Aggregate calculation — Adding an aggregate calculation inserts a select clause in the source view of the query.
Aggregate filter — This is a Boolean expression that refers to the events in the specified pattern of interest. This expression must evaluate to true for there to be a match. There can be zero, one, or more query filter conditions. Adding an aggregate filter inserts a having clause in the source view of the query.
You add query aggregates in the Aggregates pane of the Design view. Click the down arrow to the right of the plus sign (), and select the kind of aggregate you want to add. Query Designer displays a dialog in which you define the aggregate. The following topics provide more information:
After you add an aggregate in the Design view, it appears in a row in the Aggregates pane that shows the aggregate type, the expression that specifies the aggregate, and an alias for the aggregation. Select the aggregate to edit or delete it.
When you add an aggregate, it is immediately added to the source code. Any changes you make in the Source tab will be shown in the Design tab. If you introduce any errors into the query source code then you must resolve them in the Source tab before you can view the query in the Design tab.
A query can specify an aggregate calculation that computes a single value based on multiple events, such as the average of a series of numbers. See the API reference for EPL (ApamaDoc) for detailed information on all built-in aggregate functions.
When a query does not specify an aggregate calculation or filter, only the most recent set of events that match the pattern are used to invoke the actions and any other procedural code. With an aggregate calculation or filter, every set of events, in the current set of events, that matches the pattern is available for use by the aggregate function, provided that the latest event is present in one of the sets of events. Any events or combinations of events that do not match the pattern or do not meet specified query conditions, are ignored; their values are not used by the aggregate function.
To add an aggregate calculation to a query
In the Query Designer Aggregates pane, click the down arrow next to the plus sign () and select Calculation (select).
In the New Query Aggregate Calculation dialog, specify an expression that uses an aggregate function with identifiers from the pattern. You can also use parameters.
The first() and last() built-in aggregate functions process the oldest or newest event in the current set of events that the query is processing, respectively.
For example, the following aggregate calculation determines the average price of trades:
avg(trade1.price, trade1.amount)
The field at the bottom of the dialog displays the identifier for this calculation. You can change the identifier. You can refer to this identifier in a query action.
Click OK.
Query Designer displays the new aggregate calculation in a row in the Aggregates pane.
To modify the aggregate calculation, select it and then click ().
To remove the calculation, select it and then click ().
Also, the new calculation is immediately added to the source code as a select clause in the find statement. If you modify the calculation in the Source tab, this is reflected in the Aggregates pane in the Design tab.
You can add one or more aggregate calculations as well as one or more aggregate filters. The order in which they appear in the Aggregates pane is the order in which they are executed in the query. To change the order, select an aggregate and click the up arrow or down arrow as needed.
When you add more than one aggregate filter to a query, then all of them must evaluate to true for the query actions to be invoked.
A query can specify a Boolean expression that uses an aggregate function that must evaluate to true for the query actions and any other procedural code are invoked. See the com.apama.aggregates package in the API reference for EPL (ApamaDoc) for detailed information on all built-in aggregate functions.
When a query does not specify an aggregate calculation or filter, only the most recent set of events that match the pattern are used to invoke the actions and any other procedural code. With an aggregate calculation or filter, every set of events, in the current set of events, that matches the pattern is available for use by the aggregate function, provided that the latest event is present in one of the sets of events. Any events or combinations of events that do not match the pattern or do not meet specified query conditions, are ignored; their values are not used by the aggregate function.
To add an aggregate filter to a query
In the Query Designer Aggregates pane, click the down arrow next to the plus sign () and select Filter (having).
In the New Query Aggregate Filter dialog, specify a Boolean expression that uses an aggregate function with identifiers from the pattern. You can also use parameters.
The first() and last() built-in aggregate functions process the oldest or newest event in the current set of events that the query is processing, respectively.
For example, this aggregate filter causes the query actions to be invoked only when the average price of trades is greater than 100.0:
avg(trade1.price) > 100.0
Click OK.
Query Designer displays the new aggregate filter in a row in the Aggregates pane.
To modify the aggregate filter, select it and then click ().
To remove the filter, select it and then click ().
Also, the new filter is immediately added to the source code as a having clause in the find statement. If you modify the filter in the Source tab this is reflected in the Aggregates pane in the Design tab.
You can add one or more aggregate calculations as well as one or more aggregate filters. The order in which they appear in the Aggregates pane is the order in which they are executed in the query. To change the order, select an aggregate and click the up arrow or down arrow as needed.
In a query definition, you specify the actions you want Apama to perform when it finds a match for the event pattern specified in the query. You can add one or more actions and there are three kinds of actions that you can add:
“Send event” actions send an event to a channel that you specify.
“Custom EPL” actions can do anything that can be defined in an EPL action.
“Route event” actions route events to a channel that you specify.
Info
It is recommended to use the “Route event” action rather than “Send event” when events are being sent from one query to another. This is important when using reliable messaging, since although an external event will not be acknowledged until all routed events arising from it have been processed, the acknowledgement will not wait for any “sent” events to be processed.
Before you define query actions, you should add the query input events and specify the query pattern. If this is a parameterized query, you should add the query parameters before you add actions. You can then refer to the parameters in the actions.
You add query actions in the Actions pane of the Design view. Click the down arrow to the right of the plus sign () and select the kind of action you want to add. Query Designer displays a dialog where you define the action.
After you add an action in the Design view, its name appears in a row in the Actions pane. Select the action name to edit or delete it.
When you add an action, it is immediately added to the source code. Any changes you make in the Source tab will be shown in the Design tab, and vice versa. If you introduce any errors into the query source code then you must resolve them in the Source tab before you can view the query in the Design tab.
In the Query Designer Actions pane, add the send event action(s) you want Apama to perform when it finds a match for the event pattern specified in the query. You can specify one or more send actions as well as one or more custom actions.
Before you define query actions, you should add the query input events and specify the query pattern. If this query uses parameters, you should add the query parameters before you add actions. You can then refer to the parameters in the actions.
To add a send action to a query
In the Actions pane of the Query Designer, click the drop down arrow to the right of the plus sign () and select Send Event to create a send event action. The New Query Send Event Action dialog appears.
Click Choose, and select the Event type.
Info
The Event Type Selection dialog displays the automatically generated query output event definition from other queries in the project. You can select the automatically generated query output event definition as an input to the query. For more information, see Using the output of another query as query input.
In the Name field, enter a name for the send event action.
In the Description field, optionally enter a description of what the action performs.
In the Channel field, specify an EPL expression to which the event will be sent. The EPL expression must evaluate to a string. If you are using a string literal, you have to enclose the string literal within quotes.
For example, in the sample Delayed_InOrder_Events_Car_Sample, you can use an EPL expression caralert.carId in the Channel field for the event type apamax.querysamples.delayedcarevents.CarEngineAlert. Here, "caralert." is a channel name prefix which is combined with the carId value. If the value of carId is 10, then the channel to which the event will be sent is caralert.10.
To insert an event field or an expression, right-click the Channel field and select the required event field or expression.
To convert an expression to a plain text:
Select the expression that you want to convert to plain text
Right-click the selected expression
Select switch to plain text [ctrl-p]
To convert plain text to an expression:
Select the plain text that you want to convert to an expression
Right-click the selected plain text
Select switch to expression [ctrl-e]
In the Fields table, specify a value to every field name.
To specify a value to a field name, select the field name and click the edit sign (). The Edit dialog appears.
In the Edit dialog:
To insert an expression, right-click in the text box and select the required expression. Click OK.
To convert an expression to a plain text:
Select the expression that you want to convert to plain text
Right-click the selected expression
Select switch to plain text [ctrl-p]
Click OK
To convert plain text to an expression:
Select the plain text that you want to convert to an expression
Right-click the selected plain text
Select switch to expression [ctrl-e]
Click OK
The Fields table displays event fields and the values to be specified for the event. Values can be any valid EPL expression. Only string literals need to be enclosed within quotes. If any fields that are not present in the event definition have been incorrectly added to the Send Event action’s event in the Source editor tab, then these fields are listed in the missing fields table. These missing fields and values are persisted with the Send Event action when you click OK. If you do not want these missing fields and values to persist, click Clear List. Clear List removes all the missing fields and values from the Send Event action.
If you have used an or operator in the query pattern, you can select the events to be matched in the Require these events to be matched by the pattern section. Events that are on one side of an or operator in the pattern are optional as they may not be matched by the pattern if the alternative events are matched instead. The Require these events to be matched by the pattern section sets which events must be matched by the pattern in order for the send event action to send the event. If the value from an optional event is used in the send event action, then it must be selected in the Require the events to be matched by the pattern. It is not legal to use the optional events without setting them as required. It is also possible to add optional terms to the Require these events to be matched by the pattern section manually, if sending the event should be conditional on the events being matched.
If the names of the coassignments in the pattern are modified or removed, then the send event action may refer to old names. Click Clear missing events to remove the missing coassignments.
Click OK when the send action definition is complete.
If you look at the Source view of the query, you can see that for each action you define, Query Designer inserts a %send statement in the EPL query definition. The %send() statements appear in the find statement block and can be interleaved with regular EPL.
In the Source view, the modifications you can make to %send statements are to modify the quoted name, the quoted description, and the channel. Any changes you make in the Source view will appear in Query Designer. If there is a syntax error in the Source view, you cannot display the Design view until you correct the error. The recommendation is that only Query Designer should insert %send() statements. At runtime when the query finds a match, it executes all specified actions in the order in which they are listed in the Actions pane, provided any Required events set by the send event action have been matched by the pattern.
To edit a send event action, select the send event action and click the edit sign ().
To delete a send event action, select the send event action and click the delete sign ().
The arrows at the top of the Actions pane let you change this order. To change the order, select the action you want to move and then click the appropriate arrow as many times as needed.
Adding query custom EPL actions
In the Query Designer Actions pane, add the custom EPL actions you want Apama to perform when it finds a match for the event pattern specified in the query. You can specify one or more custom actions as well as one or more send actions. see Adding query actions for an understanding of these two kinds of actions.
Before you define query actions, you should add the query input events and specify the query pattern. If this is a parameterized query, you should add the query parameters before you add actions. You can then refer to the parameters in the actions.
To add a custom action to a query
In the Query Designer Actions pane, click the down arrow to the right of the plus sign () and select Custom EPL to display the New Query Custom EPL Action dialog.
In the Name field, enter a name for the custom action.
In the Description field, optionally enter a description of what the actions does.
In the Custom EPL code editor, enter the EPL code that defines the action. You define an action in a query in the same way that you define an action in a monitor except that when you use the New Query Custom EPL Action wizard, you cannot specify action arguments nor an action return value. The numbers in the left column approximately indicate the lines that the code you enter will be on if you click the Source tab to view the query code.
The Errors field displays information about any errors in the EPL you enter. You must resolve any errors before you can save the action.
Click OK when the action definition is complete.
If you look at the Source view of the query, you can see that for each action you define, Query Designer inserts a %custom statement in the EPL query definition. The %custom() statements appear in the find statement block and can be interleaved with regular EPL.
In the Source view, the modifications you can make to %custom statements are to modify the quoted name, the quoted description, or the EPL in the block. The block contains the action definition you entered in the Custom EPL code editor. Any changes you make in the Source view will appear in Query Designer. If you make an invalid change in the source then you cannot display the Design view until you correct the error.
The recommendation is that only the Query Designer should insert %custom()statements.
At runtime, when the query finds a match it executes all specified actions in the order in which they are listed in the Actions pane. Two arrows at the top of the Actions pane let you change this order. To change the order, select the action you want to move and then click the appropriate arrow as many times as needed.
Adding query route event actions
In the Query Designer Actions pane, add the route event actions you want Apama to perform when it finds a match for the event pattern specified in the query. You can specify one or more route actions as well as one or more custom actions.
Before you define query actions, you should add the query input events and specify the query pattern. If this query uses parameters, you should add the query parameters before you add actions. You can then refer to the parameters in the actions.
To add a route action to a query
In the Actions pane of the Query Designer, click the drop down arrow to the right of the plus sign () and select Route Event to create a route event action. The New Query Route Event Action dialog appears.
Click Choose, and select the Event type.
Info
The Event Type Selection dialog displays the automatically generated query output event definition from other queries in the project. You can select the automatically generated query output event definition as an input to the query. For more information, see Using the output of another query as query input.
In the Name field, enter a name for the route event action.
In the Description field, optionally enter a description of what the action performs.
In the Fields table, specify a value to every field name.
To specify a value to a field name, select the field name and click the edit sign (). The Edit dialog appears.
In the Edit dialog:
To insert an expression, right-click in the text box and select the required expression. Click OK.
To convert an expression to a plain text:
Select the expression that you want to convert to plain text
Right-click the selected expression
Select switch to plain text [ctrl-p]
Click OK
To convert plain text to an expression:
Select the plain text that you want to convert to an expression
Right-click the selected plain text
Select switch to expression [ctrl-e]
Click OK
The Fields table displays event fields and the values to be specified for the event. Values can be any valid EPL expression. Only string literals need to be enclosed within quotes. If any fields that are not present in the event definition have been incorrectly added to the Route Event action’s event in the Source editor tab, then these fields are listed in the missing fields table. These missing fields and values are persisted with the Route Event action when you click OK. If you do not want these missing fields and values to persist, click Clear List. Clear List removes all the missing fields and values from the Route Event action.
If you have used an or operator in the query pattern, you can select the events to be matched in the Require these events to be matched by the pattern section. Events that are on one side of an or operator in the pattern are optional as they may not be matched by the pattern if the alternative events are matched instead. The Require these events to be matched by the pattern section sets which events must be matched by the pattern in order for the route event action to route the event. If the value from an optional event is used in the route event action, then it must be selected in the Require the events to be matched by the pattern. It is not legal to use the optional events without setting them as required. It is also possible to add optional terms to the Require these events to be matched by the pattern section manually, if routing the event should be conditional on the events being matched.
If the names of the co-assignments in the pattern are modified or removed, then the route event action may refer to old names. Click Clear missing events to remove the missing coassignments.
Click OK when the route action definition is complete.
If you look at the Source view of the query, you can see that for each action you define, Query Designer inserts a %route statement in the EPL query definition. The %route() statements appear in the find statement block and can be interleaved with regular EPL.
In the Source view, the modifications you can make to %route statements are to modify the quoted name, the quoted description, and the channel. Any changes you make in the Source view will appear in Query Designer. If there is a syntax error in the Source view, you cannot display the Design view until you correct the error. The recommendation is that only Query Designer should insert %route() statements. At runtime when the query finds a match, it executes all specified actions in the order in which they are listed in the Actions pane, provided any Required events set by the route event action have been matched by the pattern.
To edit a route event action, select the route event action and click the edit sign ().
To delete a route event action, select the route event action and click the delete sign ().
The arrows at the top of the Actions pane let you change this order. To change the order, select the action you want to move and then click the appropriate arrow as many times as needed.
Specifying a time period in Query Designer
In Query Designer, you can specify a length of time:
To wait before or after an event pattern occurs. This is in the Wait operator in an event pattern.
In which all events in the pattern or some events in the pattern must be received. This is in a query time constraint condition.
When you specify a time period, it must be one of the following:
A time literal, which is an integer or float value, followed by a space, followed by one of the following:
day
days
hour
hours
min
minute
minutes
sec
second
seconds
msec
millisecond
milliseconds
Insert a space between consecutive time literals. For example, you could enter 5 min 10.0 sec.
A float literal, which can be a float value or an expression that resolves to a float value. An expression can use constants and parameters. A float literal always indicates a number of seconds.
For example, the following specifications are valid:
10 sec
3.5 hours
5 days
90 min 30.0 sec
60.0
Editing source code in Query Designer
The Query Designer provides a Source tab to view or modify the EPL source code for the query definition. Changes made in the Design tab are reflected in the Source tab, and vice versa.
Query Designer provides an Actions pane that lets you specify actions to perform when a match set is found. For each action added in the Actions pane, Query Designer inserts a %custom statement in the EPL query definition. The recommendation is that only Query Designer should insert %custom() statements.
The %custom() statements appear in the find statement block and can be interleaved with regular EPL. %custom() signifies a block of EPL that was added in the Actions pane of the Design tab. You can modify the string that contains the name of the action, the string that contains the description of the action, or the EPL inside the braces, { and }, of the %custom() statement. You should not modify other content inside the parentheses.
For example, you might see something like this in the code editor:
package com.apama.samples.usercomplaints;
query FindUsersComplainingAfterNoService {
inputs {
SupportCall() key subscriberId within 3 days;
CallDataRecord() key customerId as subscriberId within 3 days;
}
// Identifies subscribers who have not been able to make any successful
// calls after 2 days,
// and have made two support calls, the second of which escalated the
// problem.
find wait (2 days):previous -> SupportCall:firstCall
-> SupportCall:secondCall
where secondCall.escalated
without CallDataRecord:cdr where cdr.callSucceeded between
(previous firstCall)
{
%custom("title":"sendCustomerEscalationAlert","description":"Send
a warning about escalated a support call")
{
send CustomerEscalationAlert(firstCall.subscriberId,
"User escalated support request") to
"com.apama.samples.user_complaints";
}
}
}
If you want to change the syntax coloring that is used for queries, see the description of the Apama preference page Syntax Coloring.
Errors in query definitions
In the Design tab of Query Designer, as you add and edit the information that defines the query, Query Designer immediately displays error messages if you enter text that is not allowed or if you leave out a required item. Query Designer is optimized to prevent you from saving a query definition that contains an error. However, if there is an error in the query definition then Apama Plugin for Eclipse displays an error icon in the Query Designer section that defines the part of the query that contains the error, for example:
()
This appears in the toolbar of the section that contains the error. Hover over the “Errors (1 Item)” text, for example, to display a message that describes the error. You must resolve the error before Query Designer can save your query definition.
Any syntax errors in the Source tab prevents the Design tab from being used. You must correct any syntax errors in the Source tab before you can view the query in the Design tab..
A query file fails to run in the Correlator at the time of launching the Apama project if the query file has the following errors:
Syntax error — These errors prevent the Design tab from appearing. The syntax errors include errors such as mismatching brackets or quotes, missing semicolon (;) from end of statements.
Validation error — These errors prevent reporting of semantic errors, and are highlighted in the sections of the Design tab. The Completion proposals do not appear in the Custom EPL dialog. The validation errors include errors such as inconsistent keys across the inputs.
Semantic error — These errors are highlighted in the sections of the Design tab if there are no validation errors. The semantic errors include errors such as using the wrong type in an expression, or using a variable or field that does not exist.
Enabling diagnostic logging
You can enable diagnostic logging for a query file in Project Explorer view (available in all perspectives) and Minimal Navigator view (available in Apama Workbench) perspective. If you enable this feature, the selected query is generated with extra diagnostic logging when you run the project. A query with diagnostic logging enabled will have extra logging at both INFO and DEBUG level. To view the DEBUG level logging, you must run the correlator with its log level set to DEBUG. For more information, see Correlator arguments.
A check mark appears for Diagnostic Logging specifying that diagnostic logging is set to true for the selected file.
Configuring query projects
For a query application that will be deployed on a cluster of correlators, you need to add Java Message Service (JMS) support to your project. See Correlator arguments.
To deploy an Apama query application, you can export the project’s launch configuration to create a deployment script. This generates the build files, configuration files, property definition files, scripts, and EPL files and copies other resources that are used by Ant to build and launch the project on a different machine.
. The Configure Query dialog appears with the list of event types and aggregate functions.
). The Add metadata dialog appears. Enter the Key and Value, and click OK.
). The Edit metadata dialog appears. Edit the Key and Value, and click OK.
).
For more information on defining metadata, see 
)) from the palette onto the canvas and hover over the pattern for prompts to indicate where you can drop it.
) and select the kind of condition you want to add. Query Designer displays a dialog in which you define the condition.
)