Event contract
Fields the query expects
| Field | Type | Why it exists |
|---|---|---|
| timestamp_utc | Timestamp | When the activity occurred. |
| user_id | Utf8 | Stable user identifier. |
| event_name | Utf8 | Product event name. |
Copy the query
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.
Week 0
100%
Cohort 2026-06-29
Week 1
55%
Cohort 2026-06-29
Week 2
44.38%
Cohort 2026-06-29
Week 0
100%
Cohort 2026-07-06
Week 1
59.18%
Cohort 2026-07-06
| cohort_week | week_number | retained_users | cohort_size | retention_pct |
|---|---|---|---|---|
| 2026-06-29 | 0 | 320 | 320 | 100 |
| 2026-06-29 | 1 | 176 | 320 | 55 |
| 2026-06-29 | 2 | 142 | 320 | 44.38 |
| 2026-07-06 | 0 | 294 | 294 | 100 |
| 2026-07-06 | 1 | 174 | 294 | 59.18 |
Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.
How the SQL works
- 1The first CTE defines each user's cohort from the week they first completed the value milestone.
- 2Weekly activity is deduplicated so several events in one week count as one retained user.
- 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 setupPut the recipe to work
Related instrumentation and guides
Continue the analysis
Build a Signup-to-Activation Funnel in SQL
Calculate unique-user conversion through signup, onboarding, integration, and first-value milestones.
Open recipeFind Features Used Before Upgrade
Join feature events to upgrade events and rank behaviors that occur before paid conversion.
Open recipeCalculate DAU, WAU, and Product Stickiness
Measure daily and weekly active users together and calculate DAU-to-WAU stickiness from a consistent activity definition.
Open recipeRun 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.