Split Sessions

Split each path into sub-sessions and add session ID and index columns.

At least one boundary criterion must be provided: separator, bounds, or timeout. separator and bounds are mutually exclusive; timeout may be combined with either.

Usage

stream.split_sessions(timeout="30m")
stream.split_sessions(separator="app_open")
stream.split_sessions(bounds={"start_event": "session_start", "end_event": "session_end"})
stream.split_sessions(separator="app_open", timeout="1h")

How it works

Toy paths showing exactly what happens to the eventstream for each session-boundary mode. Exactly one of separator, start_event + end_event, or timeout must be given; timeout may additionally be combined with either of the other two to also break a session on an inactivity gap.

timeout

Every event belongs to a session; a new session starts whenever the gap to the previous event exceeds timeout. Unlike the other two modes, no rows are ever dropped from the output.

Before: A at 00:00:00, B at 00:00:30, C at 01:00:00

stream.split_sessions(timeout="1m")

After — A and B are within a minute of each other and share a session; the hour-long gap before C starts a new one:

session_id = user_1_1, user_1_1, user_1_2

timeout can combine with separator or start_event + end_event to also break a session early on an inactivity gap, without changing which events get dropped.

separator

A session is every event up to the next separator event, exclusive on both ends — the separator marks the start of the following session and is dropped from the output. Events before the first separator aren't part of any session and pass through unchanged, with session_id/session_index left empty.

Before: sep → event_1 → event_2 → sep → event_3

stream.split_sessions(separator="sep")

After — two sessions; the sep events themselves are removed:

event_1 → event_2 → event_3, with session_id = user_1_1, user_1_1, user_1_2

bounds

A session is every event strictly between a start_event and the next end_event — both boundary events are dropped from the output. The two keys are one mode, so they travel together in one argument.

Before: start → event_1 → event_2 → end

stream.split_sessions(bounds={"start_event": "start", "end_event": "end"})

After:

event_1 → event_2, with session_id = user_1_1, user_1_1

Parameters

Parameter	Type	Description
`session_col`	`str, default "session_id"`	Name of the new column that holds the unique session identifier.
`session_index_col`	`str, default "session_index"`	Name of the new column that holds the 1-based session index within each path.
`separator`	`str or list of str, optional`	Event name(s) that mark a session boundary. The separator event starts a new session; the separator row itself is dropped from the output.
`bounds`	`dict, optional`	Sessions delimited by their own opening and closing events, given as `start_event` and `end_event` — both required. Events outside a `start_event`..`end_event` window get no session.
`timeout`	`str or pandas.Timedelta, optional`	Inactivity gap after which a new session starts, as a pandas-style duration string with an explicit unit — e.g. `"30m"`, `"1h"`, `"1800s"` — or a `pandas.Timedelta`. Bare numbers are rejected to avoid unit ambiguity.
`path_col`	`str, optional`	Path ID column override; defaults to `schema.path_col`.