Session Windows

Analogy categoryAnalogies

What Makes Session Windows Different

Unlike tumbling and sliding windows, which have a fixed length and predetermined boundaries on the clock, a session window's size is dynamic and data-driven: it groups consecutive events for the same key as long as the gap between them stays below a configured inactivity timeout, and the window closes only once that gap is exceeded. EventTimeSessionWindows.withGap(Time.minutes(15)) means that if a user is continuously active with less than 15 minutes between actions, all of that activity merges into a single, ever-extending session window; the moment 15 minutes pass with no new event, the window is considered closed. This makes session windows the natural fit for modeling real user behavior — a shopping session, a video-watching binge, a support chat — where the 'right' boundary is behavioral, not a fixed clock tick.

🏏

Cricket analogy: A session window is like a rain-delay rule that keeps a single day's play open as long as gaps between showers stay under 30 minutes, but calls the day's play closed the moment a longer gap forces stumps — the 'session' length is dictated by weather activity, not a fixed clock.

How Session Windows Merge Under the Hood

Internally, Flink implements session windows by initially assigning each incoming event to its own provisional window spanning [eventTimestamp, eventTimestamp + gap), and then a MergingWindowAssigner repeatedly merges any two windows whose ranges overlap. When a new event arrives close enough to an existing session's tail, its provisional window overlaps the existing one, triggering a merge that extends the session; any window function attached (e.g., ProcessWindowFunction) must therefore be merge-aware, since Flink calls onMerge to combine per-window state such as trigger timers and accumulators from the windows being combined. This merging behavior means the number of active session windows per key can temporarily spike before consolidating, which matters for state-size planning under bursty, high-fan-out event patterns.

🏏

Cricket analogy: This merge process is like a rain-delay tracker provisionally logging each shower as its own gap-window, then retroactively stitching two showers together into one longer delay once a new shower is confirmed to start before the previous one's buffer expired.

Dynamic Gaps with SessionWindowTimeGapExtractor

A fixed gap works for many use cases, but Flink also supports EventTimeSessionWindows.withDynamicGap(SessionWindowTimeGapExtractor<T>), which computes a per-event gap duration based on the element itself. This is useful when different keys (or even different events for the same key) genuinely warrant different inactivity thresholds — for example, a premium user's session might reasonably tolerate a longer 30-minute gap before being considered 'ended' compared to a free-tier user's 5-minute threshold, or a mobile client's session gap might need to be longer than a desktop client's to account for background app suspension.

🏏

Cricket analogy: A dynamic gap is like giving Test matches a longer rain-delay tolerance before calling play abandoned compared to a T20, since the format itself dictates how much interruption is reasonable before the 'session' is considered over.

java

DataStream<UserActivity> activity = ...;

// Fixed 15-minute inactivity gap
activity
    .keyBy(UserActivity::getUserId)
    .window(EventTimeSessionWindows.withGap(Time.minutes(15)))
    .process(new SessionSummaryFunction());

// Dynamic gap: premium users get 30 minutes, free-tier users get 5
activity
    .keyBy(UserActivity::getUserId)
    .window(EventTimeSessionWindows.withDynamicGap(
        (SessionWindowTimeGapExtractor<UserActivity>) event ->
            event.isPremiumUser() ? Time.minutes(30).toMilliseconds() : Time.minutes(5).toMilliseconds()
    ))
    .process(new SessionSummaryFunction());

Session windows work with both event time (EventTimeSessionWindows) and processing time (ProcessingTimeSessionWindows) variants, though event time is strongly preferred for reproducible, replayable session boundaries.

Because session windows merge dynamically, aggregation functions and window state must be merge-compatible — a naive custom trigger or stateful function that doesn't implement proper merge logic can silently lose or duplicate state when two provisional sessions combine.

Session windows have a dynamic size, closing only after a configured inactivity gap with no new events for that key.
Flink implements sessions by assigning provisional per-event windows and merging any that overlap in time.
Window functions must be merge-aware, since Flink invokes onMerge to combine state from merging provisional windows.
withDynamicGap lets the inactivity threshold vary per event via a SessionWindowTimeGapExtractor.
Session windows suit behavioral analysis like shopping carts, binge-watching, or chat sessions better than fixed-clock windows.
Both event-time and processing-time session window variants exist, with event time preferred for reproducibility.
Bursty traffic can temporarily spike the number of provisional windows per key before they consolidate.