Using the Pattern Operator

This topic describes how to use the Pattern operator to define pattern queries in EventFlow applications. In a StreamSQL application use the SELECT Statement.

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.

Properties: General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. 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.

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 and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Pattern Settings Tab

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.

Template

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:

inputn

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 input1 and 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:

Time

The window closes and the query operation terminates when the time specified in the Window Size field has elapsed.

Value

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 ${ParamName}.

Predicate

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:

Properties: Output 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.

Properties: Concurrency Tab

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.

Caution

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.

Null Values

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.