> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript convex/tasks.ts theme={null}
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

```tsx theme={null}
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

<Tabs>
  <Tab title="Filter by index">
    ```typescript theme={null}
    .withIndex("by_team_and_status",
      q => q.eq("teamId", teamId).eq("status", "open"))
    ```
  </Tab>

  <Tab title="Sort and limit">
    ```typescript theme={null}
    .order("desc")     // by _creationTime
    .take(20)
    ```
  </Tab>

  <Tab title="Conditional reads">
    ```typescript theme={null}
    handler: async (ctx, { id }) => {
      const task = await ctx.db.get(id);
      if (!task) return null;
      // ...
    }
    ```
  </Tab>

  <Tab title="Auth scoping">
    ```typescript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Limits

* **Cannot mutate** the database.
* **Cannot call third-party APIs** — use [actions](/convex/actions) for that.
* **10-second timeout** per call.

## Tips

<Tip>
  **Always use `.withIndex()` over `.filter()` for non-tiny tables.** `.filter()` walks every row.
</Tip>

<Tip>
  **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.
</Tip>

## Related

<CardGroup cols={3}>
  <Card title="Schema" icon="database" href="/convex/schema">
    Define tables and indexes.
  </Card>

  <Card title="Mutations" icon="pencil" href="/convex/mutations">
    Write data.
  </Card>

  <Card title="Indexes" icon="zap" href="/convex/indexes">
    Make queries fast.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.