Using the Sequence Operator

  The Sequence operator generates a new sequence value for each tuple that passes through the operator, based on the current value of a sequence identifier and an updating expression. You can use the sequence values downstream as required by your application, such as to generate unique identifiers for tuples or to specify expressions that you want to use as keywords for query tables.

Introduction

The Sequence operator uses or appends a numeric field of type long to the schema definition for its incoming stream, which is otherwise passed through unmodified. The field contains values that StreamBase generates according to a sequence definition you specify as part of the operator. The settings for the operator include a name for the output field to be added or replaced, a name for the sequence variable to be used to hold the most recent value of the sequence, and an expression to use to calculate each value in the sequence.

To specify a Sequence operator, drag it from the Operators drawer in Studio's Palette view to the EventFlow canvas. More than one downstream operator can share the Sequence operator's added field by dragging more than one arc from the Sequence operator's output stream.

The sequence variable is of Java type Long, which means it can hold sequences in the range –9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, inclusive.

Linking Sequence Operators to Share State

You can designate two or more Sequence operators to share the same Sequence ID state by specifying the same Sequence ID for those operators. This can be useful in several cases:

  • You can add sequence values generated from the same Sequence ID to the tuples of more than one incoming stream as a way of coordinating two related but separate streams.

  • You can use one of a pair of Sequence operators to reset the value to zero (or to another point) when certain processing conditions are met.

    For example, to start a Sequence operator counting from 100:

    • Link two Sequence operators together by assigning both the same Sequence ID.

    • For the first Sequence operator, set the update expression to 100.

    • Use the Once adapter to initialize the Sequence ID value by connecting the output of the Once adapter to the input of the first Sequence operator.

    • Use only the second Sequence operator to append to an incoming stream, which now begins sequencing with 100.

Properties: General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. 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 checkbox 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 purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Settings Tab

In the Properties view for a Sequence operator, the Settings tab requires the following parameters:

Parameter Description
Output field name Name of the field that contains the generated sequence value. The type of the field is long, and its default initial value is 0. You can specify an existing input field name to contain the sequence values. If you specify a new field name, it is then added to the schema.
Sequence ID Name of a dynamic variable that holds the most recent value of the sequence. The scope of the Sequence ID variable is the containing module. The default name is the operator name plus id.

You can specify the same Sequence ID for more than one Sequence operator in the same module, in which case all such operators share the same state. See Linking Sequence Operators for a discussion of this feature.

Update Expression A StreamBase expression for updating the value of the Sequence ID. The default value for this expression increments the Sequence ID field by 1. This incremented value is then inserted into the output field.

For example, say the field name for the output field is seqid, the Sequence ID is id, and the update expression is id+10. In this case, StreamBase increases the value of id by 10 in the seqid field for each successive incoming tuple.