Skip to content
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-27Tested with Apache DataFusion 45.2.0

Reviewed by the Telemetry product team on . We checked the SQL syntax, required event fields, sample results, and limits on using the query. Who reviews this page

Question answered

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

New users have had less time to return. Group users by signup week and compare retention after each group has had the same observation period.

Event schema

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('epoch', a.activity_week)
      - date_part('epoch', f.cohort_week)) / 604800 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('epoch', a.activity_week)
      - date_part('epoch', f.cohort_week)) / 604800
),
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 read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. We review the synthetic sample output separately. Check field types, thresholds, and counting rules against your own data. Read the testing methodology.

Query result

Weekly retention by activation cohort

The older cohort retained half its users in week one; the newer cohort is not yet mature enough for a week-one comparison.

cohort_weekweek_numberretained_userscohort_sizeretention_pct
2026-07-20044100
2026-07-2012450
2026-07-27033100

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

Weekly retention by activation cohort: static chart of synthetic retention_pct values from the Calculate weekly cohort retention example result
Download this SVG chart of the sample results for an article, runbook, or design review. Please credit Telemetry.

Reproduce the example

Download the sample data

The JSON bundle includes the event schema with field types, reproducible input rows, exact SQL, expected output, review notes, and engine version. The CSV contains the displayed result.

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 check

  • 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

Review retention trends regularly. Flag cohorts when their observation windows close and week-one or week-four retention falls outside the expected range.

Read alert setup

Set up the events this query needs

Related instrumentation and guides

Continue the analysis

Run it on your 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