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('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.
Week 0
100%
Cohort 2026-07-20
Week 1
50%
Cohort 2026-07-20
Week 0
100%
Cohort 2026-07-27
| cohort_week | week_number | retained_users | cohort_size | retention_pct |
|---|---|---|---|---|
| 2026-07-20 | 0 | 4 | 4 | 100 |
| 2026-07-20 | 1 | 2 | 4 | 50 |
| 2026-07-27 | 0 | 3 | 3 | 100 |
Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.
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
- 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.