[FLINK-22611] add documentation about the semantics of timestamp for time window output

• Type: Improvement
• Status: Open
• Priority: Not a Priority
• Resolution: Unresolved
• Labels: auto-deprioritized-major auto-deprioritized-minor
• Assignee: Unassigned
• Reporter: Zhenhao Li
• Created: 09/May/21 13:23
• Updated: 23/Dec/21 10:39

Description

It seems that all windowed aggregation output receives the timestamp metadata if event time is being used for the processing.
However, I couldn't find anything on the documentation pages about what timestamp value each output gets. Intuitively, it makes sense to assume it is the maximal timestamp from the input records of the window.

After digging in the source code, I got the impression that the timestamp of the output is actually 1 millisecond before the window end time.
See
https://github.com/apache/flink/blob/99c2a415e9eeefafacf70762b6f54070f7911ceb/flink-streaming-java/src/main/java/org/apache/flink/streaming/runtime/operators/windowing/EvictingWindowOperator.java#L375
and
https://github.com/apache/flink/blob/99c2a415e9eeefafacf70762b6f54070f7911ceb/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/windowing/windows/TimeWindow.java#L84

Correct me if I'm wrong. If I'm right, I think we should add documentation about it since this is very important because it is not uncommon to chain multiple windowed processes. Understanding the timestamp semantics is critical to the correctness of the code.