English Vocabulary for Convex Backend Developers

Convex is a backend-as-a-service platform that introduces its own precise vocabulary for describing how data flows, how functions are structured, and how real-time updates work. If you’re working on a team that uses Convex, you’ll encounter these terms in code reviews, architecture discussions, and technical documentation. This post covers the essential Convex vocabulary and how to use it naturally in English professional conversations.

Key Vocabulary

Mutation A Convex function that writes to the database. Mutations are transactional, automatically retried on failure, and run server-side. The equivalent of a POST/PUT/DELETE in a REST API, but with built-in transactional guarantees. Example: “I wrote a Convex mutation to handle the checkout flow — it updates the order status and decrements the inventory count in a single transaction.”

Query A Convex function that reads from the database. Queries are reactive by default when used with the useQuery hook — they automatically re-run when the underlying data changes. Example: “The product list is powered by a Convex query that subscribes to the products table — it updates in real time without polling.”

Action A Convex function that can call external APIs, services, or perform side effects that queries and mutations cannot. Actions are not transactional and can be long-running. Use them for things like sending emails, calling Stripe, or generating AI completions. Example: “I wrote an action to generate the report — it calls our analytics API and writes the result back to the database via a mutation.”

useQuery hook (real-time subscription) The React hook for subscribing to a Convex query from the client. When the underlying data changes on the server, all clients subscribed to that query automatically receive the update — no polling, no WebSocket management. Example: “Subscribe to the chat messages with useQuery(api.messages.list) — the hook handles the real-time subscription automatically.”

Scheduler (runAfter / runAt) Convex’s built-in mechanism for scheduling functions to run in the future. runAfter delays execution by a duration; runAt schedules execution at a specific timestamp. Useful for delayed notifications, retries, or async workflows. Example: “I used runAfter to schedule a follow-up email 24 hours after signup — it’s cleaner than maintaining a separate cron job.”

Crons Convex supports cron-style scheduled functions that run on a recurring schedule. Defined in a crons.ts file, they run reliably without external infrastructure. Example: “We have a Convex cron that runs every night at midnight to aggregate the daily analytics and write summary records to the database.”

File storage Convex’s built-in file storage system, integrated with the Convex database. Files are stored and referenced by ID, and access can be controlled through Convex functions. Example: “Profile photos are uploaded through Convex file storage — we store the file ID in the user record and generate a signed URL on request.”

Vector search Convex’s built-in vector similarity search, which stores and queries high-dimensional embeddings alongside regular data. Enables semantic search and AI-powered retrieval without a separate vector database. Example: “We’re using Convex vector search to implement semantic document search — the embeddings are generated by an action and stored in the same database as the document metadata.”

Convex Auth Convex’s first-party authentication solution that integrates natively with the Convex backend. Handles user sessions, OAuth providers, and JWT validation without requiring a separate auth service. Example: “We switched from a third-party auth provider to Convex Auth — it simplified our setup significantly since auth state is now a first-class citizen in the Convex data model.”

Common Phrases and Collocations

“Write a Convex mutation” The standard action phrase for creating a write function in Convex. Example: “Can you write a Convex mutation to handle the friend request flow? It needs to create the request record and send a notification.”

“Subscribe to data with useQuery” Describes the client-side pattern for real-time data. Example: “Subscribe to data with useQuery instead of fetching manually — you’ll get real-time updates for free.”

“Schedule a background job” Using the Convex scheduler to defer work. Example: “Let’s schedule a background job to send the invoice email after the payment mutation succeeds — use runAfter with a 5-second delay.”

“Call an action for external integrations” The standard guidance for when to reach for an action vs. a mutation. Example: “Anything that touches Stripe or sends an email should call an action — mutations are for database writes only.”

“The query reactively updates” Describes Convex’s automatic real-time behavior. Example: “You don’t need to refresh the page — the query reactively updates whenever the task list changes.”

Practical Sentences to Practice

1. “I wrote a mutation to handle the like button — it increments the like count and creates a notification record in a single atomic operation.”
2. “The dashboard uses three useQuery subscriptions — they all update in real time without any additional code on our end.”
3. “We use a Convex action to generate AI summaries because it needs to call the OpenAI API, which isn’t allowed in a mutation.”
4. “The retry logic is handled by runAfter — if the first attempt fails, the action schedules itself to retry in 60 seconds.”
5. “We store user avatars in Convex file storage and reference them by file ID in the user profile document.”

Common Mistakes to Avoid

Calling external APIs inside a mutation Mutations in Convex are transactional and should only write to the database. Calling external APIs inside a mutation will cause an error. Use an action instead. Instead of: “I’ll call the Stripe API inside the mutation.” Say: “I’ll create a mutation to record the payment intent, and then trigger an action to call the Stripe API.”

Confusing “query” (Convex) with “database query” (SQL) In Convex, a “query” is a specific type of server function with reactivity and caching properties. It’s not the same as writing a SQL SELECT statement. Be explicit to avoid confusion. Say: “I’m writing a Convex query function — it’s different from a raw database query. It subscribes clients to live updates.”

Polling instead of using useQuery Teams migrating from REST often add polling intervals out of habit. With Convex, this is unnecessary and adds load. Instead of: “I’ll poll the endpoint every 5 seconds for updates.” Say: “Use useQuery — Convex pushes updates to the client automatically. No polling needed.”

Summary

Convex has a precise vocabulary that reflects its architecture: mutations for writes, queries for reactive reads, actions for side effects, schedulers for deferred work. Understanding these distinctions — and being able to discuss them in English — makes you a more effective collaborator on Convex-powered teams. When you can say “write a mutation for this, trigger an action for the email, and subscribe the UI with useQuery,” you’re speaking the language of the Convex ecosystem fluently.