org.apache.kafka.streams.kstream

Class SlidingWindows

java.lang.Object

org.apache.kafka.streams.kstream.SlidingWindows

public final class SlidingWindows
extends Object

A sliding window used for aggregating events.

Sliding Windows are defined based on a record's timestamp, the window size based on the given maximum time difference (inclusive) between records in the same window, and the given window grace period. While the window is sliding over the input data stream, a new window is created each time a record enters the sliding window or a record drops out of the sliding window.

Records that come after set grace period will be ignored, i.e., a window is closed when stream-time > window-end + grace-period.

For example, if we have a time difference of 5000ms and the following data arrives:

 +--------------------------------------+
 |    key    |    value    |    time    |
 +-----------+-------------+------------+
 |    A      |     1       |    8000    |
 +-----------+-------------+------------+
 |    A      |     2       |    9200    |
 +-----------+-------------+------------+
 |    A      |     3       |    12400   |
 +-----------+-------------+------------+
 

We'd have the following 5 windows:

• window [3000;8000] contains [1] (created when first record enters the window)
• window [4200;9200] contains [1,2] (created when second record enters the window)
• window [7400;12400] contains [1,2,3] (created when third record enters the window)
• window [8001;13001] contains [2,3] (created when the first record drops out of the window)
• window [9201;14201] contains [3] (created when the second record drops out of the window)

Note that while SlidingWindows are of a fixed size, as are TimeWindows, the start and end points of the window depend on when events occur in the stream (i.e., event timestamps), similar to SessionWindows.

For time semantics, see TimestampExtractor.

See Also:

TimeWindows, SessionWindows, UnlimitedWindows, JoinWindows, KGroupedStream.windowedBy(SlidingWindows), CogroupedKStream.windowedBy(SlidingWindows), TimestampExtractor

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
long	gracePeriodMs()
int	hashCode()
static SlidingWindows	ofTimeDifferenceAndGrace(Duration timeDifference, Duration afterWindowEnd) Return a window definition with the window size based on the given maximum time difference (inclusive) between records in the same window and given window grace period.
static SlidingWindows	ofTimeDifferenceWithNoGrace(Duration timeDifference) Return a window definition with the window size based on the given maximum time difference (inclusive) between records in the same window and given window grace period.
long	timeDifferenceMs()
String	toString()
static SlidingWindows	withTimeDifferenceAndGrace(Duration timeDifference, Duration grace) Deprecated. since 3.0. Use ofTimeDifferenceWithNoGrace(Duration) or ofTimeDifferenceAndGrace(Duration, Duration) instead

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

ofTimeDifferenceWithNoGrace

public static SlidingWindows ofTimeDifferenceWithNoGrace(Duration timeDifference)
                                                  throws IllegalArgumentException

Return a window definition with the window size based on the given maximum time difference (inclusive) between records in the same window and given window grace period. Reject out-of-order events that arrive after grace. A window is closed when stream-time > window-end + grace-period.

CAUTION: Using this method implicitly sets the grace period to zero, which means that any out-of-order records arriving after the window ends are considered late and will be dropped.

Parameters:

timeDifference - the max time difference (inclusive) between two records in a window

Returns:

a new window definition with no grace period. Note that this means out-of-order records arriving after the window end will be dropped

Throws:

IllegalArgumentException - if the timeDifference is negative or can't be represented as long milliseconds

ofTimeDifferenceAndGrace

public static SlidingWindows ofTimeDifferenceAndGrace(Duration timeDifference,
                                                      Duration afterWindowEnd)
                                               throws IllegalArgumentException

Return a window definition with the window size based on the given maximum time difference (inclusive) between records in the same window and given window grace period. Reject out-of-order events that arrive after afterWindowEnd. A window is closed when stream-time > window-end + grace-period.

Parameters:

timeDifference - the max time difference (inclusive) between two records in a window

afterWindowEnd - the grace period to admit out-of-order events to a window

Returns:

a new window definition with the specified grace period

Throws:

IllegalArgumentException - if the timeDifference or afterWindowEnd (grace period) is negative or can't be represented as long milliseconds

withTimeDifferenceAndGrace

@Deprecated
public static SlidingWindows withTimeDifferenceAndGrace(Duration timeDifference,
                                                                    Duration grace)
                                                             throws IllegalArgumentException

Deprecated. since 3.0. Use ofTimeDifferenceWithNoGrace(Duration) or ofTimeDifferenceAndGrace(Duration, Duration) instead

Return a window definition with the window size based on the given maximum time difference (inclusive) between records in the same window and given window grace period. Reject out-of-order events that arrive after grace. A window is closed when stream-time > window-end + grace-period.

Parameters:

timeDifference - the max time difference (inclusive) between two records in a window

grace - the grace period to admit out-of-order events to a window

Returns:

a new window definition

Throws:

IllegalArgumentException - if the specified window size is < 0 or grace < 0, or either can't be represented as long milliseconds

timeDifferenceMs

public long timeDifferenceMs()

gracePeriodMs

public long gracePeriodMs()

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object