Funnels & Cohorts

Funnels and cohorts are the two "second-order" analyses that turn the raw event stream into business-readable numbers. Both run against BigQuery directly (no rollup tables — the queries are fast on the partitioned + clustered events table). Both share the same identity-stitching layer so they can be run in either visitor mode (one row per anonymous browser) or user mode (one row per signed-in person across devices).

Funnels

A funnel measures conversion across an ordered series of events.

Defining a Funnel

Open Web Analytics > Funnels > + New. The builder collects:

Field	Notes
name	Display name.
steps	Ordered list of event names. Use Event Definition names for stable references; raw auto-events are fine too.
stepFilters	Optional per-step filter — same field/op/value shape as Event Definitions.
lookbackDays	Max time between step N and step N+1 for the visitor to be counted as having progressed. Default 30.
groupBy	'visitor' (default) or 'user'. See Visitor vs User Mode below.
segmentId	Optional pre-filter by Segment.

How the Query Runs

funnelQueryService.computeFunnel() issues a single BigQuery query that:

1. Selects every row matching any of the step event names within the lookback + date range.
2. For each visitor/user, sorts events chronologically.
3. Walks the steps in order, requiring each subsequent event to occur within lookbackDays of the prior one.
4. Aggregates by step into counts: step_1_visitors, step_2_visitors, ..., and per-step time-to-progress percentiles (p50, p90).

The result is what you see in the funnel chart — absolute count per step, plus the implicit drop-off between each.

Visitor vs User Mode

This is where identity stitching matters.

• Visitor mode treats every browser session as independent. A user who visits on their phone, signs up, then converts on their laptop counts as two separate funnels (one drops out at step 1; the other appears to "start at step 2" — which actually disqualifies them since they didn't do step 1).
• User mode LEFT JOINs identity_map to resolve visitor_id → user_id for both anonymous visits and signed-in ones. The same person's cross-device activity is unified, so the example above counts as one funnel that completed.

User mode requires the visitor to have called karma('identify', ...) at some point in their history. If they never did, user mode falls back to visitor_id for them — so user mode is a superset of visitor mode, not a different population.

User mode SQL adds a join roughly like:

LEFT JOIN identity_map idm
  ON events.tenant_id = idm.tenant_id
  AND events.site_id  = idm.site_id
  AND events.visitor_id = idm.visitor_id
GROUP BY COALESCE(idm.user_id, events.visitor_id)

Funnel Output Shape

{
  "funnelId": "...",
  "groupBy": "user",
  "computedAt": "2026-05-22T...",
  "steps": [
    { "name": "page_view",      "count": 12480, "filter": null },
    { "name": "add_to_cart",    "count":  1872, "filter": null,
      "timeToHere": { "p50_sec": 12, "p90_sec": 38 } },
    { "name": "checkout_start", "count":   942, "filter": null,
      "timeToHere": { "p50_sec":  9, "p90_sec": 22 } },
    { "name": "purchase",       "count":   311, "filter": null,
      "timeToHere": { "p50_sec": 14, "p90_sec": 47 } }
  ],
  "totalConverted": 311,
  "topConversionRate": 0.0249
}

The UI renders this as the familiar shrinking-bar funnel with drop-off percentages between each step.

Cohorts

A cohort measures retention — what percentage of users from a starting cohort return on day N, week N, or month N.

Defining a Cohort

Web Analytics > Cohorts > + New collects:

Field	Notes
name	Display name.
cohortEvent	The event that defines membership (e.g. page_view for "anyone who visited", signup for "new users").
returnEvent	The event that counts as "returning" (e.g. page_view, or a more specific conversion).
period	'day' | 'week' | 'month'.
numPeriods	How many periods of retention to compute (default 12).
groupBy	'visitor' or 'user', same semantics as funnels.

Output Shape

A cohort table — rows are cohorts (e.g. "users who signed up week of 2026-05-01"), columns are periods (week 0, week 1, week 2, ...). Each cell is the percentage of cohort members who fired returnEvent at least once in that period.

Cohort week        | Size | W0    | W1    | W2    | W3    | ...
2026-05-01         | 1247 | 100%  | 42%   | 31%   | 27%   | ...
2026-05-08         | 1418 | 100%  | 45%   | 33%   |  —    | ...

Period 0 is always 100% by definition (everyone in the cohort fired the cohort event in period 0). Period N% is the retention number.

How It's Computed

cohortService.computeCohort() runs one BQ query that:

1. Selects everyone who fired cohortEvent in the time range, grouping by their cohort period.
2. Selects everyone who fired returnEvent in any period.
3. JOINs the two on (visitor_id | user_id) and counts unique IDs per (cohort period, return period).
4. Divides by cohort size to produce the percentage.

User mode applies the same identity_map LEFT JOIN as funnels.

Segments

A Segment is a saved filter you can attach to funnels or cohorts to scope the analysis. Examples:

• "Users from the enterprise UTM campaign"
• "Mobile users"
• "Users from Germany who arrived via Twitter"

Segments are stored in segmentModel per tenant and reference one or more conditions on the standard event fields + UTM + device + geo. They compose with the funnel/cohort groupBy — a user-mode cohort of mobile users counts unique signed-in mobile humans, not unique signed-in browsers that happened to be mobile.

When to Use Which

• Funnels: linear conversion analyses ("how many of the people who saw pricing actually paid?").
• Cohorts: retention/loyalty analyses ("of people who signed up in May, what % are still active in August?").
• Both: an end-to-end onboarding analysis often uses a funnel for the first session and a cohort for week-over-week return rates afterward.

Performance Notes

• The events table is partitioned by event_ts (day) and clustered by (tenant_id, site_id, event_name). Funnel and cohort queries are written so the partition pruning + clustering pruning kicks in — typical query is sub-second on small sites, low-single-digit seconds on big ones.
• BigQuery is queried directly here (not the Mongo rollups) because rollups are pre-aggregated, and funnels/cohorts need per-event ordering. Mongo serves the realtime + overview dashboards instead.
• The default lookbackDays = 30 on funnels keeps scans manageable. Increasing to 90 days roughly triples bytes scanned. The per-tenant rate-limit in queryService caps how often these queries can be re-run.
• Identity stitching adds one JOIN per query. The identity_map table is clustered on (tenant_id, site_id, visitor_id), so the JOIN is also clustering-pruned and stays cheap.

What These Analyses Don't Do (Yet)

• Path / Sankey diagrams: not in MVP. Planned for the Explore page.
• Predictive churn: not built; if there's appetite, the same Mongo rollups + a small Gemini classifier could ship.
• Real-time funnels: funnels currently query BQ and so reflect the last successful insert. A real-time variant would have to query the Mongo capped buffer with a much smaller event population.