From 2764d85eb57c3bf85c0936bda8b5407ebb11c9c7 Mon Sep 17 00:00:00 2001 From: Ken Chen Date: Thu, 16 Oct 2025 12:15:12 -0700 Subject: [PATCH] refine session window --- docs/global-aggregation.md | 8 ++--- docs/hop-aggregation.md | 34 +++++++++--------- docs/session-aggregation.md | 70 +++++++++++++++++++++++++++++++++++-- docs/tumble-aggregation.md | 24 ++++++------- 4 files changed, 101 insertions(+), 35 deletions(-) diff --git a/docs/global-aggregation.md b/docs/global-aggregation.md index 8c21a020..85057acd 100644 --- a/docs/global-aggregation.md +++ b/docs/global-aggregation.md @@ -24,10 +24,10 @@ The `EMIT PERIODIC ` clause tells Timeplus to periodically emit aggrega - `` must be an integer greater than 0. - `` can be one of: -- ms (milliseconds) -- s (seconds) -- m (minutes) -- h (hours) +- `ms` (milliseconds) +- `s` (seconds) +- `m` (minutes) +- `h` (hours) **Examples:** ```sql diff --git a/docs/hop-aggregation.md b/docs/hop-aggregation.md index 13cc92f2..ced8b25c 100644 --- a/docs/hop-aggregation.md +++ b/docs/hop-aggregation.md @@ -16,29 +16,29 @@ For example, with a 10-minute window size and a 5-minute hop interval, a new win ## Syntax ```sql -SELECT , -FROM hop(, [], , ) +SELECT , +FROM hop(, [], , ) [WHERE clause] -GROUP BY [], ... -EMIT +GROUP BY [window_start | window_end], ... +EMIT ``` ### Parameters -- `` : the source stream the hop window applies to. **Required** -- `` : the event timestamp column which is used to calculate window starts / ends and internal watermark. You can use `now()` or `now64(3)` to enable processing time hop window. Default is `_tp_time` if absent. **Optional** +- `` : the source stream the hop window applies to. **Required** +- `` : the event timestamp column which is used to calculate window starts / ends and internal watermark. You can use `now()` or `now64(3)` to enable processing time hop window. Default is `_tp_time` if absent. **Optional** - `` : how frequently new windows start (must be less than or equal to the window size). Supported interval units are listed below. **Required** - - `s` : second - - `m` : miniute - - `h` : hour - - `d` : day - - `w` : week -- `` : hop window interval size. Supported interval units are listed below. **Required** - - `s` : second - - `m` : miniute - - `h` : hour - - `d` : day - - `w` : week + - `s` (second) + - `m` (miniute) + - `h` (hour) + - `d` (day) + - `w` (week) +- `` : hop window interval size. Supported interval units are listed below. **Required** + - `s` (second) + - `m` (miniute) + - `h` (hour) + - `d` (day) + - `w` (week) ### Example diff --git a/docs/session-aggregation.md b/docs/session-aggregation.md index 9f3dbbd9..890262e5 100644 --- a/docs/session-aggregation.md +++ b/docs/session-aggregation.md @@ -1,3 +1,69 @@ -# Session Window Aggregation {#session_window} +# Session Window Aggregation -This is similar to tumble and hop window. Please check the [session](/functions_for_streaming#session) function. +## Overview + +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). + +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. + +Each session is unique to a specific grouping key and does not overlap with other sessions for the same key. + +## Syntax + +```sql +SELECT , +FROM session( [, ], [, ] [, , ]) +[WHERE ] +GROUP BY [window_start | window_end], ; +EMIT ; +``` + +### Parameters + +- `` : (**Required**) The source stream the hop window applies to. +- `` : (**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. +- `` : (**Required**) Defines the inactivity timeout to close the session window (e.g., 5s, 1m). +- `` : (**Optional**) Maximum allowed session duration. Once exceeded, the session closes automatically. Default is 5 times of `` if absent. +- `[, ]` — **(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: + 1. `[, ]` — Include events that satisfy both the start and end conditions. + 2. `[, )` — Include events that satisfy only the start condition. + 3. `(, ]` — Include events that satisfy only the end condition. + 4. `(, )` — Exclude events that meet either the start or end condition. + +In summary, a session window can close under any of the following conditions: +1. **Idle timeout reached** — no new events arrive within the configured idle gap. +2. **Maximum session duration reached** — the window duration exceeds the specified maximum length. +3. **End condition met** — the user-defined end condition (e.g., a specific event or signal) is satisfied. + +### Example + +```sql +CREATE STREAM click_stream( + user_id string, + action string, + timestamp datetime64(3) +); + +SELECT + user_id, + count(*) AS click_count, + window_start, + window_end +FROM + session(click_stream, timestamp, 15s, 30m, position(action, 'login') > 0, position(action, 'logout') > 0) +GROUP BY + user_id, window_start, window_end +``` + +**Explanation**: +- The query defines a **session window** over the stream `click_stream`. The session window starts when action is `login`. +- Session window ends when + 1. `logout` action happens or + 2. 15 seconds of inactivity are detected or + 3. Max window duration 30 minutes reaches + +## Emit Policies + +Currently, only **EMIT AFTER WINDOW CLOSE`** is supported. + +The session window will emit results automatically once it is closed — that is, when any of the configured closing conditions are met. diff --git a/docs/tumble-aggregation.md b/docs/tumble-aggregation.md index 7e8eeed8..324b88ae 100644 --- a/docs/tumble-aggregation.md +++ b/docs/tumble-aggregation.md @@ -12,23 +12,23 @@ This makes them simple, deterministic, and ideal for producing periodic reports ## Syntax ```sql -SELECT , -FROM tumble(, [], ]) +SELECT , +FROM tumble(, [], ]) [WHERE clause] -GROUP BY [window_start | window_end], ... -EMIT +GROUP BY [window_start | window_end], ... +EMIT ``` ### Parameters -- `` : the source stream the tumble window applies to. **Required** -- `` : the event timestamp column which is used to calculate window starts / ends and internal watermark. You can use `now()` or `now64(3)` to enable processing time tumble window. Default is `_tp_time` if absent. **Optional** -- `` : tumble window interval size. Supported interval units are listed below. **Required** - - `s` : second - - `m` : miniute - - `h` : hour - - `d` : day - - `w` : week +- `` : the source stream the tumble window applies to. **Required** +- `` : the event timestamp column which is used to calculate window starts / ends and internal watermark. You can use `now()` or `now64(3)` to enable processing time tumble window. Default is `_tp_time` if absent. **Optional** +- `` : tumble window interval size. Supported interval units are listed below. **Required** + - `s` (second) + - `m` (miniute) + - `h` (hour) + - `d` (day) + - `w` (week) ### Example