Add Segment

Add a new categorical segment column to the eventstream.

Exactly one of rules, func, sql, funnel_events, or time_range must be provided — unless name is already listed in schema.custom_cols, in which case passing none of them promotes that existing column to a segment in place, without recomputing its values.

Usage

# rules mode — CASE WHEN rules
stream.add_segment(
    "region",
    rules=[
        ["country", "=", "US", "domestic"],
        ["country", "in", "('GB', 'DE', 'FR')", "europe"],
        ["other"],
    ],
)

# funnel_events mode — assign the deepest funnel step reached in order
stream.add_segment(
    "funnel",
    funnel_events=["add_to_cart", "checkout_start", "purchase"],
)
# Resulting segment values: out_of_funnel | add_to_cart | checkout_start | purchase
# A path with only "checkout_start" (no "add_to_cart") is out_of_funnel — the
# funnel is strictly ordered, so skipping or reordering an earlier step keeps
# a path from being credited for a later one it did reach.

# sql mode — one computed column, same row order as the eventstream
stream.add_segment(
    "device",
    sql="SELECT CASE WHEN platform = 'mobile' THEN 'mobile' ELSE 'web' END FROM eventstream",
)

# time_range mode — binary "inside" vs "outside" a time interval
stream.add_segment(
    "incident",
    time_range=("2024-03-10", "2024-03-17"),
)

# promoting an existing custom column — "returned" already rode along in
# the source DataFrame and landed in schema.custom_cols; no mode argument
# needed, the column's values are kept as-is
stream.add_segment("returned")

Parameters

Parameter	Type	Description
`name`	`str`	Name of the new segment column.
`rules`	`list, optional`	CASE-WHEN rules. A list of conditions plus a final else entry: Example: `[["country", "=", "US", "domestic"], ["international"]]`.
`func`	`callable, optional`	A function that accepts the raw pandas DataFrame and returns a collection of segment labels with the same length and order as the eventstream rows.
`sql`	`str, optional`	DuckDB SQL SELECT statement that reads from the `eventstream` table alias and returns exactly one column — the segment label for each row. Row count and order must match the eventstream. Example: `"SELECT CASE WHEN platform = 'mobile' THEN 'mobile' ELSE 'web' END FROM eventstream"`.
`funnel_events`	`list of str, optional`	Ordered list of at least 2 event names defining a strict, ordered ("closed") funnel. A path is assigned `funnel_events[k]` only if it contains every event `funnel_events[0]` through `funnel_events[k]` and their last occurrences appear in that same order — reaching a later step without having completed the earlier ones in order does not count towards it. A path is assigned the highest such `k`; if it never completes even `funnel_events[0]`, it is labeled `out_of_funnel`. Segment values (in ascending funnel order): `out_of_funnel`, then each event name from `funnel_events[0]` to `funnel_events[-1]`.
`time_range`	`tuple or list, optional`	`(start, end)` — two timestamps (string or `pd.Timestamp`) bounding an inclusive interval over `schema.timestamp_col`. Each event is labeled `inside` if its timestamp falls within `[start, end]`, otherwise `outside`.
`path_col`	`str, optional`	Path ID column override for `funnel_events` mode; defaults to `schema.path_col`.

Values rules

Each condition entry is [column, op, value, label] — translates to WHEN <column> <op> <value> THEN <label> in SQL.
The last entry is [else_label] — the ELSE branch label.