Telemetry
Product analytics SQL recipe

Calculate Weekly Cohort Retention

Group users by first activity week and measure the percentage returning in later weeks.

Advancedproduct_eventsReviewed 2026-07-27

Question answered

What percentage of each signup cohort returns in weeks one through twelve?

A single retention rate mixes mature and newly acquired users. Cohorts preserve the start week so product or acquisition changes can be compared on equal terms.

Event contract

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampWhen the activity occurred.
user_idUtf8Stable user identifier.
event_nameUtf8Product event name.
DataFusion SQL

Copy the query

sql
WITH first_activity AS (
  SELECT
    user_id,
    date_trunc('week', MIN(timestamp_utc)) AS cohort_week
  FROM product_events
  WHERE event_name = 'first_value_completed'
  GROUP BY user_id
),
weekly_activity AS (
  SELECT DISTINCT
    user_id,
    date_trunc('week', timestamp_utc) AS activity_week
  FROM product_events
  WHERE event_name = 'core_feature_used'
),
cohort_activity AS (
  SELECT
    f.cohort_week,
    date_part('day', a.activity_week - f.cohort_week) / 7 AS week_number,
    COUNT(DISTINCT a.user_id) AS retained_users
  FROM first_activity f
  JOIN weekly_activity a ON f.user_id = a.user_id
  WHERE a.activity_week >= f.cohort_week
  GROUP BY
    f.cohort_week,
    date_part('day', a.activity_week - f.cohort_week) / 7
),
cohort_sizes AS (
  SELECT cohort_week, COUNT(*) AS cohort_size
  FROM first_activity
  GROUP BY cohort_week
)
SELECT
  c.cohort_week,
  c.week_number,
  c.retained_users,
  s.cohort_size,
  100.0 * c.retained_users / NULLIF(s.cohort_size, 0) AS retention_pct
FROM cohort_activity c
JOIN cohort_sizes s ON c.cohort_week = s.cohort_week
WHERE c.week_number BETWEEN 0 AND 12
ORDER BY c.cohort_week, c.week_number;

This recipe is read-only and reviewed against Telemetry's DataFusion query patterns. Sample output is deterministic and synthetic; validate field types, thresholds, and business definitions against your own data.

Query result

Weekly retention by activation cohort

The July 6 cohort has a stronger week-one return rate than the previous cohort.

cohort_weekweek_numberretained_userscohort_sizeretention_pct
2026-06-290320320100
2026-06-29117632055
2026-06-29214232044.38
2026-07-060294294100
2026-07-06117429459.18

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

How the SQL works

  1. 1The first CTE defines each user's cohort from the week they first completed the value milestone.
  2. 2Weekly activity is deduplicated so several events in one week count as one retained user.
  3. 3The timestamp difference is converted from days to a week offset that can be compared across cohorts.

Edge cases to decide

  • Exclude incomplete future weeks when comparing cohorts of different ages.
  • Define return behavior from meaningful activity rather than any page view.
  • UTC week boundaries may not match the business timezone; document the chosen boundary.

Recommended dashboard

  • Heatmap-style table: cohort_week by week_number
  • Line chart: retention_pct by week_number split by cohort_week
  • Stat: mature cohort week-four retention

Alert guidance

Retention is usually reviewed as a trend rather than paged. Flag mature cohorts when week-one or week-four retention drops outside the expected range.

Read alert setup

Put the recipe to work

Related instrumentation and guides

Continue the analysis

Run it on real events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key