1# Hot Path Rules
2 
3Use these rules when the top-level workflow points to read amplification,
4denormalization, index rollout, reactive query cost, or invalidation-heavy
5writes.
6 
7## Contents
8 
9- Core Principle
10- Consistency Rule
11- 1. Push Filters To Storage (indexes, migration rule, redundant indexes)
12- 2. Minimize Data Sources (denormalization, fallback rule)
13- 3. Minimize Row Size (digest tables)
14- 4. Skip No-Op Writes
15- 5. Match Consistency To Read Patterns (high-read/low-write,
16     high-read/high-write)
17- Convex-Specific Notes (reactive queries, point-in-time reads, triggers,
18  aggregates, backfills)
19- Verification
20 
21## Core Principle
22 
23Every byte read or written multiplies with concurrency.
24 
25Think:
26 
27`cost x calls_per_second x 86400`
28 
29In Convex, every write can also fan out into reactive invalidation, replication
30work, and downstream sync.
31 
32## Consistency Rule
33 
34If you fix a hot-path pattern for one function, audit sibling functions touching
35the same tables for the same pattern.
36 
37Do this especially for:
38 
39- multiple list queries over the same table
40- multiple writers to the same table
41- public browse and search queries over the same records
42- helper functions reused by more than one endpoint
43 
44## 1. Push Filters To Storage
45 
46Both JavaScript `.filter()` and the Convex query `.filter()` method after a DB
47scan mean you already paid for the read. The Convex `.filter()` method has the
48same performance as filtering in JS, it does not push the predicate to the
49storage layer. Only `.withIndex()` and `.withSearchIndex()` actually reduce the
50documents scanned.
51 
52Prefer:
53 
54- `withIndex(...)`
55- `.withSearchIndex(...)` for text search
56- narrower tables
57- summary tables
58 
59before accepting a scan-plus-filter pattern.
60 
61```ts
62// Bad: scans then filters in JavaScript
63export const listOpen = query({
64  args: {},
65  handler: async (ctx) => {
66    const tasks = await ctx.db.query("tasks").collect();
67    return tasks.filter((task) => task.status === "open");
68  },
69});
70```
71 
72```ts
73// Also bad: Convex .filter() does not push to storage either
74export const listOpen = query({
75  args: {},
76  handler: async (ctx) => {
77    return await ctx.db
78      .query("tasks")
79      .filter((q) => q.eq(q.field("status"), "open"))
80      .collect();
81  },
82});
83```
84 
85```ts
86// Good: use an index so storage does the filtering
87export const listOpen = query({
88  args: {},
89  handler: async (ctx) => {
90    return await ctx.db
91      .query("tasks")
92      .withIndex("by_status", (q) => q.eq("status", "open"))
93      .collect();
94  },
95});
96```
97 
98### Migration rule for indexes
99 
100New indexes on partially backfilled fields can create correctness bugs during
101rollout.
102 
103Important Convex detail:
104 
105`undefined !== false`
106 
107If an older document is missing a field entirely, it will not match a compound
108index entry that expects `false`.
109 
110Do not trust old comments saying a field is "not backfilled" or "already
111backfilled". Verify.
112 
113If correctness depends on handling old and new states during rollout, do not
114improvise a partial-backfill workaround in the hot path. Use a migration-safe
115rollout and consult `skills/convex-migration-helper/SKILL.md`.
116 
117```ts
118// Bad: optional booleans can miss older rows where the field is undefined
119const projects = await ctx.db
120  .query("projects")
121  .withIndex("by_archived_and_updated", (q) => q.eq("isArchived", false))
122  .order("desc")
123  .take(20);
124```
125 
126```ts
127// Good: switch hot-path reads only after the rollout is migration-safe
128// See the migration helper skill for dual-read / backfill / cutover patterns.
129```
130 
131### Check for redundant indexes
132 
133Indexes like `by_foo` and `by_foo_and_bar` are usually redundant. You only need
134`by_foo_and_bar`, since you can query it with just the `foo` condition and omit
135`bar`. Extra indexes add storage cost and write overhead on every insert, patch,
136and delete.
137 
138```ts
139// Bad: two indexes where one would do
140defineTable({ team: v.id("teams"), user: v.id("users") })
141  .index("by_team", ["team"])
142  .index("by_team_and_user", ["team", "user"]);
143```
144 
145```ts
146// Good: single compound index serves both query patterns
147defineTable({ team: v.id("teams"), user: v.id("users") }).index(
148  "by_team_and_user",
149  ["team", "user"],
150);
151```
152 
153Exception: `.index("by_foo", ["foo"])` is really an index on `foo` +
154`_creationTime`, while `.index("by_foo_and_bar", ["foo", "bar"])` is on `foo` +
155`bar` + `_creationTime`. If you need results sorted by `foo` then
156`_creationTime`, you need the single-field index because the compound one would
157sort by `bar` first.
158 
159## 2. Minimize Data Sources
160 
161Trace every read.
162 
163If a function resolves a foreign key for a tiny display field and a denormalized
164copy already exists, prefer the denormalized field on the hot path.
165 
166### When to denormalize
167 
168Denormalize when all of these are true:
169 
170- the path is hot
171- the joined document is much larger than the field you need
172- many readers are paying that join cost repeatedly
173 
174Useful mental model:
175 
176`join_cost = rows_per_page x foreign_doc_size x pages_per_second`
177 
178Small-table joins are often fine. Large-document joins for tiny fields on hot
179list pages are usually not.
180 
181### Fallback rule
182 
183Denormalized data is an optimization. Live data is the correctness path.
184 
185Rules:
186 
187- If the denormalized field is missing or null, fall back to the live read
188- Do not show placeholders instead of falling back
189- In lookup maps, only include fully populated entries
190 
191```ts
192// Bad: missing denormalized data becomes a placeholder and blocks correctness
193const ownerName = project.ownerName ?? "Unknown owner";
194```
195 
196```ts
197// Good: denormalized data is an optimization, not the only source of truth
198const ownerName =
199  project.ownerName ?? (await ctx.db.get(project.ownerId))?.name ?? null;
200```
201 
202Bad lookup map pattern:
203 
204```ts
205const ownersById = {
206  [project.ownerId]: { ownerName: null },
207};
208```
209 
210That blocks fallback because the map says "I have data" when it does not.
211 
212Good lookup map pattern:
213 
214```ts
215const ownersById =
216  project.ownerName !== undefined && project.ownerName !== null
217    ? { [project.ownerId]: { ownerName: project.ownerName } }
218    : {};
219```
220 
221### No denormalized copy yet
222 
223Prefer adding fields to an existing summary, companion, or digest table instead
224of bloating the primary hot-path table.
225 
226If introducing the new field or table requires a staged rollout, backfill, or
227old/new-shape handling, use the migration helper skill for the rollout plan.
228 
229Rollout order:
230 
2311. Update schema
2322. Update write path
2333. Backfill
2344. Switch read path
235 
236## 3. Minimize Row Size
237 
238Hot list pages should read the smallest document shape that still answers the
239UI.
240 
241Prefer summary or digest tables over full source tables when:
242 
243- the list page only needs a subset of fields
244- source documents are large
245- the query is high volume
246 
247An 800 byte summary row is materially cheaper than a 3 KB full document on a hot
248page.
249 
250Digest tables are a tradeoff, not a default:
251 
252- Worth it when the path is clearly hot, the source rows are much larger than
253  the UI needs, or many readers are repeatedly paying the same join and payload
254  cost
255- Probably not worth it when an indexed read on the source table is already
256  cheap enough, the table is still small, or the extra write and migration
257  complexity would dominate the benefit
258 
259```ts
260// Bad: list page reads source docs, then joins owner data per row
261const projects = await ctx.db
262  .query("projects")
263  .withIndex("by_public", (q) => q.eq("isPublic", true))
264  .collect();
265```
266 
267```ts
268// Good: list page reads the smaller digest shape first
269const projects = await ctx.db
270  .query("projectDigests")
271  .withIndex("by_public_and_updated", (q) => q.eq("isPublic", true))
272  .order("desc")
273  .take(20);
274```
275 
276## 4. Isolate Frequently-Updated Fields
277 
278Convex already no-ops unchanged writes. The invalidation problem here is real
279writes hitting documents that many queries subscribe to.
280 
281Move high-churn fields like `lastSeen`, counters, presence, or ephemeral status
282off widely-read documents when most readers do not need them.
283 
284Apply this across sibling writers too. Splitting one write path does not help
285much if three other mutations still update the same widely-read document.
286 
287```ts
288// Bad: every presence heartbeat invalidates subscribers to the whole profile
289await ctx.db.patch(user._id, {
290  name: args.name,
291  avatarUrl: args.avatarUrl,
292  lastSeen: Date.now(),
293});
294```
295 
296```ts
297// Good: keep profile reads stable, move heartbeat updates to a separate document
298await ctx.db.patch(user._id, {
299  name: args.name,
300  avatarUrl: args.avatarUrl,
301});
302 
303await ctx.db.patch(presence._id, {
304  lastSeen: Date.now(),
305});
306```
307 
308## 5. Match Consistency To Read Patterns
309 
310Choose read strategy based on traffic shape.
311 
312### High-read, low-write
313 
314Examples:
315 
316- public browse pages
317- search results
318- landing pages
319- directory listings
320 
321Prefer:
322 
323- point-in-time reads where appropriate
324- explicit refresh
325- local state for pagination
326- caching where appropriate
327 
328Do not treat subscriptions as automatically wrong here. Prefer point-in-time
329reads only when the product does not need live freshness and the reactive cost
330is material. See `subscription-cost.md` for detailed patterns.
331 
332### High-read, high-write
333 
334Examples:
335 
336- collaborative editors
337- live dashboards
338- presence-heavy views
339 
340Reactive queries may be worth the ongoing cost.
341 
342## Convex-Specific Notes
343 
344### Reactive queries
345 
346Every `ctx.db.get()` and `ctx.db.query()` contributes to the invalidation set
347for the query.
348 
349On the client:
350 
351- `useQuery` creates a live subscription
352- `usePaginatedQuery` creates a live subscription per page
353 
354For low-freshness flows, consider a point-in-time read instead of a live
355subscription only when the product does not need updates pushed automatically.
356 
357### Point-in-time reads
358 
359Framework helpers, server-rendered fetches, or one-shot client reads can avoid
360ongoing subscription cost when live updates are not useful.
361 
362Use them for:
363 
364- aggregate snapshots
365- reports
366- low-churn listings
367- pages where explicit refresh is fine
368 
369### Triggers and fan-out
370 
371Triggers fire on every write, including writes that did not materially change
372the document.
373 
374When a write exists only to keep derived state in sync:
375 
376- diff before patching
377- move expensive non-blocking work to `ctx.scheduler.runAfter` when appropriate
378 
379### Aggregates
380 
381Reactive global counts invalidate frequently on busy tables.
382 
383Prefer:
384 
385- one-shot aggregate fetches
386- periodic recomputation
387- precomputed summary rows
388 
389for global stats that do not need live updates every second.
390 
391### Backfills
392 
393For larger backfills, use cursor-based, self-scheduling `internalMutation` jobs
394or the migrations component.
395 
396Deploy code that can handle both states before running the backfill.
397 
398During the gap:
399 
400- writes should populate the new shape
401- reads should fall back safely
402 
403## Verification
404 
405Before closing the audit, confirm:
406 
4071. Same results as before, no dropped records
4082. The removed table or lookup is no longer in the hot-path read set
4093. Tests or validation cover fallback behavior
4104. Migration safety is preserved while fields or indexes are unbackfilled
4115. Sibling functions were fixed consistently
412