Package org.apache.flink.table.functions

Interface ProcessTableFunction.TimeContext<TimeType>

Type Parameters:

TimeType - conversion class of timestamps, see ProcessTableFunction.Context.timeContext(Class)

Enclosing class:

ProcessTableFunction<T>

@PublicEvolving
public static interface ProcessTableFunction.TimeContext<TimeType>

A context that gives access to Flink's concepts of time and timers.

An event can have an event-time timestamp assigned. The timestamp can be accessed using the time() method.

Timers allow for continuing the processing at a later point in time. This makes waiting, synchronization, or timeouts possible. A timer fires for the registered time when the watermark progresses the logical clock.

Flink takes care of storing and restoring timers during failures or restarts. Thus, timers are a special kind of state. Similarly, timers are scoped to a virtual processor defined by the PARTITION BY clause. A timer can only be registered and deleted in the current virtual processor.

Method Summary

Modifier and Type	Method	Description
void	clearAllTimers()	Deletes all timers within the virtual partition.
void	clearTimer(String name)	Clears a timer that was previously registered under the given name.
void	clearTimer(TimeType time)	Clears a timer that was previously registered for a given time.
TimeType	currentWatermark()	Returns the current event-time watermark.
void	registerOnTime(String name, TimeType time)	Registers a timer under the given name.
void	registerOnTime(TimeType time)	Registers a timer.
TimeType	time()	Returns the timestamp of the currently processed event.

Method Detail

time

TimeType time()

Returns the timestamp of the currently processed event.

An event can be either the row of a table or a firing timer:

Row event timestamp

The timestamp of the row currently being processed within the eval() method.

Powered by the function call's on_time argument, this method will return the content of the referenced time attribute column. Returns null if the on_time argument doesn't reference a time attribute column in the currently processed table.

Timer event timestamp

The timestamp of the firing timer currently being processed within the onTimer() method.

Returns:

the event-time timestamp, or null if no timestamp is present

currentWatermark

TimeType currentWatermark()

Returns the current event-time watermark.

Watermarks are generated in sources and sent through the topology for advancing the logical clock in each Flink subtask. The current watermark of a Flink subtask is the global minimum watermark of all inputs (i.e. across all parallel inputs and table partitions).

This method returns the current watermark of the Flink subtask that evaluates the PTF. Thus, the returned timestamp represents the entire Flink subtask, independent of the currently processed partition. This behavior is similar to a call to SELECT CURRENT_WATERMARK(...) in SQL.

If a watermark was not received from all inputs, the method returns null.

In case this method is called within the onTimer() method, the returned watermark is the triggering watermark that currently fires the timer.

Returns:

the current watermark of the Flink subtask, or null if no common logical time could be determined from the inputs

registerOnTime

void registerOnTime(String name,
                    TimeType time)

Registers a timer under the given name.

The timer fires when the currentWatermark() advances the logical clock of the Flink subtask to a timestamp later or equal to the desired timestamp. In other words: A timer only fires if a watermark was received from all inputs and the timestamp is smaller or equal to the minimum of all received watermarks.

Timers can be named for distinguishing them in the onTimer() method. Registering a timer under the same name twice will replace an existing timer.

Note: Because only PTFs taking set semantic tables support state, and timers are a special kind of state, at least one ArgumentTrait.SET_SEMANTIC_TABLE table argument must be declared.

Parameters:

name - identifier of the timer

time - timestamp when the timer should fire

registerOnTime

void registerOnTime(TimeType time)

Registers a timer.

The timer fires when the currentWatermark() advances the logical clock of the Flink subtask to a timestamp later or equal to the desired timestamp. In other words: A timer only fires if a watermark was received from all inputs and the timestamp is smaller or equal to the minimum of all received watermarks.

Only one timer can be registered for a given time.

Note: Because only PTFs taking set semantic tables support state, and timers are a special kind of state, at least one ArgumentTrait.SET_SEMANTIC_TABLE table argument must be declared.

Parameters:

time - timestamp when the timer should fire

clearTimer

void clearTimer(String name)

Clears a timer that was previously registered under the given name.

The call is ignored if no timer can be found.

Parameters:

name - identifier of the timer

clearTimer

void clearTimer(TimeType time)

Clears a timer that was previously registered for a given time.

The call is ignored if no timer can be found. Named timers cannot be deleted with this method.

Parameters:

time - timestamp when the timer should have fired

clearAllTimers

void clearAllTimers()

Deletes all timers within the virtual partition.