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

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.