@superwall/cli 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +21 -5
  2. package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
  3. package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
  4. package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
  5. package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
  6. package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
  7. package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
  8. package/dist/auth.js +2 -2
  9. package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
  10. package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
  11. package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
  12. package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
  13. package/dist/dev-B0MF6z3L.js +21 -0
  14. package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
  15. package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
  16. package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
  17. package/dist/entry.js +84 -50
  18. package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
  19. package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
  20. package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
  21. package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
  22. package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
  23. package/dist/migrate-qmvOtp3l.js +283 -0
  24. package/dist/open-studio-CpHqjovS.js +1299 -0
  25. package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
  26. package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
  27. package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
  28. package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
  29. package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
  30. package/dist/publish-DWX8S9yZ.js +34 -0
  31. package/dist/push-Dox4_5Dq.js +34 -0
  32. package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
  33. package/dist/reports-C0xHCLnt.js +27 -0
  34. package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
  35. package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
  36. package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
  37. package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
  38. package/dist/skills/superwall/SKILL.md +146 -0
  39. package/dist/skills/superwall/references/api.md +275 -0
  40. package/dist/skills/superwall/references/asa.md +160 -0
  41. package/dist/skills/superwall/references/asc.md +96 -0
  42. package/dist/skills/superwall/references/dashboard-links.md +57 -0
  43. package/dist/skills/superwall/references/data-analytics.md +893 -0
  44. package/dist/skills/superwall/references/docs.md +51 -0
  45. package/dist/skills/superwall/references/sdk-integration.md +105 -0
  46. package/dist/skills/superwall/references/sdk-source.md +18 -0
  47. package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
  48. package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
  49. package/dist/skills/superwall/workflows/integrate/android.md +292 -0
  50. package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
  51. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
  52. package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
  53. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
  54. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
  55. package/dist/skills/superwall/workflows/placements/android.md +175 -0
  56. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
  57. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
  58. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
  59. package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
  60. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
  61. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
  62. package/dist/skills/superwall/workflows/review/android.md +120 -0
  63. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
  64. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
  65. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
  66. package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
  67. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
  68. package/dist/skills/superwall-framework/SKILL.md +253 -0
  69. package/dist/skills/superwall-framework/references/cli.md +340 -0
  70. package/dist/skills/superwall-framework/references/examples.md +123 -0
  71. package/dist/skills/superwall-framework/references/layout.md +295 -0
  72. package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
  73. package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
  74. package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
  75. package/dist/skills/superwall-framework/references/native/android.md +83 -0
  76. package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
  77. package/dist/skills/superwall-framework/references/native/ios.md +77 -0
  78. package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
  79. package/dist/skills/superwall-framework/references/responsive.md +162 -0
  80. package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
  81. package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
  82. package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
  83. package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
  84. package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
  85. package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
  86. package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
  87. package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
  88. package/package.json +8 -7
  89. package/prompts/actions/paywall-migrate.xml +24 -0
  90. package/prompts/actions/screen-migrate.xml +26 -0
  91. package/dist/git-ZwA3Mx8m.js +0 -433
  92. package/dist/migrate-D_x1oyTk.js +0 -114
  93. package/dist/publish-C-zEUnO9.js +0 -35
  94. package/dist/push-DUDQG-EO.js +0 -35
  95. package/skills/README.md +0 -118
  96. /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
  97. /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
  98. /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
  99. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
  100. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
  101. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
  102. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
  103. /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
@@ -0,0 +1,893 @@
1
+ ## Data & Analytics - Superwall ClickHouse Data Warehouse - Master Documentation
2
+
3
+ The `superwall query` command runs SQL against Superwall's live production ClickHouse database. The API proxies authenticated requests to ClickHouse, manages credentials internally, and applies row-level security for the logged-in organization. The `data:read` scope is required.
4
+
5
+ #### Execution Environment
6
+
7
+ Use the CLI for every query. It resolves the current organization and authenticated session automatically. Pass `--json` for ClickHouse's native JSON envelope whenever another tool or agent will consume the result.
8
+
9
+ ```bash
10
+ superwall query "SHOW TABLES FROM sw" --json
11
+ superwall query "SELECT applicationId, name FROM sw.applications_rep FINAL LIMIT 20" --json
12
+ superwall query --file report.sql --json
13
+ ```
14
+
15
+ Agents should reach for `superwall query` proactively for revenue questions,
16
+ subscription health, conversion analysis, user behavior, ad hoc investigation,
17
+ custom dashboards, and recurring reports or notifications such as a daily MRR
18
+ update. Inspect first, bound the query, then turn useful SQL into a reusable
19
+ workflow.
20
+
21
+ #### Docs access
22
+
23
+ Verify the endpoint, exposed tables, and current limits against the live docs
24
+ before changing these instructions:
25
+
26
+ ```bash
27
+ curl -sL https://superwall.com/docs/llms.txt
28
+ curl -sL https://superwall.com/docs/dashboard/guides/query-clickhouse.md
29
+ ```
30
+
31
+ #### Critical Constraints
32
+
33
+ - **READ-ONLY OPERATIONS ONLY.** No DDL/DML. `SELECT`, `SHOW`, and `DESCRIBE` are the normal operations.
34
+ - **Query limits:** 300 seconds, 4 threads, 8 GB memory, and 20 GB read. Filter by `applicationId` first to stay well inside them.
35
+ - **Filter `ts < now()`** - some tables contain future timestamps (e.g. events_hr_agg has data up to 2038).
36
+ - **Never query `sw.events_rep` unless all of these are true**:
37
+ - filter by `applicationId`
38
+ - restrict `ts` to a bounded window no longer than 7 days using both `ts > toStartOfHour(now() - INTERVAL ...)` and `ts < now()`
39
+ - never use `FINAL`
40
+ - Use `uniq(id)` instead of `count(distinct id)` for better performance.
41
+ - Parse JSON with `JSONExtractString()`, `JSONExtractInt()`, `JSONExtractKeys()` etc.
42
+ - Always run `SHOW CREATE TABLE` before querying unfamiliar tables.
43
+ - Sample data first - `meta`, `props`, `headers`, `debug` columns contain JSON strings.
44
+
45
+ ---
46
+
47
+ #### Table Overview
48
+
49
+ | Table | Engine | Purpose | Scale |
50
+ | ------------------------------------------ | -------------------------- | ------------------------------------------------------------ | --------------------------------------- |
51
+ | `sw.applications_rep` | SharedReplacingMergeTree | App registry - maps applicationId to name/platform | ~37.5K apps |
52
+ | `sw.demand_score_events_rep` | SharedReplacingMergeTree | Events enriched with demand (purchase intent) scores | Billions of rows |
53
+ | `sw.events_hr_agg` | SharedAggregatingMergeTree | Hourly pre-aggregated event counts | Billions of aggregate rows |
54
+ | `sw.events_rep` | SharedReplacingMergeTree | **Raw event firehose** - every SDK event | Massive (billions). Use as last resort. |
55
+ | `sw.subscription_status_rep` | SharedReplacingMergeTree | Latest subscription status per user per app | One row per user (after FINAL) |
56
+ | `sw.user_attributes_rep` | SharedReplacingMergeTree | Key-value user attributes | Tens of millions per app |
57
+ | `open_revenue.attributed_events_by_ts_rep` | SharedReplacingMergeTree | Revenue attribution - subscriptions, renewals, cancellations | Millions per app |
58
+ | `open_revenue.paywall_open_events_agg` | SharedAggregatingMergeTree | Lifetime paywall open counts by experiment/variant/placement | ~490K rows, 9.9K apps |
59
+
60
+ ---
61
+
62
+ #### ReplacingMergeTree vs AggregatingMergeTree
63
+
64
+ - **ReplacingMergeTree** (`_rep` suffix): Deduplicates rows by ORDER BY key. Use `FINAL` when you need read-time deduplication, except on `sw.events_rep` where `FINAL` must never be used. Tables with `isDeleted` column - filter `isDeleted=0`.
65
+ - **AggregatingMergeTree** (`_agg` or `_hr_agg` suffix): Stores pre-aggregated states. Use `-Merge` combinators to read (e.g., `uniqMerge(count)`). **Never nest aggregate functions** - `sum(uniqMerge(x))` is illegal; use subqueries instead.
66
+
67
+ ---
68
+
69
+ ### 1. `sw.applications_rep`
70
+
71
+ #### Purpose
72
+
73
+ App registry. Maps `applicationId` (Int32) to app name and platform.
74
+
75
+ #### Schema
76
+
77
+ ```sql
78
+ CREATE TABLE sw.applications_rep
79
+ (
80
+ `applicationId` Int32,
81
+ `name` String,
82
+ `platform` LowCardinality(String),
83
+ `isDeleted` UInt8,
84
+ `insertedAt` DateTime64(6, 'UTC') DEFAULT now64()
85
+ )
86
+ ENGINE = SharedReplacingMergeTree(insertedAt, isDeleted)
87
+ ORDER BY applicationId
88
+ SETTINGS index_granularity = 512
89
+ ```
90
+
91
+ #### Key Details
92
+
93
+ - **ORDER BY**: `applicationId` - direct lookups are fast
94
+ - **No PARTITION** - small table, no partitioning needed
95
+ - **isDeleted**: Soft-delete flag. Currently 0 deleted apps exist (all 37,563 are active)
96
+ - **Platform values and counts**:
97
+ - `IOS`: 25,027
98
+ - `ANDROID`: 10,967
99
+ - `STRIPE`: 983
100
+ - `PROMOTIONAL`: 327
101
+ - `WEB`: 231
102
+ - `PADDLE`: 28
103
+
104
+ #### Multi-Platform App Pattern
105
+
106
+ An organization can have the same app across platforms - each gets its own `applicationId`. When an iOS app has Stripe checkout paywalls, `paywall_open` events happen on the iOS `applicationId` but revenue flows through the STRIPE `applicationId`. Link via `appUserId` or `attributionProps.paywallId`.
107
+
108
+ #### Vetted Queries
109
+
110
+ ```sql
111
+ -- Find an app by name
112
+ SELECT applicationId, name, platform
113
+ FROM sw.applications_rep FINAL
114
+ WHERE name ILIKE '%fitness%' AND isDeleted=0
115
+ ORDER BY applicationId
116
+ LIMIT 20
117
+ ```
118
+
119
+ ```sql
120
+ -- Platform breakdown
121
+ SELECT platform, count() as cnt
122
+ FROM sw.applications_rep FINAL
123
+ WHERE isDeleted=0
124
+ GROUP BY platform ORDER BY cnt DESC
125
+ ```
126
+
127
+ ---
128
+
129
+ ### 2. `sw.events_rep`
130
+
131
+ #### Purpose
132
+
133
+ **Raw event firehose.** Every SDK event from every app. Massive table (billions of rows). Use as a last resort - prefer aggregated tables (`events_hr_agg`, `sdk_events_agg`) when possible.
134
+
135
+ #### Hard Query Guardrails
136
+
137
+ - Query `sw.events_rep` only when all of these are true:
138
+ - `WHERE applicationId = ...`
139
+ - `ts > toStartOfHour(now() - INTERVAL ... ) AND ts < now()`
140
+ - the time window is no longer than 7 days, including "last 7d" queries
141
+ - Never use `FINAL` on `sw.events_rep`
142
+ - If those conditions cannot be met, use an aggregated table or a different source instead
143
+
144
+ #### Schema
145
+
146
+ ```sql
147
+ CREATE TABLE sw.events_rep
148
+ (
149
+ `id` String CODEC(ZSTD(1)),
150
+ `appUserId` String CODEC(ZSTD(1)),
151
+ `applicationId` UInt32,
152
+ `name` LowCardinality(String),
153
+ `meta` String CODEC(ZSTD(3)),
154
+ `props` String CODEC(ZSTD(3)),
155
+ `headers` String CODEC(ZSTD(3)),
156
+ `debug` String CODEC(ZSTD(3)),
157
+ `isSandbox` UInt8,
158
+ `ts` DateTime64(6, 'UTC') CODEC(ZSTD(1)),
159
+ `insertedAt` DateTime64(6, 'UTC') DEFAULT now64(),
160
+ `isDeleted` UInt8 DEFAULT 0
161
+ )
162
+ ENGINE = SharedReplacingMergeTree(insertedAt, isDeleted)
163
+ PARTITION BY toYYYYMM(ts)
164
+ PRIMARY KEY (applicationId, isSandbox, toStartOfHour(ts), name, appUserId, id)
165
+ ORDER BY (applicationId, isSandbox, toStartOfHour(ts), name, appUserId, id, ts)
166
+ SETTINGS index_granularity = 8192
167
+ ```
168
+
169
+ #### Key Details
170
+
171
+ - **PARTITION BY**: `toYYYYMM(ts)` - monthly partitions
172
+ - **PRIMARY KEY** includes `applicationId, isSandbox, toStartOfHour(ts), name` - always filter on these for performance
173
+ - **Mandatory filters**: `applicationId` and a bounded `ts` range no longer than 7 days, with both a lower bound and `ts < now()`
174
+ - **JSON columns**: `meta`, `props`, `headers`, `debug` are all JSON strings
175
+
176
+ #### `meta` JSON Keys
177
+
178
+ `aliases`, `apiKey`, `appInstallDate`, `appUserId`, `appVersion`, `applicationId`, `bundleId`, `cfg`, `deviceCurrencyCode`, `deviceCurrencySymbol`, `deviceLanguageCode`, `deviceLocale`, `deviceModel`, `headerParsingVersion`, `interfaceStyle`, `isLowPowerModeEnabled`, `isSandbox`, `organizationId`, `osVersion`, `outcome`, `platform`, `platformEnvironment`, `platformWrapper`, `projectId`, `radioType`, `receivedAt`, `remoteIp`, `requestCurrentTime`, `requestId`, `requestPath`, `requestRetryCount`, `requestUserAgent`, `requestVerb`, `sdkVersion`, `sha`, `source`, `srv`, `staticConfigBuildId`, `subscriptionStatus`, `timezoneOffset`, `urlScheme`, `vendorId`
179
+
180
+ #### `props` JSON Keys (varies by event name)
181
+
182
+ **For `paywall_open`**: `$app_session_id`, `$build_id`, `$cache_key`, `$close_reason`, `$event_name`, `$experiment_id`, `$feature_gating`, `$is_free_trial_available`, `$is_scroll_enabled`, `$is_standard_event`, `$paywall_id`, `$paywall_identifier`, `$paywall_name`, `$paywall_product_ids`, `$paywall_products_load_*` (timing fields), `$paywall_response_load_*`, `$paywall_url`, `$paywall_webview_load_*`, `$paywalljs_version`, `$presentation_source_type`, `$presented_by`, `$presented_by_event_id`, `$presented_by_event_name`, `$presented_by_event_timestamp`, `$primary_product_id`, `$secondary_product_id`, `$tertiary_product_id`, `$trigger_session_id`, `$variant_id`, `event_name`, `paywall_id`, `paywall_name`
183
+
184
+ **For `config_attributes`**: `$app_session_id`, `$automaticallyDismiss`, `$event_name`, `$has_delegate`, `$isExternalDataCollectionEnabled`, `$isGameControllerEnabled`, `$isHapticFeedbackEnabled`, `$is_standard_event`, `$localeIdentifier`, `$logLevel`, `$networkEnvironment`, `$restoreCloseButtonTitle`, `$restoreMessage`, `$restoreTitle`, `$shouldPreload`, `$shouldShowPurchaseFailureAlert`, `$transactionBackgroundView`, `$using_purchase_controller`, `event_name`
185
+
186
+ **For `transaction_complete`**: All `paywall_open` fields plus: `$product_*` (price, period, currency, trial info), `$source`, `$store`, `$storefront_countryCode`, `$storefront_id`, `$storekit_version`, `$transaction_type`
187
+
188
+ #### Common Event Names (from app 1 over 7 days, ordered by volume)
189
+
190
+ - `user_attributes` (310K), `logged_set` (290K), `app_open` (289K), `opened_application` (285K), `app_close` (267K)
191
+ - `paywallWebviewLoad_timeout` (117K), `trigger_fire` (88K), `config_attributes` (84K)
192
+ - `session_start` (45K), `device_attributes` (44K), `app_launch` (43K)
193
+ - `paywall_open`, `paywall_close`, `paywall_decline`, `transaction_start`, `transaction_complete`, `transaction_abandon`, `transaction_fail`
194
+ - App-specific custom events (e.g. `logged_set`, `start_workout`, `equipment_tap`)
195
+
196
+ #### Standard Superwall Events
197
+
198
+ These are system events emitted by the SDK:
199
+
200
+ - **Lifecycle**: `first_seen`, `app_install`, `app_open`, `app_close`, `app_launch`, `session_start`
201
+ - **Paywall**: `paywall_open`, `paywall_close`, `paywall_decline`, `paywall_show`, `trigger_fire`, `paywallPresentationRequest`
202
+ - **Transaction**: `transaction_start`, `transaction_complete`, `transaction_abandon`, `transaction_fail`, `transaction_restore`
203
+ - **Config**: `config_attributes`, `config_refresh`
204
+ - **Identity**: `identity_alias`, `subscriber_alias`, `user_attributes`, `device_attributes`
205
+ - **Subscription**: `subscriptionStatus_didChange`
206
+ - **Loading**: `paywallWebviewLoad_start/complete/timeout/fail`, `paywallResponseLoad_start/complete/fail`, `paywallProductsLoad_start/complete/fail/retry`
207
+
208
+ #### Vetted Queries
209
+
210
+ ```sql
211
+ -- Check SDK configuration (purchase controller, StoreKit version)
212
+ SELECT props
213
+ FROM sw.events_rep
214
+ WHERE applicationId = {app_id}
215
+ AND name = 'config_attributes'
216
+ AND ts > toStartOfHour(now() - INTERVAL 1 HOUR) AND ts < now()
217
+ LIMIT 1
218
+ ```
219
+
220
+ **Key fields in config_attributes props:**
221
+
222
+ - `$using_purchase_controller` - `true` = app handles purchases itself
223
+ - `$shouldObservePurchases` - `true` = Superwall listens for StoreKit transactions independently (only in some SDK versions)
224
+ - `$has_delegate` - whether a delegate is set
225
+
226
+ **Diagnosing missing revenue:** When `using_purchase_controller=true` and no `shouldObservePurchases`, Superwall relies entirely on the app to report purchase results.
227
+
228
+ ```sql
229
+ -- Recent event volume by name for an app
230
+ SELECT name, count() as cnt
231
+ FROM sw.events_rep
232
+ WHERE applicationId = {app_id} AND isSandbox = 0
233
+ AND ts > toStartOfHour(now() - INTERVAL 7 DAY) AND ts < now()
234
+ GROUP BY name ORDER BY cnt DESC LIMIT 30
235
+ ```
236
+
237
+ ---
238
+
239
+ ### 3. `sw.demand_score_events_rep`
240
+
241
+ #### Purpose
242
+
243
+ A subset of events enriched with **demand scores** - a 0-100 score predicting purchase intent. Structurally identical to `events_rep` but adds `demandScore`, `sessionId`, and an `appInstallDate` materialized column. Contains `device_attributes`, `paywall_open`, and `transaction_complete` events.
244
+
245
+ #### Schema
246
+
247
+ ```sql
248
+ CREATE TABLE sw.demand_score_events_rep
249
+ (
250
+ `id` String CODEC(ZSTD(1)),
251
+ `appUserId` String CODEC(ZSTD(1)),
252
+ `applicationId` UInt32,
253
+ `name` LowCardinality(String),
254
+ `meta` String CODEC(ZSTD(3)),
255
+ `props` String CODEC(ZSTD(3)),
256
+ `headers` String CODEC(ZSTD(3)),
257
+ `debug` String CODEC(ZSTD(3)),
258
+ `isSandbox` UInt8,
259
+ `ts` DateTime64(6, 'UTC') CODEC(ZSTD(1)),
260
+ `insertedAt` DateTime64(6, 'UTC') DEFAULT now64(),
261
+ `isDeleted` UInt8 DEFAULT 0,
262
+ `demandScore` Int64 DEFAULT -1,
263
+ `sessionId` String CODEC(ZSTD(1)),
264
+ `appInstallDate` Nullable(DateTime64(6, 'UTC'))
265
+ MATERIALIZED parseDateTime64BestEffortOrNull(JSONExtractString(meta, 'appInstallDate'), 6, 'UTC'),
266
+ PROJECTION installs_by_demand_score (
267
+ SELECT * ORDER BY isSandbox, name, appInstallDate, demandScore
268
+ )
269
+ )
270
+ ENGINE = SharedReplacingMergeTree(insertedAt, isDeleted)
271
+ PARTITION BY toYYYYMM(ts)
272
+ PRIMARY KEY (applicationId, isSandbox, toStartOfHour(ts), sessionId, id)
273
+ ORDER BY (applicationId, isSandbox, toStartOfHour(ts), sessionId, id, ts)
274
+ SETTINGS index_granularity = 8192
275
+ ```
276
+
277
+ #### Key Details
278
+
279
+ - **demandScore**: Int64, range 1-100 when populated, `-1` when not scored. Not all apps have scoring enabled.
280
+ - **Event names in this table**: `device_attributes` (vast majority), `paywall_open`, `transaction_complete`
281
+ - **sessionId**: Groups events within a single user session
282
+ - **appInstallDate**: Materialized from `meta.appInstallDate` JSON - allows cohort analysis
283
+ - **PROJECTION** `installs_by_demand_score`: Optimized for queries filtering by `isSandbox, name, appInstallDate, demandScore`
284
+ - **meta JSON keys**: Same as `events_rep`
285
+
286
+ #### Demand Score Distribution (from app 16022, 7-day window)
287
+
288
+ - Range: 1-100 (scores of 0 do not occur)
289
+ - Mean: ~47, Median (p50): 47, P95: 81
290
+ - Distribution is roughly bell-shaped, centered around 45-55
291
+ - Higher scores predict trial starts but inversely correlate with trial-to-paid conversion
292
+
293
+ #### Vetted Queries
294
+
295
+ ```sql
296
+ -- Demand score distribution for an app
297
+ SELECT demandScore, count() as cnt
298
+ FROM sw.demand_score_events_rep
299
+ WHERE applicationId = {app_id} AND isSandbox = 0
300
+ AND ts >= now() - INTERVAL 30 DAY AND demandScore >= 0
301
+ GROUP BY demandScore ORDER BY demandScore
302
+ ```
303
+
304
+ ```sql
305
+ -- Demand score stats by event name
306
+ SELECT name,
307
+ avg(demandScore) as avg,
308
+ quantile(0.5)(demandScore) as p50,
309
+ quantile(0.95)(demandScore) as p95
310
+ FROM sw.demand_score_events_rep
311
+ WHERE applicationId = {app_id} AND isSandbox = 0
312
+ AND ts >= now() - INTERVAL 7 DAY AND demandScore >= 0
313
+ GROUP BY name
314
+ ```
315
+
316
+ ---
317
+
318
+ ### 4. `sw.events_hr_agg`
319
+
320
+ #### Purpose
321
+
322
+ **Hourly pre-aggregated event counts.** Stores unique event counts per hour, per app, per event name, per source. Much lighter than querying `events_rep` directly for volume/trend analysis.
323
+
324
+ #### Schema
325
+
326
+ ```sql
327
+ CREATE TABLE sw.events_hr_agg
328
+ (
329
+ `ts` DateTime64(6, 'UTC'),
330
+ `name` LowCardinality(String) CODEC(ZSTD(1)),
331
+ `source` LowCardinality(String) CODEC(ZSTD(1)),
332
+ `applicationId` UInt64,
333
+ `isSandbox` UInt8,
334
+ `count` AggregateFunction(uniq, String),
335
+ `recentEvents` AggregateFunction(groupArraySorted(250), Tuple(
336
+ Int64, String, UInt32, String,
337
+ DateTime64(6, 'UTC'), DateTime64(6, 'UTC'),
338
+ String, String))
339
+ )
340
+ ENGINE = SharedAggregatingMergeTree
341
+ PARTITION BY toYYYYMM(ts)
342
+ ORDER BY (applicationId, isSandbox, name, ts)
343
+ SETTINGS index_granularity = 512
344
+ ```
345
+
346
+ #### Key Details
347
+
348
+ - **AggregatingMergeTree** - use `-Merge` combinators: `uniqMerge(count)` for unique event counts
349
+ - **`source` values**: `sdk` (events from the Superwall SDK), `integration` (events from integration partners like RevenueCat)
350
+ - **`count`**: `AggregateFunction(uniq, String)` - stores HyperLogLog state for unique event IDs. Read with `uniqMerge(count)`.
351
+ - **`recentEvents`**: Stores up to 250 recent events per bucket as sorted tuples. Read with `groupArraySortedMerge(250)(recentEvents)`.
352
+ - **Time range**: Data from 2024-09-26 through 2038-01-01 (future timestamps exist - always filter `ts < now()`)
353
+ - **Event names**: Hundreds - includes all standard Superwall events plus app-specific custom events
354
+ - **Cannot nest aggregate calls**: `sum(uniqMerge(count))` is illegal. Use a subquery:
355
+
356
+ ```sql
357
+ -- WRONG: sum(uniqMerge(count))
358
+ -- RIGHT: Use subquery
359
+ SELECT name, sum(hourly_uniques) as total
360
+ FROM (
361
+ SELECT name, ts, uniqMerge(count) as hourly_uniques
362
+ FROM sw.events_hr_agg
363
+ WHERE applicationId = {app_id} AND isSandbox = 0
364
+ AND ts >= now() - INTERVAL 7 DAY AND ts < now()
365
+ GROUP BY name, ts
366
+ ) GROUP BY name ORDER BY total DESC
367
+ ```
368
+
369
+ #### Vetted Queries
370
+
371
+ ```sql
372
+ -- Hourly unique event count for an app (recent)
373
+ SELECT ts, name, source, uniqMerge(count) as unique_events
374
+ FROM sw.events_hr_agg
375
+ WHERE applicationId = {app_id} AND isSandbox = 0
376
+ AND ts >= now() - INTERVAL 2 DAY AND ts < now()
377
+ GROUP BY ts, name, source
378
+ ORDER BY ts DESC LIMIT 20
379
+ ```
380
+
381
+ ```sql
382
+ -- Check if an app is sending events (last 5 minutes proxy: check last hour)
383
+ SELECT name, uniqMerge(count) as cnt
384
+ FROM sw.events_hr_agg
385
+ WHERE applicationId = {app_id} AND isSandbox = 0
386
+ AND ts >= now() - INTERVAL 1 HOUR AND ts < now()
387
+ GROUP BY name ORDER BY cnt DESC
388
+ ```
389
+
390
+ ---
391
+
392
+ ### 5. `sw.subscription_status_rep`
393
+
394
+ #### Purpose
395
+
396
+ **Latest subscription status per user per app.** One row per `(applicationId, appUserId, isSandbox)` after `FINAL`. The `name` column always contains `subscriptionStatus_didChange`. The actual status (`ACTIVE`/`INACTIVE`) is in the `props` JSON.
397
+
398
+ #### Schema
399
+
400
+ ```sql
401
+ CREATE TABLE sw.subscription_status_rep
402
+ (
403
+ `id` String CODEC(ZSTD(1)),
404
+ `appUserId` String CODEC(ZSTD(1)),
405
+ `applicationId` UInt32,
406
+ `name` LowCardinality(String),
407
+ `meta` String CODEC(ZSTD(3)),
408
+ `props` String CODEC(ZSTD(3)),
409
+ `headers` String CODEC(ZSTD(3)),
410
+ `debug` String CODEC(ZSTD(3)),
411
+ `isSandbox` UInt8,
412
+ `ts` DateTime64(6, 'UTC') CODEC(ZSTD(1)),
413
+ `insertedAt` DateTime64(6, 'UTC') DEFAULT now64(),
414
+ `isDeleted` UInt8 DEFAULT 0
415
+ )
416
+ ENGINE = SharedReplacingMergeTree(insertedAt, isDeleted)
417
+ ORDER BY (applicationId, appUserId, isSandbox)
418
+ SETTINGS index_granularity = 8192
419
+ ```
420
+
421
+ #### Key Details
422
+
423
+ - **ORDER BY**: `(applicationId, appUserId, isSandbox)` - one row per user after FINAL (latest status wins)
424
+ - **No PARTITION** - not partitioned by time
425
+ - **name** column: Always `subscriptionStatus_didChange`
426
+ - **Subscription status** is in `props.$subscription_status`: values are `ACTIVE` or `INACTIVE`
427
+ - **Status distribution** (app 1): 251,682 INACTIVE, 29,846 ACTIVE (~10.6% active)
428
+ - **Always use FINAL** and filter `isDeleted=0`
429
+
430
+ #### Vetted Queries
431
+
432
+ ```sql
433
+ -- Subscription status distribution for an app
434
+ SELECT
435
+ JSONExtractString(props, '$subscription_status') as status,
436
+ count() as cnt
437
+ FROM sw.subscription_status_rep FINAL
438
+ WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
439
+ GROUP BY status ORDER BY cnt DESC
440
+ ```
441
+
442
+ ```sql
443
+ -- Check a specific user's subscription status
444
+ SELECT appUserId,
445
+ JSONExtractString(props, '$subscription_status') as status,
446
+ ts
447
+ FROM sw.subscription_status_rep FINAL
448
+ WHERE applicationId = {app_id} AND appUserId = '{user_id}' AND isSandbox = 0
449
+ ```
450
+
451
+ ```sql
452
+ -- Count active subscribers
453
+ SELECT count() as active_subscribers
454
+ FROM sw.subscription_status_rep FINAL
455
+ WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
456
+ AND JSONExtractString(props, '$subscription_status') = 'ACTIVE'
457
+ ```
458
+
459
+ ---
460
+
461
+ ### 6. `sw.user_attributes_rep`
462
+
463
+ #### Purpose
464
+
465
+ **Key-value user attributes.** Each row is one attribute for one user. Easier than parsing JSON from `events_rep` for user segmentation. Stores custom attributes set by the app and some system attributes.
466
+
467
+ #### Schema
468
+
469
+ ```sql
470
+ CREATE TABLE sw.user_attributes_rep
471
+ (
472
+ `appUserId` String CODEC(ZSTD(1)),
473
+ `key` LowCardinality(String) CODEC(ZSTD(3)),
474
+ `type` LowCardinality(String) CODEC(ZSTD(3)),
475
+ `value` String CODEC(ZSTD(1)),
476
+ `applicationId` UInt64,
477
+ `isSandbox` UInt8,
478
+ `isDeleted` UInt8,
479
+ `ts` DateTime64(6, 'UTC'),
480
+ `jsType` LowCardinality(String)
481
+ MATERIALIZED multiIf(
482
+ position(lower(type), 'int') != 0, 'number',
483
+ position(lower(type), 'double') != 0, 'number',
484
+ position(lower(type), 'string') != 0, 'string',
485
+ position(lower(type), 'object') != 0, 'object',
486
+ position(lower(type), 'array') != 0, 'array',
487
+ position(lower(type), 'null') != 0, 'null',
488
+ position(lower(type), 'bool') != 0, 'boolean',
489
+ 'string')
490
+ )
491
+ ENGINE = SharedReplacingMergeTree(ts, isDeleted)
492
+ ORDER BY (applicationId, isSandbox, appUserId, key)
493
+ SETTINGS index_granularity = 512
494
+ ```
495
+
496
+ #### Key Details
497
+
498
+ - **ORDER BY**: `(applicationId, isSandbox, appUserId, key)` - one row per user per key after FINAL
499
+ - **Version column**: `ts` (not `insertedAt`) - latest timestamp wins in ReplacingMergeTree
500
+ - **isDeleted**: Soft-delete flag. Filter `isDeleted=0`.
501
+ - **type values**: `String` (17M), `Bool` (15M), `Int64` (11M), `Double` (2M), `Null` (7K), `UInt64` (1)
502
+ - **jsType**: Materialized column normalizing `type` → JavaScript types (`number`, `string`, `boolean`, `object`, `array`, `null`)
503
+
504
+ #### Common Attribute Keys (app 1)
505
+
506
+ System attributes (prefixed with `$`): `$application_installed_at`, `$app_session_id`
507
+ App-specific: `first_name`, `created_at`, `subscription_canceled`, `apns_token`, `email`, `age`, `seed`, `aliasId`, `paying_user`, `uses_metric_units`, `defaultEquipment`, `routine`, `audio_queues`, etc.
508
+
509
+ #### Vetted Queries
510
+
511
+ ```sql
512
+ -- Get all attributes for a specific user
513
+ SELECT key, type, value, ts
514
+ FROM sw.user_attributes_rep FINAL
515
+ WHERE applicationId = {app_id} AND isSandbox = 0
516
+ AND appUserId = '{user_id}' AND isDeleted = 0
517
+ ORDER BY key
518
+ ```
519
+
520
+ ```sql
521
+ -- List available attribute keys for an app
522
+ SELECT key, count() as user_count, any(type) as sample_type
523
+ FROM sw.user_attributes_rep FINAL
524
+ WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
525
+ GROUP BY key ORDER BY user_count DESC LIMIT 30
526
+ ```
527
+
528
+ ```sql
529
+ -- Segment users by an attribute value
530
+ SELECT value as subscription_status, uniq(appUserId) as users
531
+ FROM sw.user_attributes_rep FINAL
532
+ WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
533
+ AND key = 'paying_user'
534
+ GROUP BY value ORDER BY users DESC
535
+ ```
536
+
537
+ ---
538
+
539
+ ### 7. `open_revenue.attributed_events_by_ts_rep`
540
+
541
+ #### Purpose
542
+
543
+ **Revenue attribution table.** The core table for all subscription revenue analysis. Contains purchase events from integrations (RevenueCat, App Store Connect) and SDK transaction_complete events, with attribution back to Superwall paywalls/experiments.
544
+
545
+ #### Schema
546
+
547
+ ```sql
548
+ CREATE TABLE open_revenue.attributed_events_by_ts_rep
549
+ (
550
+ -- Core columns
551
+ `insertedAt` DateTime64(6, 'UTC') DEFAULT now64(),
552
+ `id` String CODEC(ZSTD(1)),
553
+ `name` LowCardinality(String),
554
+ `meta` String CODEC(ZSTD(3)),
555
+ `props` String CODEC(ZSTD(3)),
556
+ `headers` String CODEC(ZSTD(3)),
557
+ `debug` String CODEC(ZSTD(3)),
558
+ `ts` DateTime64(6, 'UTC'),
559
+ `purchasedAt` DateTime64(6, 'UTC'),
560
+ `attributionTs` DateTime64(6, 'UTC'),
561
+ `originalTransactionId` String CODEC(ZSTD(1)),
562
+ `applicationId` UInt32,
563
+ `isSandbox` UInt8,
564
+ `attributionProps` String CODEC(ZSTD(3)),
565
+ `attributionEventId` String CODEC(ZSTD(1)),
566
+
567
+ -- Materialized columns (extracted from JSON at insert time)
568
+ `organizationId` UInt32,
569
+ `appUserId` Nullable(String),
570
+ `vendorId` Nullable(String),
571
+ `source` String, -- 'sdk' or 'integration'
572
+ `integration` LowCardinality(Nullable(String)), -- 'revenue_cat', 'app_store_connect'
573
+ `store` LowCardinality(Nullable(String)), -- 'APP_STORE', 'STRIPE', 'PROMOTIONAL'
574
+ `experimentId` Nullable(UInt32),
575
+ `variantId` Nullable(UInt32),
576
+ `placement` Nullable(String),
577
+ `paywallId` Nullable(UInt32),
578
+ `transactionCompleteEventDate` Nullable(DateTime64(6, 'UTC')),
579
+ `installDate` Nullable(DateTime64(6, 'UTC')),
580
+ `transactionId` Nullable(String),
581
+ `price` Nullable(Decimal(65, 2)),
582
+ `priceInPurchasedCurrency` Nullable(Decimal(65, 2)),
583
+ `proceeds` Nullable(Decimal(65, 2)),
584
+ `exchangeRate` Nullable(Decimal(65, 6)),
585
+ `productId` Nullable(String),
586
+ `periodType` LowCardinality(Nullable(String)), -- 'TRIAL', 'NORMAL', 'PROMOTIONAL', 'INTRO'
587
+ `isTrialConversion` UInt8,
588
+ `takehomePercentage` Float64,
589
+ `commissionPercentage` Float64,
590
+ `taxPercentage` Float64,
591
+ `environment` LowCardinality(String),
592
+ `newProductId` Nullable(String),
593
+ `expirationAt` Nullable(DateTime64(6, 'UTC')),
594
+ `cancelReason` LowCardinality(Nullable(String)),
595
+ `isFamilyShare` UInt8,
596
+ `isSmallBusiness` UInt8,
597
+ `isRefund` UInt8,
598
+ `countryCode` LowCardinality(Nullable(String)),
599
+ `currencyCode` LowCardinality(Nullable(String)),
600
+ `offerCode` Nullable(String),
601
+ `sdkVersion` Nullable(String),
602
+ `appVersion` Nullable(String),
603
+ -- Apple Search Ads attribution fields
604
+ `appleSearchAdsAdGroupId`, `appleSearchAdsAdGroupName`, `appleSearchAdsAdId`,
605
+ `appleSearchAdsAttribution`, `appleSearchAdsBidAmount`, `appleSearchAdsBidCurrency`,
606
+ `appleSearchAdsCampaignId`, `appleSearchAdsCampaignName`, `appleSearchAdsConversionType`,
607
+ `appleSearchAdsCountryOrRegion`, `appleSearchAdsKeywordId`, `appleSearchAdsKeywordName`,
608
+ `appleSearchAdsMatchType`, `appleSearchAdsOrgId`,
609
+ -- Other
610
+ `userAttributes` Nullable(String),
611
+ `demandScore` Nullable(Int32), -- 0-99 purchase intent score
612
+ `demandTier` Nullable(String)
613
+ )
614
+ ENGINE = SharedReplacingMergeTree(attributionTs)
615
+ PARTITION BY toYYYYMM(ts)
616
+ ORDER BY (applicationId, isSandbox, toStartOfHour(ts), name, id)
617
+ SETTINGS index_granularity = 8192
618
+ ```
619
+
620
+ #### Key Details
621
+
622
+ - **Version column**: `attributionTs` (not `insertedAt`) - controls dedup in ReplacingMergeTree
623
+ - **Always use FINAL**
624
+ - **PARTITION BY**: `toYYYYMM(ts)` - monthly
625
+
626
+ ##### Event Names (`name`)
627
+
628
+ | Name | Description | Count (app 1, 2025) |
629
+ | ----------------------- | ----------------------------------- | ------------------- |
630
+ | `expiration` | Subscription expired | 82,410 |
631
+ | `cancellation` | Subscription cancelled | 81,239 |
632
+ | `renewal` | Subscription renewed | 78,567 |
633
+ | `initial_purchase` | First purchase (trial or paid) | 61,930 |
634
+ | `transaction_complete` | SDK-reported purchase completion | 61,124 |
635
+ | `billing_issue` | Payment failed | 16,531 |
636
+ | `non_renewing_purchase` | One-time purchase | 6,305 |
637
+ | `product_change` | Subscription product changed | 1,097 |
638
+ | `uncancellation` | User re-subscribed after cancelling | 654 |
639
+
640
+ ##### Source and Integration
641
+
642
+ - **source**: `sdk` (from Superwall SDK `transaction_complete`) or `integration` (from RevenueCat, App Store Connect, etc.)
643
+ - **integration values**: `revenue_cat`, `app_store_connect`
644
+ - `transaction_complete` events always have source=`sdk`; all other event names come from integrations
645
+
646
+ ##### Attribution
647
+
648
+ - **attributionEventId**: Non-empty when the revenue event is attributed to a Superwall paywall presentation
649
+ - Events with empty `attributionEventId` are organic/unattributed
650
+ - Attribution rate varies by event type (e.g. app 1: `initial_purchase` 84% attributed, `renewal` 62%)
651
+
652
+ ##### periodType Values
653
+
654
+ | Value | Meaning | Count (app 1, 2025) |
655
+ | ------------- | ------------------------------------------------ | ------------------- |
656
+ | `NORMAL` | Regular paid period | 220,487 |
657
+ | `TRIAL` | Free trial period | 107,547 |
658
+ | NULL | SDK transaction_complete events (no period info) | 61,124 |
659
+ | `PROMOTIONAL` | Promotional offer | 377 |
660
+ | `INTRO` | Introductory offer | 322 |
661
+
662
+ **Note**: Case varies - always use `lower(periodType)` for filtering.
663
+
664
+ ##### cancelReason Values
665
+
666
+ `UNSUBSCRIBE` (61,641), `BILLING_ERROR` (17,387), `CUSTOMER_SUPPORT` (2,206), `DEVELOPER_INITIATED` (5)
667
+
668
+ ##### Store Values
669
+
670
+ `APP_STORE`, `STRIPE`, `PROMOTIONAL`
671
+
672
+ ##### `attributionProps` JSON Keys
673
+
674
+ `paywallId`, `variantId`, `experimentId`, `placement`, `appUserId`, `platform`, `store`, `productId`, `vendorId`, `appVersion`, `sdkVersion`, `countryCode`, `currencyCode`, `ts` (transaction_complete event date), `installDate`, `attrDemandScore`, `attrDemandTier`, `transactionId`, `price`, `priceInPurchasedCurrency`, `proceeds`, `exchangeRate`, `periodType`, `isTrialConversion`, `takehomePercentage`, `commissionPercentage`, `taxPercentage`, `environment`, `newProductId`, `expirationAt`, `cancelReason`, `isFamilyShare`, `isSmallBusiness`, `isRefund`, `offerCode`, `userAttributes`, Apple Search Ads fields
675
+
676
+ #### Trial Event Definitions
677
+
678
+ ```sql
679
+ name = 'initial_purchase' AND lower(periodType) = 'trial' -- Trial start
680
+ name = 'cancellation' AND lower(periodType) = 'trial' -- Trial cancel
681
+ name = 'renewal' AND isTrialConversion = 1 -- Trial conversion to paid
682
+ name = 'billing_issue' AND lower(periodType) = 'trial' -- Trial billing issue
683
+ ```
684
+
685
+ #### Dedup Pattern for Revenue
686
+
687
+ Events can arrive from multiple sources (SDK + RevenueCat + App Store Connect). Dedup by `(applicationId, name, originalTransactionId, transactionId, attributed)`:
688
+
689
+ ```sql
690
+ SELECT applicationId, attributed,
691
+ sum(price) AS net_revenue,
692
+ sumIf(price, price > 0) AS gross_revenue,
693
+ sumIf(price, price < 0) AS refund_revenue,
694
+ uniq(originalTransactionId) as subscriptions,
695
+ uniqIf(originalTransactionId, price > 0) as paid_subscribers
696
+ FROM (
697
+ SELECT applicationId, originalTransactionId, transactionId, name,
698
+ attributionEventId != '' as attributed,
699
+ argMax(price, ts) AS price
700
+ FROM open_revenue.attributed_events_by_ts_rep FINAL
701
+ WHERE isSandbox = 0 AND applicationId = {app_id}
702
+ AND ts >= now() - INTERVAL 90 DAY AND ts < now()
703
+ AND isFamilyShare = 0
704
+ GROUP BY applicationId, name, originalTransactionId, transactionId, attributed
705
+ )
706
+ GROUP BY applicationId, attributed
707
+ ```
708
+
709
+ #### ARPU (Revenue per Paywall Open)
710
+
711
+ ARPU is computed as **revenue per paywall open**. Join two sources on date:
712
+
713
+ 1. Paywall opens from `open_revenue.sdk_events_agg` (name=`paywall_open`, tsType=`event_time`)
714
+ 2. Revenue from this table, using trial conversions (name=`renewal`, isTrialConversion=1)
715
+
716
+ This works because trial conversions share the same `transaction_complete` date as the paywall open that initiated them.
717
+
718
+ ```sql
719
+ WITH opens AS (
720
+ SELECT toDate(ts) as day,
721
+ CASE WHEN breakdown['paywallId'] IN ('id1','id2') THEN 'a' ELSE 'b' END as seg,
722
+ uniqIfMerge(vendorIds) as open_users
723
+ FROM open_revenue.sdk_events_agg
724
+ WHERE applicationId = {app_id} AND isSandbox = 0
725
+ AND name = 'paywall_open' AND tsType = 'event_time'
726
+ AND ts >= now() - INTERVAL 45 DAY AND ts < now()
727
+ GROUP BY day, seg
728
+ ),
729
+ rev AS (
730
+ SELECT toDate(ts) as day,
731
+ CASE WHEN JSONExtractString(attributionProps, 'paywallId') IN ('id1','id2') THEN 'a' ELSE 'b' END as seg,
732
+ round(sum(price), 2) as revenue
733
+ FROM open_revenue.attributed_events_by_ts_rep FINAL
734
+ WHERE applicationId IN ({app_ids}) AND isSandbox = 0
735
+ AND name = 'renewal' AND isTrialConversion = 1 AND price > 0
736
+ AND ts >= now() - INTERVAL 45 DAY AND ts < now()
737
+ GROUP BY day, seg
738
+ )
739
+ SELECT o.day, o.seg, o.open_users,
740
+ coalesce(r.revenue, 0) as revenue,
741
+ round(coalesce(r.revenue, 0) / o.open_users, 4) as rev_per_open
742
+ FROM opens o
743
+ LEFT JOIN rev r ON o.day = r.day AND o.seg = r.seg
744
+ ORDER BY o.day, o.seg
745
+ ```
746
+
747
+ ---
748
+
749
+ ### 8. `open_revenue.paywall_open_events_agg`
750
+
751
+ #### Purpose
752
+
753
+ **Lifetime paywall open counts** aggregated by experiment, variant, paywall, and placement. An AggregatingMergeTree storing all-time unique users and total views per combination. No time dimension - purely lifetime aggregates.
754
+
755
+ #### Schema
756
+
757
+ ```sql
758
+ CREATE TABLE open_revenue.paywall_open_events_agg
759
+ (
760
+ `applicationId` Int32,
761
+ `experimentId` Int64,
762
+ `variantId` Int64,
763
+ `paywallId` Int32,
764
+ `placement` String,
765
+ `environment` Enum8('PRODUCTION' = 1, 'SANDBOX' = 2) DEFAULT 'PRODUCTION',
766
+ `users_state` AggregateFunction(uniq, String),
767
+ `views_state` AggregateFunction(uniq, String)
768
+ )
769
+ ENGINE = SharedAggregatingMergeTree
770
+ ORDER BY (applicationId, environment, experimentId, variantId, paywallId, placement)
771
+ SETTINGS index_granularity = 8192
772
+ ```
773
+
774
+ #### Key Details
775
+
776
+ - **No time column** - lifetime aggregates only. Cannot do time-based filtering.
777
+ - **No PARTITION** - single partition
778
+ - **Stats**: ~490K rows, 9,909 unique apps, 59,783 experiments, 78,045 paywalls
779
+ - **environment**: Enum with values `PRODUCTION` (491K rows) and `SANDBOX` (154K rows)
780
+ - **users_state**: `AggregateFunction(uniq, String)` - unique users who opened the paywall. Read with `uniqMerge(users_state)`.
781
+ - **views_state**: `AggregateFunction(uniq, String)` - unique views (event IDs, not user IDs). Read with `uniqMerge(views_state)`.
782
+ - **Note**: Despite the name `views_state`, this counts unique view event IDs, so the same user opening the same paywall twice counts as 2 views.
783
+
784
+ #### Vetted Queries
785
+
786
+ ```sql
787
+ -- Top paywalls by unique users for an app
788
+ SELECT paywallId, placement, experimentId, variantId,
789
+ uniqMerge(users_state) as unique_users,
790
+ uniqMerge(views_state) as total_views
791
+ FROM open_revenue.paywall_open_events_agg
792
+ WHERE applicationId = {app_id} AND environment = 'PRODUCTION'
793
+ GROUP BY paywallId, placement, experimentId, variantId
794
+ ORDER BY unique_users DESC LIMIT 20
795
+ ```
796
+
797
+ ```sql
798
+ -- Compare A/B test variants
799
+ SELECT variantId,
800
+ uniqMerge(users_state) as unique_users,
801
+ uniqMerge(views_state) as total_views
802
+ FROM open_revenue.paywall_open_events_agg
803
+ WHERE applicationId = {app_id} AND environment = 'PRODUCTION'
804
+ AND experimentId = {exp_id}
805
+ GROUP BY variantId ORDER BY variantId
806
+ ```
807
+
808
+ ---
809
+
810
+ # Related Tables (Not Documented Here But Referenced)
811
+
812
+ | Table | Purpose |
813
+ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
814
+ | `analytics.ps_applications` | App metadata replicated from PlanetScale, Superwall's application layer db. Use `applicationName` (not `name`). |
815
+ | `open_revenue.attributed_events_by_experiment_rep` | Revenue by A/B experiment (use FINAL) |
816
+ | `open_revenue.sdk_events_agg` | Pre-aggregated SDK events - prefer over `events_rep` for counts/uniques. Uses AggregateFunction columns. |
817
+ | `sw.device_attributes_rep` | Device-level attributes (use FINAL, filter isDeleted=0) |
818
+ | `sw.user_aliases_rep` | User ID to alias mappings (use FINAL, filter isDeleted=0) |
819
+
820
+ #### `open_revenue.sdk_events_agg` Quick Reference
821
+
822
+ Pre-aggregated SDK events. Much faster than raw tables for counts/uniques.
823
+
824
+ **ORDER BY:** `(applicationId, isSandbox, ts, tsType, name, breakdown)`
825
+
826
+ **Key columns:** `applicationId`, `isSandbox`, `ts`, `name`, `tsType`, `breakdown` (Map), `vendorIds` (use `uniqIfMerge`), `vendorIdsD1`..`D90` (retention cohorts)
827
+
828
+ **Event names:** `first_seen`, `session_start`, `paywall_open`, `transaction_start`, `transaction_complete`, `transaction_abandon`, `transaction_restore`, `transaction_fail`
829
+
830
+ **tsType:** `event_time` (when event occurred) or `install_time` (user's install date for cohorts)
831
+
832
+ **Breakdown map keys:** `store`, `countryCode`, `currencyCode`, `languageCode`, `bundleId`, `productId`, `placement`, `sdkVersion`, `platformWrapper`, `platform`, `platformEnvironment`, `subscriptionStatus`, `variantId`, `experimentId`, `paywallId`
833
+
834
+ ```sql
835
+ -- Weekly installs
836
+ SELECT toStartOfWeek(ts, 1) as week, uniqIfMerge(vendorIds) as installs
837
+ FROM open_revenue.sdk_events_agg
838
+ WHERE applicationId = {app_id} AND isSandbox = 0
839
+ AND name = 'first_seen' AND tsType = 'install_time'
840
+ AND ts >= now() - INTERVAL 90 DAY AND ts < now()
841
+ GROUP BY week ORDER BY week
842
+ ```
843
+
844
+ ---
845
+
846
+ # Cross-Table Relationships
847
+
848
+ ```
849
+ sw.applications_rep (applicationId)
850
+ ├── sw.events_rep (applicationId) - raw event firehose
851
+ │ └── sw.events_hr_agg (applicationId) - hourly aggregation
852
+ │ └── sw.demand_score_events_rep (applicationId) - events with demand scores
853
+ ├── sw.subscription_status_rep (applicationId, appUserId) - current sub status
854
+ ├── sw.user_attributes_rep (applicationId, appUserId) - user attribute KV store
855
+ ├── open_revenue.attributed_events_by_ts_rep (applicationId) - revenue events
856
+ └── open_revenue.paywall_open_events_agg (applicationId) - lifetime paywall opens
857
+ ```
858
+
859
+ #### Finding an Application
860
+
861
+ 1. Search `analytics.ps_applications` by name (or `sw.applications_rep`)
862
+ 2. If multiple results, check `sw.events_hr_agg` for recent event counts
863
+ 3. Show `applicationId` + link: `superwall.com/applications/:applicationId`
864
+
865
+ ```sql
866
+ SELECT applicationId, name, platform
867
+ FROM sw.applications_rep FINAL
868
+ WHERE name ILIKE '%app_name%' AND isDeleted = 0
869
+ ```
870
+
871
+ ---
872
+
873
+ # Identifying Stripe vs App Store Paywalls
874
+
875
+ iOS and Android apps can sell Stripe products (aka app2web, in-app web checkout) within their Superwall paywalls. In this scenario, paywall_open and revenue events events appear under the app the purchase originated in.
876
+
877
+ i.e. do not assume Stripe revenue is always attached to any specific app / platform within a project.
878
+
879
+ ---
880
+
881
+ # Query Best Practices Summary
882
+
883
+ 1. **Always filter by `applicationId` first** - it's the leading ORDER BY key on every table
884
+ 2. **Filter `isSandbox = 0`** for production data
885
+ 3. **Use `FINAL`** on ReplacingMergeTree tables only when needed for deduplication, but **never** on `sw.events_rep`
886
+ 4. **Filter `isDeleted = 0`** on tables with soft-delete (applications_rep, subscription_status_rep, user_attributes_rep, events_rep, demand_score_events_rep)
887
+ 5. **Filter `ts < now()`** - some tables have future timestamps
888
+ 6. **Only query `sw.events_rep` with `applicationId` and both `ts > toStartOfHour(now() - INTERVAL ...)` and `ts < now()`**, with a window no longer than 7 days
889
+ 7. **Use `-Merge` combinators** on AggregatingMergeTree tables: `uniqMerge()`, `groupArraySortedMerge()`
890
+ 8. **Never nest aggregate functions** - use subqueries instead
891
+ 9. **Use `lower(periodType)`** in attributed_events - case is inconsistent
892
+ 10. **Prefer aggregated tables** over `events_rep` when possible
893
+ 11. **LIMIT everything** during exploration - these tables have billions of rows