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 . SQL compatibility, event contract, synthetic output, and operational caveats. Review standards and ownership

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('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. The deterministic sample output is synthetic and reviewed separately; validate field types, thresholds, and business definitions 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
Indexable SVG of the deterministic example output. Download it for an article, runbook, or design review with attribution.

Reproduce the example

Download the public fixture

The JSON bundle includes the typed event contract, 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 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