1# Subscription Cost
2 
3Use these rules when the problem is too many reactive subscriptions, queries
4invalidating too frequently, or React components re-rendering excessively due to
5Convex state changes.
6 
7## Core Principle
8 
9Every `useQuery` and `usePaginatedQuery` call creates a live subscription. The
10server tracks the query's read set and re-executes the query whenever any
11document in that read set changes. Subscription cost scales with:
12 
13`subscriptions x invalidation_frequency x query_cost`
14 
15Subscriptions are not inherently bad. Convex reactivity is often the right
16default. The goal is to reduce unnecessary invalidation work, not to eliminate
17subscriptions on principle.
18 
19## Symptoms
20 
21- Dashboard shows high active subscription count
22- UI feels sluggish or laggy despite fast individual queries
23- React profiling shows frequent re-renders from Convex state
24- Pages with many components each running their own `useQuery`
25- Paginated lists where every loaded page stays subscribed
26 
27## Common Causes
28 
29### Reactive queries on low-freshness flows
30 
31Some user flows are read-heavy and do not need live updates every time the
32underlying data changes. In those cases, ongoing subscriptions may cost more
33than they are worth.
34 
35### Overly broad queries
36 
37A query that returns a large result set invalidates whenever any document in
38that set changes. The broader the query, the more frequent the invalidation.
39 
40### Too many subscriptions per page
41 
42A page with 20 list items, each running its own `useQuery` to fetch related
43data, creates 20+ subscriptions per visitor.
44 
45### Paginated queries keeping all pages live
46 
47`usePaginatedQuery` with `loadMore` keeps every loaded page subscribed. On a
48page where a user has scrolled through 10 pages, all 10 stay reactive.
49 
50### Frequently-updated fields on widely-read documents
51 
52A document that many queries touch gets a frequently-updated field (like
53`lastSeen`, `lastActiveAt`, or a counter). Every write to that field invalidates
54every subscription that reads the document, even if those subscriptions never
55use the field. This is different from OCC conflicts (see `occ-conflicts.md`),
56which are write-vs-write contention. This is write-vs-subscription: the write
57succeeds fine, but it forces hundreds of queries to re-run for no reason.
58 
59## Fix Order
60 
61### 1. Use point-in-time reads when live updates are not valuable
62 
63Keep `useQuery` and `usePaginatedQuery` by default when the product benefits
64from fresh live data.
65 
66Consider a point-in-time read instead when all of these are true:
67 
68- the flow is high-read
69- the underlying data changes less often than users need to see
70- explicit refresh, periodic refresh, or a fresh read on navigation is
71  acceptable
72 
73Possible implementations depend on environment:
74 
75- a server-rendered fetch
76- a framework helper like `fetchQuery`
77- a point-in-time client read such as `ConvexHttpClient.query()`
78 
79```ts
80// Reactive by default when fresh live data matters
81function TeamPresence() {
82  const presence = useQuery(api.teams.livePresence, { teamId });
83  return <PresenceList users={presence} />;
84}
85```
86 
87```ts
88// Point-in-time read when explicit refresh is acceptable
89import { ConvexHttpClient } from "convex/browser";
90 
91const client = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
92 
93function SnapshotView() {
94  const [items, setItems] = useState<Item[]>([]);
95 
96  useEffect(() => {
97    client.query(api.items.snapshot).then(setItems);
98  }, []);
99 
100  return <ItemGrid items={items} />;
101}
102```
103 
104Good candidates for point-in-time reads:
105 
106- aggregate snapshots
107- reports
108- low-churn listings
109- flows where explicit refresh is already acceptable
110 
111Keep reactive for:
112 
113- collaborative editing
114- live dashboards
115- presence-heavy views
116- any surface where users expect fresh changes to appear automatically
117 
118### 2. Batch related data into fewer queries
119 
120Instead of N components each fetching their own related data, fetch it in a
121single query.
122 
123```ts
124// Bad: each card fetches its own author
125function ProjectCard({ project }: { project: Project }) {
126  const author = useQuery(api.users.get, { id: project.authorId });
127  return <Card title={project.name} author={author?.name} />;
128}
129```
130 
131```ts
132// Good: parent query returns projects with author names included
133function ProjectList() {
134  const projects = useQuery(api.projects.listWithAuthors);
135  return projects?.map((p) => (
136    <Card key={p._id} title={p.name} author={p.authorName} />
137  ));
138}
139```
140 
141This can use denormalized fields or server-side joins in the query handler.
142Either way, it is one subscription instead of N.
143 
144This is not automatically better. If the combined query becomes much broader and
145invalidates much more often, several narrower subscriptions may be the better
146tradeoff. Optimize for total invalidation cost, not raw subscription count.
147 
148### 3. Use skip to avoid unnecessary subscriptions
149 
150The `"skip"` value prevents a subscription from being created when the arguments
151are not ready.
152 
153```ts
154// Bad: subscribes with undefined args, wastes a subscription slot
155const profile = useQuery(api.users.getProfile, { userId: selectedId! });
156```
157 
158```ts
159// Good: skip when there is nothing to fetch
160const profile = useQuery(
161  api.users.getProfile,
162  selectedId ? { userId: selectedId } : "skip",
163);
164```
165 
166### 4. Isolate frequently-updated fields into separate documents
167 
168If a document is widely read but has a field that changes often, move that field
169to a separate document. Queries that do not need the field will no longer be
170invalidated by its writes.
171 
172```ts
173// Bad: lastSeen lives on the user doc, every heartbeat invalidates
174// every query that reads this user
175const users = defineTable({
176  name: v.string(),
177  email: v.string(),
178  lastSeen: v.number(),
179});
180```
181 
182```ts
183// Good: lastSeen lives in a separate heartbeat doc
184const users = defineTable({
185  name: v.string(),
186  email: v.string(),
187  heartbeatId: v.id("heartbeats"),
188});
189 
190const heartbeats = defineTable({
191  lastSeen: v.number(),
192});
193```
194 
195Queries that only need `name` and `email` no longer re-run on every heartbeat.
196Queries that actually need online status fetch the heartbeat document
197explicitly.
198 
199For an even further optimization, if you only need a coarse online/offline
200boolean rather than the exact `lastSeen` timestamp, add a separate presence
201document with an `isOnline` flag. Update it immediately when a user comes
202online, and use a cron to batch-mark users offline when their heartbeat goes
203stale. This way the presence query only invalidates when online status actually
204changes, not on every heartbeat.
205 
206### 5. Use the aggregate component for counts and sums
207 
208Reactive global counts (`SELECT COUNT(*)` equivalent) invalidate on every insert
209or delete to the table. The
210[`@convex-dev/aggregate`](https://www.npmjs.com/package/@convex-dev/aggregate)
211component maintains denormalized COUNT, SUM, and MAX values efficiently so you
212do not need a reactive query scanning the full table.
213 
214Use it for leaderboards, totals, "X items" badges, or any stat that would
215otherwise require scanning many rows reactively.
216 
217If the aggregate component is not appropriate, prefer point-in-time reads for
218global stats, or precomputed summary rows updated by a cron or trigger, over
219reactive queries that scan large tables.
220 
221### 6. Narrow query read sets
222 
223Queries that return less data and touch fewer documents invalidate less often.
224 
225```ts
226// Bad: returns all fields, invalidates on any field change
227export const list = query({
228  handler: async (ctx) => {
229    return await ctx.db.query("projects").collect();
230  },
231});
232```
233 
234```ts
235// Good: use a digest table with only the fields the list needs
236export const listDigests = query({
237  handler: async (ctx) => {
238    return await ctx.db.query("projectDigests").collect();
239  },
240});
241```
242 
243Writes to fields not in the digest table do not invalidate the digest query.
244 
245### 7. Remove `Date.now()` from queries
246 
247Using `Date.now()` inside a query defeats Convex's query cache. The cache is
248invalidated frequently to avoid showing stale time-dependent results, which
249increases database work even when the underlying data has not changed.
250 
251```ts
252// Bad: Date.now() defeats query caching and causes frequent re-evaluation
253const releasedPosts = await ctx.db
254  .query("posts")
255  .withIndex("by_released_at", (q) => q.lte("releasedAt", Date.now()))
256  .take(100);
257```
258 
259```ts
260// Good: use a boolean field updated by a scheduled function
261const releasedPosts = await ctx.db
262  .query("posts")
263  .withIndex("by_is_released", (q) => q.eq("isReleased", true))
264  .take(100);
265```
266 
267If the query must compare against a time value, pass it as an explicit argument
268from the client and round it to a coarse interval (e.g. the most recent minute)
269so requests within that window share the same cache entry.
270 
271### 8. Consider pagination strategy
272 
273For long lists where users scroll through many pages:
274 
275- If the data does not need live updates, use point-in-time fetching with manual
276  "load more"
277- If it does need live updates, accept the subscription cost but limit the
278  number of loaded pages
279- Consider whether older pages can be unloaded as the user scrolls forward
280 
281### 9. Separate backend cost from UI churn
282 
283If the main problem is loading flash or UI churn when query arguments change,
284stabilizing the reactive UI behavior may be better than replacing reactivity
285altogether.
286 
287Treat this as a UX problem first when:
288 
289- the underlying query is already reasonably cheap
290- the complaint is flicker, loading flashes, or re-render churn
291- live updates are still desirable once fresh data arrives
292 
293## Verification
294 
2951. Subscription count in dashboard is lower for the affected pages
2962. UI responsiveness has improved
2973. React profiling shows fewer unnecessary re-renders
2984. Surfaces that do not need live updates are not paying for persistent
299   subscriptions unnecessarily
3005. Sibling pages with similar patterns were updated consistently
301