Add Segment

Add a new categorical segment column to the eventstream.

Exactly one of rules, func, sql, or funnel_events must be provided.

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 last funnel step reached per path
stream.add_segment(
    "funnel",
    funnel_events=["add_to_cart", "checkout_start", "purchase"],
)
# Resulting segment values: out_of_funnel | add_to_cart | checkout_start | purchase

# 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",
)

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 funnel. Each path is assigned the name of the last funnel step reached in sequence, or `out_of_funnel` if the first step was never reached. Segment values (in ascending funnel order): `out_of_funnel`, then each event name from `funnel_events[0]` to `funnel_events[-1]`.
`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.