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 Details

    • 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

    • tableWatermark

      TimeType tableWatermark()
      Returns the event-time watermark of the input table currently being processed.

      Watermarks are generated in sources and sent through the topology for advancing the logical clock. The current watermark of an input table is the minimum watermark of all upstream Flink subtasks producing the table.

      In multi-input scenarios, each input table can have its own independent watermark. This method returns the watermark specific to the input table that is currently being processed in the eval() method, rather than the global minimum watermark across all input tables (which is returned by currentWatermark()).

      This is particularly useful for late event detection on a per-input basis.

      If a watermark has not yet been received from all upstream Flink subtasks producing the table, the method returns null.

      Returns:
      The current watermark of the input table being processed. null if called within the onTimer() method or a watermark has not yet been received from all upstream Flink subtasks producing the table.

    • currentWatermark

      TimeType currentWatermark()
      Returns the current event-time watermark at this PTF instance.

      Watermarks are generated in sources and sent through the topology for advancing the logical clock. The current watermark of a PTF instance is the global minimum watermark of all input tables (i.e., across all upstream Flink subtasks and table partitions).

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

      If a watermark has not yet been received from all input tables, the method returns null.

      Returns:
      The current watermark at the PTF instance across all upstream Flink subtasks and table partitions. A null value is returned if no minimum logical time could be calculated across all inputs; this happens during startup or recovery when one or more active (i.e. not idle) inputs haven't sent a watermark yet.

    • 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.

      If the timestamp of the registered timer is already less than or equal to the current watermark, the timer fires on the next watermark advance if registered from within eval(), or immediately after the current timer finishes if registered from within onTimer(). Note that unconditionally re-registering a past-time timer from within onTimer() causes an infinite loop.

      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.

      If the timestamp of the registered timer is already less than or equal to the current watermark, the timer fires on the next watermark advance if registered from within eval(), or immediately after the current timer finishes if registered from within onTimer(). Note that unconditionally re-registering a past-time timer from within onTimer() causes an infinite loop.

      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.