- Index

< Previous |  | Next >

# BSORT Statement

## Syntax

    BSORT {stream_identifier | stream_expression} ON field_identifier
      SIZE size [TUPLES]
      [ERROR INTO stream_identifier];

### Substitutable Fields

`stream_identifier`

  The identifier (name) of the stream that is passed into BSORT.

`stream_expression`

  A StreamSQL statement that produces a stream that is passed into BSORT.

`field_identifier`

  The unique identifier (name) for the tuple field on which the sort will be based.

`size`

  An integer value that specifies either the number of tuples that are held within the sorting buffer, or the range of field_identifier values that will be held within the sort buffer.

### ERROR INTO Clause

You can append an ERROR INTO clause just before the closing semicolon. The StreamSQL ERROR INTO clause is analogous to the Enable Error Output Port check box for operators and adapters in EventFlow applications.

Use ERROR INTO with the name of a stream, which must already exist. This sets up an Error Port for this operator, which is much like a local catch mechanism for errors from this operator.

See Using Error Ports and Error Streams for a discussion of StreamBase error handling mechanisms.

## Discussion

BSORT can reorder slightly disordered streams by applying a user-defined number of sort passes over a buffer. Since BSORT produces a re-ordered stream, its output can be used in any context in which a stream is expected.

`stream_identifier` is the stream to sort, alternatively stream_expression generates the stream to sort; `field_identifier` is the field on which to sort the input tuples.

If the optional keyword TUPLES is present, then BSORT creates a fixed length buffer (specified through the SIZE entry) and sorts retained tuples by the value of the sort field.

If the TUPLE keyword is absent, and the sort field is numeric, BSORT creates an unbounded buffer and retains all tuples whose sort field value is within the range ±SIZE. Once a tuple is buffered whose sort field value is above the upper limit of the range, the range is reset around this tuple's sort field value and BSORT emits all retained tuples whose sort field value now falls outside of the new range.

For example, BSORT SIZE 3 TUPLES, will create a 3 position fixed length buffer and tuples will be sorted according to the value of their sort fields. The statement BSORT SIZE 3 will create an unbounded buffer that will retain all tuples whose sort field values are within a range of 6.

BSORT generates a stream and can be used anywhere a stream expression is acceptable. As an alternative, the output could be captured in a stream, as illustrated in the following code fragments.

    CREATE [OUTPUT] STREAM stream_identifier;
    BSORT ... INTO stream_identifier;

    CREATE [OUTPUT] STREAM stream_identifier AS
      BSORT ...;

Or, for an OUTPUT STREAM

    BSORT ... => CREATE OUTPUT STREAM stream_identifier;

Back to Top ^