|
1 | | -# Session Window Aggregation {#session_window} |
| 1 | +# Session Window Aggregation |
2 | 2 |
|
3 | | -This is similar to tumble and hop window. Please check the [session](/functions_for_streaming#session) function. |
| 3 | +## Overview |
| 4 | + |
| 5 | +A **Session Window** groups together events that arrive close in time, separated by periods of inactivity. Unlike [tumble](/tumble-aggregation) and [hop](/hop-aggregation) windows, which are defined by fixed durations, a session window dynamically starts when the first event arrives and closes when there’s a defined period of **inactivity** (known as the *idle* gap). |
| 6 | + |
| 7 | +This type of window is ideal for modeling user sessions, bursty event streams, or workloads where data comes in uneven bursts rather than at constant intervals. |
| 8 | + |
| 9 | +Each session is unique to a specific grouping key and does not overlap with other sessions for the same key. |
| 10 | + |
| 11 | +## Syntax |
| 12 | + |
| 13 | +```sql |
| 14 | +SELECT <grouping_keys>, <aggregate_functions> |
| 15 | +FROM session(<stream_name> [, <timestamp_column>], <idle_gap> [, <max_duration>] [, <start_condition>, <end_condition>]) |
| 16 | +[WHERE <conditions>] |
| 17 | +GROUP BY [window_start | window_end], <other_grouping_keys>; |
| 18 | +EMIT <emit_policy>; |
| 19 | +``` |
| 20 | + |
| 21 | +### Parameters |
| 22 | + |
| 23 | +- `<stream_name>` : (**Required**) The source stream the hop window applies to. |
| 24 | +- `<timestamp_column>` : (**Required**) The event timestamp column which is used to calculate window starts / ends and timeout. Using wall clock `now()` or `now64(3)` usually doesn't make sense in hop window. Default is `_tp_time` if absent. |
| 25 | +- `<idle_gap>` : (**Required**) Defines the inactivity timeout to close the session window (e.g., 5s, 1m). |
| 26 | +- `<max_duration>` : (**Optional**) Maximum allowed session duration. Once exceeded, the session closes automatically. Default is 5 times of `<idle_gap>` if absent. |
| 27 | +- `[<start_condition>, <end_condition>]` — **(Optional)** A pair of custom boolean expressions used to define the session’s start and end boundaries. These conditions are useful for domain-specific triggers that go beyond time-based sessioning. The **inclusion or exclusion** of events relative to the boundary conditions depends on the bracket type: |
| 28 | + 1. `[<start_condition>, <end_condition>]` — Include events that satisfy both the start and end conditions. |
| 29 | + 2. `[<start_condition>, <end_condition>)` — Include events that satisfy only the start condition. |
| 30 | + 3. `(<start_condition>, <end_condition>]` — Include events that satisfy only the end condition. |
| 31 | + 4. `(<start_condition>, <end_condition>)` — Exclude events that meet either the start or end condition. |
| 32 | + |
| 33 | +In summary, a session window can close under any of the following conditions: |
| 34 | +1. **Idle timeout reached** — no new events arrive within the configured idle gap. |
| 35 | +2. **Maximum session duration reached** — the window duration exceeds the specified maximum length. |
| 36 | +3. **End condition met** — the user-defined end condition (e.g., a specific event or signal) is satisfied. |
| 37 | + |
| 38 | +### Example |
| 39 | + |
| 40 | +```sql |
| 41 | +CREATE STREAM click_stream( |
| 42 | + user_id string, |
| 43 | + action string, |
| 44 | + timestamp datetime64(3) |
| 45 | +); |
| 46 | + |
| 47 | +SELECT |
| 48 | + user_id, |
| 49 | + count(*) AS click_count, |
| 50 | + window_start, |
| 51 | + window_end |
| 52 | +FROM |
| 53 | + session(click_stream, timestamp, 15s, 30m, position(action, 'login') > 0, position(action, 'logout') > 0) |
| 54 | +GROUP BY |
| 55 | + user_id, window_start, window_end |
| 56 | +``` |
| 57 | + |
| 58 | +**Explanation**: |
| 59 | +- The query defines a **session window** over the stream `click_stream`. The session window starts when action is `login`. |
| 60 | +- Session window ends when |
| 61 | + 1. `logout` action happens or |
| 62 | + 2. 15 seconds of inactivity are detected or |
| 63 | + 3. Max window duration 30 minutes reaches |
| 64 | + |
| 65 | +## Emit Policies |
| 66 | + |
| 67 | +Currently, only **EMIT AFTER WINDOW CLOSE`** is supported. |
| 68 | + |
| 69 | +The session window will emit results automatically once it is closed — that is, when any of the configured closing conditions are met. |
0 commit comments