Filter Paths

Keep only paths that satisfy a metric condition.

The condition is a tree of comparison nodes connected by and / or / not branch nodes. Per-path metrics are computed once and the condition is evaluated in SQL.

Raises EmptyEventstreamError when no paths match.

Usage

# Keep paths that contain at least one purchase
stream.filter_paths({"op": ">", "metric": "event_count", "value": 0, "metric_args": {"event": "purchase"}})

# Keep paths that contain a promo_view or a discount_applied event
stream.filter_paths({"op": "=", "metric": "has_any_event", "value": True,
                      "metric_args": {"events": ["promo_view", "discount_applied"]}})

# The same, with the shorthand for a 0/1 metric compared with True
stream.filter_paths({"has_any_event": ["promo_view", "discount_applied"]})

# Keep paths longer than 3 events that match a funnel pattern
# (a top-level list means AND)
stream.filter_paths([
    {"op": ">", "metric": "length", "value": 3},
    {"op": "=", "metric": "matches_pattern", "value": True,
     "metric_args": {"pattern": "registration->.*->purchase"}},
])

How it works

Every path is scored by the path metrics named in the condition, and then kept or dropped as a whole — unlike Filter Events, this never leaves a path with some of its events missing.

Before — three paths of different lengths, one of which converts:

u1: home → cart → purchase
u2: home → cart
u3: home

stream.filter_paths({"op": ">", "metric": "length", "value": 2})

After — only u1 has more than two events, so u2 and u3 are gone, all of their events with them:

u1: home → cart → purchase

stream.filter_paths({"op": "=", "metric": "has_event", "value": True,
                     "metric_args": {"event": "purchase"}})

After — the same single path survives, this time because it is the only one containing a purchase anywhere:

u1: home → cart → purchase

Conditions combine into a tree, and a plain list is shorthand for AND:

# longer than 2 events AND reached purchase
stream.filter_paths([
    {"op": ">", "metric": "length", "value": 2},
    {"op": "=", "metric": "has_event", "value": True,
     "metric_args": {"event": "purchase"}},
])

A 0/1 metric compared with True has a shorthand — the metric name as the only key, and its single required argument (or its metric_args) as the value:

# the same condition as the second example above
stream.filter_paths({"has_event": "purchase"})

# longer than 2 events AND went from the cart to the purchase
stream.filter_paths([
    {"op": ">", "metric": "length", "value": 2},
    {"matches_pattern": "cart->.*->purchase"},
])

See Path Metrics for the full list.

If nothing matches, the call raises EmptyEventstreamError rather than returning an empty eventstream.

Parameters

Parameter	Type	Description
`condition`	`dict or list`	Condition tree of leaf (comparison) and branch (`and`/`or`/`not`) nodes; a plain list is shorthand for AND. Metrics used in a leaf must produce exactly one value per path, which rules out `has_event_bulk`, `event_count_bulk`, and `in_segment_bulk`. A leaf comparing a 0/1 metric (`has_event`, `has_any_event`, `has_all_events`, `matches_pattern`, `in_segment`) with `True` may be written as `{metric: metric_args}`, or as `{metric: value}` for a metric with one required argument: `{"has_event": "purchase"}`, `{"matches_pattern": "A->.*->B"}`, `{"has_any_event": ["A", "B"]}`.
`path_col`	`str, optional`	Path ID column override; defaults to `schema.path_col`.

Condition node keys

op — for a leaf, a comparison operator: >, >=, <, <=, = (or ==), !=. For a branch, one of and, or, not.
args (branch nodes only) — list of child nodes. [cond1, cond2] ≡ {"op": "and", "args": [cond1, cond2]}.
metric — metric name (see the Path Metrics documentation page for the full list).
value — threshold value.
metric_args (optional) — dict of extra arguments for the metric. has_event/event_count take a single event string; for a multi-event AND/OR condition use has_all_events/has_any_event with an events list.

Supported comparison operators: = (or ==), !=, >, <, >=, <=. See Path Metrics for the full condition grammar and the list of metrics you can compare.