Interface: GenericQueryCtx<DataModel>

server.GenericQueryCtx

A set of services for use within Convex query functions.

The query context is passed as the first argument to any Convex query function run on the server. Queries are read-only, they can read from the database but cannot write. They are also reactive, when used with useQuery on the client, the result automatically updates when data changes.

You should generally use the QueryCtx type from "./_generated/server".

Example

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

export const listTasks = query({
  args: {},
  returns: v.array(v.object({
    _id: v.id("tasks"),
    _creationTime: v.number(),
    text: v.string(),
    completed: v.boolean(),
  })),
  handler: async (ctx, args) => {
    // ctx.db: read-only database access
    return await ctx.db.query("tasks").order("desc").take(100);
  },
});

Type parameters

Name	Type
DataModel	extends GenericDataModel

Properties

db

• db: GenericDatabaseReader<DataModel>

A utility for reading data in the database.

Use ctx.db.get(table, id) to fetch a single document by ID, or ctx.db.query("tableName") to query multiple documents with filtering and ordering. Queries are read-only, no write methods are available.

Defined in

server/registration.ts:209

---

auth

• auth: Auth

Information about the currently authenticated user.

Call await ctx.auth.getUserIdentity() to get the current user's identity, or null if the user is not authenticated.

Defined in

server/registration.ts:217

---

storage

• storage: StorageReader

A utility for reading files in storage.

Use ctx.storage.getUrl(storageId) to get a URL for a stored file.

Defined in

server/registration.ts:224

---

runQuery

• runQuery: <Query>(query: Query, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>

Type declaration

▸ <Query>(query, ...args): Promise<FunctionReturnType<Query>>

Call a query function within the same transaction.

The query runs within the same read snapshot. Requires a FunctionReference (e.g., api.myModule.myQuery or internal.myModule.myQuery).

NOTE: Often you can extract shared logic into a helper function instead. runQuery incurs overhead of running argument and return value validation, and creating a new isolated JS context.

Type parameters

Name	Type
Query	extends FunctionReference<"query", "public" | "internal">

Parameters

Name	Type
query	Query
...args	OptionalRestArgs<Query>

Returns

Promise<FunctionReturnType<Query>>

Defined in

server/registration.ts:237