Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

retention: stop the rolling active-users series running past today

Carl-Gerhard Lindesvärd23dfd5540130
diff --git a/packages/core/src/modules/chart/src/retention.sql.proof.md b/packages/core/src/modules/chart/src/retention.sql.proof.md
index fbcad41e3..246b52f7b 100644
--- a/packages/core/src/modules/chart/src/retention.sql.proof.md
+++ b/packages/core/src/modules/chart/src/retention.sql.proof.md
@@ -33,6 +33,25 @@ WITH weekly_active AS ( SELECT profile_id, toStartOfWeek(created_at) AS week FRO
-- V2 params: {"p1":"secure-privacy"}
```
+### rollingActiveUsersQuery — AMENDED 2026-09-27 (ISSUES.md H8c)
+
+**The three records below are superseded: V2 now DIVERGES from V1 deliberately.**
+
+The parity was real, and both sides were wrong in the same way. `date + n` smears each
+active day forward, so with no upper bound the series ran up to `days - 1` days past today.
+Measured on the seeded acme-web at `days = 7` with `today()` = 2026-09-27, it returned rows
+for 2026-09-28 and 2026-09-29 — the chart drew two points into the future.
+
+V2 adds `AND date <= today()` to the outer WHERE. On that data it removes exactly those two
+rows, 98 → 96, and leaves every remaining value unchanged.
+
+```sql
+-- V2 now (only the outer WHERE differs from the records below)
+… ARRAY JOIN range({p2:UInt64}) AS n ) WHERE project_id = {p3:String} AND date <= today() GROUP BY date
+```
+
+The row counts recorded in the three entries below are therefore pre-amendment figures.
+
### rollingActiveUsersQuery — verdict, 7d
**IDENTICAL** — rows V1/V2 = 62/62; rows_read V1/V2 = 73247/73247; wall V1/V2 = 355 ms / 358 ms.
diff --git a/packages/core/src/modules/chart/src/retention.sql.test.ts b/packages/core/src/modules/chart/src/retention.sql.test.ts
new file mode 100644
index 000000000..320e6a579
--- /dev/null
+++ b/packages/core/src/modules/chart/src/retention.sql.test.ts
@@ -0,0 +1,43 @@
+/**
+ * Shape tests for `retention.sql.ts`, same strategy as `overview.sql.test.ts`:
+ * render the statement, then `EXPLAIN` it with its bound params against the
+ * isolated `openpanel_test` ClickHouse (pinned by test/preload.ts), which
+ * parses and resolves columns without executing.
+ */
+
+import { beforeAll, describe, expect, it } from 'bun:test';
+import type { SqlFragment } from '@openpanel/db/src/clickhouse/sql';
+
+const PROJECT_ID = 'retention-sql-validation';
+
+let ch: typeof import('@openpanel/db/src/clickhouse/client').ch;
+let RET: typeof import('./retention.sql');
+
+async function explain(fragment: SqlFragment): Promise<void> {
+ const { query, query_params } = fragment.toStatement();
+ await ch.command({ query: `EXPLAIN ${query}`, query_params });
+}
+
+beforeAll(async () => {
+ ({ ch } = await import('@openpanel/db/src/clickhouse/client'));
+ RET = await import('./retention.sql');
+});
+
+describe('rollingActiveUsersQuery', () => {
+ // `date + n` smears every active day forward, so without an upper bound the
+ // series runs up to `days - 1` days past today. On the seeded acme-web at
+ // days=7 that drew two points into the future (ISSUES.md H8c).
+ it('never projects past today', () => {
+ for (const days of [1, 7, 30]) {
+ const { query } = RET.rollingActiveUsersQuery(
+ PROJECT_ID,
+ days
+ ).toStatement();
+ expect(query).toContain('date <= today()');
+ }
+ });
+
+ it('parses against ClickHouse', async () => {
+ await explain(RET.rollingActiveUsersQuery(PROJECT_ID, 7));
+ });
+});
diff --git a/packages/core/src/modules/chart/src/retention.sql.ts b/packages/core/src/modules/chart/src/retention.sql.ts
index c043d4739..04392d7c7 100644
--- a/packages/core/src/modules/chart/src/retention.sql.ts
+++ b/packages/core/src/modules/chart/src/retention.sql.ts
@@ -126,7 +126,9 @@ export function rollingActiveUsersQuery(
)
ARRAY JOIN range(${sql.uint64(days)}) AS n
)
- WHERE project_id = ${sql.string(projectId)}
+ -- date + n smears each active day forward, so without this the series
+ -- runs up to days-1 days past today.
+ WHERE project_id = ${sql.string(projectId)} AND date <= today()
GROUP BY date`;
}