convex-functions

Define the query with the query function from ./_generated/server, passing an object with args using v validators, a returns validator, and a handler. Use ctx.db.query with withIndex for indexed lookups and collect or take for results.

Queries are read-only, cached, and reactive. Mutations perform transactional database writes. Actions can call external APIs but access the database only indirectly through runQuery and runMutation.

No, mutations and queries cannot make network requests. Use an action to call the external API, then persist results by invoking a mutation through ctx.runMutation, typically an internalMutation for sensitive updates.

Define routes in convex/http.ts using httpRouter and httpAction. Each route specifies a path and method, and the handler receives the request, verifies signatures, and calls internal mutations via ctx.runMutation.

Convex actions run in a custom runtime by default without Node.js built-ins. Add "use node"; at the top of the file to run the action in the Node.js runtime with access to Node APIs.

Use internalMutation, internalQuery, and internalAction for sensitive logic that must not be exposed to clients, such as credit adjustments or webhook handlers. They are only callable from other Convex functions or scheduled jobs.