1# Function Budget
2 
3Use these rules when functions are hitting execution limits, transaction size
4errors, or returning excessively large payloads to the client.
5 
6## Core Principle
7 
8Convex functions run inside transactions with budgets for time, reads, and
9writes. Staying well within these limits is not just about avoiding errors, it
10reduces latency and contention.
11 
12## Limits to Know
13 
14These are the current values from the
15[Convex limits docs](https://docs.convex.dev/production/state/limits). Check
16that page for the latest numbers.
17 
18| Resource                          | Limit                                                 |
19| --------------------------------- | ----------------------------------------------------- |
20| Query/mutation execution time     | 1 second (user code only, excludes DB operations)     |
21| Action execution time             | 10 minutes                                            |
22| Data read per transaction         | 16 MiB                                                |
23| Data written per transaction      | 16 MiB                                                |
24| Documents scanned per transaction | 32,000 (includes documents filtered out by `.filter`) |
25| Index ranges read per transaction | 4,096 (each `db.get` and `db.query` call)             |
26| Documents written per transaction | 16,000                                                |
27| Individual document size          | 1 MiB                                                 |
28| Function return value size        | 16 MiB                                                |
29 
30## Symptoms
31 
32- "Function execution took too long" errors
33- "Transaction too large" or read/write set size errors
34- Slow queries that read many documents
35- Client receiving large payloads that slow down page load
36- `npx convex insights --details` showing high bytes read
37 
38## Common Causes
39 
40### Unbounded collection
41 
42A query that calls `.collect()` on a table without a reasonable limit. As the
43table grows, the query reads more and more documents.
44 
45### Large document reads on hot paths
46 
47Reading documents with large fields (rich text, embedded media references, long
48arrays) when only a small subset of the data is needed for the current view.
49 
50### Mutation doing too much work
51 
52A single mutation that updates hundreds of documents, backfills data, or
53rebuilds derived state in one transaction.
54 
55### Returning too much data to the client
56 
57A query returning full documents when the client only needs a few fields.
58 
59## Fix Order
60 
61### 1. Bound your reads
62 
63Never `.collect()` without a limit on a table that can grow unbounded.
64 
65```ts
66// Bad: unbounded read, breaks as the table grows
67const messages = await ctx.db.query("messages").collect();
68```
69 
70```ts
71// Good: paginate or limit
72const messages = await ctx.db
73  .query("messages")
74  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
75  .order("desc")
76  .take(50);
77```
78 
79### 2. Read smaller shapes
80 
81If the list page only needs title, author, and date, do not read full documents
82with rich content fields.
83 
84Use digest or summary tables for hot list pages. See `hot-path-rules.md` for the
85digest table pattern.
86 
87### 3. Break large mutations into batches
88 
89If a mutation needs to update hundreds of documents, split it into a
90self-scheduling chain.
91 
92```ts
93// Bad: one mutation updating every row
94export const backfillAll = internalMutation({
95  handler: async (ctx) => {
96    const docs = await ctx.db.query("items").collect();
97    for (const doc of docs) {
98      await ctx.db.patch(doc._id, { newField: computeValue(doc) });
99    }
100  },
101});
102```
103 
104```ts
105// Good: cursor-based batch processing
106export const backfillBatch = internalMutation({
107  args: { cursor: v.optional(v.string()), batchSize: v.optional(v.number()) },
108  handler: async (ctx, args) => {
109    const batchSize = args.batchSize ?? 100;
110    const result = await ctx.db
111      .query("items")
112      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
113 
114    for (const doc of result.page) {
115      if (doc.newField === undefined) {
116        await ctx.db.patch(doc._id, { newField: computeValue(doc) });
117      }
118    }
119 
120    if (!result.isDone) {
121      await ctx.scheduler.runAfter(0, internal.items.backfillBatch, {
122        cursor: result.continueCursor,
123        batchSize,
124      });
125    }
126  },
127});
128```
129 
130### 4. Move heavy work to actions
131 
132Queries and mutations run inside Convex's transactional runtime with strict
133budgets. If you need to do CPU-intensive computation, call external APIs, or
134process large files, use an action instead.
135 
136Actions run outside the transaction and can call mutations to write results
137back.
138 
139```ts
140// Bad: heavy computation inside a mutation
141export const processUpload = mutation({
142  handler: async (ctx, args) => {
143    const result = expensiveComputation(args.data);
144    await ctx.db.insert("results", result);
145  },
146});
147```
148 
149```ts
150// Good: action for heavy work, mutation for the write
151export const processUpload = action({
152  handler: async (ctx, args) => {
153    const result = expensiveComputation(args.data);
154    await ctx.runMutation(internal.results.store, { result });
155  },
156});
157```
158 
159### 5. Trim return values
160 
161Only return what the client needs. If a query fetches full documents but the
162component only renders a few fields, map the results before returning.
163 
164```ts
165// Bad: returns full documents including large content fields
166export const list = query({
167  handler: async (ctx) => {
168    return await ctx.db.query("articles").take(20);
169  },
170});
171```
172 
173```ts
174// Good: project to only the fields the client needs
175export const list = query({
176  handler: async (ctx) => {
177    const articles = await ctx.db.query("articles").take(20);
178    return articles.map((a) => ({
179      _id: a._id,
180      title: a.title,
181      author: a.author,
182      createdAt: a._creationTime,
183    }));
184  },
185});
186```
187 
188### 6. Replace `ctx.runQuery` and `ctx.runMutation` with helper functions
189 
190Inside queries and mutations, `ctx.runQuery` and `ctx.runMutation` have overhead
191compared to calling a plain TypeScript helper function. They run in the same
192transaction but pay extra per-call cost.
193 
194```ts
195// Bad: unnecessary overhead from ctx.runQuery inside a mutation
196export const createProject = mutation({
197  handler: async (ctx, args) => {
198    const user = await ctx.runQuery(api.users.getCurrentUser);
199    await ctx.db.insert("projects", { ...args, ownerId: user._id });
200  },
201});
202```
203 
204```ts
205// Good: plain helper function, no extra overhead
206export const createProject = mutation({
207  handler: async (ctx, args) => {
208    const user = await getCurrentUser(ctx);
209    await ctx.db.insert("projects", { ...args, ownerId: user._id });
210  },
211});
212```
213 
214Exception: components require `ctx.runQuery`/`ctx.runMutation`. Use them there,
215but prefer helpers everywhere else.
216 
217### 7. Avoid unnecessary `runAction` calls
218 
219`runAction` from within an action creates a separate function invocation with
220its own memory and CPU budget. The parent action just sits idle waiting. Replace
221with a plain TypeScript function call unless you need a different runtime (e.g.
222calling Node.js code from the Convex runtime).
223 
224```ts
225// Bad: runAction overhead for no reason
226export const processItems = action({
227  handler: async (ctx, args) => {
228    for (const item of args.items) {
229      await ctx.runAction(internal.items.processOne, { item });
230    }
231  },
232});
233```
234 
235```ts
236// Good: plain function call
237export const processItems = action({
238  handler: async (ctx, args) => {
239    for (const item of args.items) {
240      await processOneItem(ctx, { item });
241    }
242  },
243});
244```
245 
246## Verification
247 
2481. No function execution or transaction size errors
2492. `npx convex insights --details` shows reduced bytes read
2503. Large mutations are batched and self-scheduling
2514. Client payloads are reasonably sized for the UI they serve
2525. `ctx.runQuery`/`ctx.runMutation` in queries and mutations replaced with
253   helpers where possible
2546. Sibling functions with similar patterns were checked
255