Skip to content

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

feat(funnel): opt-in non-strict windowFunnel ordering (#442)

Ritik Jain95c574e46aff
diff --git a/apps/public/content/docs/self-hosting/environment-variables.mdx b/apps/public/content/docs/self-hosting/environment-variables.mdx
index 7d7d7faa2..b9fee9836 100644
--- a/apps/public/content/docs/self-hosting/environment-variables.mdx
+++ b/apps/public/content/docs/self-hosting/environment-variables.mdx
@@ -984,6 +984,21 @@ Batch size for bot detection buffer operations.
BOT_BUFFER_BATCH_SIZE=1000
```
+## Analytics Behavior
+
+### FUNNEL_NON_STRICT_ORDERING
+
+**Type**: `boolean` (`1` or `true`)
+**Required**: No
+**Default**: unset (strict ordering)
+
+Funnels use ClickHouse's `windowFunnel` in `strict_increase` mode by default: every step's timestamp must be strictly greater than the previous step's. Setting this variable switches funnels to non-strict ordering (`>=`), where steps sharing the same timestamp still count as an ordered sequence — matching how Mixpanel and Amplitude evaluate funnels. Useful for server-side senders, batched SDKs, or imported data with coarse timestamps.
+
+**Example**:
+```bash
+FUNNEL_NON_STRICT_ORDERING=1
+```
+
## Performance & Tuning
### IMPORT_BATCH_SIZE
diff --git a/packages/db/src/services/funnel-sql.test.ts b/packages/db/src/services/funnel-sql.test.ts
index dbd95f1ba..737c6f23a 100644
--- a/packages/db/src/services/funnel-sql.test.ts
+++ b/packages/db/src/services/funnel-sql.test.ts
@@ -309,6 +309,34 @@ describe('funnel.service / buildFunnelBase — breakdown attribution', () => {
});
});
+describe('funnel.service / buildFunnelCte — windowFunnel ordering', () => {
+ afterAll(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it('defaults to strict_increase (unchanged behavior)', async () => {
+ // Stub to '' rather than unstubbing: unstubAllEnvs restores the HOST
+ // environment, so a dev shell with the variable set would flip this test.
+ vi.stubEnv('FUNNEL_NON_STRICT_ORDERING', '');
+ const sql = await buildChartSql([]);
+ expect(sql).toContain("'strict_increase'");
+ });
+
+ it('drops strict_increase when FUNNEL_NON_STRICT_ORDERING is set', async () => {
+ vi.stubEnv('FUNNEL_NON_STRICT_ORDERING', '1');
+ const sql = await buildChartSql([]);
+ expect(sql).not.toContain('strict_increase');
+ expect(sql).toMatch(/windowFunnel\(\d+\)\(/);
+ });
+
+ itCH('non-strict funnel SQL parses and resolves', async () => {
+ vi.stubEnv('FUNNEL_NON_STRICT_ORDERING', 'true');
+ const sql = await buildChartSql([]);
+ expect(sql).not.toContain('strict_increase');
+ await explain(sql);
+ });
+});
+
describe('funnel.service / buildFunnelBase — group breakdowns', () => {
itCH('adds the group array join for a group breakdown', async () => {
const sql = await buildProfilesSql([breakdown('group.plan')]);
diff --git a/packages/db/src/services/funnel.service.ts b/packages/db/src/services/funnel.service.ts
index f42c8cc64..ec3f43b6c 100644
--- a/packages/db/src/services/funnel.service.ts
+++ b/packages/db/src/services/funnel.service.ts
@@ -84,10 +84,21 @@ export class FunnelService {
const funnels = this.getFunnelConditions(eventSeries, projectId);
const primaryKey = group === 'profile_id' ? 'profile_id' : 'session_id';
+ // windowFunnel's 'strict_increase' mode requires every step's timestamp
+ // to be strictly greater than the previous step's, so same-timestamp
+ // sequences (server-side senders, batched SDKs, imported data with
+ // coarse timestamps) never connect. Mixpanel/Amplitude count those as
+ // ordered, so deployments migrating from them can opt into the default
+ // (>=) mode; strict stays the default here.
+ const nonStrictOrdering =
+ process.env.FUNNEL_NON_STRICT_ORDERING === '1' ||
+ process.env.FUNNEL_NON_STRICT_ORDERING === 'true';
+ const windowFunnelMode = nonStrictOrdering ? '' : ", 'strict_increase'";
+
return clix(this.client, timezone)
.select([
primaryKey,
- `windowFunnel(${funnelWindowMilliseconds}, 'strict_increase')(toUInt64(toUnixTimestamp64Milli(created_at)), ${funnels.join(', ')}) AS level`,
+ `windowFunnel(${funnelWindowMilliseconds}${windowFunnelMode})(toUInt64(toUnixTimestamp64Milli(created_at)), ${funnels.join(', ')}) AS level`,
...(group === 'session_id'
? ['argMax(profile_id, created_at) AS profile_id']
: []),