Services

Confect exposes Effect services that wrap Convex platform capabilities. These services are generated in confect/_generated/services.ts and are available when implementing your Confect functions and HTTP endpoint handlers.

import {
  ActionRunner,
  Auth,
  DatabaseReader,
  DatabaseWriter,
  ExecutionMetadata,
  MutationRunner,
  QueryRunner,
  RequestMetadata,
  Scheduler,
  Storage,
  TransactionMetadata,
  VectorSearch,
} from "./_generated/services";

Database

`DatabaseReader`

Read documents from the database.

`DatabaseWriter`

Insert, edit, and delete documents from the database.

Function invocation

`QueryRunner`

Run Confect queries with runQuery(ref, args, options?):

import * as Effect from "effect/Effect";
import refs from "./_generated/refs";
import { QueryRunner } from "./_generated/services";

const firstNote = Effect.gen(function* () {
  const { runQuery } = yield* QueryRunner;
  return yield* runQuery(refs.public.notes_and_random.notes.getFirst, {});
});

The transactionLimits option is available inside queries and mutations. The useStaleSnapshot option is available only inside mutations, even when you pass false. Actions and HTTP handlers can call runQuery without these options. See Transaction controls.

`MutationRunner`

Run Confect mutations with runMutation(ref, args, options?). Obtain the method with const { runMutation } = yield* MutationRunner. The transactionLimits option is available only inside mutations. Actions and HTTP handlers can call runMutation without this option.

`ActionRunner`

Run Confect actions with runAction(ref, args). Obtain the method with const { runAction } = yield* ActionRunner. This method has no options parameter. For all three runners, args is optional when the referenced function takes no arguments. Pass {} as the second argument when supplying options to a no-argument query or mutation.

Transaction controls

Pass transaction options to a runner method to control a nested call, not the entire enclosing handler:

import * as Effect from "effect/Effect";
import refs from "./_generated/refs";
import { QueryRunner } from "./_generated/services";

const boundedRead = Effect.gen(function* () {
  const { runQuery } = yield* QueryRunner;
  return yield* runQuery(
    refs.public.notes_and_random.notes.getFirst,
    {},
    { transactionLimits: { documentsRead: 100 } },
  );
});

transactionLimits accepts Convex’s TransactionLimits fields, including documentsRead, bytesRead, and databaseQueries. Each field sets a maximum for the nested call. Convex caps these values at its platform transaction limits. Use TransactionMetadata.getMetrics() to inspect usage and remaining limits.

Method and options	Available in
`runQuery(ref, args, { transactionLimits })`	Queries and mutations
`runQuery(ref, args, { useStaleSnapshot })`, optionally with `transactionLimits`	Mutations
`runMutation(ref, args, { transactionLimits })`	Mutations

In actions and HTTP handlers, omit options or pass undefined rather than an empty options object. useStaleSnapshot: true reads from a recent database snapshot that might not be up to date when the mutation commits. Passing useStaleSnapshot: false still requires a mutation context.

Stale snapshots can introduce race conditions. Use them only when stale reads are safe for your operation, such as reading immutable records from an append-only table. Prefer ordinary reads otherwise.

Storage

`Storage`

Use one service for file storage. The available operations depend on the function’s context:

Operations	Available in
`getUrl`	Queries, mutations, actions, and HTTP actions
`generateUploadUrl`, `delete`	Mutations, actions, and HTTP actions
`get`, `store`	Actions and HTTP actions

See Storage for examples and return types.

StorageWriter and StorageActionWriter may appear in operation requirements. Confect supplies them automatically; new code only needs to import Storage. The existing storage service exports and generated aliases remain available for compatibility.

Authentication

`Auth`

Access the current user’s identity.

Scheduling

`Scheduler`

Schedule Confect functions to run after a delay or at a specific time.

Metadata

`ExecutionMetadata`

Read metadata about the current function and deployment.

`RequestMetadata`

Read metadata about the request that triggered the current execution.

`TransactionMetadata`

Read transaction usage and remaining limits. See Metadata for examples of all three services.

Search

`VectorSearch`

Query vector indexes for semantic similarity search.

Convex context

`QueryCtx`

Raw Convex query context.

`MutationCtx`

Raw Convex mutation context.

`ActionCtx`

Raw Convex action context.

Getting Started

Concepts

Server

Clients

Guides

Database

`DatabaseReader`

`DatabaseWriter`

Function invocation

`QueryRunner`

`MutationRunner`

`ActionRunner`

Transaction controls

Storage

`Storage`

Authentication

`Auth`

Scheduling

`Scheduler`

Metadata

`ExecutionMetadata`

`RequestMetadata`

`TransactionMetadata`

Search

`VectorSearch`

Convex context

`QueryCtx`

`MutationCtx`

`ActionCtx`

​Database

​DatabaseReader

​DatabaseWriter

​Function invocation

​QueryRunner

​MutationRunner

​ActionRunner

​Transaction controls

​Storage

​Storage

​Authentication

​Auth

​Scheduling

​Scheduler

​Metadata

​ExecutionMetadata

​RequestMetadata

​TransactionMetadata

​Search

​VectorSearch

​Convex context

​QueryCtx

​MutationCtx

​ActionCtx

Database

`DatabaseReader`

`DatabaseWriter`

Function invocation

`QueryRunner`

`MutationRunner`

`ActionRunner`

Transaction controls

Storage

`Storage`

Authentication

`Auth`

Scheduling

`Scheduler`

Metadata

`ExecutionMetadata`

`RequestMetadata`

`TransactionMetadata`

Search

`VectorSearch`

Convex context

`QueryCtx`

`MutationCtx`

`ActionCtx`