apache / apache/beam

Clarify windowing behavior in Javadoc

Open
#21,158 0 comments 0 reactions 0 assignees View on GitHub
core improvement java P3
Dominant language
Java
Stars
8.7k
Forks
4.7k
Avg merge
1d 20h
Merged PRs (30d)
196

Description

Feedback from a user:

> I'm confused by the documentation around AfterProcessingTime.pastFirstElementInPane(). The javadoc text seems somewhat contrived:
> "Creates a trigger that fires when the current processing time passes the processing time at which this trigger saw the first element in a pane."
> Doesn't this just mean that the trigger fires as soon it sees the first element in the pane? Processing time, IIUC, always increases monotonically.
> The text in the Beam documentation is also not very illuminating:
> "the AfterProcessingTime.pastFirstElementInPane() trigger emits a window after a certain amount of processing time has passed since data was received"
> It's not clear what the "certain amount of processing time" is. Is it some small, fixed epsilon? Is it configurable?
> Another point of confusion: there seems to be inconsistency between the AfterWatermark Javadoc and the Beam documentation on triggers w.r.t. the behavior of the default trigger. The Javadoc makes it sound as though the default trigger is sufficient for handling late data. However, the Beam documentation states that late data is discarded. It's not clear which is correct. It seems that the Javadoc is the misleading one, as it omits discussion of accumulation modes and allowed lateness.

Note: If this requires additional work after the changes to the Javadoc, please assign to the website component after the changes to the Java source files are complete.

Imported from Jira [BEAM-13160](https://issues.apache.org/jira/browse/BEAM-13160). Original Jira may contain additional context.
Reported by: pcoet.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.