Split Sessions
Split each path into sub-sessions and add session ID and index columns.
At least one boundary criterion must be provided: separator,
start_event + end_event, or timeout. separator and
start_event/end_event are mutually exclusive; timeout may be combined
with either.
Usage
stream.split_sessions(timeout="30m")
stream.split_sessions(separator="app_open")
stream.split_sessions(start_event="session_start", end_event="session_end")
stream.split_sessions(separator="app_open", timeout="1h")
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 0-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. |
start_event | str or list of str, optional | Event name(s) that mark the start of a session. Must be provided together with end_event. |
end_event | str or list of str, optional | Event name(s) that mark the end of a session. Must be provided together with start_event. |
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. |
event_col | str, optional | Event column override; defaults to schema.event_col. |
Examples
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
start_event + end_event
A session is every event strictly between a start_event and the next
end_event — both boundary events are dropped from the output.
Before: start → event_1 → event_2 → end
stream.split_sessions(start_event="start", end_event="end")
After:
event_1 → event_2, with session_id = user_1_1, user_1_1