Using the Iterate Operator

  Use the Iterate operator to emit one tuple for each element in a list. You specify a field of type list in an incoming stream, and the operator emits one tuple for each element in that field's list. Since list fields can contain a varying number of elements for each tuple, this operator resolves each incoming tuple into multiple outgoing tuples.

By default, all elements of the list value are output, in list order, one at a time. You can stop emitting elements when a predicate condition becomes false. The condition can be based on a running aggregation of previous list elements. You can also selectively emit those elements that satisfy a filter predicate. You can specify or define fields to output using the field grid on the Output Settings tab, in a similar fashion to the Map operator

For example, in incoming tuple 1, a list(double) field named Bids might have six elements. For each input tuple the Iterate operator receives, it will output six tuples (unless it has a filter expression that suppresses some), having the same fields as the incoming tuple, subject to additional expressions specified in the Output Settings field grid. For details, see Properties: Operation Settings Tab.

For example, the field grid could define an output field named oneBid using the expression each.element.Bids. That field will contain single elements of the Bids list, one at a time in list order, for each outgoing tuple and be be of data type double.

Then, in incoming tuple 2, list Bids might have three elements. The Iterate operator receives incoming tuple 2 and outputs three tuples containing oneBid fields, and so on.

The StreamSQL equivalent of the Iterate operator is the FOREACH clause of the SELECT statement. See SELECT Statement in the StreamSQL Guide. Note that iteration conditions are not supported in SSQL, but iteration filters are (as WHERE clauses).

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.

The properties view for the Operation Settings tab has the following appearance.

Use the Operation Settings tab to specify the following parameters:

You can use Iterate operators to eliminate list items that are null or fail to meet some criterion by applying a filter, or transform list item values, and then use an aggregate operator to assemble the tuples that the Iterate operator emits into a new list having the same or a different field name. For more information, see the Iterate Operator Sample and aggregate list function descriptions.

Specify an Iterate Condition if the operator should stop processing a list as soon as one or more logical criteria are met. For example, you might limit output to the first n list items or stop iterating when a flag in some field has or does not have a certain value.

The Input Field grid in the Output Settings tab is collapsed by default. When you expand it, the view has two grids, as illustrated here:

In the illustration above (taken from the sample application Iterate.sbapp), input tuples with schema {symbol string, name string, volume int, price double} have been aggregated into a list that the Iterate operator deconstructs into tuples, replacing volume and price with the field StockCost (using the expression each.element.Volume*each.element.Price). No input fields are passed directly to output, but the additional expressions each.element.Name and each.element.Symbol insert both string fields into the output stream.

Use the Concurrency tab to specify the use of parallel regions for this instance of this component. Consider selecting the parallel regions check box if this component instance is long-running or compute-intensive, can run without data dependencies on other StreamBase components, and would not cause the containing module to block while waiting for a thread to return. In this case, you may be able to improve performance by selecting this option. This option directs StreamBase Server to process this component concurrently with other processing in the application. The operating systems supported by StreamBase automatically distribute the processing of threads across multiple processors.

Back to Top ^