Queries

Convex queries — reactive read functions that auto-update on the client when underlying data changes.

Queries are read-only, reactive functions. Clients subscribe via useQuery; updates push automatically when data changes.

Anatomy

convex/tasks.ts

import { query } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: { teamId: v.id("teams") },
  handler: async (ctx, { teamId }) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_team", (q) => q.eq("teamId", teamId))
      .collect();
  },
});

Three things:

• args validators (Convex enforces and types).
• ctx.db for database access.
• ctx.auth for the calling user’s identity.

On the client

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

const tasks = useQuery(api.tasks.list, { teamId });
// `tasks` is `undefined` while loading, then the array.
// Updates automatically when any task in this team changes.

Patterns

Filter by index

.withIndex("by_team_and_status",
  q => q.eq("teamId", teamId).eq("status", "open"))

Sort and limit

.order("desc")     // by _creationTime
.take(20)

Conditional reads

handler: async (ctx, { id }) => {
  const task = await ctx.db.get(id);
  if (!task) return null;
  // ...
}

Auth scoping

const user = await ctx.auth.getUserIdentity();
if (!user) throw new Error("Not signed in");

return await ctx.db
  .query("tasks")
  .withIndex("by_owner", q => q.eq("ownerId", user.subject))
  .collect();

Limits

• Cannot mutate the database.
• Cannot call third-party APIs — use actions for that.
• 10-second timeout per call.

Tips

Always use .withIndex() over .filter() for non-tiny tables. .filter() walks every row.

Subscribe close to consumption. A useQuery near the rendering component re-runs only when its data changes — better than passing data through five levels of props.

Related

Schema

Define tables and indexes.

Mutations

Write data.

Indexes

Make queries fast.