HEARTBEAT Statement

Syntax

stream_expression 
  WITH HEARTBEAT ON field_identifier
  EVERY interval [SLACK timeout]
  INTO stream_identifier
  [ERROR INTO stream_identifier];

Substitutable Fields

stream_expression

A StreamSQL statement that produces a stream.

field_identifier

The unique identifier (name) for a field in the input stream that holds a timestamp data type.

interval

A decimal value that specifies the interval (in seconds and fractions thereof) at which the heartbeat is to emit tuples.

timeout

A decimal value in seconds that specifies a permissible delay in receiving the data tuple.

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

HEARTBEAT adds timer tuples on the same stream with your data tuples so that downstream operations can occur even if there is a lull in the incoming data. HEARTBEAT detects late or missing tuples. Like METRONOME, HEARTBEAT uses the system clock and emits output tuples periodically, but HEARTBEAT can also emit tuples using information in the input stream, independent of the system clock.

HEARTBEAT passes input tuples directly through to the output stream, updating its internal clock. If an expected input tuple does not arrive within the configured interval plus a timeout value, then HEARTBEAT synthesizes a tuple, with all null data fields except for the timestamp, and emits it.

HEARTBEAT sits on a stream and passes through data tuples without modification. The data tuple must include a field of type timestamp. At configurable intervals, HEARTBEAT inserts a tuple with the same schema as the data tuple onto the stream. Fields within tuples that originate from the HEARTBEAT are set to null, with the exception of the timestamp field, which always has a valid value.

HEARTBEAT does not begin to emit tuples until the first data tuple has passed along the stream. HEARTBEAT emits a tuple whenever the output interval elapses on the system clock or whenever the data tuple's timestamp field crosses a multiple of the output interval. If a data tuple's timestamp field has a value greater than the upcoming HEARTBEAT interval, HEARTBEAT immediately emits as many tuples as needed to bring its timestamp in line with the timestamp values currently on the stream.

HEARTBEAT generates a stream and can be used anywhere a stream expression is acceptable.

The following example illustrates the use of HEARTBEAT:

CREATE INPUT STREAM InputStream (
    symbol string,
    price double,
    date timestamp
);
CREATE OUTPUT STREAM Output ;
CREATE ERROR OUTPUT STREAM Flameout ;

SELECT * from InputStream
    WITH HEARTBEAT ON date 
    EVERY 10 SLACK 0.5
    INTO Output 
    ERROR INTO Flameout;