Understanding Convex Functions


This architecture layout describes the roles and interactions of Convex functions: Queries, Mutations, and Actions within a web application. Convex streamlines backend development by providing these functions to interact with the database and external services efficiently.


1. Queries

  • Purpose: Retrieve data from the database without modifying it.
  • Use Cases: Displaying user information, listing blog posts, fetching application settings.
  • Interaction: Directly communicates with the database to fetch data and presents it to the frontend.

2. Mutations

  • Purpose: Update, insert, or delete data in the database.
  • Use Cases: Creating a new user account, updating a blog post, deleting a comment.
  • Interaction: Performs write operations to the database and may also fetch updated data to return to the frontend.

3. Actions

  • Purpose: Interact with external APIs or services.
  • Use Cases: Sending emails, processing payments, integrating third-party APIs.
  • Interaction: Can invoke Queries and Mutations to read from or write to the database based on external API responses.


  1. Frontend Request: The user interacts with the frontend, triggering a request for data retrieval, update, or external service interaction.

  2. Convex Function Invocation:

    • For data retrieval, a Query is invoked, fetching data from the database and returning it to the frontend.
    • For data modification, a Mutation is invoked, updating the database and optionally returning the updated data to the frontend.
    • For external interactions, an Action is invoked, which may call external APIs and use Queries/Mutations as needed.
  3. Response Handling: The frontend receives the data or confirmation of the action and updates the UI accordingly.

Example Flow

  1. A user submits a form to update their profile.
  2. The frontend invokes a Mutation function to update the user's profile in the database.
  3. Upon successful update, the Mutation may fetch and return the updated user profile.
  4. The frontend updates the UI to reflect the updated profile information.


Convex functions provide a structured, efficient way to handle data management and external interactions in web applications, enabling developers to focus on building user-centric features.

Published: Jan 25, 2024
Get the latest from me on my newsletter! I'll share resources I've come across and keep you up to date on my latest projects.