Home > Documentation > HEARTBEAT Statement

HEARTBEAT Statement

Syntax

stream_expression WITH HEARTBEAT ON field_identifier
  EVERY interval [TIMEOUT timeout]

Substitutable Fields

stream_expression:

A StreamSQL statement that produces a stream.

field_identifier:

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

interval:

An integer value that specifies the interval at which heartbeat will emit tuples.

timeout:

An integer value that specifies a permissable delay in receiving the data tuple.

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 also calibrates the system clock using the input stream. 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, then HEARTBEAT will synthesize a tuple, with all null data fields except for the timestamp, and emit it.

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

The HEARTBEAT will not begin to emit tuples until the first data tuple has passed along the stream. The HEARTBEAT will emit 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 that is greater than the upcoming HEARTBEAT interval the heartbeat will immediately emit as many tuples as needed to bring its timestamp in line with the timestamp values currently on the stream.

HEARTBEAT generates a stream and may be used anywhere a stream expression is acceptable. Alternatively, the output could be "captured" in a stream, as illustrated in the following code fragment.

CREATE [OUTPUT] STREAM stream_identifier;
... WITH HEARTBEAT ON ... INTO stream_identifier;