Query vs Mutation vs Action
Query = read. Mutation = write to your database. Action = talk to the outside world.
Mental model
Plain English
Three buckets. Queries only read — they're cached and live. Mutations write to your own database inside a transaction. Actions are for anything non-deterministic: sending emails, calling Stripe, hitting an LLM. Actions can call mutations when they're done.
Query = looking at the menu. Mutation = the waiter writing in the order book. Action = calling the supplier to restock — you can't undo it, so you don't do it inside the order book.
list tasks = query. addTask = mutation. sendVendorEmail = action (calls Resend, then writes a log via a mutation).
listConversations = query. assignAgent = mutation. sendWhatsAppMessage = action (calls WhatsApp API, then writes the outbound message via a mutation).
Go deeper
Read, write-own-db, call-outside.
Common mistakes
- Calling fetch() from a mutation — it will break the transaction.
- Using an action to do simple writes — slower and not transactional.
- Putting the action's side-effect inside the mutation 'just to keep it together'.
AI-agent trap
Summary
Queries are deterministic — same input, same output, cacheable. Mutations are transactional database writes. Actions are non-transactional and can do anything (fetch, send), but they must call a mutation to persist.