Filter Events

Keep only rows that match a column filter, a Python predicate, or a SQL query.

Exactly one of keep, drop, func, or sql must be provided. If all are None the eventstream is returned unchanged.

Usage

stream.filter_events(keep={"event": ["purchase", "add_to_cart"]})
stream.filter_events(drop={"event": ["system_event"], "platform": ["bot"]})
stream.filter_events(sql="SELECT * FROM eventstream WHERE event NOT LIKE 'system_%'")

How it works

filter_events works on rows, not on paths: a path whose every event is filtered out disappears, but a path can also be left with only some of its events. To keep or drop whole paths instead, use Filter Paths.

The keep and drop forms are not mirror images once you list more than one column, and that catches people out. Starting from this toy eventstream:

user_id	event	platform
u1	home	ios
u1	cart	ios
u1	purchase	ios
u2	home	web
u2	bot_ping	web
u2	cart	web

stream.filter_events(keep={"event": ["home", "cart"], "platform": ["ios"]})

keep combines columns with AND — a row survives only if it matches every entry. Here that means "iOS rows that are also home or cart":

user_id	event	platform
u1	home	ios
u1	cart	ios

stream.filter_events(drop={"event": ["bot_ping"], "platform": ["web"]})

drop combines columns with OR — a row is removed if it matches any entry. Here that drops bot_ping and everything on web, which takes u2 out entirely:

user_id	event	platform
u1	home	ios
u1	cart	ios
u1	purchase	ios

For anything the two dict forms can't express, func takes a pandas predicate over the raw DataFrame and sql takes a DuckDB SELECT reading from the eventstream table alias.

Parameters

Parameter	Type	Description
`keep`	`dict, optional`	`{column: values}` mapping. Keeps rows where each listed column contains one of the listed values. Multiple columns combine with AND: a row is kept only if it matches every entry. Example: `{"event": ["purchase", "add_to_cart"]}`.
`drop`	`dict, optional`	Same `{column: values}` format, but removes the matching rows instead. Multiple columns combine with OR: a row is removed if it matches any entry (the exact complement of `keep`).
`func`	`callable, optional`	A function that accepts the raw pandas DataFrame and returns a boolean Series. Rows where the Series is `True` are kept.
`sql`	`str, optional`	DuckDB SQL SELECT statement that reads from the `eventstream` table alias and returns all original columns. Example: `"SELECT * FROM eventstream WHERE event NOT LIKE 'system_%'"`.