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.mdxindex 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_SIZEdiff --git a/packages/db/src/services/funnel-sql.test.ts b/packages/db/src/services/funnel-sql.test.tsindex 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.tsindex 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']: []),