Skip to content

feat: person cohorts (dynamic + static) with cohort filters in every insight - #13

Merged
ayushozha merged 2 commits into
mainfrom
ayush/cohorts-v2
Nov 17, 2026
Merged

ayushozha merged 2 commits into
mainfrom
ayush/cohorts-v2

Conversation

@ayushozha

@ayushozha ayushozha commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What and Why

Pulse's "segments" are flat, evaluated in memory on every request, and can't be used in insights. This adds PostHog-style person cohorts:

  • dynamic cohorts defined by person properties and behaviour, with nested AND/OR groups, negation and cohort references
  • precomputed membership with background recalculation
  • static cohorts (CSV, manual lists, or the people behind any chart point)
  • a cohort filter type that works in every insight

Stacked on #12 (base ayush/dashboards-v2); retarget to main once the stack below merges.

Reference followed: PostHog's Cohort model and cohort filters (posthog/models/cohort/, frontend/src/scenes/cohorts/):

  • the type: OR/AND → values property-group tree, person / behavioral / cohort criteria with negation
  • behavioural values: performed_event, performed_event_multiple, stopped_performing_event, restarted_performing_event, performed_event_first_time, performed_event_regularly
  • static cohorts via CSV or from an insight
  • the cohort property filter in insights

Changes

  • Migration 033: person_cohorts, cohort_people and cohort_counts (count history).
  • /api/v2/cohorts:
    • CRUD
    • /calculate and /history
    • /people: list, add, remove
    • /people.csv export and /people/csv import
    • /duplicate-static
    • /from-actors
    • The legacy /api/v1/cohorts acquisition matrix is unchanged.
  • Dynamic cohorts:
    • Criteria compile to SQL UNION / INTERSECT / EXCEPT over the project's known visitors (sessions ∪ profiles), and membership is swapped atomically.
    • "≤ N times" and "= 0 times" correctly include visitors who never did the event.
    • Cohort references are checked for existence in the same project and for cycles, and deleting a cohort other cohorts use is refused.
  • Recalculation: on create and update, on demand, and in a background task every 5 minutes for cohorts older than 30 minutes. The task claims each cohort (is_calculating) so multiple instances don't collide, and failures are recorded in last_error.
  • Static cohorts:
    • Members can be added by visitor id or identified user id (resolved via profiles and aliases), and unknown ids are reported.
    • CSV import skips a header and ignores duplicates.
    • Any cohort can be duplicated as static.
    • from-actors saves the people behind any trends, funnels, retention, stickiness, lifecycle or paths data point.
  • Insights: a new filter {"type": "cohort", "key": "<cohort id>", "operator": "exact" | "is_not"} works in every insight. It checks membership with EXISTS, joined to the cohort's project, so another project's cohort id matches nothing. To support that, the virtual event stream now carries project_id.
  • Permissions:
    • Everything is gated by the cohorts module.
    • Member lists and CSV export also need identity.
    • from-actors needs the same access as the actor endpoints.

Reviews and Follow-up

  • Code review: self-reviewed
  • Security review: cross-project cohort ids can't leak membership, cycle and reference checks, size caps (100k static members, 50 criteria, 5 nesting levels)
  • Documentation: request shapes above. Follow-ups: cohort targeting in feature flags (flags PR), breakdown by cohort, and migrating legacy saved_segments.

Files Changed

  • migrations/033_person_cohorts.{up,down}.sql
  • services/person_cohorts.rs, routes/cohorts.rs (new)
  • services/insights/{filters,mod}.rs: cohort filter type, project_id on the event stream
  • routes/insights.rs, routes/mod.rs, services/mod.rs, main.rs (routes and background task)

Scope and Non-scope

In scope: person cohorts and cohort filters in insights. Out of scope: flag targeting by cohort, UI, and the excluded LLM/account features.

Validation

I ran this on Postgres 18 with the seeded dataset. Every cohort's membership was compared with independent Python set logic over the raw rows, in 31 checks:

  • person property, performed, ≥2 and ≤1 times, AND/negation/cohort references, OR with a nested group
  • stopped, first time and regularly
  • validation errors
  • trends and funnels filtered by a cohort, and the cross-project isolation check
  • static add, CSV, remove, export, duplicate, and from-actors
  • history and permissions

Cohorts verification

Testing

cargo test: 129 passed, including new tests for tree parsing and validation, set-operation compilation, CSV parsing and project scoping of the cohort filter.

cargo test cohorts

Size and Notes

About 1,540 changed lines. Migration 033 only creates tables. Adding project_id to the virtual event stream is additive, since existing queries select columns by name.

🤖 Generated with Claude Code

…insight

- person_cohorts / cohort_people / cohort_counts tables; /api/v2/cohorts
  (v1 /api/v1/cohorts stays the acquisition cohort matrix)
- dynamic cohorts: nested AND/OR groups of person-property criteria,
  behavioural criteria (performed event, N times >=/<=/=, stopped, restarted,
  first time, regularly in M of N periods, with event property filters) and
  cohort-in-cohort references, each negatable; compiled to SQL
  UNION/INTERSECT/EXCEPT over the project's known visitors and materialised
  atomically; cycle detection; deleting a referenced cohort is refused
- recalculation on create/update, on demand (/calculate) and every 5 minutes
  for cohorts older than 30 minutes, claim-based so instances do not collide;
  member count history
- static cohorts: add by visitor id or user id, CSV import, remove,
  duplicate any cohort as static, create from any insight's actors
- members list and CSV export (identity module required)
- insights: new `cohort` property filter type (exact / is_not), scoped to the
  querying project, usable in trends, funnels, retention, stickiness,
  lifecycle and paths

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T22:41:46.824947Z 46961b2 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 46961b2236

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…module for cohort filters, claim lease with recovery, full CSV export

Insight authorization now takes DataNeeds { person, cohorts } instead of a
person-only flag, so every path (insight routes, actors, saved insights,
dashboards, share links) enforces the cohorts module for cohort filters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ayushozha
ayushozha changed the base branch from ayush/dashboards-v2 to main November 17, 2026 01:14
@ayushozha
ayushozha merged commit f278077 into main Nov 17, 2026
0 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant