This topic describes how to use the Pattern operator to define pattern queries in EventFlow modules.
After adding a Pattern operator to your EventFlow (for example, by dragging a Pattern operator icon from the palette), complete the fields in each of the tabs, as described in the sections that follow.
Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Storage method: Specify settings for this operator with the same in heap and in transactional memory options described for the Annotations tab of the EventFlow Editor. The default setting is Inherit from containing module.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
Use this tab to define your query's template and window, and optionally, a predicate.
- Number of input ports
Specify one port for each input stream that you want to match on.
Enter an expression that matches pairs of named streams (or subqueries that evaluate to stream names), using patterns to specify how the pairs are compared.
To identify a stream, use the operator's input port designation in this format:
For example, if your operator has one port, refer to its input stream as
input1; if it has two ports, the first port (the top one in the EventFlow) is
input1and the second (lower) port is
input2. To verify the name of a stream, toggle the Expressions Pane button and open the Streams tab.
See the Patterns section in StreamBase Pattern Matching Language for the available template patterns.
- Window Type
Choose the type of window you want to determine the terminating event for the query. One of the following:
The window closes and the query operation terminates when the time specified in the Window Size field has elapsed.
The window closes when a range of values in the specified Order Field equals or exceeds the specified Window Size.
- Order Field
For value-based windows only, the field that will be compared across all streams. The order field must be a top-level numeric or timestamp field, as described in StreamBase Pattern Matching Language.
- Window Size
For time-based windows, specify the time in seconds. For example, a window size of 5 means that the last tuple must arrive within 5 seconds after the first tuple arrives.
For value-based windows, enter a value appropriate for the order field. For example, a window size of 5 for an int field means that the window will close when the range of values of that field, across all streams, equals or exceeds 5.
You can also specify a module parameter in the form
Optionally, enter a WHERE clause that further constrains the result of your query.
The following screens show an application with a Pattern operator, and the operator's Properties view open at the Pattern Settings tab:
The Output Settings tab allows you to specify the field names from input streams to include in the output, and what to name them. Specify output fields using one of two options:
The default option is all input fields, which specifies that each field in all input streams are emitted on the output stream.
Select explicitly specified fields to specify the output fields manually. In the Output Fields grid, specify the name that you want to appear in the output field, and an expression, based on the input to the operator, that resolves to an input field name. Qualify field names with stream names to distinguish like-named fields in two or more input streams.
Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.
Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.
A Pattern operator will assign a value of
null to a
field whose expression evaluates to null. That is, if the evaluation of the field
results in a NullValueException, then the value of the
field will be
null. For more information, see Using Nulls.