Class SessionWindows
- java.lang.Object
-
- org.apache.kafka.streams.kstream.SessionWindows
-
public final class SessionWindows extends Object
A session based window specification used for aggregating events into sessions.Sessions represent a period of activity separated by a defined gap of inactivity. Any events processed that fall within the inactivity gap of any existing sessions are merged into the existing sessions. If the event falls outside of the session gap then a new session will be created.
For example, if we have a session gap of 5 and the following data arrives:
+--------------------------------------+ | key | value | time | +-----------+-------------+------------+ | A | 1 | 10 | +-----------+-------------+------------+ | A | 2 | 12 | +-----------+-------------+------------+ | A | 3 | 20 | +-----------+-------------+------------+
We'd have 2 sessions for key A. One starting from time 10 and ending at time 12 and another starting and ending at time 20. The length of the session is driven by the timestamps of the data within the session. Thus, session windows are no fixed-size windows (c.f.TimeWindows
andJoinWindows
).If we then received another record:
+--------------------------------------+ | key | value | time | +-----------+-------------+------------+ | A | 4 | 16 | +-----------+-------------+------------+
The previous 2 sessions would be merged into a single session with start time 10 and end time 20. The aggregate value for this session would be the result of aggregating all 4 values.For time semantics, see
TimestampExtractor
.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
equals(Object o)
SessionWindows
grace(Duration afterWindowEnd)
Reject out-of-order events that arrive more thanafterWindowEnd
after the end of its window.long
gracePeriodMs()
int
hashCode()
long
inactivityGap()
Return the specified gap for the session windows in milliseconds.long
maintainMs()
Deprecated.since 2.1.String
toString()
SessionWindows
until(long durationMs)
Deprecated.since 2.1.static SessionWindows
with(long inactivityGapMs)
Deprecated.Usewith(Duration)
instead.static SessionWindows
with(Duration inactivityGap)
Create a new window specification with the specified inactivity gap.
-
-
-
Method Detail
-
with
@Deprecated public static SessionWindows with(long inactivityGapMs)
Deprecated.Usewith(Duration)
instead.Create a new window specification with the specified inactivity gap in milliseconds.- Parameters:
inactivityGapMs
- the gap of inactivity between sessions in milliseconds- Returns:
- a new window specification with default maintain duration of 1 day
- Throws:
IllegalArgumentException
- ifinactivityGapMs
is zero or negative
-
with
public static SessionWindows with(Duration inactivityGap)
Create a new window specification with the specified inactivity gap.- Parameters:
inactivityGap
- the gap of inactivity between sessions- Returns:
- a new window specification with default maintain duration of 1 day
- Throws:
IllegalArgumentException
- ifinactivityGap
is zero or negative or can't be represented aslong milliseconds
-
until
@Deprecated public SessionWindows until(long durationMs) throws IllegalArgumentException
Deprecated.since 2.1. UseMaterialized.retention
or directly configure the retention in a store supplier and useMaterialized.as(SessionBytesStoreSupplier)
.Set the window maintain duration (retention time) in milliseconds. This retention time is a guaranteed lower bound for how long a window will be maintained.- Returns:
- itself
- Throws:
IllegalArgumentException
- ifdurationMs
is smaller than window gap
-
grace
public SessionWindows grace(Duration afterWindowEnd) throws IllegalArgumentException
Reject out-of-order events that arrive more thanafterWindowEnd
after the end of its window.Note that new events may change the boundaries of session windows, so aggressive close times can lead to surprising results in which an out-of-order event is rejected and then a subsequent event moves the window boundary forward.
- Parameters:
afterWindowEnd
- The grace period to admit out-of-order events to a window.- Returns:
- this updated builder
- Throws:
IllegalArgumentException
- if theafterWindowEnd
is negative of can't be represented aslong milliseconds
-
gracePeriodMs
public long gracePeriodMs()
-
inactivityGap
public long inactivityGap()
Return the specified gap for the session windows in milliseconds.- Returns:
- the inactivity gap of the specified windows
-
maintainMs
@Deprecated public long maintainMs()
Deprecated.since 2.1. UseMaterialized.retention
instead.Return the window maintain duration (retention time) in milliseconds.For
SessionWindows
the maintain duration is at least as small as the window gap.- Returns:
- the window maintain duration
-
-