Add Segment

Adds a new segment (categorical) column to the eventstream. The column is automatically registered in the schema and becomes available in widgets and metrics. Exactly one source mode must be provided.

Usage

# Rule-based segmentation
es.add_segment("value_tier", values=[
    ("revenue", ">", 500, "high"),
    ("revenue", ">", 100, "medium"),
    ("low",),  # default / ELSE
])

# Function-based
es.add_segment("is_mobile", func=lambda df: df["device"].isin(["ios", "android"]))

# SQL-based (supports window functions)
es.add_segment("first_channel", sql="""
    SELECT FIRST_VALUE(channel) OVER (
        PARTITION BY user_id ORDER BY timestamp
    ) FROM eventstream
""")

# Funnel-based: creates levels named after the last funnel event reached
es.add_segment("funnel", funnel_events=["add_to_cart", "purchase"])
# Levels: "out_of_funnel", "add_to_cart", "purchase"
# Use diff=["funnel", "add_to_cart", "purchase"] in segment_overview to compare

Parameters

Parameter	Type	Description
`name`	`str`	Name of the new segment column. Must not already exist.
`values`	`list \| None`	Mode 1. CASE-WHEN rules. Each item (except the last) is a 4-tuple `(column, operator, value, segment_value)`. The last item is a 1-tuple `(else_value,)` as the default.
`func`	`Callable \| None`	Mode 2. A function `(df) → Collection` returning a value per row.
`sql`	`str \| None`	Mode 3. DuckDB SQL selecting from `eventstream`. Must return exactly one data column.
`funnel_events`	`list[str] \| None`	Mode 4. Creates an N+1 level funnel segment. Each path is labelled with the name of the last event in the sequence that was reached. A path that reached none of the events is labelled `"out_of_funnel"`; a path that reached the final event is labelled with that event's name. Uses a single DuckDB `PARTITION BY` pass.