# Convex

> Actions can call third party services to do things such as processing a payment with [Stripe](https://stripe.com). They can be run in Convex's JavaScript environment or in Node.js. They can interact w

---

# Source: https://docs.convex.dev/tutorial/actions.md

# Source: https://docs.convex.dev/functions/actions.md

# Actions

Actions can call third party services to do things such as processing a payment with [Stripe](https://stripe.com). They can be run in Convex's JavaScript environment or in Node.js. They can interact with the database indirectly by calling [queries](/functions/query-functions.md) and [mutations](/functions/mutation-functions.md).

**Example:** [GIPHY Action](https://github.com/get-convex/convex-demos/tree/main/giphy-action)

## Action names[​](#action-names "Direct link to Action names")

Actions follow the same naming rules as queries, see [Query names](/functions/query-functions.md#query-names).

## The `action` constructor[​](#the-action-constructor "Direct link to the-action-constructor")

To declare an action in Convex you use the action constructor function. Pass it an object with a `handler` function, which performs the action:

convex/myFunctions.ts

TS

```
import { action } from "./_generated/server";

export const doSomething = action({
  args: {},
  handler: () => {
    // implementation goes here

    // optionally return a value
    return "success";
  },
});
```

Unlike a query, an action can but does not have to return a value.

### Action arguments and responses[​](#action-arguments-and-responses "Direct link to Action arguments and responses")

Action arguments and responses follow the same rules as [mutations](/functions/mutation-functions.md#mutation-arguments):

convex/myFunctions.ts

TS

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

export const doSomething = action({
  args: { a: v.number(), b: v.number() },
  handler: (_, args) => {
    // do something with `args.a` and `args.b`

    // optionally return a value
    return "success";
  },
});
```

The first argument to the handler function is reserved for the action context.

### Action context[​](#action-context "Direct link to Action context")

The `action` constructor enables interacting with the database, and other Convex features by passing an [ActionCtx](/api/interfaces/server.GenericActionCtx.md) object to the handler function as the first argument:

convex/myFunctions.ts

TS

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

export const doSomething = action({
  args: { a: v.number(), b: v.number() },
  handler: (ctx, args) => {
    // do something with `ctx`
  },
});
```

Which part of that action context is used depends on what your action needs to do:

* To read data from the database use the `runQuery` field, and call a query that performs the read:

  convex/myFunctions.ts

  TS

  ```
  import { action, internalQuery } from "./_generated/server";
  import { internal } from "./_generated/api";
  import { v } from "convex/values";

  export const doSomething = action({
    args: { a: v.number() },
    handler: async (ctx, args) => {
      const data = await ctx.runQuery(internal.myFunctions.readData, {
        a: args.a,
      });
      // do something with `data`
    },
  });

  export const readData = internalQuery({
    args: { a: v.number() },
    handler: async (ctx, args) => {
      // read from `ctx.db` here
    },
  });
  ```

  Here `readData` is an [internal query](/functions/internal-functions.md) because we don't want to expose it to the client directly. Actions, mutations and queries can be defined in the same file.

* To write data to the database use the `runMutation` field, and call a mutation that performs the write:

  convex/myFunctions.ts

  TS

  ```
  import { v } from "convex/values";
  import { action } from "./_generated/server";
  import { internal } from "./_generated/api";

  export const doSomething = action({
    args: { a: v.number() },
    handler: async (ctx, args) => {
      const data = await ctx.runMutation(internal.myMutations.writeData, {
        a: args.a,
      });
      // do something else, optionally use `data`
    },
  });
  ```

  Use an [internal mutation](/functions/internal-functions.md) when you want to prevent users from calling the mutation directly.

  As with queries, it's often convenient to define actions and mutations in the same file.

* To generate upload URLs for storing files use the `storage` field. Read on about [File Storage](/file-storage.md).

* To check user authentication use the `auth` field. Auth is propagated automatically when calling queries and mutations from the action. Read on about [Authentication](/auth.md).

* To schedule functions to run in the future, use the `scheduler` field. Read on about [Scheduled Functions](/scheduling/scheduled-functions.md).

* To search a vector index, use the `vectorSearch` field. Read on about [Vector Search](/search/vector-search.md).

### Dealing with circular type inference[​](#dealing-with-circular-type-inference "Direct link to Dealing with circular type inference")

Working around the TypeScript error: some action `implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.`

When the return value of an action depends on the result of calling `ctx.runQuery` or `ctx.runMutation`, TypeScript will complain that it cannot infer the return type of the action. This is a minimal example of the issue:

convex/myFunctions.ts

```
// TypeScript reports an error on `myAction`
export const myAction = action({
  args: {},
  handler: async (ctx) => {
    return await ctx.runQuery(api.myFunctions.getSomething);
  },
});

export const getSomething = query({
  args: {},
  handler: () => {
    return null;
  },
});
```

To work around this, there are two options:

1. Type the return value of the handler function explicitly:

   <!-- -->

   convex/myFunctions.ts

   ```
   export const myAction = action({
     args: {},
     handler: async (ctx): Promise<null> => {
       const result = await ctx.runQuery(api.myFunctions.getSomething);
       return result;
     },
   });
   ```

2. Type the the result of the `ctx.runQuery` or `ctx.runMutation` call explicitly:

   <!-- -->

   convex/myFunctions.ts

   ```
   export const myAction = action({
     args: {},
     handler: async (ctx) => {
       const result: null = await ctx.runQuery(api.myFunctions.getSomething);
       return result;
     },
   });
   ```

TypeScript will check that the type annotation matches what the called query or mutation returns, so you don't lose any type safety.

In this trivial example the return type of the query was `null`. See the [TypeScript](/understanding/best-practices/typescript.md#type-annotating-server-side-helpers) page for other types which might be helpful when annotating the result.

## Choosing the runtime ("use node")[​](#choosing-the-runtime-use-node "Direct link to Choosing the runtime (\"use node\")")

Actions can run in Convex's custom JavaScript environment or in Node.js.

By default, actions run in Convex's environment. This environment supports `fetch`, so actions that simply want to call a third-party API using `fetch` can be run in this environment:

convex/myFunctions.ts

TS

```
import { action } from "./_generated/server";

export const doSomething = action({
  args: {},
  handler: async () => {
    const data = await fetch("https://api.thirdpartyservice.com");
    // do something with data
  },
});
```

Actions running in Convex's environment are faster compared to Node.js, since they don't require extra time to start up before running your action (cold starts). They can also be defined in the same file as other Convex functions. Like queries and mutations they can import NPM packages, but not all are supported.

Actions needing unsupported NPM packages or Node.js APIs can be configured to run in Node.js by adding the `"use node"` directive at the top of the file. Note that other Convex functions cannot be defined in files with the `"use node";` directive.

convex/myAction.ts

TS

```
"use node";

import { action } from "./_generated/server";
import SomeNpmPackage from "some-npm-package";

export const doSomething = action({
  args: {},
  handler: () => {
    // do something with SomeNpmPackage
  },
});
```

Learn more about the two [Convex Runtimes](/functions/runtimes.md).

## Splitting up action code via helpers[​](#splitting-up-action-code-via-helpers "Direct link to Splitting up action code via helpers")

Just like with [queries](/functions/query-functions.md#splitting-up-query-code-via-helpers) and [mutations](/functions/mutation-functions.md#splitting-up-mutation-code-via-helpers) you can define and call helper

TypeScript

functions to split up the code in your actions or reuse logic across multiple Convex functions.

But note that the [ActionCtx](/api/interfaces/server.GenericActionCtx.md) only has the `auth` field in common with [QueryCtx](/generated-api/server.md#queryctx) and [MutationCtx](/generated-api/server.md#mutationctx).

## Calling actions from clients[​](#calling-actions-from-clients "Direct link to Calling actions from clients")

To call an action from [React](/client/react.md) use the [`useAction`](/api/modules/react.md#useaction) hook along with the generated [`api`](/generated-api/api.md) object.

src/myApp.tsx

TS

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

export function MyApp() {
  const performMyAction = useAction(api.myFunctions.doSomething);
  const handleClick = () => {
    performMyAction({ a: 1 });
  };
  // pass `handleClick` to a button
  // ...
}
```

Unlike [mutations](/functions/mutation-functions.md#calling-mutations-from-clients), actions from a single client are parallelized. Each action will be executed as soon as it reaches the server (even if other actions and mutations from the same client are running). If your app relies on actions running after other actions or mutations, make sure to only trigger the action after the relevant previous function completes.

**Note:** In most cases calling an action directly from a client **is an anti-pattern**. Instead, have the client call a [mutation](/functions/mutation-functions.md) which captures the user intent by writing into the database and then [schedules](/scheduling/scheduled-functions.md) an action:

convex/myFunctions.ts

TS

```
import { v } from "convex/values";
import { internal } from "./_generated/api";
import { internalAction, mutation } from "./_generated/server";

export const mutationThatSchedulesAction = mutation({
  args: { text: v.string() },
  handler: async (ctx, { text }) => {
    const taskId = await ctx.db.insert("tasks", { text });
    await ctx.scheduler.runAfter(0, internal.myFunctions.actionThatCallsAPI, {
      taskId,
      text,
    });
  },
});

export const actionThatCallsAPI = internalAction({
  args: { taskId: v.id("tasks"), text: v.string() },
  handler: (_, args): void => {
    // do something with `taskId` and `text`, like call an API
    // then run another mutation to store the result
  },
});
```

This way the mutation can enforce invariants, such as preventing the user from executing the same action twice.

## Limits[​](#limits "Direct link to Limits")

Actions time out after 10 minutes. [Node.js](/functions/runtimes.md#nodejs-runtime) and [Convex runtime](/functions/runtimes.md#default-convex-runtime) have 512MB and 64MB memory limit respectively. Please [contact us](/production/contact.md) if you have a use case that requires configuring higher limits.

Actions can do up to 1000 concurrent operations, such as executing queries, mutations or performing fetch requests.

For information on other limits, see [here](/production/state/limits.md).

## Error handling[​](#error-handling "Direct link to Error handling")

Unlike queries and mutations, actions may have side-effects and therefore can't be automatically retried by Convex when errors occur. For example, say your action calls Stripe to send a customer invoice. If the HTTP request fails, Convex has no way of knowing if the invoice was already sent. Like in normal backend code, it is the responsibility of the caller to handle errors raised by actions and retry the action call if appropriate.

## Dangling promises[​](#dangling-promises "Direct link to Dangling promises")

Make sure to await all promises created within an action. Async tasks still running when the function returns might or might not complete. In addition, since the Node.js execution environment might be reused between action calls, dangling promises might result in errors in subsequent action invocations.

## Best practices[​](#best-practices "Direct link to Best practices")

### `await ctx.runAction` should only be used for crossing JS runtimes[​](#await-ctxrunaction-should-only-be-used-for-crossing-js-runtimes "Direct link to await-ctxrunaction-should-only-be-used-for-crossing-js-runtimes")

**Why?** `await ctx.runAction` incurs to overhead of another Convex server function. It counts as an extra function call, it allocates its own system resources, and while you're awaiting this call the parent action call is frozen holding all it's resources. If you pile enough of these calls on top of each other, your app may slow down significantly.

**Fix:** The reason this api exists is to let you run code in the [Node.js environment](/functions/runtimes.md). If you want to call an action from another action that's in the same runtime, which is the normal case, the best way to do this is to pull the code you want to call into a TypeScript [helper function](/understanding/best-practices/.md#use-helper-functions-to-write-shared-code) and call the helper instead.

### Avoid `await ctx.runMutation` / `await ctx.runQuery`[​](#avoid-await-ctxrunmutation--await-ctxrunquery "Direct link to avoid-await-ctxrunmutation--await-ctxrunquery")

```
// ❌
const foo = await ctx.runQuery(...)
const bar = await ctx.runQuery(...)

// ✅
const fooAndBar = await ctx.runQuery(...)
```

**Why?** Multiple runQuery / runMutations execute in separate transactions and aren’t guaranteed to be consistent with each other (e.g. foo and bar could read the same document and return two different results), while a single runQuery / runMutation will always be consistent. Additionally, you’re paying for multiple function calls when you don’t have to.

**Fix:** Make a new internal query / mutation that does both things. Refactoring the code for the two functions into helpers will make it easy to create a new internal function that does both things while still keeping around the original functions. Potentially try and refactor your action code to “batch” all the database access.

Caveats: Separate runQuery / runMutation calls are valid when intentionally trying to process more data than fits in a single transaction (e.g. running a migration, doing a live aggregate).

## Related Components[​](#related-components "Direct link to Related Components")

[Convex Component](https://www.convex.dev/components/action-cache)

### [Action Cache](https://www.convex.dev/components/action-cache)

[Cache expensive or frequently run actions. Allows configurable cache duration and forcing updates.](https://www.convex.dev/components/action-cache)

[Convex Component](https://www.convex.dev/components/workpool)

### [Workpool](https://www.convex.dev/components/workpool)

[Workpool give critical tasks priority by organizing async operations into separate, customizable queues. Supports retries and parallelism limits.](https://www.convex.dev/components/workpool)

[Convex Component](https://www.convex.dev/components/workflow)

### [Workflow](https://www.convex.dev/components/workflow)

[Similar to Actions, Workflows can call queries, mutations, and actions. However, they are durable functions that can suspend, survive server crashes, specify retries for action calls, and more.](https://www.convex.dev/components/workflow)

---

# Source: https://docs.convex.dev/cli/agent-mode.md

# Agent Mode

When logged in on your own machine, agents like Cursor and Claude Code can run CLI commands like `npx convex env list` that use your logged-in credentials run commands against your personal dev environment as if you ran the commands yourself. This works well when you're collaborating with an agent; just like when the agent runs `git commit -am "Fix."`, the commit will use your local git credentials.

But when cloud-based coding agents like Jules, Devin, Codex, or Cursor Cloud Agents run Convex CLI commands, they can't log in. And if you do log in for them, the agent will use your default dev deployment to develop, conflicting with your own changes!

Instead, set `CONVEX_AGENT_MODE=anonymous` in this environment, causing the agent to use [anonymous development](/cli/local-deployments.md) to run a separate Convex backend on the VM where the agent is working.

Convex Agent Mode is in beta

Convex Agent Mode<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

You can set this variable in .env.local or set it in the agent's environment.

```
CONVEX_AGENT_MODE=anonymous npx convex dev
```

In the future `CONVEX_AGENT_MODE` may support other behaviors like allowing agents to provision their own short-lived cloud deployments.

---

# Source: https://docs.convex.dev/agents/agent-usage.md

# Agent Definition and Usage

Agents encapsulate models, prompting, tools, and other configuration. They can be defined as globals, or at runtime.

They use threads to contain a series of messages used along the way, whether those messages are from a user, another Agent / LLM, or elsewhere. A thread can have multiple Agents responding, or be used by a single Agent.

Agentic workflows are built up by combining contextual prompting (threads, messages, tool responses, RAG, etc.) and dynamic routing via LLM tool calls, structured LLM outputs, or a myriad of other techniques via custom code.

## Basic Agent definition[​](#basic-agent-definition "Direct link to Basic Agent definition")

```
import { components } from "./_generated/api";
import { Agent } from "@convex-dev/agent";
import { openai } from "@ai-sdk/openai";

const agent = new Agent(components.agent, {
  name: "Basic Agent",
  languageModel: openai.chat("gpt-4o-mini"),
});
```

See [below](#customizing-the-agent) for more configuration options.

Everything except the name can be overridden at the call site when calling the LLM, and many features available on the agent can be used without an Agent, if this way of organizing the work is not needed for your use case.

## Dynamic Agent definition[​](#dynamic-agent-definition "Direct link to Dynamic Agent definition")

You can define an Agent at runtime, which is useful if you want to create an Agent for a specific context. This allows the LLM to call tools without requiring the LLM to always pass through full context to each tool call. It also allows dynamically choosing a model or other options for the Agent.

```
import { Agent } from "@convex-dev/agent";
import { type LanguageModel } from "ai";
import type { ActionCtx } from "./_generated/server";
import type { Id } from "./_generated/dataModel";
import { components } from "./_generated/api";

function createAuthorAgent(
  ctx: ActionCtx,
  bookId: Id<"books">,
  model: LanguageModel,
) {
  return new Agent(components.agent, {
    name: "Author",
    languageModel: model,
    tools: {
      // See https://docs.convex.dev/agents/tools
      getChapter: getChapterTool(ctx, bookId),
      researchCharacter: researchCharacterTool(ctx, bookId),
      writeChapter: writeChapterTool(ctx, bookId),
    },
    maxSteps: 10, // Alternative to stopWhen: stepCountIs(10)
  });
}
```

## Generating text with an Agent[​](#generating-text-with-an-agent "Direct link to Generating text with an Agent")

To generate a message, you provide a prompt (as a string or a list of messages) to be used as context to generate one or more messages via an LLM, using calls like `agent.streamText` or `agent.generateObject`.

The arguments to `generateText` and others are the same as the AI SDK, except you don't have to provide a model. By default it will use the agent's language model. There are also extra arguments that are specific to the Agent component, such as the `promptMessageId` which we'll see below.

[**See the full list of AI SDK arguments here**](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)

The message history will be provided by default as context from the given [thread](/agents/threads.md). See [LLM Context](/agents/context.md) for details on how to configuring the context provided.

Note: `authorizeThreadAccess` referenced below is a function you would write to authenticate and authorize the user to access the thread. You can see an example implementation in [threads.ts](https://github.com/get-convex/agent/blob/main/example/convex/threads.ts).

See [chat/basic.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/basic.ts) or [chat/streaming.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/streaming.ts) for live code examples.

### Streaming text[​](#streaming-text "Direct link to Streaming text")

Streaming text follows the same pattern as the approach below, but with a few differences, depending on the type of streaming you're doing. See [streaming](/agents/streaming.md) for more details.

### Basic approach (synchronous)[​](#basic-approach-synchronous "Direct link to Basic approach (synchronous)")

```
export const generateReplyToPrompt = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    // await authorizeThreadAccess(ctx, threadId);
    const result = await agent.generateText(ctx, { threadId }, { prompt });
    return result.text;
  },
});
```

Note: best practice is to not rely on returning data from the action. Instead, query for the thread messages via the `useThreadMessages` hook and receive the new message automatically. See below.

### Saving the prompt then generating response(s) asynchronously[​](#saving-the-prompt-then-generating-responses-asynchronously "Direct link to Saving the prompt then generating response(s) asynchronously")

While the above approach is simple, generating responses asynchronously provide a few benefits:

* You can set up optimistic UI updates on mutations that are transactional, so the message will be shown optimistically on the client until the message is saved and present in your message query.
* You can save the message in the same mutation (transaction) as other writes to the database. This message can then be used and re-used in an action with retries, without duplicating the prompt message in the history. If the `promptMessageId` is used for multiple generations, any previous responses will automatically be included as context, so the LLM can continue where it left off. See [workflows](/agents/workflows.md) for more details.
* Thanks to the idempotent guarantees of mutations, the client can safely retry mutations for days until they run exactly once. Actions can transiently fail.

Any clients listing the messages will automatically get the new messages as they are created asynchronously.

To generate responses asynchronously, you need to first save the message, then pass the `messageId` as `promptMessageId` to generate / stream text.

```
import { components, internal } from "./_generated/api";
import { saveMessage } from "@convex-dev/agent";
import { internalAction, mutation } from "./_generated/server";
import { v } from "convex/values";

// Step 1: Save a user message, and kick off an async response.
export const sendMessage = mutation({
  args: { threadId: v.id("threads"), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { messageId } = await saveMessage(ctx, components.agent, {
      threadId,
      prompt,
    });
    await ctx.scheduler.runAfter(0, internal.example.generateResponseAsync, {
      threadId,
      promptMessageId: messageId,
    });
  },
});

// Step 2: Generate a response to a user message.
export const generateResponseAsync = internalAction({
  args: { threadId: v.string(), promptMessageId: v.string() },
  handler: async (ctx, { threadId, promptMessageId }) => {
    await agent.generateText(ctx, { threadId }, { promptMessageId });
  },
});
```

Note that the action doesn't need to return anything. All messages are saved by default, so any client subscribed to the thread messages will receive the new message as it is generated asynchronously.

### Generating an object[​](#generating-an-object "Direct link to Generating an object")

Similar to the AI SDK, you can generate or stream an object. The same arguments apply, except you don't have to provide a model. It will use the agent's default language model.

```
import { z } from "zod/v3";

const result = await thread.generateObject({
  prompt: "Generate a plan based on the conversation so far",
  schema: z.object({...}),
});
```

Unfortunately, object generation doesn't support using tools. One, however, is to structure your object as arguments to a tool call that returns the object. You can use a custom `stopWhen` to stop the generation when the tool call produces the result and use `toolChoice: "required"` to prevent the LLM from returning a text response.

## Customizing the agent[​](#customizing-the-agent "Direct link to Customizing the agent")

The agent by default only needs a `chat` model to be configured. However, for vector search, you'll need a `textEmbeddingModel` model. A `name` is helpful to attribute each message to a specific agent. Other options are defaults that can be over-ridden at each LLM call-site.

```
import { tool, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod/v3";
import { Agent, createTool, type Config } from "@convex-dev/agent";
import { components } from "./_generated/api";

const sharedDefaults = {
  // The language model to use for the agent.
  languageModel: openai.chat("gpt-4o-mini"),
  // Embedding model to power vector search of message history (RAG).
  textEmbeddingModel: openai.embedding("text-embedding-3-small"),
  // Used for fetching context messages. See https://docs.convex.dev/agents/context
  contextOptions,
  // Used for storing messages. See https://docs.convex.dev/agents/messages
  storageOptions,
  // Used for tracking token usage. See https://docs.convex.dev/agents/usage-tracking
  usageHandler: async (ctx, args) => {
    const { usage, model, provider, agentName, threadId, userId } = args;
    // ... log, save usage to your database, etc.
  },
  // Used for filtering, modifying, or enriching the context messages. See https://docs.convex.dev/agents/context
  contextHandler: async (ctx, args) => {
    return [...customMessages, args.allMessages];
  },
  // Useful if you want to log or record every request and response.
  rawResponseHandler: async (ctx, args) => {
    const { request, response, agentName, threadId, userId } = args;
    // ... log, save request/response to your database, etc.
  },
  // Used for limiting the number of retries when a tool call fails. Default: 3.
  callSettings: { maxRetries: 3, temperature: 1.0 },
} satisfies Config;


const supportAgent = new Agent(components.agent, {
  // The default system prompt if not over-ridden.
  instructions: "You are a helpful assistant.",
  tools: {
    // Convex tool. See https://docs.convex.dev/agents/tools
    myConvexTool: createTool({
      description: "My Convex tool",
      args: z.object({...}),
      // Note: annotate the return type of the handler to avoid type cycles.
      handler: async (ctx, args): Promise<string> => {
        return "Hello, world!";
      },
    }),
    // Standard AI SDK tool
    myTool: tool({ description, parameters, execute: () => {}}),
  },
  // Used for limiting the number of steps when tool calls are involved.
  // NOTE: if you want tool calls to happen automatically with a single call,
  // you need to set this to something greater than 1 (the default).
  stopWhen: stepCountIs(5),
  ...sharedDefaults,
});
```

---

# Source: https://docs.convex.dev/agents.md

# AI Agents

## Building AI Agents with Convex[​](#building-ai-agents-with-convex "Direct link to Building AI Agents with Convex")

Convex provides powerful building blocks for building agentic AI applications, leveraging Components and existing Convex features.

With Convex, you can separate your long-running agentic workflows from your UI, without the user losing reactivity and interactivity. The message history with an LLM is persisted by default, live updating on every client, and easily composed with other Convex features using code rather than configuration.

## Agent Component[​](#agent-component "Direct link to Agent Component")

The Agent component is a core building block for building AI agents. It manages threads and messages, around which your Agents can cooperate in static or dynamic workflows.

[Agent Component YouTube Video](https://www.youtube.com/embed/tUKMPUlOCHY?si=ce-M8pt6EWDZ8tfd)

[Agent Component YouTube Video](https://www.youtube.com/embed/tUKMPUlOCHY?si=ce-M8pt6EWDZ8tfd)

### Core Concepts[​](#core-concepts "Direct link to Core Concepts")

* Agents organize LLM prompting with associated models, prompts, and [Tools](/agents/tools.md). They can generate and stream both text and objects.
* Agents can be used in any Convex action, letting you write your agentic code alongside your other business logic with all the abstraction benefits of using code rather than static configuration.
* [Threads](/agents/threads.md) persist [messages](/agents/messages.md) and can be shared by multiple users and agents (including [human agents](/agents/human-agents.md)).
* [Conversation context](/agents/context.md) is automatically included in each LLM call, including built-in hybrid vector/text search for messages.

### Advanced Features[​](#advanced-features "Direct link to Advanced Features")

* [Workflows](/agents/workflows.md) allow building multi-step operations that can span agents, users, durably and reliably.
* [RAG](/agents/rag.md) techniques are also supported for prompt augmentation either up front or as tool calls using the [RAG Component](https://www.convex.dev/components/rag).
* [Files](/agents/files.md) can be used in the chat history with automatic saving to [file storage](/file-storage.md).

### Debugging and Tracking[​](#debugging-and-tracking "Direct link to Debugging and Tracking")

* [Debugging](/agents/debugging.md) is supported, including the [agent playground](/agents/playground.md) where you can inspect all metadata and iterate on prompts and context settings.
* [Usage tracking](/agents/usage-tracking.md) enables usage billing for users and teams.
* [Rate limiting](/agents/rate-limiting.md) helps control the rate at which users can interact with agents and keep you from exceeding your LLM provider's limits.

## [Build your first Agent](/agents/getting-started.md)

Learn more about the motivation by reading: [AI Agents with Built-in Memory](https://stack.convex.dev/ai-agents).

Sample code:

```
import { Agent } from "@convex-dev/agents";
import { openai } from "@ai-sdk/openai";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

// Define an agent
const supportAgent = new Agent(components.agent, {
  name: "Support Agent",
  chat: openai.chat("gpt-4o-mini"),
  instructions: "You are a helpful assistant.",
  tools: { accountLookup, fileTicket, sendEmail },
});

// Use the agent from within a normal action:
export const createThread = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    const { threadId, thread } = await supportAgent.createThread(ctx);
    const result = await thread.generateText({ prompt });
    return { threadId, text: result.text };
  },
});

// Pick up where you left off, with the same or a different agent:
export const continueThread = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    // This includes previous message history from the thread automatically.
    const { thread } = await anotherAgent.continueThread(ctx, { threadId });
    const result = await thread.generateText({ prompt });
    return result.text;
  },
});
```

---

# Source: https://docs.convex.dev/ai.md

# AI Code Generation

## [Prompt to build an app with Convex Chef](https://chef.convex.dev)

Convex is designed around a small set of composable abstractions with strong guarantees that result in code that is not only faster to write, but easier to read and maintain, whether written by a team member or an LLM. Key features make sure you get bug-free AI generated code:

1. **Queries are Just TypeScript** Your database queries are pure TypeScript functions with end-to-end type safety and IDE support. This means AI can generate database code using the large training set of TypeScript code without switching to SQL.
2. **Less Code for the Same Work** Since so much infrastructure and boiler plate is automatically managed by Convex there is less code to write, and thus less code to get wrong.
3. **Automatic Reactivity** The reactive system automatically tracks data dependencies and updates your UI. AI doesn't need to manually manage subscriptions, WebSocket connections, or complex state synchronization—Convex handles all of this automatically.
4. **Transactional Guarantees** Queries are read-only and mutations run in transactions. These constraints make it nearly impossible for AI to write code that could corrupt your data or leave your app in an inconsistent state.

Together, these features mean AI can focus on your business logic while Convex's guarantees prevent common failure modes. For up-to-date information on which models work best with Convex, check out our LLM [leaderboard](https://convex.dev/llm-leaderboard).

## Convex AI rules[​](#convex-ai-rules "Direct link to Convex AI rules")

AI code generation is most effective when you provide it with a set of rules to follow.

See these documents for install instructions:

* [Cursor](/ai/using-cursor.md#add-convex-cursorrules)
* [Windsurf](/ai/using-windsurf.md#add-convex-rules)
* [GitHub Copilot](/ai/using-github-copilot.md#add-convex-instructions)

For all other IDEs, add the following rules file to your project and refer to it when prompting for changes:

* [convex\_rules.txt](https://convex.link/convex_rules.txt)

We're constantly working on improving the quality of these rules for Convex by using rigorous evals. You can help by [contributing to our evals repo](https://github.com/get-convex/convex-evals).

## Using Convex with Background Agents[​](#using-convex-with-background-agents "Direct link to Using Convex with Background Agents")

Remote cloud-based coding agents like Jules, Devin, Codex, and Cursor background agents can use Convex deployments when the CLI is in [Agent Mode](/cli/agent-mode.md). This limits the permissions necessary for these remote dev environments while letting agents run codegen, iterate on code, run tests, run one-off functions.

A good setup script for e.g. ChatGPT Codex might include

```
npm i
CONVEX_AGENT_MODE=anonymous npx convex dev --once
```

or

```
bun i
CONVEX_AGENT_MODE=anonymous bun x convex dev --once
```

This command requires "full" internet access to download the binary.

## Convex MCP Server[​](#convex-mcp-server "Direct link to Convex MCP Server")

[Setup the Convex MCP server](/ai/convex-mcp-server.md) to give your AI coding agent access to your Convex deployment to query and optimize your project.

---

# Source: https://docs.convex.dev/client/android.md

# Source: https://docs.convex.dev/quickstart/android.md

# Android Kotlin Quickstart

Learn how to query data from Convex in a Android Kotlin project.

This quickstart assumes that you have Android Studio, node and npm installed. If you don’t have those tools, take time to install them first.

1. Create a new Android app in Android Studio

   Choose the following options in the wizard.

   ```
   1. Choose the "Empty Activity" template
   2. Name it "Convex Quickstart"
   3. Choose min SDK as 26
   4. Choose Kotlin as the Gradle DSL
   ```

2. Configure the AndroidManifest

   Add the following to your `AndroidManifest.xml`.

   ```
   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools">
       <uses-permission android:name="android.permission.INTERNET"/>
       <application>
           <!-- ... existing application contents -->
       </application>
   </manifest>
   ```

3. Configure your dependencies

   Add the following entries to the `:app` `build.gradle.kts` file (ignore IDE suggestion to move them to version catalog for now, if present).

   Ensure that you sync Gradle when all of the above is complete (Android Studio should prompt you to do so).

   ```
   plugins {
       // ... existing plugins
       kotlin("plugin.serialization") version "1.9.0"
   }

   dependencies {
       // ... existing dependencies
       implementation("dev.convex:android-convexmobile:0.4.1@aar") {
           isTransitive = true
       }
       implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
   }
   ```

4. Install the Convex Backend

   Open a terminal in your Android Studio instance and install the Convex client and server library.

   ```
   npm init -y
   npm install convex
   ```

5. Start Convex

   Start a Convex dev deployment. Follow the command line instructions.

   ```
   npx convex dev
   ```

6. Create a sample data for your database

   Create a new `sampleData.jsonl` file with these contents.

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

7. Add the sample data to your database

   Open another terminal tab and run.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

8. Expose a database query

   Create a `tasks.ts` file in your `convex/` directory with the following contents.

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

9. Create a data class

   Add a new `data class` to your `MainActivity` to support the task data defined above. Import whatever it asks you to.

   ```
   @Serializable
   data class Task(val text: String, val isCompleted: Boolean)
   ```

10. Create your UI

    Delete the template `@Composable` functions that Android Studio created and add a new one to display data from your Convex deployment. Again, import whatever it asks you to.

    ```
    @Composable
    fun Tasks(client: ConvexClient, modifier: Modifier = Modifier) {
        var tasks: List<Task> by remember { mutableStateOf(listOf()) }
        LaunchedEffect(key1 = "launch") {
            client.subscribe<List<Task>>("tasks:get").collect { result ->
                result.onSuccess { remoteTasks ->
                    tasks = remoteTasks
                }
            }
        }
        LazyColumn(
            modifier = modifier
        ) {
            items(tasks) { task ->
                Text(text = "Text: ${task.text}, Completed?: ${task.isCompleted}")
            }
        }
    }
    ```

11. Connect the app to your backend

    1. Get the deployment URL of your dev server with `cat .env.local | grep CONVEX_URL`
    2. Update the `onCreate` method in your `MainActivity.kt` to look like

    ```
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            ConvexQuickstartTheme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    Tasks(
                        client = ConvexClient($YOUR_CONVEX_URL),
                        modifier = Modifier.padding(innerPadding)
                    )
                }
            }
        }
    }
    ```

12. Fix any missing imports

    Fix up any missing imports (your import declarations should look something like this):

    ```
    import android.os.Bundle
    import androidx.activity.ComponentActivity
    import androidx.activity.compose.setContent
    import androidx.activity.enableEdgeToEdge
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.foundation.layout.padding
    import androidx.compose.foundation.lazy.LazyColumn
    import androidx.compose.foundation.lazy.items
    import androidx.compose.material3.Scaffold
    import androidx.compose.material3.Text
    import androidx.compose.runtime.Composable
    import androidx.compose.runtime.LaunchedEffect
    import androidx.compose.runtime.getValue
    import androidx.compose.runtime.mutableStateOf
    import androidx.compose.runtime.remember
    import androidx.compose.runtime.setValue
    import androidx.compose.ui.Modifier
    import dev.convex.android.ConvexClient
    import kotlinx.serialization.Serializable
    ```

13. Run the app

    You can also try adding, updating or deleting documents in your `tasks` table at `dashboard.convex.dev` - the app will update with the changes in real-time.

    ```
    From the IDE menu choose "Run" > "Run 'app'"
    ```

See the complete [Android Kotlin documentation](/client/android.md).

---

# Source: https://docs.convex.dev/generated-api/api.md

# Source: https://docs.convex.dev/api.md

# Convex

TypeScript backend SDK, client libraries, and CLI for Convex.

Convex is the backend application platform with everything you need to build your product.

Get started at [docs.convex.dev](https://docs.convex.dev)!

Or see [Convex demos](https://github.com/get-convex/convex-demos).

Open discussions and issues in this repository about Convex TypeScript/JavaScript clients, the Convex CLI, or the Convex platform in general.

Also feel free to share feature requests, product feedback, or general questions in the [Convex Discord Community](https://convex.dev/community).

# Structure

This package includes several entry points for building apps on Convex:

* [`convex/server`](https://docs.convex.dev/api/modules/server): SDK for defining a Convex backend functions, defining a database schema, etc.
* [`convex/react`](https://docs.convex.dev/api/modules/react): Hooks and a `ConvexReactClient` for integrating Convex into React applications.
* [`convex/browser`](https://docs.convex.dev/api/modules/browser): A `ConvexHttpClient` for using Convex in other browser environments.
* [`convex/values`](https://docs.convex.dev/api/modules/values): Utilities for working with values stored in Convex.
* [`convex/react-auth0`](https://docs.convex.dev/api/modules/react_auth0): A React component for authenticating users with Auth0.
* [`convex/react-clerk`](https://docs.convex.dev/api/modules/react_clerk): A React component for authenticating users with Clerk.
* [`convex/nextjs`](https://docs.convex.dev/api/modules/nextjs): Server-side helpers for SSR, usable by Next.js and other React frameworks.

This package also includes [`convex`](https://docs.convex.dev/using/cli), the command-line interface for managing Convex projects.

---

# Source: https://docs.convex.dev/client/nextjs/app-router.md

# Next.js

[Next.js](https://nextjs.org/) is a React web development framework. When used with Convex, Next.js provides:

* File-system based routing
* Fast refresh in development
* Font and image optimization

and more!

This page covers the App Router variant of Next.js. Alternatively see the [Pages Router](/client/nextjs/pages-router/.md) version of this page.

## Getting started[​](#getting-started "Direct link to Getting started")

Follow the [Next.js Quickstart](/quickstart/nextjs.md) to add Convex to a new or existing Next.js project.

## Calling Convex functions from client code[​](#calling-convex-functions-from-client-code "Direct link to Calling Convex functions from client code")

To fetch and edit the data in your database from client code, use hooks of the [Convex React library](/client/react.md).

## [Convex React library documentation](/client/react.md)

## Server rendering (SSR)[​](#server-rendering-ssr "Direct link to Server rendering (SSR)")

Next.js automatically renders both Client and Server Components on the server during the initial page load.

To keep your UI [automatically reactive](/functions/query-functions.md#caching--reactivity--consistency) to changes in your Convex database it needs to use Client Components. The `ConvexReactClient` will maintain a connection to your deployment and will get updates as data changes and that must happen on the client.

See the dedicated [Server Rendering](/client/nextjs/app-router/server-rendering.md) page for more details about preloading data for Client Components, fetching data and authentication in Server Components, and implementing Route Handlers.

## Adding authentication[​](#adding-authentication "Direct link to Adding authentication")

### Client-side only[​](#client-side-only "Direct link to Client-side only")

The simplest way to add user authentication to your Next.js app is to follow our React-based authentication guides for [Clerk](/auth/clerk.md) or [Auth0](/auth/auth0.md), inside your `app/ConvexClientProvider.tsx` file. For example this is what the file would look like for Auth0:

app/ConvexClientProvider.tsx

TS

```
"use client";

import { Auth0Provider } from "@auth0/auth0-react";
import { ConvexReactClient } from "convex/react";
import { ConvexProviderWithAuth0 } from "convex/react-auth0";
import { ReactNode } from "react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return (
    <Auth0Provider
      domain={process.env.NEXT_PUBLIC_AUTH0_DOMAIN!}
      clientId={process.env.NEXT_PUBLIC_AUTH0_CLIENT_ID!}
      authorizationParams={{
        redirect_uri:
          typeof window === "undefined" ? undefined : window.location.origin,
      }}
      useRefreshTokens={true}
      cacheLocation="localstorage"
    >
      <ConvexProviderWithAuth0 client={convex}>
        {children}
      </ConvexProviderWithAuth0>
    </Auth0Provider>
  );
}
```

Custom loading and logged out views can be built with the helper `Authenticated`, `Unauthenticated` and `AuthLoading` components from `convex/react`, see the [Convex Next.js demo](https://github.com/get-convex/convex-demos/tree/main/nextjs-pages-router/pages/_app.tsx) for an example.

If only some routes of your app require login, the same helpers can be used directly in page components that do require login instead of being shared between all pages from `app/ConvexClientProvider.tsx`. Share a single [ConvexReactClient](/api/classes/react.ConvexReactClient.md) instance between pages to avoid needing to reconnect to Convex on client-side page navigation.

### Server and client side[​](#server-and-client-side "Direct link to Server and client side")

To access user information or load Convex data requiring `ctx.auth` from Server Components, Server Actions, or Route Handlers you need to use the Next.js specific SDKs provided by Clerk and Auth0.

Additional `.env.local` configuration is needed for these hybrid SDKs.

#### Clerk[​](#clerk "Direct link to Clerk")

For an example of using Convex and with Next.js 15, run

**`npm create convex@latest -- -t nextjs-clerk`**

**``**

Otherwise, follow the [Clerk Next.js quickstart](https://clerk.com/docs/quickstarts/nextjs), a guide from Clerk that includes steps for adding `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` to the .env.local file. In Next.js 15, the `<ClerkProvider>` component imported from the `@clerk/nextjs` v6 package functions as both a client and a server context provider so you probably won't need the `ClerkProvider` from `@clerk/clerk-react`.

#### Auth0[​](#auth0 "Direct link to Auth0")

See the [Auth0 Next.js](https://auth0.com/docs/quickstart/webapp/nextjs/01-login) guide.

#### Other providers[​](#other-providers "Direct link to Other providers")

Convex uses JWT identity tokens on the client for live query subscriptions and running mutations and actions, and on the Next.js backend for running queries, mutations, and actions in server components and API routes.

Obtain the appropriate OpenID Identity JWT in both locations and you should be able to use any auth provider. See [Custom Auth](https://docs.convex.dev/auth/advanced/custom-auth) for more.

---

# Source: https://docs.convex.dev/functions/error-handling/application-errors.md

# Application Errors

If you have expected ways your functions might fail, you can either return different values or throw `ConvexError`s.

## Returning different values[​](#returning-different-values "Direct link to Returning different values")

If you're using TypeScript different return types can enforce that you're handling error scenarios.

For example, a `createUser` mutation could return

```
Id<"users"> | { error: "EMAIL_ADDRESS_IN_USE" };
```

to express that either the mutation succeeded or the email address was already taken.

This ensures that you remember to handle these cases in your UI.

## Throwing application errors[​](#throwing-application-errors "Direct link to Throwing application errors")

You might prefer to throw errors for the following reasons:

* You can use the exception bubbling mechanism to throw from a deeply nested function call, instead of manually propagating error results up the call stack. This will work for `runQuery`, `runMutation` and `runAction` calls in [actions](/functions/actions.md) too.
* In [mutations](/functions/mutation-functions.md), throwing an error will prevent the mutation transaction from committing
* On the client, it might be simpler to handle all kinds of errors, both expected and unexpected, uniformly

Convex provides an error subclass, [`ConvexError`](/api/classes/values.ConvexError.md), which can be used to carry information from the backend to the client:

convex/myFunctions.ts

TS

```
import { ConvexError } from "convex/values";
import { mutation } from "./_generated/server";

export const assignRole = mutation({
  args: {
    // ...
  },
  handler: (ctx, args) => {
    const isTaken = isRoleTaken(/* ... */);
    if (isTaken) {
      throw new ConvexError("Role is already taken");
    }
    // ...
  },
});
```

### Application error `data` payload[​](#application-error-data-payload "Direct link to application-error-data-payload")

You can pass the same [data types](/database/types.md) supported by function arguments, return types and the database, to the `ConvexError` constructor. This data will be stored on the `data` property of the error:

```
// error.data === "My fancy error message"
throw new ConvexError("My fancy error message");

// error.data === {message: "My fancy error message", code: 123, severity: "high"}
throw new ConvexError({
  message: "My fancy error message",
  code: 123,
  severity: "high",
});

// error.data === {code: 123, severity: "high"}
throw new ConvexError({
  code: 123,
  severity: "high",
});
```

Error payloads more complicated than a simple `string` are helpful for more structured error logging, or for handling sets of errors differently on the client.

## Handling application errors on the client[​](#handling-application-errors-on-the-client "Direct link to Handling application errors on the client")

On the client, application errors also use the `ConvexError` class, and the data they carry can be accessed via the `data` property:

src/App.tsx

TS

```
import { ConvexError } from "convex/values";
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

export function MyApp() {
  const doSomething = useMutation(api.myFunctions.mutateSomething);
  const handleSomething = async () => {
    try {
      await doSomething({ a: 1, b: 2 });
    } catch (error) {
      const errorMessage =
        // Check whether the error is an application error
        error instanceof ConvexError
          ? // Access data and cast it to the type we expect
            (error.data as { message: string }).message
          : // Must be some developer error,
            // and prod deployments will not
            // reveal any more information about it
            // to the client
            "Unexpected error occurred";
      // do something with `errorMessage`
    }
  };
  // ...
}
```

---

# Source: https://docs.convex.dev/auth.md

# Authentication

Convex deployment endpoints are exposed to the open internet and the claims clients make about who they are must be authenticated to identify users and restrict what data they can see and edit.

Convex is compatible with most authentication providers because it uses OpenID Connect (based on OAuth) ID tokens in the form of JWTs to authenticate WebSocket connections or RPCs. These JWTs can be provided by any service (including your own Convex backend) that implement the appropriate OAuth endpoints to verify them.

## Third-party authentication platforms[​](#third-party-authentication-platforms "Direct link to Third-party authentication platforms")

Leveraging a Convex integration with a third-party auth provider provides the most comprehensive authentication solutions. Integrating another service provides a ton of functionality like passkeys, two-factor auth, spam protection, and more on top of the authentication basics.

* [Clerk](/auth/clerk.md) has great Next.js and React Native support
* [WorkOS AuthKit](/auth/authkit/.md) is built for B2B apps and free for up to 1M users
* [Auth0](/auth/auth0.md) is more established with more bells and whistles
* [Custom Auth Integration](/auth/advanced/custom-auth.md) allow any OpenID Connect-compatible identity provider to be used for authentication

After you integrate one of these, learn more about accessing authentication information in [Functions](/auth/functions-auth.md) and storing user information in the [Database](/auth/database-auth.md).

## The Convex Auth Library[​](#the-convex-auth-library "Direct link to The Convex Auth Library")

For client-side React and React Native mobile apps you can implement auth directly in Convex with the [Convex Auth](/auth/convex-auth.md) library. This [npm package](https://github.com/get-convex/convex-auth) runs on your Convex deployment and helps you build a custom sign-up/sign-in flow via social identity providers, one-time email or SMS access codes, or via passwords.

Convex Auth is in beta (it isn't complete and may change in backward-incompatible ways) and doesn't provide as many features as third party auth integrations. Since it doesn't require signing up for another service it's the quickest way to get auth up and running.

Convex Auth is in beta

Convex Auth<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

Support for Next.js is under active development. If you'd like to help test this experimental support please [give it a try](https://labs.convex.dev/auth)!

## Debugging[​](#debugging "Direct link to Debugging")

If you run into issues consult the [Debugging](/auth/debug.md) guide.

## Service Authentication[​](#service-authentication "Direct link to Service Authentication")

Servers you control or third party services can call Convex functions but may not be able to obtain OpenID JWTs and often do not represent the actions of a specific user.

Say you're running some inference on a [Modal](https://modal.com/) server written in Python. When that server subscribes to a Convex query it doesn't do so with credentials of a particular end-user, rather it's looking for relevant tasks for any users that need that inference task, say summarizing and translating a conversation, completed.

To provide access to Convex queries, mutations, and actions to an external service you can write public functions accessible to the internet that check a shared secret, for example from an environment variable, before doing anything else.

## Authorization[​](#authorization "Direct link to Authorization")

Convex enables a traditional three tier application structure: a client/UI for your app, a backend that handles user requests, and a database for queries. This architecture lets you check every public request against any authorization rules you can define in code.

This means Convex doesn't need an opinionated authorization framework like RLS, which is required in client oriented databases like Firebase or Supabase. This flexibility lets you build and use an [authorization framework](https://en.wikipedia.org/wiki/Authorization) for your needs.

That said, the most common way is to simply write code that checks if the user is logged in and if they are allowed to do the requested action at the beginning of each public function.

For example, the following function enforces that only the currently authenticated user can remove their own user image:

```
export const removeUserImage = mutation({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) {
      return;
    }
    ctx.db.patch("users", userId, { imageId: undefined, image: undefined });
  },
});
```

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/auth/auth0.md

# Convex & Auth0

[Auth0](https://auth0.com) is an authentication platform providing login via passwords, social identity providers, one-time email or SMS access codes, multi-factor authentication, and single sign on and basic user management.

**Example:** [Convex Authentication with Auth0](https://github.com/get-convex/convex-demos/tree/main/users-and-auth)

If you're using Next.js see the [Next.js setup guide](https://docs.convex.dev/client/nextjs).

## Get started[​](#get-started "Direct link to Get started")

This guide assumes you already have a working React app with Convex. If not follow the [Convex React Quickstart](/quickstart/react.md) first. Then:

1. Follow the Auth0 React quickstart

   Follow the [Auth0 React Quickstart](https://auth0.com/docs/quickstart/spa/react/interactive).

   Sign up for a free Auth0 account.

   Configure your application, using `http://localhost:3000, http://localhost:5173` for Callback and Logout URLs and Allowed Web Origins.

   Come back when you finish the *Install the Auth0 React SDK* step.

   ![Sign up to Auth0](/screenshots/auth0-signup.png)

2. Create the auth config

   In the `convex` folder create a new file `auth.config.ts` with the server-side configuration for validating access tokens.

   Paste in the `domain` and `clientId` values shown in *Install the Auth0 React SDK* step of the Auth0 quickstart or in your Auth0 application's Settings dashboard.

   convex/auth.config.ts

   TS

   ```
   import { AuthConfig } from "convex/server";

   export default {
     providers: [
       {
         domain: "your-domain.us.auth0.com",
         applicationID: "yourclientid",
       },
     ]
   } satisfies AuthConfig;
   ```

3. Deploy your changes

   Run `npx convex dev` to automatically sync your configuration to your backend.

   ```
   npx convex dev
   ```

4. Configure ConvexProviderWithAuth0

   Now replace your `ConvexProvider` with an `Auth0Provider` wrapping `ConvexProviderWithAuth0`. Add the `domain` and `clientId` as props to the `Auth0Provider`.

   Paste in the `domain` and `clientId` values shown in *Install the Auth0 React SDK* step of the Auth0 quickstart or in your Auth0 application's Settings dashboard as props to `Auth0Provider`.

   src/main.tsx

   TS

   ```
   import React from "react";
   import ReactDOM from "react-dom/client";
   import App from "./App";
   import "./index.css";
   import { ConvexReactClient } from "convex/react";
   import { ConvexProviderWithAuth0 } from "convex/react-auth0";
   import { Auth0Provider } from "@auth0/auth0-react";

   const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

   ReactDOM.createRoot(document.getElementById("root")!).render(
     <React.StrictMode>
       <Auth0Provider
         domain="your-domain.us.auth0.com"
         clientId="yourclientid"
         authorizationParams={{
           redirect_uri: window.location.origin,
         }}
         useRefreshTokens={true}
         cacheLocation="localstorage"
       >
         <ConvexProviderWithAuth0 client={convex}>
           <App />
         </ConvexProviderWithAuth0>
       </Auth0Provider>
     </React.StrictMode>,
   );
   ```

## Login and logout flows[​](#login-and-logout-flows "Direct link to Login and logout flows")

Now that you have everything set up, you can use the [`useAuth0()`](https://auth0.github.io/auth0-react/functions/useAuth0.html) hook to create login and logout buttons for your app.

The login button will redirect the user to the Auth0 universal login page. For details see [Add Login to Your Application](https://auth0.com/docs/quickstart/spa/react/interactive#add-login-to-your-application) in the Auth0 React Quickstart.

src/login.ts

TS

```
import { useAuth0 } from "@auth0/auth0-react";

export default function LoginButton() {
  const { loginWithRedirect } = useAuth0();
  return <button onClick={loginWithRedirect}>Log in</button>;
}
```

The logout button will redirect the user to the Auth0 logout endpoint. For details see [Add Logout to your Application](https://auth0.com/docs/quickstart/spa/react/interactive#add-logout-to-your-application) in the Auth0 React Quickstart.

src/logout.ts

TS

```
import { useAuth0 } from "@auth0/auth0-react";

export default function LogoutButton() {
  const { logout } = useAuth0();
  return (
    <button
      onClick={() =>
        logout({ logoutParams: { returnTo: window.location.origin } })
      }
    >
      Log out
    </button>
  );
}
```

## Logged-in and logged-out views[​](#logged-in-and-logged-out-views "Direct link to Logged-in and logged-out views")

Use the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook instead of the `useAuth0` hook when you need to check whether the user is logged in or not. The `useConvex` hook makes sure that the browser has fetched the auth token needed to make authenticated requests to your Convex backend:

src/App.ts

TS

```
import { useConvexAuth } from "convex/react";

function App() {
  const { isLoading, isAuthenticated } = useConvexAuth();

  return (
    <div className="App">
      {isAuthenticated ? "Logged in" : "Logged out or still loading"}
    </div>
  );
}
```

You can also use the `Authenticated`, `Unauthenticated` and `AuthLoading` helper components which use the `useConvexAuth` hook under the hood:

src/App.ts

TS

```
import { Authenticated, Unauthenticated, AuthLoading } from "convex/react";

function App() {
  return (
    <div className="App">
      <Authenticated>Logged in</Authenticated>
      <Unauthenticated>Logged out</Unauthenticated>
      <AuthLoading>Still loading</AuthLoading>
    </div>
  );
}
```

## User information in React[​](#user-information-in-react "Direct link to User information in React")

You can access information about the authenticated user like their name from the `useAuth0` hook:

src/badge.ts

TS

```
import { useAuth0 } from "@auth0/auth0-react";

export default function Badge() {
  const { user } = useAuth0();
  return <span>Logged in as {user.name}</span>;
}
```

## User information in functions[​](#user-information-in-functions "Direct link to User information in functions")

See [Auth in Functions](/auth/functions-auth.md) to learn about how to access information about the authenticated user in your queries, mutations and actions.

See [Storing Users in the Convex Database](/auth/database-auth.md) to learn about how to store user information in the Convex database.

## Configuring dev and prod tenants[​](#configuring-dev-and-prod-tenants "Direct link to Configuring dev and prod tenants")

To configure a different Auth0 tenant (environment) between your Convex development and production deployments you can use environment variables configured on the Convex dashboard.

### Configuring the backend[​](#configuring-the-backend "Direct link to Configuring the backend")

First, change your `auth.config.ts` file to use environment variables:

convex/auth.config.ts

TS

```
import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: process.env.AUTH0_DOMAIN!,
      applicationID: process.env.AUTH0_CLIENT_ID!,
    },
  ],
} satisfies AuthConfig;
```

**Development configuration**

Open the Settings for your dev deployment on the Convex [dashboard](https://dashboard.convex.dev) and add the variables there:

![Convex dashboard dev deployment settings](/screenshots/auth0-convex-dashboard.png)

Now switch to the new configuration by running `npx convex dev`.

**Production configuration**

Similarly on the Convex [dashboard](https://dashboard.convex.dev) switch to your production deployment in the left side menu and set the values for your production Auth0 tenant there.

Now switch to the new configuration by running `npx convex deploy`.

### Configuring a React client[​](#configuring-a-react-client "Direct link to Configuring a React client")

To configure your client you can use environment variables as well. The exact name of the environment variables and the way to refer to them depends on each client platform (Vite vs Next.js etc.), refer to our corresponding [Quickstart](/quickstarts) or the relevant documentation for the platform you're using.

Change the props to `Auth0Provider` to take in environment variables:

src/main.tsx

TS

```
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";
import { ConvexReactClient } from "convex/react";
import { ConvexProviderWithAuth0 } from "convex/react-auth0";
import { Auth0Provider } from "@auth0/auth0-react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin,
      }}
      useRefreshTokens={true}
      cacheLocation="localstorage"
    >
      <ConvexProviderWithAuth0 client={convex}>
        <App />
      </ConvexProviderWithAuth0>
    </Auth0Provider>
  </React.StrictMode>,
);
```

**Development configuration**

Use the `.env.local` or `.env` file to configure your client when running locally. The name of the environment variables file depends on each client platform (Vite vs Next.js etc.), refer to our corresponding [Quickstart](/quickstarts) or the relevant documentation for the platform you're using:

.env.local

```
VITE_AUTH0_DOMAIN="your-domain.us.auth0.com"
VITE_AUTH0_CLIENT_ID="yourclientid"
```

**Production configuration**

Set the environment variables in your production environment depending on your hosting platform. See [Hosting](/production/hosting/.md).

## Debugging authentication[​](#debugging-authentication "Direct link to Debugging authentication")

If a user goes through the Auth0 login flow successfully, and after being redirected back to your page `useConvexAuth` gives `isAuthenticated: false`, it's possible that your backend isn't correctly configured.

The `auth.config.ts` file in your `convex/` directory contains a list of configured authentication providers. You must run `npx convex dev` or `npx convex deploy` after adding a new provider to sync the configuration to your backend.

For more thorough debugging steps, see [Debugging Authentication](/auth/debug.md).

## Under the hood[​](#under-the-hood "Direct link to Under the hood")

The authentication flow looks like this under the hood:

1. The user clicks a login button
2. The user is redirected to a page where they log in via whatever method you configure in
   <!-- -->
   Auth0
3. After a successful login
   <!-- -->
   Auth0
   <!-- -->
   redirects back to your page, or a different page which you configure via
   <!-- -->
   the
   <!-- -->
   [`authorizationParams`](https://auth0.github.io/auth0-react/interfaces/AuthorizationParams.html)
   <!-- -->
   prop
   <!-- -->
   .
4. The `Auth0Provider` now knows that the user is authenticated.
5. The `ConvexProviderWithAuth0` fetches an auth token from
   <!-- -->
   Auth0
   <!-- -->
   .
6. The `ConvexReactClient` passes this token down to your Convex backend to validate
7. Your Convex backend retrieves the public key from
   <!-- -->
   Auth0
   <!-- -->
   to check that the token's signature is valid.
8. The `ConvexReactClient` is notified of successful authentication, and `ConvexProviderWithAuth0` now knows that the user is authenticated with Convex. `useConvexAuth` returns `isAuthenticated: true` and the `Authenticated` component renders its children.

`ConvexProviderWithAuth0` takes care of refetching the token when needed to make sure the user stays authenticated with your backend.

---

# Source: https://docs.convex.dev/auth/authkit.md

# Convex & WorkOS AuthKit

[WorkOS AuthKit](https://authkit.com) is an authentication solution that enables sign-in using passwords, social login providers, email one-time codes, two-factor authentication, and user management capabilities.

You can use your own WorkOS account with AuthKit or [create a WorkOS account with Convex](/auth/authkit/auto-provision.md) to create and do some configuration of AuthKit environments automatically.

## Get started[​](#get-started "Direct link to Get started")

The quickest way to get started is with a template:

```
npm create convex@latest -- -t react-vite-authkit
cd my-app  # or whatever you name the directory
npm run dev
```

Follow the prompts to create a WorkOS team that will be associated with your Convex team. After this Convex deployments for projects in this team will be able to automatically provision and configure their own WorkOS environments.

That's it! After this you and other members of your Convex team can create and configure development WorkOS environments without visiting [workos.com](https://workos.com).

See [AuthKit configuration in convex.json](/auth/authkit/auto-provision.md) to modify the convex.json file in this template for your needs.

### Configuring an existing WorkOS account[​](#configuring-an-existing-workos-account "Direct link to Configuring an existing WorkOS account")

To use AuthKit with an existing WorkOS account you'll need to configure the account and copy credentials into the Convex deployment and your local `.env.local` file.

1. Sign up for WorkOS

   Sign up for a free WorkOS account at [workos.com/sign-up](https://signin.workos.com/sign-up).

   ![Sign up for a WorkOS account](/screenshots/workos-signup.png)

2. Set up AuthKit

   In the WorkOS Dashboard, navigate to **Authentication** and then to **AuthKit**. From here, click the **Set up AuthKit** button to enable AuthKit in your account.

   ![Set up AuthKit in your account](/screenshots/workos-setup-authkit.png)

3. Complete AuthKit setup

   Press the **Begin setup** button with **Use AuthKit's customizable hosted UI** selected. These options can be filled out however you like until you get to step 4, **Add default redirect endpoint URI**.

   The Redirect URI is the endpoint that WorkOS will return an authorization code to after signing in. This should match your application's domain and port, with `/callback` as the route. For example, if your application is running at `localhost:5173` then the value here should be `http://localhost:5173/callback`.

   Complete the AuthKit setup.

   ![Set the redirect URI endpoint](/screenshots/workos-redirect-uri.png)

4. Copy your Client ID and API Key

   From the [get started](https://dashboard.workos.com/get-started) page under **Quick start**, find your `WORKOS_CLIENT_ID` and copy it.

   ![Getting your WorkOS Client ID](/screenshots/workos-client-id.png)

## Client configuration[​](#client-configuration "Direct link to Client configuration")

Convex offers a provider that is specifically for integrating with WorkOS AuthKit called `<ConvexProviderWithAuthKit>`. It works using WorkOS's [authkit-react](https://github.com/workos/authkit-react) SDK.

Once you've completed the WorkOS setup above, choose your framework below to continue with the integration.

See the following sections for the WorkOS SDK that you're using:

* [React](#react) - Use this as a starting point if your SDK is not listed
* [Next.js](#nextjs)

### React[​](#react "Direct link to React")

**Example:** [React with Convex and AuthKit](https://github.com/workos/template-convex-react-vite-authkit)

This guide assumes you have [AuthKit set up](#configuring-an-existing-workos-account) and have a working React app with Convex. If not follow the [Convex React Quickstart](/quickstart/react.md) first. Then:

1. Set up CORS in the WorkOS Dashboard

   In your WorkOS Dashboard, go to [*Authentication* > *Sessions*](https://dashboard.workos.com/environment/authentication/sessions) > *Cross-Origin Resource Sharing (CORS)* and click on **Manage**. Add your local development domain (e.g., `http://localhost:5173` for Vite) to the list. You'll also need to add your production domain when you deploy. This enables your application to authenticate users through WorkOS AuthKit.

   ![Setting up CORS](/screenshots/workos-cors-setup.png)

2. Set up your environment variables

   In your `.env.local` file, add your `WORKOS_CLIENT_ID` and `WORKOS_REDIRECT_URI` environment variables. If you're using Vite, you'll need to prefix it with `VITE_`.

   **Note:** These values can be found in your [WorkOS Dashboard](https://dashboard.workos.com/).

   .env.local

   ```
   # WorkOS AuthKit Configuration
   VITE_WORKOS_CLIENT_ID=your-workos-client-id-here
   VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback
   ```

3. Configure Convex with the WorkOS Client ID

   In your app's `convex` folder, create a new file `auth.config.ts` with the following code. This is the server-side configuration for validating access tokens.

   convex/auth.config.ts

   TS

   ```
   const clientId = process.env.WORKOS_CLIENT_ID;

   const authConfig = {
     providers: [
       {
         type: 'customJwt',
         issuer: `https://api.workos.com/`,
         algorithm: 'RS256',
     jwks: `https://api.workos.com/sso/jwks/${clientId}`,
     applicationID: clientId,
       },
       {
         type: 'customJwt',
         issuer: `https://api.workos.com/user_management/${clientId}`,
         algorithm: 'RS256',
         jwks: `https://api.workos.com/sso/jwks/${clientId}`,
       },
     ],
   };

   export default authConfig;
   ```

4. Deploy your changes

   Run `npx convex dev` to automatically sync your configuration to your backend.

   You'll see an error and a link to click to fill in the WORKOS\_CLIENT\_ID environment variable in your Convex deployment. Follow the link, paste in the WorkOS client ID, save, and you should see the `npx convex dev` command show "Convex functions ready."

   ```
   npx convex dev
   ```

5. Install AuthKit

   In a new terminal window, install the AuthKit React SDK:

   ```
   npm install @workos-inc/authkit-react @convex-dev/workos
   ```

6. Configure ConvexProviderWithAuthKit

   AuthKit and Convex both have provider components that provide authentication and client context to your app.

   You should already have `<ConvexProvider>` wrapping your app. Replace it with `<ConvexProviderWithAuthKit>`, and pass WorkOS's `useAuth()` hook to it.

   Then, wrap it with `<AuthKitProvider>`. `<AuthKitProvider>` requires `clientId` and `redirectUri` props, which you can set to `VITE_WORKOS_CLIENT_ID` and `VITE_WORKOS_REDIRECT_URI`, respectively.

   src/main.tsx

   TS

   ```
   import { StrictMode } from "react";
   import { createRoot } from "react-dom/client";
   import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react";
   import { ConvexReactClient } from "convex/react";
   import { ConvexProviderWithAuthKit } from "@convex-dev/workos";
   import "./index.css";
   import App from "./App.tsx";

   const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

   createRoot(document.getElementById("root")!).render(
     <StrictMode>
       <AuthKitProvider
         clientId={import.meta.env.VITE_WORKOS_CLIENT_ID}
         redirectUri={import.meta.env.VITE_WORKOS_REDIRECT_URI}
       >
         <ConvexProviderWithAuthKit client={convex} useAuth={useAuth}>
           <App />
         </ConvexProviderWithAuthKit>
       </AuthKitProvider>
     </StrictMode>,
   );
   ```

7. Show UI based on authentication state

   You can control which UI is shown when the user is signed in or signed out using Convex's `<Authenticated>`, `<Unauthenticated>` and `<AuthLoading>` helper components.

   It's important to use the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook instead of AuthKit's `useAuth()` hook when you need to check whether the user is logged in or not. The `useConvexAuth()` hook makes sure that the browser has fetched the auth token needed to make authenticated requests to your Convex backend, and that the Convex backend has validated it.

   In the following example, the `<Content />` component is a child of `<Authenticated>`, so its content and any of its child components are guaranteed to have an authenticated user, and Convex queries can require authentication.

   src/App.tsx

   TS

   ```
   import { Authenticated, Unauthenticated, useQuery } from 'convex/react';
   import { api } from '../convex/_generated/api';
   import { useAuth } from '@workos-inc/authkit-react';

   export default function App() {
     const { user, signIn, signOut } = useAuth();

     return (
       <div className="p-4"> <div className="flex justify-between items-center mb-4">
           <h1>Convex + AuthKit</h1>
           <button onClick={() => (user ? signOut() : void signIn())}>{user ? 'Sign out' : 'Sign in'}</button>
         </div>
         <Authenticated>
           <Content />
         </Authenticated>
         <Unauthenticated>
           <p>Please sign in to view data</p>
         </Unauthenticated>
       </div>
     );
   }

   function Content() {
     const data = useQuery(api.myFunctions.listNumbers, { count: 10 });

     if (!data) return <p>Loading...</p>;

     return (
       <div>
         <p>Welcome {data.viewer}!</p>
         <p>Numbers: {data.numbers?.join(', ') || 'None'}</p>
       </div>
     );
   }
   ```

8. Use authentication state in your Convex functions

   If the client is authenticated, you can access the information stored in the JWT via `ctx.auth.getUserIdentity`.

   If the client isn't authenticated, `ctx.auth.getUserIdentity` will return `null`.

   **Make sure that the component calling this query is a child of `<Authenticated>` from `convex/react`**. Otherwise, it will throw on page load.

   convex/myFunctions.ts

   TS

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

   export const listNumbers = query({
     args: {
       count: v.number(),
     },
     handler: async (ctx, args) => {
       const numbers = await ctx.db
         .query("numbers")
         // Ordered by _creationTime, return most recent
         .order("desc")
         .take(args.count);
       return {
         viewer: (await ctx.auth.getUserIdentity())?.name ?? null,
         numbers: numbers.reverse().map((number) => number.value),
       };
     },
   });
   ```

**Note:** The [React template repository](https://github.com/workos/template-convex-react-vite-authkit) includes additional features and functions for a complete working application. This tutorial covers the core integration steps, but the template provides a more comprehensive implementation.

### Next.js[​](#nextjs "Direct link to Next.js")

**Example:** [Next.js with Convex and AuthKit](https://github.com/workos/template-convex-nextjs-authkit)

This guide assumes you have [AuthKit set up](#configuring-an-existing-workos-account) and have a working Next.js app with Convex. If not follow the [Convex Next.js Quickstart](/quickstart/nextjs.md) first. Then:

1. Set up your environment variables

   In your `.env.local` file, add the following environment variables:

   .env.local

   ```
   # WorkOS AuthKit Configuration
   WORKOS_CLIENT_ID=client_your_client_id_here
   WORKOS_API_KEY=sk_test_your_api_key_here
   WORKOS_COOKIE_PASSWORD=your_secure_password_here_must_be_at_least_32_characters_long
   NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3000/callback

   # Convex Configuration (you don't have to fill these out, they're generated by Convex)
   # Deployment used by `npx convex dev`
   CONVEX_DEPLOY_KEY=your_convex_deploy_key_here
   NEXT_PUBLIC_CONVEX_URL=https://your-convex-url.convex.cloud
   ```

2. Configure Convex with the WorkOS Client ID

   In your app's `convex` folder, create a new file `auth.config.ts` with the following code. This is the server-side configuration for validating access tokens.

   convex/auth.config.ts

   TS

   ```
   const clientId = process.env.WORKOS_CLIENT_ID;

   const authConfig = {
     providers: [
       {
         type: 'customJwt',
         issuer: `https://api.workos.com/`,
         algorithm: 'RS256',
         applicationID: clientId,
         jwks: `https://api.workos.com/sso/jwks/${clientId}`,
       },
       {
         type: 'customJwt',
         issuer: `https://api.workos.com/user_management/${clientId}`,
         algorithm: 'RS256',
         jwks: `https://api.workos.com/sso/jwks/${clientId}`,
       },
     ],
   };

   export default authConfig;
   ```

3. Deploy your changes

   Run `npx convex dev` to automatically sync your configuration to your backend.

   You'll see an error and a link to click to fill in the WORKOS\_CLIENT\_ID environment variable in your Convex deployment. Follow the link, paste in the WorkOS client ID, save, and you should see the `npx convex dev` command show "Convex functions ready."

   ```
   npx convex dev
   ```

4. Install AuthKit

   In a new terminal window, install the AuthKit Next.js SDK:

   ```
   npm install @workos-inc/authkit-nextjs @convex-dev/workos
   ```

5. Add AuthKit middleware

   AuthKit's `authkitMiddleware()` helper grants you access to user authentication state throughout your app.

   Create a `middleware.ts` file.

   In your `middleware.ts` file, export the `authkitMiddleware()` helper:

   ```
   import { authkitMiddleware } from '@workos-inc/authkit-nextjs';

   export default authkitMiddleware({
     middlewareAuth: {
       enabled: true,
       unauthenticatedPaths: ['/', '/sign-in', '/sign-up'],
     },
   });

   export const config = {
     matcher: [
       // Skip Next.js internals and all static files, unless found in search params
       '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
       // Always run for API routes
       '/(api|trpc)(.*)',
     ],
   };
   ```

6. Add authentication routes

   Create the required authentication routes for WorkOS AuthKit to handle sign-in, sign-up, and callback flows.

   These routes enable the authentication flow by providing endpoints for users to sign in, sign up, and return after authentication.

   **Create the callback route** to handle OAuth callbacks:

   app/callback/route.ts

   TS

   ```
   import { handleAuth } from '@workos-inc/authkit-nextjs';

   export const GET = handleAuth();
   ```

7. Create the sign-in route

   app/sign-in/route.ts

   TS

   ```
   import { redirect } from 'next/navigation';
   import { getSignInUrl } from '@workos-inc/authkit-nextjs';

   export async function GET() {
     const authorizationUrl = await getSignInUrl();
     return redirect(authorizationUrl);
   }
   ```

8. Create the sign-up route

   To redirect users to WorkOS sign-up:

   app/sign-up/route.ts

   TS

   ```
   import { redirect } from 'next/navigation';
   import { getSignUpUrl } from '@workos-inc/authkit-nextjs';

   export async function GET() {
     const authorizationUrl = await getSignUpUrl();
     return redirect(authorizationUrl);
   }
   ```

9. Configure ConvexProviderWithAuthKit

   Your Next.js app needs to connect AuthKit authentication with Convex for real-time data. We'll create a single provider component that handles both.

   **Create the Provider Component**

   This single component handles:

   * WorkOS authentication setup
   * Convex client initialization
   * Token management between WorkOS and Convex
   * Loading states and error handling

   Create `components/ConvexClientProvider.tsx`:

   components/ConvexClientProvider.tsx

   TS

   ```
   'use client';

   import { ReactNode, useCallback, useRef } from 'react';
   import { ConvexReactClient } from 'convex/react';
   import { ConvexProviderWithAuth } from 'convex/react';
   import { AuthKitProvider, useAuth, useAccessToken } from '@workos-inc/authkit-nextjs/components';

   const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

   export function ConvexClientProvider({ children }: { children: ReactNode }) {
     return (
       <AuthKitProvider>
         <ConvexProviderWithAuth client={convex} useAuth={useAuthFromAuthKit}>
           {children}
         </ConvexProviderWithAuth>
       </AuthKitProvider>
     );
   }

   function useAuthFromAuthKit() {
     const { user, loading: isLoading } = useAuth();
     const { accessToken, loading: tokenLoading, error: tokenError } = useAccessToken();
     const loading = (isLoading ?? false) || (tokenLoading ?? false);
     const authenticated = !!user && !!accessToken && !loading;

     const stableAccessToken = useRef<string | null>(null);
     if (accessToken && !tokenError) {
       stableAccessToken.current = accessToken;
     }

     const fetchAccessToken = useCallback(async () => {
       if (stableAccessToken.current && !tokenError) {
         return stableAccessToken.current;
       }
       return null;
     }, [tokenError]);

     return {
       isLoading: loading,
       isAuthenticated: authenticated,
       fetchAccessToken,
     };
   }
   ```

10. Add to your layout

    Update `app/layout.tsx` to use the provider:

    app/layout.tsx

    TS

    ```
    import type { Metadata } from 'next';
    import { Geist, Geist_Mono } from 'next/font/google';
    import './globals.css';
    import { ConvexClientProvider } from '@/components/ConvexClientProvider';

    const geistSans = Geist({
      variable: '--font-geist-sans',
      subsets: ['latin'],
    });

    const geistMono = Geist_Mono({
      variable: '--font-geist-mono',
      subsets: ['latin'],
    });

    export const metadata: Metadata = {
      title: 'Create Next App',
      description: 'Generated by create next app',
      icons: {
        icon: '/convex.svg',
      },
    };

    export default function RootLayout({
      children,
    }: Readonly<{
      children: React.ReactNode;
    }>) {
      return (
        <html lang="en">
          <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
            <ConvexClientProvider>{children}</ConvexClientProvider>
          </body>
        </html>
      );
    }
    ```

11. Show UI based on authentication state

    You can control which UI is shown when the user is signed in or signed out using Convex's `<Authenticated>`, `<Unauthenticated>` and `<AuthLoading>` helper components. These should be used instead of WorkOS AuthKit's `useAuth()` loading states and manual authentication checks.

    It's important to use the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook instead of WorkOS AuthKit's `useAuth()` hook when you need to check whether the user is logged in or not. The `useConvexAuth()` hook makes sure that the browser has fetched the auth token needed to make authenticated requests to your Convex backend, and that the Convex backend has validated it.

    In the following example, the `<Content />` component is a child of `<Authenticated>`, so its content and any of its child components are guaranteed to have an authenticated user, and Convex queries can require authentication.

    app/page.tsx

    TS

    ```
    "use client";

    import { Authenticated, Unauthenticated, useQuery } from "convex/react";
    import { useAuth } from "@workos-inc/authkit-nextjs/components";
    import { api } from "../convex/_generated/api";
    import Link from "next/link";

    export default function Home() {
      const { user, signOut } = useAuth();

      return (
        <div className="p-4">
          <div className="flex justify-between items-center mb-4">
            <h1>Convex + AuthKit</h1>
            <div className="flex gap-2">
              {user ? (
                <button onClick={() => signOut()}>Sign out</button>
              ) : (
                <>
                  <Link href="/sign-in">
                    <button>Sign in</button>
                  </Link>
                  <Link href="/sign-up">
                    <button>Sign up</button>
                  </Link>
                </>
              )}
            </div>
          </div>
          <Authenticated>
            <Content />
          </Authenticated>
          <Unauthenticated>
            <p>Please sign in to view data</p>
          </Unauthenticated>
        </div>
      );
    }

    function Content() {
      const data = useQuery(api.myFunctions.listNumbers, { count: 10 });

      if (!data) return <p>Loading...</p>;

      return (
        <div>
          <p>Welcome {data.viewer}!</p>
          <p>Numbers: {data.numbers?.join(', ') || 'None'}</p>
        </div>
      );
    }
    ```

12. Use authentication state in your Convex functions

    If the client is authenticated, you can access the information stored in the JWT via `ctx.auth.getUserIdentity`.

    If the client isn't authenticated, `ctx.auth.getUserIdentity` will return `null`.

    **Make sure that the component calling this query is a child of `<Authenticated>` from `convex/react`**. Otherwise, it will throw on page load.

    convex/myFunctions.ts

    TS

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

    export const listNumbers = query({
      args: {
        count: v.number(),
      },
      handler: async (ctx, args) => {
        const numbers = await ctx.db
          .query("numbers")
          // Ordered by _creationTime, return most recent
          .order("desc")
          .take(args.count);
        return {
          viewer: (await ctx.auth.getUserIdentity())?.name ?? null,
          numbers: numbers.reverse().map((number) => number.value),
        };
      },
    });
    ```

**Note:** The [Next.js template repository](https://github.com/workos/template-convex-nextjs-authkit) includes additional features and functions for a complete working application. This tutorial covers the core integration steps, but the template provides a more comprehensive implementation.

## Next steps[​](#next-steps "Direct link to Next steps")

### Accessing user information in functions[​](#accessing-user-information-in-functions "Direct link to Accessing user information in functions")

See [Auth in Functions](/auth/functions-auth.md) to learn about how to access information about the authenticated user in your queries, mutations and actions.

See [Storing Users in the Convex Database](/auth/database-auth.md) to learn about how to store user information in the Convex database.

### Accessing user information client-side[​](#accessing-user-information-client-side "Direct link to Accessing user information client-side")

To access the authenticated user's information, use AuthKit's `User` object, which can be accessed using AuthKit's [`useAuth()`](https://github.com/workos/authkit-react?tab=readme-ov-file#useauth) hook. For more information on the `User` object, see the [WorkOS docs](https://workos.com/docs/reference/user-management/user).

components/Badge.tsx

TS

```
export default function Badge() {
  const { user } = useAuth();

  return <span>Logged in as {user.firstName}</span>;
}
```

## Configuring dev and prod instances[​](#configuring-dev-and-prod-instances "Direct link to Configuring dev and prod instances")

To configure a different AuthKit instance between your Convex development and production deployments, you can use environment variables configured on the Convex dashboard.

### Configuring the backend[​](#configuring-the-backend "Direct link to Configuring the backend")

In the WorkOS Dashboard, navigate to the [**API keys**](https://dashboard.workos.com/api-keys) page. Copy your WorkOS Client ID. This Client ID is necessary for Convex to validate access tokens from WorkOS AuthKit. In development, its format will be `client_01XXXXXXXXXXXXXXXXXXXXXXXX`. In production, it will follow the same format but represent your production WorkOS application.

Paste your WorkOS Client ID into your `.env` file, set it as the `WORKOS_CLIENT_ID` environment variable. Note that this environment variable is used server-side and does not need a `NEXT_PUBLIC_` prefix.

.env

```
WORKOS_CLIENT_ID=client_01XXXXXXXXXXXXXXXXXXXXXXXX
```

Then, update your `convex/auth.config.ts` file to use the environment variable:

convex/auth.config.ts

TS

```
const clientId = process.env.WORKOS_CLIENT_ID;

export default {
  providers: [
    {
      type: "customJwt",
      issuer: `https://api.workos.com/`,
      algorithm: "RS256",
      applicationID: clientId,
      jwks: `https://api.workos.com/sso/jwks/${clientId}`,
    },
    {
      type: "customJwt",
      issuer: `https://api.workos.com/user_management/${clientId}`,
      algorithm: "RS256",
      jwks: `https://api.workos.com/sso/jwks/${clientId}`,
    },
  ],
};
```

**Development configuration**

In the left sidenav of the Convex [dashboard](https://dashboard.convex.dev), switch to your development deployment and set the `WORKOS_CLIENT_ID` environment variable to your development WorkOS Client ID.

Then, to switch your deployment to the new configuration, run `npx convex dev`.

**Production configuration**

In the left sidenav of the Convex [dashboard](https://dashboard.convex.dev), switch to your production deployment and set the `WORKOS_CLIENT_ID` environment variable to your production WorkOS Client ID.

Then, to switch your deployment to the new configuration, run `npx convex deploy`.

### Configuring WorkOS AuthKit's API keys[​](#configuring-workos-authkits-api-keys "Direct link to Configuring WorkOS AuthKit's API keys")

WorkOS AuthKit's API keys differ depending on whether they are for development or production. Don't forget to update the environment variables in your `.env` file as well as your hosting platform, such as Vercel or Netlify.

**Development configuration**

WorkOS API Key for development follows the format `sk_test_...`. WorkOS Client ID for development follows the format `client_01...`.

.env.local

```
WORKOS_CLIENT_ID="client_01XXXXXXXXXXXXXXXXXXXXXXXX"
WORKOS_API_KEY="sk_test_..."
WORKOS_COOKIE_PASSWORD="your_secure_password_here_must_be_at_least_32_characters_long"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"
```

**Production configuration**

WorkOS API Key for production follows the format `sk_live_...`. WorkOS Client ID for production follows the format `client_01...`.

.env

```
WORKOS_CLIENT_ID="client_01XXXXXXXXXXXXXXXXXXXXXXXX"
WORKOS_API_KEY="sk_live_..."
WORKOS_COOKIE_PASSWORD="your_secure_password_here_must_be_at_least_32_characters_long"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="https://your-domain.com/callback"
```

### Additional WorkOS AuthKit Configuration[​](#additional-workos-authkit-configuration "Direct link to Additional WorkOS AuthKit Configuration")

WorkOS AuthKit requires additional configuration:

**Cookie Password**: A secure password used to encrypt session cookies. This must be at least 32 characters long. You can generate a random one with `openssl rand -base64 24`.

**Redirect URI**: The URL where users are redirected after authentication. This must be configured in both your environment variables and your WorkOS Dashboard application settings.

## Debugging authentication[​](#debugging-authentication "Direct link to Debugging authentication")

If a user goes through the WorkOS AuthKit login flow successfully, and after being redirected back to your page, `useConvexAuth()` returns `isAuthenticated: false`, it's possible that your backend isn't correctly configured.

The `convex/auth.config.ts` file contains a list of configured authentication providers. You must run `npx convex dev` or `npx convex deploy` after adding a new provider to sync the configuration to your backend.

Common issues with WorkOS AuthKit integration:

1. **Incorrect Client ID**: Ensure the `WORKOS_CLIENT_ID` in your Convex environment matches your WorkOS application
2. **Missing Environment Variables**: Verify all required WorkOS environment variables are set in both your local environment and Convex dashboard
3. **Redirect URI Mismatch**: Ensure the `NEXT_PUBLIC_WORKOS_REDIRECT_URI` matches what's configured in your WorkOS Dashboard
4. **Missing `aud` claim**: WorkOS JWTs may not include the `aud` (audience) claim by default, which Convex requires for token validation. Check your WorkOS Dashboard JWT configuration to ensure the audience claim is properly set to your Client ID

For more thorough debugging steps, see the WorkOS AuthKit documentation or [Debugging Authentication](/auth/debug.md).

## Under the hood[​](#under-the-hood "Direct link to Under the hood")

The authentication flow looks like this under the hood:

1. The user clicks a login button
2. The user is redirected to a page where they log in via whatever method you configure in
   <!-- -->
   AuthKit
3. After a successful login
   <!-- -->
   AuthKit
   <!-- -->
   redirects back to your page, or a different page which you configure via
   <!-- -->
   the
   <!-- -->
   [`redirectUri`](https://workos.com/docs/user-management/vanilla/nodejs/1-configure-your-project/configure-a-redirect-uri)
   <!-- -->
   prop
   <!-- -->
   .
4. The `AuthKitProvider` now knows that the user is authenticated.
5. The `ConvexProviderWithAuthKit` fetches an auth token from
   <!-- -->
   AuthKit
   <!-- -->
   .
6. The `ConvexReactClient` passes this token down to your Convex backend to validate
7. Your Convex backend retrieves the public key from
   <!-- -->
   AuthKit
   <!-- -->
   to check that the token's signature is valid.
8. The `ConvexReactClient` is notified of successful authentication, and `ConvexProviderWithAuthKit` now knows that the user is authenticated with Convex. `useConvexAuth` returns `isAuthenticated: true` and the `Authenticated` component renders its children.

`ConvexProviderWithAuthKit` takes care of refetching the token when needed to make sure the user stays authenticated with your backend.

---

# Source: https://docs.convex.dev/components/authoring.md

# Authoring Components

Building a Convex Component lets you package up Convex functions, schemas, and persistent state into a reusable module that you or other developers can drop into their projects.

They differ from regular libraries in that they have their own database tables, sub-transactions, and can define functions that run in an isolated environment.

Trying to decide between writing a library or a component? Building it as a component allows you to:

* Persist data to tables where you control the schema.
* Isolate access to data behind an API boundary.
* Define queries, mutations, and actions that can run asynchronously to manage complex workflows.
* Share functionality between apps in a predictable way.

## Anatomy of a component[​](#anatomy-of-a-component "Direct link to Anatomy of a component")

Practically speaking, a component is defined in a folder containing a `convex.config.ts`. The component's folder has the same structure as a normal `convex/` folder:

```
 component/
 ├── _generated/        # Generated code for the component's API and data model.
 ├── convex.config.ts   # Defines the component and its child components.
 ├── schema.ts          # Defines a schema only accessible by the component
 └-- …folders/files.ts  # Queries, mutations, and actions for the component.
```

The component's `convex.config.ts` file configures the component's default name and child components.

component/convex.config.ts

TS

```
import { defineComponent } from "convex/server";
// import workpool from "@convex-dev/workpool/convex.config.js";
// import localComponent from "../localComponent/convex.config.js";
const component = defineComponent("myComponent");
// component.use(workpool);
// component.use(localComponent, { name: "customName" });
export default component;
```

Instances of the component are configured when used by the main app or other components in their `convex.config.ts` files, forming a tree of components, with the main app at the root.

## Getting started[​](#getting-started "Direct link to Getting started")

The source code for components can be a local folder or bundled into an NPM package.

### Local components[​](#local-components "Direct link to Local components")

The easiest way to get started is by creating a new folder for your component and adding a `convex.config.ts` file to it (like the one above). Then import it in your app's `convex/convex.config.ts` file:

convex/convex.config.ts

TS

```
import { defineApp } from "convex/server";
import myComponent from "./components/myComponent/convex.config.js";

const app = defineApp();
app.use(myComponent);
export default app;
```

Once installed, `npx convex dev` will generate code in `./components/myComponent/_generated/` and re-generate it whenever you make changes to the component's code.

Tip: The recommended pattern for local components is to organize them in a `convex/components` folder, but they can be stored anywhere in your project.

### Packaged components[​](#packaged-components "Direct link to Packaged components")

Components can be distributed and installed as NPM packages, enabling you to share solutions to common problems with the broader developer community via the [Convex Components directory](https://convex.dev/components).

Get started with a new project using the [component template](https://github.com/get-convex/templates/tree/main/template-component):

```
npx create-convex@latest --component
```

Follow the CLI's instructions to get started and keep the component's generated code up-to-date. [See below for more information on building and publishing NPM package components.](#building-and-publishing-npm-package-components)

### Hybrid components[​](#hybrid-components "Direct link to Hybrid components")

Hybrid components define a local component, but use shared library code for some of the functionality. This allows you to provide a extra flexibility when users need to override or extend the schema or functions.

An example of a hybrid component is the [Better Auth Component](https://convex-better-auth.netlify.app/features/local-install).

Note: in general, components should be composed or designed to be extended explicitly, as hybrid components introduce a lot of complexity for maintaining and updating the component in backwards-compatible ways.

## Hello world[​](#hello-world "Direct link to Hello world")

To try adding a new function, create a file `hello.ts` in your component's folder (e.g. `src/component/hello.ts` in the template):

./path/to/component/hello.ts

TS

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

export const world = query({
  args: {},
  returns: v.string(),
  handler: async () => {
    return "hello world";
  },
});
```

After it deploys, you can run `npx convex run --component myComponent hello:world`.

You can now also run it from a function in your app:

convex/sayHi.ts

TS

```
import { components } from "./_generated/api";
import { query } from "./_generated/server";

export default query({
  handler: async (ctx) => {
    return await ctx.runQuery(components.myComponent.hello.world);
  },
});
```

Try it out: `npx convex run sayHi`.

## Key differences from regular Convex development[​](#key-differences-from-regular-convex-development "Direct link to Key differences from regular Convex development")

Developing a component is similar to developing the rest of your Convex backend. This section is a guide to the key concepts and differences.

### The Component API[​](#the-component-api "Direct link to The Component API")

When you access a component reference like `components.foo`, you're working with the `ComponentApi` type which has some key differences from the regular `api` object:

* **Only public functions are accessible**: Internal functions are not exposed to the parent app.
* **Functions become internal references**: The component's "public" queries, mutations, and actions are turned into references with "internal" visibility. They can be called with `ctx.runQuery`, `ctx.runMutation`, etc. but **not** directly accessible from clients via HTTP or WebSockets. See below for patterns to re-export functions from the component.
* **IDs become strings**: Any `Id<"tableName">` arguments or return values become plain strings in the `ComponentApi`. See next section for details.

Similar to regular Convex functions, you can call both public and internal functions via `npx convex run` and the Convex dashboard.

### `Id` types and validation[​](#id-types-and-validation "Direct link to id-types-and-validation")

All `Id<"table_name">` types within a component become simple string types outside of the component (in the `ComponentApi` type).

In addition, you cannot currently have a `v.id("table_name")` validator that represents a table in another component / app.

Why?

In Convex, a `v.id("table_name")` validator will check that an ID in an argument, return value, or database document matches the named table's format. Under the hood, this is currently encoded as a number assigned to each table in your schema.

Within a component’s implementation, the same applies to the component's tables. However, a `v.id("users")` within the component is not the same as `v.id("users")` in another component or in the main app, as each "users" table can have a different table number representation.

For this reason, all `Id` types in the `ComponentApi` become simple strings.

### Generated code[​](#generated-code "Direct link to Generated code")

Each component has its own `_generated` directory in addition to the `convex/_generated` directory. They are similar, but its contents are specific to the component and its schema. In general, code outside of the component should not import from this directory with the exception of `_generated/component`.

* `component.ts` is only generated for components, and contains the component's `ComponentApi` type.
* `server.ts` contains function builders like `query` and `mutation` to define your component's API. It's important that you import these when defining your component's functions, and not from `convex/_generated/server`. See below for more information on function visibility.
* `api.ts` contains the component's `api` and `internal` objects to reference the component's functions. It also includes the `components` object with references to its child components, if any. In general, no code outside of the component should import from this file. Instead, they should use their own `components` object which includes this component keyed by whatever name they chose to install it with.
* `dataModel.ts` contains the types for the component's data model. Note that the `Id` and `Doc` types here are not useful outside of the component, since the API turns all ID types into strings at the boundary.

### Environment variables[​](#environment-variables "Direct link to Environment variables")

The component's functions are isolated from the app's environment variables, so they cannot access `process.env`. Instead, you can pass environment variables as arguments to the component's functions.

```
return await ctx.runAction(components.sampleComponent.lib.translate, {
  baseUrl: process.env.BASE_URL,
  ...otherArgs,
});
```

See below for other strategies for static configuration.

### HTTP Actions[​](#http-actions "Direct link to HTTP Actions")

A component cannot expose HTTP actions itself because the routes could conflict with the main app's routes. Similar to other functions (queries, mutations, and actions), a component can define HTTP action handlers which the app can choose to mount. There’s an example in the [Twilio component](https://github.com/get-convex/twilio/blob/0bdf7fd4ee7dd46d442be3693280564eea597b68/src/client/index.ts#L71). All HTTP actions need to be mounted in the main app’s `convex/http.ts` file.

### Authentication via ctx.auth[​](#authentication-via-ctxauth "Direct link to Authentication via ctx.auth")

Within a component, `ctx.auth` is not available. You typically will do authentication in the app, then pass around identifiers like `userId` or other identifying information to the component.

This explicit passing makes it clear what data flows between the app and component, making your component easier to understand and test.

convex/myFunctions.ts

TS

```
import { getAuthUserId } from "@convex-dev/auth/server";

export const someMutation = mutation({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    await ctx.runMutation(components.myComponent.foo.bar, {
      userId,
      ...otherArgs,
    });
  },
});
```

### Function Handles[​](#function-handles "Direct link to Function Handles")

Sometimes you want the app to call a component and the component should call back into the app.

For example, when using the Migrations component, the app defines a function that modifies a document, and the component runs this function on every document. As another example, an app using the Twilio component gives it a function to run whenever the phone number receives a text message.

These features are implemented using function handles.

A function reference is something like api.foo.bar or `internal.foo.bar` or `components.counter.foo.bar`. Function references are restricted as described above (a component can only use references to its own functions or the public functions of its children). If you have a valid function reference, you can turn it into something that can be called from anywhere:

```
const handle = await createFunctionHandle(api.foo.bar);
```

This handle is a string.

Since it’s a string, you can pass it between functions and even store it in a table. You would use `v.string()` in args/schema validators.

When you want to use it, cast it back to FunctionHandle and use it as you would use a function reference. Note argument and return value validation still run at runtime, so don't worry about losing guarantees.

```
const handle = handleString as FunctionHandle<"mutation">;

const result = await ctx.runMutation(handle, args);
// or run it asynchronously via the scheduler:
await ctx.scheduler.runAfter(0, handle, args);
```

[Here](https://github.com/get-convex/workpool/blob/aebe2db49fc3ec50ded6892ed27f464450b3d31e/src/component/worker.ts#L26-L28) is an example of using function handles in the [Workpool](https://www.convex.dev/components/workpool) component.

### Pagination[​](#pagination "Direct link to Pagination")

The built-in `.paginate()` doesn't work in components, because of how Convex keeps track of reactive pagination. Therefore we recommend you use `paginator` from [`convex-helpers`](https://npmjs.com/package/convex-helpers) if you need pagination within your component.

If you expose a pagination API that wants to be used with `usePaginatedQuery`, in a React context, use the `usePaginatedQuery` from `convex-helpers` instead of the default one from `convex/react`. It will have a fixed first page size until you hit “load more,” at which point the first page will grow if anything before the second page is added.

[Here](https://github.com/get-convex/rag/blob/23fb22d593682e23d9134304e823f7532cbc7e67/src/component/chunks.ts#L437-L462) is an example of pagination in the [RAG](https://www.convex.dev/components/rag) component.

## Tips and best practices[​](#tips-and-best-practices "Direct link to Tips and best practices")

### Validation[​](#validation "Direct link to Validation")

All public component functions should have argument and return validators. Otherwise, the argument and return values will be typed as `any`. Below is an example of using validators.

```
import schema from "./schema";

const messageDoc = schema.tables.messages.validator.extend({
  _id: v.id("messages),
  _creationTime: v.number(),
});

export const getLatestMessage = query({
  args: {},
  returns: v.nullable(messageDoc),
  handler: async (ctx) => {
    return await ctx.db.query("messages").order("desc).first();
  },
});
```

Find out more information about function validation [here](/functions/validation.md).

### Static configuration[​](#static-configuration "Direct link to Static configuration")

A common pattern to track configuration in a component is to have a "globals" table with a single document that contains the configuration. You can then define functions to update this document from the CLI or from the app. To read the values, you can query them with `ctx.db.query("globals").first();`.

## Wrapping the component with client code[​](#wrapping-the-component-with-client-code "Direct link to Wrapping the component with client code")

When building a component, sometimes you want to provide a simpler API than directly calling `ctx.runMutation(components.foo.bar, ...)`, add more type safety, or provide functionality that spans the component's boundary.

You can hide calls to the component's functions behind a more ergonomic client API that runs within the app's environment and calls into the component.

This section covers conventions and approaches to writing client code. These aren't hard and fast rules; choose the pattern that best fits your component's needs.

Note: An important aspect of this pattern is that the code running in the app has access to `ctx.auth`, `process.env`, and other app-level resources. For many use-cases, this is important, such as running code to define migrations in the app, which are then run from the Migrations Component. On the other hand, apps that want really tight control over what code runs in their app may prefer to call the component's functions directly.

### Simple Function Wrappers[​](#simple-function-wrappers "Direct link to Simple Function Wrappers")

The simplest approach is to define standalone functions that wrap calls to the component. This works well for straightforward operations and utilities.

```
import type {
  GenericActionCtx,
  GenericDataModel,
  GenericMutationCtx,
} from "convex/server";
import type { ComponentApi } from "../component/_generated/component.js";

export async function callMyFunction(
  ctx: MutationCtx | ActionCtx,
  component: ComponentApi,
  args: ...
) {
  // You can create function handles, add shared utilities,
  // or do any processing that needs to run in the app's environment.
  const functionHandle = await createFunctionHandle(args.someFn);
  const someArg = process.env.SOME_ARG;
  await ctx.runMutation(component.call.fn, {
    ...args,
    someArg,
    functionHandle,
  });
}

// Useful types for functions that only need certain capabilities.
type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
type ActionCtx = Pick<
  GenericActionCtx<GenericDataModel>,
  "runQuery" | "runMutation" | "runAction"
>;
```

Note: we only use `ctx.runMutation`, so we can use `Pick` to select a type that only includes that function. This allows users to call it even if their `ctx` is not exactly the standard MutationCtx. It also means it can be called from an Action, as ActionCtx also includes `ctx.runMutation`. If your function also needs auth or storage, you can adjust what you `Pick`.

### Re-exporting component functions[​](#re-exporting-component-functions "Direct link to Re-exporting component functions")

Sometimes you want to provide ready-made functions that apps can directly re-export to their public API. This is useful when you want to give apps the ability to expose your component's functionality to React clients or the public internet.

The most straightforward way to do this is have the user define their own functions that call into the component.

This allows the app to choose to add auth, rate limiting, etc.

convex/counter.ts

TS

```
export const add = mutation({
  args: { value: v.number() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // The app can authenticate the user here if needed
    await ctx.runMutation(components.counter.add, args);
  },
});
```

This is the recommended pattern, as it makes it clear to the user how the request is being authenticated. However, if you need to re-export a lot of functions, you can use the next pattern.

#### Re-mounting an API[​](#re-mounting-an-api "Direct link to Re-mounting an API")

Code in your `src/client/index.ts` can export these functions:

```
import type { Auth } from "convex/server";

// In your component's src/client/index.ts
export function makeCounterAPI(
  component: ComponentApi,
  options: {
    // Important: provide a way for the user to authenticate these requests
    auth: (ctx: { auth: Auth }, operation: "read" | "write") => Promise<string>;
  },
) {
  return {
    add: mutation({
      args: { value: v.number() },
      handler: async (ctx, args) => {
        await options.auth(ctx, "write");
        return await ctx.runMutation(component.public.add, args);
      },
    }),

    get: query({
      args: {},
      handler: async (ctx) => {
        await options.auth(ctx, "read");
        return await ctx.runQuery(component.public.get, {});
      },
    }),
  };
}
```

Then apps can mount these in their own API:

```
// In the app's convex/counter.ts
import { makeCounterAPI } from "@convex-dev/counter";
import { components } from "./_generated/server.js";

export const { add, get } = makeCounterAPI(components.counter, {
  auth: async (ctx, operation) => {
    const userId = await getAuthUserId(ctx);
    // Check if the user has permission to perform the operation
    if (operation === "write" && !userId) {
      throw new Error("User not authenticated");
    }
    return userId;
  },
});
```

This pattern is also useful for components that need to provide functions with specific signatures for integration purposes.

Here's a real-world [example](https://github.com/get-convex/prosemirror-sync/blob/91e19d5e5a2a272d44f3a31c9171e111dc98676c/src/client/index.ts#L171C4-L173C6) from the [ProseMirror component](https://www.convex.dev/components/prosemirror-sync) that exports ready-made functions.

### Class-Based Clients[​](#class-based-clients "Direct link to Class-Based Clients")

For more complex components, a class-based client provides a stateful interface that can hold configuration and provide multiple methods.

**Basic class pattern:**

```
import Foo from "@convex-dev/foo";
import { components } from "./_generated/server.js";

const foo = new Foo(components.foo, {
  maxShards: 10,
});
```

**With configuration options:**

Classes typically accept the component reference as their first argument, with optional configuration as the second:

```
export class Foo {
  private apiKey: string;

  constructor(
    public component: ComponentApi,
    options?: {
      maxShards?: number;
      // Named after the environment variable it overrides, for clarity.
      FOO_AUTH_KEY?: string;
    },
  ) {
    this.apiKey = options?.FOO_AUTH_KEY ?? process.env.FOO_AUTH_KEY!;
  }

  async count(ctx: GenericQueryCtx<GenericDataModel>) {
    return await ctx.runQuery(this.component.public.count, {
      API_KEY: this.apiKey,
    });
  }
}
```

**Dynamic instantiation:** Note that clients don't need to be instantiated statically. If you need runtime values, you can create instances dynamically:

```
export const myQuery = query({
  handler: async (ctx, args) => {
    const foo = new Foo(components.foo, {
      apiKey: args.customApiKey,
    });
    await foo.count(ctx);
  },
});
```

## Building and publishing NPM package components[​](#building-and-publishing-npm-package-components "Direct link to Building and publishing NPM package components")

### Build process[​](#build-process "Direct link to Build process")

While developing a component that will be bundled, the example app that installs and exercises it will import the bundled version of the component. This helps ensure that the code you are testing matches the code that will be published.

However, that means `npx convex dev` cannot detect where the original source code is located for the component, and will not automatically generate the code for the component. When developing a component that will be bundled, you need to run a separate build process to generate the component's `_generated` directory.

The component authoring template will automatically generate the code for the component when running `npm run dev`. You can see the setup in the [template's `package.json` scripts](https://github.com/get-convex/templates/blob/main/template-component/package.json).

If you're setting up your own build process, you'll need to run the following commands with their own file watchers:

1. **Component codegen**: Generate code for the component itself

   ```
   npx convex codegen --component-dir ./path/to/component
   ```

2. **Build the package**: Build the NPM package

   ```
   npm run build # Your build command (e.g., tsc, esbuild, etc.)
   ```

3. **Example app codegen & deploy**: Generate code for the example app and deploy it app

   ```
   npx convex dev --typecheck-components # optionally type-check the components
   ```

**Note on ordering:** The ideal ordering is: component codegen → build the package → example app `convex dev` runs. This is a recommended convention followed by the template to avoid builds racing with each other, but the key requirement is that the component must be built and available before the example app tries to import it.

### Entry points[​](#entry-points "Direct link to Entry points")

When publishing a component on NPM, you will need to expose all the relevant entry points to be used in your project:

* `@your/package` exports types, classes, and constants used to interact with the component from within their app's code. This is optional, but common.
* `@your/package/convex.config.js` exposes the component's config.
* `@your/package/_generated/component.js` exports the `ComponentApi` type, which describes the component's types from the point of view of app it's used in.
* `@your/package/test` for utilities to use the component with `convex-test`.

[The template’s package.json](https://github.com/get-convex/templates/blob/main/template-component/package.json) does this for you, but if you're setting up your own build process, you'll need to set this up in your package.json.

### Local package resolution for development[​](#local-package-resolution-for-development "Direct link to Local package resolution for development")

When developing a component, you generally want to be importing the component's code in the same way that apps will import it, e.g. `import {} from "@your/package"`. To achieve this without having to install the package from NPM in the example app, follow the template's project structure:

1. In the root of the project, have the `package.json` with the package name matching the `@your/package` name. This causes imports for that name to resolve to the `package.json`’s `exports`.
2. In the `exports` section of the `package.json`, map the aforementioned entry points to the bundled files, generally in the `dist` directory. This means imports from the package name will resolve to the bundled files.
3. Have a single package.json file and node\_modules directory in the root of the project, so the example app will resolve to the package name by default. This will also avoid having multiple versions of `convex` referenced by the library vs. the example app. To add dependencies used only by the example app, add them as `devDependencies` in the `package.json`.

### Publishing to NPM[​](#publishing-to-npm "Direct link to Publishing to NPM")

To publish a component on NPM, check out [PUBLISHING.md](https://github.com/get-convex/templates/blob/main/template-component/PUBLISHING.md).

## Testing[​](#testing "Direct link to Testing")

### Testing implementations[​](#testing-implementations "Direct link to Testing implementations")

To test components, you can use the [`convex-test` library](/testing/convex-test.md). The main difference is that you must provide the schema and modules to the test instance.

component/some.test.ts

TS

```
import { test } from "vitest";
import { convexTest } from "convex-test";
import schema from "./schema.ts";
const modules = import.meta.glob("./**/*.ts");

export function initConvexTest() {
  const t = convexTest(schema, modules);
  return t;
}

test("Test something with a local component", async () => {
  const t = initConvexTest();
  // Test like you would normally.
  await t.run(async (ctx) => {
    await ctx.db.insert("myComponentTable", { name: "test" });
  });
});
```

If your component has child components, see the [Testing components](/components/using.md#testing-components) section in the Using Components documentation.

### Testing the API and client code[​](#testing-the-api-and-client-code "Direct link to Testing the API and client code")

To test the functions that are exported from the component to run in the app's environment, you can follow the same approach as in [Using Components](/components/using.md#testing-components) and test it from an app that uses the component.

The template component includes an example app in part for this purpose: to exercise the component's bundled code as it will be used by apps installing it.

### Exporting test helpers[​](#exporting-test-helpers "Direct link to Exporting test helpers")

Most components export testing helpers to make it easy to register the component with the test instance. Here is an example from the [template component’s `/test` entrypoint](https://github.com/get-convex/templates/blob/main/template-component/src/test.ts):

```
/// <reference types="vite/client" />
import type { TestConvex } from "convex-test";
import type { GenericSchema, SchemaDefinition } from "convex/server";
import schema from "./component/schema.js";
const modules = import.meta.glob("./component/**/*.ts");

/**
 * Register the component with the test convex instance.
 * @param t - The test convex instance, e.g. from calling `convexTest`.
 * @param name - The name of the component, as registered in convex.config.ts.
 */
export function register(
  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
  name: string = "sampleComponent",
) {
  t.registerComponent(name, schema, modules);
}
export default { register, schema, modules };
```

For NPM packages, this is exposed as `@your/package/test` in the package's `package.json`:

```
{
  ...
  "exports": {
    ...
    "./test": "./src/test.ts",
    ...
  }
}
```

---

# Source: https://docs.convex.dev/auth/authkit/auto-provision.md

# Automatic AuthKit Configuration

Convex can **create** AuthKit environments in a WorkOS account made on your behalf. By default WorkOS gives you only two environments, but giving each Convex dev deployment its own AuthKit environment is useful for isolating development user data and configuration changes between multiple developers or agents working in parallel.

The Convex CLI will **configure** AuthKit environments, regardless of whether Convex or you created them, if the `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` environment variables are present in the build environment or the Convex deployment. While developing locally, Convex can write environment variables to `.env.local` to make setting up an AuthKit environment a breeze.

## Getting Started[​](#getting-started "Direct link to Getting Started")

Choose AuthKit as your authentication option in the create convex tool.

```
npm create convex@latest
```

These templates include a `convex.json` which cause an AuthKit environment for this deployment to be created and configured. With just `npx convex dev` you'll get a WorkOS environment all hooked up!

### Going to production[​](#going-to-production "Direct link to Going to production")

In the Convex dashboard settings for your production deployment, create an AuthKit environment in the WorkOS Authentication integration under settings, integrations. Copy these credentials to your hosting provider environment variables (in addition to other setup, like adding a production `CONVEX_DEPLOY_KEY`, setting the build command, and setting other framework-specific AuthKit environment variables).

### Preview deployments[​](#preview-deployments "Direct link to Preview deployments")

In the Convex dashboard settings for any deployment in your project, create a new project-level AuthKit environment in the WorkOS Authentication integration under settings, integrations. Copy these credentials to your hosting provider environment variables (in addition to other setup, like adding a preview `CONVEX_DEPLOY_KEY`, setting the build command, and setting other framework-specific AuthKit environment variables).

## How it works[​](#how-it-works "Direct link to How it works")

AuthKit provisioning and configuration is triggered by the presence of a `convex.json` file with an `authKit` section with a property corresponding to the type of code push: `dev`, `preview`, or `prod`.

If this section is present, an AuthKit environment may be provisioned (dev only), local environment variables set (dev only), and configured (all code push types).

### Finding the AuthKit environment[​](#finding-the-authkit-environment "Direct link to Finding the AuthKit environment")

The CLI looks for WorkOS credentials `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` in the following order:

1. Environment variables in the build environment shell or `.env.local` file
2. Convex deployment environment variables

In remote build environments (e.g. building a project in Vercel, Netlify, Cloudflare) if these two environment variables are not found, the build will fail.

During local dev, credentials are next fetched from the Convex Cloud API for a new or existing AuthKit environment. A link to this deployment in the WorkOS dashboard can be found in the Convex dashboard under the WorkOS integration.

### Configuring the AuthKit environment[​](#configuring-the-authkit-environment "Direct link to Configuring the AuthKit environment")

Once credentials are found, the `WORKOS_API_KEY` is used to configure the environment based on the `configure` section of the relevant `authKit` object. This sets things like an environment's [redirect URIs](https://workos.com/docs/sso/redirect-uris), [allowed CORS origins](https://workos.com/docs/authkit/client-only).

### Setting local environment variables[​](#setting-local-environment-variables "Direct link to Setting local environment variables")

For dev deployments only, environment variables are written to `.env.local` based on the `localEnvVars` section of the relevant `authKit` config.

## Project-level vs deployment level AuthKit environments[​](#project-level-vs-deployment-level-authkit-environments "Direct link to Project-level vs deployment level AuthKit environments")

In hosting providers with remote build pipelines like Vercel, it's difficult to set environment variables like `WORKOS_API_KEY` at build time in a way that's available to server-side code like Next.js middleware. This makes it necessary set the `WORKOS_*` environment variables in advance for preview and production deployments built on these platforms.

After creating the WorkOS AuthKit environments for production and preview deployments in the dashboard, copy relevant environment variables like `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, `WORKOS_REDIRECT_URI`, and `WORKOS_COOKIE_PASSWORD` to the preview and production environment variables in your hosting provider.

Deployment-specific AuthKit environments can be created for any deployment are difficult set up automatically so shared project-level environments are generally a better fit.

In the `authKit` section of `convex.json`, `localEnvVars` `automate setting up dev environments by automatically setting the right environment variables in .env.local and automatically configuring the environment with a `redirectUri\`.

Environments for hosting providers in build environments like Vercel (production and preview deploys) can be configured at build time, but the environment variables for these build environments must be set manually in the build settings.

## Recommended Configuration[​](#recommended-configuration "Direct link to Recommended Configuration")

Here's a common setup for a project where production and preview deploys are deployed to from Vercel. Check your hosting provider's docs to substitute the right environment variables, and check the guide for using AuthKit with your framework of choice to customize this example.

convex.json

```
{
  "authKit": {
    "dev": {
      "configure": {
        "redirectUris": ["http://localhost:3000/callback"],
        "appHomepageUrl": "http://localhost:3000",
        "corsOrigins": ["http://localhost:3000"]
      },
      "localEnvVars": {
        "WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
        "WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
        "NEXT_PUBLIC_WORKOS_REDIRECT_URI": "http://localhost:3000/callback"
      }
    },
    "preview": {
      "configure": {
        "redirectUris": ["https://${buildEnv.VERCEL_BRANCH_URL}/callback"],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_BRANCH_URL}"]
      }
    },
    "prod": {
      "environmentType": "production",
      "configure": {
        "redirectUris": [
          "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}/callback"
        ],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}"]
      }
    }
  }
}
```

Additionally, for local dev in **Next.js** and **TanStack Start**, Convex automatically generates a `WORKOS_COOKIE_PASSWORD` if it's not already in `.env.local`.

---

# Source: https://docs.convex.dev/database/backup-restore.md

Convex supports Backup & Restore of data via the [dashboard](https://dashboard.convex.dev/deployment/settings/backups).

![Backups Page](/assets/images/backups-7e17da1541fc3eb26194a96ab33414ea.png)

# Backups

A backup is a consistent snapshot of your table data made at the time of your request. Backups can be configured to include file storage.

Take a manual backup by pressing the "Backup Now" button. This may take a few seconds to a few hours, depending on how much data is in your deployment.

Manual backups are stored for 7 days. You can download or delete backups via this page.

Deployment configuration and other data (code, environment variables, scheduled functions, etc.) will not be included.

### Periodic Backups[​](#periodic-backups "Direct link to Periodic Backups")

Schedule a periodic daily or weekly backup by checking the "Backup automatically" box. You can select what time of day / day of week to have the backup occur and whether to include file storage or not.

Daily backups are stored for 7 days. Weekly backups are stored for 14 days.

Periodic backups require a Convex Pro plan.

Periodic backups<!-- --> <!-- -->require<!-- --> a Convex Pro plan. [Learn more](https://convex.dev/pricing) about our plans or [upgrade](https://dashboard.convex.dev/team/settings/billing).

### Restoring from backup[​](#restoring-from-backup "Direct link to Restoring from backup")

Restore from a backup by selecting "Restore" from the submenu of an individual backup. You can restore from backups in the same deployment or from other deployments on the same team by using the deployment selector on the backups page. Restores may take a few seconds to a few hours depending on how much data is in your backup.

Note that restoring is a destructive operation that wipes your existing data and replaces it with that from the backup. It's recommended that you generate an additional backup before doing a restore.

Existing files in the deployment will not be deleted when restoring from a backup, but any files in the backup that do not currently exist in the deployment will be uploaded to the deployment.

### Restoring in an emergency[​](#restoring-in-an-emergency "Direct link to Restoring in an emergency")

If your production deployment ends up in a bad state, you may want to consider doing a restore to return to a good state. Note that getting your data to a good state may not be enough. Consider whether you may need each of the following actions. Depending on the nature of your emergency, these may be required.

* Take an additional backup prior to restore, since restores are destructive
* Do a restore from a good backup - to restore data
* Use `npx convex dev` to push a known version of good code.
* Use `npx convex env` or the dashboard to restore to a good set of env vars
* Use the dashboard to make any manual fixes to the database for your app.
* Write mutations to make required (more programmatic) manual fixes to the database for your app.

# Downloading a backup

You can download your manual and periodic backups from the dashboard via the download button in the menu.

Alternatively, you can generate an export in the same format with the [command line](/cli.md#export-data-to-a-file):

```
npx convex export --path ~/Downloads
```

The backup comes as a generated a ZIP file with all documents in all Convex tables in your deployment.

The ZIP file's name has the format `snapshot_{ts}.zip` where `ts` is a UNIX timestamp of the snapshot in nanoseconds. The export ZIP file contains documents for each table at `<table_name>/documents.jsonl`, with one document per line.

Exported ZIP files that include [file storage](/file-storage.md) will contain storage data in a `_storage` folder, with metadata like IDs and checksums in `_storage/documents.jsonl` and each file as `_storage/<id>`.

### Using the downloaded backup.[​](#using-the-downloaded-backup "Direct link to Using the downloaded backup.")

Downloaded ZIP files can be imported into the same deployment or a different deployment [with the CLI](/database/import-export/import.md#restore-data-from-a-backup-zip-file).

## FAQ[​](#faq "Direct link to FAQ")

### Are there any limitations?[​](#are-there-any-limitations "Direct link to Are there any limitations?")

Each backup is accessible for up to 7 days.

On the Free/Starter plan, up to two backups can stored per deployment at a time. Deployments on Convex Professional plan can have many backups with standard usage based pricing.

### How are they priced?[​](#how-are-they-priced "Direct link to How are they priced?")

Backups uses database bandwidth to read all documents, and file bandwidth to include user files. The generation and storage of the backup itself is billed with the same bandwidth and storage pricing as user file storage. You can observe this bandwidth and storage cost in the [usage dashboard](https://dashboard.convex.dev/team/settings/usage). Check the [limits docs](/production/state/limits.md#database) for pricing details.

### What does the backup not contain?[​](#what-does-the-backup-not-contain "Direct link to What does the backup not contain?")

The backup only contains the documents for your tables and files in file storage. In particular it lacks:

1. Your deployment's code and configuration. Convex functions, crons.ts, auth.config.js, schema.ts, etc. are configured in your source code.
2. Pending scheduled functions. You can access pending scheduled functions in the [`_scheduled_functions`](/database/advanced/system-tables.md) system table.
3. Environment variables. Environment variables can be copied from Settings in the Convex dashboard.

---

# Source: https://docs.convex.dev/understanding/best-practices.md

# Best Practices

This is a list of best practices and common anti-patterns around using Convex. We recommend going through this list before broadly releasing your app to production. You may choose to try using all of these best practices from the start, or you may wait until you've gotten major parts of your app working before going through and adopting the best practices here.

## Await all Promises[​](#await-all-promises "Direct link to Await all Promises")

### Why?[​](#why "Direct link to Why?")

Convex functions use async / await. If you don't await all your promises (e.g. `await ctx.scheduler.runAfter`, `await ctx.db.patch`), you may run into unexpected behavior (e.g. failing to schedule a function) or miss handling errors.

### How?[​](#how "Direct link to How?")

We recommend the [no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises/) rule of typescript-eslint.

## Avoid `.filter` on database queries[​](#avoid-filter-on-database-queries "Direct link to avoid-filter-on-database-queries")

### Why?[​](#why-1 "Direct link to Why?")

Filtering in code instead of using the `.filter` syntax has the same performance, and is generally easier code to write. Conditions in `.withIndex` or `.withSearchIndex` are more efficient than `.filter` or filtering in code, so almost all uses of `.filter` should either be replaced with a `.withIndex` or `.withSearchIndex` condition, or written as TypeScript code.

Read through the [indexes documentation](/database/reading-data/indexes/indexes-and-query-perf.md) for an overview of how to define indexes and how they work.

### Examples[​](#examples "Direct link to Examples")

convex/messages.ts

TS

```
// ❌
const tomsMessages = ctx.db
  .query("messages")
  .filter((q) => q.eq(q.field("author"), "Tom"))
  .collect();

// ✅
// Option 1: Use an index
const tomsMessages = await ctx.db
  .query("messages")
  .withIndex("by_author", (q) => q.eq("author", "Tom"))
  .collect();

// Option 2: Filter in code
const allMessages = await ctx.db.query("messages").collect();
const tomsMessages = allMessages.filter((m) => m.author === "Tom");
```

### How?[​](#how-1 "Direct link to How?")

Search for `.filter` in your Convex codebase — a regex like `\.filter\(\(?q` will probably find all the ones on database queries.

Decide whether they should be replaced with a `.withIndex` condition — per [this section](/understanding/best-practices/.md#only-use-collect-with-a-small-number-of-results), if you are filtering over a large (1000+) or potentially unbounded number of documents, you should use an index. If not using a `.withIndex` / `.withSearchIndex` condition, consider replacing them with a filter in code for more readability and flexibility.

See [this article](https://stack.convex.dev/complex-filters-in-convex) for more strategies for filtering.

### Exceptions[​](#exceptions "Direct link to Exceptions")

Using `.filter` on a paginated query (`.paginate`) has advantages over filtering in code. The paginated query will return the number of documents requested, including the `.filter` condition, so filtering in code afterwards can result in a smaller page or even an empty page. Using `.withIndex` on a paginated query will still be more efficient than a `.filter`.

## Only use `.collect` with a small number of results[​](#only-use-collect-with-a-small-number-of-results "Direct link to only-use-collect-with-a-small-number-of-results")

### Why?[​](#why-2 "Direct link to Why?")

All results returned from `.collect` count towards database bandwidth (even ones filtered out by `.filter`). It also means that if any document in the result changes, the query will re-run or the mutation will hit a conflict.

If there's a chance the number of results is large (say 1000+ documents), you should use an index to filter the results further before calling `.collect`, or find some other way to avoid loading all the documents such as using pagination, denormalizing data, or changing the product feature.

### Example[​](#example "Direct link to Example")

**Using an index:**

convex/movies.ts

TS

```
// ❌ -- potentially unbounded
const allMovies = await ctx.db.query("movies").collect();
const moviesByDirector = allMovies.filter(
  (m) => m.director === "Steven Spielberg",
);

// ✅ -- small number of results, so `collect` is fine
const moviesByDirector = await ctx.db
  .query("movies")
  .withIndex("by_director", (q) => q.eq("director", "Steven Spielberg"))
  .collect();
```

**Using pagination:**

convex/movies.ts

TS

```
// ❌ -- potentially unbounded
const watchedMovies = await ctx.db
  .query("watchedMovies")
  .withIndex("by_user", (q) => q.eq("user", "Tom"))
  .collect();

// ✅ -- using pagination, showing recently watched movies first
const watchedMovies = await ctx.db
  .query("watchedMovies")
  .withIndex("by_user", (q) => q.eq("user", "Tom"))
  .order("desc")
  .paginate(paginationOptions);
```

**Using a limit or denormalizing:**

convex/movies.ts

TS

```
// ❌ -- potentially unbounded
const watchedMovies = await ctx.db
  .query("watchedMovies")
  .withIndex("by_user", (q) => q.eq("user", "Tom"))
  .collect();
const numberOfWatchedMovies = watchedMovies.length;

// ✅ -- Show "99+" instead of needing to load all documents
const watchedMovies = await ctx.db
  .query("watchedMovies")
  .withIndex("by_user", (q) => q.eq("user", "Tom"))
  .take(100);
const numberOfWatchedMovies =
  watchedMovies.length === 100 ? "99+" : watchedMovies.length.toString();

// ✅ -- Denormalize the number of watched movies in a separate table
const watchedMoviesCount = await ctx.db
  .query("watchedMoviesCount")
  .withIndex("by_user", (q) => q.eq("user", "Tom"))
  .unique();
```

### How?[​](#how-2 "Direct link to How?")

Search for `.collect` in your Convex codebase (a regex like `\.collect\(` will probably find these). And think through whether the number of results is small. This function health page in the dashboard can also help surface these.

The [aggregate component](https://www.npmjs.com/package/@convex-dev/aggregate) or [database triggers](https://stack.convex.dev/triggers) can be helpful patterns for denormalizing data.

### Exceptions[​](#exceptions-1 "Direct link to Exceptions")

If you're doing something that requires loading a large number of documents (e.g. performing a migration, making a summary), you may want to use an action to load them in batches via separate queries / mutations.

## Check for redundant indexes[​](#check-for-redundant-indexes "Direct link to Check for redundant indexes")

### Why?[​](#why-3 "Direct link to Why?")

Indexes like `by_foo` and `by_foo_and_bar` are usually redundant (you only need `by_foo_and_bar`). Reducing the number of indexes saves on database storage and reduces the overhead of writing to the table.

convex/teams.ts

TS

```
// ❌
const allTeamMembers = await ctx.db
  .query("teamMembers")
  .withIndex("by_team", (q) => q.eq("team", teamId))
  .collect();
const currentUserId = /* get current user id from `ctx.auth` */
const currentTeamMember = await ctx.db
  .query("teamMembers")
  .withIndex("by_team_and_user", (q) =>
    q.eq("team", teamId).eq("user", currentUserId),
  )
  .unique();

// ✅
// Just don't include a condition on `user` when querying for results on `team`
const allTeamMembers = await ctx.db
  .query("teamMembers")
  .withIndex("by_team_and_user", (q) => q.eq("team", teamId))
  .collect();
const currentUserId = /* get current user id from `ctx.auth` */
const currentTeamMember = await ctx.db
  .query("teamMembers")
  .withIndex("by_team_and_user", (q) =>
    q.eq("team", teamId).eq("user", currentUserId),
  )
  .unique();
```

### How?[​](#how-3 "Direct link to How?")

Look through your indexes, either in your `schema.ts` file or in the dashboard, and look for any indexes where one is a prefix of another.

### Exceptions[​](#exceptions-2 "Direct link to Exceptions")

`.index("by_foo", ["foo"])` is really an index on the properties `foo` and `_creationTime`, while `.index("by_foo_and_bar", ["foo", "bar"])` is an index on the properties `foo`, `bar`, and `_creationTime`. If you have queries that need to be sorted by `foo` and then `_creationTime`, then you need both indexes.

For example, `.index("by_channel", ["channel"])` on a table of messages can be used to query for the most recent messages in a channel, but `.index("by_channel_and_author", ["channel", "author"])` could not be used for this since it would first sort the messages by `author`.

## Use argument validators for all public functions[​](#use-argument-validators-for-all-public-functions "Direct link to Use argument validators for all public functions")

### Why?[​](#why-4 "Direct link to Why?")

Public functions can be called by anyone, including potentially malicious attackers trying to break your app. [Argument validators](/functions/validation.md) (as well as return value validators) help ensure you're getting the traffic you expect.

### Example[​](#example-1 "Direct link to Example")

convex/movies.ts

TS

```
// ❌ -- `id` and `update` are not validated, so a client could pass
//       any Convex value (the type at runtime could mismatch the
//       TypeScript type). In particular, `update` could contain
//       fields other than `title` and `director`.
export const updateMovie = mutation({
  handler: async (
    ctx,
    {
      id,
      update,
    }: {
      id: Id<"movies">;
      update: Pick<Doc<"movies">, "title" | "director">;
    },
  ) => {
    await ctx.db.patch("movies", id, update);
  },
});

// ✅ -- This can only be called with an ID from the movies table,
//       and an `update` object with only the `title`/`director` fields
export const updateMovie = mutation({
  args: {
    id: v.id("movies"),
    update: v.object({
      title: v.string(),
      director: v.string(),
    }),
  },
  handler: async (ctx, { id, update }) => {
    await ctx.db.patch("movies", id, update);
  },
});
```

### How?[​](#how-4 "Direct link to How?")

Search for `query`, `mutation`, and `action` in your Convex codebase, and ensure that all of them have argument validators (and optionally return value validators).

You can also check automatically that your functions have argument validators with the [`@convex-dev/require-argument-validators` ESLint rule](/eslint.md#require-argument-validators).

If you use HTTP actions, you may want to use an argument validation library like [Zod](https://zod.dev) to validate that the HTTP request is the shape you expect.

## Use some form of access control for all public functions[​](#use-some-form-of-access-control-for-all-public-functions "Direct link to Use some form of access control for all public functions")

### Why?[​](#why-5 "Direct link to Why?")

Public functions can be called by anyone, including potentially malicious attackers trying to break your app. If portions of your app should only be accessible when the user is signed in, make sure all these Convex functions check that `ctx.auth.getUserIdentity()` is set.

You may also have specific checks, like only loading messages that were sent to or from the current user, which you'll want to apply in every relevant public function.

Favoring more granular functions like `setTeamOwner` over `updateTeam` allows more granular checks for which users can do what.

Access control checks should either use `ctx.auth.getUserIdentity()` or a function argument that is unguessable (e.g. a UUID, or a Convex ID, provided that this ID is never exposed to any client but the one user). In particular, don't use a function argument which could be spoofed (e.g. email) for access control checks.

### Example[​](#example-2 "Direct link to Example")

convex/teams.ts

TS

```
// ❌ -- no checks! anyone can update any team if they get the ID
export const updateTeam = mutation({
  args: {
    id: v.id("teams"),
    update: v.object({
      name: v.optional(v.string()),
      owner: v.optional(v.id("users")),
    }),
  },
  handler: async (ctx, { id, update }) => {
    await ctx.db.patch("teams", id, update);
  },
});

// ❌ -- checks access, but uses `email` which could be spoofed
export const updateTeam = mutation({
  args: {
    id: v.id("teams"),
    update: v.object({
      name: v.optional(v.string()),
      owner: v.optional(v.id("users")),
    }),
    email: v.string(),
  },
  handler: async (ctx, { id, update, email }) => {
    const teamMembers = /* load team members */
    if (!teamMembers.some((m) => m.email === email)) {
      throw new Error("Unauthorized");
    }
    await ctx.db.patch("teams", id, update);
  },
});

// ✅ -- checks access, and uses `ctx.auth`, which cannot be spoofed
export const updateTeam = mutation({
  args: {
    id: v.id("teams"),
    update: v.object({
      name: v.optional(v.string()),
      owner: v.optional(v.id("users")),
    }),
  },
  handler: async (ctx, { id, update }) => {
    const user = await ctx.auth.getUserIdentity();
    if (user === null) {
      throw new Error("Unauthorized");
    }
    const isTeamMember = /* check if user is a member of the team */
    if (!isTeamMember) {
      throw new Error("Unauthorized");
    }
    await ctx.db.patch("teams", id, update);
  },
});

// ✅ -- separate functions which have different access control
export const setTeamOwner = mutation({
  args: {
    id: v.id("teams"),
    owner: v.id("users"),
  },
  handler: async (ctx, { id, owner }) => {
    const user = await ctx.auth.getUserIdentity();
    if (user === null) {
      throw new Error("Unauthorized");
    }
    const isTeamOwner = /* check if user is the owner of the team */
    if (!isTeamOwner) {
      throw new Error("Unauthorized");
    }
    await ctx.db.patch("teams", id, { owner: owner });
  },
});

export const setTeamName = mutation({
  args: {
    id: v.id("teams"),
    name: v.string(),
  },
  handler: async (ctx, { id, name }) => {
    const user = await ctx.auth.getUserIdentity();
    if (user === null) {
      throw new Error("Unauthorized");
    }
    const isTeamMember = /* check if user is a member of the team */
    if (!isTeamMember) {
      throw new Error("Unauthorized");
    }
    await ctx.db.patch("teams", id, { name: name });
  },
});
```

### How?[​](#how-5 "Direct link to How?")

Search for `query`, `mutation`, `action`, and `httpAction` in your Convex codebase, and ensure that all of them have some form of access control. [Custom functions](https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/README.md#custom-functions) like [`authenticatedQuery`](https://stack.convex.dev/custom-functions#modifying-the-ctx-argument-to-a-server-function-for-user-auth) can be helpful.

Some apps use Row Level Security (RLS) to check access to each document automatically whenever it's loaded, as described in [this article](https://stack.convex.dev/row-level-security). Alternatively, you can check access in each Convex function instead of checking access for each document.

Helper functions for common checks and common operations can also be useful -- e.g. `isTeamMember`, `isTeamAdmin`, `loadTeam` (which throws if the current user does not have access to the team).

## Only schedule and `ctx.run*` internal functions[​](#only-schedule-and-ctxrun-internal-functions "Direct link to only-schedule-and-ctxrun-internal-functions")

### Why?[​](#why-6 "Direct link to Why?")

Public functions can be called by anyone, including potentially malicious attackers trying to break your app, and should be carefully audited to ensure they can't be used maliciously. Functions that are only called within Convex can be marked as internal, and relax these checks since Convex will ensure that internal functions can only be called within Convex.

### How?[​](#how-6 "Direct link to How?")

Search for `ctx.runQuery`, `ctx.runMutation`, and `ctx.runAction` in your Convex codebase. Also search for `ctx.scheduler` and check the `crons.ts` file. Ensure all of these use `internal.foo.bar` functions instead of `api.foo.bar` functions.

If you have code you want to share between a public Convex function and an internal Convex function, create a helper function that can be called from both. The public function will likely have additional access control checks.

Alternatively, make sure that `api` from `_generated/api.ts` is never used in your Convex functions directory.

### Examples[​](#examples-1 "Direct link to Examples")

convex/teams.ts

TS

```
// ❌ -- using `api`
export const sendMessage = mutation({
  args: {
    body: v.string(),
    author: v.string(),
  },
  handler: async (ctx, { body, author }) => {
    // add message to the database
  },
});

// crons.ts
crons.daily(
  "send daily reminder",
  { hourUTC: 17, minuteUTC: 30 },
  api.messages.sendMessage,
  { author: "System", body: "Share your daily update!" },
);

// ✅ Using `internal`
import { MutationCtx } from './_generated/server';
async function sendMessageHelper(
  ctx: MutationCtx,
  args: { body: string; author: string },
) {
  // add message to the database
}

export const sendMessage = mutation({
  args: {
    body: v.string(),
  },
  handler: async (ctx, { body }) => {
    const user = await ctx.auth.getUserIdentity();
    if (user === null) {
      throw new Error("Unauthorized");
    }
    await sendMessageHelper(ctx, { body, author: user.name ?? "Anonymous" });
  },
});

export const sendInternalMessage = internalMutation({
  args: {
    body: v.string(),
    // don't need to worry about `author` being spoofed since this is an internal function
    author: v.string(),
  },
  handler: async (ctx, { body, author }) => {
    await sendMessageHelper(ctx, { body, author });
  },
});

// crons.ts
crons.daily(
  "send daily reminder",
  { hourUTC: 17, minuteUTC: 30 },
  internal.messages.sendInternalMessage,
  { author: "System", body: "Share your daily update!" },
);
```

## Use helper functions to write shared code[​](#use-helper-functions-to-write-shared-code "Direct link to Use helper functions to write shared code")

### Why?[​](#why-7 "Direct link to Why?")

Most logic should be written as plain TypeScript functions, with the `query`, `mutation`, and `action` wrapper functions being a thin wrapper around one or more helper function.

Concretely, most of your code should live in a directory like `convex/model`, and your public API, which is defined with `query`, `mutation`, and `action`, should have very short functions that mostly just call into `convex/model`.

Organizing your code this way makes several of the refactors mentioned in this list easier to do.

See the [TypeScript page](/understanding/best-practices/typescript.md) for useful types.

### Example[​](#example-3 "Direct link to Example")

**❌** This example overuses `ctx.runQuery` and `ctx.runMutation`, which is discussed more in the [Avoid sequential `ctx.runMutation` / `ctx.runQuery` from actions](/understanding/best-practices/.md#avoid-sequential-ctxrunmutation--ctxrunquery-calls-from-actions) section.

convex/users.ts

TS

```
export const getCurrentUser = query({
  args: {},
  handler: async (ctx) => {
    const userIdentity = await ctx.auth.getUserIdentity();
    if (userIdentity === null) {
      throw new Error("Unauthorized");
    }
    const user = /* query ctx.db to load the user */
    const userSettings = /* load other documents related to the user */
    return { user, settings: userSettings };
  },
});
```

convex/conversations.ts

TS

```
export const listMessages = query({
  args: {
    conversationId: v.id("conversations"),
  },
  handler: async (ctx, { conversationId }) => {
    const user = await ctx.runQuery(api.users.getCurrentUser);
    const conversation = await ctx.db.get("conversations", conversationId);
    if (conversation === null || !conversation.members.includes(user._id)) {
      throw new Error("Unauthorized");
    }
    const messages = /* query ctx.db to load the messages */
    return messages;
  },
});

export const summarizeConversation = action({
  args: {
    conversationId: v.id("conversations"),
  },
  handler: async (ctx, { conversationId }) => {
    const messages = await ctx.runQuery(api.conversations.listMessages, {
      conversationId,
    });
    const summary = /* call some external service to summarize the conversation */
    await ctx.runMutation(api.conversations.addSummary, {
      conversationId,
      summary,
    });
  },
});
```

**✅** Most of the code here is now in the `convex/model` directory. The API for this application is in `convex/conversations.ts`, which contains very little code itself.

convex/model/users.ts

TS

```
import { QueryCtx } from '../_generated/server';

export async function getCurrentUser(ctx: QueryCtx) {
  const userIdentity = await ctx.auth.getUserIdentity();
  if (userIdentity === null) {
    throw new Error("Unauthorized");
  }
  const user = /* query ctx.db to load the user */
  const userSettings = /* load other documents related to the user */
  return { user, settings: userSettings };
}
```

convex/model/conversations.ts

TS

```
import { QueryCtx, MutationCtx } from '../_generated/server';
import * as Users from './users';

export async function ensureHasAccess(
  ctx: QueryCtx,
  { conversationId }: { conversationId: Id<"conversations"> },
) {
  const user = await Users.getCurrentUser(ctx);
  const conversation = await ctx.db.get("conversations", conversationId);
  if (conversation === null || !conversation.members.includes(user._id)) {
    throw new Error("Unauthorized");
  }
  return conversation;
}

export async function listMessages(
  ctx: QueryCtx,
  { conversationId }: { conversationId: Id<"conversations"> },
) {
  await ensureHasAccess(ctx, { conversationId });
  const messages = /* query ctx.db to load the messages */
  return messages;
}

export async function addSummary(
  ctx: MutationCtx,
  {
    conversationId,
    summary,
  }: { conversationId: Id<"conversations">; summary: string },
) {
  await ensureHasAccess(ctx, { conversationId });
  await ctx.db.patch("conversations", conversationId, { summary });
}

export async function generateSummary(
  messages: Doc<"messages">[],
  conversationId: Id<"conversations">,
) {
  const summary = /* call some external service to summarize the conversation */
  return summary;
}
```

convex/conversations.ts

TS

```
import * as Conversations from './model/conversations';

export const addSummary = internalMutation({
  args: {
    conversationId: v.id("conversations"),
    summary: v.string(),
  },
  handler: async (ctx, { conversationId, summary }) => {
    await Conversations.addSummary(ctx, { conversationId, summary });
  },
});

export const listMessages = internalQuery({
  args: {
    conversationId: v.id("conversations"),
  },
  handler: async (ctx, { conversationId }) => {
    return Conversations.listMessages(ctx, { conversationId });
  },
});

export const summarizeConversation = action({
  args: {
    conversationId: v.id("conversations"),
  },
  handler: async (ctx, { conversationId }) => {
    const messages = await ctx.runQuery(internal.conversations.listMessages, {
      conversationId,
    });
    const summary = await Conversations.generateSummary(
      messages,
      conversationId,
    );
    await ctx.runMutation(internal.conversations.addSummary, {
      conversationId,
      summary,
    });
  },
});
```

## Use `runAction` only when using a different runtime[​](#use-runaction-only-when-using-a-different-runtime "Direct link to use-runaction-only-when-using-a-different-runtime")

### Why?[​](#why-8 "Direct link to Why?")

Calling `runAction` has more overhead than calling a plain TypeScript function. It counts as an extra function call with its own memory and CPU usage, while the parent action is doing nothing except waiting for the result. Therefore, `runAction` should almost always be replaced with calling a plain TypeScript function. However, if you want to call code that requires Node.js from a function in the Convex runtime (e.g. using a library that requires Node.js), then you can use `runAction` to call the Node.js code.

### Example[​](#example-4 "Direct link to Example")

convex/scrape.ts

TS

```
// ❌ -- using `runAction`
export const scrapeWebsite = action({
  args: {
    siteMapUrl: v.string(),
  },
  handler: async (ctx, { siteMapUrl }) => {
    const siteMap = await fetch(siteMapUrl);
    const pages = /* parse the site map */
    await Promise.all(
      pages.map((page) =>
        ctx.runAction(internal.scrape.scrapeSinglePage, { url: page }),
      ),
    );
  },
});
```

convex/model/scrape.ts

TS

```
import { ActionCtx } from '../_generated/server';

// ✅ -- using a plain TypeScript function
export async function scrapeSinglePage(
  ctx: ActionCtx,
  { url }: { url: string },
) {
  const page = await fetch(url);
  const text = /* parse the page */
  await ctx.runMutation(internal.scrape.addPage, { url, text });
}
```

convex/scrape.ts

TS

```
import * as Scrape from './model/scrape';

export const scrapeWebsite = action({
  args: {
    siteMapUrl: v.string(),
  },
  handler: async (ctx, { siteMapUrl }) => {
    const siteMap = await fetch(siteMapUrl);
    const pages = /* parse the site map */
    await Promise.all(
      pages.map((page) => Scrape.scrapeSinglePage(ctx, { url: page })),
    );
  },
});
```

### How?[​](#how-7 "Direct link to How?")

Search for `runAction` in your Convex codebase, and see if the function it calls uses the same runtime as the parent function. If so, replace the `runAction` with a plain TypeScript function. You may want to structure your functions so the Node.js functions are in a separate directory so it's easier to spot these.

## Avoid sequential `ctx.runMutation` / `ctx.runQuery` calls from actions[​](#avoid-sequential-ctxrunmutation--ctxrunquery-calls-from-actions "Direct link to avoid-sequential-ctxrunmutation--ctxrunquery-calls-from-actions")

### Why?[​](#why-9 "Direct link to Why?")

Each `ctx.runMutation` or `ctx.runQuery` runs in its own transaction, which means if they're called separately, they may not be consistent with each other. If instead we call a single `ctx.runQuery` or `ctx.runMutation`, we're guaranteed that the results we get are consistent.

### How?[​](#how-8 "Direct link to How?")

Audit your calls to `ctx.runQuery` and `ctx.runMutation` in actions. If you see multiple in a row with no other code between them, replace them with a single `ctx.runQuery` or `ctx.runMutation` that handles both things. Refactoring your code to use helper functions will make this easier.

### Example: Queries[​](#example-queries "Direct link to Example: Queries")

convex/teams.ts

TS

```
// ❌ -- this assertion could fail if the team changed between running the two queries
const team = await ctx.runQuery(internal.teams.getTeam, { teamId });
const teamOwner = await ctx.runQuery(internal.teams.getTeamOwner, { teamId });
assert(team.owner === teamOwner._id);
```

convex/teams.ts

TS

```
import * as Teams from './model/teams';
import * as Users from './model/users';

export const sendBillingReminder = action({
  args: {
    teamId: v.id("teams"),
  },
  handler: async (ctx, { teamId }) => {
    // ✅ -- this will always pass
    const teamAndOwner = await ctx.runQuery(internal.teams.getTeamAndOwner, {
      teamId,
    });
    assert(teamAndOwner.team.owner === teamAndOwner.owner._id);
    // send a billing reminder email to the owner
  },
});

export const getTeamAndOwner = internalQuery({
  args: {
    teamId: v.id("teams"),
  },
  handler: async (ctx, { teamId }) => {
    const team = await Teams.load(ctx, { teamId });
    const owner = await Users.load(ctx, { userId: team.owner });
    return { team, owner };
  },
});
```

### Example: Loops[​](#example-loops "Direct link to Example: Loops")

convex/teams.ts

TS

```
import * as Users from './model/users';

export const importTeams = action({
  args: {
    teamId: v.id("teams"),
  },
  handler: async (ctx, { teamId }) => {
    // Fetch team members from an external API
    const teamMembers = await fetchTeamMemberData(teamId);

    // ❌ This will run a separate mutation for inserting each user,
    // which means you lose transaction guarantees like atomicity.
    for (const member of teamMembers) {
      await ctx.runMutation(internal.teams.insertUser, member);
    }
  },
});
export const insertUser = internalMutation({
  args: { name: v.string(), email: v.string() },
  handler: async (ctx, { name, email }) => {
    await Users.insert(ctx, { name, email });
  },
});
```

convex/teams.ts

TS

```
import * as Users from './model/users';

export const importTeams = action({
  args: {
    teamId: v.id("teams"),
  },
  handler: async (ctx, { teamId }) => {
    // Fetch team members from an external API
    const teamMembers = await fetchTeamMemberData(teamId);

    // ✅ This action runs a single mutation that inserts all users in the same transaction.
    await ctx.runMutation(internal.teams.insertUsers, teamMembers);
  },
});
export const insertUsers = internalMutation({
  args: { users: v.array(v.object({ name: v.string(), email: v.string() })) },
  handler: async (ctx, { users }) => {
    for (const { name, email } of users) {
      await Users.insert(ctx, { name, email });
    }
  },
});
```

### Exceptions[​](#exceptions-3 "Direct link to Exceptions")

If you're intentionally trying to process more data than fits in a single transaction, like running a migration or aggregating data, then it makes sense to have multiple sequential `ctx.runMutation` / `ctx.runQuery` calls.

Multiple `ctx.runQuery` / `ctx.runMutation` calls are often necessary because the action does a side effect in between them. For example, reading some data, feeding it to an external service, and then writing the result back to the database.

## Use `ctx.runQuery` and `ctx.runMutation` sparingly in queries and mutations[​](#use-ctxrunquery-and-ctxrunmutation-sparingly-in-queries-and-mutations "Direct link to use-ctxrunquery-and-ctxrunmutation-sparingly-in-queries-and-mutations")

### Why?[​](#why-10 "Direct link to Why?")

While these queries and mutations run in the same transaction, and will give consistent results, they have extra overhead compared to plain TypeScript functions. Wanting a TypeScript helper function is much more common than needing `ctx.runQuery` or `ctx.runMutation`.

### How?[​](#how-9 "Direct link to How?")

Audit your calls to `ctx.runQuery` and `ctx.runMutation` in queries and mutations. Unless one of the exceptions below applies, replace them with a plain TypeScript function.

### Exceptions[​](#exceptions-4 "Direct link to Exceptions")

* If you're using components, these require `ctx.runQuery` or `ctx.runMutation`.
* If you want partial rollback on an error, you will want `ctx.runMutation` instead of a plain TypeScript function.

convex/messages.ts

TS

```
export const trySendMessage = mutation({
  args: {
    body: v.string(),
    author: v.string(),
  },
  handler: async (ctx, { body, author }) => {
    try {
      await ctx.runMutation(internal.messages.sendMessage, { body, author });
    } catch (e) {
      // Record the failure, but rollback any writes from `sendMessage`
      await ctx.db.insert("failures", {
        kind: "MessageFailed",
        body,
        author,
        error: `Error: ${e}`,
      });
    }
  },
});
```

## Always include the table name when calling `ctx.db` functions[​](#always-include-the-table-name-when-calling-ctxdb-functions "Direct link to always-include-the-table-name-when-calling-ctxdb-functions")

### Why?[​](#why-11 "Direct link to Why?")

Since version 1.31.0 of the `convex` NPM package, the `ctx.db` functions accept a table name as the first argument. While this first argument is currently optional, passing the table name adds an additional safeguard which will be required for custom ID generation in the future.

### Example[​](#example-5 "Direct link to Example")

convex/movies.ts

TS

```
// ❌
await ctx.db.get(movieId);
await ctx.db.patch(movieId, { title: "Whiplash" });
await ctx.db.replace(movieId, {
  title: "Whiplash",
  director: "Damien Chazelle",
  votes: 0,
});
await ctx.db.delete(movieId);

// ✅            vvvvvvvv
await ctx.db.get("movies", movieId);
await ctx.db.patch("movies", movieId, { title: "Whiplash" });
await ctx.db.replace("movies", movieId, {
  title: "Whiplash",
  director: "Damien Chazelle",
  votes: 0,
});
await ctx.db.delete("movies", movieId);
```

### How?[​](#how-10 "Direct link to How?")

Search for calls of `db.get`, `db.patch`, `db.replace` and `db.delete` in your Convex codebase, and ensure that all of them pass a table name as the first argument.

You can also check automatically that a table name argument is passed with the [`@convex-dev/explicit-table-ids` ESLint rule](/eslint.md#explicit-table-ids).

You can migrate existing code automatically by using the autofix in the ESLint rule, or with the `@convex-dev/codemod` standalone tool.

[Learn more on news.convex.dev →](https://news.convex.dev/db-table-name/)

## Don’t use `Date.now()` in queries[​](#date-in-queries "Direct link to date-in-queries")

### Why?[​](#why-12 "Direct link to Why?")

When you subscribe to a query, Convex [will automatically run it again](/realtime.md) if the data that it accesses in the database change. The query is not re-run when `Date.now()` changes, because it wouldn’t be desirable to re-run a query every millisecond. So, if your query depends on the current time, it might return stale results.

Also, using `Date.now()` in a query can cause the Convex query cache to be invalidated more frequently than necessary. In general, Convex will automatically re-use Convex query results if the query is called with the same arguments. However, when using `Date.now()` in a query, the query cache will be invalidated frequently in order to avoid showing results that are too old. This will unnecessarily increase the work that the database has to do.

### Example[​](#example-6 "Direct link to Example")

convex/posts.ts

TS

```
// ❌
const releasedPosts = await ctx.db
  .query("posts")
  .withIndex("by_released_at", (q) => q.lte("releasedAt", Date.now()))
  .take(100);

// ✅
const releasedPosts = await ctx.db
  .query("posts")
  // `isReleased` is set to `true` by a scheduled function after `releasedAt` is reached
  .withIndex("by_is_released", (q) => q.eq("isReleased", true))
  .take(100);
```

### How?[​](#how-11 "Direct link to How?")

Search for usages of `Date.now()` in your Convex queries, or in functions that are called from a Convex query.

If you want to compare the current time with a timestamp stored in a database document, consider adding a coarser field to the document that you update from a [scheduled function](/scheduling/scheduled-functions.md) (see the example above). This way, the query cache is only invalidated explicitly when data changes.

Alternatively, you can pass in the target time in as an explicit argument from the client. For best caching results, the client should avoid changing this argument frequently, for instance by rounding the time down to the most recent minute, so all client requests within that minute use the same arguments.

---

# Source: https://docs.convex.dev/api/classes/browser.BaseConvexClient.md

# Class: BaseConvexClient

[browser](/api/modules/browser.md).BaseConvexClient

Low-level client for directly integrating state management libraries with Convex.

Most developers should use higher level clients, like the [ConvexHttpClient](/api/classes/browser.ConvexHttpClient.md) or the React hook based [ConvexReactClient](/api/classes/react.ConvexReactClient.md).

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new BaseConvexClient**(`address`, `onTransition`, `options?`)

#### Parameters[​](#parameters "Direct link to Parameters")

| Name           | Type                                                                                | Description                                                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`      | `string`                                                                            | The url of your Convex deployment, often provided by an environment variable. E.g. `https://small-mouse-123.convex.cloud`.                                       |
| `onTransition` | (`updatedQueries`: [`QueryToken`](/api/modules/browser.md#querytoken)\[]) => `void` | A callback receiving an array of query tokens corresponding to query results that have changed -- additional handlers can be added via `addOnTransitionHandler`. |
| `options?`     | [`BaseConvexClientOptions`](/api/interfaces/browser.BaseConvexClientOptions.md)     | See [BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md) for a full description.                                                        |

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/client.ts:277](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L277)

## Accessors[​](#accessors "Direct link to Accessors")

### url[​](#url "Direct link to url")

• `get` **url**(): `string`

Return the address for this client, useful for creating a new client.

Not guaranteed to match the address with which this client was constructed: it may be canonicalized.

#### Returns[​](#returns "Direct link to Returns")

`string`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/sync/client.ts:1037](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L1037)

## Methods[​](#methods "Direct link to Methods")

### getMaxObservedTimestamp[​](#getmaxobservedtimestamp "Direct link to getMaxObservedTimestamp")

▸ **getMaxObservedTimestamp**(): `undefined` | `Long`

#### Returns[​](#returns-1 "Direct link to Returns")

`undefined` | `Long`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/sync/client.ts:542](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L542)

***

### addOnTransitionHandler[​](#addontransitionhandler "Direct link to addOnTransitionHandler")

▸ **addOnTransitionHandler**(`fn`): () => `boolean`

Add a handler that will be called on a transition.

Any external side effects (e.g. setting React state) should be handled here.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name | Type                                   |
| ---- | -------------------------------------- |
| `fn` | (`transition`: `Transition`) => `void` |

#### Returns[​](#returns-2 "Direct link to Returns")

`fn`

▸ (): `boolean`

##### Returns[​](#returns-3 "Direct link to Returns")

`boolean`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/sync/client.ts:621](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L621)

***

### getCurrentAuthClaims[​](#getcurrentauthclaims "Direct link to getCurrentAuthClaims")

▸ **getCurrentAuthClaims**(): `undefined` | { `token`: `string` ; `decoded`: `Record`<`string`, `any`> }

Get the current JWT auth token and decoded claims.

#### Returns[​](#returns-4 "Direct link to Returns")

`undefined` | { `token`: `string` ; `decoded`: `Record`<`string`, `any`> }

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/sync/client.ts:630](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L630)

***

### setAuth[​](#setauth "Direct link to setAuth")

▸ **setAuth**(`fetchToken`, `onChange`): `void`

Set the authentication token to be used for subsequent queries and mutations. `fetchToken` will be called automatically again if a token expires. `fetchToken` should return `null` if the token cannot be retrieved, for example when the user's rights were permanently revoked.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name         | Type                                                           | Description                                                               |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `fetchToken` | [`AuthTokenFetcher`](/api/modules/browser.md#authtokenfetcher) | an async function returning the JWT-encoded OpenID Connect Identity Token |
| `onChange`   | (`isAuthenticated`: `boolean`) => `void`                       | a callback that will be called when the authentication status changes     |

#### Returns[​](#returns-5 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/sync/client.ts:655](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L655)

***

### hasAuth[​](#hasauth "Direct link to hasAuth")

▸ **hasAuth**(): `boolean`

#### Returns[​](#returns-6 "Direct link to Returns")

`boolean`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/sync/client.ts:662](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L662)

***

### clearAuth[​](#clearauth "Direct link to clearAuth")

▸ **clearAuth**(): `void`

#### Returns[​](#returns-7 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/sync/client.ts:672](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L672)

***

### subscribe[​](#subscribe "Direct link to subscribe")

▸ **subscribe**(`name`, `args?`, `options?`): `Object`

Subscribe to a query function.

Whenever this query's result changes, the `onTransition` callback passed into the constructor will be called.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name       | Type                                                              | Description                                                                                      |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `name`     | `string`                                                          | The name of the query.                                                                           |
| `args?`    | `Record`<`string`, [`Value`](/api/modules/values.md#value)>       | An arguments object for the query. If this is omitted, the arguments will be `{}`.               |
| `options?` | [`SubscribeOptions`](/api/interfaces/browser.SubscribeOptions.md) | A [SubscribeOptions](/api/interfaces/browser.SubscribeOptions.md) options object for this query. |

#### Returns[​](#returns-8 "Direct link to Returns")

`Object`

An object containing a [QueryToken](/api/modules/browser.md#querytoken) corresponding to this query and an `unsubscribe` callback.

| Name          | Type                                               |
| ------------- | -------------------------------------------------- |
| `queryToken`  | [`QueryToken`](/api/modules/browser.md#querytoken) |
| `unsubscribe` | () => `void`                                       |

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/sync/client.ts:691](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L691)

***

### localQueryResult[​](#localqueryresult "Direct link to localQueryResult")

▸ **localQueryResult**(`udfPath`, `args?`): `undefined` | [`Value`](/api/modules/values.md#value)

A query result based only on the current, local state.

The only way this will return a value is if we're already subscribed to the query or its value has been set optimistically.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name      | Type                                                        |
| --------- | ----------------------------------------------------------- |
| `udfPath` | `string`                                                    |
| `args?`   | `Record`<`string`, [`Value`](/api/modules/values.md#value)> |

#### Returns[​](#returns-9 "Direct link to Returns")

`undefined` | [`Value`](/api/modules/values.md#value)

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[browser/sync/client.ts:724](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L724)

***

### queryJournal[​](#queryjournal "Direct link to queryJournal")

▸ **queryJournal**(`name`, `args?`): `undefined` | [`QueryJournal`](/api/modules/browser.md#queryjournal)

Retrieve the current [QueryJournal](/api/modules/browser.md#queryjournal) for this query function.

If we have not yet received a result for this query, this will be `undefined`.

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name    | Type                                                        | Description                          |
| ------- | ----------------------------------------------------------- | ------------------------------------ |
| `name`  | `string`                                                    | The name of the query.               |
| `args?` | `Record`<`string`, [`Value`](/api/modules/values.md#value)> | The arguments object for this query. |

#### Returns[​](#returns-10 "Direct link to Returns")

`undefined` | [`QueryJournal`](/api/modules/browser.md#queryjournal)

The query's [QueryJournal](/api/modules/browser.md#queryjournal) or `undefined`.

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[browser/sync/client.ts:777](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L777)

***

### connectionState[​](#connectionstate "Direct link to connectionState")

▸ **connectionState**(): [`ConnectionState`](/api/modules/browser.md#connectionstate)

Get the current [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend.

#### Returns[​](#returns-11 "Direct link to Returns")

[`ConnectionState`](/api/modules/browser.md#connectionstate)

The [ConnectionState](/api/modules/browser.md#connectionstate) with the Convex backend.

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[browser/sync/client.ts:792](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L792)

***

### subscribeToConnectionState[​](#subscribetoconnectionstate "Direct link to subscribeToConnectionState")

▸ **subscribeToConnectionState**(`cb`): () => `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name | Type                                                                                        |
| ---- | ------------------------------------------------------------------------------------------- |
| `cb` | (`connectionState`: [`ConnectionState`](/api/modules/browser.md#connectionstate)) => `void` |

#### Returns[​](#returns-12 "Direct link to Returns")

`fn`

An unsubscribe function to stop listening.

▸ (): `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.

##### Returns[​](#returns-13 "Direct link to Returns")

`void`

An unsubscribe function to stop listening.

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[browser/sync/client.ts:838](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L838)

***

### mutation[​](#mutation "Direct link to mutation")

▸ **mutation**(`name`, `args?`, `options?`): `Promise`<`any`>

Execute a mutation function.

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name       | Type                                                            | Description                                                                                       |
| ---------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `name`     | `string`                                                        | The name of the mutation.                                                                         |
| `args?`    | `Record`<`string`, [`Value`](/api/modules/values.md#value)>     | An arguments object for the mutation. If this is omitted, the arguments will be `{}`.             |
| `options?` | [`MutationOptions`](/api/interfaces/browser.MutationOptions.md) | A [MutationOptions](/api/interfaces/browser.MutationOptions.md) options object for this mutation. |

#### Returns[​](#returns-14 "Direct link to Returns")

`Promise`<`any`>

* A promise of the mutation's result.

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[browser/sync/client.ts:858](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L858)

***

### action[​](#action "Direct link to action")

▸ **action**(`name`, `args?`): `Promise`<`any`>

Execute an action function.

#### Parameters[​](#parameters-8 "Direct link to Parameters")

| Name    | Type                                                        | Description                                                                         |
| ------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `name`  | `string`                                                    | The name of the action.                                                             |
| `args?` | `Record`<`string`, [`Value`](/api/modules/values.md#value)> | An arguments object for the action. If this is omitted, the arguments will be `{}`. |

#### Returns[​](#returns-15 "Direct link to Returns")

`Promise`<`any`>

A promise of the action's result.

#### Defined in[​](#defined-in-14 "Direct link to Defined in")

[browser/sync/client.ts:979](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L979)

***

### close[​](#close "Direct link to close")

▸ **close**(): `Promise`<`void`>

Close any network handles associated with this client and stop all subscriptions.

Call this method when you're done with an [BaseConvexClient](/api/classes/browser.BaseConvexClient.md) to dispose of its sockets and resources.

#### Returns[​](#returns-16 "Direct link to Returns")

`Promise`<`void`>

A `Promise` fulfilled when the connection has been completely closed.

#### Defined in[​](#defined-in-15 "Direct link to Defined in")

[browser/sync/client.ts:1026](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L1026)

---

# Source: https://docs.convex.dev/api/interfaces/browser.BaseConvexClientOptions.md

# Interface: BaseConvexClientOptions

[browser](/api/modules/browser.md).BaseConvexClientOptions

Options for [BaseConvexClient](/api/classes/browser.BaseConvexClient.md).

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* **`BaseConvexClientOptions`**

  ↳ [`ConvexReactClientOptions`](/api/interfaces/react.ConvexReactClientOptions.md)

## Properties[​](#properties "Direct link to Properties")

### unsavedChangesWarning[​](#unsavedchangeswarning "Direct link to unsavedChangesWarning")

• `Optional` **unsavedChangesWarning**: `boolean`

Whether to prompt the user if they have unsaved changes pending when navigating away or closing a web page.

This is only possible when the `window` object exists, i.e. in a browser.

The default value is `true` in browsers.

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/client.ts:69](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L69)

***

### webSocketConstructor[​](#websocketconstructor "Direct link to webSocketConstructor")

• `Optional` **webSocketConstructor**: `Object`

#### Call signature[​](#call-signature "Direct link to Call signature")

• **new webSocketConstructor**(`url`, `protocols?`): `WebSocket`

Specifies an alternate [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) constructor to use for client communication with the Convex cloud. The default behavior is to use `WebSocket` from the global environment.

##### Parameters[​](#parameters "Direct link to Parameters")

| Name         | Type                    |
| ------------ | ----------------------- |
| `url`        | `string` \| `URL`       |
| `protocols?` | `string` \| `string`\[] |

##### Returns[​](#returns "Direct link to Returns")

`WebSocket`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name         | Type        |
| ------------ | ----------- |
| `prototype`  | `WebSocket` |
| `CONNECTING` | `0`         |
| `OPEN`       | `1`         |
| `CLOSING`    | `2`         |
| `CLOSED`     | `3`         |

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/sync/client.ts:76](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L76)

***

### verbose[​](#verbose "Direct link to verbose")

• `Optional` **verbose**: `boolean`

Adds additional logging for debugging purposes.

The default value is `false`.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/sync/client.ts:82](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L82)

***

### logger[​](#logger "Direct link to logger")

• `Optional` **logger**: `boolean` | `Logger`

A logger, `true`, or `false`. If not provided or `true`, logs to the console. If `false`, logs are not printed anywhere.

You can construct your own logger to customize logging to log elsewhere. A logger is an object with 4 methods: log(), warn(), error(), and logVerbose(). These methods can receive multiple arguments of any types, like console.log().

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/sync/client.ts:91](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L91)

***

### reportDebugInfoToConvex[​](#reportdebuginfotoconvex "Direct link to reportDebugInfoToConvex")

• `Optional` **reportDebugInfoToConvex**: `boolean`

Sends additional metrics to Convex for debugging purposes.

The default value is `false`.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/sync/client.ts:97](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L97)

***

### onServerDisconnectError[​](#onserverdisconnecterror "Direct link to onServerDisconnectError")

• `Optional` **onServerDisconnectError**: (`message`: `string`) => `void`

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

▸ (`message`): `void`

This API is experimental: it may change or disappear.

A function to call on receiving abnormal WebSocket close messages from the connected Convex deployment. The content of these messages is not stable, it is an implementation detail that may change.

Consider this API an observability stopgap until higher level codes with recommendations on what to do are available, which could be a more stable interface instead of `string`.

Check `connectionState` for more quantitative metrics about connection status.

##### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name      | Type     |
| --------- | -------- |
| `message` | `string` |

##### Returns[​](#returns-1 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/sync/client.ts:111](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L111)

***

### skipConvexDeploymentUrlCheck[​](#skipconvexdeploymenturlcheck "Direct link to skipConvexDeploymentUrlCheck")

• `Optional` **skipConvexDeploymentUrlCheck**: `boolean`

Skip validating that the Convex deployment URL looks like `https://happy-animal-123.convex.cloud` or localhost.

This can be useful if running a self-hosted Convex backend that uses a different URL.

The default value is `false`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/sync/client.ts:121](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L121)

***

### authRefreshTokenLeewaySeconds[​](#authrefreshtokenleewayseconds "Direct link to authRefreshTokenLeewaySeconds")

• `Optional` **authRefreshTokenLeewaySeconds**: `number`

If using auth, the number of seconds before a token expires that we should refresh it.

The default value is `2`.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/sync/client.ts:127](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L127)

***

### expectAuth[​](#expectauth "Direct link to expectAuth")

• `Optional` **expectAuth**: `boolean`

This API is experimental: it may change or disappear.

Whether query, mutation, and action requests should be held back until the first auth token can be sent.

Opting into this behavior works well for pages that should only be viewed by authenticated clients.

Defaults to false, not waiting for an auth token.

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/sync/client.ts:139](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L139)

---

# Source: https://docs.convex.dev/api/classes/browser.ConvexClient.md

# Class: ConvexClient

[browser](/api/modules/browser.md).ConvexClient

Subscribes to Convex query functions and executes mutations and actions over a WebSocket.

Optimistic updates for mutations are not provided for this client. Third party clients may choose to wrap [BaseConvexClient](/api/classes/browser.BaseConvexClient.md) for additional control.

```
const client = new ConvexClient("https://happy-otter-123.convex.cloud");
const unsubscribe = client.onUpdate(api.messages.list, {}, (messages) => {
  console.log(messages[0].body);
});
```

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new ConvexClient**(`address`, `options?`)

Construct a client and immediately initiate a WebSocket connection to the passed address.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                 |
| --------- | -------------------------------------------------------------------- |
| `address` | `string`                                                             |
| `options` | [`ConvexClientOptions`](/api/modules/browser.md#convexclientoptions) |

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/simple\_client.ts:119](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L119)

## Accessors[​](#accessors "Direct link to Accessors")

### closed[​](#closed "Direct link to closed")

• `get` **closed**(): `boolean`

Once closed no registered callbacks will fire again.

#### Returns[​](#returns "Direct link to Returns")

`boolean`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/simple\_client.ts:96](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L96)

***

### client[​](#client "Direct link to client")

• `get` **client**(): [`BaseConvexClient`](/api/classes/browser.BaseConvexClient.md)

#### Returns[​](#returns-1 "Direct link to Returns")

[`BaseConvexClient`](/api/classes/browser.BaseConvexClient.md)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/simple\_client.ts:99](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L99)

***

### disabled[​](#disabled "Direct link to disabled")

• `get` **disabled**(): `boolean`

#### Returns[​](#returns-2 "Direct link to Returns")

`boolean`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/simple\_client.ts:110](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L110)

## Methods[​](#methods "Direct link to Methods")

### onUpdate[​](#onupdate "Direct link to onUpdate")

▸ **onUpdate**<`Query`>(`query`, `args`, `callback`, `onError?`): `Unsubscribe`<`Query`\[`"_returnType"`]>

Call a callback whenever a new result for a query is received. The callback will run soon after being registered if a result for the query is already in memory.

The return value is an Unsubscribe object which is both a function an an object with properties. Both of the patterns below work with this object:

```
// call the return value as a function
const unsubscribe = client.onUpdate(api.messages.list, {}, (messages) => {
  console.log(messages);
});
unsubscribe();

// unpack the return value into its properties
const {
  getCurrentValue,
  unsubscribe,
} = client.onUpdate(api.messages.list, {}, (messages) => {
  console.log(messages);
});
```

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name       | Type                                                                                                | Description                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `query`    | `Query`                                                                                             | A [FunctionReference](/api/modules/server.md#functionreference) for the public query to run.                                          |
| `args`     | [`FunctionArgs`](/api/modules/server.md#functionargs)<`Query`>                                      | The arguments to run the query with.                                                                                                  |
| `callback` | (`result`: [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>) => `unknown` | Function to call when the query result updates.                                                                                       |
| `onError?` | (`e`: `Error`) => `unknown`                                                                         | Function to call when the query result updates with an error. If not provided, errors will be thrown instead of calling the callback. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Unsubscribe`<`Query`\[`"_returnType"`]>

an Unsubscribe function to stop calling the onUpdate function.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/simple\_client.ts:185](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L185)

***

### onPaginatedUpdate\_experimental[​](#onpaginatedupdate_experimental "Direct link to onPaginatedUpdate_experimental")

▸ **onPaginatedUpdate\_experimental**<`Query`>(`query`, `args`, `options`, `callback`, `onError?`): `Unsubscribe`<`PaginatedQueryResult`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>\[]>>

Call a callback whenever a new result for a paginated query is received.

This is an experimental preview: the final API may change. In particular, caching behavior, page splitting, and required paginated query options may change.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name                      | Type                                                                                                                                                                  | Description                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `query`                   | `Query`                                                                                                                                                               | A [FunctionReference](/api/modules/server.md#functionreference) for the public query to run. |
| `args`                    | [`FunctionArgs`](/api/modules/server.md#functionargs)<`Query`>                                                                                                        | The arguments to run the query with.                                                         |
| `options`                 | `Object`                                                                                                                                                              | Options for the paginated query including initialNumItems and id.                            |
| `options.initialNumItems` | `number`                                                                                                                                                              | -                                                                                            |
| `callback`                | (`result`: [`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>) => `unknown` | Function to call when the query result updates.                                              |
| `onError?`                | (`e`: `Error`) => `unknown`                                                                                                                                           | Function to call when the query result updates with an error.                                |

#### Returns[​](#returns-4 "Direct link to Returns")

`Unsubscribe`<`PaginatedQueryResult`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>\[]>>

an Unsubscribe function to stop calling the callback.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/simple\_client.ts:263](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L263)

***

### close[​](#close "Direct link to close")

▸ **close**(): `Promise`<`void`>

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/simple\_client.ts:366](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L366)

***

### getAuth[​](#getauth "Direct link to getAuth")

▸ **getAuth**(): `undefined` | { `token`: `string` ; `decoded`: `Record`<`string`, `any`> }

Get the current JWT auth token and decoded claims.

#### Returns[​](#returns-6 "Direct link to Returns")

`undefined` | { `token`: `string` ; `decoded`: `Record`<`string`, `any`> }

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/simple\_client.ts:380](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L380)

***

### setAuth[​](#setauth "Direct link to setAuth")

▸ **setAuth**(`fetchToken`, `onChange?`): `void`

Set the authentication token to be used for subsequent queries and mutations. `fetchToken` will be called automatically again if a token expires. `fetchToken` should return `null` if the token cannot be retrieved, for example when the user's rights were permanently revoked.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name         | Type                                                           | Description                                                                      |
| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `fetchToken` | [`AuthTokenFetcher`](/api/modules/browser.md#authtokenfetcher) | an async function returning the JWT (typically an OpenID Connect Identity Token) |
| `onChange?`  | (`isAuthenticated`: `boolean`) => `void`                       | a callback that will be called when the authentication status changes            |

#### Returns[​](#returns-7 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/simple\_client.ts:393](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L393)

***

### mutation[​](#mutation "Direct link to mutation")

▸ **mutation**<`Mutation`>(`mutation`, `args`, `options?`): `Promise`<`Awaited`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>>

Execute a mutation function.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name       | Type                                                                                  |
| ---------- | ------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`> |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name       | Type                                                              | Description                                                                                      |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `mutation` | `Mutation`                                                        | A [FunctionReference](/api/modules/server.md#functionreference) for the public mutation to run.  |
| `args`     | [`FunctionArgs`](/api/modules/server.md#functionargs)<`Mutation`> | An arguments object for the mutation.                                                            |
| `options?` | [`MutationOptions`](/api/interfaces/browser.MutationOptions.md)   | A [MutationOptions](/api/interfaces/browser.MutationOptions.md) options object for the mutation. |

#### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<`Awaited`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>>

A promise of the mutation's result.

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[browser/simple\_client.ts:488](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L488)

***

### action[​](#action "Direct link to action")

▸ **action**<`Action`>(`action`, `args`): `Promise`<`Awaited`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>>

Execute an action function.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name     | Type                                                                                |
| -------- | ----------------------------------------------------------------------------------- |
| `Action` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"action"`> |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name     | Type                                                            | Description                                                                                   |
| -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `action` | `Action`                                                        | A [FunctionReference](/api/modules/server.md#functionreference) for the public action to run. |
| `args`   | [`FunctionArgs`](/api/modules/server.md#functionargs)<`Action`> | An arguments object for the action.                                                           |

#### Returns[​](#returns-9 "Direct link to Returns")

`Promise`<`Awaited`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>>

A promise of the action's result.

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[browser/simple\_client.ts:505](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L505)

***

### query[​](#query "Direct link to query")

▸ **query**<`Query`>(`query`, `args`): `Promise`<`Awaited`<`Query`\[`"_returnType"`]>>

Fetch a query result once.

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name    | Type                | Description                                                                                  |
| ------- | ------------------- | -------------------------------------------------------------------------------------------- |
| `query` | `Query`             | A [FunctionReference](/api/modules/server.md#functionreference) for the public query to run. |
| `args`  | `Query`\[`"_args"`] | An arguments object for the query.                                                           |

#### Returns[​](#returns-10 "Direct link to Returns")

`Promise`<`Awaited`<`Query`\[`"_returnType"`]>>

A promise of the query's result.

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[browser/simple\_client.ts:521](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L521)

***

### connectionState[​](#connectionstate "Direct link to connectionState")

▸ **connectionState**(): [`ConnectionState`](/api/modules/browser.md#connectionstate)

Get the current [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend.

#### Returns[​](#returns-11 "Direct link to Returns")

[`ConnectionState`](/api/modules/browser.md#connectionstate)

The [ConnectionState](/api/modules/browser.md#connectionstate) with the Convex backend.

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[browser/simple\_client.ts:553](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L553)

***

### subscribeToConnectionState[​](#subscribetoconnectionstate "Direct link to subscribeToConnectionState")

▸ **subscribeToConnectionState**(`cb`): () => `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name | Type                                                                                        |
| ---- | ------------------------------------------------------------------------------------------- |
| `cb` | (`connectionState`: [`ConnectionState`](/api/modules/browser.md#connectionstate)) => `void` |

#### Returns[​](#returns-12 "Direct link to Returns")

`fn`

An unsubscribe function to stop listening.

▸ (): `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.

##### Returns[​](#returns-13 "Direct link to Returns")

`void`

An unsubscribe function to stop listening.

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[browser/simple\_client.ts:568](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L568)

---

# Source: https://docs.convex.dev/api/classes/browser.ConvexHttpClient.md

# Class: ConvexHttpClient

[browser](/api/modules/browser.md).ConvexHttpClient

A Convex client that runs queries and mutations over HTTP.

This client is stateful (it has user credentials and queues mutations) so take care to avoid sharing it between requests in a server.

This is appropriate for server-side code (like Netlify Lambdas) or non-reactive webapps.

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new ConvexHttpClient**(`address`, `options?`)

Create a new [ConvexHttpClient](/api/classes/browser.ConvexHttpClient.md).

#### Parameters[​](#parameters "Direct link to Parameters")

| Name                                    | Type                                                                                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`                               | `string`                                                                                                                                                                     | The url of your Convex deployment, often provided by an environment variable. E.g. `https://small-mouse-123.convex.cloud`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `options?`                              | `Object`                                                                                                                                                                     | An object of options. - `skipConvexDeploymentUrlCheck` - Skip validating that the Convex deployment URL looks like `https://happy-animal-123.convex.cloud` or localhost. This can be useful if running a self-hosted Convex backend that uses a different URL. - `logger` - A logger or a boolean. If not provided, logs to the console. You can construct your own logger to customize logging to log elsewhere or not log at all, or use `false` as a shorthand for a no-op logger. A logger is an object with 4 methods: log(), warn(), error(), and logVerbose(). These methods can receive multiple arguments of any types, like console.log(). - `auth` - A JWT containing identity claims accessible in Convex functions. This identity may expire so it may be necessary to call `setAuth()` later, but for short-lived clients it's convenient to specify this value here. - `fetch` - A custom fetch implementation to use for all HTTP requests made by this client. |
| `options.skipConvexDeploymentUrlCheck?` | `boolean`                                                                                                                                                                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `options.logger?`                       | `boolean` \| `Logger`                                                                                                                                                        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `options.auth?`                         | `string`                                                                                                                                                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `options.fetch?`                        | (`input`: `URL` \| `RequestInfo`, `init?`: `RequestInit`) => `Promise`<`Response`>(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`<`Response`> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/http\_client.ts:97](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L97)

## Accessors[​](#accessors "Direct link to Accessors")

### url[​](#url "Direct link to url")

• `get` **url**(): `string`

Return the address for this client, useful for creating a new client.

Not guaranteed to match the address with which this client was constructed: it may be canonicalized.

#### Returns[​](#returns "Direct link to Returns")

`string`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/http\_client.ts:147](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L147)

## Methods[​](#methods "Direct link to Methods")

### backendUrl[​](#backendurl "Direct link to backendUrl")

▸ **backendUrl**(): `string`

Obtain the [ConvexHttpClient](/api/classes/browser.ConvexHttpClient.md)'s URL to its backend.

**`Deprecated`**

Use url, which returns the url without /api at the end.

#### Returns[​](#returns-1 "Direct link to Returns")

`string`

The URL to the Convex backend, including the client's API version.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/http\_client.ts:137](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L137)

***

### setAuth[​](#setauth "Direct link to setAuth")

▸ **setAuth**(`value`): `void`

Set the authentication token to be used for subsequent queries and mutations.

Should be called whenever the token changes (i.e. due to expiration and refresh).

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name    | Type     | Description                                |
| ------- | -------- | ------------------------------------------ |
| `value` | `string` | JWT-encoded OpenID Connect identity token. |

#### Returns[​](#returns-2 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/http\_client.ts:158](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L158)

***

### clearAuth[​](#clearauth "Direct link to clearAuth")

▸ **clearAuth**(): `void`

Clear the current authentication token if set.

#### Returns[​](#returns-3 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/http\_client.ts:184](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L184)

***

### consistentQuery[​](#consistentquery "Direct link to consistentQuery")

▸ **consistentQuery**<`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

This API is experimental: it may change or disappear.

Execute a Convex query function at the same timestamp as every other consistent query execution run by this HTTP client.

This doesn't make sense for long-lived ConvexHttpClients as Convex backends can read a limited amount into the past: beyond 30 seconds in the past may not be available.

Create a new client to use a consistent time.

**`Deprecated`**

This API is experimental: it may change or disappear.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name      | Type                                                                   | Description                                                                         |
| --------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `query`   | `Query`                                                                | -                                                                                   |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> | The arguments object for the query. If this is omitted, the arguments will be `{}`. |

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

A promise of the query's result.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/http\_client.ts:226](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L226)

***

### query[​](#query "Direct link to query")

▸ **query**<`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Execute a Convex query function.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name      | Type                                                                   | Description                                                                         |
| --------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `query`   | `Query`                                                                | -                                                                                   |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> | The arguments object for the query. If this is omitted, the arguments will be `{}`. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

A promise of the query's result.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/http\_client.ts:270](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L270)

***

### mutation[​](#mutation "Direct link to mutation")

▸ **mutation**<`Mutation`>(`mutation`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

Execute a Convex mutation function. Mutations are queued by default.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name       | Type                                                                                  |
| ---------- | ------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`> |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name       | Type                                                                                                                                        | Description                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `mutation` | `Mutation`                                                                                                                                  | -                                                                                      |
| `...args`  | [`ArgsAndOptions`](/api/modules/server.md#argsandoptions)<`Mutation`, [`HttpMutationOptions`](/api/modules/browser.md#httpmutationoptions)> | The arguments object for the mutation. If this is omitted, the arguments will be `{}`. |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

A promise of the mutation's result.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/http\_client.ts:430](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L430)

***

### action[​](#action "Direct link to action")

▸ **action**<`Action`>(`action`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

Execute a Convex action function. Actions are not queued.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name     | Type                                                                                |
| -------- | ----------------------------------------------------------------------------------- |
| `Action` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"action"`> |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name      | Type                                                                    | Description                                                                          |
| --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `action`  | `Action`                                                                | -                                                                                    |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Action`> | The arguments object for the action. If this is omitted, the arguments will be `{}`. |

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

A promise of the action's result.

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/http\_client.ts:453](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L453)

---

# Source: https://docs.convex.dev/api/interfaces/browser.MutationOptions.md

# Interface: MutationOptions

[browser](/api/modules/browser.md).MutationOptions

Options for [mutation](/api/classes/browser.BaseConvexClient.md#mutation).

## Properties[​](#properties "Direct link to Properties")

### optimisticUpdate[​](#optimisticupdate "Direct link to optimisticUpdate")

• `Optional` **optimisticUpdate**: [`OptimisticUpdate`](/api/modules/browser.md#optimisticupdate)<`any`>

An optimistic update to apply along with this mutation.

An optimistic update locally updates queries while a mutation is pending. Once the mutation completes, the update will be rolled back.

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/client.ts:210](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L210)

---

# Source: https://docs.convex.dev/api/interfaces/browser.OptimisticLocalStore.md

# Interface: OptimisticLocalStore

[browser](/api/modules/browser.md).OptimisticLocalStore

A view of the query results currently in the Convex client for use within optimistic updates.

## Methods[​](#methods "Direct link to Methods")

### getQuery[​](#getquery "Direct link to getQuery")

▸ **getQuery**<`Query`>(`query`, `...args`): `undefined` | [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>

Retrieve the result of a query from the client.

Important: Query results should be treated as immutable! Always make new copies of structures within query results to avoid corrupting data within the client.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                   | Description                                                                           |
| --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `query`   | `Query`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the query to get. |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> | The arguments object for this query.                                                  |

#### Returns[​](#returns "Direct link to Returns")

`undefined` | [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>

The query result or `undefined` if the query is not currently in the client.

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/optimistic\_updates.ts:28](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/optimistic_updates.ts#L28)

***

### getAllQueries[​](#getallqueries "Direct link to getAllQueries")

▸ **getAllQueries**<`Query`>(`query`): { `args`: [`FunctionArgs`](/api/modules/server.md#functionargs)<`Query`> ; `value`: `undefined` | [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`> }\[]

Retrieve the results and arguments of all queries with a given name.

This is useful for complex optimistic updates that need to inspect and update many query results (for example updating a paginated list).

Important: Query results should be treated as immutable! Always make new copies of structures within query results to avoid corrupting data within the client.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name    | Type    | Description                                                                           |
| ------- | ------- | ------------------------------------------------------------------------------------- |
| `query` | `Query` | A [FunctionReference](/api/modules/server.md#functionreference) for the query to get. |

#### Returns[​](#returns-1 "Direct link to Returns")

{ `args`: [`FunctionArgs`](/api/modules/server.md#functionargs)<`Query`> ; `value`: `undefined` | [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`> }\[]

An array of objects, one for each query of the given name. Each object includes:

* `args` - The arguments object for the query.
* `value` The query result or `undefined` if the query is loading.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/sync/optimistic\_updates.ts:49](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/optimistic_updates.ts#L49)

***

### setQuery[​](#setquery "Direct link to setQuery")

▸ **setQuery**<`Query`>(`query`, `args`, `value`): `void`

Optimistically update the result of a query.

This can either be a new value (perhaps derived from the old value from [getQuery](/api/interfaces/browser.OptimisticLocalStore.md#getquery)) or `undefined` to remove the query. Removing a query is useful to create loading states while Convex recomputes the query results.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type                                                                                      | Description                                                                           |
| ------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `query` | `Query`                                                                                   | A [FunctionReference](/api/modules/server.md#functionreference) for the query to set. |
| `args`  | [`FunctionArgs`](/api/modules/server.md#functionargs)<`Query`>                            | The arguments object for this query.                                                  |
| `value` | `undefined` \| [`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`> | The new value to set the query to or `undefined` to remove it from the client.        |

#### Returns[​](#returns-2 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/sync/optimistic\_updates.ts:69](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/optimistic_updates.ts#L69)

---

# Source: https://docs.convex.dev/api/interfaces/browser.SubscribeOptions.md

# Interface: SubscribeOptions

[browser](/api/modules/browser.md).SubscribeOptions

Options for [subscribe](/api/classes/browser.BaseConvexClient.md#subscribe).

## Properties[​](#properties "Direct link to Properties")

### journal[​](#journal "Direct link to journal")

• `Optional` **journal**: [`QueryJournal`](/api/modules/browser.md#queryjournal)

An (optional) journal produced from a previous execution of this query function.

If there is an existing subscription to a query function with the same name and arguments, this journal will have no effect.

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/client.ts:190](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L190)

---

# Source: https://docs.convex.dev/api/modules/browser.md

# Module: browser

Tools for accessing Convex in the browser.

**If you are using React, use the [react](/api/modules/react.md) module instead.**

## Usage[​](#usage "Direct link to Usage")

Create a [ConvexHttpClient](/api/classes/browser.ConvexHttpClient.md) to connect to the Convex Cloud.

```
import { ConvexHttpClient } from "convex/browser";
// typically loaded from an environment variable
const address = "https://small-mouse-123.convex.cloud";
const convex = new ConvexHttpClient(address);
```

## Classes[​](#classes "Direct link to Classes")

* [ConvexHttpClient](/api/classes/browser.ConvexHttpClient.md)
* [ConvexClient](/api/classes/browser.ConvexClient.md)
* [BaseConvexClient](/api/classes/browser.BaseConvexClient.md)

## Interfaces[​](#interfaces "Direct link to Interfaces")

* [BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md)
* [SubscribeOptions](/api/interfaces/browser.SubscribeOptions.md)
* [MutationOptions](/api/interfaces/browser.MutationOptions.md)
* [OptimisticLocalStore](/api/interfaces/browser.OptimisticLocalStore.md)

## Type Aliases[​](#type-aliases "Direct link to Type Aliases")

### HttpMutationOptions[​](#httpmutationoptions "Direct link to HttpMutationOptions")

Ƭ **HttpMutationOptions**: `Object`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name        | Type      | Description                                                                                                                                                                                                    |
| ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipQueue` | `boolean` | Skip the default queue of mutations and run this immediately. This allows the same HttpConvexClient to be used to request multiple mutations in parallel, something not possible with WebSocket-based clients. |

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/http\_client.ts:40](https://github.com/get-convex/convex-js/blob/main/src/browser/http_client.ts#L40)

***

### ConvexClientOptions[​](#convexclientoptions "Direct link to ConvexClientOptions")

Ƭ **ConvexClientOptions**: [`BaseConvexClientOptions`](/api/interfaces/browser.BaseConvexClientOptions.md) & { `disabled?`: `boolean` ; `unsavedChangesWarning?`: `boolean` }

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/simple\_client.ts:36](https://github.com/get-convex/convex-js/blob/main/src/browser/simple_client.ts#L36)

***

### AuthTokenFetcher[​](#authtokenfetcher "Direct link to AuthTokenFetcher")

Ƭ **AuthTokenFetcher**: (`args`: { `forceRefreshToken`: `boolean` }) => `Promise`<`string` | `null` | `undefined`>

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

▸ (`args`): `Promise`<`string` | `null` | `undefined`>

An async function returning a JWT. Depending on the auth providers configured in convex/auth.config.ts, this may be a JWT-encoded OpenID Connect Identity Token or a traditional JWT.

`forceRefreshToken` is `true` if the server rejected a previously returned token or the token is anticipated to expiring soon based on its `exp` time.

See ConvexReactClient.setAuth.

##### Parameters[​](#parameters "Direct link to Parameters")

| Name                     | Type      |
| ------------------------ | --------- |
| `args`                   | `Object`  |
| `args.forceRefreshToken` | `boolean` |

##### Returns[​](#returns "Direct link to Returns")

`Promise`<`string` | `null` | `undefined`>

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/sync/authentication\_manager.ts:25](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/authentication_manager.ts#L25)

***

### ConnectionState[​](#connectionstate "Direct link to ConnectionState")

Ƭ **ConnectionState**: `Object`

State describing the client's connection with the Convex backend.

#### Type declaration[​](#type-declaration-2 "Direct link to Type declaration")

| Name                          | Type             | Description                                                                                                                                                                                                                                                                         |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hasInflightRequests`         | `boolean`        | -                                                                                                                                                                                                                                                                                   |
| `isWebSocketConnected`        | `boolean`        | -                                                                                                                                                                                                                                                                                   |
| `timeOfOldestInflightRequest` | `Date` \| `null` | -                                                                                                                                                                                                                                                                                   |
| `hasEverConnected`            | `boolean`        | True if the client has ever opened a WebSocket to the "ready" state.                                                                                                                                                                                                                |
| `connectionCount`             | `number`         | The number of times this client has connected to the Convex backend. A number of things can cause the client to reconnect -- server errors, bad internet, auth expiring. But this number being high is an indication that the client is having trouble keeping a stable connection. |
| `connectionRetries`           | `number`         | The number of times this client has tried (and failed) to connect to the Convex backend.                                                                                                                                                                                            |
| `inflightMutations`           | `number`         | The number of mutations currently in flight.                                                                                                                                                                                                                                        |
| `inflightActions`             | `number`         | The number of actions currently in flight.                                                                                                                                                                                                                                          |

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/sync/client.ts:147](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L147)

***

### FunctionResult[​](#functionresult "Direct link to FunctionResult")

Ƭ **FunctionResult**: `FunctionSuccess` | `FunctionFailure`

The result of running a function on the server.

If the function hit an exception it will have an `errorMessage`. Otherwise it will produce a `Value`.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/sync/function\_result.ts:11](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/function_result.ts#L11)

***

### OptimisticUpdate[​](#optimisticupdate "Direct link to OptimisticUpdate")

Ƭ **OptimisticUpdate**<`Args`>: (`localQueryStore`: [`OptimisticLocalStore`](/api/interfaces/browser.OptimisticLocalStore.md), `args`: `Args`) => `void`

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name   | Type                                                                |
| ------ | ------------------------------------------------------------------- |
| `Args` | extends `Record`<`string`, [`Value`](/api/modules/values.md#value)> |

#### Type declaration[​](#type-declaration-3 "Direct link to Type declaration")

▸ (`localQueryStore`, `args`): `void`

A temporary, local update to query results within this client.

This update will always be executed when a mutation is synced to the Convex server and rolled back when the mutation completes.

Note that optimistic updates can be called multiple times! If the client loads new data while the mutation is in progress, the update will be replayed again.

##### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name              | Type                                                                      | Description                                        |
| ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------- |
| `localQueryStore` | [`OptimisticLocalStore`](/api/interfaces/browser.OptimisticLocalStore.md) | An interface to read and edit local query results. |
| `args`            | `Args`                                                                    | The arguments to the mutation.                     |

##### Returns[​](#returns-1 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/sync/optimistic\_updates.ts:90](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/optimistic_updates.ts#L90)

***

### PaginationStatus[​](#paginationstatus "Direct link to PaginationStatus")

Ƭ **PaginationStatus**: `"LoadingFirstPage"` | `"CanLoadMore"` | `"LoadingMore"` | `"Exhausted"`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/sync/pagination.ts:5](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/pagination.ts#L5)

***

### QueryJournal[​](#queryjournal "Direct link to QueryJournal")

Ƭ **QueryJournal**: `string` | `null`

A serialized representation of decisions made during a query's execution.

A journal is produced when a query function first executes and is re-used when a query is re-executed.

Currently this is used to store pagination end cursors to ensure that pages of paginated queries will always end at the same cursor. This enables gapless, reactive pagination.

`null` is used to represent empty journals.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/sync/protocol.ts:113](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/protocol.ts#L113)

***

### QueryToken[​](#querytoken "Direct link to QueryToken")

Ƭ **QueryToken**: `string` & { `__queryToken`: `true` }

A string representing the name and arguments of a query.

This is used by the [BaseConvexClient](/api/classes/browser.BaseConvexClient.md).

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/sync/udf\_path\_utils.ts:31](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/udf_path_utils.ts#L31)

***

### PaginatedQueryToken[​](#paginatedquerytoken "Direct link to PaginatedQueryToken")

Ƭ **PaginatedQueryToken**: [`QueryToken`](/api/modules/browser.md#querytoken) & { `__paginatedQueryToken`: `true` }

A string representing the name and arguments of a paginated query.

This is a specialized form of QueryToken used for paginated queries.

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[browser/sync/udf\_path\_utils.ts:38](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/udf_path_utils.ts#L38)

***

### UserIdentityAttributes[​](#useridentityattributes "Direct link to UserIdentityAttributes")

Ƭ **UserIdentityAttributes**: `Omit`<[`UserIdentity`](/api/interfaces/server.UserIdentity.md), `"tokenIdentifier"`>

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/authentication.ts:215](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L215)

---

# Source: https://docs.convex.dev/client/javascript/bun.md

# Source: https://docs.convex.dev/quickstart/bun.md

Learn how to query data from Convex in a Bun project.

For instructions for subscriptions instead of point-in-time queries see [Bun notes](/client/javascript/bun.md).

# Using Convex with Bun

1. Create a new Bun project

   Create a new directory for your Bun project.

   ```
   mkdir my-project && cd my-project && bun init -y
   ```

2. Install the Convex client and server library

   Install the `convex` package.

   ```
   bun add convex
   ```

3. Set up a Convex dev deployment

   Next, run `bunx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   bunx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   bunx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Connect the script to your backend

   In a new file `index.ts`, create a `ConvexClient` using the URL of your development environment.

   index.ts

   ```
   import { ConvexClient } from "convex/browser";
   import { api } from "./convex/_generated/api.js";

   const client = new ConvexClient(process.env["CONVEX_URL"]);

   const unsubscribe = client.onUpdate(api.tasks.get, {}, async (tasks) => {
     console.log(tasks);
   });

   await Bun.sleep(1000);
   unsubscribe();
   await client.close();
   ```

8. Run the script

   Run the script from the same directory and see the list of tasks logged to the terminal.

   ```
   bun index.ts
   ```

See the complete [Bun documentation](/client/javascript/bun.md).

---

# Source: https://docs.convex.dev/functions/bundling.md

# Bundling

Bundling is the process of gathering, optimizing and transpiling the JS/TS source code of [functions](/functions.md) and their dependencies. During development and when deploying, the code is transformed to a format that Convex [runtimes](/functions/runtimes.md) can directly and efficiently execute.

Convex currently bundles all dependencies automatically, but for the Node.js runtime you can disable bundling certain packages via the [external packages](#external-packages) config.

## Bundling for Convex[​](#bundling-for-convex "Direct link to Bundling for Convex")

When you push code either via `npx convex dev` or `npx convex deploy`, the Convex CLI uses [esbuild](https://esbuild.github.io/) to traverse your `convex/` folder and bundle your functions and all of their used dependencies into a source code bundle. This bundle is then sent to the server.

Thanks to bundling you can write your code using both modern ECMAScript Modules (ESM) or the older CommonJS (CJS) syntax.

ESM vs. CJS

ESM

* Is the standard for browser JavaScript
* Uses static imports via the `import` and `export` **keywords** (not functions) at the global scope
* Also supports dynamic imports via the asynchronous `import` function

CJS

* Was previously the standard module system for Node.js
* Relies on dynamic imports via the `require` and asynchronous `import` functions for fetching external modules
* Uses the `module.exports` object for exports

## Bundling limitations[​](#bundling-limitations "Direct link to Bundling limitations")

The nature of bundling comes with a few limitations.

### Code size limits[​](#code-size-limits "Direct link to Code size limits")

The total size of your bundled function code in your `convex/` folder is **limited to 32MiB (\~33.55MB)**. Other platform limits can be found [here](/production/state/limits.md).

While this limit in itself is quite high for just source code, certain dependencies can quickly make your bundle size cross over this limit, particularly if they are not effectively [tree-shakeable](https://webpack.js.org/guides/tree-shaking/) (such as [aws-sdk](https://www.npmjs.com/package/aws-sdk) or [snowflake-sdk](https://www.npmjs.com/package/snowflake-sdk))

You can follow these steps to debug bundle size:

1. Make sure you're using the most recent version of convex

   ```
   npm install convex@latest
   ```

2. Generate the bundle

   Note that this will not push code, and just generated a bundle for debugging purposes.

   ```
   npx convex dev --once --debug-bundle-path /tmp/myBundle
   ```

3. Visualize the bundle

   Use [source-map-explorer](https://github.com/danvk/source-map-explorer/tree/master) to visualize your bundle.

   ```
   npx source-map-explorer /tmp/myBundle/**/*.js
   ```

Code bundled for the Convex runtime will be in the `isolate` directory while code bundled for node actions will be in the `node` directory.

Large node dependencies can be eliminated from the bundle by marking them as [external packages](/functions/bundling.md#external-packages).

### Dynamic dependencies[​](#dynamic-dependencies "Direct link to Dynamic dependencies")

Some libraries rely on dynamic imports (via `import`/`require` calls) to avoid always including their dependencies. These imports are not supported by the [default Convex runtime](/functions/runtimes.md#default-convex-runtime) and will throw an error at runtime.

Additionally, some libraries rely on local files, which cannot be bundled by esbuild. If bundling is used, irrespective of the choice of runtime, these imports will always fail in Convex.

Examples of libraries with dynamic dependencies

Consider the following examples of packages relying on dynamic dependencies:

* [langchain](https://www.npmjs.com/package/langchain) relying on the presence of peer dependencies that it can dynamically import. These dependencies are not statically `import`ed so will not be bundled by `esbuild`.
* [sharp](https://www.npmjs.com/package/sharp) relying on the presence of `libvips` binaries for image-processing operations
* [pdf-parse](https://www.npmjs.com/package/pdf-parse) relies on being dynamically imported with `require()` in order to detect if it is being run in test mode. Bundling can eliminate these `require()` calls, making `pdf-parse` assume it is running in test mode.
* [tiktoken](https://www.npmjs.com/package/tiktoken) relying on local WASM files

## External packages[​](#external-packages "Direct link to External packages")

As a workaround for the bundling limitations above, Convex provides an escape hatch: **external packages**. This feature is currently exclusive to Convex's [Node.js runtime](/functions/runtimes.md#nodejs-runtime).

External packages use [`esbuild`'s facility for marking a dependency as external](https://esbuild.github.io/api/#external). This tells `esbuild` to not bundle the external dependency at all and to leave the import as a dynamic runtime import using `require()` or `import()`. Thus, your Convex modules will rely on the underlying system having that dependency made available at execution-time.

### Package installation on the server[​](#package-installation-on-the-server "Direct link to Package installation on the server")

Packages marked as external are installed from [npm](https://www.npmjs.com/) the first time you push code that uses them. The version installed matches the version installed in the `node_modules` folder on your local machine.

While this comes with a latency penalty the first time you push external packages, your packages are cached and this install step only ever needs to rerun if your external packages change. Once cached, pushes can actually be faster due to smaller source code bundles being sent to the server during pushes!

### Specifying external packages[​](#specifying-external-packages "Direct link to Specifying external packages")

Create a [`convex.json`](/production/project-configuration.md#convexjson) file in the same directory as your `package.json` if it does not exist already. Set the `node.externalPackages` field to `["*"]` to mark all dependencies used within your Node actions as external:

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "node": {
    "externalPackages": ["*"]
  }
}
```

Alternatively, you can explicitly specify which packages to mark as external:

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "node": {
    "externalPackages": ["aws-sdk", "sharp"]
  }
}
```

The package identifiers should match the string used in `import`/`require` in your [Node.js action](/functions/actions.md#choosing-the-runtime-use-node).

### Troubleshooting external packages[​](#troubleshooting-external-packages "Direct link to Troubleshooting external packages")

#### Incorrect package versions[​](#incorrect-package-versions "Direct link to Incorrect package versions")

The Convex CLI searches for external packages within your local `node_modules` directory. Thus, changing version of a package in the `package.json` will not affect the version used on the server until you've updated the package version installed in your local `node_modules` folder (e.g. running `npm install`).

#### Import errors[​](#import-errors "Direct link to Import errors")

Marking a dependency as external may result in errors like this:

> The requested module "some-module" is a CommonJs module, which may not support all module.exports as named exports. CommonJs modules can always be imported via the default export

This requires rewriting any imports for this module as follows:

```
// ❌ old
import { Foo } from "some-module";

// ✅ new
import SomeModule from "some-module";
const { Foo } = SomeModule;
```

### Limitations[​](#limitations "Direct link to Limitations")

The total size of your source code bundle and external packages cannot exceed the following:

* 45MB zipped
* 240MB unzipped

Packages that are known not to work at this time:

* [Puppeteer](https://www.npmjs.com/package/puppeteer) - browser binary installation exceeds the size limit
* [@ffmpeg.wasm](https://www.npmjs.com/package/@ffmpeg/ffmpeg) - since 0.12.0, [no longer supports Node environments](https://ffmpegwasm.netlify.app/docs/faq#why-ffmpegwasm-doesnt-support-nodejs)

If there is a package that you would like working in your Convex functions, [let us know](https://convex.dev/community).

---

# Source: https://docs.convex.dev/chef.md

# Chef

Chef is an AI app builder that builds complex full-stack apps. It leverages the full power of the Convex platform to one-shot apps like Slack, Instagram, and Notion.

This means Chef can: build real-time apps, upload files, do text search and take advantage of Convex Components.

## [Prompt to start an app with Convex Chef](https://chef.convex.dev)

![Chef Screenshot](/assets/images/chef_preview-dfe305b7d7ebb5910c22cf2c22a6842d.png)

## Deploying to production[​](#deploying-to-production "Direct link to Deploying to production")

Chef does have a built in ability to deploy the dev version of your app for you to immediately share with your friends to try.

For apps intended to be built and maintained over the long term, we recommend downloading the code and importing it into your preferred IDE. When you download the code from Chef, your project automatically comes with [Cursor rules for Convex](/ai.md), helping you keep coding with confidence.

### Download the code[​](#download-the-code "Direct link to Download the code")

![Chef Screenshot](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbgAAAAxCAYAAACoArwXAAABXWlDQ1BJQ0MgUHJvZmlsZQAAKJF1kE9LAlEUxc+UZZT9ISIIWsymRWExjGnQzgw0cjFZobUbx2kURn2ME9GuDxHt20TQB7DARUTtWgRCQatoVy2j2ZRM92mlFl24nB+Hex/nXaDDpzJmegDkC7aViC6IqY1N0fuEbgxjAD0YU7USCytKnEbwre3l3ELgWp3mb0n9gZeT1Gns8TJ5uHw1//x3vq16M3pJI/2gljVm2YAgESs7NuO8RzxiUSjifc5Gg485pxtcqc+sJSLEN8RDWlbNED8Q+9MtvtHCeXNb+8rA0/v0wvoq6Sj1OOKIQkQMi0iQJrFSZ/yzM1vfiaAIhl1YyMFAFjZthslhMKETL6EADTPwE8uQqIP81r9v2PSKU0DojeCi6an0p7M5ihlqehPXwGAVqASZaqk/lxUcT2krIDe4rwx0HbjuaxLwTgK1O9d9L7tu7QjovAfOnU+RKmSTCMrFsQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAABuKADAAQAAAABAAAAMQAAAAB2UVURAAAgCklEQVR4Ae1dB3hcxbX+pV2terfc5YJtXDDyM2AbMM2EXkMLHRJCQhJMCSm0hBpSCKEE00looZgAMb3XUIwM2Lhgy5J7kWXJsupK29/5R2/E9Xp3tXu14tnrOfpW9+7cqf+dmVPmzGxawO8JwZBBwCBgEDAIGARSDIH0FGuPaY5BwCBgEDAIGAQUAobBmY5gEDAIGAQMAimJgGFwKflaTaMMAgYBg4BBwDA40wcMAgYBg4BBICURMAwuJV+raZRBwCBgEDAIGAZn+oBBwCBgEDAIpCQChsGl5Gs1jTIIGAQMAgYBp4HAIGAQMAgYBAwCyULA7fHjy+WN+GZdK1ZuaEF9swftviAQCCEv24FBBZkYMzALE4dmYuK4IcjMzkxW0dvlkxbvRu+W5ha0u9vh8/kQCpm94dshuYsEpKWlISMjA7k5uSgoLLDV6l29LxkMbXWbmIkMpkAyMIgJcg8P19a78fq8Tfjg680IBkNSH0kQ9MMZEkNhhh8ubxAFPjcKWqqQuXkD1vhC8I2ajgMO3hOHTxmKYWU5PZSQ+OMeGZzP50dDQz3S0tNRVFiIrKysxEsxKVIKgc7OTvDT0dGBfv3KhOHFZwgwfenbbmAw/BaLZN31FlMKbnl5ecjMzFTMIln1suazZs0aDB8+3BqU1Hu7GPS2Ek+8vxavVNYKQwshHSFR1oTByZ8TAWQLDxnVVoW89fNR1dAB956HwFM6GkiXpyEH0tN8CAozPH5aOc6eMay3VdkmfY8Mrra2FtnZ2SgqKtomofliEGhqalJMbtCgQXGBYfrS9jAZDLfHpLchdjDNzRWLRIE9i0Qi9e1rBqfrkigGOl2iV2pt97+2Eis2tiqGlpaWjsygF1nBAIo7N2Jx5evo72mBO38wvMPGAsUjhK+5kJ4lWKe7RJAIIo3MUJS8kLDDyQU+nHlyBcrLchOtSsT4MRkcTUnBUNAwt4jQmUAisKmuDjlZ2T2aK01fit5fDIbRsbH7JBFMvT6vWCL62S0qoXTfFYNjpeLFIKEGWCIv29CK25+vQntnQJatgsgKBVDo34L+tVVoWb0YVa0NmLemCgHR6vxiqvSKSdIlypIodCjsNwxDxkzBoHEHwFVQKvZV0fuE0ZV1NCFQVIpLTx2LsUPyLaXZu41pW+KaW3Fxsb2cTapdAgGarbdu3dojgzN9KXp3MBhGx8buE4Mp1JJSPGPTDsZrG9yY9fxy+Ds7MKCjDrntjUjbuAxr61bivbXV2NLWjk6v+GvAL+txQYiLiVqXa/d2iEkSaFjbiIY1i7C88iUMmbAfdpt+ujib5AmjA9weH26bsxzXnT4B5f2y7VSvO03MbQJ0KDFrbt1YmZsICLB/sJ/0RKYvRUfIYBgdG7tPEsGUa26pSPFiYKftT760GPmbqzGu5kPkLnwL1etXYK67Fa8umY9NLU1o62xDlnhM0tMkKJqZM92BDKestwnL43dR12R1zofWljpUf/4iVnzwOBx+MVdKDIf893cE8dRrVXaqtk2amAzOeEtug5X5EgWBePpJPHGiZL9LBMeDTzxxdgmw4mxkPHgxDr0PU5XiwSDRtn/40jton3Mv6uvWoFq8IBvGn4CtDieWVL6JkM8jvCuAoGwJaG1zK+GXGpxXhGA/bZNC1OsCchXLpbAy0fHEvFkz/z101C2R9Ts3BnZuxfhN/4Xn5Ycx+7kPVRq7/2KaKO1matIZBAwCBgGDQOohsGFjPZ5cLLrXjIuEO2XA626Dv6EaNfPeQCeZmN+PkGwHoNe9Q5hXmtgjveJwgoD4VDpEoxPmR62Kvh2BEP0s6VxChc6Nuf++HeP3noqmgf+DTSMmw19+CGo2OLD/lg6Ul9ozVcbU4FLv9ZgW7QwIVFZWYty4ceDVUHIQIJYGz+RguSvn8u5SN/x5hUgXD8h0YWKuTAdqNyxH89ZNCHj9SBdtrSTTiWkDCnHEbgNw4MBCTOmXhzGyubtI1CmXMwNZYq50StoM+VB7TldmzHS0tG7BF44CeCYciFBeARxpYtYU55N3v260DXlSGdysu2fZrsjOkHD27Nn46KOP+qyqLS0tePzxx/HNN9/0WEZrayuqq6uVxNRj5DgifPLJJ3jqqafiiNm3UTgJn3feeaoQXpM5KTc2NqKqqgoej2ebRtClmrjzWarReeedr4SFWbPuAT8UHHakcZrK2KdaX+rwBvDJ0iakh1zi4i+sg9pZextaG2tFWwsiU1z+jxKmdu2Rk3HnOTNw80nTcc3Re+HCSSNxzPB+mFySj6GyLudyCFOTzd/pXaqb8p6kGTMgf6s31IiyF0IozSUfWb+TsE++aQDLtkNJNVHOumcWZl4y0049tklDz5/99ttvm7C99toL++yzD0499VQMG5bczYDbFBTjy6233ooZM2bgoIMOihHL/iMO9j/+8Y/4/e9/jwkTJkTM6NNPP5WJaha++uqr7ucnnXQSrr32WrVJtTswwZtXXnkF//nPf3DWWWclmDK50cnUyGys12XLlvWqkCVLluBXv/oVVq9e3Z3P97//ffzud79TmNXX1yvcb775ZowdK3t1dkJSGtrnlZg6bWp37YnhzItnCp6PdYfxhkyO8aZO/TbuNhHky3HHHYeampru4BEjRqgxecwxx2DKlCnd4b292dGxpzDAeS1emjp12nZ4x5s2nnh8d70dD/GUEynOwlUtXRqXg64iNDPKWpuYJD2yHcDn9+G8PYfjsiMrUDqiHNn5RWhv2IqAPG8XT8sOOb4rz5mOctlv6EvzYBM84mUpHpZ0NhFG5pSPWCzhcbslZ5W7mEBFwyMjFUMmy542NnGP/qQyuEig2AnTC6NkJmRobmk0X+qTTz6pPo888ggqKirsZL1Tp6GW9eMf/1hNwn/7298wdOhQxej+8pe/KK2PDIpmg52ZrIOXE7D1u512se+ccsopCrN//OMfar/T/PnzccMNNyjJkdjt7KS1XjIzammVlZ+rJlFQiMTEOAnHQwMHDlTCFtdVyOxef/11PP3006AgcNppp8WTxU4dh9rvVGHmifRBxRCFKSZD0A8Hj+853ncXnjYZ36tr24XXBJWbPx3/0+QUksxMlzrVKE/2wl6w3wQMHjUSaUUlCLkykO0NobNtlTAtPwpcDniEg9W1i+ekMENlmhQN0Cn7B5QmxwqK5tYpW9PoSZmRniHbCkRr4w5woepNncLg1G1C/3bo2XDUqFH43ve+h+OPPx6/+c1vlGTf3t6uJifdys2bN+O6667DIYccgqOOOkoNPpr6SL/+9a9x8cUX66iKOTLO8uXLVRjT8jsZA82C+v5nP/sZ9t57byXhxzJbxSqbBaxbtw6XXHIJpk+frup31VVXgaZFTTQx/vKXv1RlUXNaunSpfhTxSqbGExceeOABHHvssZg0aRJ+9KMfqUmI9Zw7d65KFwgE8Pe//x0nn3yyKps4hLfj4YcfxoknnqieMy5NBFbSbWPdGe+ee+4B8+0L4qRAyZSfcOKg1s/smNYWL16ssiSTY1uooZ1xxhm4//77MW3athM9LQd8X3z3p59+Or788svu6sR6l7rvcPKn1sT07KfE6+6771b4sX+yn9JMmkzSzI3MjJPqzJld/V0zNz4nbrwmSiUlJWr8HXnkkWocUcAcPXq06m96jDHPF198sbvdl19+OTTmfEYt+ec//7mKc/jhh6tx8Kc//UlNinweiebMmYMf/vCHCsef/vSneOedd1S0r7/+Wo1RPtfEelDbZB9ONlFQSJRRMX4iGl8idabwot9vIumSFXd9fYcwJmpVdA1xwimaXFZhPwwYtjtGFDjhkqO3gsLEOptkjvMH4OnoRFA8J0vzs5CTl40O0dZaZFN9wB+CxyvLBMoEKYxSriRxQYFDuB2FdAbxqj5S5vr6ThUn0X87NIMLb8wee+yBI444QjEjrqNQOiczevbZZ8HBs++++yomdumll6q1KR4h9e6776p4zOvNN99UZirNCDhgaLbabbfd1IDj/dVXX602t1N7fO6553DLLbeEV0N976lsMoyf/OQnoEnxzDPPVGZNDsw//OEPKj0H5i9+8QslFR999NFgXS+77LKIZTGQ+8g4kR544IGgZG0lMkea4dh+EiXse++9V515Ryb3/vvv44ILLsCmTZvUc6613XbbbeqewsPLL7+sJiAVIP94nh0Fg1dffRU/+MEPsOeee6qJ+s4779RRknrlhEApOZKkrLU4Tth2Jg4KSaS77roLxF8zGDIcYmOl22+/HS6XS/Ux9g1OrsS9p3dJvNh3brzxRpUdTcZOp1OZPSkYUBChkMB+OnPmzLj2DVrrFc99pZgnrcxOa24MJ268auLErZ/rsHiuhbKpn32ZpAWmN954A1deeaVq74UXXqj64fnnn4+NGzeqeLyy/910001qDHCsPfbYY6qPqghh/9jnKAjynFMyOaYnZhxH48ePB02aL730Uneqzz77TGmXEydO7A7b2W+0UGJthxZQ9HuzK7RY80z0vrHNh3SHHw5fEBmSOFe2BJQFW3HgqCGoKB+E9GzRyHKz4CgqFs9JBxZu7cBDi1bhwaoGPF5dj4/qW1Eva2kuObs2P0vO+5Q5ssuPUrRC0QiF/6F0wFA4ZOwI95OrAw7ZS+CU+8Z2e8J1r02UBDrcns+XwQGVqPQTD+Ds5G+99RZWrFiBOjkmipM+Bw8nYlL//v2VNKcn/IceekgNOg4A1ovMgYOCkvbChQtVGjJOfc8BfP3116twTlKcFCnZh5/o8vnnn8csm1rHNddcg/LycowcOVLlx0nw448/VvccsNQKuN529tlnq7DBgweD9dUmWhX4f/+YlkQJOpwoATkclH+A5uZmPPPMM0qq1UyMa4bnnnsuXnvtNcXoyCyIAyVyHi5LLZBrK9Q6SBQAFi1apHCkQEGiNsK6UULXZakH39E/PbATLa60tBRcO/3tb3+rJk6mJ4Y0sVEw4AG7mihoUEsmcTJ/9NFHsWrVKiUoxHqXOj0ZG7UTEgUY4nvOOecoLYZh7AecvNlnyfSSQcSFggHNaWRkWnPTeXNsil7XvTbH8UpTpl3afffdVVJaQbgWd9999ymt+MEHH1RMjpYF9hmaM2lO10SNmfHZty+66CI8//zz3e9Dx+GV+XDMkAlyozLxO+yww9S72H///ZU1h/2b+PLsSDJPWjWonacCcY7S68/W9oRrb3yvOp7dsWHNP557jy+AHNnKVupvRHDtUjQ31QNyzFa7owiOnGK8Wt2A4W1L0K8oHwuWrcdHGxrxxao6sVp1qveujl8WppYla3GcQ8TZUvbNeYW10V9FWJ14V6aJFsh1N6dsI3Dw4/DK3jgf8ju75rd46mmN02sGZwWaGUd7QdZCe3PPjk3iBMTOTaJWo+nggw9WEzMH/QknnKCCKY1zHYHECZqTDL+zrjSBkpFpoiOLpsmTJysGR3NdOIPjJEWKVjYnMDJOao1PPPGEGpAsT5NewD/00EN1kBrIZCKRiIyI1NbWFulxd5jWgqiBaqLJjESmpbUNmul0ngMGDFDmIO0hSuGARE2PExVJX1euXIkxY8aosJ3lH/sBNTZq82TeNKmREVGo0QyNbbG+e73GS4GBJ13EepcahwMOOEDfdmuj//rXv7BlyxYVTuxINEUni8GpDOWfMqcJ4wqf7Phdh7H/aW1Zp0v0qvtffn6+6ktak+MSgpWsZkoyIO2YQmGM1hb2NeKRk5PTnYx9k/mxb5K5kTjuWH89dshAyeAoIDKft99+GxRMUuU0EsXIIrzHLq37sW6siIlec3388ejOQt0JknBTXP0Ocr1erJM1taxxU+AdMw2NngAWvzwLjWtXwet1Y/+KcSjJdeObRVWoaWyRE008Yq2UzdwBmiLFsCmMjet3DvGidImJ0+PnfrkAijJzxMQZQj9xPhnZUoNiMW0OdYjW1t6M5vp1CMlZlsCUhFvx7cyecNKuBASaUiOlCVJfSxVkVhww1Ha0u7dVCtfMis/4Kwg029GpgCZFSoDaA/KLL74A8+K6iJV0eoZZ761xeN9T2ZzUOLHyyrW9IUOGbJOFTk+TmCbdDm2T1uG8UuNiuzUDsz6jOWf9+vUgo9L56rwYj3ZspvVK5+SHZH0e/p0TDYnmJKYjUSon5nriUYF9+C/Zi+mU9qlh8UMzNCdRmsO0WZFNifQuGN7Tu2QckrW/aAypjdAZiMQDfanF9cXPpegxGG5NUQXLPzIIPTZ1mJ2rFn5oSbEe0abbyDwpXFm9oMP7jMaZfdHK4HR+VhyZH5kXrQs0FdObmlo5hVviyXBaH1KFuMbG92R9j3x34eNBCyt8798VeSceIudEivNHhheeYKZoZWmor3oPG1d+LXvgOpQn5TufLBDzI3Do6HIsXF8rJk06i3TVkCZIfpxikKTZMV1MkBwn2TIHpguTyxQNrqO2GmWL5yDHIz/H1dKMPF8QQwJucVwpsNXMXjM4lqqZnFaj+b0viCYfusdzsiUT0K70CxYsUNoPy+Q9iQOQRNMFzSPUwjgQuHDOdHSyINmta09l04TJiZFOBpQ0SWSqWnPTWhDDuIhP0lJqJBMl20sp+IMPPlDSK5m1Jq63UfObPXt2t6OGxolxWCYnAmohnOjJLFkWzY40FfCZxo3xNXaUjLXkTTMtMYz3p3GYT28o3LXdbl50ICI+XD9k+0n86SearGn2JfPviXp6l5HS6+0GXOejkwWJg5mnyScbw64JMLrHKZ+rSTNO78lI7WEYNV5uUaHQQ+GHfYcMnMIbt2FoYn+jhqeJ44BLCno9VK+BMw+9Jsq4TMP85s2b1903iRm/c5zqd0UhhQ491O5Yl3BnIV3uznjVcymXePTcpOdVa3v4PNwcbX3eF/dlRSVY1SSHJcv6miNNTiwRLaxh1VJxGGlVbv5+mhsDHhw8ZjzOrxiKFZu2YGG9nEnpkrMlxSMyKGdNFmVlSFynMlmS2+VnZUtVQyJ4tyM3Mx/Bzha0ymHN8+sasWRLKzb7OzGypEwcVDLwto1G2WZwtPlbJ6GuF7M9YwuPl0gdOUlz4qZZkoOUGteIESO6pW5OvpTmuGbGQUSzIx0sGEcvOrPz0wxF85yW1mnG5NoB0+pBl0i9GLensrWk+8ILLyhtiWtvWvtkemqWHJxc2+FCOqVXOjnEIsblYKenH9ftOIly8qXzAh1BtNmLzI/rR2Rm1Lo0M+daBokOD/TEpAcnNVrugSN+mogZsaHZ6YorrlCayR133KG0YJr5wiVsnW5HvPI9ca2TTjNkNNRyiSHbTJOiVYOIVn+u65KivctI6VgO3wOdW2hJYJ+kuZL9gPloASlS2kTDyLwiafbMRzM3ToacKBMhrnFz/FHTYt/VJux//vOfirkxL65lst9qJxIyL/Y969oy4xF/Op+QwVPoYP9nH7MyOGt+7Ovsm1w3Zt+kJ7AmCl7s0yyHefbVmrAyAXLNUjwj4yXlk9BLQYJzqWZufH8k/V3XI5E66TS9vfJk/83CdJxyrFZxSDSvoByhNWUP3DF/Dvzi4p8hJkeXnHBy2uj+aFhfh/2LXOIVWYjivCx0eoKYPq5c3v8GfLqhCa1isuTGN3piyvHLcjBzDnwS1i6nl6zo8OG1jQ1oFdkzIOtwg+VTUTHZVvVtMzjahOOheONZ89ImOjI4fkg0TdCrjU4gej2MA4SDjWZGMjkSOwLXVzipkCi1azOblqo5uMjgOIB0WeFXpo0UxnBST2Vz/Y6OHVx/ozmFZXK9T0uvnDQpDZPpci+WZnbc6K3L7Srp2//c4M4Jh84jXIzXRDfpG264QX9VkyonCO06zXYznXYQIIOkNsaJhg471DA5aeh1NraNe8aIKZ0zSJyQOVmHm5u6C+3jGz3QEy2GpjNO7myH7iPMg2Y0vQcuGt6Mx2c9vUudXl+ZjkStkRvw//znP6vvxJXCVjKZGzNm+4iPduzSTE1N0OJ4wmvXBCl75CyagapUjH9kLHqNkgyaTjn0utWCFJPSU5hbX8i09Uk4epzqrJmW/UsLmBwLOt9wzJgf1/nohMK1UmJG5katTRPHNDU9Ci40//cVkYmcJ4J8pO0rLFNrUNbnxNoq+Pe2bpG0t97maTd9RXYdPAuehkN+AQCBTjhb3OIoEsL1E0bj1qrlyvvxuPGjUCjHcj362UY0Cg9b39CEvQaNwT6jC7Bo/UbU1DfBHZDjlkX7k63iMr6Ez4mnZEjW6URSQbMcxfxqzQYcPqocb6xag1YxXmbKvrnjZxxkq9ppAb9Hco5MsX6cjy+emyBjSRLKlVWk5WS+8Mg1hXIr5mD5/5iAuQYWrWxKv1wXs5pswttADZUMLhFJlJMA3f7J9PSaRni+1Gi59khNLhKxbowTS4th2xgnVv1j9RNdbqw47CfxbAHg5BGrv+myol05YVNj4ORop5/E8y4jlU38yAS0YBYpTix8dPxocTRD44RLIjNjGCdHjtFKGYN6bUdPyjrPZF1pVie2NP9a+zG3p9BCwe0EHAdcR9PCZ6yymR8dfJhfONGkzmUK9klqeNp0GR4vGl7WePHEscbX91bMY2nQOr6+JloemWc07VznGeuaaHmx8vLLXPLfU07EirZW0cD8aBKN65DiQjmhBCiZNglrGzfj33MXyPoaMG9jEzZ7xAMyIwP5sm+uLE/W7CR+zdZ2eGWeTpODmmW3G4Jy7wt4RftzqjW4WikjIHkXuzJx3KjheKdmDY4aUIK/Vn6BzNwuR7tYdQx/ZluD44DhALJKL+GZc2H0u9qYGM+gCa9fsr7HKpvMJxoD0uVHY0D6eaQrPSAjbRmwxqUpMVbe8dQtVtusZfXmnkyrN4wr3rKpDfBjl+LBK1LefA+xmFukNImEWddj9IRIJqe96yiMchLuK+bGulLA6wnbRDwdmV8k5sZ1eFojKKxQI4zG3BLBz07cLny/da6zk0c8aXrD3OLJP5E4TvF4razYC/c/9CjcaQFMKivEgsY2ZLrScc6gHLw4dzGy5de4j5ooGvu+2Zi3bC1WyL7F1Y1u1Ld7cOq+e8A3X37tm2t3bZ1ifnSoX/p2i8ekx90hR3bx9+K4uduJZtko/vrKtbh9vz0x/dgTbDE3ts02g7MOoERAMnENAgaB5CJgFQ60FmctoUvIvHi7dRxrnL66p7cqrQjJIjI9Ht9HM6d1W0ey8k8kn++KySVSp76Oe7Jo5LMeeRS7yTaOQmTgK9Gyy/Mz8WRlDX1FUJyZgRfmfoPh5SUIpAfR3OqT47naMX5wGQbk5ch6XC7yxGOyQfbGeUVT6xRzpVucU7gJgPvjnMrrMiBmS/lJHhFy6vr3Q+DI42w3yzaDs12iSWgQMAj0GQKcdMMpUlh4nL76TlNiMon74HYkIrY7kpbV19iMkfX8G6+4HPNnP4s5a9YiJzML2eIoUl3XiquOmqQ0tbxxw3DQ/hVoXFmL6lVvYerAUkwfPwzzV6xCuzjTbXJ70CHmyg6/HLgs++icYsbMla0gITFf8wDnHDnpJMuRLXvoOrFx6FgMGjnKdrNiMjiaCQwZBHpCIJ5+Ek+cnspJ5efx4BNPnFTGKNG2GbwSRSy++BdcdTUu++AjjKivw8SyMnHjz0G+UxhdhgO7DS1Fx9ZWvPT8e2hs6cCAwiyUFeVgzdZmLGtwY504pjS4fegQRufl2psrW9bDs9VG7hyXE2ViBnXJ/rgtovVN/p9JuOnGm+KrVJRYdGWJStwMrDesRo1kHuzSCLB/hG8ajwSI6UuRUOkKMxhGx8buk3gxJROMtO/Ubrk7Wrq+YvLX3DcLR0+pQIYwty+3uvHM2tV4fvFa+Wkcj6yX5WDMkDKMLi/FcHEQqe/woHKd7GurbxHtTUySXmFwsr8tU7S0bOEx/B25kiwXSrOzlMNJi8wpxcWluOueu3sNZ0wGl5uTiyaxsRoyCERDgBMJ+0lPZPpSdIQMhtGxsfskXkwpeOnTf+yWtaOmi5fJ26n/ADEbHn3dLVjpzERbaQn6jZuEzfmDsKhJHEbEWeTD6lo8Oq8Kb6ypx9urG/B1bQOaxasyKKZJOgblZeWjMD8bucLYyIRbhAmuE8ehhvZOuHLycO/DD2H8uPF2qrZNmpgMrqCwQNlF+UOchgwC4QiwX3AbAftJT2T6UmSEDIaRcelNaCKYUvDS52v2pswdMW28TN5u3SdP3hu3z3oQA4aPxcTDzpIjgsZhfkc+rnrxMzzw2VLMXbcFC9Y3oMUbVM4jOa4slMrpM1niWc71tgwxaXbK1pFOj0+2IgXEVJmDiokVeEp+xWXvKduvJdupZ8x9cMzQJy6cDQ31au8K9w7Z2T9kp2ImzY6LAAcONXt20n79yqSjxlzK7W6I6UvdUCjTv8HwWzyScWe3X9bW1qp9qLG21CSjfswjmfvSYtVJM/lkHwsXrcy//vVW3Cn7WdtaWrtNvtTM+OFZJf3lcHyP8JLWDjc6hZkF5XQSV4Zob+JU0r8gDyXiiXnGuRfgsiuvjVaErfAeGZzOtaW5Be3ya6s8UiqVbda6veYaGQF2WJp1KPnGo7lFymVX70sGw0i9ondhvcFUC17s19xfyv16zK8vqK8ZnF0mn4y2LpFfWLnvvvvV6U3kETxBhD+D4xQoh8r+061yOIVPfvomQ34/QA6zRIlsGaBTybHyY8QnnnUORo4ek4xqbJNH3Axum1Tmi0HAIGAQSDEEdnbBqzdMPpmvsrW1RU6YeR0ff/KpOsN0vRyp5hJNrbmtHcMG98ewIcOw77S9sdc+0zDt4Bnya9+Jn1ASb30Ng4sXKRPPIGAQMAgYBHYqBGI6mexULTGVNQgYBAwCBgGDgAUBw+AsYJhbg4BBwCBgEEgdBAyDS513aVpiEDAIGAQMAhYEDIOzgGFuDQIGAYOAQSB1EDAMLnXepWmJQcAgYBAwCFgQMAzOAoa5NQgYBAwCBoHUQcAwuNR5l6YlBgGDgEHAIGBBwDA4Cxjm1iBgEDAIGARSB4H/BcSYac9JP+PcAAAAAElFTkSuQmCC)

At the top right of the Chef UI there is a download code button. Download the code and you’ll get a zip file.

Unzip the file and put the folder in your desired location. We recommend renaming the folder to the name of your app for convenience. For the rest of the setup, open up the terminal and `cd` into your app:

```
cd ~/<app folder>
```

### Install dependencies[​](#install-dependencies "Direct link to Install dependencies")

Run the following command to install all dependencies for your project

```
npm i
```

### Run your app[​](#run-your-app "Direct link to Run your app")

Run the following command run your app, and setup Convex if you haven’t already.

```
npm run dev
```

Follow any instructions to login to Convex from your machine.

caution

You have now taken over from Chef for development of this app. Chef doesn't have the ability to re-import a project or track any progress from outside it. Going back to this project on Chef will cause conflicts in your project.

### Set up the frontend build script[​](#set-up-the-frontend-build-script "Direct link to Set up the frontend build script")

Chef projects don’t come with a build script. So make sure to add the following to your `package.json` file:

```
  "scripts": {
		//... other scripts
    "build": "vite build"
  },
```

### Recommended: Setup Git[​](#recommended-setup-git "Direct link to Recommended: Setup Git")

In the terminal run the following three commands setup git for your app. The downloaded code comes with a `.gitignore` file.

```
git init
git add --all
git commit -m "Initial commit"
```

It's also recommended you setup a remote git repository with [GitHub](https://github.com/) if you're going to use the production hosting guides below.

### Set up production frontend hosting[​](#set-up-production-frontend-hosting "Direct link to Set up production frontend hosting")

Follow one of the Convex [hosting guides](/production/hosting/.md) to set up frontend hosting and continuous deployment of your frontend and backend code.

### Initialize Convex Auth for Prod[​](#initialize-convex-auth-for-prod "Direct link to Initialize Convex Auth for Prod")

Once you have a production deployment. You need to [set up Convex Auth for production](https://labs.convex.dev/auth/production).

## Integrations[​](#integrations "Direct link to Integrations")

### OpenAI[​](#openai "Direct link to OpenAI")

If you ask Chef to use AI, by default it will try to use the built in OpenAI proxy with a limited number of calls. This helps you prototype your AI app idea quickly.

However, at some point the built in number of calls will run out and you'll need to provide your own OpenAI API Key and remove the proxy URL.

So that means you'll have to find the code that looks like this:

```
const openai = new OpenAI({
  baseURL: process.env.CONVEX_OPENAI_BASE_URL,
  apiKey: process.env.CONVEX_OPENAI_API_KEY,
});
```

And remove the baseURL parameter:

```
const openai = new OpenAI({
  apiKey: process.env.CONVEX_OPENAI_API_KEY,
});
```

Chef may automatically prompt you to change the environment variable. But if it doesn't, you can change it by going to the "Database" tab. Then click on Settings > Environment Variables and change `CONVEX_OPENAI_API_KEY` to your [personal OpenAI key](https://platform.openai.com).

We plan on making this transition better over time.

### Resend[​](#resend "Direct link to Resend")

Chef comes with a built in way to send emails to yourself via Resend. You can only send emails to the account you used to log into Chef. To send emails to anyone, you have to setup your app for production with a domain name. This is a limitation of how email providers work to combat spam.

## FAQs[​](#faqs "Direct link to FAQs")

### What browsers does Chef support?[​](#what-browsers-does-chef-support "Direct link to What browsers does Chef support?")

Chef is best used on desktop/laptop browsers. It may work on some tablet or mobile browsers. Chef does not work in Safari on any platform.

### How does the pricing for Chef work?[​](#how-does-the-pricing-for-chef-work "Direct link to How does the pricing for Chef work?")

Chef pricing is primarily based on AI token usage. The free plan gives you enough tokens to build the first version of your app in a small number of prompts. After that you can upgrade to the Starter plan that where you can pay for tokens as you go.

### What’s the difference between Chef and Convex?[​](#whats-the-difference-between-chef-and-convex "Direct link to What’s the difference between Chef and Convex?")

Chef is an AI app builder that builds full-stack apps. Convex is the backend and database that powers Chef.

### Can I import my existing app to Chef?[​](#can-i-import-my-existing-app-to-chef "Direct link to Can I import my existing app to Chef?")

Chef currently doesn’t have import and GitHub integration. But you can get most of the value by setting up the [Convex AI Rules and MCP server](/ai.md) in your Agentic IDE like Cursor.

### Are there any best practices for Chef?[​](#are-there-any-best-practices-for-chef "Direct link to Are there any best practices for Chef?")

Yes! Check out this [tips post written by one of our engineers](https://stack.convex.dev/chef-cookbook-tips-working-with-ai-app-builders).

### What Convex Components can Chef use?[​](#what-convex-components-can-chef-use "Direct link to What Convex Components can Chef use?")

Chef can use the [collaborative text editor](https://www.convex.dev/components/prosemirror-sync) component and the [presence](https://www.convex.dev/components/presence) component. We will support more components soon. Chef supports all other Convex features like text search, file storage, etc.

## Limitations[​](#limitations "Direct link to Limitations")

Chef works off a singular template with Convex, Convex Auth and React powered by Vite. Switching these technologies is not supported by Chef.

---

# Source: https://docs.convex.dev/testing/ci.md

# Continuous Integration

Continuous integration allows your team to move fast by combining changes from all team members and automatically testing them on a remote machine.

## Testing in GitHub Actions[​](#testing-in-github-actions "Direct link to Testing in GitHub Actions")

It's easy if you're using [GitHub](https://docs.github.com/en/actions) to set up [CI](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) workflow for running your test suite:

.github/workflows/test.yml

```
name: Run Tests

on: [pull_request, push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run test
```

After you commit and push this file to your repository, GitHub will run `npm run test` every time you create a pull request or push a new commit.

---

# Source: https://docs.convex.dev/client/tanstack/tanstack-start/clerk.md

# Source: https://docs.convex.dev/auth/clerk.md

# Convex & Clerk

[Clerk](https://clerk.com) is an authentication platform providing login via passwords, social identity providers, one-time email or SMS access codes, and multi-factor authentication and user management.

## Get started[​](#get-started "Direct link to Get started")

Convex offers a provider that is specifically for integrating with Clerk called `<ConvexProviderWithClerk>`. It works with any of Clerk's React-based SDKs, such as the Next.js and Expo SDKs.

See the following sections for the Clerk SDK that you're using:

* [React](#react) - Use this as a starting point if your SDK is not listed
* [Next.js](#nextjs)
* [TanStack Start](#tanstack-start)

### React[​](#react "Direct link to React")

**Example:** [React with Convex and Clerk](https://github.com/get-convex/template-react-vite-clerk)

This guide assumes you already have a working React app with Convex. If not follow the [Convex React Quickstart](/quickstart/react.md) first. Then:

1. Sign up for Clerk

   Sign up for a free Clerk account at [clerk.com/sign-up](https://dashboard.clerk.com/sign-up).

   ![Sign up to Clerk](/screenshots/clerk-signup.png)

2. Create an application in Clerk

   Choose how you want your users to sign in.

   ![Create a Clerk application](/screenshots/clerk-createapp.png)

3. Create a JWT Template

   In the Clerk Dashboard, navigate to the [JWT templates](https://dashboard.clerk.com/last-active?path=jwt-templates) page.

   Select *New template* and then from the list of templates, select *Convex*. You'll be redirected to the template's settings page. **Do NOT rename the JWT token. It must be called `convex`.**

   Copy and save the *Issuer* URL somewhere secure. This URL is the issuer domain for Clerk's JWT templates, which is your Clerk app's *Frontend API URL*. In development, it's format will be `https://verb-noun-00.clerk.accounts.dev`. In production, it's format will be `https://clerk.<your-domain>.com`.

   ![Create a JWT template](/screenshots/clerk-createjwt.png)

4. Configure Convex with the Clerk issuer domain

   In your app's `convex` folder, create a new file `auth.config.ts` with the following code. This is the server-side configuration for validating access tokens.

   convex/auth.config.ts

   TS

   ```
   import { AuthConfig } from "convex/server";

   export default {
     providers: [
       {
         // Replace with your own Clerk Issuer URL from your "convex" JWT template
         // or with `process.env.CLERK_JWT_ISSUER_DOMAIN`
         // and configure CLERK_JWT_ISSUER_DOMAIN on the Convex Dashboard
         // See https://docs.convex.dev/auth/clerk#configuring-dev-and-prod-instances
         domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
         applicationID: "convex",
       },
     ]
   } satisfies AuthConfig;
   ```

5. Deploy your changes

   Run `npx convex dev` to automatically sync your configuration to your backend.

   ```
   npx convex dev
   ```

6. Install clerk

   In a new terminal window, install the Clerk React SDK:

   ```
   npm install @clerk/clerk-react
   ```

7. Set your Clerk API keys

   In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. In the **Quick Copy** section, copy your Clerk Publishable Key and set it as the `CLERK_PUBLISHABLE_KEY` environment variable. If you're using Vite, you will need to prefix it with `VITE_`.

   .env

   ```
   VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
   ```

8. Configure ConvexProviderWithClerk

   Both Clerk and Convex have provider components that are required to provide authentication and client context.

   You should already have `<ConvexProvider>` wrapping your app. Replace it with `<ConvexProviderWithClerk>`, and pass Clerk's `useAuth()` hook to it.

   Then, wrap it with `<ClerkProvider>`. `<ClerkProvider>` requires a `publishableKey` prop, which you can set to the `VITE_CLERK_PUBLISHABLE_KEY` environment variable.

   src/main.tsx

   TS

   ```
   import React from "react";
   import ReactDOM from "react-dom/client";
   import App from "./App";
   import "./index.css";
   import { ClerkProvider, useAuth } from "@clerk/clerk-react";
   import { ConvexProviderWithClerk } from "convex/react-clerk";
   import { ConvexReactClient } from "convex/react";

   const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

   ReactDOM.createRoot(document.getElementById("root")!).render(
     <React.StrictMode>
       <ClerkProvider publishableKey="pk_test_...">
         <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
           <App />
         </ConvexProviderWithClerk>
       </ClerkProvider>
     </React.StrictMode>,
   );
   ```

9. Show UI based on authentication state

   You can control which UI is shown when the user is signed in or signed out using Convex's `<Authenticated>`, `<Unauthenticated>` and `<AuthLoading>` helper components. These should be used instead of Clerk's `<SignedIn>`, `<SignedOut>` and `<ClerkLoading>` components, respectively.

   It's important to use the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook instead of Clerk's `useAuth()` hook when you need to check whether the user is logged in or not. The `useConvexAuth()` hook makes sure that the browser has fetched the auth token needed to make authenticated requests to your Convex backend, and that the Convex backend has validated it.

   In the following example, the `<Content />` component is a child of `<Authenticated>`, so its content and any of its child components are guaranteed to have an authenticated user, and Convex queries can require authentication.

   src/App.tsx

   TS

   ```
   import { SignInButton, UserButton } from "@clerk/clerk-react";
   import { Authenticated, Unauthenticated, AuthLoading, useQuery } from "convex/react";
   import { api } from "../convex/_generated/api";

   function App() {
     return (
       <main>
         <Unauthenticated>
           <SignInButton />
         </Unauthenticated>
         <Authenticated>
           <UserButton />
           <Content />
         </Authenticated>
         <AuthLoading>
           <p>Still loading</p>
         </AuthLoading>
       </main>
     );
   }

   function Content() {
     const messages = useQuery(api.messages.getForCurrentUser);
     return <div>Authenticated content: {messages?.length}</div>;
   }

   export default App;
   ```

10. Use authentication state in your Convex functions

    If the client is authenticated, you can access the information stored in the JWT via `ctx.auth.getUserIdentity`.

    If the client isn't authenticated, `ctx.auth.getUserIdentity` will return `null`.

    **Make sure that the component calling this query is a child of `<Authenticated>` from `convex/react`**. Otherwise, it will throw on page load.

    convex/messages.ts

    TS

    ```
    import { query } from "./_generated/server";

    export const getForCurrentUser = query({
      args: {},
      handler: async (ctx) => {
        const identity = await ctx.auth.getUserIdentity();
        if (identity === null) {
          throw new Error("Not authenticated");
        }
        return await ctx.db
          .query("messages")
          .withIndex("by_author", (q) => q.eq("author", identity.email))
          .collect();
      },
    });
    ```

### Next.js[​](#nextjs "Direct link to Next.js")

**Example:** [Next.js with Convex and Clerk](https://github.com/get-convex/template-nextjs-clerk)

This guide assumes you already have a working Next.js app with Convex. If not follow the [Convex Next.js Quickstart](/quickstart/nextjs.md) first. Then:

1. Sign up for Clerk

   Sign up for a free Clerk account at [clerk.com/sign-up](https://dashboard.clerk.com/sign-up).

   ![Sign up to Clerk](/screenshots/clerk-signup.png)

2. Create an application in Clerk

   Choose how you want your users to sign in.

   ![Create a Clerk application](/screenshots/clerk-createapp.png)

3. Create a JWT Template

   In the Clerk Dashboard, navigate to the [JWT templates](https://dashboard.clerk.com/last-active?path=jwt-templates) page.

   Select *New template* and then from the list of templates, select *Convex*. You'll be redirected to the template's settings page. **Do NOT rename the JWT token. It must be called `convex`.**

   Copy and save the *Issuer* URL somewhere secure. This URL is the issuer domain for Clerk's JWT templates, which is your Clerk app's *Frontend API URL*. In development, it's format will be `https://verb-noun-00.clerk.accounts.dev`. In production, it's format will be `https://clerk.<your-domain>.com`.

   ![Create a JWT template](/screenshots/clerk-createjwt.png)

4. Configure Convex with the Clerk issuer domain

   In your app's `convex` folder, create a new file `auth.config.ts` with the following code. This is the server-side configuration for validating access tokens.

   convex/auth.config.ts

   TS

   ```
   import { AuthConfig } from "convex/server";

   export default {
     providers: [
       {
         // Replace with your own Clerk Issuer URL from your "convex" JWT template
         // or with `process.env.CLERK_JWT_ISSUER_DOMAIN`
         // and configure CLERK_JWT_ISSUER_DOMAIN on the Convex Dashboard
         // See https://docs.convex.dev/auth/clerk#configuring-dev-and-prod-instances
         domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
         applicationID: "convex",
       },
     ]
   } satisfies AuthConfig;
   ```

5. Deploy your changes

   Run `npx convex dev` to automatically sync your configuration to your backend.

   ```
   npx convex dev
   ```

6. Install clerk

   In a new terminal window, install the Clerk Next.js SDK:

   ```
   npm install @clerk/nextjs
   ```

7. Set your Clerk API keys

   In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. In the **Quick Copy** section, copy your Clerk Publishable and Secret Keys and set them as the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively.

   .env

   ```
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
   CLERK_SECRET_KEY=YOUR_SECRET_KEY
   ```

8. Add Clerk middleware

   Clerk's `clerkMiddleware()` helper grants you access to user authentication state throughout your app.

   Create a `middleware.ts` file.

   In your `middleware.ts` file, export the `clerkMiddleware()` helper:

   ```
   import { clerkMiddleware } from '@clerk/nextjs/server'

   export default clerkMiddleware()

   export const config = {
     matcher: [
       // Skip Next.js internals and all static files, unless found in search params
       '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
       // Always run for API routes
       '/(api|trpc)(.*)',
     ],
   }
   ```

   By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes.<https://clerk.com/docs/references/nextjs/clerk-middleware>) to learn how to require authentication for specific routes.

9. Configure ConvexProviderWithClerk

   Both Clerk and Convex have provider components that are required to provide authentication and client context.

   Typically, you'd replace `<ConvexProvider>` with `<ConvexProviderWithClerk>`, but with Next.js App Router, things are a bit more complex.

   `<ConvexProviderWithClerk>` calls `ConvexReactClient()` to get Convex's client, so it must be used in a Client Component. Your `app/layout.tsx`, where you would use `<ConvexProviderWithClerk>`, is a Server Component, and a Server Component cannot contain Client Component code. To solve this, you must first create a *wrapper* Client Component around `<ConvexProviderWithClerk>`.

   ```
   'use client'

   import { ReactNode } from 'react'
   import { ConvexReactClient } from 'convex/react'
   import { ConvexProviderWithClerk } from 'convex/react-clerk'
   import { useAuth } from '@clerk/nextjs'

   if (!process.env.NEXT_PUBLIC_CONVEX_URL) {
     throw new Error('Missing NEXT_PUBLIC_CONVEX_URL in your .env file')
   }

   const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL)

   export default function ConvexClientProvider({ children }: { children: ReactNode }) {
     return (
       <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
         {children}
       </ConvexProviderWithClerk>
     )
   }
   ```

10. Wrap your app in Clerk and Convex

    Now, your Server Component, `app/layout.tsx`, can render `<ConvexClientProvider>` instead of rendering `<ConvexProviderWithClerk>` directly. It's important that `<ClerkProvider>` wraps `<ConvexClientProvider>`, and not the other way around, as Convex needs to be able to access the Clerk context.

    ```
    import type { Metadata } from 'next'
    import { Geist, Geist_Mono } from 'next/font/google'
    import './globals.css'
    import { ClerkProvider } from '@clerk/nextjs'
    import ConvexClientProvider from '@/components/ConvexClientProvider'

    const geistSans = Geist({
      variable: '--font-geist-sans',
      subsets: ['latin'],
    })

    const geistMono = Geist_Mono({
      variable: '--font-geist-mono',
      subsets: ['latin'],
    })

    export const metadata: Metadata = {
      title: 'Clerk Next.js Quickstart',
      description: 'Generated by create next app',
    }

    export default function RootLayout({
      children,
    }: Readonly<{
      children: React.ReactNode
    }>) {
      return (
        <html lang="en">
          <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
            <ClerkProvider>
              <ConvexClientProvider>{children}</ConvexClientProvider>
            </ClerkProvider>
          </body>
        </html>
      )
    }
    ```

11. Show UI based on authentication state

    You can control which UI is shown when the user is signed in or signed out using Convex's `<Authenticated>`, `<Unauthenticated>` and `<AuthLoading>` helper components. These should be used instead of Clerk's `<SignedIn>`, `<SignedOut>` and `<ClerkLoading>` components, respectively.

    It's important to use the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook instead of Clerk's `useAuth()` hook when you need to check whether the user is logged in or not. The `useConvexAuth()` hook makes sure that the browser has fetched the auth token needed to make authenticated requests to your Convex backend, and that the Convex backend has validated it.

    In the following example, the `<Content />` component is a child of `<Authenticated>`, so its content and any of its child components are guaranteed to have an authenticated user, and Convex queries can require authentication.

    app/page.tsx

    TS

    ```
    "use client";

    import { Authenticated, Unauthenticated } from "convex/react";
    import { SignInButton, UserButton } from "@clerk/nextjs";
    import { useQuery } from "convex/react";
    import { api } from "../convex/_generated/api";

    export default function Home() {
      return (
        <>
          <Authenticated>
            <UserButton />
            <Content />
          </Authenticated>
          <Unauthenticated>
            <SignInButton />
          </Unauthenticated>
        </>
      );
    }

    function Content() {
      const messages = useQuery(api.messages.getForCurrentUser);
      return <div>Authenticated content: {messages?.length}</div>;
    }
    ```

12. Use authentication state in your Convex functions

    If the client is authenticated, you can access the information stored in the JWT via `ctx.auth.getUserIdentity`.

    If the client isn't authenticated, `ctx.auth.getUserIdentity` will return `null`.

    **Make sure that the component calling this query is a child of `<Authenticated>` from `convex/react`**. Otherwise, it will throw on page load.

    convex/messages.ts

    TS

    ```
    import { query } from "./_generated/server";

    export const getForCurrentUser = query({
      args: {},
      handler: async (ctx) => {
        const identity = await ctx.auth.getUserIdentity();
        if (identity === null) {
          throw new Error("Not authenticated");
        }
        return await ctx.db
          .query("messages")
          .withIndex("by_author", (q) => q.eq("author", identity.email))
          .collect();
      },
    });
    ```

### TanStack Start[​](#tanstack-start "Direct link to TanStack Start")

**Example:** [TanStack Start with Convex and Clerk](https://github.com/get-convex/templates/tree/main/template-tanstack-start)

See the [TanStack Start with Clerk guide](/client/tanstack/tanstack-start/clerk.md) for more information.

## Next steps[​](#next-steps "Direct link to Next steps")

### Accessing user information in functions[​](#accessing-user-information-in-functions "Direct link to Accessing user information in functions")

See [Auth in Functions](/auth/functions-auth.md) to learn about how to access information about the authenticated user in your queries, mutations and actions.

See [Storing Users in the Convex Database](/auth/database-auth.md) to learn about how to store user information in the Convex database.

### Accessing user information client-side[​](#accessing-user-information-client-side "Direct link to Accessing user information client-side")

To access the authenticated user's information, use Clerk's `User` object, which can be accessed using Clerk's [`useUser()`](https://clerk.com/docs/hooks/use-user) hook. For more information on the `User` object, see the [Clerk docs](https://clerk.com/docs/references/javascript/user).

components/Badge.tsx

TS

```
export default function Badge() {
  const { user } = useUser();

  return <span>Logged in as {user.fullName}</span>;
}
```

## Configuring dev and prod instances[​](#configuring-dev-and-prod-instances "Direct link to Configuring dev and prod instances")

To configure a different Clerk instance between your Convex development and production deployments, you can use environment variables configured on the Convex dashboard.

### Configuring the backend[​](#configuring-the-backend "Direct link to Configuring the backend")

In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page. Copy your Clerk Frontend API URL. This URL is the issuer domain for Clerk's JWT templates, and is necessary for Convex to validate access tokens. In development, it's format will be `https://verb-noun-00.clerk.accounts.dev`. In production, it's format will be `https://clerk.<your-domain>.com`.

Paste your Clerk Frontend API URL into your `.env` file, set it as the `CLERK_JWT_ISSUER_DOMAIN` environment variable.

.env

```
CLERK_JWT_ISSUER_DOMAIN=https://verb-noun-00.clerk.accounts.dev
```

Then, update your `auth.config.ts` file to use the environment variable.

convex/auth.config.ts

TS

```
import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
      applicationID: "convex",
    },
  ],
} satisfies AuthConfig;
```

**Development configuration**

In the left sidenav of the Convex [dashboard](https://dashboard.convex.dev), switch to your development deployment and set the values for your development Clerk instance.

<!-- -->

![Convex dashboard dev deployment settings](/screenshots/clerk-convex-dashboard.png)

Then, to switch your deployment to the new configuration, run `npx convex dev`.

**Production configuration**

In the left sidenav of the Convex [dashboard](https://dashboard.convex.dev), switch to your production deployment and set the values for your production Clerk instance.

<!-- -->

Then, to switch your deployment to the new configuration, run `npx convex deploy`.

### Configuring Clerk's API keys[​](#configuring-clerks-api-keys "Direct link to Configuring Clerk's API keys")

Clerk's API keys differ depending on whether they are for development or production. Don't forget to update the environment variables in your `.env` file as well as your hosting platform, such as Vercel or Netlify.

**Development configuration**

Clerk's Publishable Key for development follows the format `pk_test_...`.

.env.local

```
VITE_CLERK_PUBLISHABLE_KEY="pk_test_..."
```

**Production configuration**

Clerk's Publishable Key for production follows the format `pk_live_...`.

.env

```
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."
```

## Debugging authentication[​](#debugging-authentication "Direct link to Debugging authentication")

If a user goes through the Clerk login flow successfully, and after being redirected back to your page, `useConvexAuth()` returns `isAuthenticated: false`, it's possible that your backend isn't correctly configured.

The `auth.config.ts` file contains a list of configured authentication providers. You must run `npx convex dev` or `npx convex deploy` after adding a new provider to sync the configuration to your backend.

For more thorough debugging steps, see [Debugging Authentication](/auth/debug.md).

## Under the hood[​](#under-the-hood "Direct link to Under the hood")

The authentication flow looks like this under the hood:

1. The user clicks a login button
2. The user is redirected to a page where they log in via whatever method you configure in
   <!-- -->
   Clerk
3. After a successful login
   <!-- -->
   Clerk
   <!-- -->
   redirects back to your page, or a different page which you configure via
   <!-- -->
   the
   <!-- -->
   [`afterSignIn`](https://clerk.com/docs/authentication/sign-in#override-ur-ls)
   <!-- -->
   prop
   <!-- -->
   .
4. The `ClerkProvider` now knows that the user is authenticated.
5. The `ConvexProviderWithClerk` fetches an auth token from
   <!-- -->
   Clerk
   <!-- -->
   .
6. The `ConvexReactClient` passes this token down to your Convex backend to validate
7. Your Convex backend retrieves the public key from
   <!-- -->
   Clerk
   <!-- -->
   to check that the token's signature is valid.
8. The `ConvexReactClient` is notified of successful authentication, and `ConvexProviderWithClerk` now knows that the user is authenticated with Convex. `useConvexAuth` returns `isAuthenticated: true` and the `Authenticated` component renders its children.

`ConvexProviderWithClerk` takes care of refetching the token when needed to make sure the user stays authenticated with your backend.

---

# Source: https://docs.convex.dev/cli.md

# CLI

The Convex command-line interface (CLI) is your interface for managing Convex projects and Convex functions.

To install the CLI, run:

```
npm install convex
```

You can view the full list of commands with:

```
npx convex
```

## Configure[​](#configure "Direct link to Configure")

### Create a new project[​](#create-a-new-project "Direct link to Create a new project")

The first time you run

```
npx convex dev
```

it will ask you to log in your device and create a new Convex project. It will then create:

1. The `convex/` directory: This is the home for your query and mutation functions.
2. `.env.local` with `CONVEX_DEPLOYMENT` variable: This is the main configuration for your Convex project. It is the name of your development deployment.

### Recreate project configuration[​](#recreate-project-configuration "Direct link to Recreate project configuration")

Run

```
npx convex dev
```

in a project directory without a set `CONVEX_DEPLOYMENT` to configure a new or existing project.

### Log out[​](#log-out "Direct link to Log out")

```
npx convex logout
```

Remove the existing Convex credentials from your device, so subsequent commands like `npx convex dev` can use a different Convex account.

## Develop[​](#develop "Direct link to Develop")

### Run the Convex dev server[​](#run-the-convex-dev-server "Direct link to Run the Convex dev server")

```
npx convex dev
```

Watches the local filesystem. When you change a [function](/functions.md) or the [schema](/database/schemas.md), the new versions are pushed to your dev deployment and the [generated types](/generated-api/.md) in `convex/_generated` are updated. By default, logs from your dev deployment are displayed in the terminal.

It's also possible to [run a Convex deployment locally](/cli/local-deployments.md) for development.

### Open the dashboard[​](#open-the-dashboard "Direct link to Open the dashboard")

```
npx convex dashboard
```

Open the [Convex dashboard](/dashboard.md).

### Open the docs[​](#open-the-docs "Direct link to Open the docs")

```
npx convex docs
```

Get back to these docs!

### Run Convex functions[​](#run-convex-functions "Direct link to Run Convex functions")

```
npx convex run <functionName> [args]
```

Run a public or internal Convex query, mutation, or action on your development deployment.

Arguments are specified as a JSON object.

```
npx convex run messages:send '{"body": "hello", "author": "me"}'
```

Add `--watch` to live update the results of a query. Add `--push` to push local code to the deployment before running the function.

Use `--prod` to run functions in the production deployment for a project.

### Tail deployment logs[​](#tail-deployment-logs "Direct link to Tail deployment logs")

You can choose how to pipe logs from your dev deployment to your console:

```
# Show all logs continuously
npx convex dev --tail-logs always

# Pause logs during deploys to see sync issues (default)
npx convex dev

# Don't display logs while developing
npx convex dev --tail-logs disable

# Tail logs without deploying
npx convex logs
```

Use `--prod` with `npx convex logs` to tail the prod deployment logs instead.

### Import data from a file[​](#import-data-from-a-file "Direct link to Import data from a file")

```
npx convex import --table <tableName> <path>
npx convex import <path>.zip
```

See description and use-cases: [data import](/database/import-export/import.md).

### Export data to a file[​](#export-data-to-a-file "Direct link to Export data to a file")

```
npx convex export --path <directoryPath>
npx convex export --path <filePath>.zip
npx convex export --include-file-storage --path <path>
```

See description and use-cases: [data export](/database/import-export/export.md).

### Display data from tables[​](#display-data-from-tables "Direct link to Display data from tables")

```
npx convex data  # lists tables
npx convex data <table>
```

Display a simple view of the [dashboard data page](/dashboard/deployments/data.md) in the command line.

The command supports `--limit` and `--order` flags to change data displayed. For more complex filters, use the dashboard data page or write a [query](/database/reading-data/.md).

The `npx convex data <table>` command works with [system tables](/database/advanced/system-tables.md), such as `_storage`, in addition to your own tables.

### Read and write environment variables[​](#read-and-write-environment-variables "Direct link to Read and write environment variables")

```
npx convex env list
npx convex env get <name>
npx convex env set <name> <value>
npx convex env remove <name>
```

See and update the deployment environment variables which you can otherwise manage on the dashboard [environment variables settings page](/dashboard/deployments/deployment-settings.md#environment-variables).

## Deploy[​](#deploy "Direct link to Deploy")

### Deploy Convex functions to production[​](#deploy-convex-functions-to-production "Direct link to Deploy Convex functions to production")

```
npx convex deploy
```

The target deployment to push to is determined like this:

1. If the `CONVEX_DEPLOY_KEY` environment variable is set (typical in CI), then it is the deployment associated with that key.
2. If the `CONVEX_DEPLOYMENT` environment variable is set (typical during local development), then the target deployment is the production deployment of the project that the deployment specified by `CONVEX_DEPLOYMENT` belongs to. This allows you to deploy to your prod deployment while developing against your dev deployment.

This command will:

1. Run a command if specified with `--cmd`. The command will have CONVEX\_URL (or similar) environment variable available:

   <!-- -->

   ```
   npx convex deploy --cmd "npm run build"
   ```

   <!-- -->

   You can customize the URL environment variable name with `--cmd-url-env-var-name`:

   <!-- -->

   ```
   npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_CONVEX_URL
   ```

2. Typecheck your Convex functions.

3. Regenerate the [generated code](/generated-api/.md) in the `convex/_generated` directory.

4. Bundle your Convex functions and their dependencies.

5. Push your functions, [indexes](/database/reading-data/indexes/.md), and [schema](/database/schemas.md) to production.

Once this command succeeds the new functions will be available immediately.

### Deploy Convex functions to a [preview deployment](/production/hosting/preview-deployments.md)[​](#deploy-convex-functions-to-a-preview-deployment "Direct link to deploy-convex-functions-to-a-preview-deployment")

```
npx convex deploy
```

When run with the `CONVEX_DEPLOY_KEY` environment variable containing a [Preview Deploy Key](/cli/deploy-key-types.md#deploying-to-preview-deployments), this command will:

1. Create a new Convex deployment. `npx convex deploy` will infer the Git branch name for Vercel, Netlify, GitHub, and GitLab environments, or the `--preview-create` option can be used to customize the name associated with the newly created deployment.

   ```
   npx convex deploy --preview-create my-branch-name
   ```

2. Run a command if specified with `--cmd`. The command will have CONVEX\_URL (or similar) environment variable available:

   ```
   npx convex deploy --cmd "npm run build"
   ```

   You can customize the URL environment variable name with `--cmd-url-env-var-name`:

   ```
   npx convex deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_CONVEX_URL
   ```

3. Typecheck your Convex functions.

4. Regenerate the [generated code](/generated-api/.md) in the `convex/_generated` directory.

5. Bundle your Convex functions and their dependencies.

6. Push your functions, [indexes](/database/reading-data/indexes/.md), and [schema](/database/schemas.md) to the deployment.

7. Run a function specified by `--preview-run` (similar to the `--run` option for `npx convex dev`).

   ```
   npx convex deploy --preview-run myFunction
   ```

See the [Vercel](/production/hosting/vercel.md#preview-deployments) or [Netlify](/production/hosting/netlify.md#deploy-previews) hosting guide for setting up frontend and backend previews together.

### Update generated code[​](#update-generated-code "Direct link to Update generated code")

```
npx convex codegen
```

The [generated code](/generated-api/.md) in the `convex/_generated` directory includes types required for a TypeScript typecheck. This code is generated whenever necessary while running `npx convex dev` and this code should be committed to the repo (your code won't typecheck without it!).

In the rare cases it's useful to regenerate code (e.g. in CI to ensure that the correct code was checked it) you can use this command.

Generating code can require communicating with a convex deployment in order to evaluate configuration files in the Convex JavaScript runtime. This doesn't modify the code running on the deployment.

---

# Source: https://docs.convex.dev/components.md

# Components

Convex Components package up code and data in a sandbox that allows you to confidently and quickly add new features to your backend.

Convex Components are like mini self-contained Convex backends, and installing them is always safe. They can't read your app's tables or call your app's functions unless you pass them in explicitly.

You can read about the full vision in [Convex: The Software-Defined Database](https://stack.convex.dev/the-software-defined-database#introducing-convex-components).

Components can be installed from NPM or from a local folder. Once installed, they have their own database tables and isolated function execution environment. Check out the full directory of components on the [Convex website](https://convex.dev/components).

## [Understanding components](/components/understanding.md)

[Explore the concepts behind and build a mental model for how components work.](/components/understanding.md)

## [Using components](/components/using.md)

[Learn about useful components and how to use them in your application.](/components/using.md)

## [Authoring components](/components/authoring.md)

[Learn how to write and publish a component.](/components/authoring.md)

## [Components Directory](https://convex.dev/components)

[List of all components.](https://convex.dev/components)

---

# Source: https://docs.convex.dev/production/contact.md

# Contact Us

Convex is a rapidly developing platform and we're always eager to hear your feedback.

## Feedback and Support[​](#feedback-and-support "Direct link to Feedback and Support")

Please share any general questions, feature requests, or product feedback in our [Convex Discord Community](https://convex.dev/community). We're particularly excited to see what you build on Convex!

Any specific support questions that aren't able to be adequately addressed on our Discord channel can be directed to <support@convex.dev>.

## Following Convex[​](#following-convex "Direct link to Following Convex")

Release notes are shared on [Convex News](https://news.convex.dev/tag/releases) and the [Convex Discord Community](https://convex.dev/community).

Product announcements, articles and demos are posted on [Stack](https://stack.convex.dev/), [News](https://news.convex.dev/), [our YouTube channel](https://www.youtube.com/channel/UCoC_9mdiPwIu1sDxDtGQggQ), and [X (fka Twitter)](https://x.com/convex).

## Vulnerability Disclosure[​](#vulnerability-disclosure "Direct link to Vulnerability Disclosure")

If you believe you've discovered a bug in Convex's security, please get in touch at <security@convex.dev> and we'll get back to you within 24 hours. We request that you not publicly disclose the issue until we have had a chance to address it.

---

# Source: https://docs.convex.dev/agents/context.md

# LLM Context

By default, the Agent will provide context based on the message history of the thread. This context is used to generate the next message.

The context can include recent messages, as well as messages found via text and /or vector search.

If a `promptMessageId` is provided, the context will include that message, as well as any other messages on that same `order`. More details on order are in [messages.mdx](/agents/messages.md#message-ordering), but in practice this means that if you pass the ID of the user-submitted message as the `promptMessageId` and there had already been some assistant and/or tool responses, those will be included in the context, allowing the LLM to continue the conversation.

You can also use [RAG](/agents/rag.md) to add extra context to your prompt.

## Customizing the context[​](#customizing-the-context "Direct link to Customizing the context")

You can customize the context provided to the agent when generating messages with custom `contextOptions`. These can be set as defaults on the `Agent`, or provided at the call-site for `generateText` or others.

```
const result = await agent.generateText(
  ctx,
  { threadId },
  { prompt },
  {
    // Values shown are the defaults.
    contextOptions: {
      // Whether to exclude tool messages in the context.
      excludeToolMessages: true,
      // How many recent messages to include. These are added after the search
      // messages, and do not count against the search limit.
      recentMessages: 100,
      // Options for searching messages via text and/or vector search.
      searchOptions: {
        limit: 10, // The maximum number of messages to fetch.
        textSearch: false, // Whether to use text search to find messages.
        vectorSearch: false, // Whether to use vector search to find messages.
        // Note, this is after the limit is applied.
        // E.g. this will quadruple the number of messages fetched.
        // (two before, and one after each message found in the search)
        messageRange: { before: 2, after: 1 },
      },
      // Whether to search across other threads for relevant messages.
      // By default, only the current thread is searched.
      searchOtherThreads: false,
    },
  },
);
```

## Full context control[​](#full-context-control "Direct link to Full context control")

To have full control over which messages are passed to the LLM, you can either:

1. Provide a `contextHandler` to filter, modify, or enrich the context messages.
2. Provide all messages manually via the `messages` argument and specify `contextOptions` to use no recent or search messages. See below for how to fetch context messages manually.

### Providing a contextHandler[​](#providing-a-contexthandler "Direct link to Providing a contextHandler")

The Agent will combine messages from search, recent, input messages, and all messages on the same `order` as the `promptMessageId` if that is provided.

You can customize how they are combined, as well as add or remove messages by providing a `contextHandler` which returns the `ModelMessage[]` which will be passed to the LLM.

You can specify a `contextHandler` in the Agent constructor, or at the call-site for a single generation, which overrides any Agent default.

```
const myAgent = new Agent(components.agent, {
  ///...
  contextHandler: async (ctx, args) => {
    // This is the default behavior.
    return [
      ...args.search,
      ...args.recent,
      ...args.inputMessages,
      ...args.inputPrompt,
      ...args.existingResponses,
    ];
    // Equivalent to:
    return args.allMessages;
  },
);
```

With this callback, you can:

1. Filter out messages you don't want to include.
2. Add memories or other context.
3. Add sample messages to guide the LLM on how it should respond.
4. Inject extra context based on the user or thread.
5. Copy in messages from other threads.
6. Summarize messages.

For example:

```
// Note: when you specify it at the call-site, you can also leverage variables
// available in the scope, e.g. if the user is in a specific step in a workflow.
const result = await agent.generateText(
  ctx,
  { threadId },
  { prompt },
  {
    contextHandler: async (ctx, args) => {
      // Filter out messages that are not relevant.
      const relevantSearch = args.search.filter((m) => messageIsRelevant(m));
      // Fetch user memories to include in every prompt.
      const userMemories = await getUserMemories(ctx, args.userId);
      // Fetch sample messages to instruct the LLM on how to respond.
      const sampleMessages = [
        { role: "user", content: "Generate a function that adds two numbers" },
        { role: "assistant", content: "function add(a, b) { return a + b; }" },
      ];
      // Fetch user context to include in every prompt.
      const userContext = await getUserContext(ctx, args.userId, args.threadId);
      // Fetch messages from a related / parent thread.
      const related = await getRelatedThreadMessages(ctx, args.threadId);
      return [
        // Summarize or truncate context messages if they are too long.
        ...(await summarizeOrTruncateIfTooLong(related)),
        ...relevantSearch,
        ...userMemories,
        ...sampleMessages,
        ...userContext,
        ...args.recent,
        ...args.inputMessages,
        ...args.inputPrompt,
        ...args.existingResponses,
      ];
    },
  },
);
```

### Fetch context manually[​](#fetch-context-manually "Direct link to Fetch context manually")

If you want to get context messages for a given prompt, without calling the LLM, you can use `fetchContextWithPrompt`. This is used internally to get the context messages passed to the AI SDK `generateText`, `streamText`, etc.

As with normal generation, you can provide a `prompt` or `messages`, and/or a `promptMessageId` to fetch the context messages using a given pre-saved message as the prompt.

This will return recent and search messages combined with the input messages.

```
import { fetchContextWithPrompt } from "@convex-dev/agent";

const { messages } = await fetchContextWithPrompt(ctx, components.agent, {
  prompt,
  messages,
  promptMessageId,
  userId,
  threadId,
  contextOptions,
});
```

## Search for messages[​](#search-for-messages "Direct link to Search for messages")

This is what the agent does automatically, but it can be useful to do manually, e.g. to find custom context to include.

For text and vector search, you can provide a `targetMessageId` and/or `searchText`. It will embed the text for vector search. If `searchText` is not provided, it will use the target message's text.

If `targetMessageId` is provided, it will only fetch search messages previous to that message, and recent messages up to and including that message's "order". This enables re-generating a response for an earlier message.

```
import type { MessageDoc } from "@convex-dev/agent";

const messages: MessageDoc[] = await agent.fetchContextMessages(ctx, {
  threadId,
  searchText: prompt, // Optional unless you want text/vector search.
  targetMessageId: promptMessageId, // Optionally target the search.
  userId, // Optional, unless `searchOtherThreads` is true.
  contextOptions, // Optional, defaults are used if not provided.
});
```

Note: you can also search for messages without an agent. The main difference is that in order to do vector search, you need to create the embeddings yourself, and it will not run your usage handler.

```
import { fetchRecentAndSearchMessages } from "@convex-dev/agent";

const { recentMessages, searchMessages } = await fetchRecentAndSearchMessages(
  ctx,
  components.agent,
  {
    threadId,
    searchText: prompt, // Optional unless you want text/vector search.
    targetMessageId: promptMessageId, // Optionally target the search.
    contextOptions, // Optional, defaults are used if not provided.
    getEmbedding: async (text) => {
      const embedding = await textEmbeddingModel.embed(text);
      return { embedding, textEmbeddingModel };
    },
  },
);
```

## Searching other threads[​](#searching-other-threads "Direct link to Searching other threads")

If you set `searchOtherThreads` to `true`, the agent will search across all threads belonging to the provided `userId`. This can be useful to have multiple conversations that the Agent can reference.

The search will use a hybrid of text and vector search.

## Passing in messages as context[​](#passing-in-messages-as-context "Direct link to Passing in messages as context")

You can pass in messages as context to the Agent's LLM, for instance to implement [Retrieval-Augmented Generation](/agents/rag.md). The final messages sent to the LLM will be:

1. The system prompt, if one is provided or the agent has `instructions`
2. The messages found via contextOptions
3. The `messages` argument passed into `generateText` or other function calls.
4. If a `prompt` argument was provided, a final `{ role: "user", content: prompt }` message.

This allows you to pass in messages that are not part of the thread history and will not be saved automatically, but that the LLM will receive as context.

## Manage embeddings manually[​](#manage-embeddings-manually "Direct link to Manage embeddings manually")

The `textEmbeddingModel` argument to the Agent constructor allows you to specify a text embedding model to use for vector search.

If you set this, the agent will automatically generate embeddings for messages and use them for vector search.

When you change models or decide to start or stop using embeddings for vector search, you can manage the embeddings manually.

Generate embeddings for a set of messages. Optionally pass `config` with a usage handler, which can be a globally shared `Config`.

```
import { embedMessages } from "@convex-dev/agent";

const embeddings = await embedMessages(
  ctx,
  { userId, threadId, textEmbeddingModel, ...config },
  [{ role: "user", content: "What is love?" }],
);
```

Generate and save embeddings for existing messages.

```
const embeddings = await supportAgent.generateAndSaveEmbeddings(ctx, {
  messageIds,
});
```

Get and update embeddings, e.g. for a migration to a new model.

```
const messages = await ctx.runQuery(components.agent.vector.index.paginate, {
  vectorDimension: 1536,
  targetModel: "gpt-4o-mini",
  cursor: null,
  limit: 10,
});
```

Updating the embedding by ID.

```
const messages = await ctx.runQuery(components.agent.vector.index.updateBatch, {
  vectors: [{ model: "gpt-4o-mini", vector: embedding, id: msg.embeddingId }],
});
```

Note: If the dimension changes, you need to delete the old and insert the new.

Delete embeddings

```
await ctx.runMutation(components.agent.vector.index.deleteBatch, {
  ids: [embeddingId1, embeddingId2],
});
```

Insert embeddings

```
const ids = await ctx.runMutation(components.agent.vector.index.insertBatch, {
  vectorDimension: 1536,
  vectors: [
    {
      model: "gpt-4o-mini",
      table: "messages",
      userId: "123",
      threadId: "123",
      vector: embedding,
      // Optional, if you want to update the message with the embeddingId
      messageId: messageId,
    },
  ],
});
```

---

# Source: https://docs.convex.dev/auth/convex-auth.md

# Convex Auth

[Convex Auth](https://labs.convex.dev/auth) is a library for implementing authentication directly within your Convex backend. This allows you to authenticate users without needing an authentication service or even a hosting server. Convex Auth currently supports client-side React web apps served from a CDN and React Native mobile apps.

**Example:** [Live Demo](https://labs.convex.dev/auth-example) ([Source](https://github.com/get-convex/convex-auth-example))

Convex Auth is in beta

Convex Auth<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

Support for [authentication in Next.js](https://labs.convex.dev/auth/authz/nextjs) server components, API routes, middleware, SSR etc. is under active development. If you'd like to help test this experimental support please [let us know how it goes in Discord](https://convex.dev/community).

## Get Started[​](#get-started "Direct link to Get Started")

To start a new project from scratch with Convex and Convex Auth, run:

```
npm create convex@latest
```

and choose `React (Vite)` and `Convex Auth`.

***

To add Convex Auth to an existing project, follow the full [setup guide](https://labs.convex.dev/auth/setup).

## Overview[​](#overview "Direct link to Overview")

Convex Auth enables you to implement the following authentication methods:

1. Magic Links & OTPs - send a link or code via email
2. OAuth - sign in with GitHub / Google / Apple etc.
3. Passwords - including password reset flow and optional email verification

The library doesn't come with UI components, but you can copy code from the docs and example repo to quickly build a UI in React.

Learn more in the [Convex Auth docs](https://labs.convex.dev/auth).

---

# Source: https://docs.convex.dev/testing/convex-backend.md

# Testing Local Backend

Alternatively to [`convex-test`](/testing/convex-test.md) you can test your functions using the [open-source version of the Convex backend](https://github.com/get-convex/convex-backend).

## Getting Started[​](#getting-started "Direct link to Getting Started")

Follow [this guide](https://stack.convex.dev/testing-with-local-oss-backend) for the instructions.

Compared to `convex-test`, which uses a JS mock of the backend, running your tests against the real backend has these advantages:

* Your tests will run against the same code as your Convex production (as long you keep the local backend up-to-date).
* Limits on argument, data, query sizes are enforced.
* You can bootstrap a large test dataset from a data import.
* You can test your client code in combination with your backend logic.

## Limitations[​](#limitations "Direct link to Limitations")

Note that testing against the local backend also has some drawbacks:

* It requires setting up the local backend, which is more involved.
* No control over time and any scheduled functions will run as scheduled.
* Crons will also run unless disabled via [`IS_TEST`](https://stack.convex.dev/testing-with-local-oss-backend#setting-up-a-local-backend).
* No way to mock `fetch` calls.
* No way to mock dependencies or parts of the codebase.
* No way to control randomness (tests may not be deterministic).
* No way to set environment variable values from within tests.

To test your functions in JS with a mocked Convex backend, check out [convex-test](/testing/convex-test.md).

## CI[​](#ci "Direct link to CI")

See [Continuous Integration](/testing/ci.md) to run your tests on a shared remote machine.

---

# Source: https://docs.convex.dev/deployment-api/convex-deployment-api.md

Version: 1.0.0

# Convex Deployment API

Admin API for interacting with deployments.

## Authentication[​](#authentication "Direct link to Authentication")

* API Key: Deploy Key
* API Key: OAuth Project Token
* API Key: OAuth Team Token
* API Key: Team Token

Deploy keys are used for deployment operations. See [deploy key types](https://docs.convex.dev/cli/deploy-key-types) for more information. Use the `Convex `prefix (e.g., `Convex <deploy_key>`).

| Security Scheme Type:  | apiKey        |
| ---------------------- | ------------- |
| Header parameter name: | Authorization |

Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api) with project scope. Use the `Convex `prefix (e.g., `Convex <oauth_project_token>`).

| Security Scheme Type:  | apiKey        |
| ---------------------- | ------------- |
| Header parameter name: | Authorization |

Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api). Use the `Convex `prefix (e.g., `Convex <oauth_token>`).

| Security Scheme Type:  | apiKey        |
| ---------------------- | ------------- |
| Header parameter name: | Authorization |

Created in the dashboard under team settings for any team you can manage. Use the `Convex `prefix (e.g., `Convex <team_token>`).

| Security Scheme Type:  | apiKey        |
| ---------------------- | ------------- |
| Header parameter name: | Authorization |

### License

---

# Source: https://docs.convex.dev/management-api/convex-management-api.md

Version: 1.0.0

# Convex Management API

Management API for provisioning and managing Convex projects and deployments.

## Authentication[​](#authentication "Direct link to Authentication")

* HTTP: Bearer Auth
* HTTP: Bearer Auth
* HTTP: Bearer Auth

Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api).

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |

Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api).

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |

Created in the dashboard under team settings for any team you can manage.

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |

### License

---

# Source: https://docs.convex.dev/ai/convex-mcp-server.md

# Convex MCP Server

The Convex [Model Context Protocol](https://docs.cursor.com/context/model-context-protocol) (MCP) server provides several tools that allow AI agents to interact with your Convex deployment.

## Setup[​](#setup "Direct link to Setup")

Add the following command to your MCP servers configuration:

`npx -y convex@latest mcp start`

For Cursor you can use this quick link to install:

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=convex\&config=eyJjb21tYW5kIjoibnB4IC15IGNvbnZleEBsYXRlc3QgbWNwIHN0YXJ0In0%3D)

or see editor specific instructions:

* [Cursor](/ai/using-cursor.md#setup-the-convex-mcp-server)
* [Windsurf](/ai/using-windsurf.md#setup-the-convex-mcp-server)
* [VS Code](/ai/using-github-copilot.md#setup-the-convex-mcp-server)
* Claude Code: add the MCP server and test with
  <!-- -->
  ```
  claude mcp add-json convex '{"type":"stdio","command":"npx","args":["convex","mcp","start"]}'
  claude mcp get convex
  ```

## Configuration Options[​](#configuration-options "Direct link to Configuration Options")

The MCP server supports several command-line options to customize its behavior:

### Project Directory[​](#project-directory "Direct link to Project Directory")

By default, the MCP server can run for multiple projects, and each tool call specifies its project directory. To run the server for a single project instead, use:

```
npx -y convex@latest mcp start --project-dir /path/to/project
```

### Deployment Selection[​](#deployment-selection "Direct link to Deployment Selection")

By default, the MCP server connects to your development deployment. You can specify a different deployment using these options:

* `--prod`: Run the MCP server on your project's production deployment (requires `--dangerously-enable-production-deployments`)
* `--preview-name <name>`: Run on a preview deployment with the given name
* `--deployment-name <name>`: Run on a specific deployment by name
* `--env-file <path>`: Path to a custom environment file for choosing the deployment (e.g., containing `CONVEX_DEPLOYMENT` or `CONVEX_SELF_HOSTED_URL`). Uses the same format as `.env.local` or `.env` files.

### Production Deployments[​](#production-deployments "Direct link to Production Deployments")

By default, the MCP server cannot access production deployments. This is a safety measure to prevent accidental modifications to production data. If you need to access production deployments, you must explicitly enable this:

```
npx -y convex@latest mcp start --dangerously-enable-production-deployments
```

Use with care

Enabling production access allows the MCP server to read and modify data in your production deployment. Only enable this when you specifically need to interact with production, and be careful with any operations that modify data.

### Disabling Tools[​](#disabling-tools "Direct link to Disabling Tools")

You can disable specific tools if you want to restrict what the MCP server can do:

```
npx -y convex@latest mcp start --disable-tools data,run,envSet
```

Available tools that can be disabled: `data`, `envGet`, `envList`, `envRemove`, `envSet`, `functionSpec`, `logs`, `run`, `runOneoffQuery`, `status`, `tables`

## Available Tools[​](#available-tools "Direct link to Available Tools")

### Deployment Tools[​](#deployment-tools "Direct link to Deployment Tools")

* **`status`**: Queries available deployments and returns a deployment selector that can be used with other tools. This is typically the first tool you'll use to find your Convex deployment.

### Table Tools[​](#table-tools "Direct link to Table Tools")

* **`tables`**: Lists all tables in a deployment along with their:

  * Declared schemas (if present)
  * Inferred schemas (automatically tracked by Convex)
  * Table names and metadata

* **`data`**: Allows pagination through documents in a specified table.

* **`runOneoffQuery`**: Enables writing and executing sandboxed JavaScript queries against your deployment's data. These queries are read-only and cannot modify the database.

### Function Tools[​](#function-tools "Direct link to Function Tools")

* **`functionSpec`**: Provides metadata about all deployed functions, including:

  * Function types
  * Visibility settings
  * Interface specifications

* **`run`**: Executes deployed Convex functions with provided arguments.

* **`logs`**: Fetches a chunk of recent function execution log entries, similar to `npx convex logs` but as structured objects.

### Environment Variable Tools[​](#environment-variable-tools "Direct link to Environment Variable Tools")

* **`envList`**: Lists all environment variables for a deployment
* **`envGet`**: Retrieves the value of a specific environment variable
* **`envSet`**: Sets a new environment variable or updates an existing one
* **`envRemove`**: Removes an environment variable from the deployment

[Read more about how to use the Convex MCP Server](https://stack.convex.dev/convex-mcp-server)

---

# Source: https://docs.convex.dev/public-deployment-api/convex-public-http-routes.md

Version: 1.0.0

# Convex Public HTTP routes

Endpoints that require no authentication

### License

---

# Source: https://docs.convex.dev/testing/convex-test.md

# convex-test

The [`convex-test`](https://www.npmjs.com/package/convex-test) library provides a mock implementation of the Convex backend in JavaScript. It enables fast automated testing of the logic in your [functions](/functions.md).

## Example[​](#example "Direct link to Example")

convex/posts.test.ts

TS

```
import { convexTest } from "convex-test";
import { describe, it, expect } from "vitest";
import { api, internal } from "./_generated/api";
import schema from "./schema";

describe("posts.list", () => {
  it("returns empty array when no posts exist", async () => {
    const t = convexTest(schema, modules);

    // Initially, there are no posts, so `list` returns an empty array
    const posts = await t.query(api.posts.list);
    expect(posts).toEqual([]);
  });

  it("returns all posts ordered by creation time when there are posts", async () => {
    const t = convexTest(schema, modules);

    // Create some posts
    await t.mutation(internal.posts.add, {
      title: "First Post",
      content: "This is the first post",
      author: "Alice",
    });
    await t.mutation(internal.posts.add, {
      title: "Second Post",
      content: "This is the second post",
      author: "Bob",
    });

    // `list` returns all posts ordered by creation time
    const posts = await t.query(api.posts.list);
    expect(posts).toHaveLength(2);
    expect(posts[0].title).toBe("Second Post");
    expect(posts[1].title).toBe("First Post");
  });
});

const modules = import.meta.glob("./**/*.ts");
```

You can see more examples in the [test suite](https://github.com/get-convex/convex-test/tree/main/convex) of the convex-test library.

## Get started[​](#get-started "Direct link to Get started")

1. Install test dependencies

   Install [Vitest](https://vitest.dev/) and the [`convex-test`](https://www.npmjs.com/package/convex-test) library.

   ```
   npm install --save-dev convex-test vitest @edge-runtime/vm
   ```

2. Setup NPM scripts

   Add these scripts to your `package.json`

   package.json

   ```
   "scripts": {
     "test": "vitest",
     "test:once": "vitest run",
     "test:debug": "vitest --inspect-brk --no-file-parallelism",
     "test:coverage": "vitest run --coverage --coverage.reporter=text",
   }
   ```

3. Configure Vitest

   Add `vitest.config.ts` file to configure the test environment to better match the Convex runtime, and to inline the test library for better dependency tracking.

   If your Convex functions are in a directory other than `convex`

   If your project has a [different name or location configured](/production/project-configuration.md#changing-the-convex-folder-name-or-location) for the `convex/` folder in `convex.json`, you need to call [`import.meta.glob`](https://vitejs.dev/guide/features#glob-import) and pass the result as the second argument to `convexTest`.

   The argument to `import.meta.glob` must be a glob pattern matching all the files containing your Convex functions. The paths are relative to the test file in which `import.meta.glob` is called. It's best to do this in one place in your custom functions folder:

   src/convex/test.setup.ts

   TS

   ```
   /// <reference types="vite/client" />
   export const modules = import.meta.glob(
     "./**/!(*.*.*)*.*s"
   );
   ```

   This example glob pattern includes all files with a single extension ending in `s` (like `js` or `ts`) in the `src/convex` folder and any of its children.

   Use the result in your tests:

   src/convex/messages.test.ts

   TS

   ```
   import { convexTest } from "convex-test";
   import { test } from "vitest";
   import schema from "./schema";
   import { modules } from "./test.setup";

   test("some behavior", async () => {
     const t = convexTest(schema, modules);
     // use `t`...
   });
   ```

   Set up multiple test environments (e.g. Convex + frontend)

   If you want to use Vitest to test both your Convex functions and your React frontend, you might want to use multiple Vitest environments depending on the test file location via [environmentMatchGlobs](https://vitest.dev/config/#environmentmatchglobs):

   vitest.config.ts

   TS

   ```
   import { defineConfig } from "vitest/config";

   export default defineConfig({
     test: {
       environmentMatchGlobs: [
         // all tests in convex/ will run in edge-runtime
         ["convex/**", "edge-runtime"],
         // all other tests use jsdom
         ["**", "jsdom"],
       ],
       server: { deps: { inline: ["convex-test"] } },
     },
   });
   ```

   vitest.config.ts

   TS

   ```
   import { defineConfig } from "vitest/config";

   export default defineConfig({
     test: {
       environment: "edge-runtime",
       server: { deps: { inline: ["convex-test"] } },
     },
   });
   ```

4. Add a test file

   In your `convex` folder add a file ending in `.test.ts`

   The example test calls the `api.messages.send` mutation twice and then asserts that the `api.messages.list` query returns the expected results.

   convex/messages.test.ts

   TS

   ```
   import { convexTest } from "convex-test";
   import { expect, test } from "vitest";
   import { api } from "./_generated/api";
   import schema from "./schema";

   test("sending messages", async () => {
     const t = convexTest(schema);
     await t.mutation(api.messages.send, { body: "Hi!", author: "Sarah" });
     await t.mutation(api.messages.send, { body: "Hey!", author: "Tom" });
     const messages = await t.query(api.messages.list);
     expect(messages).toMatchObject([
       { body: "Hi!", author: "Sarah" },
       { body: "Hey!", author: "Tom" }
     ]);
   });
   ```

5. Run tests

   Start the tests with `npm run test`. When you change the test file or your functions the tests will rerun automatically.

   ```
   npm run test
   ```

If you're not familiar with Vitest, read the [Vitest Getting Started docs](https://vitest.dev/guide) first.

## Using convex-test[​](#using-convex-test "Direct link to Using convex-test")

### Initialize `convexTest`[​](#initialize-convextest "Direct link to initialize-convextest")

The library exports a `convexTest` function which should be called at the start of each of your tests. The function returns an object which is by convention stored in the `t` variable and which provides methods for exercising your Convex functions.

If your project uses a [schema](/database/schemas.md) you should pass it to the `convexTest` function:

convex/myFunctions.test.ts

TS

```
import { convexTest } from "convex-test";
import { test } from "vitest";
import schema from "./schema";

test("some behavior", async () => {
  const t = convexTest(schema);
  // use `t`...
});
```

Passing in the schema is required for the tests to correctly implement schema validation and for correct typing of [`t.run`](#setting-up-and-inspecting-data-and-storage-with-trun).

If you don't have a schema, call `convexTest()` with no argument.

### Call functions[​](#call-functions "Direct link to Call functions")

Your test can call public and internal Convex [functions](/functions.md) in your project:

convex/myFunctions.test.ts

TS

```
import { convexTest } from "convex-test";
import { test } from "vitest";
import { api, internal } from "./_generated/api";

test("functions", async () => {
  const t = convexTest();
  const x = await t.query(api.myFunctions.myQuery, { a: 1, b: 2 });
  const y = await t.query(internal.myFunctions.internalQuery, { a: 1, b: 2 });
  const z = await t.mutation(api.myFunctions.mutateSomething, { a: 1, b: 2 });
  const w = await t.mutation(internal.myFunctions.mutateSomething, { a: 1 });
  const u = await t.action(api.myFunctions.doSomething, { a: 1, b: 2 });
  const v = await t.action(internal.myFunctions.internalAction, { a: 1, b: 2 });
});
```

### Modify data outside of functions[​](#modify-data-outside-of-functions "Direct link to Modify data outside of functions")

Sometimes you might want to directly [write](/database/writing-data.md) to the mock database or [file storage](/file-storage.md) from your test, without needing a declared function in your project. You can use the `t.run` method which takes a handler that is given a `ctx` that allows reading from and writing to the mock backend:

convex/tasks.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test } from "vitest";
import schema from "./schema";

test("functions", async () => {
  const t = convexTest(schema, modules);
  const firstTask = await t.run(async (ctx) => {
    await ctx.db.insert("tasks", { text: "Eat breakfast" });
    return await ctx.db.query("tasks").first();
  });
  expect(firstTask).toMatchObject({ text: "Eat breakfast" });
});

const modules = import.meta.glob("./**/*.ts");
```

### HTTP actions[​](#http-actions "Direct link to HTTP actions")

Your test can call [HTTP actions](/functions/http-actions.md) registered by your router:

convex/http.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test } from "vitest";
import schema from "./schema";

test("functions", async () => {
  const t = convexTest(schema, modules);
  const response = await t.fetch("/some/path", { method: "POST" });
  expect(response.status).toBe(200);
});

const modules = import.meta.glob("./**/*.ts");
```

Mocking the global `fetch` function doesn't affect `t.fetch`, but you can use `t.fetch` in a `fetch` mock to route to your HTTP actions.

### Scheduled functions[​](#scheduled-functions "Direct link to Scheduled functions")

One advantage of using a mock implementation running purely in JavaScript is that you can control time in the Vitest test environment. To test implementations relying on [scheduled functions](/scheduling/scheduled-functions.md) use [Vitest's fake timers](https://vitest.dev/guide/mocking.html#timers) in combination with `t.finishInProgressScheduledFunctions`:

convex/scheduling.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("mutation scheduling action", async () => {
  // Enable fake timers
  vi.useFakeTimers();

  const t = convexTest(schema, modules);

  // Call a function that schedules a mutation or action
  const scheduledFunctionId = await t.mutation(
    api.scheduler.mutationSchedulingAction,
    { delayMs: 10000 },
  );

  // Advance the mocked time
  vi.advanceTimersByTime(5000);

  // Advance the mocked time past the scheduled time of the function
  vi.advanceTimersByTime(6000);

  // Or run all currently pending timers
  vi.runAllTimers();

  // At this point the scheduled function will be `inProgress`,
  // now wait for it to finish
  await t.finishInProgressScheduledFunctions();

  // Assert that the scheduled function succeeded or failed
  const scheduledFunctionStatus = await t.run(async (ctx) => {
    return await ctx.db.system.get("_scheduled_functions", scheduledFunctionId);
  });
  expect(scheduledFunctionStatus).toMatchObject({ state: { kind: "success" } });

  // Reset to normal `setTimeout` etc. implementation
  vi.useRealTimers();
});

const modules = import.meta.glob("./**/*.ts");
```

If you have a chain of several scheduled functions, for example a mutation that schedules an action that schedules another action, you can use `t.finishAllScheduledFunctions` to wait for all scheduled functions, including recursively scheduled functions, to finish:

convex/chainedScheduling.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("mutation scheduling action scheduling action", async () => {
  // Enable fake timers
  vi.useFakeTimers();

  const t = convexTest(schema, modules);

  // Call a function that schedules a mutation or action
  await t.mutation(api.scheduler.mutationSchedulingActionSchedulingAction);

  // Wait for all scheduled functions, repeatedly
  // advancing time and waiting for currently in-progress
  // functions to finish
  await t.finishAllScheduledFunctions(vi.runAllTimers);

  // Assert the resulting state after all scheduled functions finished
  const createdTask = await t.run(async (ctx) => {
    return await ctx.db.query("tasks").first();
  });
  expect(createdTask).toMatchObject({ author: "AI" });

  // Reset to normal `setTimeout` etc. implementation
  vi.useRealTimers();
});

const modules = import.meta.glob("./**/*.ts");
```

Check out more examples in [this file](https://github.com/get-convex/convex-test/blob/main/convex/scheduler.test.ts).

### Authentication[​](#authentication "Direct link to Authentication")

To test functions which depend on the current [authenticated](/auth.md) user identity you can create a version of the `t` accessor with given [user identity attributes](/api/interfaces/server.UserIdentity.md). If you don't provide them, `issuer`, `subject` and `tokenIdentifier` will be generated automatically:

convex/tasks.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("authenticated functions", async () => {
  const t = convexTest(schema, modules);

  const asSarah = t.withIdentity({ name: "Sarah" });
  await asSarah.mutation(api.tasks.create, { text: "Add tests" });

  const sarahsTasks = await asSarah.query(api.tasks.list);
  expect(sarahsTasks).toMatchObject([{ text: "Add tests" }]);

  const asLee = t.withIdentity({ name: "Lee" });
  const leesTasks = await asLee.query(api.tasks.list);
  expect(leesTasks).toEqual([]);
});

const modules = import.meta.glob("./**/*.ts");
```

## Vitest tips[​](#vitest-tips "Direct link to Vitest tips")

### Asserting results[​](#asserting-results "Direct link to Asserting results")

See Vitest's [Expect](https://vitest.dev/api/expect.html) reference.

[`toMatchObject()`](https://vitest.dev/api/expect.html#tomatchobject) is particularly helpful when asserting the shape of results without needing to list every object field.

### Asserting errors[​](#asserting-errors "Direct link to Asserting errors")

To assert that a function throws, use [`.rejects.toThrowError()`](https://vitest.dev/api/expect.html#tothrowerror):

convex/messages.test.ts

TS

```
import { convexTest } from "convex-test";
import { expect, test } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("messages validation", async () => {
  const t = convexTest(schema, modules);
  await expect(async () => {
    await t.mutation(api.messages.send, { body: "", author: "James" });
  }).rejects.toThrowError("Empty message body is not allowed");
});

const modules = import.meta.glob("./**/*.ts");
```

### Mocking `fetch` calls[​](#mocking-fetch-calls "Direct link to mocking-fetch-calls")

You can use Vitest's [vi.stubGlobal](https://vitest.dev/guide/mocking.html#globals) method:

convex/ai.test.ts

TS

```
import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";
import { convexTest } from "convex-test";

test("ai", async () => {
  const t = convexTest(schema, modules);

  vi.stubGlobal(
    "fetch",
    vi.fn(async () => ({ text: async () => "I am the overlord" }) as Response),
  );

  const reply = await t.action(api.messages.sendAIMessage, { prompt: "hello" });
  expect(reply).toEqual("I am the overlord");

  vi.unstubAllGlobals();
});

const modules = import.meta.glob("./**/*.ts");
```

### Measuring test coverage[​](#measuring-test-coverage "Direct link to Measuring test coverage")

You can get a printout of the code coverage provided by your tests. Besides answering the question "how much of my code is covered by tests" it is also helpful to check that your test is actually exercising the code that you want it to exercise.

Run `npm run test:coverage`

``

. It will ask you to install a required dependency the first time you run it.

![example coverage printout](/screenshots/testing_coverage.png)

### Debugging tests[​](#debugging-tests "Direct link to Debugging tests")

You can attach a debugger to the running tests. Read the Vitest [Debugging docs](https://vitest.dev/guide/debugging.html) and then use

`npm run test:debug`

``

.

## Limitations[​](#limitations "Direct link to Limitations")

Since `convex-test` is only a mock implementation, it doesn't have many of the behaviors of the real Convex backend. Still, it should be helpful for testing the logic in your functions, and catching regressions caused by changes to your code.

Some of the ways the mock differs:

* Error messages content. You should not write product logic that relies on the content of error messages thrown by the real backend, as they are always subject to change.

* Limits. The mock doesn't enforce size and time [limits](/production/state/limits.md).

* ID format. Your code should not depend on the document or storage ID format.

* Runtime built-ins. Most of your functions are written for the [Convex default runtime](/functions/runtimes.md), while Vitest uses a mock of Vercel's Edge Runtime, which is similar but might differ from the Convex runtime. You should always test new code manually to make sure it doesn't use built-ins not available in the Convex runtime.

* Some features have only simplified semantics, namely:

  <!-- -->

  * [Text search](/search.md) returns all documents that include a word for which at least one word in the searched string is a prefix. It does not sort the results by relevance.
  * [Vector search](/search/vector-search.md) returns results sorted by cosine similarity, but doesn't use an efficient vector index in its implementation.
  * There is no support for [cron jobs](/scheduling/cron-jobs.md), you should trigger your functions manually from the test.

To test your functions running on a real Convex backend, check out [Testing Local Backend](/testing/convex-backend.md).

## CI[​](#ci "Direct link to CI")

See [Continuous Integration](/testing/ci.md) to run your tests on a shared remote machine.

---

# Source: https://docs.convex.dev/management-api/create-custom-domain.md

# Create custom domain

```
POST 
/deployments/:deployment_name/create_custom_domain
```

Create custom domain

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/create-deploy-key.md

# Create deploy key

```
POST 
/deployments/:deployment_name/create_deploy_key
```

Create a deploy key like "dev<!-- -->:happy-animal-123<!-- -->|ey..." which can be used with the Convex CLI to develop against or deploy code.

When access to the deployment is granted through an OAuth token this deploy key will use the same OAuth-granted token.

When access to the deployment is granted any other way a new token will be created which grants access only to this deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/create-deployment.md

# Create deployment

```
POST 
/projects/:project_id/create_deployment
```

Create a new deployment for a project.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/create-log-stream.md

# Create log stream

```
POST 
/create_log_stream
```

Create a new log stream for the deployment. Errors if a log stream of the given type already exists.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/create-project.md

# Create project

```
POST 
/teams/:team_id/create_project
```

Create a new project on a team and provision a dev or prod deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/scheduling/cron-jobs.md

# Cron Jobs

Convex allows you to schedule functions to run on a recurring basis. For example, cron jobs can be used to clean up data at a regular interval, send a reminder email at the same time every month, or schedule a backup every Saturday.

**Example:** [Cron Jobs](https://github.com/get-convex/convex-demos/tree/main/cron-jobs)

## Defining your cron jobs[​](#defining-your-cron-jobs "Direct link to Defining your cron jobs")

Cron jobs are defined in a `crons.ts` file in your `convex/` directory and look like:

convex/crons.ts

TS

```
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

crons.interval(
  "clear messages table",
  { minutes: 1 }, // every minute
  internal.messages.clearAll,
);

crons.monthly(
  "payment reminder",
  { day: 1, hourUTC: 16, minuteUTC: 0 }, // Every month on the first day at 8:00am PST
  internal.payments.sendPaymentEmail,
  { email: "my_email@gmail.com" }, // argument to sendPaymentEmail
);

// An alternative way to create the same schedule as above with cron syntax
crons.cron(
  "payment reminder duplicate",
  "0 16 1 * *",
  internal.payments.sendPaymentEmail,
  { email: "my_email@gmail.com" }, // argument to sendPaymentEmail
);

export default crons;
```

The first argument is a unique identifier for the cron job.

The second argument is the schedule at which the function should run, see [Supported schedules](/scheduling/cron-jobs.md#supported-schedules) below.

The third argument is the name of the public function or [internal function](/functions/internal-functions.md), either a [mutation](/functions/mutation-functions.md) or an [action](/functions/actions.md).

## Supported schedules[​](#supported-schedules "Direct link to Supported schedules")

* [`crons.interval()`](/api/classes/server.Crons.md#interval) runs a function every specified number of `seconds`, `minutes`, or `hours`. The first run occurs when the cron job is first deployed to Convex. Unlike traditional crons, this option allows you to have seconds-level granularity.
* [`crons.cron()`](/api/classes/server.Crons.md#cron) the traditional way of specifying cron jobs by a string with five fields separated by spaces (e.g. `"* * * * *"`). Times in cron syntax are in the UTC timezone. [Crontab Guru](https://crontab.guru/) is a helpful resource for understanding and creating schedules in this format.
* [`crons.hourly()`](/api/classes/server.Crons.md#cron), [`crons.daily()`](/api/classes/server.Crons.md#daily), [`crons.weekly()`](/api/classes/server.Crons.md#weekly), [`crons.monthly()`](/api/classes/server.Crons.md#monthly) provide an alternative syntax for common cron schedules with explicitly named arguments.

## Viewing your cron jobs[​](#viewing-your-cron-jobs "Direct link to Viewing your cron jobs")

You can view all your cron jobs in the [Convex dashboard cron jobs view](/dashboard/deployments/schedules.md#cron-jobs-ui). You can view added, updated, and deleted cron jobs in the logs and history view. Results of previously executed runs of the cron jobs are also available in the logs view.

## Error handling[​](#error-handling "Direct link to Error handling")

Mutations and actions have the same guarantees that are described in [Error handling](/scheduling/scheduled-functions.md#error-handling) for scheduled functions.

At most one run of each cron job can be executing at any moment. If the function scheduled by the cron job takes too long to run, following runs of the cron job may be skipped to avoid execution from falling behind. Skipping a scheduled run of a cron job due to the previous run still executing logs a message visible in the logs view of the dashboard.

---

# Source: https://docs.convex.dev/auth/advanced/custom-auth.md

# Custom OIDC Provider

**Note: This is an advanced feature!** We recommend sticking with the [supported third-party authentication providers](/auth.md).

Convex can be integrated with any identity provider supporting the [OpenID Connect](https://openid.net/connect/) protocol. At minimum this means that the provider can issue [ID tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and exposes the corresponding [JWKS](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets). The ID token is passed from the client to your Convex backend which ensures that the token is valid and enables you to query the user information embedded in the token, as described in [Auth in Functions](/auth/functions-auth.md).

## Server-side integration[​](#server-side-integration "Direct link to Server-side integration")

Just like with [Clerk](/auth/clerk.md) and [Auth0](/auth/auth0.md), the backend needs to be aware of the domain of the Issuer and your application's specific applicationID for a given identity provider.

Add these to your `convex/auth.config.ts` file:

convex/auth.config.ts

TS

```
import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: "https://your.issuer.url.com",
      applicationID: "your-application-id",
    },
  ],
} satisfies AuthConfig;
```

The `applicationID` property must exactly match the `aud` field of your JWT and the `domain` property must exactly match the `iss` field of the JWT. Use a tool like [jwt.io](https://jwt.io/) to view an JWT and confirm these fields match exactly.

If multiple providers are provided, the first one fulfilling the above criteria will be used.

If you're not able to obtain tokens with an `aud` field, you'll need to instead configure a [Custom JWT](/auth/advanced/custom-jwt.md). If you're not sure if your token is an OIDC ID token, check [the spec](https://openid.net/specs/openid-connect-core-1_0-final.html#rfc.section.2) for a list of all required fields.

OIDC requires the routes `${domain}/.well-known/jwks.json` and `${domain}/.well-known/openid-configuration`. `domain` may include a path like `https://your.issuer.url.com/api/auth`. This isn't common for third party auth providers but may be useful if you're implementing OIDC on your own server.

## Client-side integration[​](#client-side-integration "Direct link to Client-side integration")

### Integrating a new identity provider[​](#integrating-a-new-identity-provider "Direct link to Integrating a new identity provider")

The [`ConvexProviderWithAuth`](/api/modules/react.md#convexproviderwithauth) component provides a convenient abstraction for building an auth integration similar to the ones Convex provides for [Clerk](/auth/clerk.md) and [Auth0](/auth/auth0.md).

In the following example we build an integration with an imaginary "ProviderX", whose React integration includes `AuthProviderXReactProvider` and `useProviderXAuth` hook.

First we replace `ConvexProvider` with `AuthProviderXReactProvider` wrapping `ConvexProviderWithAuth` at the root of our app:

src/index.js

```
import { AuthProviderXReactProvider } from "providerX";
import { ConvexProviderWithAuth } from "convex/react";

root.render(
  <StrictMode>
    <AuthProviderXReactProvider>
      <ConvexProviderWithAuth client={convex} useAuth={useAuthFromProviderX}>
        <App />
      </ConvexProviderWithAuth>
    </AuthProviderXReactProvider>
  </StrictMode>,
);
```

All we really need is to implement the `useAuthFromProviderX` hook which gets passed to the `ConvexProviderWithAuth` component.

This `useAuthFromProviderX` hook provides a translation between the auth provider API and the [`ConvexReactClient`](/api/classes/react.ConvexReactClient.md) API, which is ultimately responsible for making sure that the ID token is passed down to your Convex backend.

src/ConvexProviderWithProviderX.js

```
function useAuthFromProviderX() {
  const { isLoading, isAuthenticated, getToken } = useProviderXAuth();
  const fetchAccessToken = useCallback(
    async ({ forceRefreshToken }) => {
      // Here you can do whatever transformation to get the ID Token
      // or null
      // Make sure to fetch a new token when `forceRefreshToken` is true
      return await getToken({ ignoreCache: forceRefreshToken });
    },
    // If `getToken` isn't correctly memoized
    // remove it from this dependency array
    [getToken],
  );
  return useMemo(
    () => ({
      // Whether the auth provider is in a loading state
      isLoading: isLoading,
      // Whether the auth provider has the user signed in
      isAuthenticated: isAuthenticated ?? false,
      // The async function to fetch the ID token
      fetchAccessToken,
    }),
    [isLoading, isAuthenticated, fetchAccessToken],
  );
}
```

### Using the new provider[​](#using-the-new-provider "Direct link to Using the new provider")

If you successfully follow the steps above you can now use the standard Convex utilities for checking the authentication state: the [`useConvexAuth()`](/api/modules/react.md#useconvexauth) hook and the [`Authenticated`](/api/modules/react.md#authenticated), [`Unauthenticated`](/api/modules/react.md#authenticated) and [`AuthLoading`](/api/modules/react.md#authloading) helper components.

### Debugging[​](#debugging "Direct link to Debugging")

See [Debugging Authentication](/auth/debug.md).

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/auth/advanced/custom-jwt.md

# Custom JWT Provider

**Note: This is an advanced feature!** We recommend sticking with the [supported third-party authentication providers](/auth.md).

A [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) is a string combining three base64-encoded JSON objects containing claims about who a user is valid for a limited period of time like an hour. You can create them with a library like [jose](https://github.com/panva/jose) after receiving some evidence (typically a cookie) of a user's identity or get them from a third party authentication service like [Clerk](https://clerk.com). The information in a JWT is signed (the Convex deployment can tell the information is really from the issuer and hasn't been modified) but generally not encrypted (you can read it by base64-decoding the token or pasting it into [jwt.io](https://jwt.io/).

If the JWTs issued to your users by an authentication service contain the right fields to implement the OpenID Connect (OIDC) protocol, the easiest way to configure accepting these JWTs is adding an [OIDC Provider](/auth/advanced/custom-auth.md) entry in `convex/auth.config.ts`. If the authentication service or library you're using to issue JWTs doesn't support these fields (for example [OpenAuth](https://openauth.js.org/) JWTs missing an `aud` field because they implement the OAuth 2.0 spec but not OIDC) you'll need to configure a Custom JWT provider in the `convex/auth.config.ts` file.

Custom JWTs are required only to have header fields `kid`, `alg` and `typ`, and payload fields `sub`, `iss`, and `exp`. An `iat` field is also expected by Convex clients to implement token refreshing.

## Server-side integration[​](#server-side-integration "Direct link to Server-side integration")

Use `type: "customJwt"` to configure a Custom JWT auth provider:

convex/auth.config.ts

TS

```
import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      type: "customJwt",
      applicationID: "your-application-id",
      issuer: "https://your.issuer.url.com",
      jwks: "https://your.issuer.url.com/.well-known/jwks.json",
      algorithm: "RS256",
    },
  ],
};
```

* `applicationID`: Convex will verify that JWTs have this value in the `aud` claim. See below for important information regarding leaving this field out. The applicationID field is not required, but necessary to use with many authentication providers for security. Read more below before omitting it.
* `issuer`: The issuer URL of the JWT.
* `jwks`: The URL for fetching the JWKS (JSON Web Key Set) from the auth provider. If you'd like to avoid hitting an external service you may use a data URI, e.g. `"data:text/plain;charset=utf-8;base64,ey..."`
* `algorithm`: The algorithm used to sign the JWT. Only RS256 and ES256 are currently supported. See [RFC 7518](https://datatracker.ietf.org/doc/html/rfc7518#section-3.1) for more details.

The `issuer` property must exactly match the `iss` field of the JWT used and if specified the `applicationID` property must exactly match the `aud` field. If your JWT doesn't match, use a tool like [jwt.io](https://jwt.io/) to view an JWT and confirm these fields match exactly.

### Warning: omitting `applicationID` is often insecure[​](#warning-omitting-applicationid-is-often-insecure "Direct link to warning-omitting-applicationid-is-often-insecure")

Leaving out `applicationID` from an auth configuration means the `aud` (audience) field of your users' JWTs will not be verified. In many cases this is insecure because a JWT intended for another service can be used to impersonate them in your service.

Say a user has accounts with `https://todos.com` and `https://banking.com`, two services which use the same third-party authentication service, `accounts.google.com`. A JWT accepted by todos.com could be reused to authenticate with banking.com by either todos.com or an attacker that obtained access to that JWT.

The `aud` (audience) field of the JWT prevents this: if the JWT was generated for a specific audience of `https://todos.com` then banking.com can enforce the `aud` field and know not to accept it.

If the JWTs issued to your users have an `iss` (issuer) URL like `https://accounts.google.com` that is not specific to your application, it is not secure to trust these tokens without an ApplicationID because that JWT could have been collected by a malicious application.

If the JWTs issued to your users have a more specific `iss` field like `https://api.3rd-party-auth.com/client_0123...` then it may be secure to use no `aud` field if you control all the services the issuer url grants then access to and intend for access to any one of these services to grants access to all of them.

### Custom claims[​](#custom-claims "Direct link to Custom claims")

In addition to top-level fields like `subject`, `issuer`, and `tokenIdentifier`, subfields of the nested fields of the JWT will be accessible in the auth data returned from `const authInfo = await ctx.auth.getUserIdentity()` like `authInfo["properties.id"]` and `authInfo["properties.favoriteColor"]` for a JWT structured like this:

```
{
  "properties": {
    "id": "123",
    "favoriteColor": "red"
  },
  "iss": "http://localhost:3000",
  "sub": "user:8fa2be73c2229e85",
  "exp": 1750968478
}
```

## Client-side integration[​](#client-side-integration "Direct link to Client-side integration")

Your users' browsers need a way to obtain an initial JWT and to request updated JWTs, ideally before the previous one expires.

See the instructions for [Custom OIDC Providers](/auth/advanced/custom-auth.md#client-side-integration) for how to do this.

---

# Source: https://docs.convex.dev/production/hosting/custom.md

# Custom Domains & Hosting

## Custom Domains[​](#custom-domains "Direct link to Custom Domains")

You can configure a custom domain, like `api.example.com`, to serve HTTP actions or Convex functions from your production Convex deployments. The settings for this feature are accessed through the Project Settings page on any of your projects.

![Add Custom Domain](/assets/images/add_custom_domain-2886f40eb3fd3ab420535fe0e9311908.png)

After you enter a domain, you will be shown which records to set on your DNS provider. Some popular DNS providers that you can use to buy a domain are Cloudflare and GoDaddy. We will verify your domain in the background, and once these records are set, you will see a green checkmark.

When you see that checkmark, your backend will now serve traffic from that domain. The first request may take up to a minute because Convex will have to mint a new SSL certificate.

Reach out to <support@convex.dev> if you have any questions about getting set up!

Custom domains require a Convex Pro plan.

Custom domains<!-- --> <!-- -->require<!-- --> a Convex Pro plan. [Learn more](https://convex.dev/pricing) about our plans or [upgrade](https://dashboard.convex.dev/team/settings/billing).

### Hosting with a Custom Domain[​](#hosting-with-a-custom-domain "Direct link to Hosting with a Custom Domain")

To use a custom domain to serve your Convex functions, there's an additional step: override the `CONVEX_CLOUD_URL` environment variable.

![Override system environment variables](/assets/images/override_system_env_vars-23e3d90ae07a8a7c7937e78fef9e6869.png)

Then re-deploy your project. This may entail clicking "Redeploy" in Vercel or Netlify, or directly running `npx convex deploy --cmd 'npm run build'`. The newly deployed code will access your Convex functions through your custom domain.

The `CONVEX_CLOUD_URL` environment variable is used in several places:

* `npx convex deploy --cmd '...'` sets `CONVEX_URL` (or similarly named) for your frontend to connect websockets and HTTP clients
* In your Convex functions, it is available as `process.env.CONVEX_CLOUD_URL`
* File storage URLs: `ctx.storage.getUrl(id)` and `ctx.storage.generateUploadUrl()`
* Generate an OpenAPI spec with `npx convex function-spec --prod`

You may also override the `CONVEX_SITE_URL` environment variable to be a custom HTTP Action domain.

* In your Convex functions, it is available as `process.env.CONVEX_SITE_URL`
* It may be used for webhooks
* It may be used in `auth.config.ts` as the `issuer` for Convex Auth

## Custom Hosting[​](#custom-hosting "Direct link to Custom Hosting")

If you're using only Convex for backend functionality you can host your web app on any static hosting provider. This guide will use [GitHub Pages](https://pages.github.com/) as an example.

If you're using Next.js or other framework with server functionality you'll need to use a provider that supports it, such as [Netlify](/production/hosting/netlify.md) or [Vercel](/production/hosting/vercel.md). You can still host Next.js statically via a [static export](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports).

### Configure your build[​](#configure-your-build "Direct link to Configure your build")

First make sure that you have a working build process.

In this guide we'll set up a local build, but your hosting provider might support a remote build. For example see [Vite's Deploying to GitHub Pages guide](https://vitejs.dev/guide/static-deploy.html#github-pages) which uses GitHub actions.

We'll use Vite and GitHub Pages as an example.

1. Configure `vite.config.mts`:

   vite.config.mts

   TS

   ```
   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";

   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [react()],
     build: {
       outDir: "docs",
     },
     base: "/some-repo-name/",
   });
   ```

   The `build.outDir` field specifies where Vite will place the production build, and we use `docs` because that's the directory GitHub Pages allow hosting from.

   The `base` field specifies the URL path under which you'll serve your app, in this case we will serve on `https://<some username>.github.io/<some repo name>`.

### Configure your hosting provider[​](#configure-your-hosting-provider "Direct link to Configure your hosting provider")

With GitHub Pages, you can choose whether you want to include your build output in your main working branch or publish from a separate branch.

Open your repository's GitHub page > *Settings* > *Pages*. Under *Build and deployment* > *Source* choose `Deploy from a branch`.

Under *branch* choose a branch (if you want to use a separate branch, push at least one commit to it first), and the `/docs` folder name. Hit *Save*.

### Build and deploy to Convex and GitHub Pages[​](#build-and-deploy-to-convex-and-github-pages "Direct link to Build and deploy to Convex and GitHub Pages")

To manually deploy to GitHub pages follow these steps:

1. Checkout the branch you chose to publish from
2. Run `npx convex deploy --cmd 'npm run build'` and confirm that you want to push your current backend code to your **production** deployment
3. Commit the build output changes and push to GitHub.

### How it works[​](#how-it-works "Direct link to How it works")

First, `npx convex deploy` runs through these steps:

1. It sets the `VITE_CONVEX_URL` (or similarly named) environment variable to your **production** Convex deployment.
2. It invokes the frontend framework build process, via `npm run build`. The build process reads the environment variable and uses it to point the built site at your **production** deployment.
3. It deploys your backend code, from the `convex` directory, to your **production** deployment.

Afterwards you deploy the built frontend code to your hosting provider. In this case you used Git, but for other providers you might use a different method, such as an old-school FTP request.

You can use `--cmd-url-env-var-name` to customize the variable name used by your frontend code if the `deploy` command cannot infer it, like

```
npx convex deploy --cmd-url-env-var-name CUSTOM_CONVEX_URL --cmd 'npm run build'
```

### Authentication[​](#authentication "Direct link to Authentication")

You will want to configure your [authentication](/auth.md) provider (Clerk, Auth0 or other) to accept your production URL, where your frontend is served.

---

# Source: https://docs.convex.dev/dashboard.md

# Dashboard

![Dashboard Projects View](/assets/images/projects-ea1be7a1deec4ee628278d2badc15e2f.png)

[The dashboard](https://dashboard.convex.dev/) is the central hub for managing your Convex projects. Here you can create and manage your Convex teams, projects, and deployments.

---

# Source: https://docs.convex.dev/generated-api/data-model.md

# dataModel.d.ts

This code is generated

These exports are not directly available in the `convex` package!

Instead you must run `npx convex dev` to create `convex/_generated/dataModel.d.ts`.

Generated data model types.

## Types[​](#types "Direct link to Types")

### TableNames[​](#tablenames "Direct link to TableNames")

Ƭ **TableNames**: `string`

The names of all of your Convex tables.

***

### Doc[​](#doc "Direct link to Doc")

Ƭ **Doc**`<TableName>`: `Object`

The type of a document stored in Convex.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                | Description                                             |
| ----------- | ----------------------------------- | ------------------------------------------------------- |
| `TableName` | extends [`TableNames`](#tablenames) | A string literal type of the table name (like "users"). |

***

### Id[​](#id "Direct link to Id")

An identifier for a document in Convex.

Convex documents are uniquely identified by their `Id`, which is accessible on the `_id` field. To learn more, see [Document IDs](/database/document-ids.md).

Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.

IDs are just strings at runtime, but this type can be used to distinguish them from other strings when type checking.

This is an alias of [`GenericId`](/api/modules/values.md#genericid) that is typed for your data model.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type                                | Description                                             |
| ----------- | ----------------------------------- | ------------------------------------------------------- |
| `TableName` | extends [`TableNames`](#tablenames) | A string literal type of the table name (like "users"). |

***

### DataModel[​](#datamodel "Direct link to DataModel")

Ƭ **DataModel**: `Object`

A type describing your Convex data model.

This type includes information about what tables you have, the type of documents stored in those tables, and the indexes defined on them.

This type is used to parameterize methods like [`queryGeneric`](/api/modules/server.md#querygeneric) and [`mutationGeneric`](/api/modules/server.md#mutationgeneric) to make them type-safe.

---

# Source: https://docs.convex.dev/client/swift/data-types.md

# Source: https://docs.convex.dev/client/android/data-types.md

# Kotlin and Convex type conversion

## Custom data types[​](#custom-data-types "Direct link to Custom data types")

When receiving values from Convex, you aren't limited to primitive values. You can create custom `@Serializable` classes that will be automatically decoded from response data.

Consider a Convex query function that returns results like this JavaScript object:

```
{
	name: "Guardians",
	uniformColors: ["blue", "white", "red"],
	wins: 80n,
	losses: 60n
}
```

That can be represented in Kotlin using:

```
@Serializable
data class BaseballTeam(
    val name: String,
    val uniformColors: List<String>,
    val wins: @ConvexNum Int,
    val losses: @ConvexNum Int)
```

Then you can pass it as the type argument in your `subscribe` call:

```
convex.subscribe<Team>("mlb:first_place_team", args = mapOf("division" to "AL Central"))
```

The data from the remote function will be deserialized to your custom class.

## Numerical types[​](#numerical-types "Direct link to Numerical types")

Your Convex backend code is written in JavaScript, which has two relatively common types for numerical data: `number` and `BigInt`.

`number` is used whenever a value is assigned a literal numeric value, whether `42` or `3.14`. `BigInt` can be used by adding a trailing `n`, like `42n`. Despite the two types, is very common to use `number` for holding either integer or floating point values in JavaScript.

Because of this, Convex takes extra care to encode values so they won't lose precision. Since technically the `number` type is an IEEE 754 floating point value, anytime you get a plain `number` from Convex it will be represented as floating point in Kotlin. You can choose to use `Double` or `Float`, depending on your needs but be aware that `Float` might lose precision from the original.

It also means that Kotlin's `Long` type (64 bit) can't be safely stored in a `number` (only 53 bits are available to encode integers) and requires a `BigInt`.

That's a long lead up to explain that in order to represent numerical values in responses from Convex, you need to hint to Kotlin that they should use custom decoding.

You can do this in three ways. Use whichever seems most useful to your project.

1. Annotate the plain Kotlin type (`Int`, `Long`, `Float`, `Double`) with `@ConvexNum`

2. Use a provided type alias for those types (`Int32`, `Int64`, `Float32`, `Float64`)

3. Include a special annotation at the top of any file that defines `@Serializable` classes and just use the plain types with no annotation

   ```
   @file:UseSerializers(
       Int64ToIntDecoder::class,
       Int64ToLongDecoder::class,
       Float64ToFloatDecoder::class,
       Float64ToDoubleDecoder::class
   )

   package com.example.convexapp

   import kotlinx.serialization.UseSerializers

   // @Serializable classes and things.
   ```

In the example, JavaScript's `BigInt` type is used by adding a trailing `n` to the `wins` and `losses` values which lets the Kotlin code use `Int`. If instead the code used regular JavaScript `number` types, on the Kotlin side those would be received as floating point values and deserialization would fail.

If you have a situation like that where `number` is used but by convention only contains integer values, you can handle that in your `@Serializable` class.

```
@Serializable
data class BaseballTeam(
    val name: String,
    val uniformColors: List<String>,
    @SerialName("wins") private val internalWins: Double,
    @SerialName("losses") private val internalLosses: Double) {

    // Expose the JavaScript number values as Ints.
    val wins get() = internalWins.toInt()
    val losses get() = internalLosses.toInt()
}
```

The pattern is to store the `Double` values privately and with different names that the value from the backend. Then add accessors to provide the `Int` values.

## Field name conversion[​](#field-name-conversion "Direct link to Field name conversion")

This pattern was used above, but it bears describing on its own. Sometimes a value will be produced on the backend with a key that matches a Kotlin keyword (`{fun: true}`) or doesn't conform to Kotlin naming conventions (e.g. starts with an underscore). You can use `@SerialName` to handle those cases.

For example, here's how you can ingest the Convex [document ID](https://docs.convex.dev/database/document-ids) from a backend response and convert it to a field name that won't trigger Kotlin lint warnings:

```
@Serializable
data class ConvexDocument(@SerialName("_id") val id: String)
```

---

# Source: https://docs.convex.dev/dashboard/deployments/data.md

# Data

![Data Dashboard Page](/assets/images/data-8f3dc6a4eb6c62497429e58ad703367b.png)

The [data page](https://dashboard.convex.dev/deployment/data) allows you to view and manage all of your tables and documents.

On the left side of the page is a list of your tables. Clicking on a table will allows you to create, view, update, and delete documents in that table.

You may drag-and-drop the column headers in each table to visually re-order the data.

A readonly view of the data page is available in the [command line](/cli.md#display-data-from-tables).

```
npx convex data [table]
```

## Filtering documents[​](#filtering-documents "Direct link to Filtering documents")

You may filters documents on the data page by clicking the "Filter" button on the top of the page.

![Data filters](/assets/images/data_filters-1d3e550f86642506f0507d143a070ab8.png)

All fields in a document are filterable by the operations supported in Convex query syntax. [Equality](/database/reading-data/filters.md#equality-conditions) and [comparisons](/database/reading-data/filters.md#comparisons) share the same rules when filtering in the dashboard as a query using the Convex client. You may also filter based on the type of the field.

To add a filter, click the `+` next to an existing filter. If you add more than one condition, they will be evaluated using the `and` operation.

For each filter, you must select a field to filter by, operation, and comparison value. In the third input box (selecting a value), you may enter a valid Convex value, such as `"a string"`, `123`, or even a complex object, such as `{ a: { b: 2 } }`

note

When filtering by `_creationTime`, a date picker will be displayed instead of the normal JavaScript syntax input box. Comparisons for `_creationTime` are made at the nanosecond granularity, so if you'd like to filter to an exact time, try adding two filter conditions for `creationTime >= $time` and `creationTime <= $time + 1 minute`.

## Writing custom queries[​](#writing-custom-queries "Direct link to Writing custom queries")

You can write a [query](/database/reading-data/.md) directly in the dashboard. This allows you to perform arbitrary filtering and transformation of the data, including sorting, joins, grouping and aggregations.

In the `⋮` overflow menu at the top of the data page click on the “Custom query” option.

![Custom query button](/screenshots/data_custom_query.png)

This opens the same UI used for [running your deployed functions](/dashboard/deployments/functions.md#running-functions), but with the “Custom test query” option selected, which lets you edit the source code for the query. This source code will be sent to your deployment and executed when you click on the “Run Custom Query“ button.

![Running a custom test query](/assets/images/data_custom_query_runner-3ed1f45c917689a4d0109d8759690e24.png)

If you're not on the data page, you can still open this UI via the persistent *fn* button shown on the bottom right of all deployment pages. The keyboard shortcut to open the function runner is Ctrl + \` (backtick).

## Creating tables[​](#creating-tables "Direct link to Creating tables")

You may create a table from the dashboard by clicking the "Create Table" button and entering a new name for the table.

## Creating documents[​](#creating-documents "Direct link to Creating documents")

You may add individual documents to the table using the “Add Documents” button located in the data table's toolbar.

Once you click “Add Documents” a side panel will open, allowing you to add new documents to your table using JavaScript syntax. To add more than one document add a time, add new objects to the array in the editor.

![Add document](/assets/images/data_add_document-f81e3b7952d2685f6d797773bb4c5b6d.png)

## Quick actions (context menu)[​](#quick-actions-context-menu "Direct link to Quick actions (context menu)")

You can right-click on a document or value to open a context menu with quick actions, like copying values, quickly filtering by the selected value, and deleting documents.

![Quick actions context menu](/assets/images/data_context_menu-dc17e11f1df2733cdcf9170af0baf0b1.png)

## Editing a cell[​](#editing-a-cell "Direct link to Editing a cell")

To edit a cell's value, double-click on the cell in the data table, or press the Enter key while it’s selected. You can change the selected cell by using the arrow keys.

You can change the value by editing inline, and pressing enter to save.

note

You can even edit the type of your value here, as long as it satisfies your [schema](/database/schemas.md) — try replacing a string with an object!

![Inline value editor](/assets/images/data_edit_inline-eb2c461a2f3395ec975e6829eb70d66d.png)

## Editing a document[​](#editing-a-document "Direct link to Editing a document")

To edit multiple fields in a document at the same time, hover over the document and right-click to open the context menu. From there you can click on "Edit Document".

![Edit entire document](/assets/images/data_edit_document-23e314be7901f2892a2136350798afc6.png)

## Adding references to other documents[​](#adding-references-to-other-documents "Direct link to Adding references to other documents")

To reference another document, use the string ID of the document you want to reference.

You can copy the ID by clicking on its cell and pressing CTRL/CMD+C.

## Bulk editing documents[​](#bulk-editing-documents "Direct link to Bulk editing documents")

You can edit multiple or all documents at once. To select all documents click on the checkbox in the table header row. To select individual documents hover over the left-most cell and click the checkbox that appears. To select multiple adjacent documents at once, press the Shift key when clicking on the checkbox.

When at least one document is selected, the “(Bulk) Edit Document(s)” button will be visible in the table toolbar. Click the button and an editor will appear on the right hand side.

![Bulk edit documents](/assets/images/data_bulk_edit-77eab4f33e91c212d74c2b3664adea8d.png)

## Deleting documents[​](#deleting-documents "Direct link to Deleting documents")

When at least one document is selected (see above), the “Delete Document(s)” button will be visible in the table toolbar. Click the button to delete documents. If you're editing data in a production deployment a confirmation dialog will appear before the documents are deleted.

## Clear a table[​](#clear-a-table "Direct link to Clear a table")

You can also delete all documents by clicking on the `⋮` overflow menu at the top of the data page and clicking "Clear Table". This action will delete all documents in the table, without deleting the table itself.

In production environments, the Convex dashboard will have you type in the name of the table before deletion.

## Delete a table[​](#delete-a-table "Direct link to Delete a table")

This is a permanent action

Deleting a table is irreversible. In production environments, the Convex dashboard will have you type in the name of the table before deletion.

The "Delete table" button can be found by clicking on the `⋮` overflow menu at the top of the data page. This action will delete all documents this table, and remove the table from your list of tables. If this table had indexes, you will need to redeploy your convex functions (by running `npx convex deploy` or `npx convex dev` for production or development, respectively) to recreate the indexes.

## Generating a schema[​](#generating-a-schema "Direct link to Generating a schema")

At the bottom-left of the page is a "Generate Schema" button which you can click to have Convex generate a [schema](/database/schemas.md) of all your documents within this table.

![Generate Schema button](/assets/images/data_generate_schema-83edb92d597e55d5fc1f7c7fed701d47.png)

## View the schema of a table[​](#view-the-schema-of-a-table "Direct link to View the schema of a table")

The "Schema" button can be found by clicking on the `⋮` overflow menu at the top of the data page.

This button will open a panel showing the saved and generated [schemas](/database/schemas.md) associated with the selected table.

## View the indexes of a table[​](#view-the-indexes-of-a-table "Direct link to View the indexes of a table")

The "Indexes" button can be found by clicking on the `⋮` overflow menu at the top of the data page.

This button will open a panel showing the [indexes](/database/reading-data/indexes/.md) associated with the selected table.

Indexes that have not completed backfilling will be accompanied by a loading spinner next to their name.

---

# Source: https://docs.convex.dev/auth/database-auth.md

# Storing Users in the Convex Database

*If you're using [Convex Auth](/auth/convex-auth.md) the user information is already stored in your database. There's nothing else you need to implement.*

You might want to store user information directly in your Convex database, for the following reasons:

* Your functions need information about other users, not just about the currently logged-in user
* Your functions need access to information other than the fields available in the [Open ID Connect JWT](/auth/functions-auth.md)

There are two ways you can choose from for storing user information in your database (but only the second one allows storing information not contained in the JWT):

1. Have your app's [client call a mutation](#call-a-mutation-from-the-client) that stores the information from the JWT available on [`ctx.auth`](/api/interfaces/server.Auth.md)
2. [Implement a webhook](#set-up-webhooks) and have your identity provider call it whenever user information changes

## Call a mutation from the client[​](#call-a-mutation-from-the-client "Direct link to Call a mutation from the client")

**Example:** [Convex Authentication with Clerk](https://github.com/get-convex/convex-demos/tree/main/users-and-clerk)

### (optional) Users table schema[​](#optional-users-table-schema "Direct link to (optional) Users table schema")

You can define a `"users"` table, optionally with an [index](/database/reading-data/indexes/.md) for efficient looking up the users in the database.

In the examples below we will use the `tokenIdentifier` from the `ctx.auth.getUserIdentity()` to identify the user, but you could use the `subject` field (which is usually set to the unique user ID from your auth provider) or even `email`, if your authentication provider provides email verification and you have it enabled.

Which field you use will determine how multiple providers interact, and how hard it will be to migrate to a different provider.

convex/schema.ts

```
users: defineTable({
  name: v.string(),
  tokenIdentifier: v.string(),
}).index("by_token", ["tokenIdentifier"]),
```

### Mutation for storing current user[​](#mutation-for-storing-current-user "Direct link to Mutation for storing current user")

This is an example of a mutation that stores the user's `name` and `tokenIdentifier`:

convex/users.ts

TS

```
import { mutation } from "./_generated/server";

export const store = mutation({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      throw new Error("Called storeUser without authentication present");
    }

    // Check if we've already stored this identity before.
    // Note: If you don't want to define an index right away, you can use
    // ctx.db.query("users")
    //  .filter(q => q.eq(q.field("tokenIdentifier"), identity.tokenIdentifier))
    //  .unique();
    const user = await ctx.db
      .query("users")
      .withIndex("by_token", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
    if (user !== null) {
      // If we've seen this identity before but the name has changed, patch the value.
      if (user.name !== identity.name) {
        await ctx.db.patch(user._id, { name: identity.name });
      }
      return user._id;
    }
    // If it's a new identity, create a new `User`.
    return await ctx.db.insert("users", {
      name: identity.name ?? "Anonymous",
      tokenIdentifier: identity.tokenIdentifier,
    });
  },
});
```

### Calling the store user mutation from React[​](#calling-the-store-user-mutation-from-react "Direct link to Calling the store user mutation from React")

You can call this mutation when the user logs in from a `useEffect` hook. After the mutation succeeds you can update local state to reflect that the user has been stored.

This helper hook that does the job:

src/useStoreUserEffect.ts

TS

```
import { useUser } from "@clerk/clerk-react";
import { useConvexAuth } from "convex/react";
import { useEffect, useState } from "react";
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";
import { Id } from "../convex/_generated/dataModel";

export function useStoreUserEffect() {
  const { isLoading, isAuthenticated } = useConvexAuth();
  const { user } = useUser();
  // When this state is set we know the server
  // has stored the user.
  const [userId, setUserId] = useState<Id<"users"> | null>(null);
  const storeUser = useMutation(api.users.store);
  // Call the `storeUser` mutation function to store
  // the current user in the `users` table and return the `Id` value.
  useEffect(() => {
    // If the user is not logged in don't do anything
    if (!isAuthenticated) {
      return;
    }
    // Store the user in the database.
    // Recall that `storeUser` gets the user information via the `auth`
    // object on the server. You don't need to pass anything manually here.
    async function createUser() {
      const id = await storeUser();
      setUserId(id);
    }
    createUser();
    return () => setUserId(null);
    // Make sure the effect reruns if the user logs in with
    // a different identity
  }, [isAuthenticated, storeUser, user?.id]);
  // Combine the local state with the state from context
  return {
    isLoading: isLoading || (isAuthenticated && userId === null),
    isAuthenticated: isAuthenticated && userId !== null,
  };
}
```

You can use this hook in your top-level component. If your queries need the user document to be present, make sure that you only render the components that call them after the user has been stored:

src/App.tsx

TS

```
import { SignInButton, UserButton } from "@clerk/clerk-react";
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
import { useStoreUserEffect } from "./useStoreUserEffect.js";

function App() {
  const { isLoading, isAuthenticated } = useStoreUserEffect();
  return (
    <main>
      {isLoading ? (
        <>Loading...</>
      ) : !isAuthenticated ? (
        <SignInButton />
      ) : (
        <>
          <UserButton />
          <Content />
        </>
      )}
    </main>
  );
}

function Content() {
  const messages = useQuery(api.messages.getForCurrentUser);
  return <div>Authenticated content: {messages?.length}</div>;
}

export default App;
```

In this way the `useStoreUserEffect` hook replaces the `useConvexAuth` hook.

### Using the current user's document ID[​](#using-the-current-users-document-id "Direct link to Using the current user's document ID")

Similarly to the store user mutation, you can retrieve the current user's ID, or throw an error if the user hasn't been stored.

Now that you have users stored as documents in your Convex database, you can use their IDs as foreign keys in other documents:

convex/messages.ts

TS

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

export const send = mutation({
  args: { body: v.string() },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      throw new Error("Unauthenticated call to mutation");
    }
    const user = await ctx.db
      .query("users")
      .withIndex("by_token", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
    if (!user) {
      throw new Error("Unauthenticated call to mutation");
    }
    await ctx.db.insert("messages", { body: args.body, user: user._id });
  },
});
    // do something with `user`...
}
});
```

### Loading users by their ID[​](#loading-users-by-their-id "Direct link to Loading users by their ID")

The information about other users can be retrieved via their IDs:

convex/messages.ts

TS

```
import { query } from "./_generated/server";

export const list = query({
  args: {},
  handler: async (ctx) => {
    const messages = await ctx.db.query("messages").collect();
    return Promise.all(
      messages.map(async (message) => {
        // For each message in this channel, fetch the `User` who wrote it and
        // insert their name into the `author` field.
        const user = await ctx.db.get(message.user);
        return {
          author: user?.name ?? "Anonymous",
          ...message,
        };
      }),
    );
  },
});
```

## Set up webhooks[​](#set-up-webhooks "Direct link to Set up webhooks")

This guide will use Clerk, but Auth0 can be set up similarly via [Auth0 Actions](https://auth0.com/docs/customize/actions/actions-overview).

With this implementation Clerk will call your Convex backend via an HTTP endpoint any time a user signs up, updates or deletes their account.

**Example:** [Convex Authentication with Clerk and Webhooks](https://github.com/get-convex/convex-demos/tree/main/users-and-clerk-webhooks)

### Configure the webhook endpoint in Clerk[​](#configure-the-webhook-endpoint-in-clerk "Direct link to Configure the webhook endpoint in Clerk")

On your Clerk dashboard, go to *Webhooks*, click on *+ Add Endpoint*.

Set *Endpoint URL* to `https://<your deployment name>.convex.site/clerk-users-webhook` (note the domain ends in **`.site`**, not `.cloud`). You can see your deployment name in the `.env.local` file in your project directory, or on your Convex dashboard as part of the [Deployment URL](/dashboard/deployments/deployment-settings.md). For example, the endpoint URL could be: `https://happy-horse-123.convex.site/clerk-users-webhook`.

In *Message Filtering*, select **user** for all user events (scroll down or use the search input).

Click on *Create*.

After the endpoint is saved, copy the *Signing Secret* (on the right side of the UI), it should start with `whsec_`. Set it as the value of the `CLERK_WEBHOOK_SECRET` environment variable in your Convex [dashboard](https://dashboard.convex.dev).

### (optional) Users table schema[​](#optional-users-table-schema-1 "Direct link to (optional) Users table schema")

You can define a `"users"` table, optionally with an [index](/database/reading-data/indexes/.md) for efficient looking up the users in the database.

In the examples below we will use the `subject` from the `ctx.auth.getUserIdentity()` to identify the user, which should be set to the Clerk user ID.

convex/schema.ts

```
users: defineTable({
  name: v.string(),
  // this the Clerk ID, stored in the subject JWT field
  externalId: v.string(),
}).index("byExternalId", ["externalId"]),
```

### Mutations for upserting and deleting users[​](#mutations-for-upserting-and-deleting-users "Direct link to Mutations for upserting and deleting users")

This is an example of mutations that handle the updates received via the webhook:

convex/users.ts

TS

```
import { internalMutation, query, QueryCtx } from "./_generated/server";
import { UserJSON } from "@clerk/backend";
import { v, Validator } from "convex/values";

export const current = query({
  args: {},
  handler: async (ctx) => {
    return await getCurrentUser(ctx);
  },
});

export const upsertFromClerk = internalMutation({
  args: { data: v.any() as Validator<UserJSON> }, // no runtime validation, trust Clerk
  async handler(ctx, { data }) {
    const userAttributes = {
      name: `${data.first_name} ${data.last_name}`,
      externalId: data.id,
    };

    const user = await userByExternalId(ctx, data.id);
    if (user === null) {
      await ctx.db.insert("users", userAttributes);
    } else {
      await ctx.db.patch(user._id, userAttributes);
    }
  },
});

export const deleteFromClerk = internalMutation({
  args: { clerkUserId: v.string() },
  async handler(ctx, { clerkUserId }) {
    const user = await userByExternalId(ctx, clerkUserId);

    if (user !== null) {
      await ctx.db.delete(user._id);
    } else {
      console.warn(
        `Can't delete user, there is none for Clerk user ID: ${clerkUserId}`,
      );
    }
  },
});

export async function getCurrentUserOrThrow(ctx: QueryCtx) {
  const userRecord = await getCurrentUser(ctx);
  if (!userRecord) throw new Error("Can't get current user");
  return userRecord;
}

export async function getCurrentUser(ctx: QueryCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (identity === null) {
    return null;
  }
  return await userByExternalId(ctx, identity.subject);
}

async function userByExternalId(ctx: QueryCtx, externalId: string) {
  return await ctx.db
    .query("users")
    .withIndex("byExternalId", (q) => q.eq("externalId", externalId))
    .unique();
}
```

There are also a few helpers in this file:

* `current` exposes the user information to the client, which will helps the client determine whether the webhook already succeeded
* `upsertFromClerk` will be called when a user signs up or when they update their account
* `deleteFromClerk` will be called when a user deletes their account via Clerk UI from your app
* `getCurrentUserOrThrow` retrieves the currently logged-in user or throws an error
* `getCurrentUser` retrieves the currently logged-in user or returns null
* `userByExternalId` retrieves a user given the Clerk ID, and is used only for retrieving the current user or when updating an existing user via the webhook

### Webhook endpoint implementation[​](#webhook-endpoint-implementation "Direct link to Webhook endpoint implementation")

This how the actual HTTP endpoint can be implemented:

convex/http.ts

TS

```
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";
import type { WebhookEvent } from "@clerk/backend";
import { Webhook } from "svix";

const http = httpRouter();

http.route({
  path: "/clerk-users-webhook",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    const event = await validateRequest(request);
    if (!event) {
      return new Response("Error occured", { status: 400 });
    }
    switch (event.type) {
      case "user.created": // intentional fallthrough
      case "user.updated":
        await ctx.runMutation(internal.users.upsertFromClerk, {
          data: event.data,
        });
        break;

      case "user.deleted": {
        const clerkUserId = event.data.id!;
        await ctx.runMutation(internal.users.deleteFromClerk, { clerkUserId });
        break;
      }
      default:
        console.log("Ignored Clerk webhook event", event.type);
    }

    return new Response(null, { status: 200 });
  }),
});

async function validateRequest(req: Request): Promise<WebhookEvent | null> {
  const payloadString = await req.text();
  const svixHeaders = {
    "svix-id": req.headers.get("svix-id")!,
    "svix-timestamp": req.headers.get("svix-timestamp")!,
    "svix-signature": req.headers.get("svix-signature")!,
  };
  const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET!);
  try {
    return wh.verify(payloadString, svixHeaders) as unknown as WebhookEvent;
  } catch (error) {
    console.error("Error verifying webhook event", error);
    return null;
  }
}

export default http;
```

If you deploy your code now and sign in, you should see the user being created in your Convex database.

### Using the current user's document[​](#using-the-current-users-document "Direct link to Using the current user's document")

You can use the helpers defined before to retrieve the current user's document.

Now that you have users stored as documents in your Convex database, you can use their IDs as foreign keys in other documents:

convex/messages.ts

TS

```
import { v } from "convex/values";
import { mutation } from "./_generated/server";
import { getCurrentUserOrThrow } from "./users";

export const send = mutation({
  args: { body: v.string() },
  handler: async (ctx, args) => {
    const user = await getCurrentUserOrThrow(ctx);
    await ctx.db.insert("messages", { body: args.body, userId: user._id });
  },
});
```

### Loading users by their ID[​](#loading-users-by-their-id-1 "Direct link to Loading users by their ID")

The information about other users can be retrieved via their IDs:

convex/messages.ts

TS

```
export const list = query({
  args: {},
  handler: async (ctx) => {
    const messages = await ctx.db.query("messages").collect();
    return Promise.all(
      messages.map(async (message) => {
        // For each message in this channel, fetch the `User` who wrote it and
        // insert their name into the `author` field.
        const user = await ctx.db.get(message.user);
        return {
          author: user?.name ?? "Anonymous",
          ...message,
        };
      }),
    );
  },
});
```

### Waiting for current user to be stored[​](#waiting-for-current-user-to-be-stored "Direct link to Waiting for current user to be stored")

If you want to use the current user's document in a query, make sure that the user has already been stored. You can do this by explicitly checking for this condition before rendering the components that call the query, or before redirecting to the authenticated portion of your app.

For example you can define a hook that determines the current authentication state of the client, taking into account whether the current user has been stored:

src/useCurrentUser.ts

TS

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

export function useCurrentUser() {
  const { isLoading, isAuthenticated } = useConvexAuth();
  const user = useQuery(api.users.current);
  // Combine the authentication state with the user existence check
  return {
    isLoading: isLoading || (isAuthenticated && user === null),
    isAuthenticated: isAuthenticated && user !== null,
  };
}
```

And then you can use it to render the appropriate components:

src/App.tsx

TS

```
import { useCurrentUser } from "./useCurrentUser";

export default function App() {
  const { isLoading, isAuthenticated } = useCurrentUser();
  return (
    <main>
      {isLoading ? (
        <>Loading...</>
      ) : isAuthenticated ? (
        <Content />
      ) : (
        <LoginPage />
      )}
    </main>
  );
}
```

---

# Source: https://docs.convex.dev/database.md

# Database

The Convex database provides a relational data model, stores JSON-like documents, and can be used with or without a schema. It "just works," giving you predictable query performance in an easy-to-use interface.

Query and mutation [functions](/functions.md) read and write data through a lightweight JavaScript API. There is nothing to set up and no need to write any SQL. Just use JavaScript to express your app's needs.

Start by learning about the basics of [tables](#tables), [documents](#documents) and [schemas](#schemas) below, then move on to [Reading Data](/database/reading-data/.md) and [Writing Data](/database/writing-data.md).

As your app grows more complex you'll need more from your database:

* Relational data modeling with [Document IDs](/database/document-ids.md)
* Fast querying with [Indexes](/database/reading-data/indexes/.md)
* Exposing large datasets with [Paginated Queries](/database/pagination.md)
* Type safety by [Defining a Schema](/database/schemas.md)
* Interoperability with data [Import & Export](/database/import-export/.md)

## Tables[​](#tables "Direct link to Tables")

Your Convex deployment contains tables that hold your app's data. Initially, your deployment contains no tables or documents.

Each table springs into existence as soon as you add the first document to it.

```
// `friends` table doesn't exist.
await ctx.db.insert("friends", { name: "Jamie" });
// Now it does, and it has one document.
```

You do not have to specify a schema upfront or create tables explicitly.

## Documents[​](#documents "Direct link to Documents")

Tables contain documents. Documents are very similar to JavaScript objects. They have fields and values, and you can nest arrays or objects within them.

These are all valid Convex documents:

```
{}
{"name": "Jamie"}
{"name": {"first": "Ari", "second": "Cole"}, "age": 60}
```

They can also contain references to other documents in other tables. See [Data Types](/database/types.md) to learn more about the types supported in Convex and [Document IDs](/database/document-ids.md) to learn about how to use those types to model your data.

## Schemas[​](#schemas "Direct link to Schemas")

Though optional, schemas ensure that your data looks exactly how you want. For a simple chat app, the schema will look like this:

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

// @snippet start schema
export default defineSchema({
  messages: defineTable({
    author: v.id("users"),
    body: v.string(),
  }),
});
```

You can choose to be as flexible as you want by using types such as `v.any()` or as specific as you want by precisely describing a `v.object()`.

See [the schema documentation](/database/schemas.md) to learn more about schemas.

## [Next: Reading Data](/database/reading-data/.md)

[Query and read data from Convex database tables](/database/reading-data/.md)

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/auth/debug.md

# Debugging Authentication

You have followed one of our authentication guides but something is not working. You have double checked that you followed all the steps, and that you used the correct secrets, but you are still stuck.

## Frequently encountered issues[​](#frequently-encountered-issues "Direct link to Frequently encountered issues")

### `ctx.auth.getUserIdentity()` returns `null` in a query[​](#ctxauthgetuseridentity-returns-null-in-a-query "Direct link to ctxauthgetuseridentity-returns-null-in-a-query")

This often happens when subscribing to queries via `useQuery` in React, without waiting for the client to be authenticated. Even if the user has been logged-in previously, it takes some time for the client to authenticate with the Convex backend. Therefore on page load, `ctx.auth.getUserIdentity()` called within a query returns `null`.

To handle this, you can either:

1. Use the `Authenticated` component from `convex/react` to wrap the component that includes the `useQuery` call (see the last two steps in the [Clerk guide](/auth/clerk.md#get-started))
2. Or return `null` or some other "sentinel" value from the query and handle it on the client

If you are using `fetchQuery` for [Next.js Server Rendering](/client/nextjs/app-router/server-rendering.md), make sure you are explicitly passing in a JWT token as documented [here](/client/nextjs/app-router/server-rendering.md#server-side-authentication).

If this hasn't helped, follow the steps below to resolve your issue.

## Step 1: Check whether authentication works on the backend[​](#step-1-check-whether-authentication-works-on-the-backend "Direct link to Step 1: Check whether authentication works on the backend")

1. Add the following code to the *beginning* of your function (query, mutation, action or http action):

```
console.log("server identity", await ctx.auth.getUserIdentity());
```

2. Then call this function from whichever client you're using to talk to Convex.

3. Open the [logs page on your dashboard](https://dashboard.convex.dev/deployment/logs).

4. What do you see on the logs page?

   **Answer: I don't see anything**:

   * Potential cause: You don't have the right dashboard open. Confirm that the Deployment URL on *Settings* > *URL and Deploy Key* page matches how your client is configured.
   * Potential cause: Your client is not connected to Convex. Check your client logs (browser logs) for errors. Reload the page / restart the client.
   * Potential cause: The code has not been pushed. For dev deployments make sure you have `npx convex dev` running. For prod deployments make sure you successfully pushed via `npx convex deploy`. Go to the *Functions* page on the dashboard and check that the code shown there includes the `console.log` line you added.

   When you resolved the cause you should see the log appear.

   **Answer: I see a log with `'server identity' null`**:

   * Potential cause: The client is not supplying an auth token.
   * Potential cause: Your deployment is misconfigured.
   * Potential cause: Your client is misconfigured.

   Proceed to [step 2](#step-2-check-whether-authentication-works-on-the-frontend).

   **Answer: I see a log with `'server identity' { tokenIdentifier: '... }`**

   Great, you are all set!

## Step 2: Check whether authentication works on the frontend[​](#step-2-check-whether-authentication-works-on-the-frontend "Direct link to Step 2: Check whether authentication works on the frontend")

No matter which client you use, it must pass a JWT token to your backend for authentication to work.

The most bullet-proof way of ensuring your client is passing the token to the backend, is to inspect the traffic between them.

1. If you're using a client from the web browser, open the *Network* tab in your browser's developer tools.

2. Check the token

   * For Websocket-based clients (`ConvexReactClient` and `ConvexClient`), filter for the `sync` name and select `WS` as the type of traffic. Check the `sync` items. After the client is initialized (commonly after loading the page), it will send a message (check the *Messages* tab) with `type: "Authenticate"`, and `value` will be the authentication token.

     ![Network tab inspecting Websocket messages](/screenshots/auth-ws.png)

   * For HTTP based clients (`ConvexHTTPClient` and the [HTTP API](/http-api/.md)), select `Fetch/XHR` as the type of traffic. You should see an individual network request for each function call, with an `Authorization` header with value `Bearer `followed by the authentication token.

     ![Network tab inspecting HTTP headers](/screenshots/auth-http.png)

3. Do you see the authentication token in the traffic?

   **Answer: No**:

   * Potential cause: The Convex client is not configured to get/fetch a JWT token. You're not using `ConvexProviderWithClerk`/`ConvexProviderWithAuth0`/`ConvexProviderWithAuth` with the `ConvexReactClient` or you forgot to call `setAuth` on `ConvexHTTPClient` or `ConvexClient`.

   * Potential cause: You are not signed in, so the token is `null` or `undefined` and the `ConvexReactClient` skipped authentication altogether. Verify that you are signed in via `console.log`ing the token from whichever auth provider you are using:

     * Clerk:

       ```
       // import { useAuth } from "@clerk/nextjs"; // for Next.js
       import { useAuth } from "@clerk/clerk-react";

       const { getToken } = useAuth();
       console.log(getToken({ template: "convex" }));
       ```

     * Auth0:

       ```
       import { useAuth0 } from "@auth0/auth0-react";

       const { getAccessTokenSilently } = useAuth0();
       const response = await getAccessTokenSilently({
         detailedResponse: true,
       });
       const token = response.id_token;
       console.log(token);
       ```

     * Custom: However you implemented `useAuthFromProviderX`

     If you don't see a long string that looks like a token, check the browser logs for errors from your auth provider. If there are none, check the Network tab to see whether requests to your provider are failing. Perhaps the auth provider is misconfigured. Double check the auth provider configuration (in the corresponding React provider or however your auth provider is configured for the client). Try clearing your cookies in the browser (in dev tools *Application* > *Cookies* > *Clear all cookies* button).

   **Answer: Yes, I see a long string that looks like a JWT**:

   Great, copy the whole token (there can be `.`s in it, so make sure you're not copying just a portion of it).

4. Open <https://jwt.io/>, scroll down and paste the token in the Encoded textarea on the left of the page. On the right you should see:

   * In *HEADER*, `"typ": "JWT"`
   * in *PAYLOAD*, a valid JSON with at least `"aud"`, `"iss"` and `"sub"` fields. If you see gibberish in the payload you probably didn't copy the token correctly or it's not a valid JWT token.

   If you see a valid JWT token, repeat [step 1](#step-1-check-whether-authentication-works-on-the-backend). If you still don't see correct identity, proceed to step 3.

## Step 3: Check that backend configuration matches frontend configuration[​](#step-3-check-that-backend-configuration-matches-frontend-configuration "Direct link to Step 3: Check that backend configuration matches frontend configuration")

You have a valid JWT token on the frontend, and you know that it is being passed to the backend, but the backend is not validating it.

1. Open the *Settings* > *Authentication* on your dashboard. What do you see?

   **Answer: I see `This deployment has no configured authentication providers`**:

   * Cause: You do not have an `auth.config.ts` (or `auth.config.js`) file in your `convex` directory, or you haven't pushed your code. Follow the authentication guide to create a valid auth config file. For dev deployments make sure you have `npx convex dev` running. For prod deployments make sure you successfully pushed via `npx convex deploy`.

   \*\*Answer: I see one or more *Domain* and *Application ID* pairs.

Great, let's check they match the JWT token.

2. Look at the `iss` field in the JWT token payload at <https://jwt.io/>. Does it match a *Domain* on the *Authentication* page?

   **Answer: No, I don't see the `iss` URL on the Convex dashboard**:

   * Potential cause: You copied the wrong value into your

     `auth.config.ts`

     's `domain`, or into the environment variable that is used there. Go back to the authentication guide and make sure you have the right URL from your auth provider.

   * Potential cause: Your client is misconfigured:

     * Clerk: You have the wrong `publishableKey` configured. The key must belong to the Clerk instance that you used to configure your

       `auth.config.ts`.

       * Also make sure that the JWT token in Clerk is called `convex`, as that's the name `ConvexProviderWithClerk` uses to fetch the token!

     * Auth0: You have the wrong `domain` configured (on the client!). The domain must belong to the Auth0 instance that you used to configure your `auth.config.ts`.

     * Custom: Make sure that your client is correctly configured to match your `auth.config.ts`.

   **Answer: Yes, I do see the `iss` URL**:

   Great, let's move one.

3. Look at the `aud` field in the JWT token payload at <https://jwt.io/>. Does it match the *Application ID* under the correct *Domain* on the *Authentication* page?

   **Answer: No, I don't see the `aud` value in the *Application ID* field**:

   * Potential cause: You copied the wrong value into your
     <!-- -->
     `auth.config.ts`
     <!-- -->
     's `applicationID`, or into the environment variable that is used there. Go back to the authentication guide and make sure you have the right value from your auth provider.

   * Potential cause: Your client is misconfigured:

     <!-- -->

     * Clerk: You have the wrong `publishableKey` configured.The key must belong to the Clerk instance that you used to configure your `auth.config.ts`.
     * Auth0: You have the wrong `clientId` configured. Make sure you're using the right `clientId` for the Auth0 instance that you used to configure your `auth.config.ts`.
     * Custom: Make sure that your client is correctly configured to match your `auth.config.ts`.

   **Answer: Yes, I do see the `aud` value in the *Application ID* field**:

   Great, repeat [step 1](#step-1-check-whether-authentication-works-on-the-backend) and you should be all set!

---

# Source: https://docs.convex.dev/agents/debugging.md

# Source: https://docs.convex.dev/functions/debugging.md

# Debugging

Debugging is the process of figuring out why your code isn't behaving as you expect.

## Debugging during development[​](#debugging-during-development "Direct link to Debugging during development")

During development the built-in `console` API allows you to understand what's going on inside your functions:

convex/myFunctions.ts

TS

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

export const mutateSomething = mutation({
  args: { a: v.number(), b: v.number() },
  handler: (_, args) => {
    console.log("Received args", args);
    // ...
  },
});
```

The following methods are available in the [default Convex runtime](/functions/runtimes.md#default-convex-runtime):

* Logging values, with a specified severity level:

  <!-- -->

  * `console.log`
  * `console.info`
  * `console.warn`
  * `console.error`
  * `console.debug`

* Logging with a stack trace:
  <!-- -->
  * [`console.trace`](https://developer.mozilla.org/en-US/docs/Web/API/console/trace_static)

* Measuring execution time:

  <!-- -->

  * [`console.time`](https://developer.mozilla.org/en-US/docs/Web/API/console/time_static)
  * [`console.timeLog`](https://developer.mozilla.org/en-US/docs/Web/API/console/timelog_static)
  * [`console.timeEnd`](https://developer.mozilla.org/en-US/docs/Web/API/console/timeend_static)

The Convex backend also automatically logs all successful function executions and all errors thrown by your functions.

You can view these logs:

1. When using the [`ConvexReactClient`](/client/react.md), in your browser developer tools console pane. The logs are sent from your dev deployment to your client, and the client logs them to the browser. Production deployments [**do not** send logs to the client](/functions/error-handling/.md#differences-in-error-reporting-between-dev-and-prod).
2. In your Convex dashboard on the [Logs page](/dashboard/deployments/logs.md).
3. In your terminal with [`npx convex dev`](/cli.md#tail-deployment-logs) during development or [`npx convex logs`](/cli.md#tail-deployment-logs), which only prints logs.

### Using a debugger[​](#using-a-debugger "Direct link to Using a debugger")

You can exercise your functions from tests, in which case you can add `debugger;` statements and step through your code. See [Testing](/testing/convex-test.md#debugging-tests).

## Debugging in production[​](#debugging-in-production "Direct link to Debugging in production")

When debugging an issue in production your options are:

1. Leverage existing logging
2. Add more logging and deploy a new version of your backend to production

Convex backend currently only preserves a limited number of logs, and logs can be erased at any time when the Convex team performs internal maintenance and upgrades. You should therefore set up [log streaming and error reporting](/production/integrations/.md) integrations to enable your team easy access to historical logs and additional information logged by your client.

## Finding relevant logs by Request ID[​](#finding-relevant-logs-by-request-id "Direct link to Finding relevant logs by Request ID")

To find the appropriate logs for an error you or your users experience, Convex includes a Request ID in all exception messages in both dev and prod in this format: `[Request ID: <request_id>]`.

You can copy and paste a Request ID into your Convex dashboard to view the logs for functions started by that request. See the [Dashboard logs page](/dashboard/deployments/logs.md#filter-logs) for details.

---

# Source: https://docs.convex.dev/management-api/delete-custom-domain.md

# Delete custom domain

```
POST 
/deployments/:deployment_name/delete_custom_domain
```

Remove a custom domain from a deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/delete-deploy-key.md

# Delete deploy key

```
POST 
/deployments/:deployment_name/delete_deploy_key
```

Deletes a deploy key for the specified deployment. The `id` in the request body can be the full deploy key (with prefix), encoded token, or the name of the deploy key.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/delete-deployment.md

# Delete deployment

```
POST 
/deployments/:deployment_name/delete
```

Delete a deployment. This will delete all data and files in the deployment, so we recommend creating and downloading a backup before calling this endpoint. This does not delete the project itself.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/file-storage/delete-files.md

# Deleting Files

Files stored in Convex can be deleted from [mutations](/functions/mutation-functions.md), [actions](/functions/actions.md), and [HTTP actions](/functions/http-actions.md) via the [`storage.delete()`](/api/interfaces/server.StorageWriter.md#delete) function, which accepts a storage ID.

Storage IDs correspond to documents in the `"_storage"` system table (see [Metadata](/file-storage/file-metadata.md)), so they can be validated using the `v.id("_storage")`.

convex/images.ts

TS

```
import { v } from "convex/values";
import { Id } from "./_generated/dataModel";
import { mutation } from "./_generated/server";

export const deleteById = mutation({
  args: {
    storageId: v.id("_storage"),
  },
  handler: async (ctx, args) => {
    return await ctx.storage.delete(args.storageId);
  },
});
```

---

# Source: https://docs.convex.dev/deployment-api/delete-log-stream.md

# Delete log stream

```
POST 
/delete_log_stream/:id
```

Delete the deployment's log stream with the given id.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/delete-project.md

# Delete project

```
POST 
/projects/:project_id/delete
```

Delete a project. Deletes all deployments in the project as well.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/cli/deploy-key-types.md

# Deploy keys

When you can't log in or use the CLI interactively to specify a project or deployment, for example in a production build environment, the environment variable `CONVEX_DEPLOY_KEY` can be set to a deploy key to make convex CLI commands run non-interactively.

Deploy keys identify a deployment, project, or team; confer permission to take certain actions with those resources; and can change the behavior of the convex CLI.

### Developing locally does not require a deploy key[​](#developing-locally-does-not-require-a-deploy-key "Direct link to Developing locally does not require a deploy key")

Running `npx convex dev` on a new machine offers the choice to log in or run Convex locally without an account.

Logging in stores a *user token* at `~/.convex/config.json` which is used automatically for all CLI use going forward on that machine. This token grants permission to push code to and read/write data from any deployment this user has access to.

Using Convex locally without logging in ([anonymous development](/cli/local-deployments.md#anonymous-development)) creates a deployment locally and records this preference for this project in the `.env.local` file in the project directory. The *admin key* for this anonymous backend is stored in `~/.convex/anonymous-convex-backend-state/` along with its serialized data.

In either of these cases, there's no reason to set `CONVEX_DEPLOY_KEY`.

### How to set a deploy key[​](#how-to-set-a-deploy-key "Direct link to How to set a deploy key")

Generally deploys keys are set in a dashboard of the service that needs the key but in most shells you can set it right before the command, like

```
CONVEX_DEPLOY_KEY='key goes here' npx convex dev
```

or export it before you run the command

```
export CONVEX_DEPLOY_KEY='key goes here'
npx convex dev
```

or add it to your `.env.local` file where it will be found by `npx convex` when run in that directory.

# Common uses of deploy keys

### Deploying from build pipelines[​](#deploying-from-build-pipelines "Direct link to Deploying from build pipelines")

A *production deploy key* specifies the production deployment of a project and grants permissions to deploy code to it.

> `prod:qualified-jaguar-123|eyJ2...0=`

You can deploying code from a build pipeline where you can't log in (e.g. Vercel, Netlify, Cloudflare build pipelines)

Read more about [deploying to production](https://docs.convex.dev/production/hosting/).

### Deploying to preview deployments[​](#deploying-to-preview-deployments "Direct link to Deploying to preview deployments")

A *preview deploy key* looks like this:

> `preview:team-slug:project-slug|eyJ2...0=`

Use a preview deploy key to change the behavior of a normal `npx convex deploy` command to deploy to a preview branch.

Read more about [preview deployments](/production/hosting/preview-deployments.md).

### Admin keys[​](#admin-keys "Direct link to Admin keys")

An admin key provides complete control over a deployment.

An admin key might look like

> `bold-hyena-681|01c2...c09c`

Unlike other types of deploy key, an admin key does not require a network connection to <https://convex.dev> to be used since it's a irrevocable secret baked into the deployment when created.

These keys are used to control [anonymous](/cli/local-deployments.md#anonymous-development) Convex deployments locally without logging in, but rarely need to be set explicitly.

Setting `CONVEX_DEPLOY_KEY` to one will cause the Convex CLI to run against that deployment instead of offering a choice.

## Rarer types of deploy keys[​](#rarer-types-of-deploy-keys "Direct link to Rarer types of deploy keys")

### Project tokens[​](#project-tokens "Direct link to Project tokens")

A *project token* grants total control over a project to a convex CLI and carries with it the permission to create and use development and production deployments in that project.

> `project:team-slug:project-slug|eyJ2...0=`

Project tokens are obtained when a user grants an permission to use a project to an organization via an Convex OAuth application. Actions made with the token are on behalf of the user so if a user loses access to a project the token no longer grant access to it.

### Development deploy keys[​](#development-deploy-keys "Direct link to Development deploy keys")

A *dev deploy key* might be used to provide an agent full access to a single deployment for development.

> `dev:joyful-jaguar-123|eyJ2...0=`

This can help limit the blast radius when developing with an agent.

To give an agent exclusive access to its own dev deployment, see [Agent Mode](/cli/agent-mode.md).

---

# Source: https://docs.convex.dev/deployment-api.md

# Deployment API

The public interface of a Convex deployment is defined by the functions defined in files in a convex folder.

The public HTTP endpoints of every Convex deployment consist of custom HTTP endpoints defined by [HTTP Actions](/functions/http-actions.md) and a static [public HTTP API](/http-api/.md).

Deployments also provide private endpoints only for the administrators of that deployment:

* [Streaming export API](/streaming-export-api.md)
* [Streaming import API](/streaming-import-api.md)
* [Platform APIs](/deployment-platform-api.md)

---

# Source: https://docs.convex.dev/deployment-platform-api.md

# Deployment Platform API

info

The Convex Deployment API is openly available in Beta. Please contact <platforms@convex.dev> if your use case requires additional capabilities.

Unlike HTTP endpoints which expose application-specific functionality to clients, management API endpoints configure deployments (e.g. modifying environment variables).

## Authorization[​](#authorization "Direct link to Authorization")

The Deployment Management API requires a Authorization header with a key that grants admin access to that deployment.

[Deployment keys](https://docs.convex.dev/cli/deploy-key-types#development-deploy-keys) created in the [dashboard](https://docs.convex.dev/dashboard/deployments/deployment-settings#url-and-deploy-key) or by API calls can be used for these APIs.

[Team Access Tokens](/platform-apis.md#managing-your-own-projects) and [OAuth Application Tokens](/platform-apis/oauth-applications.md) can also be used in depending on whether you are using the Management API on behalf of your own team or on behalf of the team of a user of a Convex integration you've built.

Whatever type of key, add the string `"Convex "` to the front.

```
const token = "ey...0=";
const response = await fetch(
  "https://happy-otter-123.convex.cloud/api/v1/list_environment_variables",
  {
    headers: {
      Authorization: `Convex ${token}`,
    },
  },
);
console.log(await response.json());
```

---

# Source: https://docs.convex.dev/dashboard/deployments/deployment-settings.md

# Settings

The [deployment settings page](https://dashboard.convex.dev/deployment/settings) gives you access to information and configuration options related to a specific deployment (**production**, your personal **development** deployment, or a **preview** deployment).

## URL and Deploy Key[​](#url-and-deploy-key "Direct link to URL and Deploy Key")

The [URL and deploy key page](https://dashboard.convex.dev/deployment/settings) shows:

* The URL this deployment is hosted at. Some Convex integrations may require the deployment URL for configuration.
* The URL that HTTP Actions for this deployment should be sent to.
* The deployment's deploy key, used to [integrate with build tools such as Netlify and Vercel](/production/hosting/.md) and [syncing data with Fivetran and Airbyte](/production/integrations/streaming-import-export.md).

![Deployment Settings Dashboard Page](/assets/images/deployment_settings-58661797d5cadbc484d3d36dde845c04.png)

## Environment Variables[​](#environment-variables "Direct link to Environment Variables")

The [environment variables page](https://dashboard.convex.dev/deployment/settings/environment-variables) lets you add, change, remove and copy the deployment's [environment variables](/production/environment-variables.md).

![deployment settings environment variables page](/assets/images/deployment_settings_env_vars-e148766325f85db3409292b10f202bba.png)

## Authentication[​](#authentication "Direct link to Authentication")

The [authentication page](https://dashboard.convex.dev/deployment/settings/authentication) shows the values configured in your `auth.config.js` for user [authentication](/auth.md) implementation.

## Backup & Restore[​](#backup--restore "Direct link to Backup & Restore")

The [backup & restore page](https://dashboard.convex.dev/deployment/settings/backups) lets you [backup](/database/backup-restore.md) the data stored in your deployment's database and file storage. On this page, you can schedule periodic backups.

![deployment settings export page](/assets/images/backups-7e17da1541fc3eb26194a96ab33414ea.png)

## Integrations[​](#integrations "Direct link to Integrations")

The integrations page allows you to configure [log streaming](/production/integrations/.md), [exception reporting](/production/integrations/.md), and [streaming export](/production/integrations/streaming-import-export.md) integrations.

## Pause Deployment[​](#pause-deployment "Direct link to Pause Deployment")

On the [pause deployment page](https://dashboard.convex.dev/deployment/settings/pause-deployment) you can [pause your deployment](/production/pause-deployment.md) with the pause button.

![deployment settings pause deployment page](/assets/images/deployment_settings_pause-4e036413269bccced2d58a99d2bb6f98.png)

---

# Source: https://docs.convex.dev/client/react/deployment-urls.md

# Configuring Deployment URL

When [connecting to your backend](/client/react.md#connecting-to-a-backend) it's important to correctly configure the deployment URL.

### Create a Convex project[​](#create-a-convex-project "Direct link to Create a Convex project")

The first time you run

```
npx convex dev
```

in your project directory you will create a new Convex project.

Your new project includes two deployments: *production* and *development*. The *development* deployment's URL will be saved in `.env.local` or `.env` file, depending on the frontend framework or bundler you're using.

You can find the URLs of all deployments in a project by visiting the [deployment settings](/dashboard/deployments/deployment-settings.md) on your Convex [dashboard](https://dashboard.convex.dev).

### Configure the client[​](#configure-the-client "Direct link to Configure the client")

Construct a Convex React client by passing in the URL of the Convex deployment. There should generally be a single Convex client in a frontend application.

src/index.js

```
import { ConvexProvider, ConvexReactClient } from "convex/react";

const deploymentURL = import.meta.env.VITE_CONVEX_URL;

const convex = new ConvexReactClient(deploymentURL);
```

While this URL can be hardcoded, it's convenient to use an environment variable to determine which deployment the client should connect to.

Use an environment variable name accessible from your client code according to the frontend framework or bundler you're using.

### Choosing environment variable names[​](#choosing-environment-variable-names "Direct link to Choosing environment variable names")

To avoid unintentionally exposing secret environment variables in frontend code, many bundlers require environment variables referenced in frontend code to use a specific prefix.

[Vite](https://vitejs.dev/guide/env-and-mode.html) requires environment variables used in frontend code start with `VITE_`, so `VITE_CONVEX_URL` is a good name.

[Create React App](https://create-react-app.dev/docs/adding-custom-environment-variables/) requires environment variables used in frontend code to begin with `REACT_APP_`, so the code above uses `REACT_APP_CONVEX_URL`.

[Next.js](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser) requires them to begin with `NEXT_PUBLIC_`, so `NEXT_PUBLIC_CONVEX_URL` is a good name.

Bundlers provide different ways to access these variables too: while [Vite uses `import.meta.env.VARIABLE_NAME`](https://vitejs.dev/guide/env-and-mode.html), many other tools like Next.js use the Node.js-like [`process.env.VARIABLE_NAME`](https://nextjs.org/docs/basic-features/environment-variables)

```
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);
```

[`.env` files](https://www.npmjs.com/package/dotenv) are a common way to wire up different environment variable values in development and production environments. `npx convex dev` will save the deployment URL to the corresponding `.env` file, while trying to infer which bundler your project uses.

.env.local

```
NEXT_PUBLIC_CONVEX_URL=https://guiltless-dog-960.convex.cloud

# examples of other environment variables that might be passed to the frontend
NEXT_PUBLIC_SENTRY_DSN=https://123abc@o123.ingest.sentry.io/1234
NEXT_PUBLIC_LAUNCHDARKLY_SDK_CLIENT_SIDE_ID=01234567890abcdef
```

Your backend functions can use [environment variables](/production/environment-variables.md) configured on your dashboard. They do not source values from `.env` files.

---

# Source: https://docs.convex.dev/dashboard/deployments.md

# Deployments

Each project in Convex has a main production deployment, and each developer on your team can also set up their own personal development deployment. Additionally, there are [preview deployments](/production/hosting/preview-deployments.md) used to test backend changes before they're deployed to production.

While on a [deployment page](https://dashboard.convex.dev/deployment), you may switch between production, your development deployment, and any preview deployments by using the dropdown menu on the top-left of the page.

![Deployment switcher](/assets/images/deployment_menu-b2e23e5c7d44f8defdad7685df75ef29.png)

---

# Source: https://docs.convex.dev/database/document-ids.md

# Document IDs

**Example:** [Relational Data Modeling](https://github.com/get-convex/convex-demos/tree/main/relational-data-modeling)

Every document in convex has a globally unique string *document ID* that is automatically generated by the system.

```
const userId = await ctx.db.insert("users", { name: "Michael Jordan" });
```

You can use this ID to efficiently read a single document using the `get` method:

```
const retrievedUser = await ctx.db.get("users", userId);
```

You can access the ID of a document in the [`_id` field](/database/types.md#system-fields):

```
const userId = retrievedUser._id;
```

Also, this same ID can be used to update that document in place:

```
await ctx.db.patch("users", userId, { name: "Steph Curry" });
```

Convex generates an [`Id`](/generated-api/data-model.md#id) TypeScript type based on your [schema](/database/schemas.md) that is parameterized over your table names:

```
import { Id } from "./_generated/dataModel";

const userId: Id<"users"> = user._id;
```

IDs are strings at runtime, but the [`Id`](/generated-api/data-model.md#id) type can be used to distinguish IDs from other strings at compile time.

## References and relationships[​](#references-and-relationships "Direct link to References and relationships")

In Convex, you can reference a document simply by embedding its `Id` in another document:

```
await ctx.db.insert("books", {
  title,
  ownerId: user._id,
});
```

You can follow references with `ctx.db.get`:

```
const user = await ctx.db.get("users", book.ownerId);
```

And [query for documents](/database/reading-data/.md) with a reference:

```
const myBooks = await ctx.db
  .query("books")
  .filter((q) => q.eq(q.field("ownerId"), user._id))
  .collect();
```

Using `Id`s as references can allow you to build a complex data model.

## Trading off deeply nested documents vs. relationships[​](#trading-off-deeply-nested-documents-vs-relationships "Direct link to Trading off deeply nested documents vs. relationships")

While it's useful that Convex supports nested objects and arrays, you should keep documents relatively small in size. In practice, we recommend limiting Arrays to no more than 5-10 elements and avoiding deeply nested Objects.

Instead, leverage separate tables, documents, and references to structure your data. This will lead to better maintainability and performance as your project grows.

## Serializing IDs[​](#serializing-ids "Direct link to Serializing IDs")

IDs are strings, which can be easily inserted into URLs or stored outside of Convex.

You can pass an ID string from an external source (like a URL) into a Convex function and get the corresponding object. If you're using TypeScript on the client you can cast a string to the `Id` type:

src/App.tsx

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

export function App() {
  const id = localStorage.getItem("myIDStorage");
  const task = useQuery(api.tasks.getTask, { taskId: id as Id<"tasks"> });
  // ...
}
```

Since this ID is coming from an external source, use an argument validator or [`ctx.db.normalizeId`](/api/interfaces/server.GenericDatabaseReader.md#normalizeid) to confirm that the ID belongs to the expected table before returning the object.

convex/tasks.ts

TS

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

export const getTask = query({
  args: {
    taskId: v.id("tasks"),
  },
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);
    // ...
  },
});
```

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/platform-apis/embedded-dashboard.md

# Embedding the dashboard

Convex provides a hosted dashboard that is embeddable via iframe. Embedding the dashboard is useful for developers building AI app generators, like [Convex Chef](https://chef.convex.dev).

You can embed the Convex dashboard by adding an `<iframe>` to <https://dashboard-embedded.convex.dev>. Normally, the embedded dashboard requires the user to enter credentials to use it, but you may skip the login step by providing deployment credentials via a [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to the iframe.

When using `postMessage`, there may be a delay until the credentials are received. The default login page will be shown until credentials are received, so we recommend adding a delay before displaying the rendered iframe to avoid flashing a login screen.

This will share the credentials of the deployment client-side

When using `postMessage` to authenticate with the embedded dashboard, the deployment key will be shared with the end-user. This means that the user gets full control of the deployment. Do this only when sharing credentials with the user is safe, such as with an [OAuth Application](/platform-apis/oauth-applications.md) (for Convex deployments that are in the Convex account of the end user), or deploy keys [created with the Management API](/management-api/create-deploy-key.md) (if the Convex deployment is in a Convex account that the end user doesn’t control).

Required information for `postMessage`:

* `deploymentUrl`: The deployment cloud URL. Returned when creating the project with the [Create project API](/management-api/create-project.md)
* `deploymentName`: The readable identifier for the deployment. Returned when creating the project with the [Create project API](/management-api/create-project.md).
* `adminKey`: A deploy key scoped to the specified `deploymentName`. Can be retrieved with the [Create deploy key API](/management-api/create-deploy-key.md).

Optional configuration:

* `visiblePages`: An array of page keys to show in the sidebar. If not provided, all pages are shown. If an empty array is provided, the sidebar will be hidden. Available page keys: `"health"`, `"data"`, `"functions"`, `"files"`, `"schedules"`, `"logs"`, `"history"`, `"settings"`. Please note that this only changes the user interface on the client side, and does not strictly prevent the user from accessing the functionality exposed by the pages.

Here's an example of the Convex dashboard embedded in a React application:

```
import { useEffect, useRef } from "react";

export function Dashboard({
  deploymentUrl,
  deploymentName,
  deployKey,
  visiblePages,
}: {
  deploymentUrl: string;
  deploymentName: string;
  deployKey: string;
  visiblePages?: string[];
}) {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // We first wait for the iframe to send a dashboard-credentials-request message.
      // This makes sure that we don't send the credentials until the iframe is ready.
      if (event.data?.type !== "dashboard-credentials-request") {
        return;
      }
      iframeRef.current?.contentWindow?.postMessage(
        {
          type: "dashboard-credentials",
          adminKey: deployKey,
          deploymentUrl,
          deploymentName,
          // Optional: specify which pages to show
          visiblePages,
        },
        "*",
      );
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, [deploymentUrl, adminKey, deploymentName, visiblePages]);

  return (
    <iframe
      ref={iframeRef}
      // You can also default on other pages, for instance /functions, /files or /logs
      src="https://dashboard-embedded.convex.dev/data"
      allow="clipboard-write"
    />
  );
}
```

---

# Source: https://docs.convex.dev/production/environment-variables.md

# Environment Variables

Environment variables are key-value pairs that are useful for storing values you wouldn't want to put in code or in a table, such as an API key. You can set environment variables in Convex through the dashboard, and you can access them in [functions](/functions.md) using `process.env`.

## Setting environment variables[​](#setting-environment-variables "Direct link to Setting environment variables")

Under [Deployment Settings](/dashboard/deployments/deployment-settings.md) in the Dashboard, you can see a list of environment variables in the current deployment. ![Environment Variables Table](/assets/images/environment_variables_table-1d215d0d797cca385b2c94dad4e938b4.png)

You can add up to 100 environment variables. Environment variable names cannot be more than 40 characters long, and they must start with a letter and only contain letters numbers, and underscores. Environment variable values cannot be larger than 8KB.

You can modify environment variables using the pencil icon button:

![Edit Environment Variable](/assets/images/edit_environment_variable-24411104aa164c750be92ce82fce3f50.png)

Environment variables can also be viewed and modified with the [command line](/cli.md#read-and-write-environment-variables).

```
npx convex env list
npx convex env set API_KEY secret-api-key
```

### Using environment variables in dev and prod deployments[​](#using-environment-variables-in-dev-and-prod-deployments "Direct link to Using environment variables in dev and prod deployments")

Since environment variables are set per-deployment, you can use different values for the same key in dev and prod deployments. This can be useful for when you have different external accounts you'd like to use depending on the environment. For example, you might have a dev and prod SendGrid account for sending emails, and your function expects an environment variable called `SENDGRID_API_KEY` that should work in both environments.

If you expect an environment variable to be always present in a function, you must add it to **all** your deployments. In this example, you would add an environment variable with the name `SENDGRID_API_KEY` to your dev and prod deployments, with a different value for dev and prod.

## Accessing environment variables[​](#accessing-environment-variables "Direct link to Accessing environment variables")

You can access environment variables in Convex functions using `process.env.KEY`. If the variable is set it is a `string`, otherwise it is `undefined`. Here is an example of accessing an environment variable with the key `GIPHY_KEY`:

```
function giphyUrl(query) {
  return (
    "https://api.giphy.com/v1/gifs/translate?api_key=" +
    process.env.GIPHY_KEY +
    "&s=" +
    encodeURIComponent(query)
  );
}
```

Note that you should not condition your Convex function exports on environment variables. The set of Convex functions that can be called is determined during deployment and is not reevaluated when you change an environment variable. The following code will throw an error at runtime, if the DEBUG environment variable changes between deployment and calling the function.

```
// THIS WILL NOT WORK!
export const myFunc = process.env.DEBUG ? mutation(...) : internalMutation(...);
```

Similarly, environment variables used in cron definitions will only be reevaluated on deployment.

## System environment variables[​](#system-environment-variables "Direct link to System environment variables")

The following environment variables are always available in Convex functions:

* `CONVEX_CLOUD_URL` - Your deployment URL (eg. `https://dusty-nightingale-847.convex.cloud`) for use with Convex clients.
* `CONVEX_SITE_URL` - Your deployment site URL (eg. `https://dusty-nightingale-847.convex.site`) for use with [HTTP Actions](/functions/http-actions.md)

## Project environment variable defaults[​](#project-environment-variable-defaults "Direct link to Project environment variable defaults")

You can set up default environment variable values for a project for development and preview deployments in Project Settings.

![Project Default Environment Variables](/assets/images/project_default_environment_variables-94be77c692d0a3c9564cb7f642b6cb64.png)

These default values will be used when creating a new development or preview deployment, and will have no effect on existing deployments (they are not kept in sync).

The Deployment Settings will indicate when a deployment has environment variables that do not match the project defaults. ![Environment Variable Default Mismatch](/assets/images/environment_variable_default_diff-0d02a2a8fe3f8d48d2437e0908421368.png)

---

# Source: https://docs.convex.dev/functions/error-handling.md

# Error Handling

There are four reasons why your Convex [queries](/functions/query-functions.md) and [mutations](/functions/mutation-functions.md) may hit errors:

1. [Application Errors](#application-errors-expected-failures): The function code hits a logical condition that should stop further processing, and your code throws a `ConvexError`
2. Developer Errors: There is a bug in the function (like calling `db.get("documents", null)` instead of `db.get("documents", id)`).
3. [Read/Write Limit Errors](#readwrite-limit-errors): The function is retrieving or writing too much data.
4. Internal Convex Errors: There is a problem within Convex (like a network blip).

Convex will automatically handle internal Convex errors. If there are problems on our end, we'll automatically retry your queries and mutations until the problem is resolved and your queries and mutations succeed.

On the other hand, you must decide how to handle application, developer and read/write limit errors. When one of these errors happens, the best practices are to:

1. Show the user some appropriate UI.
2. Send the error to an exception reporting service using the [Exception Reporting Integration](/production/integrations/exception-reporting.md).
3. Log the incident using `console.*` and set up reporting with [Log Streaming](/production/integrations/log-streams/.md). This can be done in addition to the above options, and doesn't require an exception to be thrown.

Additionally, you might also want to send client-side errors to a service like [Sentry](https://sentry.io) to capture additional information for debugging and observability.

## Errors in queries[​](#errors-in-queries "Direct link to Errors in queries")

If your query function hits an error, the error will be sent to the client and thrown from your `useQuery` call site. **The best way to handle these errors is with a React [error boundary component](https://reactjs.org/docs/error-boundaries.html).**

Error boundaries allow you to catch errors thrown in their child component tree, render fallback UI, and send information about the error to your exception handling service. Adding error boundaries to your app is a great way to handle errors in Convex query functions as well as other errors in your React components. If you are using Sentry, you can use their [`Sentry.ErrorBoundary`](https://docs.sentry.io/platforms/javascript/guides/react/components/errorboundary/) component.

With error boundaries, you can decide how granular you'd like your fallback UI to be. One simple option is to wrap your entire application in a single error boundary like:

```
<StrictMode>
  <ErrorBoundary>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </ErrorBoundary>
</StrictMode>,
```

Then any error in any of your components will be caught by the boundary and render the same fallback UI.

On the other hand, if you'd like to enable some portions of your app to continue functioning even if other parts hit errors, you can instead wrap different parts of your app in separate error boundaries.

Retrying

Unlike other frameworks, there is no concept of "retrying" if your query function hits an error. Because Convex functions are [deterministic](/functions/query-functions.md#caching--reactivity--consistency), if the query function hits an error, retrying will always produce the same error. There is no point in running the query function with the same arguments again.

## Errors in mutations[​](#errors-in-mutations "Direct link to Errors in mutations")

If a mutation hits an error, this will

1. Cause the promise returned from your mutation call to be rejected.
2. Cause your [optimistic update](/client/react/optimistic-updates.md) to be rolled back.

If you have an exception service like [Sentry](https://sentry.io/) configured, it should report "unhandled promise rejections" like this automatically. That means that with no additional work your mutation errors should be reported.

Note that errors in mutations won't be caught by your error boundaries because the error doesn't happen as part of rendering your components.

If you would like to render UI specifically in response to a mutation failure, you can use `.catch` on your mutation call. For example:

```
sendMessage(newMessageText).catch((error) => {
  // Do something with `error` here
});
```

If you're using an `async` handled function you can also use `try...catch`:

```
try {
  await sendMessage(newMessageText);
} catch (error) {
  // Do something with `error` here
}
```

Reporting caught errors

If you handle your mutation error, it will no longer become an unhandled promise rejection. You may need to report this error to your exception handling service manually.

## Errors in action functions[​](#errors-in-action-functions "Direct link to Errors in action functions")

Unlike queries and mutations, [actions](//docs/functions/actions.mdx) may have side-effects and therefore can't be automatically retried by Convex when errors occur. For example, say your action sends a email. If it fails part-way through, Convex has no way of knowing if the email was already sent and can't safely retry the action. It is responsibility of the caller to handle errors raised by actions and retry if appropriate.

## Differences in error reporting between dev and prod[​](#differences-in-error-reporting-between-dev-and-prod "Direct link to Differences in error reporting between dev and prod")

Using a dev deployment any server error thrown on the client will include the original error message and a server-side stack trace to ease debugging.

Using a production deployment any server error will be redacted to only include the name of the function and a generic `"Server Error"` message, with no stack trace. Server [application errors](/functions/error-handling/application-errors.md) will still include their custom `data`.

Both development and production deployments log full errors with stack traces which can be found on the [Logs](/dashboard/deployments/logs.md) page of a given deployment.

## Application errors, expected failures[​](#application-errors-expected-failures "Direct link to Application errors, expected failures")

If you have expected ways your functions might fail, you can either return different values or throw `ConvexError`s.

See [Application Errors](/functions/error-handling/application-errors.md).

## Read/write limit errors[​](#readwrite-limit-errors "Direct link to Read/write limit errors")

To ensure uptime and guarantee performance, Convex will catch queries and mutations that try to read or write too much data. These limits are enforced at the level of a single query or mutation function execution. The exact limits are listed in [Limits](/production/state/limits.md#transactions).

Documents are "scanned" by the database to figure out which documents should be returned from `db.query`. So for example `db.query("table").take(5).collect()` will only need to scan 5 documents, but `db.query("table").filter(...).first()` might scan up to as many documents as there are in `"table"`, to find the first one that matches the given filter.

The number of calls to `db.get` and `db.query` has a limit to prevent a single query from subscribing to too many index ranges, or a mutation from reading from too many ranges that could cause conflicts.

In general, if you're running into these limits frequently, we recommend [indexing your queries](/database/reading-data/indexes/.md) to reduce the number of documents scanned, allowing you to avoid unnecessary reads. Queries that scan large swaths of your data may look innocent at first, but can easily blow up at any production scale. If your functions are close to hitting these limits they will log a warning.

For information on other limits, see [here](/production/state/limits.md).

## Debugging Errors[​](#debugging-errors "Direct link to Debugging Errors")

See [Debugging](/functions/debugging.md) and specifically [Finding relevant logs by Request ID](/functions/debugging.md#finding-relevant-logs-by-request-id).

## Related Components[​](#related-components "Direct link to Related Components")

[Convex Component](https://www.convex.dev/components/workpool)

### [Workpool](https://www.convex.dev/components/workpool)

[Workpool give critical tasks priority by organizing async operations into separate, customizable queues. Supports retries and parallelism limits.](https://www.convex.dev/components/workpool)

[Convex Component](https://www.convex.dev/components/workflow)

### [Workflow](https://www.convex.dev/components/workflow)

[Simplify programming long running code flows. Workflows execute durably with configurable retries and delays.](https://www.convex.dev/components/workflow)

---

# Source: https://docs.convex.dev/error.md

# Errors and Warnings

This page explains specific errors thrown by Convex.

See [Error Handling](/functions/error-handling/.md) to learn about handling errors in general.

## Write conflict: Optimistic concurrency control[​](#1 "Direct link to Write conflict: Optimistic concurrency control")

This system error is thrown when a mutation repeatedly fails due to conflicting changes from parallel mutation executions.

### Example A[​](#example-a "Direct link to Example A")

A mutation `updateCounter` always updates the same document:

```
export const updateCounter = mutation({
  args: {},
  handler: async (ctx) => {
    const doc = await ctx.db.get("counts", process.env.COUNTER_ID);
    await ctx.db.patch("counts", doc._id, { value: doc.value + 1 });
  },
});
```

If this mutation is called many times per second, many of its executions will conflict with each other. Convex internally does several retries to mitigate this concern, but if the mutation is called more rapidly than Convex can execute it, some of the invocations will eventually throw this error:

> failure `updateCounter`
>
> Documents read from or written to the table "counters" changed while this mutation was being run and on every subsequent retry. Another call to this mutation changed the document with ID "123456789101112".

The error message will note the table name, which mutation caused the conflict (in this example its another call to the same mutation), and one document ID which was part of the conflicting change.

### Example B[​](#example-b "Direct link to Example B")

Mutation `writeCount` depends on the entire `tasks` table:

```
export const writeCount = mutation({
  args: {
    target: v.id("counts"),
  },
  handler: async (ctx, args) => {
    const tasks = await ctx.db.query("tasks").collect();
    await ctx.db.patch("tasks", args.target, { value: tasks });
  },
});

export const addTask = mutation({
  args: {
    text: v.string(),
  },
  handler: async (ctx, args) => {
    await ctx.db.insert("tasks", { text: args.text });
  },
});
```

If the mutation `writeCount` is called at the same time as many calls to `addTask` are made, either of the mutations can fail with this error. This is because any change to the `"tasks"` table will conflict with the `writeCount` mutation:

> failure `writeCount`
>
> Documents read from or written to the table "tasks" changed while this mutation was being run and on every subsequent retry. A call to "addTask" changed the document with ID "123456789101112".

### Remediation[​](#remediation "Direct link to Remediation")

To fix this issue:

1. Make sure that your mutations only read the data they need. Consider reducing the amount of data read by using indexed queries with [selective index range expressions](https://docs.convex.dev/database/indexes/).
2. Make sure you are not calling a mutation an unexpected number of times, perhaps from an action inside a loop.
3. Design your data model such that it doesn't require making many writes to the same document.

### Resources[​](#resources "Direct link to Resources")

* Learn more about [optimistic concurrency control](/database/advanced/occ.md).
* See this [Stack post](https://stack.convex.dev/waitlist) for an example of designing an app to avoid mutation conflicts.

### Related Components[​](#related-components "Direct link to Related Components")

[Convex Component](https://www.convex.dev/components/workpool)

### [Workpool](https://www.convex.dev/components/workpool)

[Workpool give critical tasks priority by organizing async operations into separate, customizable queues.](https://www.convex.dev/components/workpool)

[Convex Component](https://www.convex.dev/components/sharded-counter)

### [Sharded Counter](https://www.convex.dev/components/sharded-counter)

[High-throughput counter enables denormalized counts without write conflicts by spreading writes over multiple documents.](https://www.convex.dev/components/sharded-counter)

[Convex Component](https://www.convex.dev/components/action-cache)

### [Action Cache](https://www.convex.dev/components/action-cache)

[Cache frequently run actions. By leveraging the \`force\` parameter to keep the cache populated, you can ensure that the cache is always up to date and avoid data races.](https://www.convex.dev/components/action-cache)

## Undefined validator[​](#undefined-validator "Direct link to Undefined validator")

This error occurs when a validator passed to a Convex function definition or schema is `undefined`. This most commonly happens due to circular imports (also known as import cycles) in TypeScript.

### Example[​](#example "Direct link to Example")

You have two files that import from each other:

convex/validators.ts

TS

```
import { v } from "convex/values";
import { someUtility } from "./functions";

export const myValidator = v.object({
  name: v.string(),
});

// Uses someUtility somewhere...
```

convex/functions.ts

TS

```
import { mutation } from "./_generated/server";
// Both functions.ts and validators.ts import from each other.
import { myValidator } from "./validators";

export function someUtility() {
  // ...
}

export const myMutation = mutation({
  args: {
    data: myValidator, // <-- May be undefined due to import cycle
  },
  handler: async (ctx, args) => {
    // ...
  },
});
```

When `functions.ts` is loaded, it imports from `validators.ts`, which in turn tries to import from `functions.ts`. Since `functions.ts` hasn't finished the `import` statement yet, `myValidator` is still `undefined`, causing the `mutation` builder to throw an error.

Note: the value may be defined at runtime if you try to log it. This is only a quirk of TypeScript’s import time behavior.

### Cycles involving `schema.ts`[​](#cycles-involving-schemats "Direct link to cycles-involving-schemats")

A common way to accidentally introduce this kind of cycle is through your `schema.ts` file. Larger apps often define validators or whole tables in other files and import them into `schema.ts`.

If these files import from `schema.ts` or depend on files that do, you have a cycle.

```
schema.ts → validators.ts → someFile.ts → schema.ts
```

To break the cycle, define validators in "pure" files that have minimal dependencies, and import them into the places they are needed.

### Investigate circular imports[​](#investigate-circular-imports "Direct link to Investigate circular imports")

If you suspect a circular import but aren't sure where it is, tools like [madge](https://github.com/pahen/madge) can help you visualize your import graph and list cycles:

```
npx madge convex/ --extensions ts --exclude api.d.ts --circular
```

We exclude `api.d.ts` here because type-only imports are generally safe.

---

# Source: https://docs.convex.dev/eslint.md

# ESLint rules

The Convex ESLint plugin provides linter rules that enforce best practices for Convex functions. Let us know if there's a rule you would find helpful!

## Setup[​](#setup "Direct link to Setup")

For ESLint 9 (flat config, using `eslint.config.js`), install the rules with:

```
npm i @convex-dev/eslint-plugin --save-dev
```

and add this to your `eslint.config.js` file:

```
import { defineConfig } from "eslint/config";

import convexPlugin from "@convex-dev/eslint-plugin";

export default defineConfig([
  // Other configurations

  ...convexPlugin.configs.recommended,
]);
```

If you’re using the deprecated `.eslintrc.js` format

Install these two libraries:

```
npm i @typescript-eslint/eslint-plugin @convex-dev/eslint-plugin --save-dev
```

In `.eslintrc.js`, add:

```
module.exports =
  extends: [
    // Other configurations
    "plugin:@typescript-eslint/recommended",
    "plugin:@convex-dev/recommended",
  ],
  ignorePatterns: ["node_modules/", "dist/", "build/"],
};
```

If your Convex functions are in a directory other than `convex`

By default, the Convex ESLint plugin will only apply rules in the `convex` directory.

If you’re [customizing the Convex directory location](/production/project-configuration.md#changing-the-convex-folder-name-or-location), here’s how to adapt your ESLint configuration:

```
// eslint.config.js
import { defineConfig } from "eslint/config";

import convexPlugin from "@convex-dev/eslint-plugin";

const recommendedConfig = convexPlugin.configs.recommended[0];
const recommendedRules = recommendedConfig.rules;

export default defineConfig([
  // Other configurations go here...

  // Custom configuration with modified directory pattern
  {
    files: ["**/src/convex/**/*.ts"],
    plugins: {
      "@convex-dev": convexPlugin,
    },
    rules: recommendedRules,
  },
]);
```

If you’re using the `next lint` command from Next.js

For `next lint` to run ESLint on your `convex` directory you need to add that directory to the default set of directories. Add this section to your `next.config.ts`:

```
const nextConfig: NextConfig = {
  /* other options here */

  eslint: {
    dirs: ["pages", "app", "components", "lib", "src", "convex"],
  },
};
```

## Rules[​](#rules "Direct link to Rules")

| Rule                                                                                                                                     | Recommended | Auto-fixable |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------ |
| [`@convex-dev/no-old-registered-function-syntax`](#no-old-registered-function-syntax)<br />Prefer object syntax for registered functions | ✅          | 🔧           |
| [`@convex-dev/require-argument-validators`](#require-argument-validators)<br />Require argument validators for Convex functions          | ✅          | 🔧           |
| [`@convex-dev/explicit-table-ids`](#explicit-table-ids)<br />Require explicit table names in database operations                         | ✅          | 🔧           |
| [`@convex-dev/import-wrong-runtime`](#import-wrong-runtime)<br />Prevent Convex runtime files from importing from Node runtime files     |             |              |

### no-old-registered-function-syntax[​](#no-old-registered-function-syntax "Direct link to no-old-registered-function-syntax")

Prefer object syntax for registered functions.

Convex queries, mutations, and actions can be defined with a single function or with an object containing a handler property. Using the objects makes it possible to add argument and return value validators, so is always preferable.

```
// ✅ Allowed by this rule:
export const list = query({
  handler: async (ctx) => {
    const data = await ctx.db.query("messages").collect();
    ...
  },
});

// ❌ Not allowed by this rule:
export const list = query(async (ctx) => {
  const data = await ctx.db.query("messages").collect();
  ...
});
```

### require-argument-validators[​](#require-argument-validators "Direct link to require-argument-validators")

Require argument validators for Convex functions.

Convex queries, mutations, and actions can validate their arguments before beginning to run the handler function. Besides being a concise way to validate, the types of arguments, using argument validators enables generating more descriptive function specs and therefore OpenAPI bindings.

```
// ✅ Allowed by this rule:
export const list = query({
  args: {},
  handler: async (ctx) => {
    ...
  },
});

// ✅ Allowed by this rule:
export const list = query({
  args: { channel: v.id('channel') },
  handler: async (ctx, { channel }) => {
    ...
  },
});

// ❌ Not allowed with option { ignoreUnusedArguments: false } (default)
// ✅ Allowed with option { ignoreUnusedArguments: true }
export const list = query({
  handler: async (ctx) => {
    ...
  },
});

// ❌ Not allowed by this rule:
export const list = query({
  handler: async (ctx, { channel }: { channel: Id<"channel"> }) => {
    ...
  },
});
```

This rule can be customized to tolerate functions that don’t define an argument validator but don’t use their arguments. Here’s how you can set up the rule to work this way:

```
// eslint.config.js

export default defineConfig([
  // Your other rules…

  {
    files: ["**/convex/**/*.ts"],
    rules: {
      "@convex-dev/require-args-validator": [
        "error",
        {
          ignoreUnusedArguments: true,
        },
      ],
    },
  },
]);
```

### explicit-table-ids[​](#explicit-table-ids "Direct link to explicit-table-ids")

Require explicit table names in database operations.

Starting from version 1.31.0 of the `convex` npm package, we recommend including the table name as the first argument to database operations (`db.get`, `db.replace`, `db.patch`, `db.delete`).

This approach is more secure because it prevents vulnerabilities when an ID from one table is incorrectly typed as belonging to another table. The implicit syntax (where table names are inferred from the ID) will be deprecated in the future to give developers more control over ID generation. For both these reasons, we recommend developers to migrate to the new format.

This rule helps migrate code from the old implicit format to the new explicit format. It uses TypeScript type information to automatically infer the table name from the `Id<"tableName">` type and provides automatic fixes.

```
const messageId: Id<"messages"> = "123" as Id<"messages">;

// ✅ Allowed by this rule:
const message = await ctx.db.get("messages", messageId);
await ctx.db.patch("messages", messageId, { text: "updated" });
await ctx.db.replace("messages", messageId, {
  text: "replaced",
  author: "Alice",
});
await ctx.db.delete("messages", messageId);

// ❌ Not allowed by this rule:
const message = await ctx.db.get(messageId);
await ctx.db.patch(messageId, { text: "updated" });
await ctx.db.replace(messageId, { text: "replaced", author: "Alice" });
await ctx.db.delete(messageId);
```

typescript-eslint required

In order for this rule to work, [typescript-eslint](https://typescript-eslint.io) must be set up in your ESLint configuration. If typescript-eslint is installed and the rule doesn’t seem to work, please make sure that [type-aware linting](https://typescript-eslint.io/troubleshooting/typed-linting/) is enabled.

Note that if you’re not using ESLint, you can alternatively use the `@convex-dev/codemod` CLI tool to automatically migrate to the new format:

```
npx @convex-dev/codemod@latest explicit-ids
```

[Learn more on news.convex.dev →](https://news.convex.dev/db-table-name/)

### import-wrong-runtime[​](#import-wrong-runtime "Direct link to import-wrong-runtime")

Prevent Convex runtime files from importing from Node runtime files (files with a `"use node"` directive).

This rule is experimental. Please let us know if you find it helpful!

```
// In a file that doesn’t use `"use node"`:

// ✅ Allowed by this rule:
import { someFunction } from "./someOtherFile"; // where someOtherFile doesn't use `"use node"`

// ❌ Not allowed by this rule:
import { someFunction } from "./someNodeFile"; // where someNodeFile uses `"use node"`
```

---

# Source: https://docs.convex.dev/production/integrations/exception-reporting.md

# Exception Reporting

Configure exception reporting to gain visibility into errors from your Convex function executions. Convex supports integration with [Sentry](https://sentry.io/) and with [Datadog Error Tracking](https://www.datadoghq.com/product/error-tracking/).

Currently, exception reporting is only available to Pro users.

## Configuring Sentry[​](#configuring-sentry "Direct link to Configuring Sentry")

To configure sentry, navigate to the [Deployment Settings](/dashboard/deployments/deployment-settings.md) in the Dashboard, and the "Integrations" tab in the sidebar.

![Integrations Page](/assets/images/integrations_page-0f9edc52770c9caa6980330930e7517a.png)

Click on the Sentry card and follow the setup directions. You will need your [Sentry DSN](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/). You may optionally specify additional tags to be added to each exception event.

![Configure sentry](/assets/images/configure_sentry-4c105cf7c0923db0225a0465f15ec38e.png)

## Supported Tags[​](#supported-tags "Direct link to Supported Tags")

Convex automatically tags exception events on their way to sentry with the following tags. These tags cannot be overridden.

* `func`: The name of the running function in [string format](/functions/query-functions.md#query-names)
* `func_type`: One of `["query", "mutation", "action", "http_action"]`
* `func_runtime`: One of the [function runtimes](/functions/runtimes.md) - `["default", "node"]`
* `request_id`: The [request id](/functions/debugging.md#finding-relevant-logs-by-request-id) of the function that errored.
* `server_name`: The name of the deployment. e.g. `happy-animal-123`
* `environment`: One of `["prod", "dev", "preview"]`
* `user`: If the function is [authenticated](/auth.md), then the [tokenIdentifier](/api/interfaces/server.UserIdentity.md#tokenidentifier) is used as the user id on Sentry. The `tokenIdentifier` is a stable and globally unique string representing the authenticated user.

## Sentry Notes[​](#sentry-notes "Direct link to Sentry Notes")

* Sentry Exceptions may take a minute or two to propagate to Sentry.
* Convex's built-in sentry support does not yet support the advanced customization provided by the sentry SDK.
* Please reach out with any questions, comments, or suggestions [on Discord](https://convex.dev/community).

## Configuring Datadog Error Tracking[​](#configuring-datadog-error-tracking "Direct link to Configuring Datadog Error Tracking")

Follow the instructions in the [Datadog application](https://app.datadoghq.com/error-tracking/settings/setup/sentry) to configure Datadog error tracking via the Sentry SDK. Then use the Convex-Sentry integration to proceed.

---

# Source: https://docs.convex.dev/database/import-export/export.md

# Data Export

You can export your data from Convex by [taking a backup](/database/backup-restore.md) and downloading it as a zip file.

Alternatively, you can export the same data with the [command line](/cli.md#export-data-to-a-file):

```
npx convex export --path ~/Downloads
```

---

# Source: https://docs.convex.dev/file-storage/file-metadata.md

# Accessing File Metadata

Every stored file is reflected as a document in the `"_storage"` system table. File metadata of a file can be accessed from [queries](/functions/query-functions.md) and [mutations](/functions/mutation-functions.md) via `db.system.get` and `db.system.query`:

convex/images.ts

TS

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

export const getMetadata = query({
  args: {
    storageId: v.id("_storage"),
  },
  handler: async (ctx, args) => {
    return await ctx.db.system.get("_storage", args.storageId);
  },
});

export const listAllFiles = query({
  args: {},
  handler: async (ctx) => {
    // You can use .paginate() as well
    return await ctx.db.system.query("_storage").collect();
  },
});
```

This is an example of the returned document:

```
{
  "_creationTime": 1700697415295.742,
  "_id": "3k7ty84apk2zy00ay4st1n5p9kh7tf8",
  "contentType": "image/jpeg",
  "sha256": "cb58f529b2ed5a1b8b6681d91126265e919ac61fff6a367b8341c0f46b06a5bd",
  "size": 125338
}
```

The returned document has the following fields:

* `sha256`: a base16 encoded sha256 checksum of the file contents
* `size`: the size of the file in bytes
* `contentType`: the `ContentType` of the file if it was provided on upload

You can check the metadata manually on your [dashboard](/dashboard/deployments/file-storage.md).

## Accessing metadata from actions (deprecated)[​](#accessing-metadata-from-actions-deprecated "Direct link to Accessing metadata from actions (deprecated)")

Alternatively, a [`storage.getMetadata()`](/api/interfaces/server.StorageReader.md#getmetadata) function is available to access individual file metadata from [actions](/functions/actions.md) and [HTTP actions](/functions/http-actions.md):

convex/images.ts

TS

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

export const getMetadata = action({
  args: { storageId: v.id("_storage") },
  handler: async (ctx, args) => {
    return await ctx.storage.getMetadata(args.storageId);
  },
});
```

Note that [`storage.getMetadata()`](/api/interfaces/server.StorageReader.md#getmetadata) returns a [`FileMetadata`](/api/modules/server.md#filemetadata), which has a slightly different shape than the result from `db.system.get`.

---

# Source: https://docs.convex.dev/dashboard/deployments/file-storage.md

# Source: https://docs.convex.dev/file-storage.md

# File Storage

File Storage makes it easy to implement file upload in your app, store files from and send files to third-party APIs, and to serve dynamic files to your users. All file types are supported.

* [Upload](/file-storage/upload-files.md) files to store them in Convex and reference them in your database documents
* [Store](/file-storage/store-files.md) files generated or fetched from third-party APIs
* [Serve](/file-storage/serve-files.md) files via URL
* [Delete](/file-storage/delete-files.md) files stored in Convex
* Access file [metadata](/file-storage/file-metadata.md)

You can manage your stored files on the [dashboard](/dashboard/deployments/file-storage.md).

**Examples:** [File Storage with HTTP Actions](https://github.com/get-convex/convex-demos/tree/main/file-storage-with-http), [File Storage with Queries and Mutations](https://github.com/get-convex/convex-demos/tree/main/file-storage)

---

# Source: https://docs.convex.dev/agents/files.md

# Files and Images in Agent messages

You can add images and files for the LLM to reference in the messages.

NOTE: Sending URLs to LLMs is much easier with the cloud backend, since it has publicly available storage URLs. To develop locally you can use `ngrok` or similar to proxy the traffic.

Example code:

* [files/autoSave.ts](https://github.com/get-convex/agent/blob/main/example/convex/files/autoSave.ts) has a simple example of how to use the automatic file saving.
* [files/addFile.ts](https://github.com/get-convex/agent/blob/main/example/convex/files/addFile.ts) has an example of how to save the file, submit a question, and generate a response in separate steps.
* [files/generateImage.ts](https://github.com/get-convex/agent/blob/main/example/convex/files/generateImage.ts) has an example of how to generate an image and save it in an assistant message.
* [FilesImages.tsx](https://github.com/get-convex/agent/blob/main/example/ui/files/FilesImages.tsx) has client-side code.

## Running the example[​](#running-the-example "Direct link to Running the example")

```
git clone https://github.com/get-convex/agent.git
cd agent
npm run setup
npm run dev
```

## Sending an image by uploading first and generating asynchronously[​](#sending-an-image-by-uploading-first-and-generating-asynchronously "Direct link to Sending an image by uploading first and generating asynchronously")

The standard approach is to:

1. Upload the file to the database (`uploadFile` action). Note: this can be in a regular action or in an httpAction, depending on what's more convenient.
2. Send a message to the thread (`submitFileQuestion` action)
3. Send the file to the LLM to generate / stream text asynchronously (`generateResponse` action)
4. Query for the messages from the thread (`listThreadMessages` query)

Rationale:

It's better to submit a message in a mutation vs. an action because you can use an optimistic update on the client side to show the sent message immediately and have it disappear exactly when the message comes down in the query.

However, you can't save to file storage from a mutation, so the file needs to already exist (hence the fileId).

You can then asynchronously generate the response (with retries / etc) without the client waiting.

### 1: Saving the file[​](#1-saving-the-file "Direct link to 1: Saving the file")

```
import { storeFile } from "@convex-dev/agent";
import { components } from "./_generated/api";

const { file } = await storeFile(
  ctx,
  components.agent,
  new Blob([bytes], { type: mimeType }),
  {
    filename,
    sha256,
  },
);
const { fileId, url, storageId } = file;
```

### 2: Sending the message[​](#2-sending-the-message "Direct link to 2: Sending the message")

```
// in your mutation
const { filePart, imagePart } = await getFile(ctx, components.agent, fileId);
const { messageId } = await fileAgent.saveMessage(ctx, {
  threadId,
  message: {
    role: "user",
    content: [
      imagePart ?? filePart, // if it's an image, prefer that kind.
      { type: "text", text: "What is this image?" },
    ],
  },
  metadata: { fileIds: [fileId] }, // IMPORTANT: this tracks the file usage.
});
```

### 3: Generating the response & querying the responses[​](#3-generating-the-response--querying-the-responses "Direct link to 3: Generating the response & querying the responses")

This is done in the same way as text inputs.

```
// in an action
await thread.generateText({ promptMessageId: messageId });
```

```
// in a query
const messages = await agent.listMessages(ctx, { threadId, paginationOpts });
```

## Inline saving approach[​](#inline-saving-approach "Direct link to Inline saving approach")

You can also pass in an image / file direction when generating text, if you're in an action. Any image or file passed in the `message` argument will automatically be saved in file storage if it's larger than 64k, and a fileId will be saved to the message.

Example:

```
await thread.generateText({
  message: {
    role: "user",
    content: [
      { type: "image", image: imageBytes, mimeType: "image/png" },
      { type: "text", text: "What is this image?" },
    ],
  },
});
```

## Under the hood[​](#under-the-hood "Direct link to Under the hood")

Saving to the files has 3 components:

1. Saving to file storage (in your app, not in the component's storage). This means you can access it directly with the `storageId` and generate URLs.
2. Saving a reference (the storageId) to the file in the component. This will automatically keep track of how many messages are referencing the file, so you can vacuum files that are no longer used (see [files/vacuum.ts](https://github.com/get-convex/agent/blob/main/example/convex/files/vacuum.ts)).
3. Inserting a URL in place of the data in the message sent to the LLM, along with the mimeType and other metadata provided. It will be inferred if not provided in [`guessMimeType`](https://github.com/get-convex/agent/blob/main/src/mapping.ts#L556).

### Can I just store the file myself and pass in a URL?[​](#can-i-just-store-the-file-myself-and-pass-in-a-url "Direct link to Can I just store the file myself and pass in a URL?")

Yes! You can always pass a URL in the place of an image or file to the LLM.

```
const storageId = await ctx.storage.store(blob);
const url = await ctx.storage.getUrl(storageId);

await thread.generateText({
  message: {
    role: "user",
    content: [
      { type: "image", data: url, mimeType: blob.type },
      { type: "text", text: "What is this image?" },
    ],
  },
});
```

## Generating images[​](#generating-images "Direct link to Generating images")

There's an example in [files/generateImage.ts](https://github.com/get-convex/agent/blob/main/example/convex/files/generateImage.ts) that takes a prompt, generates an image with OpenAI's dall-e 2, then saves the image to a thread.

You can try it out with:

```
npx convex run files:generateImage:replyWithImage '{prompt: "make a picture of a cat" }'
```

---

# Source: https://docs.convex.dev/database/reading-data/filters.md

# Filtering

The [`filter`](/api/interfaces/server.Query.md#filter) method allows you to restrict the documents that your document query returns. This method takes a filter constructed by [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md) and will only select documents that match.

The examples below demonstrate some of the common uses of `filter`. You can see the full list of available filtering methods [in the reference docs](/api/interfaces/server.FilterBuilder.md).

If you need to filter to documents containing some keywords, use a [search query](/search/text-search.md).

Use indexes instead

Filters effectively loop over your table looking for documents that match. This can be slow or cause your function to hit a [limit](/production/state/limits.md) when your table has thousands of rows. For faster more database efficient queries use [indexes instead](/database/reading-data/indexes/.md).

### Equality conditions[​](#equality-conditions "Direct link to Equality conditions")

This document query finds documents in the `users` table where `doc.name === "Alex"`:

```
// Get all users named "Alex".
const usersNamedAlex = await ctx.db
  .query("users")
  .filter((q) => q.eq(q.field("name"), "Alex"))
  .collect();
```

Here `q` is the [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md) utility object. It contains methods for all of our supported filter operators.

This filter will run on all documents in the table. For each document, `q.field("name")` evaluates to the `name` property. Then `q.eq` checks if this property is equal to `"Alex"`.

If your query references a field that is missing from a given document then that field will be considered to have the value `undefined`.

### Comparisons[​](#comparisons "Direct link to Comparisons")

Filters can also be used to compare fields against values. This document query finds documents where `doc.age >= 18`:

```
// Get all users with an age of 18 or higher.
const adults = await ctx.db
  .query("users")
  .filter((q) => q.gte(q.field("age"), 18))
  .collect();
```

Here the `q.gte` operator checks if the first argument (`doc.age`) is greater than or equal to the second (`18`).

Here's the full list of comparisons:

| Operator      | Equivalent TypeScript |
| ------------- | --------------------- |
| `q.eq(l, r)`  | `l === r`             |
| `q.neq(l, r)` | `l !== r`             |
| `q.lt(l, r)`  | `l < r`               |
| `q.lte(l, r)` | `l <= r`              |
| `q.gt(l, r)`  | `l > r`               |
| `q.gte(l, r)` | `l >= r`              |

### Arithmetic[​](#arithmetic "Direct link to Arithmetic")

You can also include basic arithmetic in your queries. This document query finds documents in the `carpets` table where `doc.height * doc.width > 100`:

```
// Get all carpets that have an area of over 100.
const largeCarpets = await ctx.db
  .query("carpets")
  .filter((q) => q.gt(q.mul(q.field("height"), q.field("width")), 100))
  .collect();
```

Here's the full list of arithmetic operators:

| Operator      | Equivalent TypeScript |
| ------------- | --------------------- |
| `q.add(l, r)` | `l + r`               |
| `q.sub(l, r)` | `l - r`               |
| `q.mul(l, r)` | `l * r`               |
| `q.div(l, r)` | `l / r`               |
| `q.mod(l, r)` | `l % r`               |
| `q.neg(x)`    | `-x`                  |

### Combining operators[​](#combining-operators "Direct link to Combining operators")

You can construct more complex filters using methods like `q.and`, `q.or`, and `q.not`. This document query finds documents where `doc.name === "Alex" && doc.age >= 18`:

```
// Get all users named "Alex" whose age is at least 18.
const adultAlexes = await ctx.db
  .query("users")
  .filter((q) =>
    q.and(q.eq(q.field("name"), "Alex"), q.gte(q.field("age"), 18)),
  )
  .collect();
```

Here is a query that finds all users where `doc.name === "Alex" || doc.name === "Emma"`:

```
// Get all users named "Alex" or "Emma".
const usersNamedAlexOrEmma = await ctx.db
  .query("users")
  .filter((q) =>
    q.or(q.eq(q.field("name"), "Alex"), q.eq(q.field("name"), "Emma")),
  )
  .collect();
```

## Advanced filtering techniques[​](#advanced-filtering-techniques "Direct link to Advanced filtering techniques")

Sometimes the filter syntax is is not expressive enough. For example you may want to collect all posts that have a tag. Your schema for the posts looks like this:

```
export default defineSchema({
  posts: defineTable({
    body: v.string(),
    tags: v.array(v.string()),
  }),
});
```

One way to solve is by applying the filter on the result of the `collect()` call. This is just filtering a JavaScript array:

```
export const postsWithTag = query({
  args: { tag: v.string() },
  handler: async (ctx, args) => {
    const allPosts = await ctx.db.query("posts").collect();
    return allPosts.filter((post) => post.tags.includes(args.tag));
  },
});
```

But this requires reading the whole table first. If you want to just get the first result that matches, reading the whole table could be very inefficient. Instead you may want to use the JavaScript [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) syntax to loop through the table one document at a time:

```
export const firstPostWithTag = query({
  args: { tag: v.string() },
  handler: (ctx, args) => {
    for await (const post of db.query("posts")) {
      if (post.tags.includes(args.tag)) {
        return post;
      }
    }
  },
});
```

This works because Convex queries are [JavaScript iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).

Even with this optimization you are still just looping over the table to find the first post that matches and may hit your function limits. Using indexes is still the way to go. You can read a [detailed discussion of how to handle tags with indexes](https://stack.convex.dev/complex-filters-in-convex#optimize-with-indexes).

## Querying performance and limits[​](#querying-performance-and-limits "Direct link to Querying performance and limits")

Most of the example document queries above can lead to a *full table scan*. That is, for the document query to return the requested results, it might need to walk over every single document in the table.

Take this simple example:

```
const tasks = await ctx.db.query("tasks").take(5);
```

This document query will not scan more than 5 documents.

On the other hand, this document query:

```
const tasks = await ctx.db
  .query("tasks")
  .filter((q) => q.eq(q.field("isCompleted"), true))
  .first();
```

might need to walk over every single document in the `"tasks"` table just to find the first one with `isCompleted: true`.

If a table has more than a few thousand documents, you should use [indexes](/database/reading-data/indexes/.md) to improve your document query performance. Otherwise, you may run into our enforced limits, detailed in [Read/write limit errors](/functions/error-handling/.md#readwrite-limit-errors).

For information on other limits, see [Limits](/production/state/limits.md).

---

# Source: https://docs.convex.dev/auth/functions-auth.md

# Auth in Functions

*If you're using Convex Auth, see the [authorization doc](https://labs.convex.dev/auth/authz#use-authentication-state-in-backend-functions).*

Within a Convex [function](/functions.md), you can access information about the currently logged-in user by using the [`auth`](/api/interfaces/server.Auth.md) property of the [`QueryCtx`](/generated-api/server.md#queryctx), [`MutationCtx`](/generated-api/server.md#mutationctx), or [`ActionCtx`](/generated-api/server.md#actionctx) object:

convex/myFunctions.ts

TS

```
import { mutation } from "./_generated/server";

export const myMutation = mutation({
  args: {
    // ...
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (identity === null) {
      throw new Error("Unauthenticated call to mutation");
    }
    //...
  },
});
```

## User identity fields[​](#user-identity-fields "Direct link to User identity fields")

The [UserIdentity](/api/interfaces/server.UserIdentity.md) object returned by `getUserIdentity` is guaranteed to have `tokenIdentifier`, `subject` and `issuer` fields. Which other fields it will include depends on the identity provider used and the configuration of JWT tokens and [OpenID scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

`tokenIdentifier` is a combination of `subject` and `issuer` to ensure uniqueness even when multiple providers are used.

If you followed one of our integrations with Clerk or Auth0 at least the following fields will be present: `familyName`, `givenName`, `nickname`, `pictureUrl`, `updatedAt`, `email`, `emailVerified`. See their corresponding standard definition in the [OpenID docs](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

convex/myFunctions.ts

TS

```
import { mutation } from "./_generated/server";

export const myMutation = mutation({
  args: {
    // ...
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    const { tokenIdentifier, name, email } = identity!;
    //...
  },
});
```

### Clerk claims configuration[​](#clerk-claims-configuration "Direct link to Clerk claims configuration")

If you're using Clerk, the fields returned by `getUserIdentity` are determined by your JWT template's *Claims* config. If you've set custom claims, they will be returned by `getUserIdentity` as well.

### Custom JWT Auth[​](#custom-jwt-auth "Direct link to Custom JWT Auth")

If you're using [Custom JWT auth](/auth/advanced/custom-jwt.md) instead of OpenID standard fields you'll find each nested field available at dot-containing-string field names like `identity["properties.email"]`.

## HTTP Actions[​](#http-actions "Direct link to HTTP Actions")

You can also access the user identity from an HTTP action [`ctx.auth.getUserIdentity()`](/api/interfaces/server.Auth.md#getuseridentity), by calling your endpoint with an `Authorization` header including a JWT token:

myPage.ts

TS

```
const jwtToken = "...";

fetch("https://<deployment name>.convex.site/myAction", {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
  },
});
```

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/dashboard/deployments/functions.md

# Source: https://docs.convex.dev/functions.md

# Functions

Functions run on the backend and are written in JavaScript (or TypeScript). They are automatically available as APIs accessed through [client libraries](/client/react.md). Everything you do in the Convex backend starts from functions.

There are three types of functions:

* [Queries](/functions/query-functions.md) read data from your Convex database and are automatically cached and subscribable (realtime, reactive).
* [Mutations](/functions/mutation-functions.md) write data to the database and run as a transaction.
* [Actions](/functions/actions.md) can call OpenAI, Stripe, Twilio, or any other service or API you need to make your app work.

You can also build [HTTP actions](/functions/http-actions.md) when you want to call your functions from a webhook or a custom client.

Here's an overview of the three different types of Convex functions and what they can do:

|                            | Queries | Mutations | Actions |
| -------------------------- | ------- | --------- | ------- |
| Database access            | Yes     | Yes       | No      |
| Transactional              | Yes     | Yes       | No      |
| Cached                     | Yes     | No        | No      |
| Real-time Updates          | Yes     | No        | No      |
| External API Calls (fetch) | No      | No        | Yes     |

---

# Source: https://docs.convex.dev/generated-api.md

# Generated Code

Convex uses code generation to create code that is specific to your app's data model and API. Convex generates JavaScript files (`.js`) with TypeScript type definitions (`.d.ts`).

Code generation isn't required to use Convex, but using the generated code will give you more better autocompletion in your editor and more type safety if you're using TypeScript.

To generate the code, run:

```
npx convex dev
```

This creates a `convex/_generated` directory that contains:

* [`api.js` and `api.d.ts`](/generated-api/api.md)
* [`dataModel.d.ts`](/generated-api/data-model.md)
* [`server.js` and `server.d.ts`](/generated-api/server.md)

---

# Source: https://docs.convex.dev/deployment-api/get-canonical-urls.md

# Get canonical URLs

```
GET 
/get_canonical_urls
```

Get the canonical URLs for a deployment.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/get-log-stream.md

# Get log stream

```
GET 
/get_log_stream/:id
```

Get the config for a specific log stream by id.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/get-token-details.md

# Get token details

```
GET 
/token_details
```

Returns the team ID for team tokens. Especially useful after receiving a team token from an OAuth flow since most endpoints require team ID.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/agents/getting-started.md

# Getting Started with Agent

To install the agent component, you'll need an existing Convex project. New to Convex? Go through the [tutorial](https://docs.convex.dev/tutorial/).

Run `npm create convex` or follow any of the [quickstarts](https://docs.convex.dev/home) to set one up.

## Installation[​](#installation "Direct link to Installation")

Install the component package:

```
npm install @convex-dev/agent
```

Create a `convex.config.ts` file in your app's `convex/` folder and install the component by calling `use`:

```
// convex/convex.config.ts
import { defineApp } from "convex/server";
import agent from "@convex-dev/agent/convex.config";

const app = defineApp();
app.use(agent);

export default app;
```

Then run `npx convex dev` to generate code for the component. This needs to successfully run once before you start defining Agents.

## Defining your first Agent[​](#defining-your-first-agent "Direct link to Defining your first Agent")

```
import { components } from "./_generated/api";
import { Agent } from "@convex-dev/agent";
import { openai } from "@ai-sdk/openai";

const agent = new Agent(components.agent, {
  name: "My Agent",
  languageModel: openai.chat("gpt-4o-mini"),
  instructions: "You are a weather forecaster.",
  tools: { getWeather, getGeocoding },
  maxSteps: 3,
});
```

## Basic usage[​](#basic-usage "Direct link to Basic usage")

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

export const helloWorld = action({
  args: { city: v.string() },
  handler: async (ctx, { city }) => {
    const threadId = await createThread(ctx, components.agent);
    const prompt = `What is the weather in ${city}?`;
    const result = await agent.generateText(ctx, { threadId }, { prompt });
    return result.text;
  },
});
```

If you get type errors about `components.agent`, ensure you've run `npx convex dev` to generate code for the component.

That's it! Check out [Agent Usage](/agents/agent-usage.md) to see more details and options.

---

# Source: https://docs.convex.dev/dashboard/deployments/health.md

# Health

The [health page](https://dashboard.convex.dev/deployment/) is the landing page for your deployment. On this page, you can see some important information about the health of your deployment.

## Failure Rate[​](#failure-rate "Direct link to Failure Rate")

![Failure Rate Card](/assets/images/health_failure_rate-96b5cc94c00dc12c789240f58c7e4ab2.png)

The failure rate card shows the percentage of failed request by minute ove the last hour. The failure rate is calculated as the number of failed requests divided by the total number of requests.

## Cache Hit Rate[​](#cache-hit-rate "Direct link to Cache Hit Rate")

![Cache Hit Rate Card](/assets/images/health_cache_hit_rate-81841697e2ba3432148ac37633aaad6e.png)

The cache hit rate card shows the percentage of cache hits by minute over the last hour. The cache hit rate is calculated as the number of cache hits divided by the total number of requests.

Cache hit rate only applies to query functions.

## Scheduler Status[​](#scheduler-status "Direct link to Scheduler Status")

![Scheduler Status Card](/assets/images/scheduler_overdue-d79a8e0d353fdaee48ed6ec968444f98.png)

The scheduler status card shows the status of the [scheduler](/scheduling/scheduled-functions.md). If the scheduler falls behind due to too many scheduled tasks, the status will show as "Overdue", displaying the lag time in minutes.

You may click the button in the top right corner of the card to view a chart showing the scheduler status over the last hour.

![Scheduler Status Chart](/assets/images/scheduler_status-feaf42e465eb0ff0516cd033b658c662.png)

## Last Deployed[​](#last-deployed "Direct link to Last Deployed")

![Last Deployed Card](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAXgAAAA/CAYAAADqt9PGAAABXWlDQ1BJQ0MgUHJvZmlsZQAAKJF1kM1KQmEQhp9jhVRCQREtIlz1AxZiQm3tBzFciCX9LIrT0TRQ+zga1a4raBXRFUR34CairqAgqGhVtHEbhYtKTnO0UosGhvfhZWa++QYcLl2pdDOQyebNaHDSvbi07HYWcdFFK+MM6kZOBSKRsJTwrY1RukGz9XrEnrWjXV5Fgo6359jo0OvTyu7f+oZoiydyhuiHpN9QZh40r3BkO69s3hPuNmUp4QObk1U+sXmtyqeVmvnolPCVcKeR0uPCD8KetTo/WceZ9JbxtYO9vSuRjc2J9kr2ESaIm5joPFECLBBimpl/evyVnik2UexiskGSFHmZEBBHkSYhHCKLwSgeYR9eSb996983rHmqByaO5KnHmrd6B4V+6NiveQNF+c4sXJwp3dR/LquVmnPrY74qtxeg5dCyXhbAOQzlW8t6L1hW+Ria7uG89AkQvWUZ5yFI3gAAAFZlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA5KGAAcAAAASAAAARKACAAQAAAABAAABeKADAAQAAAABAAAAPwAAAABBU0NJSQAAAFNjcmVlbnNob3RntW2aAAAB1WlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNi4wLjAiPgogICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgICAgICAgICB4bWxuczpleGlmPSJodHRwOi8vbnMuYWRvYmUuY29tL2V4aWYvMS4wLyI+CiAgICAgICAgIDxleGlmOlBpeGVsWURpbWVuc2lvbj42MzwvZXhpZjpQaXhlbFlEaW1lbnNpb24+CiAgICAgICAgIDxleGlmOlBpeGVsWERpbWVuc2lvbj4zNzY8L2V4aWY6UGl4ZWxYRGltZW5zaW9uPgogICAgICAgICA8ZXhpZjpVc2VyQ29tbWVudD5TY3JlZW5zaG90PC9leGlmOlVzZXJDb21tZW50PgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4Kr7XQLQAAE25JREFUeAHtnQdcFNf2x48RTYy9d2ONsSBYMLFEFCsWrIAaxRZ9n2c0MVY0kjxb8kwkin81saBREwUVnxWNBUSN+p5d7NifsaAiYG+Z//0dM+OyLmF3Dexbcu7ns8zce8+de+c7M2fOPecumyUpIV4jSUJACAgBIZDpCLyW6c5ITkgICAEhIASYgCh4uRGEgBAQApmUgCj4THph5bSEgBAQAqLg5R4QAkJACGRSAqLgM+mFldMSAkJACIiCl3tACAgBIZBJCYiCz6QXVk5LCAgBISAKXu4BISAEhEAmJeDyKuf19OkzevDwIT158pQ0Tb4v9Sospa0QEAJCwJxAlixZKFs2F8rxxhvk4pLVvDrNvN0KHso9+c5dypM3DxXPmy/NjkRACAgBISAEbCeQmJRIyUnJlCd3LpuVvN0KHpY7lHs+Ue62XzFpIQSEgBCwkoCuYx/cv0+5c+W0stVzMbt98HDL6B3b1KMICwEhIASEgE0EoGuhc21Ndit48bnbilrkhYAQEAL2E7BH59qt4O0fprQUAkJACAiBjCAgCj4jKEsfQkAICAEHEBAF7wDo0qUQEAJCICMIiILPCMrShxAQAkLAAQREwTsAunQpBISAEMgIAqLgM4Ky9CEEhIAQcAABUfAOgC5dCgEhIAQygoAo+IygLH0IASEgBBxAQBS8A6BLl0JACAiBjCAgCj4jKEsfQkAICAEHEBAF7wDo0qUQEAKZj0BMzHbyatacsmZ7PcV23PgJDjvZdFfwR2Jj6dTp0w47wevX4wlj0D+3bt1Kt7EkJSVxP/HxN9Ktj7QOfF/9xzmc65UrV9MSlXohQA8ePKC9e/fSpUuX7KIRFxdHD9V/lv2rJyj2cRMm0BdBQfTsySOK2rKZt56NGlHM9u3kKCWf7gq+Zq061KFDp3S7/j8sXEhTgr9N9fiz58whjEH/FC1ekqq7utGIkaPo6VPb/ztbqh2piq1bo7if+QsW/JFYutYdOnyYxzD566/TtR85uPMTWLt2LdWrX48mTppIfv5+1LtPb4KBYEvq4tuFoOT/ygnKG4ocSt3TsxGjgDWP9MXnQVyOfbwEMjqlu4JP7xMKCfk/+mxsUJrd9Ondm2bOmE7Dhn5KOXLkoG+nTqNeffrSb7/9lmZbERACmY3AjRs3KHB0IP2w4AdavWo1xWyL4V9lmz1ndmY71XQ9Hyh3WOhQ5HrSXTW6kke5Xm9apsun59buH/z4swb17NkzCp0/n7bv2MnTxfr16tHfBvSnXLlycRewKGbMnEX7DxygYkWLUovmzcnbuxW99tpr9MmQT9kdAUEo684dO5KPTzuLQ2vW1Iu6dvXnOvTZ2dePwsLCybtlS+rR4wMuh/tm2fLl6oLtoLx58lJAQA9qUL8+1929e5c+Gvwx1apZkzw86tD3s+dQrpy5yN/fl9/eFjtVhXBPrVz5Lzpw8CDVdHenTp060juVK9O9e/do4KDBVKpkSZo08YWPbtKXX9FpZRFN+XoyFS5cmNtHRKzk8y9frhx9PHgwlS5dyugObqHQ+Qto95495FajBjVs0MCokx0hkBqBK1evqOehK7mrexLp9ddfp5bqWdi0aVNqTXjGu2r1Ktq9azflL5CfBvQf8JIsrPmlS5cqF+EVKqXu014BvdT9WprwQpkyZQqNGTOG8ubNa7SbFjJNPVO1qJGygDGjXrx4MR06fIjKlC6jnnNvqlq1qiFrvhOzPYYi10dSUnISubq6Up/efejNN980xLYrxbtl6xZ6/Pgx+fv509GjR6nMW2XU8+rJMvj3uxs2bqCdO3eqn8TLQU2aNKGGDRsa7a3ZgXKH9W6aYMWbWvN6Hdw3cONEeW7Wi9J963ALvtsHPejvAwdR3Ok4uqr8xiNHBZKvf1fjxL2aNmcLHQr28OEj5NOhI82ZO5frL//6qyF36eIlgrKzJmXNmtV4o+7avYeb3Llzh1q2ak1Dh42geOW334zpVmMvCg9fxvWPHj2iH3/8iebOnUet27Sj2COxNC80lFq09GbXjKV+4Quv3+B9mjBxEp8blDfyh48coZw5c9KZuDP09TdT+OZHe5wjZPbv28/K/eixYyyP2QbGN19ZW65u7nTm7FnuDg9EF3Xjwt20Ryn4ufPm0ZBPh1oaipQJgRQE3Gq4UZDZzPfQoUNUvlz5FHKmmXHjxrHF7+bmxgbQYGVswFjS04mTJwguGyjUVq1a8X3dM6An++hhrEBxb9r84gVy/fp1mqNcqGXKlOFDjBg5gjb+vJG8vLwob7689GH/D+ny5cv64VNsw8LCaNiwYVS8RHGWj4qK4hmJLoQX0chRI6lwocJUtUpVGj9+PC0NW8rPnC4THBxMISEhVLFCRX5hYUazfMVyvdqqLSxy3TrXGyDICkVunqD4M9qCp6SEeM2ez7kzpzUVTEjzo05Se7tSJYty9+4kaV9OmqiFTJtq1L/37rv49W7txvWr2oVzZ3m/efNmRn3wlG+0BaHzjHwNV1fNxcXFyJuPScHnY/y0eFEKmft3k7mdsqq5fHTgKJaLXLeW83eTEzXX6tW1YsWKcj7+2hWuz5Ytm/aff+/msl92btfUy0JTVj3nl4eHsYyyyDlf7733NMjv3/cfzh88sI/zdT08OD89ZBrLzw+dy/kVy8I5P2H8OM6r2YxWsGBB7eL5c5yPO31Sy549u+bv78f5VSsjWL5du7ba08cPuax9ex8uG/TRQM6b85B82vfsX5HR1s0/a+5u1bVf/3vR4n0Te+SgVsO1qnb5vxeM+lUrV2iVKpbTDqn7GszwjMREbzXq8Yy51aim7d/7by6bMX2a1rNHN6M+dN5szbdLRyNfu6abtn1blJE/fHC/dvvWDSNvel1OnzyuoV4v26ueSdfqVbTHD+/zs1DT3VXbtDHSqL94/qxWrWplbc73s7js1IljLH/+bJwhs2fXTq3KO5U06CX9uGltldK2KAsdZqltavKWZM3LoHNt1dUOddG8oX4pfPiwoRQVFc2B0jhl0R47fpxffDdu3qTKb79N6uXAFnLrtu3IS02hunTpTGXfeotlXuUPrAxYH7CkkaKjt/E2Kjqaorc931cvDrp27TpdvXqNsmfPxvXqhUK1a9XiffUyIvUSIFjaT5484TL9D44PtwxcOu7K4kFCW486dWjvvn1s1fgpa2fosOG0Zu06NZUNoNUq6IXUrVtXtoJ27d7N+RkzZ/IWf3Lnzk0HDxzkPI6P1K9PH8KvryP1VbGG1avX8L78EQLWEIDrYviI4RQ8JZiKFStmsQlkqlerTsWLFTfqGzdubOxjRxkjVLt2bdoWs43OnztP586d4/sc7hkkHx8f5W6dQTfVs12oUCFav349denchevwBy6isUFj2Z0Cl0119WyllipUqMAzhA0bNtDFixeVC3M/94VZcEJCAu97enoazUuVKkUVK1Y08ofVYoRq1aoZswdUeHh4sPvomHqecR7WJFstclvlrRnDH8k41EWTmJhItWp7kHebtrRiRQQHPKHQTdP2mGgapaZuuGECR4+htytXoaDPvzAVsWsfbhL44OrW9eD2165d4+258+fprLox8SlXvhz7zB88fGD0kTtPbmMfO3ny5GFljBvLNCUnJxPcOvhhctOEPF4GSepX0jFtbdasKW3evIV98pGRG9jnX65s2RTuJn082GKa5/H7mHEjI2EMejIfn14uWyFgicCFCxdowN8G0NChQ8lcYZvKw/2ZK/fzuJhejsUKcHfqCW7C9xu9T6HKdRkfH8/+/aIqbqankireVEsZR1DKWJZ5WsWnvFt769U0Qbk14DY6dvwYr+jp1bsXpbasee68uco92oIiIyPp4aOH1NxkhQriW2rmnGJs6ATj1VPC7YQUsQC9HPEB1FmbbHG78Gob9fxmZHKoBb9x489s/U7+51dsyePE27TzMc4fAdZ49fb/aOBAmjhhvHpTXyJPZcXDJ61cKkZABYoaH92KNQ6Qyg5eLIMGfcy1zZo25S1uzAuLL9KM6dOpaNEiXAZl75LVhYOaujKNjT3KvnIEgaHE4WcvU6Y05c+fP0VvsFAw04ClgPNA8AdrjuHnRJBU7+ODbt0IHCZO+pJv5u7dn8cfoPxxXARylynfoX5umC0ULfJ8fO7uz2cGO3/5xVietUsFwCQJAWsIQAn37deXevboSd27df/DJlXeqUJLlizhWa+u1OPOxKXwwS9ctJB8fX2VQTaKj4Vn8psp36Q4bof2HdRChmVs0CComSf3C+MEhg/87/hgbX1ArwCKiIigAQNSBnNx3NmzZ9PUb6caL6VTp04Z/VRWixgQnzquvAGw0pGg9PFC8WrixXnMDszPB3EuzAYwU7E2WQqcwgePhK1ysxiHshSQNSrTaSdDLHi4WxAINP1AMRb5XVFti4khKKlgdcGwllxPt28nUoOGjaiVd2taq9wY0dui1fTuFpUsUcJQ7mXLleWbbMxnYw33jt7edBuq1qYjmNuilTeVq1CJYtWU86svJ6lpYQsW69WzJ7/1O3bqTMuWLedAbh2Pd6mteuHghtITLHUEemd99z35tO9IeFn4dnkxzdTlsB2gVgPhS08IhC5atJiDx3D5DOjf3xBTPnM+F7y0YHWYHqtf3750/MQJXiGE88fMxc29Fn3xj/HcvlnTZvxi+eqfk+kf48bT+AkT+eVnHFx2hEAqBGCc9Puwn3IZerBShtsEn9Qs5prK1YiVa1OnTmVDBW6XyZMnp7CSYZRgpg3lDGUNJYznwzQh+AplvGTpEvX9mA5GFZRr4yaNlas0mstuJ95mF0zOXM9dqIag2oGxAwPq5MmTPOtH25DpIYYInqMePXoo9+dQWh+5nlfJfDLkE+VmzW7IuKvFCrDog78NZuUPAy5ILXWs61GXihd/4YYyGqSyAwseCda5nqDU9Y9exta7cjuZB2T1+nTb2uq01+VtCbKqwUNDpviEL12iPXpwT1Pr0zlQiXoEWLt378Zyx4/FcpAibMlPWp3atTV1c/EH+4cPHTACGHt2/6IpS5fbIFBqHpjQg6x6/8qq5j5+XLTwJVllKWtVq1TR1A3Efaklh5o+Dj3IqlwqmlLQXK+sci0goCefB/o1D7KiLGjsZ1rJkiV4fCVKFNc+GzP6pX6Vz53r27Zt81LdmNGBRnu1lI37S7gZb8ht2fSzpmIV3L5UqZLanNnf8b4EWSWYav4smObnh87hACmCpKYfBBlN5Uz3Tx4/qvm0ba1Vr/YOBygjloerZ9PdCLJeunBOa9O6JQczEfD8PGiM1qxpY21j5LoUx/x0yGD1rNfhgKjp8deu+ZfW1MtTQ4AUAdHAUcNTDXjuiInWPOrU5MAwgr+zZkzn89CfDSw6QEC1m7+v5ufbSVuzaqXWt0+AEWRFvxivv19nPhcco/+HfbTEhJspxmo6vj/a/zxorIYAKramcmq5JJejzrTcnn17gqxZoLCV8rM53UpIpLf+hGAnOoYL486du4bbwtJg4ANE0FMPiprLwFJAAFKfPprX25LH2xwBYNM1tbBsihQrQWpFD21UVgEseVgKWD9sTYIlX6RIYYuiH38yhGbO+o6W/vQj+fn5WpSB5V+oUEFmYEkAYy5QoIClKikTAn8qgdu3b/OzhufRUoLrB9YxnkdLKTAwkGeeo0Y9d+WYy+BZgy88tePr8viS4tWrVzmWZWqdox4zCLTXXZuQbdmqpXL3fpRi5gBZPMuQxTP/KglWOtwwCKTqvnls4cbB9lUT3EcFC+Sz6TCWr5BNh3h1YShSU2Vq6YimX46wVJ8vn20nbukYepk1ilL/IpbeJq2tJeWOVTJwS61bt54qqQh/x44vpqzmx1PLNc2LUuStGXOKBpIRAnYSMI83mR9Gd72alyOge1Ct/MJa97Vrnq8YM5dBHqtxrElwGSFwaykhaIwFBwP/PpCNvoiVEfzlq/q/f3HRtI2tz7JpW9P9DHe/mHaeyn6G+OBT6dupinEzVShf3ib/XFonGKviEPiCV4cO7dXKgvU8I0irjdQLAWclEB4eTmHhYfyNVny7NT0TZgfwzeOLV63btKYdO3bQYhUHS+3lk55jceSx/ydcNI4EIH0LASEgBJyBgD0uGrHgneHKyhiFgBAQAnYQEAVvBzRpIgSEgBBwBgKi4J3hKskYhYAQEAJ2EBAFbwc0aSIEhIAQcAYCouCd4SrJGIWAEBACdhAQBW8HNGkiBISAEHAGAqLgneEqyRiFgBAQAnYQEAVvBzRpIgSEgBBwBgJ2K3j9fzw4w0nKGIWAEBACzk7AHp1rt4LPls2FEpMSnZ2ZjF8ICAEh8D9PALoWOtfWZLeCz6H+81qy+lUiUfK2Ihd5ISAEhID1BKBjoWuhc21Ndv8vGnT09OkzesD/3P9pih/FsHUQIi8EhIAQEAIvE4BbBpY7lLuLy4ufR3xZ0nKJ7Ta/yXHQYW4Lv7hiIiK7QkAICAEh4CACdrtoHDRe6VYICAEhIASsJCAK3kpQIiYEhIAQcDYCouCd7YrJeIWAEBACVhIQBW8lKBETAkJACDgbAVHwznbFZLxCQAgIASsJiIK3EpSICQEhIAScjYAoeGe7YjJeISAEhICVBETBWwlKxISAEBACzkZAFLyzXTEZrxAQAkLASgKi4K0EJWJCQAgIAWcj8P/bl5hNUzqt1gAAAABJRU5ErkJggg==)

The last deployed card shows the time of the last time your functions were deployed.

## Integrations[​](#integrations "Direct link to Integrations")

info

Integrations are only available on Convex Professional.

![Last Deployed Card](/assets/images/health_integrations-d276b1aa3d1f8706b3a9d3104d4a7cb2.png)

The integrations card shows the status of your [Exception Reporting](/production/integrations/exception-reporting.md) and [Log Streams](/production/integrations/log-streams/.md) integrations, with quick links to view and configure your integrations.

## Insights[​](#insights "Direct link to Insights")

![Insights Card](/assets/images/insights-15ec1ad7e37db8c689c0abb030b1fa17.png)

The Health page also surfaces insights about your deployment, with suggestions on how to improve performance and reliability.

Each Insight contains a description of the issue, the impact on your deployment (via a chart and event log), and a link to learn more about the issue and how to resolve it.

Clicking on an Insight will open a breakdown of the issue, including a larger chart and a list of events that triggered the Insight.

![Insight Breakdown](/assets/images/insights_breakdown-9f58d14e058976c361b23a1cac9f8a37.png)

Available insights include:

* Functions that are [reading too many bytes](/production/state/limits.md#transactions) in a single transaction.
* Functions that are [reading too many documents](/production/state/limits.md#transactions) in a single transaction.
* Functions that are experiencing [write conflicts](/error.md#1).

---

# Source: https://docs.convex.dev/dashboard/deployments/history.md

# History

![History Dashboard Page](/assets/images/history-9d8ba9365e0f53531de2ddef5cd4cfd0.png)

info

The history page is only available on Convex Professional.

This [history page](https://dashboard.convex.dev/deployment/history) is an audit log of configuration-related events that have occurred in the selected deployment, such as function deployments, changes to indexes, and changes to environment variables.

You may also view an audit log of team-related events in the [team audit log](/dashboard/teams.md#audit-log).

---

# Source: https://docs.convex.dev/production/hosting.md

# Hosting and Deployment

The easiest way to publish your full-stack web app is to use a hosting provider like [Vercel](https://vercel.com) or [Netlify](https://netlify.com).

Both Vercel and Netlify integrate with Git to deploy code whenever a new revision is pushed. To host your app:

1. Commit all files and push to your favorite Git hosting provider such as [GitHub](https://github.com/), [GitLab](https://gitlab.com/) or [Bitbucket](https://bitbucket.org/).

2. Follow the appropriate guide below.

If you aren't using Netlify or Vercel, you can follow the Custom Hosting guide.

* [Vercel](/production/hosting/vercel.md)
* [Netlify](/production/hosting/netlify.md)
* [Custom Hosting](/production/hosting/custom.md)

---

# Source: https://docs.convex.dev/functions/http-actions.md

# HTTP Actions

HTTP actions allow you to build an HTTP API right in Convex!

convex/http.ts

TS

```
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";

const http = httpRouter();

http.route({
  path: "/",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    return new Response(`Hello from ${request.url}`);
  }),
});
export default http;
```

HTTP actions take in a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) following the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). HTTP actions can manipulate the request and response directly, and interact with data in Convex indirectly by running [queries](/functions/query-functions.md), [mutations](/functions/mutation-functions.md), and [actions](/functions/actions.md). HTTP actions might be used for receiving webhooks from external applications or defining a public HTTP API.

HTTP actions are exposed at `https://<your deployment name>.convex.site` (e.g. `https://happy-animal-123.convex.site`).

**Example:** [HTTP Actions](https://github.com/get-convex/convex-demos/tree/main/http)

## Defining HTTP actions[​](#defining-http-actions "Direct link to Defining HTTP actions")

HTTP action handlers are defined using the [`httpAction`](/generated-api/server.md#httpaction) constructor, similar to the `action` constructor for normal actions:

convex/myHttpActions.ts

TS

```
import { httpAction } from "./_generated/server";

export const doSomething = httpAction(async () => {
  // implementation will be here
  return new Response();
});
```

The first argument to the `handler` is an [`ActionCtx`](/api/interfaces/server.GenericActionCtx.md) object, which provides [`auth`](/api/interfaces/server.Auth.md), [`storage`](/api/interfaces/server.StorageActionWriter.md), and [`scheduler`](/api/interfaces/server.Scheduler.md), as well as `runQuery`, `runMutation`, `runAction`.

The second argument contains the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) data. HTTP actions do not support argument validation, as the parsing of arguments from the incoming Request is left entirely to you.

Here's an example:

convex/messages.ts

TS

```
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";

export const postMessage = httpAction(async (ctx, request) => {
  const { author, body } = await request.json();

  await ctx.runMutation(internal.messages.sendOne, {
    body: `Sent via HTTP action: ${body}`,
    author,
  });

  return new Response(null, {
    status: 200,
  });
});
```

To expose the HTTP Action, export an instance of [`HttpRouter`](/api/classes/server.HttpRouter.md) from the `convex/http.ts` file. To create the instance call the `httpRouter` function. On the `HttpRouter` you can expose routes using the `route` method:

convex/http.ts

TS

```
import { httpRouter } from "convex/server";
import { postMessage, getByAuthor, getByAuthorPathSuffix } from "./messages";

const http = httpRouter();

http.route({
  path: "/postMessage",
  method: "POST",
  handler: postMessage,
});

// Define additional routes
http.route({
  path: "/getMessagesByAuthor",
  method: "GET",
  handler: getByAuthor,
});

// Define a route using a path prefix
http.route({
  // Will match /getAuthorMessages/User+123 and /getAuthorMessages/User+234 etc.
  pathPrefix: "/getAuthorMessages/",
  method: "GET",
  handler: getByAuthorPathSuffix,
});

// Convex expects the router to be the default export of `convex/http.js`.
export default http;
```

You can now call this action via HTTP and interact with data stored in the Convex Database. HTTP actions are exposed on `https://<your deployment name>.convex.site`.

```
export DEPLOYMENT_NAME=... # example: "happy-animal-123"
curl -d '{ "author": "User 123", "body": "Hello world" }' \
    -H 'content-type: application/json' "https://$DEPLOYMENT_NAME.convex.site/postMessage"
```

Like other Convex functions, you can view your HTTP actions in the [Functions view](/dashboard/deployments/functions.md) of [your dashboard](https://dashboard.convex.dev/) and view logs produced by them in the [Logs view](/dashboard/deployments/logs.md).

## Limits[​](#limits "Direct link to Limits")

HTTP actions run in the same environment as queries and mutations so also do not have access to Node.js-specific JavaScript APIs. HTTP actions can call [actions](/functions/actions.md), which can run in Node.js.

Like [actions](/functions/actions.md#error-handling), HTTP actions may have side-effects and will not be automatically retried by Convex when errors occur. It is a responsibility of the caller to handle errors and retry the request if appropriate.

Request and response size is limited to 20MB.

HTTP actions support request and response body types of `.text()`, `.json()`, `.blob()`, and `.arrayBuffer()`.

Note that you don't need to define an HTTP action to call your queries, mutations and actions over HTTP if you control the caller, since you can use use the JavaScript [`ConvexHttpClient`](/api/classes/browser.ConvexHttpClient.md) or the [Python client](/client/python.md) to call these functions directly.

## Debugging[​](#debugging "Direct link to Debugging")

### Step 1: Check that your HTTP actions were deployed.[​](#step-1-check-that-your-http-actions-were-deployed "Direct link to Step 1: Check that your HTTP actions were deployed.")

Check the [functions page](https://dashboard.convex.dev/deployment/functions) in the dashboard and make sure there's an entry called `http`.

If not, double check that you've defined your HTTP actions with the `httpRouter` in a file called `http.js` or `http.ts` (the name of the file must match exactly), and that `npx convex dev` has no errors.

### Step 2: Check that you can access your endpoint using curl[​](#step-2-check-that-you-can-access-your-endpoint-using-curl "Direct link to Step 2: Check that you can access your endpoint using curl")

Get your URL from the dashboard under [Settings](https://dashboard.convex.dev/deployment/settings) > URL and Deploy Key.

Make sure this is the URL that ends in **`.convex.site`**, and not `.convex.cloud`. E.g. `https://happy-animal-123.convex.site`

Run a `curl` command to hit one of your defined endpoints, potentially defining a new endpoint specifically for testing

```
curl -X GET https://<deployment name>.convex.site/myEndpoint
```

Check the [logs page](https://dashboard.convex.dev/deployment/logs) in the dashboard to confirm that there's an entry for your HTTP action.

### Step 3: Check the request being made by your browser[​](#step-3-check-the-request-being-made-by-your-browser "Direct link to Step 3: Check the request being made by your browser")

If you've determined that your HTTP actions have been deployed and are accessible via curl, but there are still issues requesting them from your app, check the exact requests being made by your browser.

Open the *Network* tab in your browser's developer tools, and trigger your HTTP requests.

Check that this URL matches what you tested earlier with curl -- it ends in `.convex.site` and has the right deployment name.

You should be able to see these requests in the dashboard [logs page](https://dashboard.convex.dev/deployment/logs).

If you see "CORS error" or messages in the browser console like `Access to fetch at '...' from origin '...' has been blocked by CORS policy`, you likely need to configure CORS headers and potentially add a handler for the pre-flight `OPTIONS` request. See [this section](/functions/http-actions.md#cors) below.

## Common patterns[​](#common-patterns "Direct link to Common patterns")

### File Storage[​](#file-storage "Direct link to File Storage")

HTTP actions can be used to handle uploading and fetching stored files, see:

* [Uploading files via an HTTP action](/file-storage/upload-files.md#uploading-files-via-an-http-action)
* [Serving files from HTTP actions](/file-storage/serve-files.md#serving-files-from-http-actions)

### CORS[​](#cors "Direct link to CORS")

To make requests to HTTP actions from a website you need to add [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers to your HTTP actions.

There are existing resources for exactly which CORS headers are required based on the use case. [This site](https://httptoolkit.com/will-it-cors/) provides an interactive walkthrough for what CORS headers to add. Here's an example of adding CORS headers to a Convex HTTP action:

convex/http.ts

TS

```
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { api } from "./_generated/api";
import { Id } from "./_generated/dataModel";

const http = httpRouter();

http.route({
  path: "/sendImage",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    // Step 1: Store the file
    const blob = await request.blob();
    const storageId = await ctx.storage.store(blob);

    // Step 2: Save the storage ID to the database via a mutation
    const author = new URL(request.url).searchParams.get("author");
    if (author === null) {
      return new Response("Author is required", {
        status: 400,
      });
    }

    await ctx.runMutation(api.messages.sendImage, { storageId, author });

    // Step 3: Return a response with the correct CORS headers
    return new Response(null, {
      status: 200,
      // CORS headers
      headers: new Headers({
        // e.g. https://mywebsite.com, configured on your Convex dashboard
        "Access-Control-Allow-Origin": process.env.CLIENT_ORIGIN!,
        Vary: "origin",
      }),
    });
  }),
});
```

Here's an example of handling a pre-flight `OPTIONS` request:

convex/http.ts

TS

```
// Pre-flight request for /sendImage
http.route({
  path: "/sendImage",
  method: "OPTIONS",
  handler: httpAction(async (_, request) => {
    // Make sure the necessary headers are present
    // for this to be a valid pre-flight request
    const headers = request.headers;
    if (
      headers.get("Origin") !== null &&
      headers.get("Access-Control-Request-Method") !== null &&
      headers.get("Access-Control-Request-Headers") !== null
    ) {
      return new Response(null, {
        headers: new Headers({
          // e.g. https://mywebsite.com, configured on your Convex dashboard
          "Access-Control-Allow-Origin": process.env.CLIENT_ORIGIN!,
          "Access-Control-Allow-Methods": "POST",
          "Access-Control-Allow-Headers": "Content-Type, Digest",
          "Access-Control-Max-Age": "86400",
        }),
      });
    } else {
      return new Response();
    }
  }),
});
```

### Authentication[​](#authentication "Direct link to Authentication")

You can leverage Convex's built-in [authentication](/auth.md) integration and access a user identity from [`ctx.auth.getUserIdentity()`](/api/interfaces/server.Auth.md#getuseridentity). To do this call your endpoint with an `Authorization` header including a JWT token:

myPage.ts

TS

```
const jwtToken = "...";

fetch("https://<deployment name>.convex.site/myAction", {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
  },
});
```

---

# Source: https://docs.convex.dev/http-api.md

# Convex HTTP API

The public functions that define a deployment are exposed at public HTTP endpoints.

## Convex value format[​](#convex-value-format "Direct link to Convex value format")

Each of the HTTP APIs take a `format` query param that describes how documents are formatted. Currently the only supported value is `json`. See our [types page](/database/types.md#convex-values) for details. Note that for simplicity, the `json` format does not support all Convex data types as input, and uses overlapping representation for several data types in output. We plan to add a new format with support for all Convex data types in the future.

## API authentication[​](#api-authentication "Direct link to API authentication")

The Functions API can be optionally authenticated as a user via a bearer token in a `Authorization` header. The value is `Bearer <access_key>` where the key is a token from your auth provider. See the [under the hood](/auth/clerk.md#under-the-hood) portion of the Clerk docs for details on how this works with Clerk.

Streaming export and streaming import requests require deployment admin authorization via the HTTP header `Authorization`. The value is `Convex <access_key>` where the access key comes from "Deploy key" on the Convex dashboard and gives full read and write access to your Convex data.

## Functions API[​](#functions-api "Direct link to Functions API")

### POST `/api/query`, `/api/mutation`, `/api/action`[​](#post-apiquery-apimutation-apiaction "Direct link to post-apiquery-apimutation-apiaction")

These HTTP endpoints allow you to call Convex functions and get the result as a value.

You can find your backend deployment URL on the dashboard [Settings](/dashboard/deployments/deployment-settings.md) page, then the API URL will be `<CONVEX_URL>/api/query` etc., for example:

* Shell
* NodeJS
* Python

```
curl https://acoustic-panther-728.convex.cloud/api/query \
   -d '{"path": "messages:list", "args": {}, "format": "json"}' \
   -H "Content-Type: application/json"
```

```
const url = "https://acoustic-panther-728.convex.cloud/api/query";
const request = { path: "messages:list", args: {}, format: "json" };

const response = fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(request),
});
```

```
import requests

url = "https://acoustic-panther-728.convex.cloud/api/query"
headers = {"accept": "application/json"}
body = {"path": "messages:list", "args": {}, "format": "json"}

response = requests.post(url, headers=headers, json=body)
```

**JSON Body parameters**

| Name   | Type   | Required | Description                                                                                                     |
| ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| path   | string | y        | Path to the Convex function formatted as a string as defined [here](/functions/query-functions.md#query-names). |
| args   | object | y        | Named argument object to pass to the Convex function.                                                           |
| format | string | n        | Output format for values. Valid values: \[`json`]                                                               |

**Result JSON on success**

| Field Name | Type          | Description                                            |
| ---------- | ------------- | ------------------------------------------------------ |
| status     | string        | "success"                                              |
| value      | object        | Result of the Convex function in the requested format. |
| logLines   | list\[string] | Log lines printed out during the function execution.   |

**Result JSON on error**

| Field Name   | Type          | Description                                                                                                 |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------- |
| status       | string        | "error"                                                                                                     |
| errorMessage | string        | The error message.                                                                                          |
| errorData    | object        | Error data within an [application error](/functions/error-handling/application-errors.md) if it was thrown. |
| logLines     | list\[string] | Log lines printed out during the function execution.                                                        |

### POST `/api/run/{functionIdentifier}`[​](#post-apirunfunctionidentifier "Direct link to post-apirunfunctionidentifier")

This HTTP endpoint allows you to call arbitrary Convex function types with the path in the request URL and get the result as a value. The function identifier is formatted as a string as defined [here](/functions/query-functions.md#query-names) with a `/` replacing the `:`.

You can find your backend deployment URL on the dashboard [Settings](/dashboard/deployments/deployment-settings.md) page, then the API URL will be `<CONVEX_URL>/api/run/{functionIdentifier}` etc., for example:

* Shell
* NodeJS
* Python

```
curl https://acoustic-panther-728.convex.cloud/api/run/messages/list \
   -d '{"args": {}, "format": "json"}' \
   -H "Content-Type: application/json"
```

```
const url = "https://acoustic-panther-728.convex.cloud/api/run/messages/list";
const request = { args: {}, format: "json" };

const response = fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(request),
});
```

```
import requests

url = "https://acoustic-panther-728.convex.cloud/api/run/messages/list"
headers = {"accept": "application/json"}
body = {"args": {}, "format": "json"}

response = requests.get(url, headers=headers, body=json)
```

**JSON Body parameters**

| Name   | Type   | Required | Description                                                           |
| ------ | ------ | -------- | --------------------------------------------------------------------- |
| args   | object | y        | Named argument object to pass to the Convex function.                 |
| format | string | n        | Output format for values. Defaults to `json`. Valid values: \[`json`] |

**Result JSON on success**

| Field Name | Type          | Description                                            |
| ---------- | ------------- | ------------------------------------------------------ |
| status     | string        | "success"                                              |
| value      | object        | Result of the Convex function in the requested format. |
| logLines   | list\[string] | Log lines printed out during the function execution.   |

**Result JSON on error**

| Field Name   | Type          | Description                                                                                                 |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------- |
| status       | string        | "error"                                                                                                     |
| errorMessage | string        | The error message.                                                                                          |
| errorData    | object        | Error data within an [application error](/functions/error-handling/application-errors.md) if it was thrown. |
| logLines     | list\[string] | Log lines printed out during the function execution.                                                        |

---

# Source: https://docs.convex.dev/agents/human-agents.md

# Human Agents

The Agent component generally takes a prompt from a human or agent, and uses an LLM to generate a response.

However, there are cases where you want to generate the reply from a human acting as an agent, such as for customer support.

For full code, check out [chat/human.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/human.ts)

## Saving a user message without generating a reply[​](#saving-a-user-message-without-generating-a-reply "Direct link to Saving a user message without generating a reply")

You can save a message from a user without generating a reply by using the `saveMessage` function.

```
import { saveMessage } from "@convex-dev/agent";
import { components } from "./_generated/api";

await saveMessage(ctx, components.agent, {
  threadId,
  prompt: "The user message",
});
```

## Saving a message from a human as an agent[​](#saving-a-message-from-a-human-as-an-agent "Direct link to Saving a message from a human as an agent")

Similarly, you can save a message from a human as an agent in the same way, using the `message` field to specify the role and agent name:

```
import { saveMessage } from "@convex-dev/agent";
import { components } from "./_generated/api";

await saveMessage(ctx, components.agent, {
  threadId,
  agentName: "Alex",
  message: { role: "assistant", content: "The human reply" },
});
```

## Storing additional metadata about human agents[​](#storing-additional-metadata-about-human-agents "Direct link to Storing additional metadata about human agents")

You can store additional metadata about human agents by using the `saveMessage` function, and adding the `metadata` field.

```
await saveMessage(ctx, components.agent, {
  threadId,
  agentName: "Alex",
  message: { role: "assistant", content: "The human reply" },
  metadata: {
    provider: "human",
    providerMetadata: {
      human: {
        /* ... */
      },
    },
  },
});
```

## Deciding who responds next[​](#deciding-who-responds-next "Direct link to Deciding who responds next")

You can choose whether the LLM or human responds next in a few ways:

1. Explicitly store in the database whether the user or LLM is assigned to the thread.
2. Using a call to a cheap and fast LLM to decide if the user question requires a human response.
3. Using vector embeddings of the user question and message history to make the decision, based on a corpus of sample questions and what questions are better handled by humans.
4. Have the LLM generate an object response that includes a field indicating whether the user question requires a human response.
5. Providing a tool to the LLM to decide if the user question requires a human response. The human response is then the tool response message.

## Human responses as tool calls[​](#human-responses-as-tool-calls "Direct link to Human responses as tool calls")

You can have the LLM generate a tool call to a human agent to provide context to answer the user question by providing a tool that doesn't have a handler. Note: this generally happens when the LLM still intends to answer the question, but needs human intervention to do so, such as confirmation of a fact.

```
import { tool } from "ai";
import { z } from "zod/v3";

const askHuman = tool({
  description: "Ask a human a question",
  parameters: z.object({
    question: z.string().describe("The question to ask the human"),
  }),
});

export const ask = action({
  args: { question: v.string(), threadId: v.string() },
  handler: async (ctx, { question, threadId }) => {
    const result = await agent.generateText(
      ctx,
      { threadId },
      {
        prompt: question,
        tools: { askHuman },
      },
    );
    const supportRequests = result.toolCalls
      .filter((tc) => tc.toolName === "askHuman")
      .map(({ toolCallId, args: { question } }) => ({
        toolCallId,
        question,
      }));
    if (supportRequests.length > 0) {
      // Do something so the support agent knows they need to respond,
      // e.g. save a message to their inbox
      // await ctx.runMutation(internal.example.sendToSupport, {
      //   threadId,
      //   supportRequests,
      // });
    }
  },
});

export const humanResponseAsToolCall = internalAction({
  args: {
    humanName: v.string(),
    response: v.string(),
    toolCallId: v.string(),
    threadId: v.string(),
    messageId: v.string(),
  },
  handler: async (ctx, args) => {
    await agent.saveMessage(ctx, {
      threadId: args.threadId,
      message: {
        role: "tool",
        content: [
          {
            type: "tool-result",
            result: args.response,
            toolCallId: args.toolCallId,
            toolName: "askHuman",
          },
        ],
      },
      metadata: {
        provider: "human",
        providerMetadata: {
          human: { name: args.humanName },
        },
      },
    });
    // Continue generating a response from the LLM
    await agent.generateText(
      ctx,
      { threadId: args.threadId },
      {
        promptMessageId: args.messageId,
      },
    );
  },
});
```

---

# Source: https://docs.convex.dev/database/import-export.md

# Data Import & Export

If you're bootstrapping your app from existing data, Convex provides three ways to get the data in:

* Import from csv/json into a single table via the [CLI](/database/import-export/import.md#single-table-import).
* Restore from a backup via the [dashboard](/database/backup-restore.md) or [CLI](/database/import-export/import.md#restore-data-from-a-backup-zip-file).
* [Streaming import](/production/integrations/streaming-import-export.md) from any existing database via Airbyte destination connector.

You can export data from Convex in two ways.

* Download a backup as a zip from the [dashboard](/database/backup-restore.md).
* Set up [streaming export](/production/integrations/streaming-import-export.md) to any external database via Fivetran or Airbyte. Great for connecting to a custom BI setup (eg [Snowflake](https://www.snowflake.com/), [Databricks](https://www.databricks.com), or [BigQuery](https://cloud.google.com/bigquery)):

Data Import & Export is in beta

Data Import & Export<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

---

# Source: https://docs.convex.dev/database/import-export/import.md

# Data Import

You can import data into Convex from a local file using the command line.

```
npx convex import
```

Data import is in beta

Data import<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

Use `--help` to see all options. The most common flows are described here.

## Single table import[​](#single-table-import "Direct link to Single table import")

```
npx convex import --table <tableName> <path>
```

Import a CSV, JSON, or JSONLines file into a Convex table.

* `.csv` files must have a header, and each row's entries are interpreted either as a (floating point) number or a string.
* `.jsonl` files must have a JSON object per line.
* `.json` files must be an array of JSON objects.
  <!-- -->
  * JSON arrays have a size limit of 8MiB. To import more data, use CSV or JSONLines. You can convert json to jsonl with a command like `jq -c '.[]' data.json > data.jsonl`

Imports into a table with existing data will fail by default, but you can specify `--append` to append the imported rows to the table or `--replace` to replace existing data in the table with your import.

The default is to import into your dev deployment. Use `--prod` to import to your production deployment or `--preview-name` to import into a preview deployment.

## Restore data from a backup ZIP file[​](#restore-data-from-a-backup-zip-file "Direct link to Restore data from a backup ZIP file")

```
npx convex import <path>.zip
```

Import from a [Backup](/database/backup-restore.md) into a Convex deployment, where the backup is a ZIP file that has been downloaded on the dashboard. Documents will retain their `_id` and `_creationTime` fields so references between tables are maintained.

Imports where tables have existing data will fail by default, but you can specify `--replace` to replace existing data in tables mentioned in the ZIP file.

## Use cases[​](#use-cases "Direct link to Use cases")

1. Seed dev deployments with sample data.

```
# full backup - exported from prod or another dev deployment.
npx convex import seed_data.zip

# Import single table from jsonl/csv
npx convex import --table <table name> data.jsonl
```

2. Restore a deployment from a [backup](/database/backup-restore.md) programmatically. Download a backup, and restore from this backup if needed.

```
npx convex import --prod --replace backup.zip
```

3. Seed preview deployments with sample data, exported from prod, dev, or another preview deployment. Example for Vercel, seeding data from `seed_data.zip` committed in the root of the repo.

```
npx convex deploy --cmd 'npm run build' &&
if [ "$VERCEL_ENV" == "preview" ]; then
npx convex import --preview-name "$VERCEL_GIT_COMMIT_REF" seed_data.zip;
fi
```

4. Clear a table efficiently with an empty import.

```
touch empty_file.jsonl
npx convex import --replace --table <tableNameToClear> empty_file.jsonl
```

## Features[​](#features "Direct link to Features")

* Data import is the only way to create documents with pre-existing `_id` and `_creationTime` fields.

  <!-- -->

  * The `_id` field must match Convex's ID format.
  * If `_id` or `_creationTime` are not provided, new values are chosen during import.

* Data import creates and replaces tables atomically (except when using `--append`).

  <!-- -->

  * Queries and mutations will not view intermediate states where partial data is imported.
  * Indexes and schemas will work on the new data without needing time for re-backfilling or re-validating.

* Data import only affects tables that are mentioned in the import, either by `--table` or as entries in the ZIP file.

* While JSON and JSONLines can import arbitrary JSON values, ZIP imports can additionally import other Convex values: Int64, Bytes, etc. Types are preserved in the ZIP file through the `generated_schema.jsonl` file.

* Data import of ZIP files that include [file storage](/file-storage.md) import the files and preserve [`_storage`](/database/advanced/system-tables.md) documents, including their `_id`, `_creationTime`, and `contentType` fields.

## Warnings[​](#warnings "Direct link to Warnings")

* [Streaming Export](/production/integrations/streaming-import-export.md) (Fivetran or Airbyte) does not handle data imports or backup restorations, similar to table deletion and creation and some schema changes. We recommend resetting streaming export sync after a restore or a data import.

* Avoid changing the ZIP file between downloading it from Data Export and importing it with `npx convex import`. Some manual changes of the ZIP file may be possible, but remain undocumented. Please share your use case and check with the Convex team in [Discord](https://convex.dev/community).

* Data import is not always supported when importing into a deployment that was created before Convex version 1.7.

  <!-- -->

  * The import may work, especially when importing a ZIP backup from a deployment created around the same time as the target deployment. As a special case, you can always restore from backups from its own deployment.
  * Reach out in [Discord](https://convex.dev/community) if you encounter issues, as there may be a workaround.

Data import uses database bandwidth to write all documents, and file bandwidth if the export includes file storage. You can observe this bandwidth in the [usage dashboard](https://dashboard.convex.dev/team/settings/usage) as function name `_cli/import` and associated cost in the [limits docs](/production/state/limits.md#database).

---

# Source: https://docs.convex.dev/database/reading-data/indexes/indexes-and-query-perf.md

# Introduction to Indexes and Query Performance

How do I ensure my Convex [database queries](/database/reading-data/.md) are fast and efficient? When should I define an [index](/database/reading-data/indexes/.md)? What is an index?

This document explains how you should think about query performance in Convex by describing a simplified model of how queries and indexes function.

If you already have a strong understanding of database queries and indexes you can jump straight to the reference documentation instead:

* [Reading Data](/database/reading-data/.md)
* [Indexes](/database/reading-data/indexes/.md)

## A Library of Documents[​](#a-library-of-documents "Direct link to A Library of Documents")

You can imagine that Convex is a physical library storing documents as physical books. In this world, every time you add a document to Convex with [`db.insert("books", {...})`](/api/interfaces/server.GenericDatabaseWriter.md#insert) a librarian places the book on a shelf.

By default, Convex organizes your documents in the order they were inserted. You can imagine the librarian inserting documents left to right on a shelf.

If you run a query to find the first book like:

```
const firstBook = await ctx.db.query("books").first();
```

then the librarian could start at the left edge of the shelf and find the first book. This is an extremely fast query because the librarian only has to look at a single book to get the result.

Similarly, if we want to retrieve the last book that was inserted we could instead do:

```
const lastBook = await ctx.db.query("books").order("desc").first();
```

This is the same query but we've swapped the order to descending. In the library, this means that the librarian will start on the right edge of the shelf and scan right-to-left. The librarian still only needs to look at a single book to determine the result so this query is also extremely fast.

## Full Table Scans[​](#full-table-scans "Direct link to Full Table Scans")

Now imagine that someone shows up at the library and asks "what books do you have by Jane Austen?"

This could be expressed as:

```
const books = await ctx.db
  .query("books")
  .filter((q) => q.eq(q.field("author"), "Jane Austen"))
  .collect();
```

This query is saying "look through all of the books, left-to-right, and collect the ones where the `author` field is Jane Austen." To do this the librarian will need to look through the entire shelf and check the author of every book.

This query is a *full table scan* because it requires Convex to look at every document in the table. The performance of this query is based on the number of books in the library.

If your Convex table has a small number of documents, this is fine! Full table scans should still be fast if there are a few hundred documents, but if the table has many thousands of documents these queries will become slow.

In the library analogy, this kind of query is fine if the library has a single shelf. As the library expands into a bookcase with many shelves or many bookcases, this approach becomes infeasible.

## Card Catalogs[​](#card-catalogs "Direct link to Card Catalogs")

How can we more efficiently find books given an author?

One option is to re-sort the entire library by `author`. This will solve our immediate problem but now our original queries for `firstBook` and `lastBook` would become full table scans because we'd need to examine every book to see which was inserted first/last.

Another option is to duplicate the entire library. We could purchase 2 copies of every book and put them on 2 separate shelves: one shelf sorted by insertion time and another sorted by author. This would work, but it's expensive. We now need twice as much space for our library.

A better option is to build an *index* on `author`. In the library, we could use an old-school [card catalog](https://en.wikipedia.org/wiki/Library_catalog) to organize the books by author. The idea here is that the librarian will write an index card for each book that contains:

* The book's author
* The location of the book on the shelves

These index cards will be sorted by author and live in a separate organizer from the shelves that hold the books. The card catalog should stay small because it only has an index card per book (not the entire text of the book).

![Card Catalog](/assets/images/card-catalog-7ca883b19c630085876ee5d2f59b672a.jpg)

When a patron asks for "books by Jane Austen", the librarian can now:

1. Go to the card catalog and quickly find all of the cards for "Jane Austen".
2. For each card, go and find the book on the shelf.

This is quite fast because the librarian can quickly find the index cards for Jane Austen. It's still a little bit of work to find the book for each card but the number of index cards is small so this is quite fast.

## Indexes[​](#indexes "Direct link to Indexes")

Database indexes work based on the same concept! With Convex you can define an *index* with:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  books: defineTable({
    author: v.string(),
    title: v.string(),
    text: v.string(),
  }).index("by_author", ["author"]),
});
```

then Convex will create a new index called `by_author` on `author`. This means that your `books` table will now have an additional data structure that is sorted by the `author` field.

You can query this index with:

```
const austenBooks = await ctx.db
  .query("books")
  .withIndex("by_author", (q) => q.eq("author", "Jane Austen"))
  .collect();
```

This query instructs Convex to go to the `by_author` index and find all the entries where `doc.author === "Jane Austen"`. Because the index is sorted by `author`, this is a very efficient operation. This means that Convex can execute this query in the same manner that the librarian can:

1. Find the range of the index with entries for Jane Austen.
2. For each entry in that range, get the corresponding document.

The performance of this query is based on the number of documents where `doc.author === "Jane Austen"` which should be quite small. We've dramatically sped up the query!

## Backfilling and Maintaining Indexes[​](#backfilling-and-maintaining-indexes "Direct link to Backfilling and Maintaining Indexes")

One interesting detail to think about is the work needed to create this new structure. In the library, the librarian must go through every book on the shelf and put a new index card for each one in the card catalog sorted by author. Only after that can the librarian trust that the card catalog will give it correct results.

The same is true for Convex indexes! When you define a new index, the first time you run `npx convex deploy` Convex will need to loop through all of your documents and index each one. This is why the first deploy after the creation of a new index will be slightly slower than normal; Convex has to do a bit of work for each document in your table. If the table is particularly large, consider using a [staged index](/database/reading-data/indexes/.md#staged-indexes) to complete the backfill asynchronously from the deploy.

Similarly, even after an index is defined, Convex will have to do a bit of extra work to keep this index up to date as the data changes. Every time a document is inserted, updated, or deleted in an indexed table, Convex will also update its index entry. This is analogous to a librarian creating new index cards for new books as they add them to the library.

If you are defining a few indexes there is no need to worry about the maintenance cost. As you define more indexes, the cost to maintain them grows because every `insert` needs to update every index. This is why Convex has a limit of 32 indexes per table. In practice most applications define a handful of indexes per table to make their important queries efficient.

## Indexing Multiple Fields[​](#indexing-multiple-fields "Direct link to Indexing Multiple Fields")

Now imagine that a patron shows up at the library and would like to check out *Foundation* by Isaac Asimov. Given our index on `author`, we can write a query that uses the index to find all the books by Isaac Asimov and then examines the title of each book to see if it's *Foundation*.

```
const foundation = await ctx.db
  .query("books")
  .withIndex("by_author", (q) => q.eq("author", "Isaac Asimov"))
  .filter((q) => q.eq(q.field("title"), "Foundation"))
  .unique();
```

This query describes how a librarian might execute the query. The librarian will use the card catalog to find all of the index cards for Isaac Asimov's books. The cards themselves don't have the title of the book so the librarian will need to find every Asimov book on the shelves and look at its title to find the one named *Foundation*. Lastly, this query ends with [`.unique`](/api/interfaces/server.Query.md#unique) because we expect there to be at most one result.

This query demonstrates the difference between filtering using [`withIndex`](/api/interfaces/server.QueryInitializer.md#withindex) and [`filter`](/api/interfaces/server.Query.md#filter). `withIndex` only allows you to restrict your query based on the index. You can only do operations that the index can do efficiently like finding all documents with a given author.

`filter` on the other hand allows you to write arbitrary, complex expressions but it won't be run using the index. Instead, `filter` expressions will be evaluated on every document in the range.

Given all of this, we can conclude that **the performance of indexed queries is based on how many documents are in the index range**. In this case, the performance is based on the number of Isaac Asimov books because the librarian will need to look at each one to examine its title.

Unfortunately, Isaac Asimov wrote [a lot of books](https://en.wikipedia.org/wiki/Isaac_Asimov_bibliography_\(alphabetical\)). Realistically even with 500+ books, this will be fast enough on Convex with the existing index, but let's consider how we could improve it anyway.

One approach is to build a separate `by_title` index on `title`. This could let us swap the work we do in `.filter` and `.withIndex` to instead be:

```
const foundation = await ctx.db
  .query("books")
  .withIndex("by_title", (q) => q.eq("title", "Foundation"))
  .filter((q) => q.eq(q.field("author"), "Isaac Asimov"))
  .unique();
```

In this query, we're efficiently using the index to find all the books called *Foundation* and then filtering through to find the one by Isaac Asimov.

This is okay, but we're still at risk of having a slow query because too many books have a title of *Foundation*. An even better approach could be to build a *compound* index that indexes both `author` and `title`. Compound indexes are indexes on an ordered list of fields.

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  books: defineTable({
    author: v.string(),
    title: v.string(),
    text: v.string(),
  }).index("by_author_title", ["author", "title"]),
});
```

In this index, books are sorted first by the author and then within each author by title. This means that a librarian can use the index to jump to the Isaac Asimov section and quickly find *Foundation* within it.

Expressing this as a Convex query this looks like:

```
const foundation = await ctx.db
  .query("books")
  .withIndex("by_author_title", (q) =>
    q.eq("author", "Isaac Asimov").eq("title", "Foundation"),
  )
  .unique();
```

Here the index range expression tells Convex to only consider documents where the author is Isaac Asimov and the title is *Foundation*. This is only a single document so this query will be quite fast!

Because this index sorts by `author` and then by `title`, it also efficiently supports queries like "All books by Isaac Asimov that start with F." We could express this as:

```
const asimovBooksStartingWithF = await ctx.db
  .query("books")
  .withIndex("by_author_title", (q) =>
    q.eq("author", "Isaac Asimov").gte("title", "F").lt("title", "G"),
  )
  .collect();
```

This query uses the index to find books where `author === "Isaac Asimov" && "F" <= title < "G"`. Once again, the performance of this query is based on how many documents are in the index range. In this case, that's just the Asimov books that begin with "F" which is quite small.

Also note that this index also supports our original query for "books by Jane Austen." It's okay to only use the `author` field in an index range expression and not restrict by title at all.

Lastly, imagine that a library patron asks for the book *The Three-Body Problem* but they don't know the author's name. Our `by_author_title` index won't help us here because it's sorted first by `author`, and then by `title`. The title, *The Three-Body Problem*, could appear anywhere in the index!

The Convex TypeScript types in the `withIndex` make this clear because they require that you compare index fields in order. Because the index is defined on `["author", "title"]`, you must first compare the `author` with `.eq` before the `title`.

In this case, the best option is probably to create the separate `by_title` index to facilitate this query.

## Conclusions[​](#conclusions "Direct link to Conclusions")

Congrats! You now understand how queries and indexes work within Convex!

Here are the main points we've covered:

1. By default Convex queries are *full table scans*. This is appropriate for prototyping and querying small tables.
2. As your tables grow larger, you can improve your query performance by adding *indexes*. Indexes are separate data structures that order your documents for fast querying.
3. In Convex, queries use the *`withIndex`* method to express the portion of the query that uses the index. The performance of a query is based on how many documents are in the index range expression.
4. Convex also supports *compound indexes* that index multiple fields.

To learn more about queries and indexes, check out our reference documentation:

* [Reading Data](/database/reading-data/.md)
* [Indexes](/database/reading-data/indexes/.md)

---

# Source: https://docs.convex.dev/database/reading-data/indexes.md

# Indexes

Indexes are a data structure that allow you to speed up your [document queries](/database/reading-data/.md#querying-documents) by telling Convex how to organize your documents. Indexes also allow you to change the order of documents in query results.

For a more in-depth introduction to indexing see [Indexes and Query Performance](/database/reading-data/indexes/indexes-and-query-perf.md).

## Defining indexes[​](#defining-indexes "Direct link to Defining indexes")

Indexes are defined as part of your Convex [schema](/database/schemas.md). Each index consists of:

1. A name.
   <!-- -->
   * Must be unique per table.
2. An ordered list of fields to index.
   <!-- -->
   * To specify a field on a nested document, use a dot-separated path like `properties.name`.

To add an index onto a table, use the [`index`](/api/classes/server.TableDefinition.md#index) method on your table's schema:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

// Define a messages table with two indexes.
export default defineSchema({
  messages: defineTable({
    channel: v.id("channels"),
    body: v.string(),
    user: v.id("users"),
  })
    .index("by_channel", ["channel"])
    .index("by_channel_user", ["channel", "user"]),
});
```

The `by_channel` index is ordered by the `channel` field defined in the schema. For messages in the same channel, they are ordered by the [system-generated `_creationTime` field](/database/types.md#system-fields) which is added to all indexes automatically.

By contrast, the `by_channel_user` index orders messages in the same `channel` by the `user` who sent them, and only then by `_creationTime`.

Indexes are created in [`npx convex dev`](/cli.md#run-the-convex-dev-server) and [`npx convex deploy`](/cli.md#deploy-convex-functions-to-production).

You may notice that the first deploy that defines an index is a bit slower than normal. This is because Convex needs to *backfill* your index. The more data in your table, the longer it will take Convex to organize it in index order. If you need to add indexes to large tables, use a [staged index](#staged-indexes).

You can feel free to query an index in the same deploy that defines it. Convex will ensure that the index is backfilled before the new query and mutation functions are registered.

Be careful when removing indexes

In addition to adding new indexes, `npx convex deploy` will delete indexes that are no longer present in your schema. Make sure that your indexes are completely unused before removing them from your schema!

## Querying documents using indexes[​](#querying-documents-using-indexes "Direct link to Querying documents using indexes")

A query for "messages in `channel` created 1-2 minutes ago" over the `by_channel` index would look like:

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) =>
    q
      .eq("channel", channel)
      .gt("_creationTime", Date.now() - 2 * 60000)
      .lt("_creationTime", Date.now() - 60000),
  )
  .collect();
```

The [`.withIndex`](/api/interfaces/server.QueryInitializer.md#withindex) method defines which index to query and how Convex will use that index to select documents. The first argument is the name of the index and the second is an *index range expression*. An index range expression is a description of which documents Convex should consider when running the query.

The choice of index both affects how you write the index range expression and what order the results are returned in. For instance, by making both a `by_channel` and `by_channel_user` index, we can get results within a channel ordered by `_creationTime` or by `user`, respectively. If you were to use the `by_channel_user` index like this:

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel_user", (q) => q.eq("channel", channel))
  .collect();
```

The results would be all of the messages in a `channel` ordered by `user`, then by `_creationTime`. If you were to use `by_channel_user` like this:

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel_user", (q) =>
    q.eq("channel", channel).eq("user", user),
  )
  .collect();
```

The results would be the messages in the given `channel` sent by `user`, ordered by `_creationTime`.

An index range expression is always a chained list of:

1. 0 or more equality expressions defined with [`.eq`](/api/interfaces/server.IndexRangeBuilder.md#eq).
2. \[Optionally] A lower bound expression defined with [`.gt`](/api/interfaces/server.IndexRangeBuilder.md#gt) or [`.gte`](/api/interfaces/server.IndexRangeBuilder.md#gte).
3. \[Optionally] An upper bound expression defined with [`.lt`](/api/interfaces/server.IndexRangeBuilder.md#lt) or [`.lte`](/api/interfaces/server.IndexRangeBuilder.md#lte).

**You must step through fields in index order.**

Each equality expression must compare a different index field, starting from the beginning and in order. The upper and lower bounds must follow the equality expressions and compare the next field.

For example, it is not possible to write a query like:

```
// DOES NOT COMPILE!
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) =>
    q
      .gt("_creationTime", Date.now() - 2 * 60000)
      .lt("_creationTime", Date.now() - 60000),
  )
  .collect();
```

This query is invalid because the `by_channel` index is ordered by `(channel, _creationTime)` and this query range has a comparison on `_creationTime` without first restricting the range to a single `channel`. Because the index is sorted first by `channel` and then by `_creationTime`, it isn't a useful index for finding messages in all channels created 1-2 minutes ago. The TypeScript types within `withIndex` will guide you through this.

To better understand what queries can be run over which indexes, see [Introduction to Indexes and Query Performance](/database/reading-data/indexes/indexes-and-query-perf.md).

**The performance of your query is based on the specificity of the range.**

For example, if the query is

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) =>
    q
      .eq("channel", channel)
      .gt("_creationTime", Date.now() - 2 * 60000)
      .lt("_creationTime", Date.now() - 60000),
  )
  .collect();
```

then query's performance would be based on the number of messages in `channel` created 1-2 minutes ago.

If the index range is not specified, all documents in the index will be considered in the query.

Picking a good index range

For performance, define index ranges that are as specific as possible! If you are querying a large table and you're unable to add any equality conditions with `.eq`, you should consider defining a new index.

`.withIndex` is designed to only allow you to specify ranges that Convex can efficiently use your index to find. For all other filtering you can use the [`.filter`](/api/interfaces/server.Query.md#filter) method.

For example to query for "messages in `channel` **not** created by me" you could do:

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channel", channel))
  .filter((q) => q.neq(q.field("user"), myUserId))
  .collect();
```

In this case the performance of this query will be based on how many messages are in the channel. Convex will consider each message in the channel and only return the messages where the `user` field doesn't match `myUserId`.

## Sorting with indexes[​](#sorting-with-indexes "Direct link to Sorting with indexes")

Queries that use `withIndex` are ordered by the columns specified in the index.

The order of the columns in the index dictates the priority for sorting. The values of the columns listed first in the index are compared first. Subsequent columns are only compared as tie breakers only if all earlier columns match.

Since Convex automatically includes `_creationTime` as the last column in all indexes, `_creationTime` will always be the final tie breaker if all other columns in the index are equal.

For example, `by_channel_user` includes `channel`, `user`, and `_creationTime`. So queries on `messages` that use `.withIndex("by_channel_user")` will be sorted first by channel, then by user within each channel, and finally by the creation time.

Sorting with indexes allows you to satisfy use cases like displaying the top `N` scoring users, the most recent `N` transactions, or the most `N` liked messages.

For example, to get the top 10 highest scoring players in your game, you might define an index on the player's highest score:

```
export default defineSchema({
  players: defineTable({
    username: v.string(),
    highestScore: v.number(),
  }).index("by_highest_score", ["highestScore"]),
});
```

You can then efficiently find the top 10 highest scoring players using your index and [`take(10)`](/api/interfaces/server.Query.md#take):

```
const topScoringPlayers = await ctx.db
  .query("users")
  .withIndex("by_highest_score")
  .order("desc")
  .take(10);
```

In this example, the range expression is omitted because we're looking for the highest scoring players of all time. This particular query is reasonably efficient for large data sets only because we're using `take()`.

If you use an index without a range expression, you should always use one of the following in conjunction with `withIndex`:

1. [`.first()`](/api/interfaces/server.Query.md#first)
2. [`.unique()`](/api/interfaces/server.Query.md#unique)
3. [`.take(n)`](/api/interfaces/server.Query.md#take)
4. [`.paginate(ops)`](/database/pagination.md)

These APIs allow you to efficiently limit your query to a reasonable size without performing a full table scan.

Full Table Scans

When your query fetches documents from the database, it will scan the rows in the range you specify. If you are using `.collect()`, for instance, it will scan all of the rows in the range. So if you use `withIndex` without a range expression, you will be [scanning the whole table](https://docs.convex.dev/database/indexes/indexes-and-query-perf#full-table-scans), which can be slow when your table has thousands of rows. `.filter()` doesn't affect which documents are scanned. Using `.first()` or `.unique()` or `.take(n)` will only scan rows until it has enough documents.

You can include a range expression to satisfy more targeted queries. For example, to get the top scoring players in Canada, you might use both `take()` and a range expression:

```
// query the top 10 highest scoring players in Canada.
const topScoringPlayers = await ctx.db
  .query("users")
  .withIndex("by_country_highest_score", (q) => q.eq("country", "CA"))
  .order("desc")
  .take(10);
```

## Staged indexes[​](#staged-indexes "Direct link to Staged indexes")

By default, index creation happens synchronously when you deploy code. For large tables, the process of [backfilling the index](/database/reading-data/indexes/indexes-and-query-perf.md#backfilling-and-maintaining-indexes) for the existing table can be slow. Staged indexes are a way to create an index on a large table asynchronously without blocking deploy. This can be useful if you are working on multiple features at once.

To create a staged index, use the following syntax in your `schema.ts`.

```
export default defineSchema({
  messages: defineTable({
    channel: v.id("channels"),
  }).index("by_channel", { fields: ["channel"], staged: true }),
});
```

Staged indexes cannot be used until enabled

Staged indexes cannot be used in queries until you enable them. To enable them, they must first finish backfilling.

You can check the backfill progress via the [*Indexes* pane](/dashboard/deployments/data.md#view-the-indexes-of-a-table) on the dashboard data page. Once it is complete, you can enable the index and use it by removing the `staged` option.

```
export default defineSchema({
  messages: defineTable({
    channel: v.id("channels"),
  }).index("by_channel", { fields: ["channel"] }),
});
```

## Limits[​](#limits "Direct link to Limits")

Convex supports indexes containing up to 16 fields. You can define 32 indexes on each table. Indexes can't contain duplicate fields.

No reserved fields (starting with `_`) are allowed in indexes. The `_creationTime` field is automatically added to the end of every index to ensure a stable ordering. It should not be added explicitly in the index definition, and it's counted towards the index fields limit.

The `by_creation_time` index is created automatically (and is what is used in database queries that don't specify an index). The `by_id` index is reserved.

---

# Source: https://docs.convex.dev/production/integrations.md

# Integrations

Convex integrates with a variety of supported third party tools for log streaming and exception reporting.

* [Log Streams](/production/integrations/log-streams/.md) enable streaming of log events from your Convex deployment to supported destinations, such as Axiom, Datadog, or a custom webhook.
* [Exception Reporting](/production/integrations/exception-reporting.md) gives visibility into errors in your Convex function executions.

## Configuring an Integration[​](#configuring-an-integration "Direct link to Configuring an Integration")

To configure an integration, navigate to the [Deployment Settings](https://dashboard.convex.dev/deployment/settings) in the Dashboard, and the "Integrations" tab in the sidebar. This page provides a list of your configured integrations, their current health status, and other integrations available to be configured. To configure a integration, click on the card and follow the setup directions.

![Integrations Page](/assets/images/integrations_page-0f9edc52770c9caa6980330930e7517a.png)

## Deleting an Integration[​](#deleting-an-integration "Direct link to Deleting an Integration")

To remove an integration and stop further events from being piped out to the configured destination, select the menu icon in the upper-right corner of a configured panel and select "Delete integration". After confirming, the integration will stop running within a few seconds.

## Feedback[​](#feedback "Direct link to Feedback")

Please reach out with any questions, comments, or suggestions [on Discord](https://convex.dev/community).

## Integration Components[​](#integration-components "Direct link to Integration Components")

Beyond integrations for logs and exceptions, [Convex Components](/components.md) make it easier to work with third party services. See the full list of components on the [Convex Components Directory](https://convex.dev/components).

[Convex Component](https://www.convex.dev/components/cloudflare-r2)

### [Cloudflare R2](https://www.convex.dev/components/cloudflare-r2)

[Store and serve files in Cloudflare's R2 storage.](https://www.convex.dev/components/cloudflare-r2)

[Convex Component](https://www.convex.dev/components/prosemirror-sync)

### [Collaborative Text Editor](https://www.convex.dev/components/prosemirror-sync)

[Real-time collaborative text editing using BlockNote or Tiptap.](https://www.convex.dev/components/prosemirror-sync)

[Convex Component](https://www.convex.dev/components/push-notifications)

### [Expo Push Notifications](https://www.convex.dev/components/push-notifications)

[Send mobile push notifications using Expo.](https://www.convex.dev/components/push-notifications)

[Convex Component](https://www.convex.dev/components/twilio)

### [Twilio SMS](https://www.convex.dev/components/twilio)

[Send and receive SMS messages using Twilio's API.](https://www.convex.dev/components/twilio)

[Convex Component](https://www.convex.dev/components/launchdarkly)

### [LaunchDarkly Feature Flags](https://www.convex.dev/components/launchdarkly)

[Sync feature flags with backend, backed by LaunchDarkly.](https://www.convex.dev/components/launchdarkly)

[Convex Component](https://www.convex.dev/components/polar)

### [Polar](https://www.convex.dev/components/polar)

[Add subscriptions and billing with Polar.](https://www.convex.dev/components/polar)

---

# Source: https://docs.convex.dev/functions/internal-functions.md

# Internal Functions

Internal functions can only be called by other [functions](/functions.md) and cannot be called directly from a [Convex client](/client/react.md).

By default your Convex functions are public and accessible to clients. Public functions may be called by malicious users in ways that cause surprising results. Internal functions help you mitigate this risk. We recommend using internal functions any time you're writing logic that should not be called from a client.

While internal functions help mitigate risk by reducing the public surface area of your application, you can still validate internal invariants using [argument validation](/functions/validation.md) and/or [authentication](/auth/functions-auth.md).

## Use cases for internal functions[​](#use-cases-for-internal-functions "Direct link to Use cases for internal functions")

Leverage internal functions by:

* Calling them from [actions](/functions/actions.md#action-context) via `runQuery` and `runMutation`
* Calling them from [HTTP actions](/functions/http-actions.md) via `runQuery`, `runMutation`, and `runAction`
* [Scheduling](/scheduling/scheduled-functions.md) them from other functions to run in the future
* Scheduling them to run periodically from [cron jobs](/scheduling/cron-jobs.md)
* Running them using the [Dashboard](/dashboard/deployments/functions.md#running-functions)
* Running them from the [CLI](/cli.md#run-convex-functions)

## Defining internal functions[​](#defining-internal-functions "Direct link to Defining internal functions")

An internal function is defined using `internalQuery`, `internalMutation`, or `internalAction`. For example:

convex/plans.ts

TS

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

export const markPlanAsProfessional = internalMutation({
  args: { planId: v.id("plans") },
  handler: async (ctx, args) => {
    await ctx.db.patch("plans", args.planId, { planType: "professional" });
  },
});
```

If you need to pass complicated objects to internal functions you might prefer to not use argument validation. Note though that if you're using `internalQuery` or `internalMutation` it's a better idea to pass around document IDs instead of documents, to ensure the query or mutation is working with the up-to-date state of the database.

Internal function without argument validation

convex/plans.ts

TS

```
import { internalAction } from "./_generated/server";
import { Doc } from "./_generated/dataModel";

export const markPlanAsProfessional = internalAction({
  handler: async (actionCtx, args) => {
    // perform an action, perhaps calling a third-party API
  },
});
```

## Calling internal functions[​](#calling-internal-functions "Direct link to Calling internal functions")

Internal functions can be called from actions and scheduled from actions and mutation using the [`internal`](/generated-api/api.md#internal) object.

For example, consider this public `upgrade` action that calls the internal `plans.markPlanAsProfessional` mutation we defined above:

convex/changes.ts

TS

```
import { action } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";

export const upgrade = action({
  args: {
    planId: v.id("plans"),
  },
  handler: async (ctx, args) => {
    // Call out to payment provider (e.g. Stripe) to charge customer
    const response = await fetch("https://...");
    if (response.ok) {
      // Mark the plan as "professional" in the Convex DB
      await ctx.runMutation(internal.plans.markPlanAsProfessional, {
        planId: args.planId,
      });
    }
  },
});
```

In this example a user should not be able to directly call `internal.plans.markPlanAsProfessional` without going through the `upgrade` action — if they did, then they would get a free upgrade.

You can define public and internal functions in the same file.

---

# Source: https://docs.convex.dev/client/javascript.md

# Convex JavaScript Clients

Convex applications can be accessed from Node.js or any JavaScript runtime that implements [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) or [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket). The reactive [Convex Client](/api/classes/browser.ConvexClient.md) allows web applications and long-running Node.js servers to subscribe to updates on Convex queries, while the [Convex HTTP client](/api/classes/browser.ConvexHttpClient.md) is typically used for server-side rendering, migrations, administrative scripts, and serverless functions to run queries at a single point in time.

If you're using React, see the dedicated [`ConvexReactClient`](/api/classes/browser.ConvexClient.md) described in [React](/client/react.md).

## Convex Client[​](#convex-client "Direct link to Convex Client")

The [`ConvexClient`](/api/classes/browser.ConvexClient.md) provides subscriptions to queries in Node.js and any JavaScript environment that supports WebSockets.

<!-- -->

script.ts

TS

```
import { ConvexClient } from "convex/browser";
import { api } from "../convex/_generated/api";

const client = new ConvexClient(process.env.CONVEX_URL!);

// subscribe to query results
client.onUpdate(api.messages.listAll, {}, (messages) =>
  console.log(messages.map((msg) => msg.body)),
);

// execute a mutation
function hello() {
  client.mutation(api.messages.sendAnon, {
    body: `hello at ${new Date()}`,
  });
}
```

The Convex client is open source and available on [GitHub](https://github.com/get-convex/convex-js).

See the [Script Tag Quickstart](/quickstart/script-tag.md) to get started.

## HTTP client[​](#http-client "Direct link to HTTP client")

<!-- -->

The [`ConvexHttpClient`](/api/classes/browser.ConvexHttpClient.md) works in the browser, Node.js, and any JavaScript environment with `fetch`.

See the [Node.js Quickstart](/quickstart/nodejs.md).

script.ts

TS

```
import { ConvexHttpClient } from "convex/browser";
import { api } from "./convex/_generated/api";

const client = new ConvexHttpClient(process.env["CONVEX_URL"]);

// either this
const count = await client.query(api.counter.get);
// or this
client.query(api.counter.get).then((count) => console.log(count));
```

## Using Convex without generated `convex/_generated/api.js`[​](#using-convex-without-generated-convex_generatedapijs "Direct link to using-convex-without-generated-convex_generatedapijs")

If the source code for your Convex function isn't located in the same project or in the same monorepos you can use the untyped `api` object called `anyApi`.

<!-- -->

script.ts

TS

```
import { ConvexClient } from "convex/browser";
import { anyApi } from "convex/server";

const CONVEX_URL = "http://happy-otter-123";
const client = new ConvexClient(CONVEX_URL);
client.onUpdate(anyApi.messages.list, {}, (messages) =>
  console.log(messages.map((msg) => msg.body)),
);
setInterval(
  () =>
    client.mutation(anyApi.messages.send, {
      body: `hello at ${new Date()}`,
      author: "me",
    }),
  5000,
);
```

---

# Source: https://docs.convex.dev/production/integrations/log-streams/legacy-event-schema.md

# (Legacy) Event schema

info

Log streams configured before May 23, 2024 will use the legacy format documented here. We recommend updating your log stream to use the new format.

## Updating to the new format[​](#updating-to-the-new-format "Direct link to Updating to the new format")

You can update existing log streams to the new format in the dashboard under your [deployment's Settings](https://dashboard.convex.dev/deployment/settings) > Integrations.

You can either create an entirely new dataset to hold events using the new format, or can reuse your existing dataset to hold historical events in the legacy format as well as events in the new format going forward.

We recommend reading the documentation on both the legacy format and the [current format](/production/integrations/log-streams/.md#log-event-schema) for the full set of differences, but here are a few key differences:

* Many fields have been renamed to drop leading underscores and use `snake_case`

* Fields have been added, e.g.

  <!-- -->

  * `function.request_id`
  * `usage.vector_storage_read_bytes`
  * `log_level`

* Fields have been renamed or nested for clarity, e.g.

  <!-- -->

  * `reason` -> `error_message`
  * `_functionPath` -> `function.path`

## (Legacy) Event schema[​](#legacy-event-schema-1 "Direct link to (Legacy) Event schema")

Log events have a well-defined JSON schema that allow building complex, type-safe pipelines ingesting log events.

## System fields[​](#system-fields "Direct link to System fields")

System fields are reserved fields which are included on log events and prefixed by an underscore.

All log events include the following system fields:

* `_topic`: string that categorizes a log event by its internal source
* `_timestamp`: Unix epoch timestamp in milliseconds. This is as an integer.

## Log sources[​](#log-sources "Direct link to Log sources")

This section outlines the source and data model of all log events.

### `console` logs[​](#console-logs "Direct link to console-logs")

Convex function logs via the `console` API.

Schema:

* `_topic = "_console"`

* `_timestamp` = Unix epoch timestamp in milliseconds

* `_functionType = "query" | "mutation" | "action" | "httpAction"`

* `_functionPath` =

  <!-- -->

  * If this is an HTTP action, this is a string of the HTTP method and URL pathname i.e. `POST /my_endpoint`
  * Otherwise, this is a path to function within `convex/` directory including an optional module export identifier i.e. `myDir/myFile:myFunction`.

* `_functionCached = true | false`. This field is only set if `_functionType = "query"` and says if this log event came from a cached function execution.

* `message` = payload string of arguments to `console` API

Example query log event:

```
{
  "_topic": "_console",
  "_timestamp": 1695066350531,
  "_functionType": "query",
  "_functionPath": "myDir/myFile",
  "_functionCached": true,
  "message": "[LOG] 'My log message'"
}
```

### Function execution record logs[​](#function-execution-record-logs "Direct link to Function execution record logs")

Function executions which log a record of their execution and their result.

Schema:

* `_topic = "_execution_record"`
* `_timestamp` = Unix epoch timestamp in milliseconds
* `_functionType = "query" | "mutation" | "action" | "httpAction"`
* `_functionPath` = path to function within `convex/` directory including module export identifier
* `_functionCached = true | false`. This field is only set if `_functionType = "query"` and says if this log event came from a cached function execution.
* `status = "success" | "failure"`
* `reason` = error message from function. Only set if `status = "failure"`
* `executionTimeMs` = length of execution of this function in milliseconds
* `databaseReadBytes` = the database read bandwidth used by this function in bytes
* `databaseWriteBytes` = the database write bandwidth used by this function in bytes
* `storageReadBytes` = the file storage read bandwidth this function used in bytes
* `storageWriteBytes` = the file storage write bandwidth this function used in bytes

Example execution record log from an HTTP action:

```
{
  "_topic": "_execution_record",
  "_timestamp": 1695066350531,
  "_functionType": "httpAction",
  "_functionPath": "POST /sendImage",
  "status": "failure",
  "reason": "Unexpected Error: Some error message\n\n  at ....",
  "executionTimeMs": 73
}
```

### Audit trail logs[​](#audit-trail-logs "Direct link to Audit trail logs")

Audit logs of deployment events.

Schema:

* `_topic = "_audit_log"`
* `_timestamp` = Unix epoch timestamp in milliseconds
* `action = "create_environment_variable" | "update_environment_variable" | "delete_environment_variable" | "replace_environment_variable" | "push_config" | "build_indexes" | "change_deployment_state"`
* `actionMetadata` = object whose fields depends on the value of the `action` field.

Example `push_config` audit log:

```
{
  "_topic": "_audit_log",
  "_timestamp": 1695066350531,
  "action": "push_config",
  "actionMetadata": {
    "modules": {
      "added": ["ffmpeg.js", "fetch.js", "test.js"],
      "removed": ["removed.js"]
    }
  }
}
```

### Verification logs[​](#verification-logs "Direct link to Verification logs")

Internal logging events used to verify access to a log stream.

Schema

* `_topic = "_verification"`
* `_timestamp` = Unix epoch timestamp in milliseconds.
* `message = Convex connection test`

---

# Source: https://docs.convex.dev/production/state/limits.md

# Limits

We’d love for you to have *unlimited* joy building on Convex but engineering practicalities dictate a few limits. This page outlines current limits in the Convex ecosystem.

Many of these limits will become more permissive over time. Please get in touch if any are prohibitive for your application.

Limits are applied per team unless stated otherwise.

## Team[​](#team "Direct link to Team")

|             | Free/Starter | Professional             |
| ----------- | ------------ | ------------------------ |
| Developers  | 1-6          | 25$ per member per month |
| Deployments | 40           | 120                      |

## Database[​](#database "Direct link to Database")

|                   | Free/Starter                                                       | Professional                                        | Notes                                                                                     |
| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Storage           | 0.5 GiB included<br />(on Starter: $0.22/month per additional GiB) | 50 GiB included<br />$0.20/month per additional GiB | Includes database rows and indexes but not files or backups.                              |
| Bandwidth         | 1 GiB/month included<br />(on Starter: $0.22 per additional GiB)   | 50 GiB/month included<br />$0.20 per additional GiB | Document and index data transferred between Convex functions and the underlying database. |
| Tables            | 10,000                                                             | 10,000                                              | Per deployment.                                                                           |
| Indexes per table | 32                                                                 | 32                                                  |                                                                                           |
| Fields per index  | 16                                                                 | 16                                                  |                                                                                           |
| Index name length | 64 characters                                                      | 64 characters                                       |                                                                                           |

### Restrictions[​](#restrictions "Direct link to Restrictions")

* Table and index names must be valid identifiers and cannot start with an underscore.

## Documents[​](#documents "Direct link to Documents")

Applied per document and to any nested `Object` unless stated otherwise.

|                     |               | Notes                                                            |
| ------------------- | ------------- | ---------------------------------------------------------------- |
| Size                | 1 MiB         |                                                                  |
| Fields              | 1024          | The number of fields/keys                                        |
| Field name length   | 64 characters | Nested `Object` keys can have length up to 1024 characters.      |
| Field nesting depth | 16            | How many times objects and arrays can be nested, e.g. `[[[[]]]]` |
| Array elements      | 8192          |                                                                  |

### Restrictions[​](#restrictions-1 "Direct link to Restrictions")

* Field names must only contain non-control alphanumeric ASCII characters and underscores and must start with an alphabetic character or underscore.
* Documents cannot contain top-level fields that start with an underscore, other than the system-provided `_id` and `_creationTime` fields.
* Strings must be valid Unicode sequences with no unpaired surrogates.

## Functions[​](#functions "Direct link to Functions")

|                                                                  | Free/Starter                                                               | Professional                                               | Notes                                                                                                         |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Function calls                                                   | 1,000,000/month included<br />(on Starter: $2.20 per additional 1,000,000) | 25,000,000/month included<br />$2 per additional 1,000,000 | Explicit client calls, scheduled executions, subscription updates, and file accesses count as function calls. |
| Action execution                                                 | 20 GiB-hours included<br />(on Starter: $0.33/GiB-hour additional)         | 250 GiB-hours included<br />$0.30/GiB-hour additional      | Convex runtime: 64 MiB RAM.<br />Node.js runtime: 512 MiB RAM.                                                |
| Code size                                                        | 32 MiB                                                                     | 32 MiB                                                     | Per deployment.                                                                                               |
| Function argument size                                           | 16 MiB                                                                     | 16 MiB                                                     | Node actions only support arguments up to 5MiB.                                                               |
| Function return value size                                       | 16 MiB                                                                     | 16 MiB                                                     |                                                                                                               |
| HTTP action response size                                        | 20 MiB                                                                     | 20 MiB                                                     | There is no specific limit on request size                                                                    |
| Length of a console.log line                                     | 4 KiB                                                                      | 4 KiB                                                      |                                                                                                               |
| [Log streaming](/production/integrations/log-streams/.md) limits | 4096 logs, flushed every 10 seconds                                        | 4096 logs, flushed every 10 seconds                        | How many logs can be buffered when streaming                                                                  |

## Concurrent Function Executions[​](#concurrent-function-executions "Direct link to Concurrent Function Executions")

Number of functions you can run at a time for each function type.

|                        | Free/Starter | Professional\* |
| ---------------------- | ------------ | -------------- |
| Queries                | 16           | 256            |
| Mutations              | 16           | 256            |
| Convex runtime actions | 64           | 256            |
| Node actions           | 64           | 1000           |
| HTTP actions           | 16           | 128            |
| Scheduled jobs         | 10           | 300            |

\* Limits can be lifted for Professional plan customers on a case-by-case basis. Send us support message through the dashboard to discuss your needs. Usually this is only needed if your product has highly bursty traffic.

## Execution time and scheduling[​](#execution-time-and-scheduling "Direct link to Execution time and scheduling")

|                                              |            | Notes                                                                                                                   |
| -------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| Query/mutation execution time                | 1 second   | Limit applies only to user code and doesn’t include database operations.                                                |
| Action execution time                        | 10 minutes |                                                                                                                         |
| Scheduled functions                          | 1000       | The number of other functions a single mutation can schedule.                                                           |
| Total size of scheduled functions' arguments | 16 MiB     | Applies only to mutations.                                                                                              |
| Concurrent IO operations per function        | 1000       | The number of IO operations a single function can perform, e.g., a database operation, or a fetch request in an action. |
| Outstanding scheduled functions              | 1,000,000  |                                                                                                                         |

## Transactions[​](#transactions "Direct link to Transactions")

These limits apply to each `query` or `mutation` function.

|                            |        | Notes                                                     |
| -------------------------- | ------ | --------------------------------------------------------- |
| Data read                  | 16 MiB | Data not returned due to a `filter` counts as scanned     |
| Data written               | 16 MiB |                                                           |
| Documents scanned          | 32,000 | Documents not returned due to a `filter` count as scanned |
| Index ranges read          | 4,096  | The number of calls to `db.get` and `db.query`.           |
| Documents written          | 16,000 |                                                           |
| Function return value size | 16 MiB |                                                           |

## Environment Variables[​](#environment-variables "Direct link to Environment Variables")

Applied per-deployment.

|                     |               |
| ------------------- | ------------- |
| Number of variables | 1000          |
| Maximum name length | 40 characters |
| Maximum value size  | 8 KiB         |

## File Storage[​](#file-storage "Direct link to File Storage")

|           | Free/Starter                                                      | Professional                                         | Notes                                                                                                     |
| --------- | ----------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Storage   | 1 GiB included<br />(on Starter: $0.033/month per additional GiB) | 100 GiB included<br />$0.03/month per additional GiB | Includes user files and backups.                                                                          |
| Bandwidth | 1 GiB/month included<br />(on Starter: $0.33 per additional GiB)  | 50 GiB/month included<br />$0.30 per additional GiB  | Includes serving user files, accessing user files inside functions, and generating and restoring backups. |

## Full text search[​](#full-text-search "Direct link to Full text search")

|                          | Value |
| ------------------------ | ----- |
| Search indexes per table | 4     |
| Filters per search index | 16    |
| Terms per search query   | 16    |
| Filters per search query | 8     |
| Maximum term length      | 32 B  |
| Maximum result set       | 1024  |

## Vector search[​](#vector-search "Direct link to Vector search")

|                          | Value                    |
| ------------------------ | ------------------------ |
| Vector indexes per table | 4                        |
| Filters per vector index | 16                       |
| Terms per search query   | 16                       |
| Vectors to search by     | 1                        |
| Dimension fields         | 1 (value between 2-4096) |
| Filters per search query | 64                       |
| Maximum term length      | 32 B                     |
| Maximum result set       | 256 (defaults to 10)     |

If any of these limits don't work for you, [let us know](https://convex.dev/community)!

Please see our [plans and pricing page](https://www.convex.dev/pricing) for resource limits. After these limits are hit on a free plan, new mutations that attempt to commit more insertions or updates may fail. Paid plans have no hard resource limits - they can scale to billions of documents and TBs of storage.

---

# Source: https://docs.convex.dev/management-api/list-custom-domains.md

# List custom domains

```
GET 
/deployments/:deployment_name/custom_domains
```

Get all custom domains configured for a deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/list-deploy-keys.md

# List deploy keys

```
GET 
/deployments/:deployment_name/list_deploy_keys
```

Lists all deploy keys for the specified deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/list-deployment-classes.md

# list\_deployment\_classes

```
GET 
/teams/:team_id/list_deployment_classes
```

list\_deployment\_classes

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/list-deployment-regions.md

# list\_deployment\_regions

```
GET 
/teams/:team_id/list_deployment_regions
```

list\_deployment\_regions

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/list-deployments.md

# List deployments

```
GET 
/projects/:project_id/list_deployments
```

List deployments for a projects.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/list-environment-variables.md

# List environment variables

```
GET 
/list_environment_variables
```

Get all environment variables in a deployment. In the future this might not include "secret" environment variables.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/list-log-streams.md

# List log streams

```
GET 
/list_log_streams
```

List configs for all existing log streams in a deployment.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/management-api/list-projects.md

# List projects

```
GET 
/teams/:team_id/list_projects
```

List all projects for a team.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/cli/local-deployments.md

# Local Deployments for Development

Instead of syncing code to a Convex dev deployment hosted in the cloud, you can develop against a deployment running on your own computer. You can even use the Convex dashboard with local deployments!

## Background on deployments in Convex[​](#background-on-deployments-in-convex "Direct link to Background on deployments in Convex")

Each Convex deployment contains its own data, functions, scheduled functions, etc. A project has one production deployment, up to one cloud deployment for development per team member, and potentially many transient [preview deployments](/production/hosting/preview-deployments.md).

You can also develop with Convex using a deployment running on your own machine. Since the deployment is running locally, code sync is faster and means resources like functions calls and database bandwidth don't count against [the quotas for your Convex plan](https://www.convex.dev/pricing).

You can use local deployments with an existing Convex project, and view your deployment in the Convex dashboard under your project. You can also use local deployments without a Convex account and debug and inspect them with a locally running version of the Convex dashboard.

## Using local deployments[​](#using-local-deployments "Direct link to Using local deployments")

Local deployments are in beta

Local deployments<!-- --> <!-- -->are<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

While using local deployments, the local Convex backend runs as a subprocess of the `npx convex dev` command and exits when that command is stopped. This means a `convex dev` command must be running in order to run other commands like `npx convex run` against this local deployment or for your frontend to connect to this deployment.

State for local backends is stored the `~/.convex/` directory.

### Anonymous development[​](#anonymous-development "Direct link to Anonymous development")

You can use local deployments to develop with Convex without having to create an account. Whenever you want to create an account to deploy your app to production or to use more Convex features, you can use `npx convex login` to link your local deployments with your account.

### Local deployments for an existing project[​](#local-deployments-for-an-existing-project "Direct link to Local deployments for an existing project")

To use a local deployment for an existing project, run:

```
npx convex dev --local --once
```

You'll also always be given the option for a local deployment if you run `npx convex dev --configure`. Other flows may assume you want a cloud deployment in some situations, for example when connecting to a project for which you already have a cloud development deployment.

## Local deployments vs. production[​](#local-deployments-vs-production "Direct link to Local deployments vs. production")

Local deployments are not recommended for production use: they're development deployments, i.e. logs for function results and full stack traces for error responses are sent to connected clients.

For running a production application, you can use a production deployment hosted on the Convex cloud. Learn more about deploying to production [here](/production.md).

Alternatively, you can self-host a production deployment using the [open source convex-backend repo](https://github.com/get-convex/convex-backend).

### Disabling[​](#disabling "Direct link to Disabling")

To stop using local developments for a project, run the following:

```
npx convex disable-local-deployments
```

Remember your cloud dev deployment and each local dev deployment are completely separate, so contain different data. When switching between deployments you may wish to [export and re-import](/database/import-export/.md) the data to keep using it.

## Limitations[​](#limitations "Direct link to Limitations")

* **No Public URL** - Cloud deployments have public URL to receive incoming HTTP requests from services like Twilio, but local deployments listen for HTTP requests on your own computer. Similarly, you can't power websites with Convex WebSocket connections unless your users browsers know how to reach your computer. Set up a proxy like ngrok or use a cloud deployment for these uses cases.

* **Node actions require specific Node.js versions** - Running Node.js actions (actions defined in files with `"use node;"`) requires having the same version of Node.js as your project is [configured for](/production/project-configuration.md#configuring-the-nodejs-version). By default this is Node.js 20 today, though this may change in the future. To resolve this you can install and set up [nvm](https://github.com/nvm-sh/nvm) and then install the required Node.js version. You don't need to use this version for the rest of your project.

* **Node.js actions run directly on your computer** - Like a normal Node.js server, code running in Node.js actions has unrestricted filesystem access. Queries, mutations, and Convex runtime actions still run in isolated environments.

* Logs get cleared out every time a `npx convex dev` command is restarted.

* []()**Using the dashboard with Safari**: Safari [blocks requests to localhost](https://bugs.webkit.org/show_bug.cgi?id=171934), which prevents the dashboard from working with local deployments. We recommend using another browser if you’re using local deployments.

* []()**Using the dashboard with Brave**: Brave [blocks requests to localhost by default](https://brave.com/privacy-updates/27-localhost-permission/), which prevents the dashboard from working with local deployments. You can use the following workaround:

  * Go to `brave://flags/`
  * Enable the `#brave-localhost-access-permission` flag
  * Go back to the Convex dashboard
  * Click on **View Site Information** (![View Site Information icon](/screenshots/brave-site-information.png)) in the URL bar, then on **Site settings**
  * Change the setting for **Localhost access** to **Allow**

---

# Source: https://docs.convex.dev/production/integrations/log-streams.md

# Log Streams

Log streams enable streaming of events such as function executions and `console.log`s from your Convex deployment to supported destinations, such as Axiom, Datadog, or a custom webhook.

The most recent logs produced by your Convex deployment can be viewed in the Dashboard [Logs page](/dashboard/deployments/logs.md), the [Convex CLI](/cli.md), or in the browser console, providing a quick and easy way to view recent logs.

Log streaming to a third-party destination like Axiom or Datadog enables storing historical logs, more powerful querying and data visualization, and integrations with other tools (e.g. PagerDuty, Slack).

Log streams require a Convex Pro plan.

Log streams<!-- --> <!-- -->require<!-- --> a Convex Pro plan. [Learn more](https://convex.dev/pricing) about our plans or [upgrade](https://dashboard.convex.dev/team/settings/billing).

## Configuring log streams[​](#configuring-log-streams "Direct link to Configuring log streams")

We currently support the following log streams, with plans to support many more:

* [Axiom](https://www.axiom.co)
* [Datadog](https://www.datadoghq.com/)
* Webhook to a custom URL

See the instructions for [configuring an integration](/production/integrations/.md#configuring-an-integration). The specific information needed for each log stream is covered below.

### Axiom[​](#axiom "Direct link to Axiom")

Configuring an Axiom log stream requires specifying:

* The name of your [Axiom dataset](https://axiom.co/docs/reference/settings#dataset)
* An Axiom [API key](https://axiom.co/docs/reference/settings#api-token)
* An optional list of attributes and their values to be included in all log events send to Axiom. These will be sent via the `attributes` field in the [Ingest API](https://axiom.co/docs/send-data/ingest#ingest-api).

When configuring a Convex dataset in Axiom, a dashboard will automatically be created in Axiom. You can find it in the *Integrations* section of the *Dashboards* tab. To customize the layout of the dashboard, you can [fork it](https://axiom.co/docs/dashboards/create#fork-dashboards).

![A dashboard in Axiom](/assets/images/axiom_dashboard-a989f50d9d1fe5d65e33ecafb7facea1.png)

### Datadog[​](#datadog "Direct link to Datadog")

Configuring a Datadog log stream requires specifying:

* The [site location](https://docs.datadoghq.com/getting_started/site/) of your Datadog deployment
* A Datadog [API key](https://docs.datadoghq.com/account_management/api-app-keys/#add-an-api-key-or-client-token)
* A comma-separated list of tags that will be passed using the [`ddtags` field](https://docs.datadoghq.com/getting_started/tagging/) in all payloads sent to Datadog. This can be used to include any other metadata that can be useful for querying or categorizing your Convex logs ingested by your Datadog deployment.

### Webhook[​](#webhook "Direct link to Webhook")

A webhook log stream is the simplest and most generic stream, allowing piping logs via POST requests to any URL you configure. The only parameter required to set up this stream is the desired webhook URL.

A request to this webhook contains as its body a JSON array of events in the schema defined below.

## Securing webhook log streams[​](#securing-webhook-log-streams "Direct link to Securing webhook log streams")

Webhook log stream requests include a signature so you can verify that a request is legitimate. The request body is signed using HMAC-SHA256 and encoded as a lowercase hex string, and the resulting signature is included in the `x-webhook-signature` HTTP header. The HMAC secret is visible in the dashboard upon configuring the webhook.

To verify the authenticity of a request, sign and encode the request body using the HMAC secret and [compare the result in constant time](https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html) (for instance using [`SubtleCrypto.verify()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/verify) in JavaScript) with the signature included in the request header. Note that the signature is prefixed with `sha256=`.

For additional security, consider validating that the `timestamp` field of the log event body falls within an acceptable time range to prevent replay attacks.

```
import { Hono } from "hono";

const app = new Hono();

app.post("/webhook", async (c) => {
  const payload = await c.req.json();
  const log = payload[0];

  // If using JSONL, parse the first line:
  // const payload = await c.req.text();
  // const log = JSON.parse(payload.split("\n")[0]);

  // Validate that the timestamp of the first log is within 5 minutes
  if (log.timestamp < Date.now() - 5 * 60 * 1000) {
    c.status(403);
    return c.text("Request expired");
  }

  const signature = c.req.header("x-webhook-signature");
  if (!signature) {
    c.status(401);
    return c.text("Unauthorized");
  }

  const hmacSecret = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(process.env.WEBHOOK_SECRET!),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  const hashPayload = await c.req.arrayBuffer();

  // Use constant-time comparison to verify the payload
  const isValid = await crypto.subtle.verify(
    "HMAC",
    hmacSecret,
    Uint8Array.fromHex(signature.replace("sha256=", "")),
    hashPayload,
  );

  if (isValid) {
    return c.text("Success");
  }

  c.status(401);
  return c.text("Unauthorized");
});

export default app;
```

## Log event schema[​](#log-event-schema "Direct link to Log event schema")

info

Log streams configured before May 23, 2024 will use the legacy format documented on [this page](/production/integrations/log-streams/legacy-event-schema.md). We recommend updating your log stream to use the new format.

Log events have a well-defined JSON schema that allow building complex, type-safe pipelines ingesting log events.

All events will have the following three fields:

* `topic`: string, categorizes a log event, one of `["verification", "console", "function_execution", "audit_log", "concurrency_stats", "scheduler_stats", "current_storage_usage"]`
* `timestamp`: number, Unix epoch timestamp in milliseconds as an integer
* `convex`: An object containing metadata related to your Convex deployment, including `deployment_name`, `deployment_type`, `project_name`, and `project_slug`.

Note: In the Axiom integration, event-specific information will be available under the `data` field.

### `verification` events[​](#verification-events "Direct link to verification-events")

This is an event sent to confirm the log stream is working. Schema:

* `topic`: `"verification"`
* `timestamp`: Unix epoch timestamp in milliseconds
* `message`: string

### `console` events[​](#console-events "Direct link to console-events")

Convex function logs via the [`console` API](/functions/debugging.md).

Schema:

* `topic`: `"console"`
* `timestamp`: Unix epoch timestamp in milliseconds
* `function`: object, see [function fields](/production/integrations/log-streams/.md#function-fields)
* `log_level`: string, one of `["DEBUG", "INFO", "LOG", "WARN", "ERROR"]`
* `message`: string, the [`object-inspect`](https://www.npmjs.com/package/object-inspect) representation of the `console.log` payload
* `is_truncated`: boolean, whether this message was truncated to fit within our logging limits
* `system_code`: optional string, present for automatically added warnings when functions are approaching [limits](/production/state/limits.md#functions)

Example event for `console.log("Sent message!")` from a mutation:

```
{
    "topic": "console"
    "timestamp": 1715879172882,
    "function": {
      "path": "messages:send",
      "request_id": "d064ef901f7ec0b7",
      "type": "mutation"
    },
    "log_level": "LOG",
    "message": "'Sent message!'"
}
```

### `function_execution` events[​](#function_execution-events "Direct link to function_execution-events")

These events occur whenever a function is run.

Schema:

* `topic`: `"function_execution"`

* `timestamp`: Unix epoch timestamp in milliseconds

* `function`: object, see [function fields](/production/integrations/log-streams/.md#function-fields)

* `execution_time_ms`: number, the time in milliseconds this function took to

* `status`: string, one of `["success", "failure"]`

* `error_message`: string, present for functions with status `failure`, containing the error and any stack trace.

* `mutation_queue_length`: optional number (for mutations only), the length of the per-session mutation queue at the time the mutation was executed. This is useful for monitoring and debugging mutation queue backlogs in individual sessions.

* `mutation_retry_count`: number, the number of previous failed executions (for mutations only) run before a successful one. Only applicable to mutations and actions.

* `occ_info`: object, if the function call resulted in an OCC (write conflict between two functions), this field will be present and contain information relating to the OCC. [Learn more about write conflicts](https://docs.convex.dev/error/#1).

  <!-- -->

  * `table_name`: table the conflict occurred in
  * `document_id`: Id of the document that received conflicting writes
  * `write_source`: name of the function that conflicted writes against `table_name`
  * `retry_count`: the number of previously failed attempts before the current function execution

* `scheduler_info`: object, if set, indicates that the function was originally invoked by the [scheduler](/scheduling/scheduled-functions.md).
  <!-- -->
  * `job_id`: the job within the [`_scheduled_functions`](/scheduling/scheduled-functions.md#retrieving-scheduled-function-status) table

* `usage`:

  <!-- -->

  * `database_read_bytes`: number
  * `database_write_bytes`: number, this and `database_read_bytes` make up the database bandwidth used by the function
  * `database_read_documents`: number, the number of documents read by the function
  * `file_storage_read_bytes`: number
  * `file_storage_write_bytes`: number, this and `file_storage_read_bytes` make up the file bandwidth used by the function
  * `vector_storage_read_bytes`: number
  * `vector_storage_write_bytes`: number, this and `vector_storage_read_bytes` make up the vector bandwidth used by the function
  * `memory_used_mb`: number, for queries, mutations, and actions, the memory used in MiB. This combined with `execution_time_ms` makes up the compute.

Example event for a query:

```
{
  "data": {
    "execution_time_ms": 294,
    "function": {
      "cached": false,
      "path": "message:list",
      "request_id": "892104e63bd39d9a",
      "type": "query"
    },
    "status": "success",
    "timestamp": 1715973841548,
    "topic": "function_execution",
    "usage": {
      "database_read_bytes": 1077,
      "database_write_bytes": 0,
      "database_read_documents": 3,
      "file_storage_read_bytes": 0,
      "file_storage_write_bytes": 0,
      "vector_storage_read_bytes": 0,
      "vector_storage_write_bytes": 0
    }
  }
}
```

### Function fields[​](#function-fields "Direct link to Function fields")

The following fields are added under `function` for all `console` and `function_execution` events:

* `type`: string, one of `["query", "mutation", "action", "http_action"]`
* `path`: string, e.g. `"myDir/myFile:myFunction"`, or `"POST /my_endpoint"`
* `cached`: optional boolean, for queries this denotes whether this event came from a cached function execution
* `request_id`: string, the [request ID](/functions/debugging.md#finding-relevant-logs-by-request-id) of the function.

### `concurrency_stats` events[​](#concurrency_stats-events "Direct link to concurrency_stats-events")

These events are sent once a minute, reporting function concurrency statistics. Events are only sent if the stats have changed. Missing data points should be interpolated from the previous data event.

Schema:

Each event contains concurrency statistics for each function type (e.g. queries, mutations, actions). The records for each events have the following schema:

* `num_running`: The maximum number of concurrently running functions within the minute the metric was reported

* `num_queued`: The maximum number of queued functions within the minute the metric was reported. Functions may become temporarily queued when concurrency limits have been reached.

* `topic`: `"concurrency_stats"`

* `timestamp`: Unix epoch timestamp in milliseconds

* `query`: Concurrency stats for queries

* `mutation`: Concurrency stats for mutations

* `action`: Concurrency stats for actions

* `node_action`: Concurrency stats for node actions

* `http_action`: Concurrency stats for HTTP actions

### `scheduler_stats` events[​](#scheduler_stats-events "Direct link to scheduler_stats-events")

These events are periodically sent by the scheduler reporting statistics from the scheduled function executor.

Schema:

* `topic`: `"scheduler_stats"`
* `timestamp`: Unix epoch timestamp in milliseconds
* `lag_seconds`: The difference between `timestamp` and the scheduled run time of the oldest overdue scheduled job, in seconds.
* `num_running_jobs`: number, the number of scheduled jobs currently running

### `current_storage_usage` events[​](#current_storage_usage-events "Direct link to current_storage_usage-events")

These events are periodically sent with snapshots of the current storage usage across your deployment. They provide aggregated totals for all storage types.

These events are not currently sent for self-hosted deployments.

For calculating billing costs:

* Database Storage Bytes: `total_document_size_bytes + total_index_size_bytes`
* File Storage: `total_file_storage_bytes + total_backup_storage_bytes`
* Vector Storage: `total_vector_storage_bytes`

Schema:

* `topic`: `"current_storage_usage"`
* `timestamp`: Unix epoch timestamp in milliseconds
* `total_document_size_bytes`: number, total size in bytes of all documents stored in database tables
* `total_index_size_bytes`: number, total size in bytes of all database indexes
* `total_vector_storage_bytes`: number, total size in bytes of vector index storage
* `total_file_storage_bytes`: number, total size in bytes of file storage
* `total_backup_storage_bytes`: number, total size in bytes of snapshot/backup storage

Example event:

```
{
  "topic": "current_storage_usage",
  "timestamp": 1715973841548,
  "total_document_size_bytes": 104857600,
  "total_index_size_bytes": 10485760,
  "total_vector_storage_bytes": 5242880,
  "total_file_storage_bytes": 52428800,
  "total_backup_storage_bytes": 209715200
}
```

### `audit_log` events[​](#audit_log-events "Direct link to audit_log-events")

These events represent changes to your deployment, which also show up in the [History tab](https://dashboard.convex.dev/deployment/history) in the dashboard.

Schema:

* `topic`: `audit_log`
* `timestamp`: Unix epoch timestamp in milliseconds
* `audit_log_action`: string, e.g. `"create_environment_variable"`, `"push_config"`, `"change_deployment_state"`
* `audit_log_metadata`: string, stringified JSON holding metadata about the event. The exact format of this event may change.

Example `push_config` audit log:

```
{
  "topic": "audit_log",
  "timestamp": 1714421999886,
  "audit_log_action": "push_config",
  "audit_log_metadata": "{\"auth\":{\"added\":[],\"removed\":[]},\"crons\":{\"added\":[],\"deleted\":[],\"updated\":[]},..."
}
```

## Guarantees[​](#guarantees "Direct link to Guarantees")

Log events provide a best-effort delivery guarantee. Log streams are buffered in-memory and sent out in batches to your deployment's configured streams. This means that logs can be dropped if ingestion throughput is too high. Similarly, due to network retries, it is possible for a log event to be duplicated in a log stream.

That's it! Your logs are now configured to stream out. If there is a log streaming destination that you would like to see supported, [please let us know](/production/contact.md)!

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/dashboard/deployments/logs.md

# Logs

![Logs Dashboard Page](/assets/images/logs-ed208103a42edfb005e9089a8edad58e.png)

The [logs page](https://dashboard.convex.dev/deployment/logs) is a realtime view of all activity that occurs within your deployment.

The logs page provides a short history of recent function logs, and will display new logs as they are generated. To store a longer history of logs, you may configure a [log stream](/production/integrations/log-streams/.md).

Function activity includes:

* The time of function execution.
* The request ID of the function execution.
* The outcome of the function execution (success or failure).
* The name of the invoked function.
* The output of the function, including any log lines logged by the function (ex `console.log`) and exceptions.
* The duration of function execution, in milliseconds (does not include network latency).

In addition to function activity, [deployment events](/dashboard/deployments/history.md) describing configuration changes will be present here.

Clicking on log will open a view for all logs associated with the same Request ID as the selected log. This can be useful for debugging errors and understanding the context of a function execution.

![Request ID Logs](/assets/images/request_logs-dd39b47c480a5c133a89f7ef87420b4e.png)

You can use controls on the top of this page to filter logs by text, function name, execution status, and log severity.

### Filter logs[​](#filter-logs "Direct link to Filter logs")

Use the "Filter logs..." text box on the top of the page to filter log text.

You can use the “Functions” drop-down list to include or exclude functions from the results.

You can also find logs for a particular error using "Filter logs" and the [Convex request id](/functions/error-handling/.md#debugging-errors). For example if you see this `Error` in your browser console:

![Browser Error](/assets/images/console_error_requestid-27707a2afed9232acb56746eaa59248c.png)

You can view the logs for that function in your dashboard by pasting that Request ID into the 'Search logs...' search bar on the [Logs](/dashboard/deployments/logs.md) page of your Convex dashboard. Note that because this page is not a complete historical view of logs, you may not find logs for older requests.

Most error reporting services and log sinks should also be searchable by Request ID.

### Log Types[​](#log-types "Direct link to Log Types")

Logs can also be filtered by type. Types include function outcomes (success or failure) and severity levels (info, warn, debug, error).

All failed executions will include a reason, which will usually be a JavaScript exception.

---

# Source: https://docs.convex.dev/management-api.md

# Management API

info

The Convex Management API is openly available in Beta. Please contact <platforms@convex.dev> if your use case requires additional capabilities.

You can provision and manage Convex projects and deployments with the Management API.

## Authorization[​](#authorization "Direct link to Authorization")

The Management API uses a Bearer token Authorization header.

```
const token = "ey...0=";
const response = await fetch(
  "https://api.convex.dev/v1/teams/41/list_projects",
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);
console.log(await response.json());
```

[Team Access Tokens](/platform-apis.md#managing-your-own-projects) and [OAuth Application Tokens](/platform-apis/oauth-applications.md) can be used in Bearer tokens depending on whether you are using the Management API on behalf of your own team or on behalf of the team of a user of a Convex integration you've built.

## Required Parameters[​](#required-parameters "Direct link to Required Parameters")

Most Management APIs require a team ID or project ID.

When creating a Team Access Token the team ID will be available in the Convex dashboard.

OAuth applications may request the team (or project, if using project-scoped tokens) ID by calling the [Token Details](/management-api/get-token-details.md) endpoint.

When using a team token, projects will be assigned IDs upon creation. The [List Projects](/management-api/list-projects.md) endpoint may also be used to retrieve the ID for a project.

## Responses[​](#responses "Direct link to Responses")

All API responses are in JSON format.

## Endpoints[​](#endpoints "Direct link to Endpoints")

An OpenAPI spec for the Management API is available at <https://api.convex.dev/v1/openapi.json>.

---

# Source: https://docs.convex.dev/agents/messages.md

# Messages

The Agent component stores message and [thread](/agents/threads.md) history to enable conversations between humans and agents.

To see how humans can act as agents, see [Human Agents](/agents/human-agents.md).

## Retrieving messages[​](#retrieving-messages "Direct link to Retrieving messages")

For clients to show messages, you need to expose a query that returns the messages. For streaming, see [retrieving streamed deltas](/agents/streaming.md#retrieving-streamed-deltas) for a modified version of this query.

See [chat/basic.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/basic.ts) for the server-side code, and [chat/streaming.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/streaming.ts) for the streaming example.

```
import { paginationOptsValidator } from "convex/server";
import { v } from "convex/values";
import { listUIMessages } from "@convex-dev/agent";
import { components } from "./_generated/api";

export const listThreadMessages = query({
  args: { threadId: v.string(), paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    await authorizeThreadAccess(ctx, threadId);

    const paginated = await listUIMessages(ctx, components.agent, args);

    // Here you could filter out / modify the documents
    return paginated;
  },
});
```

Note: Above we used `listUIMessages`, which returns UIMessages, specifically the Agent extension that includes some extra fields like order, status, etc. UIMessages combine multiple MessageDocs into a single UIMessage when there are multiple tool calls followed by an assistant message, making it easy to build UIs that work with the various "parts" on the UIMessage.

If you want to get MessageDocs, you can use `listMessages` instead.

## Showing messages in React[​](#showing-messages-in-react "Direct link to Showing messages in React")

See [ChatStreaming.tsx](https://github.com/get-convex/agent/blob/main/example/ui/chat/ChatStreaming.tsx) for a streaming example, or [ChatBasic.tsx](https://github.com/get-convex/agent/blob/main/example/ui/chat/ChatBasic.tsx) for a non-streaming example.

### `useUIMessages` hook[​](#useuimessages-hook "Direct link to useuimessages-hook")

The crux is to use the `useUIMessages` hook. For streaming, pass in `stream: true` to the hook.

```
import { api } from "../convex/_generated/api";
import { useUIMessages } from "@convex-dev/agent/react";

function MyComponent({ threadId }: { threadId: string }) {
  const { results, status, loadMore } = useUIMessages(
    api.chat.streaming.listMessages,
    { threadId },
    { initialNumItems: 10 /* stream: true */ },
  );
  return (
    <div>
      {results.map((message) => (
        <div key={message.key}>{message.text}</div>
      ))}
    </div>
  );
}
```

Note: If you want to work with MessageDocs instead of UIMessages, you can use the older `useThreadMessages` hook instead. However, working with UIMessages enables richer streaming capabilities, such as status on whether the agent is actively reasoning.

### UIMessage type[​](#uimessage-type "Direct link to UIMessage type")

The Agent component extends the AI SDK's `UIMessage` type to provide convenient metadata for rendering messages.

The core UIMessage type from the AI SDK is:

* `parts` is an array of parts (e.g. "text", "file", "image", "toolCall", "toolResult")
* `content` is a string of the message content.
* `role` is the role of the message (e.g. "user", "assistant", "system").

The helper adds these additional fields:

* `key` is a unique identifier for the message.
* `order` is the order of the message in the thread.
* `stepOrder` is the step order of the message in the thread.
* `status` is the status of the message (or "streaming").
* `agentName` is the name of the agent that generated the message.
* `text` is the text of the message.
* `_creationTime` is the timestamp of the message. For streaming messages, it's currently assigned to the current time on the streaming client.

To reference these, ensure you're importing `UIMessage` from `@convex-dev/agent`.

#### `toUIMessages` helper[​](#touimessages-helper "Direct link to touimessages-helper")

`toUIMessages` is a helper function that transforms MessageDocs into AI SDK "UIMessage"s. This is a convenient data model for displaying messages.

If you are using `useThreadMessages` for instance, you can convert the messages to UIMessages like this:

```
import { toUIMessages, type UIMessage } from "@convex-dev/agent";

...
const { results } = useThreadMessages(...);
const uiMessages = toUIMessages(results);
```

### Optimistic updates for sending messages[​](#optimistic-updates-for-sending-messages "Direct link to Optimistic updates for sending messages")

The `optimisticallySendMessage` function is a helper function for sending a message, so you can optimistically show a message in the message list until the mutation has completed on the server.

Pass in the query that you're using to list messages, and it will insert the ephemeral message at the top of the list.

```
const sendMessage = useMutation(
  api.streaming.streamStoryAsynchronously,
).withOptimisticUpdate(
  optimisticallySendMessage(api.streaming.listThreadMessages),
);
```

If your arguments don't include `{ threadId, prompt }` then you can use it as a helper function in your optimistic update:

```
import { optimisticallySendMessage } from "@convex-dev/agent/react";

const sendMessage = useMutation(
  api.chatStreaming.streamStoryAsynchronously,
).withOptimisticUpdate(
  (store, args) => {
    optimisticallySendMessage(api.chatStreaming.listThreadMessages)(store, {
      threadId:
      prompt: /* change your args into the user prompt. */,
    })
  }
);
```

## Saving messages[​](#saving-messages "Direct link to Saving messages")

By default, the Agent will save messages to the database automatically when you provide them as a prompt, as well as all generated messages.

However, it is useful to save the prompt message ahead of time and use the `promptMessageId` to continue the conversation. See [Agent Usage](/agents/agent-usage.md) for more details.

You can save messages to the database manually using `saveMessage` or `saveMessages`, either on the Agent class or as a direct function call.

* You can pass a `prompt` or a full `message` (`ModelMessage` type)
* The `metadata` argument is optional and allows you to provide more details, such as `sources`, `reasoningDetails`, `usage`, `warnings`, `error`, etc.

```
const { messageId } = await saveMessage(ctx, components.agent, {
  threadId,
  userId,
  message: { role: "user", content: "The user message" },
});
```

Note: when calling `agent.generateText` with the raw prompt, embeddings are generated automatically for vector search (if you have a text embedding model configured). Similarly with `agent.saveMessage` when calling from an action. However, if you're saving messages in a mutation, where calling an LLM is not possible, it will generate them automatically if `generateText` receives a `promptMessageId` that lacks an embedding (and you have a text embedding model configured).

### Without the Agent class:[​](#without-the-agent-class "Direct link to Without the Agent class:")

Note: If you aren't using the Agent class with a text embedding model set, you need to pass an `embedding` if you want to save it at the same time.

```
import { saveMessage } from "@convex-dev/agent";

const { messageId } = await saveMessage(ctx, components.agent, {
  threadId,
  userId,
  message: { role: "assistant", content: result },
  metadata: [{ reasoning, usage, ... }] // See MessageWithMetadata type
  agentName: "my-agent",
  embedding: { vector: [0.1, 0.2, ...], model: "text-embedding-3-small" },
});
```

### Using the Agent class:[​](#using-the-agent-class "Direct link to Using the Agent class:")

```
const { messageId } = await agent.saveMessage(ctx, {
  threadId,
  userId,
  prompt,
  metadata,
});
```

```
const { messages } = await agent.saveMessages(ctx, {
  threadId, userId,
  messages: [{ role, content }],
  metadata: [{ reasoning, usage, ... }] // See MessageWithMetadata type
});
```

If you are saving the message in a mutation and you have a text embedding model set, pass `skipEmbeddings: true`. The embeddings for the message will be generated lazily if the message is used as a prompt. Or you can provide an embedding upfront if it's available, or later explicitly generate them using `agent.generateEmbeddings`.

## Configuring the storage of messages[​](#configuring-the-storage-of-messages "Direct link to Configuring the storage of messages")

Generally the defaults are fine, but if you want to pass in multiple messages and have them all saved (vs. just the last one), or avoid saving any input or output messages, you can pass in a `storageOptions` object, either to the Agent constructor or per-message.

The use-case for passing in multiple messages but not saving them is if you want to include some extra messages for context to the LLM, but only the last message is the user's actual request. e.g. `messages = [...messagesFromRag, messageFromUser]`. The default is to save the prompt and all output messages.

```
const result = await thread.generateText({ messages }, {
  storageOptions: {
    saveMessages: "all" | "none" | "promptAndOutput";
  },
});
```

## Message ordering[​](#message-ordering "Direct link to Message ordering")

Each message has `order` and `stepOrder` fields, which are incrementing integers specific to a thread.

When `saveMessage` or `generateText` is called, the message is added to the thread's next `order` with a `stepOrder` of 0.

As response message(s) are generated in response to that message, they are added at the same `order` with the next `stepOrder`.

To associate a response message with a previous message, you can pass in the `promptMessageId` to `generateText` and others.

Note: if the `promptMessageId` is not the latest message in the thread, the context for the message generation will not include any messages following the `promptMessageId`.

## Deleting messages[​](#deleting-messages "Direct link to Deleting messages")

You can delete messages by their `_id` (returned from `saveMessage` or `generateText`) or `order` / `stepOrder`.

By ID:

```
await agent.deleteMessage(ctx, { messageId });
// batch delete
await agent.deleteMessages(ctx, { messageIds });
```

By order (start is inclusive, end is exclusive):

```
// Delete all messages with the same order as a given message:
await agent.deleteMessageRange(ctx, {
  threadId,
  startOrder: message.order,
  endOrder: message.order + 1,
});
// Delete all messages with order 1 or 2.
await agent.deleteMessageRange(ctx, { threadId, startOrder: 1, endOrder: 3 });
// Delete all messages with order 1 and stepOrder 2-4
await agent.deleteMessageRange(ctx, {
  threadId,
  startOrder: 1,
  startStepOrder: 2,
  endOrder: 2,
  endStepOrder: 5,
});
```

## Other utilities:[​](#other-utilities "Direct link to Other utilities:")

```
import { ... } from "@convex-dev/agent";
```

* `serializeDataOrUrl` is a utility function that serializes an AI SDK `DataContent` or `URL` to a Convex-serializable format.
* `filterOutOrphanedToolMessages` is a utility function that filters out tool call messages that don't have a corresponding tool result message.
* `extractText` is a utility function that extracts text from a `ModelMessage`-like object.

### Validators and types[​](#validators-and-types "Direct link to Validators and types")

There are types to validate and provide types for various values

```
import { ... } from "@convex-dev/agent";
```

* `vMessage` is a validator for a `ModelMessage`-like object (with a `role` and `content` field e.g.).
* `MessageDoc` and `vMessageDoc` are the types for a message (which includes a `.message` field with the `vMessage` type).
* `Thread` is the type of a thread returned from `continueThread` or `createThread`.
* `ThreadDoc` and `vThreadDoc` are the types for thread metadata.
* `AgentComponent` is the type of the installed component (e.g. `components.agent`).
* `ToolCtx` is the `ctx` type for calls to `createTool` tools.

---

# Source: https://docs.convex.dev/api/modules.md

# convex

## Modules[​](#modules "Direct link to Modules")

* [browser](/api/modules/browser.md)
* [nextjs](/api/modules/nextjs.md)
* [react-auth0](/api/modules/react_auth0.md)
* [react-clerk](/api/modules/react_clerk.md)
* [react](/api/modules/react.md)
* [server](/api/modules/server.md)
* [values](/api/modules/values.md)

---

# Source: https://docs.convex.dev/production/multiple-repos.md

# Multiple Repositories

Your TypeScript clients can call Convex functions in a type-safe way outside of the repository where your Convex functions are defined. By following the steps below, you can generate a file similar to `convex/_generated/api.d.ts` that you can check in and use in a separate repository.

TypeScript API generation is in beta

TypeScript API generation<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

1. Install the Convex Helpers npm package

   Install the `convex-helpers` package, which contains a CLI command to generate an api file.

   ```
   npm install convex-helpers
   ```

2. Run a command to generate a TypeScript API file

   Running this command will call into your configured Convex deployment and generate an `api.ts` file based on it. You can see additional flags by passing `--help` to the command.

   ```
   npx convex-helpers ts-api-spec
   ```

## Example[​](#example "Direct link to Example")

Below are code snippets of what this workflow looks like in action. These snippets include three different files:

* `convex/messages.ts` - contains Convex function definitions
* `api.ts` - a generated file from running the command above
* `src/App.tsx` - frontend code in a separate repository where `api.ts` is checked in

convex/messages.ts

TS

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

export const send = mutation({
  args: { body: v.string(), author: v.string() },
  returns: v.null(),
  handler: async (ctx, { body, author }) => {
    const message = { body, author };
    await ctx.db.insert("messages", message);
  },
});
```

api.ts

TS

```
import { FunctionReference, anyApi } from "convex/server";

export const api: PublicApiType = anyApi as unknown as PublicApiType;

export type PublicApiType = {
  messages: {
    send: FunctionReference<
      "mutation",
      "public",
      { author: string; body: string },
      null
    >;
  };
};
```

src/App.tsx

TS

```
import { FormEvent, useState } from "react";
import { useMutation } from "convex/react";
// Note: This file is importing from the file we generated,`api`,
// and not from `../convex/_generated/api`
import { api } from "../api";

export default function App() {
  const [newMessageText, setNewMessageText] = useState("");
  const sendMessage = useMutation(api.messages.send);

  const [name] = useState(() => "User " + Math.floor(Math.random() * 10000));
  async function handleSendMessage(event: FormEvent) {
    event.preventDefault();
    await sendMessage({ body: newMessageText, author: name });
    setNewMessageText("");
  }
  return (
    <main>
      <h1>Send Messages</h1>
      <form onSubmit={handleSendMessage}>
        <input
          value={newMessageText}
          onChange={(event) => setNewMessageText(event.target.value)}
          placeholder="Write a message…"
        />
        <input type="submit" value="Send" disabled={!newMessageText} />
      </form>
    </main>
  );
}
```

## Limits[​](#limits "Direct link to Limits")

* Argument and return value validators are not required, but they will enrich the types of your TypeScript API. Where validators aren't defined, we default to `v.any()` as the validator.
* You cannot call internal functions from outside of your Convex deployment.

---

# Source: https://docs.convex.dev/functions/mutation-functions.md

# Mutations

Mutations insert, update and remove data from the database, check authentication or perform other business logic, and optionally return a response to the client application.

This is an example mutation, taking in named arguments, writing data to the database and returning a result:

convex/myFunctions.ts

TS

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

// Create a new task with the given text
export const createTask = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    const newTaskId = await ctx.db.insert("tasks", { text: args.text });
    return newTaskId;
  },
});
```

Read on to understand how to build mutations yourself.

## Mutation names[​](#mutation-names "Direct link to Mutation names")

Mutations follow the same naming rules as queries, see [Query names](/functions/query-functions.md#query-names).

Queries and mutations can be defined in the same file when using named exports.

## The `mutation` constructor[​](#the-mutation-constructor "Direct link to the-mutation-constructor")

To declare a mutation in Convex use the `mutation` constructor function. Pass it an object with a `handler` function, which performs the mutation:

convex/myFunctions.ts

TS

```
import { mutation } from "./_generated/server";

export const mutateSomething = mutation({
  args: {},
  handler: () => {
    // implementation will be here
  },
});
```

Unlike a query, a mutation can but does not have to return a value.

### Mutation arguments[​](#mutation-arguments "Direct link to Mutation arguments")

Just like queries, mutations accept named arguments, and the argument values are accessible as fields of the second parameter of the `handler` function:

convex/myFunctions.ts

TS

```
import { mutation } from "./_generated/server";

export const mutateSomething = mutation({
  handler: (_, args: { a: number; b: number }) => {
    // do something with `args.a` and `args.b`

    // optionally return a value
    return "success";
  },
});
```

Arguments and responses are automatically serialized and deserialized, and you can pass and return most value-like JavaScript data to and from your mutation.

To both declare the types of arguments and to validate them, add an `args` object using `v` validators:

convex/myFunctions.ts

TS

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

export const mutateSomething = mutation({
  args: { a: v.number(), b: v.number() },
  handler: (_, args) => {
    // do something with `args.a` and `args.b`
  },
});
```

See [argument validation](/functions/validation.md) for the full list of supported types and validators.

The first parameter to the handler function is reserved for the mutation context.

### Mutation responses[​](#mutation-responses "Direct link to Mutation responses")

Queries can return values of any supported [Convex type](/functions/validation.md) which will be automatically serialized and deserialized.

Mutations can also return `undefined`, which is not a valid Convex value. When a mutation returns `undefined` **it is translated to `null`** on the client.

### Mutation context[​](#mutation-context "Direct link to Mutation context")

The `mutation` constructor enables writing data to the database, and other Convex features by passing a [MutationCtx](/generated-api/server.md#mutationctx) object to the handler function as the first parameter:

convex/myFunctions.ts

TS

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

export const mutateSomething = mutation({
  args: { a: v.number(), b: v.number() },
  handler: (ctx, args) => {
    // Do something with `ctx`
  },
});
```

Which part of the mutation context is used depends on what your mutation needs to do:

* To read from and write to the database use the `db` field. Note that we make the handler function an `async` function so we can `await` the promise returned by `db.insert()`:

  convex/myFunctions.ts

  TS

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

  export const addItem = mutation({
    args: { text: v.string() },
    handler: async (ctx, args) => {
      await ctx.db.insert("tasks", { text: args.text });
    },
  });
  ```

  Read on about [Writing Data](/database/writing-data.md).

* To generate upload URLs for storing files use the `storage` field. Read on about [File Storage](/file-storage.md).

* To check user authentication use the `auth` field. Read on about [Authentication](/auth.md).

* To schedule functions to run in the future, use the `scheduler` field. Read on about [Scheduled Functions](/scheduling/scheduled-functions.md).

## Splitting up mutation code via helpers[​](#splitting-up-mutation-code-via-helpers "Direct link to Splitting up mutation code via helpers")

When you want to split up the code in your mutation or reuse logic across multiple Convex functions you can define and call helper

TypeScript

functions:

convex/myFunctions.ts

TS

```
import { v } from "convex/values";
import { mutation, MutationCtx } from "./_generated/server";

export const addItem = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("tasks", { text: args.text });
    await trackChange(ctx, "addItem");
  },
});

async function trackChange(ctx: MutationCtx, type: "addItem" | "removeItem") {
  await ctx.db.insert("changes", { type });
}
```

Mutations can call helpers that take a [QueryCtx](/generated-api/server.md#queryctx) as argument, since the mutation context can do everything query context can.

You can `export` helpers to use them across multiple files. They will not be callable from outside of your Convex functions.

See [Type annotating server side helpers](/understanding/best-practices/typescript.md#type-annotating-server-side-helpers) for more guidance on TypeScript types.

## Using NPM packages[​](#using-npm-packages "Direct link to Using NPM packages")

Mutations can import NPM packages installed in `node_modules`. Not all NPM packages are supported, see [Runtimes](/functions/runtimes.md#default-convex-runtime) for more details.

```
npm install @faker-js/faker
```

convex/myFunctions.ts

TS

```
import { faker } from "@faker-js/faker";
import { mutation } from "./_generated/server";

export const randomName = mutation({
  args: {},
  handler: async (ctx) => {
    faker.seed();
    await ctx.db.insert("tasks", { text: "Greet " + faker.person.fullName() });
  },
});
```

## Calling mutations from clients[​](#calling-mutations-from-clients "Direct link to Calling mutations from clients")

To call a mutation from [React](/client/react.md) use the [`useMutation`](/client/react.md#editing-data) hook along with the generated [`api`](/generated-api/api.md) object.

src/myApp.tsx

TS

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

export function MyApp() {
  const mutateSomething = useMutation(api.myFunctions.mutateSomething);
  const handleClick = () => {
    mutateSomething({ a: 1, b: 2 });
  };
  // pass `handleClick` to a button
  // ...
}
```

See the [React](/client/react.md) client documentation for all the ways queries can be called.

When mutations are called from the [React](/client/react.md) or [Rust](/client/rust.md) clients, they are executed one at a time in a single, ordered queue. You don't have to worry about mutations editing the database in a different order than they were triggered.

## Transactions[​](#transactions "Direct link to Transactions")

Mutations run **transactionally**. This means that:

1. All database reads inside the transaction get a consistent view of the data in the database. You don't have to worry about a concurrent update changing the data in the middle of the execution.
2. All database writes get committed together. If the mutation writes some data to the database, but later throws an error, no data is actually written to the database.

For this to work, similarly to queries, mutations must be deterministic, and cannot call third party APIs. To call third party APIs, use [actions](/functions/actions.md).

## Limits[​](#limits "Direct link to Limits")

Mutations have a limit to the amount of data they can read and write at once to guarantee good performance. Learn more in [Read/write limit errors](/functions/error-handling/.md#readwrite-limit-errors).

For information on other limits, see [Limits](/production/state/limits.md).

---

# Source: https://docs.convex.dev/production/hosting/netlify.md

# Using Convex with Netlify

Hosting your Convex app on Netlify allows you to automatically re-deploy both your backend and your frontend whenever you push your code.

## Deploying to Netlify[​](#deploying-to-netlify "Direct link to Deploying to Netlify")

This guide assumes you already have a working React app with Convex. If not follow the [Convex React Quickstart](/quickstart/react.md) first. Then:

1. Create a Netlify account

   If you haven't done so, create a [Netlify](https://netlify.com) account. This is free for small projects and should take less than a minute to set up.

2. Link your project on Netlify

   Create a Netlify project at <https://app.netlify.com/start> and link it to the source code repository for your project on GitHub or other Git platform.

   ![Netlify import project](/assets/images/netlify_import-a65616c6c06a44eacbd8dd6a58e9ec6b.png)

3. Override the Build command

   Override the *Build command* to be `npx convex deploy --cmd 'npm run build'`.

   If your project lives in a subdirectory of your repository you'll also need to change *Base directory* in Netlify accordingly.

   ![Netlify build settings](/assets/images/netlify_build_settings-3003b87fdb3b152f78ef5e794fb43c4c.png)

4. Set up the CONVEX\_DEPLOY\_KEY environment variable

   On your [Convex Dashboard](https://dashboard.convex.dev/) go to your project's *Settings* page. Click the *Generate* button to generate a **Production** deploy key. Then click the copy button to copy the key.

   In Netlify, click *Add environment variables* and *New variable*.

   Create an environment variable `CONVEX_DEPLOY_KEY` and paste in your deploy key.

   ![Netlify environment variable CONVEX\_DEPLOY\_KEY](/assets/images/netlify_prod_deploy_key-e92a5b4d1f17a3c7df3612f3574f3cdf.png)

5. Deploy your site

   Now click the *Deploy* button and your work here is done!

Netlify will automatically publish your site to a URL `https://<site-name>.netlify.app` listed at the top of the site overview page. Every time you push to your git repository, Netlify will automatically deploy your Convex functions and publish your site changes.

Using a Custom Domain?

If you're using a custom domain to serve your Convex functions, you'll need additional configuration. See [Custom Domains](/production/hosting/custom.md#hosting-with-a-custom-domain) for more information.

### How it works[​](#how-it-works "Direct link to How it works")

In Netlify, we overrode the *Build Command* to be `npx convex deploy --cmd 'npm run build'`.

`npx convex deploy` will read `CONVEX_DEPLOY_KEY` from the environment and use it to set the `CONVEX_URL` (or similarly named) environment variable to point to your **production** deployment.

Your frontend framework of choice invoked by `npm run build` will read the `CONVEX_URL` environment variable and point your deployed site (via `ConvexReactClient`) at your **production** deployment.

Finally, `npx convex deploy` will push your Convex functions to your production deployment.

Now, your production deployment has your newest functions and your app is configured to connect to it.

You can use `--cmd-url-env-var-name` to customize the variable name used by your frontend code if the `deploy` command cannot infer it, like

```
npx convex deploy --cmd-url-env-var-name CUSTOM_CONVEX_URL --cmd 'npm run build'
```

## Authentication[​](#authentication "Direct link to Authentication")

You will want to configure your [authentication](/auth.md) provider (Clerk, Auth0 or other) to accept your production `<site-name>.netlify.app` URL.

## Deploy Previews[​](#deploy-previews "Direct link to Deploy Previews")

Netlify's Deploy Previews allow you to preview changes to your app before they're merged in. In order to preview both changes to frontend code and Convex functions, you can set up [Convex preview deployments](/production/hosting/preview-deployments.md).

This will create a fresh Convex backend for each preview and leave your production and development deployments unaffected.

This assumes you have already followed the steps in [Deploying to Netlify](#deploying-to-netlify) above.

1. Set up the CONVEX\_DEPLOY\_KEY environment variable

   On your [Convex Dashboard](https://dashboard.convex.dev/) go to your project's *Settings* page. Click the *Generate Preview Deploy Key* button to generate a **Preview** deploy key. Then click the copy button to copy the key.

   In Netlify, click *Site configuration* > *Environment variables*. Edit your existing `CONVEX_DEPLOY_KEY` environment variable. Select *Different value for each deploy context* and paste the key under *Deploy Previews*.

   ![Netlify environment variable CONVEX\_DEPLOY\_KEY](/assets/images/netlify_preview_deploy_key-51d8c3210b827a6946d8f9997987616a.png)

2. (optional) Set up default environment variables

   If your app depends on certain Convex environment variables, you can set up [default environment variables](/production/environment-variables.md#project-environment-variable-defaults) for preview and development deployments in your project.

   ![Project Default Environment Variables](/assets/images/project_default_environment_variables-94be77c692d0a3c9564cb7f642b6cb64.png)

3. (optional) Run a function to set up initial data

   Deploy Previews run against fresh Convex backends, which do not share data with development or production Convex deployments. You can call a Convex function to set up data by adding `--preview-run 'functionName'` to the `npx convex deploy` command. This function will only be run for preview deployments, and will be ignored when deploying to production.

   Netlify > Site configuration > Build & deploy > Build settings > Build command

   ```
   npx convex deploy --cmd 'npm run build' --preview-run 'functionName'
   ```

4. Now test out creating a PR and generating a Deploy Preview!

   You can find the Convex deployment for your branch in the Convex dashboard.

   ![Preview Deployment in Deployment Picker](/assets/images/preview_deployment_deployment_picker-bc5b5e7cd3ac7e0e44ec7ed4c8b40c1c.png)

### How it works[​](#how-it-works-1 "Direct link to How it works")

For Deploy Previews, `npx convex deploy` will read `CONVEX_DEPLOY_KEY` from the environment, and use it to create a Convex deployment associated with the Git branch name for the Deploy Preview. It will set the `CONVEX_URL` (or similarly named) environment variable to point to the new Convex deployment.

Your frontend framework of choice invoked by `npm run build` will read the `CONVEX_URL` environment variable and point your deployed site (via `ConvexReactClient`) at the Convex preview deployment.

Finally, `npx convex deploy` will push your Convex functions to the preview deployment and run the `--preview-run` function (if provided). This deployment has separate functions, data, crons and all other configuration from any other deployments.

`npx convex deploy` will infer the Git branch name for Vercel, Netlify, GitHub, and GitLab environments, but the `--preview-create` option can be used to customize the name associated with the newly created deployment.

Production deployments will work exactly the same as before.

---

# Source: https://docs.convex.dev/api/modules/nextjs.md

# Source: https://docs.convex.dev/quickstart/nextjs.md

# Next.js Quickstart

Convex + Next.js

Convex is an all-in-one backend and database that integrates quickly and easily with Next.js.

Once you've gotten started, see how to set up [hosting](/production/hosting/.md), [server rendering](/client/nextjs/app-router/server-rendering.md), and [auth](https://docs.convex.dev/client/nextjs/).

To get setup quickly with Convex and Next.js run

**`npm create convex@latest`**

**``**

or follow the guide below.

***

Learn how to query data from Convex in a Next.js app using the App Router and

TypeScript

Alternatively see the [Pages Router](/client/nextjs/pages-router/quickstart.md) version of this quickstart.

1. Create a Next.js app

   Create a Next.js app using the `npx create-next-app` command.

   Choose the default option for every prompt (hit Enter).

   ```
   npx create-next-app@latest my-app
   ```

2. Install the Convex client and server library

   To get started, install the `convex` package.

   Navigate to your app and install `convex`.

   ```
   cd my-app && npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Use the [`import`](/database/import-export/import.md) command to add a `tasks` table with the sample data into your Convex database.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   In the `convex/` folder, add a new file `tasks.ts` with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name: `api.tasks.get`.

   convex/tasks.ts

   TS

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Create a client component for the Convex provider

   For `<ConvexProvider>` to work on the client, `ConvexReactClient` must be passed to it.

   In the `app/` folder, add a new file `ConvexClientProvider.tsx` with the following code. This creates a client component that wraps `<ConvexProvider>` and passes it the `<ConvexReactClient>`.

   app/ConvexClientProvider.tsx

   TS

   ```
   "use client";

   import { ConvexProvider, ConvexReactClient } from "convex/react";
   import { ReactNode } from "react";

   const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

   export function ConvexClientProvider({ children }: { children: ReactNode }) {
     return <ConvexProvider client={convex}>{children}</ConvexProvider>;
   }
   ```

8. Wire up the ConvexClientProvider

   In `app/layout.tsx`, wrap the children of the `body` element with the `<ConvexClientProvider>`.

   app/layout.tsx

   TS

   ```
   import type { Metadata } from "next";
   import { Geist, Geist_Mono } from "next/font/google";
   import "./globals.css";
   import { ConvexClientProvider } from "./ConvexClientProvider";

   const geistSans = Geist({
     variable: "--font-geist-sans",
     subsets: ["latin"],
   });

   const geistMono = Geist_Mono({
     variable: "--font-geist-mono",
     subsets: ["latin"],
   });

   export const metadata: Metadata = {
     title: "Create Next App",
     description: "Generated by create next app",
   };

   export default function RootLayout({
     children,
   }: Readonly<{
     children: React.ReactNode;
   }>) {
     return (
       <html lang="en">
         <body
           className={`${geistSans.variable} ${geistMono.variable} antialiased`}
         >
           <ConvexClientProvider>{children}</ConvexClientProvider>
         </body>
       </html>
     );
   }
   ```

9. Display the data in your app

   In `app/page.tsx`, use the `useQuery()` hook to fetch from your `api.tasks.get` API function.

   app/page.tsx

   TS

   ```
   "use client";

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

   export default function Home() {
     const tasks = useQuery(api.tasks.get);
     return (
       <main className="flex min-h-screen flex-col items-center justify-between p-24">
         {tasks?.map(({ _id, text }) => <div key={_id}>{text}</div>)}
       </main>
     );
   }
   ```

10. Start the app

    Run your Next.js development server, open <http://localhost:3000> in a browser, and see the list of tasks.

    ```
    npm run dev
    ```

See the complete [Next.js documentation](/client/nextjs/app-router/.md).

---

# Source: https://docs.convex.dev/client/javascript/node.md

# Node.js

Convex supports point-in-time queries (see [HTTP client](/api/classes/browser.ConvexHttpClient.md)) and query subscriptions (see [ConvexClient](/api/classes/browser.ConvexClient.md)) in Node.js.

If your JavaScript code uses import/export syntax, calling Convex functions works just like in a browser.

```
import { ConvexHttpClient, ConvexClient } from "convex/browser";
import { api } from "./convex/_generated/api.js";

// HTTP client
const httpClient = new ConvexHttpClient(CONVEX_URL_GOES_HERE);
httpClient.query(api.messages.list).then(console.log);

// Subscription client
const client = new ConvexClient(CONVEX_URL_GOES_HERE);
client.onUpdate(api.messages.list, {}, (messages) => console.log(messages));
```

## TypeScript[​](#typescript "Direct link to TypeScript")

Just like bundling for the browser, bundling TypeScript code for Node.js with webpack, esbuild, rollup, vite, and others usually allow you import from code that uses import/export syntax with no extra setup.

If you use TypeScript to *compile* your code (this is rare for web projects but more common with Node.js), add `"allowJs": true` to `tsconfig.json` compiler options so that TypeScript will compile the `api.js` file as well.

## TypeScript without a compile step[​](#typescript-without-a-compile-step "Direct link to TypeScript without a compile step")

If you want to run your TypeScript script directly without a compile step, installing [ts-node-esm](https://www.npmjs.com/package/ts-node) and running your script with ts-node-esm should work if you use `"type": "module"` in your `package.json`.

## JavaScript with CommonJS (`require()` syntax)[​](#javascript-with-commonjs-require-syntax "Direct link to javascript-with-commonjs-require-syntax")

If you don't use `"type": "module"` in the `package.json` of your project you'll need to use `require()` syntax and Node.js will not be able to import the `convex/_generated/api.js` file directly.

In the same directory as your `package.json`, create or edit [`convex.json`](/production/project-configuration.md#convexjson):

```
{
  "generateCommonJSApi": true
}
```

When the `convex dev` command generates files in `convex/_generated/` a new `api_cjs.cjs` file will be created which can be imported from CommonJS code.

```
const { ConvexHttpClient, ConvexClient } = require("convex/browser");
const { api } = require("./convex/_generated/api_cjs.cjs");
const httpClient = new ConvexHttpClient(CONVEX_URL_GOES_HERE);
```

## TypeScript with CommonJS without a compile step[​](#typescript-with-commonjs-without-a-compile-step "Direct link to TypeScript with CommonJS without a compile step")

Follow the steps above for CommonJS and use [`ts-node`](https://www.npmjs.com/package/ts-node) to run you code. Be sure your `tsconfig.json` is configured for CommonJS output.

## Using Convex with Node.js without codegen[​](#using-convex-with-nodejs-without-codegen "Direct link to Using Convex with Node.js without codegen")

You can always use the `anyApi` object or strings if you don't have the Convex functions and api file handy. An api reference like `api.folder.file.exportName` becomes `anyApi.folder.file.exportName` or `"folder/file:exportName"`.

---

# Source: https://docs.convex.dev/quickstart/nodejs.md

# Node.js Quickstart

Learn how to query data from Convex in a Node.js project.

For instructions for subscriptions instead of point-in-time queries and more project configurations (TypeScript, bundlers, CJS vs ESM) see [Node.js notes](/client/javascript/node.md).

1. Create a new npm project

   Create a new directory for your Node.js project.

   ```
   mkdir my-project && cd my-project && npm init -y && npm pkg set type="module"
   ```

2. Install the Convex client and server library

   Install the `convex` package which provides a convenient interface for working with Convex from JavaScript.

   Also install the `dotenv` library for loading `.env` files.

   ```
   npm install convex dotenv
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Connect the script to your backend

   In a new file `script.js`, create a `ConvexHttpClient` using the URL of your development environment.

   script.js

   ```
   import { ConvexHttpClient } from "convex/browser";
   import { api } from "./convex/_generated/api.js";
   import * as dotenv from "dotenv";
   dotenv.config({ path: ".env.local" });

   const client = new ConvexHttpClient(process.env["CONVEX_URL"]);

   client.query(api.tasks.get).then(console.log);
   ```

8. Run the script

   Run the script from the same directory and see the list of tasks logged to the terminal.

   ```
   node script.js
   ```

See the complete [Node.js documentation](/client/javascript/node.md).

---

# Source: https://docs.convex.dev/client/vue/nuxt.md

# Source: https://docs.convex.dev/quickstart/nuxt.md

# Nuxt Quickstart

Learn how to query data from Convex in a Nuxt app.

This quickstart guide uses a [community-maintained](/client/vue/nuxt.md) Nuxt client for Convex.

1. Create a Nuxt application

   Create a Nuxt application using the `npm create nuxt@latest my-nuxt-app` command.

   Convex will work with any of the official modules but to follow this quickstart skip installing them for now.

   <br />

   ```
   npm create nuxt@latest my-nuxt-app
   ```

2. Install the Convex library

   To get started, install the `convex` package and the `convex-nuxt` module to your Nuxt application.

   ```
   cd my-nuxt-app && npm install convex && npx nuxi module add convex-nuxt
   ```

3. Add the Convex URL

   Add the Convex URL to your `nuxt.config.ts` file.

   nuxt.config.ts

   ```
   export default defineNuxtConfig({
     compatibilityDate: '2025-07-15',
     devtools: { enabled: true },
     modules: ['convex-nuxt'],
     convex: {
       url: process.env.CONVEX_URL
     },
   })
   ```

4. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

5. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

6. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

7. (optional) Define a schema

   Add a new file `schema.ts` in the `convex/` folder with a description of your data.

   This will declare the types of your data for optional typechecking with TypeScript, and it will be also enforced at runtime.

   <br />

   convex/schema.ts

   ```
   import { defineSchema, defineTable } from "convex/server";
   import { v } from "convex/values";

   export default defineSchema({
     tasks: defineTable({
       text: v.string(),
       isCompleted: v.boolean(),
     }),
   });
   ```

8. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

9. Display the data in your app

   In `app.vue` use `useQuery` to subscribe your `api.tasks.get` API function.

   app/app.vue

   ```
   <script setup lang="ts">
   import { api } from "../convex/_generated/api";
   const { data: tasks } = useConvexQuery(api.tasks.get);
   </script>

   <template>
     <div>
       <h1>Tasks</h1>
       <ul>
         <li v-for="task in tasks" :key="task._id">
           <span>{{ task.text }}</span>
         </li>
       </ul>
     </div>
   </template>
   ```

10. Update script to start development server

    By default, Convex stores environment variables in `.env.local`, and Nuxt looks for environment variables in `.env`.

    To use the default `npm run dev` command, update your `package.json` to use the `--dotenv .env.local` flag.

    package.json

    ```
    {
      "name": "nuxt-app",
      "private": true,
      "type": "module",
      "scripts": {
        "build": "nuxt build",
        "dev": "nuxt dev --dotenv .env.local",
        "generate": "nuxt generate",
        "preview": "nuxt preview",
        "postinstall": "nuxt prepare"
      },
      "dependencies": {
        "convex": "^1.25.2",
        "convex-nuxt": "^0.1.3",
        "nuxt": "^3.17.6",
        "vue": "^3.5.17",
        "vue-router": "^4.5.1"
      }
    }
    ```

11. Start the app

    Start the app, open <http://localhost:3000> in a browser, and see the list of tasks.

    ```
    npm run dev
    ```

For more examples, take a look at the [Nuxt Convex module repository](https://github.com/chris-visser/convex-nuxt).

See the complete [Nuxt npm package documentation](https://www.npmjs.com/package/convex-nuxt).

---

# Source: https://docs.convex.dev/platform-apis/oauth-applications.md

# OAuth Applications

Convex allows third-party app developers to manage a user's projects on their behalf through **Application Tokens**.

Application tokens are obtained through the OAuth authorization code flow, which will be described in detail below.

There are two types of OAuth tokens:

* Team-scoped tokens that are authorized to create new projects, create new deployments within projects, and have read and write access to data and functions to every project on the team.
* Project-scoped tokens that can create new deployments and access data and functions within a specific project.

note

All application tokens are also scoped to the permissions of the member that authorized usage. If the member is removed from the team, or their permissions changed, the permissions of the token will also change.

## Creating an application[​](#creating-an-application "Direct link to Creating an application")

To obtain application tokens, you'll first have to register an OAuth application with Convex, which can be done in your [Team Settings](https://dashboard.convex.dev/team/settings/applications/oauth-apps).

To register an application, you'll need to provide a name for the application and a set of redirect URIs. Redirect URIs are used to return users to your application once they have authorized you to access their Convex team or project. You may add up to 20 redirect URIs, including ones pointing to [localhost](http://localhost) for testing.

Once you've created your application, it will be in the "Unverified" state. In the Unverified state, you'll be able to obtain application tokens for your own team, but not for other teams. We recommend testing your application in the Unverified state before requesting verification.

You may request verification by clicking the ⋮ button next to your application, and clicking "Request Verification".

### Verification requirements[​](#verification-requirements "Direct link to Verification requirements")

To have your application be verified and be accessible for all Convex users, it must meet the following criteria:

* The application description has an explanation of the capabilities and planned future capabilities of your application.
* The application name, redirect URIs, and content of the redirect URIs do not attempt to misrepresent another organization, business, or entity.
* The listed redirect URIs belong to your organization.

The Convex team will respond to your verification request by email if more information is required.

## Implementing OAuth[​](#implementing-oauth "Direct link to Implementing OAuth")

Convex implements [OAuth 2.0](https://oauth.net/2/) (RFC 6749)'s [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) flow. Convex also optionally supports the [PKCE extension](https://oauth.net/2/pkce/) (RFC 7636) to improve security.

* Convex provides two *authorization endpoint* URLs, depending on whether you are generating team-scoped or project-scoped tokens:

  <!-- -->

  * `https://dashboard.convex.dev/oauth/authorize/team`
  * `https://dashboard.convex.dev/oauth/authorize/project`

* Convex's **token endpoint** is `https://api.convex.dev/oauth/token`.

We'll walk through the authorization flow step by step. However, we recommend using an OAuth 2.0 client library to help construct the required URLs and API calls.

## Step 1: Redirect the user to Convex's authorization endpoint[​](#step-1-redirect-the-user-to-convexs-authorization-endpoint "Direct link to Step 1: Redirect the user to Convex's authorization endpoint")

In your application, navigate the user to:

`https://dashboard.convex.dev/oauth/authorize[TOKEN_SCOPE]?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code&state=[STATE]`

* `[TOKEN_SCOPE]` should be replaced with "team" or "project"
* `[CLIENT_ID]` should be replaced with your app's client ID as assigned by Convex.
* `[REDIRECT_URI]` is a URL on your application's domain. The user will be redirected back to that URL after authorizing.
  <!-- -->
  * **Important note**: You'll need to provide us with all the redirect URIs that your application might use (likely just one). This is required to prevent a malicious application from masquerading as yours, but redirecting to a different callback.
* `[STATE]` is an optional arbitrary string. It's up to you how to encode it, but your application will use this to decide what to do with the auth token after it receives it.

**Remember to URI-encode all the parameters!**

This brings the user to a page that looks like this:

![OAuth authorization page](/assets/images/oauth-page-a895fb5b2d41e9fd16dcc4003f1ca6a1.png)

From here, the user can select which team they'd like to authorize access to. If using the project flow, the user will also be able to select an existing project or create a new project. After they click "Authorize", the page will redirect to your redirect URL.

## Step 2: Receive the callback[​](#step-2-receive-the-callback "Direct link to Step 2: Receive the callback")

The authorization endpoint brings the user to your redirect URI with the `code` and `state` query parameters populated. If your `redirect_uri` was `https://yourapp.example.com/cb`, the result would look like:

`https://yourapp.example.com/cb?code=[CODE]&state=[STATE]`

where `state` is the same value you provided earlier, and `code` is a randomly generated string like `895c59eb98504a5bbaa7ad2e49cf4817`. This code **is not** the final auth token - you'll need to exchange it for one within 10 minutes.

## Step 3: Exchange the authorization code for a project token[​](#step-3-exchange-the-authorization-code-for-a-project-token "Direct link to Step 3: Exchange the authorization code for a project token")

Your application should make an HTTP POST request to the following endpoint:

`https://api.convex.dev/oauth/token`

The body should have content type `application/x-www-form-urlencoded` and look like the following:

`client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&grant_type=authorization_code&redirect_uri=[REDIRECT_URI]&code=[CODE]`

* `client_id` is the same one used to construct the authorization endpoint URL.
* `client_secret` is your app's secret assigned by Convex.
* `grant_type` is always `authorization_code`.
* `redirect_uri` is the same one used to construct the authorization endpoint URL.
* `code` is the authorization code provided to your callback.
  <!-- -->
  * Note that a `code` can only be exchanged *once* for an access token.

If all provided values are correct, Convex's API returns a JSON response containing:

```
{
	"access_token": "team:my-team|AAAAAA==",
	"token_type": "bearer"
}
```

The `access_token` is the application token!

# Using PKCE (RFC 7636)

Convex supports this extension to the Authorization Code grant type. Only the `S256` method is allowed. PKCE protects a leaked authorization code from being used by an attacker even if your client secret is not private (e.g. if it has to be embedded in a client-side application).

OAuth client libraries typically support PKCE already, but to implement it manually:

* Each time you request user authorization, before redirecting the user, construct a random string called the `code_verifier`. It's recommended that you generate a random 32-byte value and base64url-encode it.
* Calculate `code_challenge = base64url(sha256(code_verifier))`. This will be a 43-character string.
* Redirect the user to authorization endpoint as before (`/oauth/authorize/[TOKEN_SCOPE]`), but additionally provide the parameters `code_challenge=[CODE_CHALLENGE]&code_challenge_method=S256`.
* When exchanging the authorization code for a token, additionally provide the parameter `code_verifier=[CODE_VERIFIER]`.

---

# Source: https://docs.convex.dev/database/advanced/occ.md

# OCC and Atomicity

In [Queries](/functions/query-functions.md), we mentioned that determinism was important in the way optimistic concurrency control (OCC) was used within Convex. In this section, we'll dive much deeper into *why*.

## Convex Financial, Inc.[​](#convex-financial-inc "Direct link to Convex Financial, Inc.")

Imagine that you're building a banking app, and therefore your databases stores accounts with balances. You want your users to be able to give each other money, so you write a mutation function that transfers funds from one user's account to another.

One run of that transaction might read Alice's account balance, and then Bob's. You then propose to deduct $5 from Alice's account and increase Bob's balance by the same $5.

Here's our pseudocode:

```
$14 <- READ Alice
$11 <- READ Bob
WRITE Alice $9
WRITE Bob $16
```

This ledger balance transfer is a classic database scenario that requires a guarantee that these write operations will only apply together. It is a really bad thing if only one operation succeeds!

```
$14 <- READ Alice
$11 <- READ Bob
WRITE Alice $9
*crash* // $5 lost from your bank
```

You need a guarantee that this can never happen. You require transaction atomicity, and Convex provides it.

The problem of data correctness is much deeper. Concurrent transactions that read and edit the same records can create *data races*.

In the case of our app it's entirely possible that someone deducts Alice's balance right after we read it. Maybe she bought a Coke Zero at the airport with her debit card for $3.

```
$5 Transfer                           $3 Debit Card Charge
----------------------------------------------------------
$14 <- READ Alice
$11 <- READ Bob
                                        $14 <- READ Alice
                                        WRITE Alice $11
WRITE Alice $9 // Free coke!
WRITE Bob $16
```

Clearly, we need to prevent these types of data races from happening. We need a way to handle these concurrent conflicts. Generally, there are two common approaches.

Most traditional databases choose a *pessimistic locking* strategy. (Pessimism in this case means the strategy assumes conflict will happen ahead of time so seeks to prevent it.) With pessimistic locking, you first need to acquire a lock on Alice's record, and then acquire a lock on Bob's record. Then you can proceed to conduct your transaction, knowing that any other transaction that needed to touch those records will wait until you are done and all your writes are committed.

After decades of experience, the drawbacks of pessimistic locking are well understood and undeniable. The biggest limitation arises from real-life networks and computers being inherently unreliable. If the lock holder goes missing for whatever reason half way through its transaction, everyone else that wants to modify any of those records is waiting indefinitely. Not good!

Optimistic concurrency control is, as the name states, optimistic. It assumes the transaction will succeed and doesn't worry about locking anything ahead of time. Very brash! How can it be so sure?

It does this by treating the transaction as a *declarative proposal* to write records on the basis of any read record versions (the "read set"). At the end of the transaction, the writes all commit if every version in the read set is still the latest version of that record. This means no concurrent conflict occurred.

Now using our version read set, let's see how OCC would have prevented the soda-catastrophe above:

```
$5 Transfer                           $3 Debit Card Charge
----------------------------------------------------------
(v1, $14) <- READ Alice
(v7, $11) <- READ Bob
                                        (v1, $14) <- READ Alice
                                        WRITE Alice $11
                                        IF Alice.v = v1

WRITE Alice = $9, Bob = $16
    IF Alice.v = v1, Bob.v = v7 // Fails! Alice is = v2
```

This is akin to being unable to push your Git repository because you're not at HEAD. We all know in that circumstance, we need to pull, and rebase or merge, etc.

## When OCC loses, determinism wins[​](#when-occ-loses-determinism-wins "Direct link to When OCC loses, determinism wins")

A naive optimistic concurrency control solution would be to solve this the same way that Git does: require the user/application to resolve the conflict and determine if it is safe to retry.

In Convex, however, we don't need to do that. We know the transaction is deterministic. It didn't charge money to Stripe, it didn't write a permanent value out to the filesystem. It had no effect at all other than proposing some atomic changes to Convex tables that were not applied.

The determinism means that we can simply re-run the transaction; you never need to worry about temporary data races. We can run several retries if necessary until we succeed to execute the transaction without any conflicts.

tip

In fact, the Git analogy stays very apt. An OCC conflict means we cannot push because our HEAD is out of date, so we need to rebase our changes and try again. And determinism is what guarantees there is never a "merge conflict", so (unlike with Git) this rebase operation will always eventually succeed without developer intervention.

## Snapshot Isolation vs Serializability[​](#snapshot-isolation-vs-serializability "Direct link to Snapshot Isolation vs Serializability")

It is common for optimistic multi-version concurrency control databases to provide a guarantee of [snapshot isolation](https://en.wikipedia.org/wiki/Snapshot_isolation). This [isolation level](https://en.wikipedia.org/wiki/Isolation_\(database_systems\)) provides the illusion that all transactions execute on an atomic snapshot of the data but it is vulnerable to [anomalies](https://en.wikipedia.org/wiki/Snapshot_isolation#Definition) where certain combinations of concurrent transactions can yield incorrect results. The implementation of optimistic concurrency control in Convex instead provides true [serializability](https://en.wikipedia.org/wiki/Serializability) and will yield correct results regardless of what transactions are issued concurrently.

## No need to think about this[​](#no-need-to-think-about-this "Direct link to No need to think about this")

The beauty of this approach is that you can simply write your mutation functions as if they will *always succeed*, and always be guaranteed to be atomic.

Aside from sheer curiosity about how Convex works, day to day there's no need to worry about conflicts, locking, or atomicity when you make changes to your tables and documents. The "obvious way" to write your mutation functions will just work.

---

# Source: https://docs.convex.dev/client/open-api.md

# OpenAPI & Other Languages

Convex doesn’t have explicit support for many languages including Go, Java, and C++. However, you can generate [OpenAPI](https://swagger.io/specification/) specifications from your Convex deployment to create type-safe clients for languages that aren't currently supported. Under the hood, this uses our [HTTP API](/http-api/.md). This means that your queries will not be reactive/real-time.

OAS generation is in beta

OAS generation<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

## Setup[​](#setup "Direct link to Setup")

1. Install the Convex Helpers npm package

   Install the `convex-helpers` package, which contains a CLI command to generate an Open API specification.

   ```
   npm install convex-helpers
   ```

2. Run a command to generate an OpenAPI specification

   Running this command will call into your configured Convex deployment and generate an `convex-spec.yaml` file based on it. You can see additional flags by passing `--help` to the command.

   ```
   npx convex-helpers open-api-spec
   ```

3. Generate a type-safe client

   You can use a separate tools to generate a client from the `convex-spec.yaml` file. Some popular options are [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator) and [Swagger](https://swagger.io/tools/swagger-codegen/).

   ```
   # convex-spec.yaml
   openapi: 3.0.3
   info:
     title: Convex App - OpenAPI 3.0
     version: 0.0.0
     servers:
       - url: "{hostUrl}"
     description: Convex App API
     ...
   ```

## Example[​](#example "Direct link to Example")

Below are code snippets of what this workflow looks like in action. These snippets include two different files:

* `convex/load.ts` - contains Convex function definitions
* `convex.go` - contains `Go` code that uses a generated, type-safe `HTTP` client. This client was generated by installing the [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator) package and running the command `npx openapi-generator-cli generate -i convex-spec.yaml -g go -o convex_client`

convex/load.ts

TS

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

export const loadOne = query({
  args: { normalizedId: v.string(), token: v.string() },
  returns: v.union(
    v.object({
      ...LinkTable.validator.fields,
      _creationTime: v.number(),
      _id: v.id("links"),
    }),
    v.null(),
  ),
  handler: async (ctx, { normalizedId, token }) => {
    if (token === "" || token !== process.env.CONVEX_AUTH_TOKEN) {
      throw new Error("Invalid authorization token");
    }
    return await ctx.db
      .query("links")
      .withIndex("by_normalizedId", (q) => q.eq("normalizedId", normalizedId))
      .first();
  },
});
```

convex.go

```
type Link struct {
	Short    string // the "foo" part of http://go/foo
	Long     string // the target URL or text/template pattern to run
	Created  time.Time
	LastEdit time.Time // when the link was last edited
	Owner    string    // user@domain
}

func (c *ConvexDB) Load(short string) (*Link, error) { 
  request := *convex.NewRequestLoadLoadOne(*convex.NewRequestLoadLoadOneArgs(short, c.token))
  resp, httpRes, err := c.client.QueryAPI.ApiRunLoadLoadOnePost(context.Background()).RequestLoadLoadOne(request).Execute()
  validationErr := validateResponse(httpRes.StatusCode, err, resp.Status) if
  validationErr != nil { return nil, validationErr }

  linkDoc := resp.Value.Get()
  if linkDoc == nil {
    err := fs.ErrNotExist
    return nil, err
  }
  link := Link{
    Short:    linkDoc.Short,
    Long:     linkDoc.Long,
    Created:  time.Unix(int64(linkDoc.Created), 0),
    LastEdit: time.Unix(int64(linkDoc.LastEdit), 0),
    Owner:    linkDoc.Owner,
  }

  return &link, nil
```

## Limits[​](#limits "Direct link to Limits")

* Argument and return value validators are not required, but they will enrich the types of your OpenAPI spec. Where validators aren't defined, we default to `v.any()` as the validator.
* You cannot call internal functions from outside of your Convex deployment.
* We currently do not support `bigints` or `bytes`.

---

# Source: https://docs.convex.dev/client/react/optimistic-updates.md

# Optimistic Updates

Even though Convex queries are completely reactive, sometimes you'll want to update your UI before the mutation changes propagate back to the client. To accomplish this, you can configure an *optimistic update* to execute as part of your mutation.

Optimistic updates are temporary, local changes to your query results which are used to make your app more responsive. These updates are made by functions registered on a mutation invocation with the [`.withOptimisticUpdate`](/api/interfaces/react.ReactMutation.md#withoptimisticupdate) configuration option.

Optimistic updates are run when a mutation is initiated, rerun if the local query results change, and rolled back when a mutation completes.

## Simple example[​](#simple-example "Direct link to Simple example")

Here is how an optimistic update could be added to an `increment` mutation in a simple counter app:

src/IncrementCounter.tsx

TS

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

export function IncrementCounter() {
  const increment = useMutation(api.counter.increment).withOptimisticUpdate(
    (localStore, args) => {
      const { increment } = args;
      const currentValue = localStore.getQuery(api.counter.get);
      if (currentValue !== undefined) {
        localStore.setQuery(api.counter.get, {}, currentValue + increment);
      }
    },
  );

  const incrementCounter = () => {
    increment({ increment: 1 });
  };

  return <button onClick={incrementCounter}>+1</button>;
}
```

Optimistic updates receive a [`localStore`](/api/interfaces/browser.OptimisticLocalStore.md), a view of the Convex client's internal state, followed by the arguments to the mutation.

This optimistic update updates the `api.counter.get` query to be `increment` higher if it's loaded.

## Complex example[​](#complex-example "Direct link to Complex example")

If we want to add an optimistic update to a multi-channel chat app, that might look like:

src/MessageSender.tsx

TS

```
import { api } from "../convex/_generated/api";
import { useMutation } from "convex/react";
import { Id } from "../convex/_generated/dataModel";

export function MessageSender(props: { channel: Id<"channels"> }) {
  const sendMessage = useMutation(api.messages.send).withOptimisticUpdate(
    (localStore, args) => {
      const { channel, body } = args;
      const existingMessages = localStore.getQuery(api.messages.list, {
        channel,
      });
      // If we've loaded the api.messages.list query, push an optimistic message
      // onto the list.
      if (existingMessages !== undefined) {
        const now = Date.now();
        const newMessage = {
          _id: crypto.randomUUID() as Id<"messages">,
          _creationTime: now,
          channel,
          body,
        };
        localStore.setQuery(api.messages.list, { channel }, [
          ...existingMessages,
          newMessage,
        ]);
      }
    },
  );

  async function handleSendMessage(
    channelId: Id<"channels">,
    newMessageText: string,
  ) {
    await sendMessage({ channel: channelId, body: newMessageText });
  }

  return (
    <button onClick={() => handleSendMessage(props.channel, "Hello world!")}>
      Send message
    </button>
  );
}
```

This optimistic update changes the `api.messages.list` query for the current channel to include a new message. The newly created message object should match the structure of the real messages generated by the `api.messages.list` query on the server.

Because this message includes the client's current time (not the server's), it will inevitably not match the `api.messages.list` query after the mutation runs. That's okay! The Convex client will handle rolling back this update after the mutation completes and the queries are updated. If there are small mistakes in optimistic updates, the UI will always eventually render the correct values.

Similarly, the update creates a temporary `Id` with `new Id("messages", crypto.randomUUID())`. This will also be rolled back and replaced with the true ID once the server assigns it.

Lastly, note that this update creates a new array of messages instead of using `existingMessages.push(newMessage)`. This is important! Mutating objects inside of optimistic updates will corrupt the client's internal state and lead to surprising results. Always create new objects inside of optimistic updates.

## Learning more[​](#learning-more "Direct link to Learning more")

To learn more, check out our API documentation:

* [`.withOptimisticUpdate`](/api/interfaces/react.ReactMutation.md#withoptimisticupdate)
* [`OptimisticUpdate`](/api/modules/browser.md#optimisticupdate)
* [`OptimisticLocalStore`](/api/interfaces/browser.OptimisticLocalStore.md)

If you'd like some hands on experience, try adding optimistic updates to the [tutorial app](https://github.com/get-convex/convex-tutorial)! If you do, you should notice the app feels snappier — just a little, Convex is pretty fast already! — but otherwise works the same.

To explore even further, try inserting a mistake into this update! You should see a flicker as the optimistic update is applied and then rolled back.

---

# Source: https://docs.convex.dev/client/nextjs/pages-router.md

# Next.js Pages Router

This pages covers the Pages Router variant of Next.js. Alternatively see the [App Router](/client/nextjs/app-router/.md) version of this page.

## Getting started[​](#getting-started "Direct link to Getting started")

Follow the [Next.js Pages Router Quickstart](/client/nextjs/pages-router/quickstart.md) to add Convex to a new or existing Next.js project.

## Adding client-side authentication[​](#adding-client-side-authentication "Direct link to Adding client-side authentication")

The simplest approach to authentication in Next.js is to keep it client-side.

For example Auth0 describes this approach in [Next.js Authentication with Auth0 guide](https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0), describing it in "[Next.js Static Site Approach](https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/#Next-js-Static-Site-Approach)" and "Serverless with the user on the frontend".

To require login on every page of your application you can add logic to `_app.jsx` to conditionally render page content, blocking it until the user is logged in.

If you're using Auth0, the helper component `ConvexProviderWithAuth0` can be imported from `convex/react-auth0`.

pages/\_app.jsx

```
import { ConvexReactClient } from "convex/react";
import { ConvexProviderWithAuth0 } from "convex/react-auth0";
import { Auth0Provider } from "@auth0/auth0-react";
import { AppProps } from "next/app";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider
      domain={process.env.NEXT_PUBLIC_AUTH0_DOMAIN!}
      clientId={process.env.NEXT_PUBLIC_AUTH0_CLIENT_ID!}
      authorizationParams={{
        redirect_uri:
          typeof window === "undefined" ? undefined : window.location.origin,
      }}
      useRefreshTokens={true}
      cacheLocation="localstorage"
    >
      <ConvexProviderWithAuth0 client={convex}>
        <Component {...pageProps} />
      </ConvexProviderWithAuth0>
    </Auth0Provider>
  );
}
```

Custom loading and logged out views can be built with the helper `Authenticated`, `Unauthenticated` and `AuthLoading` components from `convex/react`, see the [Convex Next.js demo](https://github.com/get-convex/convex-demos/tree/main/nextjs-pages-router/pages/_app.jsx) for an example.

If only some routes of your app require login, the same helpers can be used directly in page components that do require login instead of being shared between all pages from `pages/_app.jsx`. Share a single [ConvexReactClient](/api/classes/react.ConvexReactClient.md) instance between pages to avoid needing to reconnect to Convex on client-side page navigation.

Read more about authenticating users with Convex in [Authentication](/auth.md).

## API routes[​](#api-routes "Direct link to API routes")

Next.js supports building HTTP request handling routes, similar to Convex [HTTP Actions](/functions/http-actions.md). Using Next.js routes might be helpful if you need to use a dependency not supported by the Convex default runtime.

To build an [API route](https://nextjs.org/docs/api-routes/introduction) add a file to the `pages/api` directory.

To load and edit Convex data in your endpoints, use the [`fetchQuery`](/api/modules/nextjs.md#fetchquery) function from `convex/nextjs`:

pages/api/clicks.js

```
import type { NextApiRequest, NextApiResponse } from "next";
import { fetchQuery } from "convex/nextjs";
import { api } from "../../convex/_generated/api";

export const count = async function handler(
  _req: NextApiRequest,
  res: NextApiResponse,
) {
  const clicks = await fetchQuery(api.counter.get, { counterName: "clicks" });
  res.status(200).json({ clicks });
};
```

## Server-side rendering[​](#server-side-rendering "Direct link to Server-side rendering")

**Consider client-side rendering Convex data when using Next.js.** Data from Convex is [fully reactive](/functions/query-functions.md#caching--reactivity--consistency) so Convex needs a connection from your deployment to the browser in order to push updates as data changes.

You can of course load data from Convex in [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props) or [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props), but it will be non-reactive. To do this, use the [`fetchQuery`](/api/modules/nextjs.md#fetchquery) function to call query functions just like you would in [API routes](#api-routes).

To make authenticated requests to Convex during server-side rendering, you need authentication info present server-side. Auth0 describes this approach in [Serverless with the user on the backend](https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/#Serverless-with-the-user-on-the-backend). When server-side rendering, pass the authentication token as `token` to the third argument of `fetchQuery`.

To preload data on server side before rendering a reactive query on the client side use [`preloadQuery`](/api/modules/nextjs.md#preloadquery). Check out the [App Router version of these docs](/client/nextjs/app-router/server-rendering.md) for more details.

---

# Source: https://docs.convex.dev/database/pagination.md

# Paginated Queries

Paginated queries are [queries](/functions/query-functions.md) that return a list of results in incremental pages.

This can be used to build components with "Load More" buttons or "infinite scroll" UIs where more results are loaded as the user scrolls.

**Example:** [Paginated Messaging App](https://github.com/get-convex/convex-demos/tree/main/pagination)

Using pagination in Convex is as simple as:

1. Writing a paginated query function that calls [`.paginate(paginationOpts)`](/api/interfaces/server.OrderedQuery.md#paginate).
2. Using the [`usePaginatedQuery`](/api/modules/react.md#usepaginatedquery) React hook.

Like other Convex queries, paginated queries are completely reactive.

## Writing paginated query functions[​](#writing-paginated-query-functions "Direct link to Writing paginated query functions")

Convex uses cursor-based pagination. This means that paginated queries return a string called a [`Cursor`](/api/modules/server.md#cursor) that represents the point in the results that the current page ended. To load more results, you simply call the query function again, passing in the cursor.

To build this in Convex, define a query function that:

1. Takes in a single arguments object with a `paginationOpts` property of type [`PaginationOptions`](/api/interfaces/server.PaginationOptions.md).

   <!-- -->

   * `PaginationOptions` is an object with `numItems` and `cursor` fields.
   * Use `paginationOptsValidator` exported from `"convex/server"` to [validate](/functions/validation.md) this argument
   * The arguments object may include properties as well.

2. Calls [`.paginate(paginationOpts)`](/api/interfaces/server.OrderedQuery.md#paginate) on a [database query](/database/reading-data/.md), passing in the `PaginationOptions` and returning its result.
   <!-- -->
   * The returned `page` in the [`PaginationResult`](/api/interfaces/server.PaginationResult.md) is an array of documents. You may [`map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) or [`filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) it before returning it.

convex/messages.ts

TS

```
import { v } from "convex/values";
import { query, mutation } from "./_generated/server";
import { paginationOptsValidator } from "convex/server";

export const list = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    const foo = await ctx.db
      .query("messages")
      .order("desc")
      .paginate(args.paginationOpts);
    return foo;
  },
});
```

### Additional arguments[​](#additional-arguments "Direct link to Additional arguments")

You can define paginated query functions that take arguments in addition to `paginationOpts`:

convex/messages.ts

TS

```
export const listWithExtraArg = query({
  args: { paginationOpts: paginationOptsValidator, author: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_author", (q) => q.eq("author", args.author))
      .order("desc")
      .paginate(args.paginationOpts);
  },
});
```

### Transforming results[​](#transforming-results "Direct link to Transforming results")

You can apply arbitrary [transformations](/database/reading-data/.md#more-complex-queries) to the `page` property of the object returned by `paginate`, which contains the array of documents:

convex/messages.ts

TS

```
export const listWithTransformation = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    const results = await ctx.db
      .query("messages")
      .order("desc")
      .paginate(args.paginationOpts);
    return {
      ...results,
      page: results.page.map((message) => ({
        author: message.author.slice(0, 1),
        body: message.body.toUpperCase(),
      })),
    };
  },
});
```

## Paginating within React Components[​](#paginating-within-react-components "Direct link to Paginating within React Components")

To paginate within a React component, use the [`usePaginatedQuery`](/api/modules/react.md#usepaginatedquery) hook. This hook gives you a simple interface for rendering the current items and requesting more. Internally, this hook manages the continuation cursors.

The arguments to this hook are:

* The name of the paginated query function.
* The arguments object to pass to the query function, excluding the `paginationOpts` (that's injected by the hook).
* An options object with the `initialNumItems` to load on the first page.

The hook returns an object with:

* `results`: An array of the currently loaded results.

* `isLoading` - Whether the hook is currently loading results.

* `status`: The status of the pagination. The possible statuses are:

  <!-- -->

  * `"LoadingFirstPage"`: The hook is loading the first page of results.
  * `"CanLoadMore"`: This query may have more items to fetch. Call `loadMore` to fetch another page.
  * `"LoadingMore"`: We're currently loading another page of results.
  * `"Exhausted"`: We've paginated to the end of the list.

* `loadMore(n)`: A callback to fetch more results. This will only fetch more results if the status is `"CanLoadMore"`.

src/App.tsx

TS

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

export function App() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.messages.list,
    {},
    { initialNumItems: 5 },
  );
  return (
    <div>
      {results?.map(({ _id, body }) => <div key={_id}>{body}</div>)}
      <button onClick={() => loadMore(5)} disabled={status !== "CanLoadMore"}>
        Load More
      </button>
    </div>
  );
}
```

You can also pass additional arguments in the arguments object if your function expects them:

src/App.tsx

TS

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

export function App() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.messages.listWithExtraArg,
    { author: "Alex" },
    { initialNumItems: 5 },
  );
  return (
    <div>
      {results?.map(({ _id, body }) => <div key={_id}>{body}</div>)}
      <button onClick={() => loadMore(5)} disabled={status !== "CanLoadMore"}>
        Load More
      </button>
    </div>
  );
}
```

### Reactivity[​](#reactivity "Direct link to Reactivity")

Like any other Convex query functions, paginated queries are **completely reactive**. Your React components will automatically rerender if items in your paginated list are added, removed or changed.

One consequence of this is that **page sizes in Convex may change!** If you request a page of 10 items and then one item is removed, this page may "shrink" to only have 9 items. Similarly if new items are added, a page may "grow" beyond its initial size.

## Paginating manually[​](#paginating-manually "Direct link to Paginating manually")

If you're paginating outside of React, you can manually call your paginated function multiple times to collect the items:

download.ts

TS

```
import { ConvexHttpClient } from "convex/browser";
import { api } from "../convex/_generated/api";
import * as dotenv from "dotenv";

dotenv.config();

const client = new ConvexHttpClient(process.env.VITE_CONVEX_URL!);

/**
 * Logs an array containing all messages from the paginated query "listMessages"
 * by combining pages of results into a single array.
 */
async function getAllMessages() {
  let continueCursor = null;
  let isDone = false;
  let page;

  const results = [];

  while (!isDone) {
    ({ continueCursor, isDone, page } = await client.query(api.messages.list, {
      paginationOpts: { numItems: 5, cursor: continueCursor },
    }));
    console.log("got", page.length);
    results.push(...page);
  }

  console.log(results);
}

getAllMessages();
```

---

# Source: https://docs.convex.dev/deployment-api/pause-deployment.md

# Source: https://docs.convex.dev/production/pause-deployment.md

# Pausing a Deployment

Pausing a deployment is a way to "turn off" a deployment without deleting any data. This can be useful if you have an action that is blowing through a third-party API quota and you just need a big red stop button.

When a deployment is paused:

* New function calls will return an error.
* Scheduled jobs will queue and run when the deployment is resumed.
* Cron jobs will be skipped.
* Everything else (e.g. code push, dashboard edits) should work as usual.

**This is important!** All new function calls will return an error when a deployment is paused, so if you are running an app in production you may want to consider alternatives like pushing code that disables a feature you are trying to "turn off". We recommend testing this feature in a dev deployment first before pausing a production deployment.

![Pause Deployment Button](/assets/images/pause_deployment-a9d8c37bbb48ab9b670afce0c8296e6d.png)

A deployment can be resumed with this button on the same page:

![Resume Deployment](/assets/images/resume_deployment-851f7726c60d50f1561a568c5b4beee4.png)

---

# Source: https://docs.convex.dev/platform-apis.md

# Platform APIs

info

Convex Platform APIs are in openly available in Beta. Please contact <platforms@convex.dev> if your use case requires additional capabilities.

This guide is for products that want to orchestrate multiple Convex projects in their accounts or manage projects in their users' accounts. These APIs are most often used by AI app builders, such as [Bloom](https://bloom.diy/), [A0](https://a0.dev/), or [Macaly](https://www.macaly.com/).

These guides assume a good understanding of Convex cloud hierarchy (teams, projects, and deployments) as well as the [development workflow](/understanding/workflow.md).

## Managing your own projects[​](#managing-your-own-projects "Direct link to Managing your own projects")

This means that you are creating projects, deployments, and pushing code programmatically in the context of the team you own.

To manage projects in your own team, you need to get a team-scoped token and ID from your [Team Settings](https://dashboard.convex.dev/team/settings/access-tokens).

caution

These tokens are owned by the team member that's logged into the Convex dashboard when you retrieve them.

This means that this user owns any dev deployments created by using these tokens. If this user leaves the team, that also deletes all of their dev deployments from the team.

We recommend creating a separate service account that's added as a team member. Retrieve the token after logging in as this service account.

## Managing your users' projects[​](#managing-your-users-projects "Direct link to Managing your users' projects")

This means your users authorize your product to manage their own Convex team or projects.

To do this, you need to create an OAuth 2.0 application so that the user can grant your product the necessary permissions.

Follow the [OAuth Applications](/platform-apis/oauth-applications.md) guide to create an OAuth application and request a relevant token.

## APIs to manage projects[​](#apis-to-manage-projects "Direct link to APIs to manage projects")

Once you have obtained a token from one of the methods above, you can use it to call the relevant APIs to manage Convex projects and deployments.

[Management API Reference](/management-api.md)

## Pushing code to a deployment[​](#pushing-code-to-a-deployment "Direct link to Pushing code to a deployment")

Working with your deployment should be scripted primarily with the existing Convex CLI. The Convex CLI manages a lot of the heavy lifting: bundling code, properly handling responses, etc.

The examples here assume you are working in a container with shell and file system access from which you can drive the app building process. You likely already have this if you're generating frontend code.

Set [`CONVEX_DEPLOY_KEY`](/cli/deploy-key-types.md) is the value returned by the [Create deploy key](/management-api/create-deploy-key.md) API.

### Pushing code to the dev Convex backend[​](#pushing-code-to-the-dev-convex-backend "Direct link to Pushing code to the dev Convex backend")

```
CONVEX_DEPLOY_KEY="YOUR_DEPLOY_KEY" npx convex dev --once
```

### Pushing code to the prod Convex backend[​](#pushing-code-to-the-prod-convex-backend "Direct link to Pushing code to the prod Convex backend")

```
CONVEX_DEPLOY_KEY="YOUR_DEPLOY_KEY" npx convex deploy
```

To view the full list of commands, refer to the [CLI documentation](/cli.md).

---

# Source: https://docs.convex.dev/agents/playground.md

# Playground

The Playground UI is a simple way to test, debug, and develop with the agent.

![Playground UI Screenshot](https://get-convex.github.io/agent/screenshot.png)

* Pick a user to list their threads.
* Browse the user's threads.
* List the selected thread's messages, along with tool call details.
* Show message metadata details.
* Experiment with contextual message lookup, adjusting context options.
* Send a message to the thread, with configurable saving options.
* It uses api keys to communicate securely with the backend.

There is also a [hosted version here](https://get-convex.github.io/agent/).

## Setup[​](#setup "Direct link to Setup")

**Note**: You must already have a Convex project set up with the Agent. See the [docs](/agents/getting-started.md) for setup instructions.

In your agent Convex project, make a file `convex/playground.ts` with:

```
import { definePlaygroundAPI } from "@convex-dev/agent";
import { components } from "./_generated/api";
import { weatherAgent, fashionAgent } from "./example";

/**
 * Here we expose the API so the frontend can access it.
 * Authorization is handled by passing up an apiKey that can be generated
 * on the dashboard or via CLI via:
 * npx convex run --component agent apiKeys:issue
 */
export const {
  isApiKeyValid,
  listAgents,
  listUsers,
  listThreads,
  listMessages,
  createThread,
  generateText,
  fetchPromptContext,
} = definePlaygroundAPI(components.agent, {
  agents: [weatherAgent, fashionAgent],
});
```

From in your project's repo, issue yourself an API key:

```
npx convex run --component agent apiKeys:issue '{name:"..."}'
```

Note: to generate multiple keys, give a different name to each key. To revoke and reissue a key, pass the same name.

Then visit the [hosted version](https://get-convex.github.io/agent/).

It will ask for your Convex deployment URL, which can be found in `.env.local`. It will also ask for your API key that you generated above. If you used a different path for `convex/playground.ts` you can enter it. E.g. if you had `convex/foo/bar.ts` where you exported the playground API, you'd put in `foo/bar`.

## Running it locally[​](#running-it-locally "Direct link to Running it locally")

You can run the playground locally with:

```
npx @convex-dev/agent-playground
```

It uses the `VITE_CONVEX_URL` env variable, usually pulling it from .env.local.

---

# Source: https://docs.convex.dev/production/hosting/preview-deployments.md

# Preview Deployments

Convex preview deployments allow your team to test out backend changes before pushing them to production.

In combination with Vercel Preview Deployments or Netlify Deploy Previews, you can preview both frontend and backend changes together.

Convex preview deployments are in beta

Convex preview deployments<!-- --> <!-- -->are<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

## Setup[​](#setup "Direct link to Setup")

Follow the [Vercel](/production/hosting/vercel.md#preview-deployments) or [Netlify](/production/hosting/netlify.md#deploy-previews) hosting guide for setting up frontend and backend previews together, as well as details on how Convex preview deployments work.

See `npx convex deploy --help` for all available options for `npx convex deploy`.

## Limits[​](#limits "Direct link to Limits")

Convex preview deployments are automatically cleaned up 5 days (14 days on the Professional Convex plan) after creation, or when a new preview deployment with the same name is created. They can also be manually deleted from the Convex dashboard.

Preview deployments count towards your deployment limit.

When a Convex preview deployment is deleted, the Vercel/Netlify preview link will open and show UI, but will be unable to run any Convex functions since it is pointing at a Convex deployment that no longer exists. In these cases, re-deploying in Vercel/Netlify should produce a link pointing at a new Convex deployment.

Convex allows a single deployment at a time for a given name (Git branch). When pushing updates to an existing branch, the deployment will be deleted, resulting in a preview link unable to run Convex functions, before it is replaced by a new Convex deployment.

Initial data can be set up on a Convex preview deployment by running a function. There are currently no other ways to set up data on a Convex preview deployment -- viewing changes against a copy of production data or importing data from a different Convex deployment is not supported.

Note that if the function call fails, the `deploy` command will fail, but the new preview deployment will have already been provisioned. Best course of action is to fix the issue in the function and redeploy.

Support for preview deployments is a beta feature, so [let us know on Discord](https://convex.dev/community) if you have feedback!

---

# Source: https://docs.convex.dev/production.md

# Deploying Your App to Production

Convex is built to serve live, production app traffic. Here we cover how to deploy and maintain a production version of your app.

## Project management[​](#project-management "Direct link to Project management")

When you sign up for Convex, a Convex team is created for you. You can [create more teams from the dashboard](/dashboard/teams.md) and add other people to them as members. You can upgrade your team to the [Starter](https://www.convex.dev/pricing) plan to pay as you go or the [Professional](https://www.convex.dev/pricing) for additional features, higher built-in limits, 24h support, and discounted usage-based pricing.

Each team can have multiple projects. When you run `npx convex dev` for the first time, a project is created for you automatically. You can also create a project from the dashboard.

Every project has one shared production deployment and one development deployment per team member. This allows each team member to make and test changes independently before they are deployed to the production deployment.

Usually all deployments belonging to a single project run the same code base (or a version of it), but Convex doesn't enforce this. You can also run the same code base on multiple different prod deployments belonging to different projects, see [staging](#staging-environment) below.

## Deploying to production[​](#deploying-to-production "Direct link to Deploying to production")

Your Convex deployments run your backend logic and in most cases you will also develop a client that uses the backend. If your client is a web app, follow the [Hosting and Deployment](/production/hosting/.md) guide, to learn how to deploy your client and your Convex backend together.

You can also deploy your backend on its own. Check out the [Project Configuration](/production/project-configuration.md) page to learn more.

## Staging environment[​](#staging-environment "Direct link to Staging environment")

With Convex [preview deployments](/production/hosting/preview-deployments.md) your team can test out changes before deploying them to production. If you need a more permanent staging environment, you can use a separate Convex project, and deploy to it by setting the `CONVEX_DEPLOY_KEY` environment variable when running [`npx convex deploy`](/cli.md#deploy-convex-functions-to-production).

## Typical team development workflow[​](#typical-team-development-workflow "Direct link to Typical team development workflow")

Teams developing on Convex usually follow this workflow:

1. If this is the team's first project, one team member creates a team on the dashboard.

2. One team member creates a project by running `npx convex dev`, perhaps starting with a [quickstart](/quickstarts) or a [template](https://www.convex.dev/templates).

3. The team member creates a Git repository from the initial code and shares it with their team (via GitHub, GitLab etc.).

4. Other team members pull the codebase, and get their own dev deployments by running `npx convex dev`.

5. All team members can make backend changes and test them out with their individual dev deployments. When a change is ready the team member opens a pull-request (or commits to a shared branch).

   <!-- -->

   * [Backup / Restore](/database/backup-restore.md) can be used to populate a dev deployment with data from a prod deployment.
   * [Data import](/database/import-export/import.md) can be used to populate a dev deployment with synthetic seed data.
   * Members of a team with the [Pro plan](https://www.convex.dev/pricing) can get separate [preview deployments](/production/hosting/preview-deployments.md) to test each other's pull-requests.

6. Deployment to production can happen [automatically](/production/hosting/.md) when changes get merged to the designated branch (say `main`).
   <!-- -->
   * Alternatively one of the team members can deploy to production manually by running `npx convex deploy`.

### Making safe changes[​](#making-safe-changes "Direct link to Making safe changes")

Especially if your app is live you want to make sure that changes you make to your Convex codebase do not break it.

Some unsafe changes are handled and caught by Convex, but others you need handle yourself.

1. **Schema must always match existing data.** Convex enforces this constraint. You cannot push a schema to a deployment with existing data that doesn't match it, unless you turn off schema enforcement. In general it safe to:

   <!-- -->

   1. Add new tables to the schema.
   2. Add an `optional` field to an existing table's schema, set the field on all documents in the table, and then make the field required.
   3. Mark an existing field as `optional`, remove the field from all documents, and then remove the field.
   4. Mark an existing field as a `union` of the existing type and a new type, modify the field on all documents to match the new type, and then change the type to the new type.

2. **Functions should be backwards compatible.** Even if your only client is a website, and you deploy it together with your backend, your users might still be running the old version of your website when your backend changes. Therefore you should make your functions backwards compatible until you are OK to break old clients. In general it is safe to:

   <!-- -->

   1. Add new functions.
   2. Add an `optional` named argument to an existing function.
   3. Mark an existing named argument as `optional`.
   4. Mark an existing named argument as a `union` of the existing type and a new type.
   5. Change the behavior of the function in such a way that given the arguments from an old client its behavior will still be acceptable to the old client.

3. **Scheduled functions should be backwards compatible.** When you schedule a function to run in the future, you provide the argument values it will receive. Whenever a function runs, it always runs its currently deployed version. If you change the function between the time it was scheduled and the time it runs, you must ensure the new version will behave acceptably given the old arguments.

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/production/project-configuration.md

# Project Configuration

## Local development[​](#local-development "Direct link to Local development")

When you're developing locally you need two pieces of information:

1. The name of your dev deployment. This is where your functions are pushed to and served from. It is stored in the `CONVEX_DEPLOYMENT` environment variable. `npx convex dev` writes it to the `.env.local` file.
2. The URL of your dev deployment, for your client to connect to. The name of the variable and which file it can be read from varies between client frameworks. `npx convex dev` writes the URL to the `.env.local` or `.env` file.

## Production deployment[​](#production-deployment "Direct link to Production deployment")

You should only be deploying to your production deployment once you have tested your changes on your local deployment. When you're ready, you can deploy either via a hosting/CI provider or from your local machine.

For a CI environment you can follow the [hosting](/production/hosting/.md) docs. `npx convex deploy` run by the CI pipeline will use the `CONVEX_DEPLOY_KEY`, and the frontend build command will use the deployment URL variable, both configured in your CI environment.

You can also deploy your backend from your local machine. `npx convex deploy` will ask for a confirmation and then deploy to the production deployment in the same project as your configured development `CONVEX_DEPLOYMENT`.

## `convex.json`[​](#convexjson "Direct link to convexjson")

Additional project configuration can be specified in the `convex.json` file in the root of your project (in the same directory as your `package.json`).

You can use the JSON schema for editor validation by adding a `$schema` property:

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json"
}
```

The file supports the following configuration options:

### Changing the `convex/` folder name or location[​](#changing-the-convex-folder-name-or-location "Direct link to changing-the-convex-folder-name-or-location")

You can choose a different name or location for the `convex/` folder via the `functions` field. For example, Create React App doesn't allow importing from outside the `src/` directory, so if you're using Create React App you should have the following config:

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "functions": "src/convex/"
}
```

### Installing packages on the server[​](#installing-packages-on-the-server "Direct link to Installing packages on the server")

You can specify which packages used by Node actions should be installed on the server, instead of being bundled, via the `node.externalPackages` field. [Read more](/functions/bundling.md#external-packages).

### Importing the generated functions API via `require()` syntax[​](#importing-the-generated-functions-api-via-require-syntax "Direct link to importing-the-generated-functions-api-via-require-syntax")

The Convex code generation can be configured to generate a CommonJS-version of the `_generated/api.js` file via the `generateCommonJSApi` field. [Read more](/client/javascript/node.md#javascript-with-commonjs-require-syntax).

### Configuring the Node.js version[​](#configuring-the-nodejs-version "Direct link to Configuring the Node.js version")

You can specify which Node.js version is used by Node actions via the `node.nodeVersion` field. The currently supported values are `"20"` and `"22"`. [Read more](/functions/runtimes.md#nodejs-version-configuration).

Convex version required

To change the Node.js version used by your project, you must use the `convex` NPM package version 1.27.0 or later.

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "node": {
    "nodeVersion": "22"
  }
}
```

Note: This configuration is not supported when running the self-hosted Convex backend. The node version that is specified in the [.nvmrc](https://github.com/get-convex/convex-backend/blob/main/.nvmrc) will be used instead.

### Using static code generation (beta)[​](#using-static-code-generation-beta "Direct link to Using static code generation (beta)")

Convex's code generation heavily relies on TypeScript's type inference. This makes updates snappy and jump-to-definition work for the `api` and `internal` objects, but it often slows down with large codebases.

If you're running into language server performance issues, you can instruct the Convex CLI to generate static versions of the `_generated/api.d.ts` and `_generated/dataModel.d.ts`:

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "codegen": {
    "staticApi": true,
    "staticDataModel": true
  }
}
```

This will greatly improve autocomplete and incremental typechecking performance, but it does have some tradeoffs:

* These types only update when `convex dev` is running.
* Jump-to-definition no longer works. To find `api.example.f`, you'll need to manually open `convex/example.ts` and find `f`.
* Functions no longer have return type inference and will default to `v.any()` if they don't have a returns validator.
* [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) no longer work in schema or API definitions. Use unions of string literal types instead.

This feature is currently in beta, and we'd love to improve these limitations. Let us know if you run into any issues or have any feedback!

### Configuring the TypeScript compiler[​](#configuring-the-typescript-compiler "Direct link to Configuring the TypeScript compiler")

By default, Convex will use the `tsc` binary installed in your project for typechecking. If you would like to use the TypeScript 7 native preview instead, you can set the `typescriptCompiler` option to `tsgo`. Note that `@typescript/native-preview` must be installed in your project to use `tsgo`.

Convex version required

To use the TypeScript 7 native preview, you must use the `convex` NPM package version 1.31.1 or later.

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "typescriptCompiler": "tsgo"
}
```

### Configuring bundler options[​](#configuring-bundler-options "Direct link to Configuring bundler options")

Convex includes sourcemaps when bundling your source code to provide stack traces and to display your code on the dashboard. If your code bundle is especially large, you can improve CLI upload times by excluding the source code content from the bundle. Set the `includeSourcesContent` property to `false` in the `bundler` options. Stack traces will continue to function as usual, but you will no longer be able to view your source code in the dashboard.

Convex version required

This configuration option is only available in version 1.31.3 or later of the `convex` NPM package.

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "bundler": {
    "includeSourcesContent": false
  }
}
```

### Configuring WorkOS AuthKit integration[​](#configuring-workos-authkit-integration "Direct link to Configuring WorkOS AuthKit integration")

If you're using [WorkOS AuthKit](/auth/authkit/.md) for authentication, you can configure automatic provisioning (development only) and configuration of WorkOS environments via the `authKit` field.

Convex version required

This configuration option is only available in version 1.31.6 or later of the `convex` NPM package.

convex.json

```
{
  "$schema": "./node_modules/convex/schemas/convex.schema.json",
  "authKit": {
    "dev": {
      "configure": {
        "redirectUris": ["http://localhost:3000/callback"],
        "appHomepageUrl": "http://localhost:3000",
        "corsOrigins": ["http://localhost:3000"]
      },
      "localEnvVars": {
        "WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
        "WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
        "NEXT_PUBLIC_WORKOS_REDIRECT_URI": "http://localhost:3000/callback"
      }
    },
    "preview": {
      "configure": {
        "redirectUris": ["https://${buildEnv.VERCEL_BRANCH_URL}/callback"],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_BRANCH_URL}"]
      }
    },
    "prod": {
      "environmentType": "production",
      "configure": {
        "redirectUris": [
          "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}/callback"
        ],
        "appHomepageUrl": "https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",
        "corsOrigins": ["https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}"]
      }
    }
  }
}
```

This configuration controls how WorkOS environments are provisioned and configured for each deployment type (dev, preview, prod). See the [Automatic AuthKit Configuration](/auth/authkit/auto-provision.md) guide for complete details.

---

# Source: https://docs.convex.dev/dashboard/projects.md

# Projects

![Project settings](/assets/images/projects-ea1be7a1deec4ee628278d2badc15e2f.png)

A project corresponds to a codebase that uses Convex, which contains a production deployment and one personal deployment for each team member.

Clicking on a project in the [landing page](https://dashboard.convex.dev) will redirect you to project details.

## Creating a project[​](#creating-a-project "Direct link to Creating a project")

Projects can be created from the dashboard or from the [CLI](/cli.md#create-a-new-project). To create a project from the dashboard click on the Create Project button.

## Project Settings[​](#project-settings "Direct link to Project Settings")

You can access project-level settings by clicking on the triple-dot `⋮` button on each Project card on the Projects page.

![Project card menu](/assets/images/project_menu-374924ad6539365422c2fe033a860807.png)

On the [Project Settings page](https://dashboard.convex.dev/project/settings), you can:

* Update your project's name and slug.
* Manage the project's Admins. See [Roles and Permissions](/dashboard/teams.md#roles-and-permissions) for more details.
* View the amount of [usage metrics](/dashboard/teams.md#usage) your project has consumed.
* Add [custom domains](/production/hosting/custom.md#custom-domains) for your production deployment
* Generate deploy keys for your production and preview deployments.
* Create and edit [default environment variables](/production/environment-variables.md#project-environment-variable-defaults).
* View instructions to regain access to your project, should you lose track of your `CONVEX_DEPLOYMENT` config.
* Permanently delete the project.

![Project settings](/assets/images/project_settings-1f0b5c77c97069e4f609965071ca2759.png)

## Deleting projects[​](#deleting-projects "Direct link to Deleting projects")

To delete a project, click on the triple-dot `⋮` button on the Project card and select "Delete". You may also delete your project from the Project Settings page.

Once a project is deleted, it cannot be recovered. All deployments and data associated with the project will be permanently removed. When deleting a project from the dashboard, you will be asked to confirm the deletion. Projects with activity in the production deployment will have additional confirmation steps to prevent accidental deletion.

![Delete project](/assets/images/project_delete-6db8dd21ba528b6c7ce4063a54e2d7f0.png)

---

# Source: https://docs.convex.dev/public-deployment-api/public-action-post.md

# Execute action

```
POST 
/action
```

Execute an action function.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-function-post-with-path.md

# Execute function by URL path

```
POST 
/run/{*functionIdentifier}
```

Execute a query, mutation, or action function by path in URL.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-function-post.md

# Execute any function

```
POST 
/function
```

Execute a query, mutation, or action function by name.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-get-query-ts.md

# Get latest timestamp

```
POST 
/query_ts
```

Get the latest timestamp for queries.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-mutation-post.md

# Execute mutation

```
POST 
/mutation
```

Execute a mutation function.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-query-at-ts-post.md

# Execute query at timestamp

```
POST 
/query_at_ts
```

Execute a query function at a specific timestamp.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-query-batch-post.md

# Execute query batch

```
POST 
/query_batch
```

Execute multiple query functions in a batch.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-query-get.md

# Execute query (GET)

```
GET 
/query
```

Execute a query function via GET request.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/public-deployment-api/public-query-post.md

# Execute query (POST)

```
POST 
/query
```

Execute a query function via POST request.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/client/python.md

# Source: https://docs.convex.dev/quickstart/python.md

# Python Quickstart

Learn how to query data from Convex in a Python app.

1. Create a Python script folder

   Create a folder for your Python script with a virtual environment.

   ```
   python3 -m venv my-app/venv
   ```

2. Install the Convex client and server libraries

   To get started, install the `convex` npm package which enables you to write your backend.

   And also install the `convex` Python client library and `python-dotenv` for working with `.env` files.

   ```
   cd my-app && npm init -y && npm install convex && venv/bin/pip install convex python-dotenv
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `"tasks:get"`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async ({ db }) => {
       return await db.query("tasks").collect();
     },
   });
   ```

7. Create a script to load data from Convex

   In a new file `main.py`, create a `ConvexClient` and use it to fetch from your `"tasks:get"` API.

   main.py

   ```
   import os

   from convex import ConvexClient
   from dotenv import load_dotenv

   load_dotenv(".env.local")
   CONVEX_URL = os.getenv("CONVEX_URL")
   # or you can hardcode your deployment URL instead
   # CONVEX_URL = "https://happy-otter-123.convex.cloud"

   client = ConvexClient(CONVEX_URL)

   print(client.query("tasks:get"))

   for tasks in client.subscribe("tasks:get"):
       print(tasks)
       # this loop lasts forever, ctrl-c to exit it
   ```

8. Run the script

   Run the script and see the serialized list of tasks.

   ```
   venv/bin/python -m main
   ```

See the [docs on PyPI](https://pypi.org/project/convex/) for more details.

---

# Source: https://docs.convex.dev/functions/query-functions.md

# Queries

Queries are the bread and butter of your backend API. They fetch data from the database, check authentication or perform other business logic, and return data back to the client application.

This is an example query, taking in named arguments, reading data from the database and returning a result:

convex/myFunctions.ts

TS

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

// Return the last 100 tasks in a given task list.
export const getTaskList = query({
  args: { taskListId: v.id("taskLists") },
  handler: async (ctx, args) => {
    const tasks = await ctx.db
      .query("tasks")
      .withIndex("by_task_list_id", (q) => q.eq("taskListId", args.taskListId))
      .order("desc")
      .take(100);
    return tasks;
  },
});
```

Read on to understand how to build queries yourself.

## Query names[​](#query-names "Direct link to Query names")

Queries are defined in

TypeScript

files inside your `convex/` directory.

The path and name of the file, as well as the way the function is exported from the file, determine the name the client will use to call it:

convex/myFunctions.ts

TS

```
// This function will be referred to as `api.myFunctions.myQuery`.
export const myQuery = …;

// This function will be referred to as `api.myFunctions.sum`.
export const sum = …;
```

To structure your API you can nest directories inside the `convex/` directory:

convex/foo/myQueries.ts

TS

```
// This function will be referred to as `api.foo.myQueries.listMessages`.
export const listMessages = …;
```

Default exports receive the name `default`.

convex/myFunctions.ts

TS

```
// This function will be referred to as `api.myFunctions.default`.
export default …;
```

The same rules apply to [mutations](/functions/mutation-functions.md) and [actions](/functions/actions.md), while [HTTP actions](/functions/http-actions.md) use a different routing approach.

Client libraries in languages other than JavaScript and TypeScript use strings instead of API objects:

* `api.myFunctions.myQuery` is `"myFunctions:myQuery"`
* `api.foo.myQueries.myQuery` is `"foo/myQueries:myQuery"`.
* `api.myFunction.default` is `"myFunction:default"` or `"myFunction"`.

## The `query` constructor[​](#the-query-constructor "Direct link to the-query-constructor")

To actually declare a query in Convex you use the `query` constructor function. Pass it an object with a `handler` function, which returns the query result:

convex/myFunctions.ts

TS

```
import { query } from "./_generated/server";

export const myConstantString = query({
  args: {},
  handler: () => {
    return "My never changing string";
  },
});
```

### Query arguments[​](#query-arguments "Direct link to Query arguments")

Queries accept named arguments. The argument values are accessible as fields of the second parameter of the handler function:

convex/myFunctions.ts

TS

```
import { query } from "./_generated/server";

export const sum = query({
  handler: (_, args: { a: number; b: number }) => {
    return args.a + args.b;
  },
});
```

Arguments and responses are automatically serialized and deserialized, and you can pass and return most value-like JavaScript data to and from your query.

To both declare the types of arguments and to validate them, add an `args` object using `v` validators:

convex/myFunctions.ts

TS

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

export const sum = query({
  args: { a: v.number(), b: v.number() },
  handler: (_, args) => {
    return args.a + args.b;
  },
});
```

See [argument validation](/functions/validation.md) for the full list of supported types and validators.

The first parameter of the handler function contains the query context.

### Query responses[​](#query-responses "Direct link to Query responses")

Queries can return values of any supported [Convex type](/functions/validation.md) which will be automatically serialized and deserialized.

Queries can also return `undefined`, which is not a valid Convex value. When a query returns `undefined` **it is translated to `null`** on the client.

### Query context[​](#query-context "Direct link to Query context")

The `query` constructor enables fetching data, and other Convex features by passing a [QueryCtx](/generated-api/server.md#queryctx) object to the handler function as the first parameter:

convex/myFunctions.ts

TS

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

export const myQuery = query({
  args: { a: v.number(), b: v.number() },
  handler: (ctx, args) => {
    // Do something with `ctx`
  },
});
```

Which part of the query context is used depends on what your query needs to do:

* To fetch from the database use the `db` field. Note that we make the handler function an `async` function so we can `await` the promise returned by `db.get()`:

  convex/myFunctions.ts

  TS

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

  export const getTask = query({
    args: { id: v.id("tasks") },
    handler: async (ctx, args) => {
      return await ctx.db.get("tasks", args.id);
    },
  });
  ```

  Read more about [Reading Data](/database/reading-data/.md).

* To return URLs to stored files use the `storage` field. Read more about [File Storage](/file-storage.md).

* To check user authentication use the `auth` field. Read more about [Authentication](/auth.md).

## Splitting up query code via helpers[​](#splitting-up-query-code-via-helpers "Direct link to Splitting up query code via helpers")

When you want to split up the code in your query or reuse logic across multiple Convex functions you can define and call helper

TypeScript

functions:

convex/myFunctions.ts

TS

```
import { Id } from "./_generated/dataModel";
import { query, QueryCtx } from "./_generated/server";
import { v } from "convex/values";

export const getTaskAndAuthor = query({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.id);
    if (task === null) {
      return null;
    }
    return { task, author: await getUserName(ctx, task.authorId ?? null) };
  },
});

async function getUserName(ctx: QueryCtx, userId: Id<"users"> | null) {
  if (userId === null) {
    return null;
  }
  return (await ctx.db.get("users", userId))?.name;
}
```

You can `export` helpers to use them across multiple files. They will not be callable from outside of your Convex functions.

See [Type annotating server side helpers](/understanding/best-practices/typescript.md#type-annotating-server-side-helpers) for more guidance on TypeScript types.

## Using NPM packages[​](#using-npm-packages "Direct link to Using NPM packages")

Queries can import NPM packages installed in `node_modules`. Not all NPM packages are supported, see [Runtimes](/functions/runtimes.md#default-convex-runtime) for more details.

```
npm install @faker-js/faker
```

convex/myFunctions.ts

TS

```
import { query } from "./_generated/server";
import { faker } from "@faker-js/faker";

export const randomName = query({
  args: {},
  handler: () => {
    faker.seed();
    return faker.person.fullName();
  },
});
```

## Calling queries from clients[​](#calling-queries-from-clients "Direct link to Calling queries from clients")

To call a query from [React](/client/react.md) use the [`useQuery`](/client/react.md#fetching-data) hook along with the generated [`api`](/generated-api/api.md) object.

src/MyApp.tsx

TS

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

export function MyApp() {
  const data = useQuery(api.myFunctions.sum, { a: 1, b: 2 });
  // do something with `data`
}
```

See the [React](/client/react.md) client documentation for all the ways queries can be called.

## Caching & reactivity & consistency[​](#caching--reactivity--consistency "Direct link to Caching & reactivity & consistency")

Queries have three awesome attributes:

1. **Caching**: Convex caches query results automatically. If many clients request the same query, with the same arguments, they will receive a cached response.
2. **Reactivity**: clients can subscribe to queries to receive new results when the underlying data changes.
3. **Consistency**: All database reads inside a single query call are performed at the same logical timestamp. Concurrent writes do not affect the query results.

To have these attributes the handler function must be *deterministic*, which means that given the same arguments (including the query context) it will return the same response.

For this reason queries cannot `fetch` from third party APIs. To call third party APIs, use [actions](/functions/actions.md).

You might wonder whether you can use non-deterministic language functionality like `Math.random()` or `Date.now()`. The short answer is that Convex takes care of implementing these in a way that you don't have to think about the deterministic constraint.

See [Runtimes](/functions/runtimes.md#default-convex-runtime) for more details on the Convex runtime.

## Limits[​](#limits "Direct link to Limits")

Queries have a limit to the amount of data they can read at once to guarantee good performance. Check out these limits in [Read/write limit errors](/functions/error-handling/.md#readwrite-limit-errors).

For information on other limits, see [Limits](/production/state/limits.md).

---

# Source: https://docs.convex.dev/client/nextjs/pages-router/quickstart.md

# Next.js Pages Quickstart

Learn how to query data from Convex in a Next.js app using the Pages Router.

Alternatively see the [App Router](/quickstart/nextjs.md) version of this quickstart.

1. Create a React app

   Create a Next.js app using the `npx create-next-app` command.

   Choose the default option for every prompt (hit Enter).

   ```
   npx create-next-app@latest my-app --no-app --js
   ```

2. Install the Convex client and server library

   To get started, install the `convex` package which provides a convenient interface for working with Convex from a React app.

   Navigate to your app and install `convex`.

   ```
   cd my-app && npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Connect the app to your backend

   In `pages/_app.js`, create a `ConvexReactClient` and pass it to a `ConvexProvider` wrapping your app.

   pages/\_app.js

   ```
   import "@/styles/globals.css";
   import { ConvexProvider, ConvexReactClient } from "convex/react";

   const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);

   export default function App({ Component, pageProps }) {
     return (
       <ConvexProvider client={convex}>
         <Component {...pageProps} />
       </ConvexProvider>
     );
   }
   ```

8. Display the data in your app

   In `pages/index.js`, use the `useQuery` hook to fetch from your `api.tasks.get` API function.

   pages/index.js

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

   export default function Home() {
     const tasks = useQuery(api.tasks.get);
     return (
       <main className="flex min-h-screen flex-col items-center p-24">
         {tasks?.map(({ _id, text }) => (
           <div key={_id}>{text}</div>
         ))}
       </main>
     );
   }
   ```

9. Start the app

   Start the app, open <http://localhost:3000> in a browser, and see the list of tasks.

   ```
   npm run dev
   ```

---

# Source: https://docs.convex.dev/agents/rag.md

# RAG (Retrieval-Augmented Generation) with the Agent component

The Agent component has built-in capabilities to search message history with hybrid text & vector search. You can also use the RAG component to use other data to search for context.

## What is RAG?[​](#what-is-rag "Direct link to What is RAG?")

Retrieval-Augmented Generation (RAG) is a technique that allows an LLM to search through custom knowledge bases to answer questions.

RAG combines the power of Large Language Models (LLMs) with knowledge retrieval. Instead of relying solely on the model's training data, RAG allows your AI to:

* Search through custom documents and knowledge bases
* Retrieve relevant context for answering questions
* Provide more accurate, up-to-date, and domain-specific responses
* Cite sources and explain what information was used

## RAG Component[​](#rag-component "Direct link to RAG Component")

[RAG Component YouTube Video](https://www.youtube.com/embed/dGmtAmdAaFs?si=ce-M8pt6EWDZ8tfd)

The RAG component is a Convex component that allows you to add data that you can search. It breaks up the data into chunks and generates embeddings to use for vector search. See the [RAG component docs](https://convex.dev/components/rag) for details, but here are some key features:

* **Namespaces:** Use namespaces for user-specific or team-specific data to isolate search domains.
* **Add Content**: Add or replace text content by key.
* **Semantic Search**: Vector-based search using configurable embedding models
* **Custom Filtering:** Define filters on each document for efficient vector search.
* **Chunk Context**: Get surrounding chunks for better context.
* **Importance Weighting**: Weight content by providing a 0 to 1 "importance" to affect per-document vector search results.
* **Chunking flexibility:** Bring your own document chunking, or use the default.
* **Graceful Migrations**: Migrate content or whole namespaces without disruption.

<!-- -->

[Convex Component](https://www.convex.dev/components/rag)

### [RAG (Retrieval-Augmented Generation)](https://www.convex.dev/components/rag)

[Search documents for relevant content to prompt an LLM using embeddings.](https://www.convex.dev/components/rag)

## RAG Approaches[​](#rag-approaches "Direct link to RAG Approaches")

This directory contains two different approaches to implementing RAG:

### 1. Prompt-based RAG[​](#1-prompt-based-rag "Direct link to 1. Prompt-based RAG")

A straightforward implementation where the system automatically searches for relevant context for a user query.

* The message history will only include the original user prompt and the response, not the context.
* Looks up the context and injects it into the user's prompt.
* Works well if you know the user's question will *always* benefit from extra context.

For example code, see [ragAsPrompt.ts](https://github.com/get-convex/agent/blob/main/example/convex/rag/ragAsPrompt.ts) for the overall code. The simplest version is:

```
const context = await rag.search(ctx, {
  namespace: "global",
  query: userPrompt,
  limit: 10,
});

const result = await agent.generateText(
  ctx,
  { threadId },
  {
    prompt: `# Context:\n\n ${context.text}\n\n---\n\n# Question:\n\n"""${userPrompt}\n"""`,
  },
);
```

### 2. Tool-based RAG[​](#2-tool-based-rag "Direct link to 2. Tool-based RAG")

The LLM can intelligently decide when to search for context or add new information by providing a tool to search for context.

* The message history will include the original user prompt and message history.
* After a tool call and response, the message history will include the tool call and response for the LLM to reference.
* The LLM can decide when to search for context or add new information.
* This works well if you want the Agent to be able to dynamically search.

See [ragAsTools.ts](https://github.com/get-convex/agent/blob/main/example/convex/rag/ragAsTools.ts) for the code. The simplest version is:

```
searchContext: createTool({
  description: "Search for context related to this user prompt",
  args: z.object({ query: z.string().describe("Describe the context you're looking for") }),
  handler: async (ctx, { query }) => {
    const context = await rag.search(ctx, { namespace: userId, query });
    return context.text;
  },
}),
```

## Key Differences[​](#key-differences "Direct link to Key Differences")

| Feature            | Basic RAG                    | Tool-based RAG                         |
| ------------------ | ---------------------------- | -------------------------------------- |
| **Context Search** | Always searches              | AI decides when to search              |
| **Adding Context** | Manual via separate function | AI can add context during conversation |
| **Flexibility**    | Simple, predictable          | Intelligent, adaptive                  |
| **Use Case**       | FAQ systems, document search | Dynamic knowledge management           |
| **Predictability** | Defined by code              | AI may query too much or little        |

## Ingesting content[​](#ingesting-content "Direct link to Ingesting content")

On the whole, the RAG component works with text. However, you can turn other files into text, either using parsing tools or asking an LLM to do it.

### Parsing images[​](#parsing-images "Direct link to Parsing images")

Image parsing does oddly well with LLMs. You can use `generateText` to describe and transcribe the image, and then use that description to search for relevant context. And by storing the associated image, you can then pass the original file around once you've retrieved it via searching.

[See an example here](https://github.com/get-convex/rag/blob/main/example/convex/getText.ts#L28-L42).

```
const description = await thread.generateText({
  message: {
    role: "user",
    content: [{ type: "image", data: url, mimeType: blob.type }],
  },
});
```

### Parsing PDFs[​](#parsing-pdfs "Direct link to Parsing PDFs")

For PDF parsing, I suggest using Pdf.js in the browser.

**Why not server-side?**

Opening up the pdf can use hundreds of MB of memory, and requires downloading a big pdfjs bundle - so big it's usually fetched dynamically in practice. You probably wouldn't want to load that bundle on every function call server-side, and you're more limited on memory usage in serverless environments. If the browser already has the file, it's a pretty good environment to do the heavy lifting in (and free!).

There's an example in [the RAG demo](https://github.com/get-convex/rag/blob/main/example/src/pdfUtils.ts#L14), [used in the UI here](https://github.com/get-convex/rag/blob/main/example/src/components/UploadSection.tsx#L51), [with Pdf.js served statically](https://github.com/get-convex/rag/blob/main/example/public/pdf-worker/).

If you really want to do it server-side and don't worry about cost or latency, you can pass it to an LLM, but note it takes a long time for big files.

[See an example here](https://github.com/get-convex/rag/blob/main/example/convex/getText.ts#L50-L65).

### Parsing text files[​](#parsing-text-files "Direct link to Parsing text files")

Generally you can use text files directly, for code or markdown or anything with a natural structure an LLM can understand.

However, to get good embeddings, you can once again use an LLM to translate the text into a more structured format.

[See an example here](https://github.com/get-convex/rag/blob/main/example/convex/getText.ts#L68-L89).

## Examples in Action[​](#examples-in-action "Direct link to Examples in Action")

To see these examples in action, check out the [RAG example](https://github.com/get-convex/rag/blob/main/example/convex/example.ts).

* Adding text, pdf, and image content to the RAG component
* Searching and generating text based on the context.
* Introspecting the context produced by searching.
* Browsing the chunks of documents produced.
* Try out searching globally, per-user, or with custom filters.

Run the example with:

```
git clone https://github.com/get-convex/rag.git
cd rag
npm run setup
npm run example
```

---

# Source: https://docs.convex.dev/agents/rate-limiting.md

# Rate Limiting

Rate limiting is a way to control the rate of requests to your AI agent, preventing abuse and managing API budgets.

To demonstrate using the [Rate Limiter component](https://www.convex.dev/components/rate-limiter), there is an example implementation you can run yourself.

It rate limits the number of messages a user can send in a given time period, as well as the total token usage for a user. When a limit is exceeded, the client can reactively tell the user how long to wait (even if they exceeded the limit in another browser tab!).

For general usage tracking, see [Usage Tracking](/agents/usage-tracking.md).

## Overview[​](#overview "Direct link to Overview")

The rate limiting example demonstrates two types of rate limiting:

1. **Message Rate Limiting**: Prevents users from sending messages too frequently
2. **Token Usage Rate Limiting**: Controls AI model token consumption over time

## Running the Example[​](#running-the-example "Direct link to Running the Example")

```
git clone https://github.com/get-convex/agent.git
cd agent
npm run setup
npm run dev
```

Try sending multiple questions quickly to see the rate limiting in action!

## Rate Limiting Strategy[​](#rate-limiting-strategy "Direct link to Rate Limiting Strategy")

Below we'll go through each configuration. You can also see the full example implementation in [rateLimiting.ts](https://github.com/get-convex/agent/blob/main/example/convex/rate_limiting/rateLimiting.ts).

```
import { MINUTE, RateLimiter, SECOND } from "@convex-dev/rate-limiter";
import { components } from "./_generated/api";

export const rateLimiter = new RateLimiter(components.rateLimiter, {
  sendMessage: {
    kind: "fixed window",
    period: 5 * SECOND,
    rate: 1,
    capacity: 2,
  },
  globalSendMessage: { kind: "token bucket", period: MINUTE, rate: 1_000 },
  tokenUsagePerUser: {
    kind: "token bucket",
    period: MINUTE,
    rate: 2000,
    capacity: 10000,
  },
  globalTokenUsage: { kind: "token bucket", period: MINUTE, rate: 100_000 },
});
```

### 1. Fixed Window Rate Limiting for Messages[​](#1-fixed-window-rate-limiting-for-messages "Direct link to 1. Fixed Window Rate Limiting for Messages")

```
// export const rateLimiter = new RateLimiter(components.rateLimiter, {
sendMessage: { kind: "fixed window", period: 5 * SECOND, rate: 1, capacity: 2 }
```

* Allows 1 message every 5 seconds per user.
* Prevents spam and rapid-fire requests.
* Allows up to a 2 message burst to be sent within 5 seconds via `capacity`, if they had usage leftover from the previous 5 seconds.

Global limit:

```
globalSendMessage: { kind: "token bucket", period: MINUTE, rate: 1_000 },
```

* Allows 1000 messages per minute globally, to stay under the API limit.
* As a token bucket, it will continuously accrue tokens at the rate of 1000 tokens per minute until it caps out at 1000. All available tokens can be used in quick succession.

### 2. Token Bucket Rate Limiting for Token Usage[​](#2-token-bucket-rate-limiting-for-token-usage "Direct link to 2. Token Bucket Rate Limiting for Token Usage")

```
tokenUsage: { kind: "token bucket", period: MINUTE, rate: 1_000 }
globalTokenUsage: { kind: "token bucket", period: MINUTE, rate: 100_000 },
```

* Allows 1000 tokens per minute per user (a userId is provided as the key), and 100k tokens per minute globally.
* Provides burst capacity while controlling overall usage. If it hasn't been used in a while, you can consume all tokens at once. However, you'd then need need to wait for tokens to gradually accrue before making more requests.
* Having a per-user limit is useful to prevent single users from hogging all of the token bandwidth you have available with your LLM provider, while a global limit helps stay under the API limit without throwing an error midway through a potentially long multi-step request.

## How It Works[​](#how-it-works "Direct link to How It Works")

### Step 1: Pre-flight Rate Limit Checks[​](#step-1-pre-flight-rate-limit-checks "Direct link to Step 1: Pre-flight Rate Limit Checks")

Before processing a question, the system:

1. Checks if the user can send another message (frequency limit)
2. Estimates token usage for the question
3. Verifies the user has sufficient token allowance
4. Throws an error if either limit would be exceeded
5. If the rate limits aren't exceeded, the LLM request is made.

See [rateLimiting.ts](https://github.com/get-convex/agent/blob/main/example/convex/rate_limiting/rateLimiting.ts) for the full implementation.

```
// In the mutation that would start generating a message.
await rateLimiter.limit(ctx, "sendMessage", { key: userId, throws: true });
// Also check global limit.
await rateLimiter.limit(ctx, "globalSendMessage", { throws: true });

// A heuristic based on the previous token usage in the thread + the question.
const count = await estimateTokens(ctx, args.threadId, args.question);
// Check token usage, but don't consume the tokens yet.
await rateLimiter.check(ctx, "tokenUsage", {
  key: userId,
  count: estimateTokens(args.question),
  throws: true,
});
// Also check global limit.
await rateLimiter.check(ctx, "globalTokenUsage", {
  count,
  reserve: true,
  throws: true,
});
```

If there is not enough allowance, the rate limiter will throw an error that the client can catch and prompt the user to wait a bit before trying again.

The difference between `limit` and `check` is that `limit` will consume the tokens immediately, while `check` will only check if the limit would be exceeded. We actually mark the tokens as used once the request is complete with the total usage.

### Step 2: Post-generation Usage Tracking[​](#step-2-post-generation-usage-tracking "Direct link to Step 2: Post-generation Usage Tracking")

While rate limiting message sending frequency is a good way to prevent many messages being sent in a short period of time, each message could generate a very long response or use a lot of context tokens. For this we also track token usage as its own rate limit.

After the AI generates a response, we mark the tokens as used using the total usage. We use `reserve: true` to allow a (temporary) negative balance, in case the generation used more tokens than estimated. A "reservation" here means allocating tokens beyond what is allowed. Typically this is done ahead of time, to "reserve" capacity for a big request that can be scheduled in advance. In this case, we're marking capacity that has already been consumed. This prevents future requests from starting until the "debt" is paid off.

When using the Agent component, we can do this in the "usageHandler", which is called after the AI generates a response.

```
import { Agent, type Config } from "@convex-dev/rate-limiter";

const sharedConfig = {
  usageHandler: async (ctx, { usage, userId }) => {
    if (!userId) {
      return;
    }
    // We consume the token usage here, once we know the full usage.
    // This is too late for the first generation, but prevents further requests
    // until we've paid off that debt.
    await rateLimiter.limit(ctx, "tokenUsage", {
      key: userId,
      // You could weight different kinds of tokens differently here.
      count: usage.totalTokens,
      // Reserving the tokens means it won't fail here, but will allow it
      // to go negative, disallowing further requests at the `check` call below.
      reserve: true,
    });
  },
} satisfies Config;

// use it in your agent definitions
const agent = new Agent(components.agent, {
  name,
  languageModel,
  ...sharedConfig,
});
```

The "trick" here is that, while a user can make a request that exceeds the limit for a single request, they then have to wait longer to accrue the tokens for another request. So averaged over time they can't consume more than the rate limit.

This balances pragmatism of trying to prevent requests ahead of time with an estimate, while also rate limiting the actual usage.

## Client-side Handling[​](#client-side-handling "Direct link to Client-side Handling")

See [RateLimiting.tsx](https://github.com/get-convex/agent/blob/main/example/ui/rate_limiting/RateLimiting.tsx) for the client-side code.

While the client isn't the final authority on whether a request should be allowed, it can still show a waiting message while the rate limit is being checked, and an error message when the rate limit is exceeded. This prevents the user from making attempts that are likely to fail.

It makes use of the `useRateLimit` hook to check the rate limits. See the full [Rate Limiting docs here](https://www.convex.dev/components/rate-limiter).

```
import { useRateLimit } from "@convex-dev/rate-limiter/react";
//...
const { status } = useRateLimit(api.example.getRateLimit);
```

In `convex/example.ts` we expose `getRateLimit`:

```
export const { getRateLimit, getServerTime } = rateLimiter.hookAPI<DataModel>(
  "sendMessage",
  { key: (ctx) => getAuthUserId(ctx) },
);
```

Showing a waiting message while the rate limit is being checked:

```
{status && !status.ok && (
    <div className="text-xs text-gray-500 text-center">
    <p>Message sending rate limit exceeded.</p>
    <p>
        Try again after <Countdown ts={status.retryAt} />
    </p>
    </div>
)}
```

Showing an error message when the rate limit is exceeded:

```
import { isRateLimitError } from "@convex-dev/rate-limiter";

// in a button handler
await submitQuestion({ question, threadId }).catch((e) => {
  if (isRateLimitError(e)) {
    toast({
      title: "Rate limit exceeded",
      description: `Rate limit exceeded for ${e.data.name}.
          Try again after ${getRelativeTime(Date.now() + e.data.retryAfter)}`,
    });
  }
});
```

## Token Estimation[​](#token-estimation "Direct link to Token Estimation")

The example includes a simple token estimation function:

```
import { QueryCtx } from "./_generated/server";
import { fetchContextMessages } from "@convex-dev/agent";
import { components } from "./_generated/api";

// This is a rough estimate of the tokens that will be used.
// It's not perfect, but it's a good enough estimate for a pre-generation check.
export async function estimateTokens(
  ctx: QueryCtx,
  threadId: string | undefined,
  question: string,
) {
  // Assume roughly 4 characters per token
  const promptTokens = question.length / 4;
  // Assume a longer non-zero reply
  const estimatedOutputTokens = promptTokens * 3 + 1;
  const latestMessages = await fetchContextMessages(ctx, components.agent, {
    threadId,
    searchText: question,
    contextOptions: { recentMessages: 2 },
  });
  // Our new usage will roughly be the previous tokens + the question.
  // The previous tokens include the tokens for the full message history and
  // output tokens, which will be part of our new history.
  const lastUsageMessage = latestMessages
    .reverse()
    .find((message) => message.usage);
  const lastPromptTokens = lastUsageMessage?.usage?.totalTokens ?? 1;
  return lastPromptTokens + promptTokens + estimatedOutputTokens;
}
```

---

# Source: https://docs.convex.dev/client/react-native.md

# Source: https://docs.convex.dev/quickstart/react-native.md

# React Native Quickstart

Learn how to query data from Convex in a React Native app.

1. Create a React Native app

   Create a React Native app using the `npx create-expo-app` command.

   ```
   npx create-expo-app my-app
   ```

2. Install the Convex client and server library

   To get started, install the `convex` package which provides a convenient interface for working with Convex from a React app.

   Navigate to your app and install `convex`.

   ```
   cd my-app && npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   Create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Reset the Expo project

   If you haven't done so yet, reset the Expo project to get a fresh `app` directory.

   ```
   npm run reset-project
   ```

8. Connect the app to your backend

   In `_layout.tsx`, create a `ConvexReactClient` and pass it to a `ConvexProvider` wrapping your component tree.

   app/\_layout.tsx

   ```
   import { ConvexProvider, ConvexReactClient } from "convex/react";
   import { Stack } from "expo-router";

   const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
     unsavedChangesWarning: false,
   });

   export default function RootLayout() {
     return (
       <ConvexProvider client={convex}>
         <Stack>
           <Stack.Screen name="index" />
         </Stack>
       </ConvexProvider>
     );
   }
   ```

9. Display the data in your app

   In `index.tsx` use the `useQuery` hook to fetch from your `api.tasks.get` API.

   app/index.tsx

   ```
   import { api } from "@/convex/_generated/api";
   import { useQuery } from "convex/react";
   import { Text, View } from "react-native";

   export default function Index() {
     const tasks = useQuery(api.tasks.get);
     return (
       <View
         style={{
           flex: 1,
           justifyContent: "center",
           alignItems: "center",
         }}
       >
         {tasks?.map(({ _id, text }) => <Text key={_id}>{text}</Text>)}
       </View>
     );
   }
   ```

10. Start the app

    Start the app, scan the provided QR code with your phone, and see the serialized list of tasks in the center of the screen.

    ```
    npm start
    ```

React native uses the same library as React web. See the complete [React documentation](/client/react.md).

---

# Source: https://docs.convex.dev/api/classes/react.ConvexReactClient.md

# Class: ConvexReactClient

[react](/api/modules/react.md).ConvexReactClient

A Convex client for use within React.

This loads reactive queries and executes mutations over a WebSocket.

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new ConvexReactClient**(`address`, `options?`)

#### Parameters[​](#parameters "Direct link to Parameters")

| Name       | Type                                                                            | Description                                                                                                                |
| ---------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `address`  | `string`                                                                        | The url of your Convex deployment, often provided by an environment variable. E.g. `https://small-mouse-123.convex.cloud`. |
| `options?` | [`ConvexReactClientOptions`](/api/interfaces/react.ConvexReactClientOptions.md) | See [ConvexReactClientOptions](/api/interfaces/react.ConvexReactClientOptions.md) for a full description.                  |

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:317](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L317)

## Accessors[​](#accessors "Direct link to Accessors")

### url[​](#url "Direct link to url")

• `get` **url**(): `string`

Return the address for this client, useful for creating a new client.

Not guaranteed to match the address with which this client was constructed: it may be canonicalized.

#### Returns[​](#returns "Direct link to Returns")

`string`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[react/client.ts:352](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L352)

***

### logger[​](#logger "Direct link to logger")

• `get` **logger**(): `Logger`

Get the logger for this client.

#### Returns[​](#returns-1 "Direct link to Returns")

`Logger`

The Logger for this client.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[react/client.ts:713](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L713)

## Methods[​](#methods "Direct link to Methods")

### setAuth[​](#setauth "Direct link to setAuth")

▸ **setAuth**(`fetchToken`, `onChange?`): `void`

Set the authentication token to be used for subsequent queries and mutations. `fetchToken` will be called automatically again if a token expires. `fetchToken` should return `null` if the token cannot be retrieved, for example when the user's rights were permanently revoked.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name         | Type                                                           | Description                                                               |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `fetchToken` | [`AuthTokenFetcher`](/api/modules/browser.md#authtokenfetcher) | an async function returning the JWT-encoded OpenID Connect Identity Token |
| `onChange?`  | (`isAuthenticated`: `boolean`) => `void`                       | a callback that will be called when the authentication status changes     |

#### Returns[​](#returns-2 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[react/client.ts:408](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L408)

***

### clearAuth[​](#clearauth "Direct link to clearAuth")

▸ **clearAuth**(): `void`

Clear the current authentication token if set.

#### Returns[​](#returns-3 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[react/client.ts:430](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L430)

***

### watchQuery[​](#watchquery "Direct link to watchQuery")

▸ **watchQuery**<`Query`>(`query`, `...argsAndOptions`): [`Watch`](/api/interfaces/react.Watch.md)<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Construct a new [Watch](/api/interfaces/react.Watch.md) on a Convex query function.

**Most application code should not call this method directly. Instead use the [useQuery](/api/modules/react.md#usequery) hook.**

The act of creating a watch does nothing, a Watch is stateless.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name                | Type                                                                                                                                  | Description                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `query`             | `Query`                                                                                                                               | A [FunctionReference](/api/modules/server.md#functionreference) for the public query to run. |
| `...argsAndOptions` | [`ArgsAndOptions`](/api/modules/server.md#argsandoptions)<`Query`, [`WatchQueryOptions`](/api/interfaces/react.WatchQueryOptions.md)> | -                                                                                            |

#### Returns[​](#returns-4 "Direct link to Returns")

[`Watch`](/api/interfaces/react.Watch.md)<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

The [Watch](/api/interfaces/react.Watch.md) object.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[react/client.ts:463](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L463)

***

### prewarmQuery[​](#prewarmquery "Direct link to prewarmQuery")

▸ **prewarmQuery**<`Query`>(`queryOptions`): `void`

Indicates likely future interest in a query subscription.

The implementation currently immediately subscribes to a query. In the future this method may prioritize some queries over others, fetch the query result without subscribing, or do nothing in slow network connections or high load scenarios.

To use this in a React component, call useQuery() and ignore the return value.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name           | Type                                                                   | Description                                                                                                                                  |
| -------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryOptions` | `ConvexQueryOptions`<`Query`> & { `extendSubscriptionFor?`: `number` } | A query (function reference from an api object) and its args, plus an optional extendSubscriptionFor for how long to subscribe to the query. |

#### Returns[​](#returns-5 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[react/client.ts:539](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L539)

***

### mutation[​](#mutation "Direct link to mutation")

▸ **mutation**<`Mutation`>(`mutation`, `...argsAndOptions`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

Execute a mutation function.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name       | Type                                                                                  |
| ---------- | ------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`> |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name                | Type                                                                                                                                                                                                    | Description                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `mutation`          | `Mutation`                                                                                                                                                                                              | A [FunctionReference](/api/modules/server.md#functionreference) for the public mutation to run. |
| `...argsAndOptions` | [`ArgsAndOptions`](/api/modules/server.md#argsandoptions)<`Mutation`, [`MutationOptions`](/api/interfaces/react.MutationOptions.md)<[`FunctionArgs`](/api/modules/server.md#functionargs)<`Mutation`>>> | -                                                                                               |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

A promise of the mutation's result.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[react/client.ts:618](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L618)

***

### action[​](#action "Direct link to action")

▸ **action**<`Action`>(`action`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

Execute an action function.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name     | Type                                                                                |
| -------- | ----------------------------------------------------------------------------------- |
| `Action` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"action"`> |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name      | Type                                                                    | Description                                                                                   |
| --------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `action`  | `Action`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the public action to run. |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Action`> | An arguments object for the action. If this is omitted, the arguments will be `{}`.           |

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

A promise of the action's result.

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[react/client.ts:639](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L639)

***

### query[​](#query "Direct link to query")

▸ **query**<`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Fetch a query result once.

**Most application code should subscribe to queries instead, using the [useQuery](/api/modules/react.md#usequery) hook.**

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name    | Type                                                                               |
| ------- | ---------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`> |

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name      | Type                                                                   | Description                                                                                  |
| --------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `query`   | `Query`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the public query to run. |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> | An arguments object for the query. If this is omitted, the arguments will be `{}`.           |

#### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

A promise of the query's result.

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[react/client.ts:659](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L659)

***

### connectionState[​](#connectionstate "Direct link to connectionState")

▸ **connectionState**(): [`ConnectionState`](/api/modules/browser.md#connectionstate)

Get the current [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend.

#### Returns[​](#returns-9 "Direct link to Returns")

[`ConnectionState`](/api/modules/browser.md#connectionstate)

The [ConnectionState](/api/modules/browser.md#connectionstate) with the Convex backend.

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[react/client.ts:686](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L686)

***

### subscribeToConnectionState[​](#subscribetoconnectionstate "Direct link to subscribeToConnectionState")

▸ **subscribeToConnectionState**(`cb`): () => `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently. ConnectionState may also *lose* properties in future versions as we figure out what information is most useful. As such this API is considered unstable.

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name | Type                                                                                        |
| ---- | ------------------------------------------------------------------------------------------- |
| `cb` | (`connectionState`: [`ConnectionState`](/api/modules/browser.md#connectionstate)) => `void` |

#### Returns[​](#returns-10 "Direct link to Returns")

`fn`

An unsubscribe function to stop listening.

▸ (): `void`

Subscribe to the [ConnectionState](/api/modules/browser.md#connectionstate) between the client and the Convex backend, calling a callback each time it changes.

Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently. ConnectionState may also *lose* properties in future versions as we figure out what information is most useful. As such this API is considered unstable.

##### Returns[​](#returns-11 "Direct link to Returns")

`void`

An unsubscribe function to stop listening.

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[react/client.ts:702](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L702)

***

### close[​](#close "Direct link to close")

▸ **close**(): `Promise`<`void`>

Close any network handles associated with this client and stop all subscriptions.

Call this method when you're done with a [ConvexReactClient](/api/classes/react.ConvexReactClient.md) to dispose of its sockets and resources.

#### Returns[​](#returns-12 "Direct link to Returns")

`Promise`<`void`>

A `Promise` fulfilled when the connection has been completely closed.

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[react/client.ts:725](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L725)

---

# Source: https://docs.convex.dev/api/interfaces/react.ConvexReactClientOptions.md

# Interface: ConvexReactClientOptions

[react](/api/modules/react.md).ConvexReactClientOptions

Options for [ConvexReactClient](/api/classes/react.ConvexReactClient.md).

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`BaseConvexClientOptions`](/api/interfaces/browser.BaseConvexClientOptions.md)

  ↳ **`ConvexReactClientOptions`**

## Properties[​](#properties "Direct link to Properties")

### unsavedChangesWarning[​](#unsavedchangeswarning "Direct link to unsavedChangesWarning")

• `Optional` **unsavedChangesWarning**: `boolean`

Whether to prompt the user if they have unsaved changes pending when navigating away or closing a web page.

This is only possible when the `window` object exists, i.e. in a browser.

The default value is `true` in browsers.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[unsavedChangesWarning](/api/interfaces/browser.BaseConvexClientOptions.md#unsavedchangeswarning)

#### Defined in[​](#defined-in "Direct link to Defined in")

[browser/sync/client.ts:69](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L69)

***

### webSocketConstructor[​](#websocketconstructor "Direct link to webSocketConstructor")

• `Optional` **webSocketConstructor**: `Object`

#### Call signature[​](#call-signature "Direct link to Call signature")

• **new webSocketConstructor**(`url`, `protocols?`): `WebSocket`

Specifies an alternate [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) constructor to use for client communication with the Convex cloud. The default behavior is to use `WebSocket` from the global environment.

##### Parameters[​](#parameters "Direct link to Parameters")

| Name         | Type                    |
| ------------ | ----------------------- |
| `url`        | `string` \| `URL`       |
| `protocols?` | `string` \| `string`\[] |

##### Returns[​](#returns "Direct link to Returns")

`WebSocket`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name         | Type        |
| ------------ | ----------- |
| `prototype`  | `WebSocket` |
| `CONNECTING` | `0`         |
| `OPEN`       | `1`         |
| `CLOSING`    | `2`         |
| `CLOSED`     | `3`         |

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[webSocketConstructor](/api/interfaces/browser.BaseConvexClientOptions.md#websocketconstructor)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[browser/sync/client.ts:76](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L76)

***

### verbose[​](#verbose "Direct link to verbose")

• `Optional` **verbose**: `boolean`

Adds additional logging for debugging purposes.

The default value is `false`.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[verbose](/api/interfaces/browser.BaseConvexClientOptions.md#verbose)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[browser/sync/client.ts:82](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L82)

***

### logger[​](#logger "Direct link to logger")

• `Optional` **logger**: `boolean` | `Logger`

A logger, `true`, or `false`. If not provided or `true`, logs to the console. If `false`, logs are not printed anywhere.

You can construct your own logger to customize logging to log elsewhere. A logger is an object with 4 methods: log(), warn(), error(), and logVerbose(). These methods can receive multiple arguments of any types, like console.log().

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[logger](/api/interfaces/browser.BaseConvexClientOptions.md#logger)

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[browser/sync/client.ts:91](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L91)

***

### reportDebugInfoToConvex[​](#reportdebuginfotoconvex "Direct link to reportDebugInfoToConvex")

• `Optional` **reportDebugInfoToConvex**: `boolean`

Sends additional metrics to Convex for debugging purposes.

The default value is `false`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[reportDebugInfoToConvex](/api/interfaces/browser.BaseConvexClientOptions.md#reportdebuginfotoconvex)

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[browser/sync/client.ts:97](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L97)

***

### onServerDisconnectError[​](#onserverdisconnecterror "Direct link to onServerDisconnectError")

• `Optional` **onServerDisconnectError**: (`message`: `string`) => `void`

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

▸ (`message`): `void`

This API is experimental: it may change or disappear.

A function to call on receiving abnormal WebSocket close messages from the connected Convex deployment. The content of these messages is not stable, it is an implementation detail that may change.

Consider this API an observability stopgap until higher level codes with recommendations on what to do are available, which could be a more stable interface instead of `string`.

Check `connectionState` for more quantitative metrics about connection status.

##### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name      | Type     |
| --------- | -------- |
| `message` | `string` |

##### Returns[​](#returns-1 "Direct link to Returns")

`void`

#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[onServerDisconnectError](/api/interfaces/browser.BaseConvexClientOptions.md#onserverdisconnecterror)

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[browser/sync/client.ts:111](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L111)

***

### skipConvexDeploymentUrlCheck[​](#skipconvexdeploymenturlcheck "Direct link to skipConvexDeploymentUrlCheck")

• `Optional` **skipConvexDeploymentUrlCheck**: `boolean`

Skip validating that the Convex deployment URL looks like `https://happy-animal-123.convex.cloud` or localhost.

This can be useful if running a self-hosted Convex backend that uses a different URL.

The default value is `false`

#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[skipConvexDeploymentUrlCheck](/api/interfaces/browser.BaseConvexClientOptions.md#skipconvexdeploymenturlcheck)

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[browser/sync/client.ts:121](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L121)

***

### authRefreshTokenLeewaySeconds[​](#authrefreshtokenleewayseconds "Direct link to authRefreshTokenLeewaySeconds")

• `Optional` **authRefreshTokenLeewaySeconds**: `number`

If using auth, the number of seconds before a token expires that we should refresh it.

The default value is `2`.

#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[authRefreshTokenLeewaySeconds](/api/interfaces/browser.BaseConvexClientOptions.md#authrefreshtokenleewayseconds)

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[browser/sync/client.ts:127](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L127)

***

### expectAuth[​](#expectauth "Direct link to expectAuth")

• `Optional` **expectAuth**: `boolean`

This API is experimental: it may change or disappear.

Whether query, mutation, and action requests should be held back until the first auth token can be sent.

Opting into this behavior works well for pages that should only be viewed by authenticated clients.

Defaults to false, not waiting for an auth token.

#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")

[BaseConvexClientOptions](/api/interfaces/browser.BaseConvexClientOptions.md).[expectAuth](/api/interfaces/browser.BaseConvexClientOptions.md#expectauth)

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[browser/sync/client.ts:139](https://github.com/get-convex/convex-js/blob/main/src/browser/sync/client.ts#L139)

---

# Source: https://docs.convex.dev/api/interfaces/react.MutationOptions.md

# Interface: MutationOptions\<Args>

[react](/api/modules/react.md).MutationOptions

Options for [mutation](/api/classes/react.ConvexReactClient.md#mutation).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name   | Type                                                                |
| ------ | ------------------------------------------------------------------- |
| `Args` | extends `Record`<`string`, [`Value`](/api/modules/values.md#value)> |

## Properties[​](#properties "Direct link to Properties")

### optimisticUpdate[​](#optimisticupdate "Direct link to optimisticUpdate")

• `Optional` **optimisticUpdate**: [`OptimisticUpdate`](/api/modules/browser.md#optimisticupdate)<`Args`>

An optimistic update to apply along with this mutation.

An optimistic update locally updates queries while a mutation is pending. Once the mutation completes, the update will be rolled back.

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:282](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L282)

---

# Source: https://docs.convex.dev/api/interfaces/react.ReactAction.md

# Interface: ReactAction\<Action>

[react](/api/modules/react.md).ReactAction

An interface to execute a Convex action on the server.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name     | Type                                                                                |
| -------- | ----------------------------------------------------------------------------------- |
| `Action` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"action"`> |

## Callable[​](#callable "Direct link to Callable")

### ReactAction[​](#reactaction "Direct link to ReactAction")

▸ **ReactAction**(`...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

Execute the function on the server, returning a `Promise` of its return value.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                    | Description                                          |
| --------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Action`> | Arguments for the function to pass up to the server. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

The return value of the server-side function call.

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:136](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L136)

---

# Source: https://docs.convex.dev/api/interfaces/react.ReactMutation.md

# Interface: ReactMutation\<Mutation>

[react](/api/modules/react.md).ReactMutation

An interface to execute a Convex mutation function on the server.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name       | Type                                                                                  |
| ---------- | ------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`> |

## Callable[​](#callable "Direct link to Callable")

### ReactMutation[​](#reactmutation "Direct link to ReactMutation")

▸ **ReactMutation**(`...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

Execute the mutation on the server, returning a `Promise` of its return value.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                      | Description                                          |
| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Mutation`> | Arguments for the mutation to pass up to the server. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

The return value of the server-side function call.

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:64](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L64)

## Methods[​](#methods "Direct link to Methods")

### withOptimisticUpdate[​](#withoptimisticupdate "Direct link to withOptimisticUpdate")

▸ **withOptimisticUpdate**<`T`>(`optimisticUpdate`): [`ReactMutation`](/api/interfaces/react.ReactMutation.md)<`Mutation`>

Define an optimistic update to apply as part of this mutation.

This is a temporary update to the local query results to facilitate a fast, interactive UI. It enables query results to update before a mutation executed on the server.

When the mutation is invoked, the optimistic update will be applied.

Optimistic updates can also be used to temporarily remove queries from the client and create loading experiences until a mutation completes and the new query results are synced.

The update will be automatically rolled back when the mutation is fully completed and queries have been updated.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name | Type                                                                                                                                      |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `T`  | extends [`OptimisticUpdate`](/api/modules/browser.md#optimisticupdate)<[`FunctionArgs`](/api/modules/server.md#functionargs)<`Mutation`>> |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name               | Type                                                                                                    | Description                     |
| ------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `optimisticUpdate` | `T` & `ReturnType`<`T`> extends `Promise`<`any`> ? `"Optimistic update handlers must be synchronous"` : | The optimistic update to apply. |

#### Returns[​](#returns-1 "Direct link to Returns")

[`ReactMutation`](/api/interfaces/react.ReactMutation.md)<`Mutation`>

A new `ReactMutation` with the update configured.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[react/client.ts:87](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L87)

---

# Source: https://docs.convex.dev/api/interfaces/react.Watch.md

# Interface: Watch\<T>

[react](/api/modules/react.md).Watch

A watch on the output of a Convex query function.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name |
| ---- |
| `T`  |

## Methods[​](#methods "Direct link to Methods")

### onUpdate[​](#onupdate "Direct link to onUpdate")

▸ **onUpdate**(`callback`): () => `void`

Initiate a watch on the output of a query.

This will subscribe to this query and call the callback whenever the query result changes.

**Important: If the client is already subscribed to this query with the same arguments this callback will not be invoked until the query result is updated.** To get the current, local result call [localQueryResult](/api/interfaces/react.Watch.md#localqueryresult).

#### Parameters[​](#parameters "Direct link to Parameters")

| Name       | Type         | Description                                                |
| ---------- | ------------ | ---------------------------------------------------------- |
| `callback` | () => `void` | Function that is called whenever the query result changes. |

#### Returns[​](#returns "Direct link to Returns")

`fn`

* A function that disposes of the subscription.

▸ (): `void`

Initiate a watch on the output of a query.

This will subscribe to this query and call the callback whenever the query result changes.

**Important: If the client is already subscribed to this query with the same arguments this callback will not be invoked until the query result is updated.** To get the current, local result call [localQueryResult](/api/interfaces/react.Watch.md#localqueryresult).

##### Returns[​](#returns-1 "Direct link to Returns")

`void`

* A function that disposes of the subscription.

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:170](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L170)

***

### localQueryResult[​](#localqueryresult "Direct link to localQueryResult")

▸ **localQueryResult**(): `undefined` | `T`

Get the current result of a query.

This will only return a result if we're already subscribed to the query and have received a result from the server or the query value has been set optimistically.

**`Throws`**

An error if the query encountered an error on the server.

#### Returns[​](#returns-2 "Direct link to Returns")

`undefined` | `T`

The result of the query or `undefined` if it isn't known.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[react/client.ts:182](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L182)

***

### journal[​](#journal "Direct link to journal")

▸ **journal**(): `undefined` | [`QueryJournal`](/api/modules/browser.md#queryjournal)

Get the current [QueryJournal](/api/modules/browser.md#queryjournal) for this query.

If we have not yet received a result for this query, this will be `undefined`.

#### Returns[​](#returns-3 "Direct link to Returns")

`undefined` | [`QueryJournal`](/api/modules/browser.md#queryjournal)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[react/client.ts:194](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L194)

---

# Source: https://docs.convex.dev/api/interfaces/react.WatchQueryOptions.md

# Interface: WatchQueryOptions

[react](/api/modules/react.md).WatchQueryOptions

Options for [watchQuery](/api/classes/react.ConvexReactClient.md#watchquery).

## Properties[​](#properties "Direct link to Properties")

### journal[​](#journal "Direct link to journal")

• `Optional` **journal**: [`QueryJournal`](/api/modules/browser.md#queryjournal)

An (optional) journal produced from a previous execution of this query function.

If there is an existing subscription to a query function with the same name and arguments, this journal will have no effect.

#### Defined in[​](#defined-in "Direct link to Defined in")

[react/client.ts:241](https://github.com/get-convex/convex-js/blob/main/src/react/client.ts#L241)

---

# Source: https://docs.convex.dev/api/modules/react.md

# Source: https://docs.convex.dev/client/react.md

# Source: https://docs.convex.dev/quickstart/react.md

# React Quickstart

[YouTube video player](https://www.youtube.com/embed/4MgsvjMb59Q)

To get setup quickly with Convex and React run

**`npm create convex@latest`**

**``**

or follow the guide below.

***

Learn how to query data from Convex in a React app using Vite and

TypeScript

1. Create a React app

   Create a React app using the `create vite` command.

   ```
   npm create vite@latest my-app -- --template react-ts
   ```

2. Install the Convex client and server library

   To get started, install the `convex` package which provides a convenient interface for working with Convex from a React app.

   Navigate to your app directory and install `convex`.

   ```
   cd my-app && npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. (optional) Define a schema

   Add a new file `schema.ts` in the `convex/` folder with a description of your data.

   This will declare the types of your data for optional typechecking with TypeScript, and it will be also enforced at runtime.

   Alternatively remove the line `'plugin:@typescript-eslint/recommended-requiring-type-checking',` from the `.eslintrc.cjs` file to lower the type checking strictness.

   convex/schema.ts

   ```
   import { defineSchema, defineTable } from "convex/server";
   import { v } from "convex/values";

   export default defineSchema({
     tasks: defineTable({
       text: v.string(),
       isCompleted: v.boolean(),
     }),
   });
   ```

7. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   TS

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

8. Connect the app to your backend

   In `src/main.tsx`, create a `ConvexReactClient` and pass it to a `ConvexProvider` wrapping your app.

   src/main.tsx

   TS

   ```
   import React from "react";
   import ReactDOM from "react-dom/client";
   import App from "./App";
   import "./index.css";
   import { ConvexProvider, ConvexReactClient } from "convex/react";

   const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

   ReactDOM.createRoot(document.getElementById("root")!).render(
     <React.StrictMode>
       <ConvexProvider client={convex}>
         <App />
       </ConvexProvider>
     </React.StrictMode>,
   );
   ```

9. Display the data in your app

   In `src/App.tsx`, use the `useQuery` hook to fetch from your `api.tasks.get` API function and display the data.

   src/App.tsx

   TS

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

   function App() {
     const tasks = useQuery(api.tasks.get);
     return (
       <div className="App">
         {tasks?.map(({ _id, text }) => <div key={_id}>{text}</div>)}
       </div>
     );
   }

   export default App;
   ```

10. Start the app

    Start the app, open <http://localhost:5173/> in a browser, and see the list of tasks.

    ```
    npm run dev
    ```

See the complete [React documentation](/client/react.md).

---

# Source: https://docs.convex.dev/api/modules/react_auth0.md

# Module: react-auth0

React login component for use with Auth0.

## Functions[​](#functions "Direct link to Functions")

### ConvexProviderWithAuth0[​](#convexproviderwithauth0 "Direct link to ConvexProviderWithAuth0")

▸ **ConvexProviderWithAuth0**(`«destructured»`): `Element`

A wrapper React component which provides a [ConvexReactClient](/api/classes/react.ConvexReactClient.md) authenticated with Auth0.

It must be wrapped by a configured `Auth0Provider` from `@auth0/auth0-react`.

See [Convex Auth0](https://docs.convex.dev/auth/auth0) on how to set up Convex with Auth0.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type                 |
| ---------------- | -------------------- |
| `«destructured»` | `Object`             |
| › `children`     | `ReactNode`          |
| › `client`       | `IConvexReactClient` |

#### Returns[​](#returns "Direct link to Returns")

`Element`

#### Defined in[​](#defined-in "Direct link to Defined in")

[react-auth0/ConvexProviderWithAuth0.tsx:26](https://github.com/get-convex/convex-js/blob/main/src/react-auth0/ConvexProviderWithAuth0.tsx#L26)

---

# Source: https://docs.convex.dev/api/modules/react_clerk.md

# Module: react-clerk

React login component for use with Clerk.

## Functions[​](#functions "Direct link to Functions")

### ConvexProviderWithClerk[​](#convexproviderwithclerk "Direct link to ConvexProviderWithClerk")

▸ **ConvexProviderWithClerk**(`«destructured»`): `Element`

A wrapper React component which provides a [ConvexReactClient](/api/classes/react.ConvexReactClient.md) authenticated with Clerk.

It must be wrapped by a configured `ClerkProvider`, from `@clerk/clerk-react`, `@clerk/clerk-expo`, `@clerk/nextjs` or another React-based Clerk client library and have the corresponding `useAuth` hook passed in.

See [Convex Clerk](https://docs.convex.dev/auth/clerk) on how to set up Convex with Clerk.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type                 |
| ---------------- | -------------------- |
| `«destructured»` | `Object`             |
| › `children`     | `ReactNode`          |
| › `client`       | `IConvexReactClient` |
| › `useAuth`      | `UseAuth`            |

#### Returns[​](#returns "Direct link to Returns")

`Element`

#### Defined in[​](#defined-in "Direct link to Defined in")

[react-clerk/ConvexProviderWithClerk.tsx:41](https://github.com/get-convex/convex-js/blob/main/src/react-clerk/ConvexProviderWithClerk.tsx#L41)

---

# Source: https://docs.convex.dev/database/reading-data.md

# Reading Data

[Query](/functions/query-functions.md) and [mutation](/functions/mutation-functions.md) functions can read data from database tables using *document ids* and *document queries*.

## Reading a single document[​](#reading-a-single-document "Direct link to Reading a single document")

Given a single document's id you can read its data with the [`db.get`](/api/interfaces/server.GenericDatabaseReader.md#get) method:

convex/tasks.ts

TS

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

export const getTask = query({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    const task = await ctx.db.get("tasks", args.taskId);
    // do something with `task`
  },
});
```

**Note**: You should use the `v.id` validator like in the example above to make sure you are not exposing data from tables other than the ones you intended.

## Querying documents[​](#querying-documents "Direct link to Querying documents")

Document queries always begin by choosing the table to query with the [`db.query`](/api/interfaces/server.GenericDatabaseReader.md#query) method:

convex/tasks.ts

TS

```
import { query } from "./_generated/server";

export const listTasks = query({
  args: {},
  handler: async (ctx) => {
    const tasks = await ctx.db.query("tasks").collect();
    // do something with `tasks`
  },
});
```

Then you can:

1. filter
2. order
3. and `await` the results

We'll see how this works in the examples below.

## Filtering your query[​](#filtering-your-query "Direct link to Filtering your query")

The best way to filter in Convex is to use indexes. Indexes build a special internal structure in your database to speed up lookups.

There are two steps to using indexes:

1. Define the index in your `convex/schema.ts` file.
2. Query via the `withIndex()` syntax.

### 1. Define the index[​](#1-define-the-index "Direct link to 1. Define the index")

If you aren't familiar with how to create a Convex schema, read the [schema doc](/database/schemas.md).

Let’s assume you’re building a chat app and want to get all messages in a particular channel. You can define a new index called `by_channel` on the `messages` table by using the `.index()` method in your schema.

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

// Define a messages table with an index.
export default defineSchema({
  messages: defineTable({
    channel: v.id("channels"),
    body: v.string(),
    user: v.id("users"),
  }).index("by_channel", ["channel"]),
});
```

### 2. Filter a query with an index[​](#2-filter-a-query-with-an-index "Direct link to 2. Filter a query with an index")

In your query function, you can now filter your `messages` table by using the `by_channel` index.

```
const messages = await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channel", channel))
  .collect();
```

In Convex, you must explicitly use the `withIndex()` syntax to ensure your database uses the index. This differs from a more traditional SQL database, where the database implicitly chooses to use an index based on heuristics. The Convex approach leads to fewer surprises in the long run.

You can create an index across multiple fields at once, query a specific range of data, and change the order of your query result. [Read the complete index documentation](/database/reading-data/indexes/.md) to learn more.

Convex also supports a slower filtering mechanism that effectively loops through the table to match the filter. This can be useful if you know your table will be small (low thousands of rows), you're prototyping, or you want to filter an index query further. You can read more about filters [here](/database/reading-data/filters.md).

## Ordering[​](#ordering "Direct link to Ordering")

By default Convex always returns documents ordered by [`_creationTime`](/database/types.md#system-fields).

You can use [`.order("asc" | "desc")`](/api/interfaces/server.Query.md#order) to pick whether the order is ascending or descending. If the order isn't specified, it defaults to ascending.

```
// Get all messages, oldest to newest.
const messages = await ctx.db.query("messages").order("asc").collect();
```

```
// Get all messages, newest to oldest.
const messages = await ctx.db.query("messages").order("desc").collect();
```

If you need to sort on a field other than `_creationTime` and your document query returns a small number of documents (on the order of hundreds rather than thousands of documents), consider sorting in JavaScript:

```
// Get top 10 most liked messages, assuming messages is a fairly small table:
const messages = await ctx.db.query("messages").collect();
const topTenMostLikedMessages = recentMessages
  .sort((a, b) => b.likes - a.likes)
  .slice(0, 10);
```

For document queries that return larger numbers of documents, you'll want to use an [index](/database/reading-data/indexes/.md) to improve the performance. Document queries that use indexes will be [ordered based on the columns in the index](/database/reading-data/indexes/.md#sorting-with-indexes) and can avoid slow table scans.

```
// Get the top 20 most liked messages of all time, using the "by_likes" index.
const messages = await ctx.db
  .query("messages")
  .withIndex("by_likes")
  .order("desc")
  .take(20);
```

See [Limits](/database/reading-data/indexes/.md#limits) for details.

### Ordering of different types of values[​](#ordering-of-different-types-of-values "Direct link to Ordering of different types of values")

A single field can have values of any [Convex type](/database/types.md). When there are values of different types in an indexed field, their ascending order is as follows:

No value set (`undefined`) < Null (`null`) < Int64 (`bigint`) < Float64 (`number`) < Boolean (`boolean`) < String (`string`) < Bytes (`ArrayBuffer`) < Array (`Array`) < Object (`Object`)

The same ordering is used by the filtering comparison operators `q.lt()`, `q.lte()`, `q.gt()` and `q.gte()`.

## Retrieving results[​](#retrieving-results "Direct link to Retrieving results")

Most of our previous examples have ended the document query with the [`.collect()`](/api/interfaces/server.Query.md#collect) method, which returns all the documents that match your filters. Here are the other options for retrieving results.

### Taking `n` results[​](#taking-n-results "Direct link to taking-n-results")

[`.take(n)`](/api/interfaces/server.Query.md#take) selects only the first `n` results that match your query.

```
const users = await ctx.db.query("users").take(5);
```

### Finding the first result[​](#finding-the-first-result "Direct link to Finding the first result")

[`.first()`](/api/interfaces/server.Query.md#first) selects the first document that matches your query and returns `null` if no documents were found.

```
// We expect only one user with that email address.
const userOrNull = await ctx.db
  .query("users")
  .withIndex("by_email", (q) => q.eq("email", "test@example.com"))
  .first();
```

### Using a unique result[​](#using-a-unique-result "Direct link to Using a unique result")

[`.unique()`](/api/interfaces/server.Query.md#unique) selects the single document from your query or returns `null` if no documents were found. If there are multiple results it will throw an exception.

```
// Our counter table only has one document.
const counterOrNull = await ctx.db.query("counter").unique();
```

### Loading a page of results[​](#loading-a-page-of-results "Direct link to Loading a page of results")

[`.paginate(opts)`](/api/interfaces/server.OrderedQuery.md#paginate) loads a page of results and returns a [`Cursor`](/api/modules/server.md#cursor) for loading additional results.

See [Paginated Queries](/database/pagination.md) to learn more.

## More complex queries[​](#more-complex-queries "Direct link to More complex queries")

Convex prefers to have a few, simple ways to walk through and select documents from tables. In Convex, there is no specific query language for complex logic like a join, an aggregation, or a group by.

Instead, you can write the complex logic in JavaScript! Convex guarantees that the results will be consistent.

### Join[​](#join "Direct link to Join")

Table join might look like:

convex/events.ts

TS

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

export const eventAttendees = query({
  args: { eventId: v.id("events") },
  handler: async (ctx, args) => {
    const event = await ctx.db.get("events", args.eventId);
    return Promise.all(
      (event?.attendeeIds ?? []).map((userId) => ctx.db.get("users", userId)),
    );
  },
});
```

### Aggregation[​](#aggregation "Direct link to Aggregation")

Here's an example of computing an average:

convex/purchases.ts

TS

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

export const averagePurchasePrice = query({
  args: { email: v.string() },
  handler: async (ctx, args) => {
    const userPurchases = await ctx.db
      .query("purchases")
      .withIndex("by_buyer", (q) => q.eq("buyer", args.email))
      .collect();
    const sum = userPurchases.reduce((a, { value: b }) => a + b, 0);
    return sum / userPurchases.length;
  },
});
```

> If you need more scalable aggregate options (for example to handle frequent updates or large tables), consider using the [Sharded Counter](https://www.convex.dev/components/sharded-counter) or [Aggregate](https://www.convex.dev/components/aggregate) components. These components can help you handle high-throughput counters, sums, or computations without looping through the whole table.

### Group by[​](#group-by "Direct link to Group by")

Here's an example of grouping and counting:

convex/purchases.ts

TS

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

export const numPurchasesPerBuyer = query({
  args: { email: v.string() },
  handler: async (ctx, args) => {
    const userPurchases = await ctx.db.query("purchases").collect();

    return userPurchases.reduce(
      (counts, { buyer }) => ({
        ...counts,
        [buyer]: counts[buyer] ?? 0 + 1,
      }),
      {} as Record<string, number>,
    );
  },
});
```

## Explore the syntax on the dashboard[​](#explore-the-syntax-on-the-dashboard "Direct link to Explore the syntax on the dashboard")

You can try out the syntax described above directly from the dashboard by [writing a custom test query](/dashboard/deployments/data.md#writing-custom-queries).

---

# Source: https://docs.convex.dev/realtime.md

# Realtime

Turns out Convex is automatically realtime! You don’t have to do anything special if you are already using [query functions](/functions/query-functions.md), [database](/database.md), and [client libraries](/client/react.md) in your app. Convex tracks the dependencies to your query functions, including database changes, and triggers the subscription in the client libraries.

![Convex is automatically reactive and realtime](/assets/images/realtime-3197272a21b075792f6ac922af228378.gif)

Aside from building a highly interactive app with ease, there are other benefits to the realtime architecture of Convex:

## Automatic caching[​](#automatic-caching "Direct link to Automatic caching")

Convex automatically caches the result of your query functions so that future calls just read from the cache. The cache is updated if the data ever changes. You don't get charged for database bandwidth for cached reads.

This requires no work or bookkeeping from you.

## Consistent data across your app[​](#consistent-data-across-your-app "Direct link to Consistent data across your app")

Every client subscription gets updated simultaneously to the same snapshot of the database. Your app always displays the most consistent view of your data.

This avoids bugs like increasing the number of items in the shopping cart and not showing that an item is sold out.

## Learn more[​](#learn-more "Direct link to Learn more")

Learn how to work with realtime and reactive queries in Convex on [Stack](https://stack.convex.dev/tag/Reactivity).

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/quickstart/remix.md

# Remix Quickstart

Learn how to query data from Convex in a Remix app.

1. Create a Remix site

   Create a Remix site using the `npx create-remix@latest` command.

   <br />

   ```
   npx create-remix@latest my-remix-app
   ```

2. Install the Convex library

   To get started, install the `convex` package.

   ```
   cd my-remix-app && npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   Create a `sampleData.jsonl` file at the root of you app and fill it with the sample data given.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data you just created in `sampleData.jsonl` into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Wire up the ConvexProvider

   Modify `app/root.tsx` to set up the Convex client there to make it available on every page of your app.

   app/root.tsx

   ```
   import {
     Links,
     Meta,
     Outlet,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "@remix-run/react";
   import { ConvexProvider, ConvexReactClient } from "convex/react";
   import { useState } from "react";

   export async function loader() {
     const CONVEX_URL = process.env["CONVEX_URL"]!;
     return { ENV: { CONVEX_URL } };
   }

   export function Layout({ children }: { children: React.ReactNode }) {
     const { ENV } = useLoaderData<typeof loader>();
     const [convex] = useState(() => new ConvexReactClient(ENV.CONVEX_URL));
     return (
       <html lang="en">
         <head>
           <meta charSet="utf-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1" />
           <Meta />
           <Links />
         </head>
         <body>
           <ConvexProvider client={convex}>{children}</ConvexProvider>
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }

   export default function App() {
     return <Outlet />;
   }
   ```

8. Display the data in your app

   In `app/routes/_index.tsx` use `useQuery` to subscribe your `api.tasks.get` API function.

   app/routes/\_index.tsx

   ```
   import type { MetaFunction } from "@remix-run/node";
   import { api } from "convex/_generated/api";
   import { useQuery } from "convex/react";

   export const meta: MetaFunction = () => {
     return [
       { title: "New Remix App" },
       { name: "description", content: "Welcome to Remix!" },
     ];
   };

   export default function Index() {
     const tasks = useQuery(api.tasks.get);
     return (
       <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.8" }}>
         <h1>Welcome to Remix</h1>
         {tasks === undefined
           ? "loading..."
           : tasks.map(({ _id, text }) => <div key={_id}>{text}</div>)}
       </div>
     );
   }
   ```

9. Start the app

   Start the app, open <http://localhost:5173> in a browser, and see the list of tasks.

   ```
   npm run dev
   ```

Remix uses the React web library. See the complete [React documentation](/client/react.md).

---

# Source: https://docs.convex.dev/deployment-api/rotate-webhook-secret.md

# Rotate webhook log stream secret

```
POST 
/rotate_webhook_secret/:id
```

Rotate the secret for the webhook log stream.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/functions/runtimes.md

# Runtimes

Convex functions can run in two runtimes:

* Default [Convex runtime](#default-convex-runtime)
* Opt-in [Node.js runtime](#nodejs-runtime)

## Default Convex runtime[​](#default-convex-runtime "Direct link to Default Convex runtime")

All Convex backend functions are written in JavaScript or TypeScript. By default all functions run in a custom JavaScript runtime very similar to the [Cloudflare Workers runtime](https://blog.cloudflare.com/cloud-computing-without-containers/) with access to most [web standard globals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects).

The default runtime has many advantages including:

* **No cold starts**. The runtime is always up, and ready to handle any function at a moments notice.
* **Latest web JavaScript standards**. The runtime is based on V8 that also powers Google Chrome. This ensures it provides an interface very similar to your frontend code, allowing further simplification to your code.
* **Low overhead access to your data**. The runtime is designed to have low overhead access to your data via query & mutation functions, allowing you to access your database via a simple [JavaScript interface](/database/reading-data/.md).

### Supported APIs[​](#supported-apis "Direct link to Supported APIs")

The default runtime supports most npm libraries that work in the browser, [Deno](https://deno.com/), and [Cloudflare workers](https://developers.cloudflare.com/workers/). If your library isn't supported, you can use an action with the [Node.js runtime](#nodejs-runtime), or reach out in [Discord](https://convex.dev/community). We are improving support all the time.

#### Network APIs[​](#network-apis "Direct link to Network APIs")

* [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
* [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event)
* [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
* [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) — in [Actions](#actions) only
* [File](https://developer.mozilla.org/en-US/docs/Web/API/File)
* [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
* [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
* [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)
* [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)

#### Encoding APIs[​](#encoding-apis "Direct link to Encoding APIs")

* [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
* [TextEncoder](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
* [atob](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/atob)
* [btoa](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/btoa)

#### Web Stream APIs[​](#web-stream-apis "Direct link to Web Stream APIs")

* [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
* [ReadableStreamBYOBReader](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader)
* [ReadableStreamDefaultReader](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader)
* [TransformStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
* [WritableStream](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
* [WritableStreamDefaultWriter](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter)

#### Web Crypto APIs[​](#web-crypto-apis "Direct link to Web Crypto APIs")

* [crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
* [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
* [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)

### Restrictions on queries and mutations[​](#restrictions-on-queries-and-mutations "Direct link to Restrictions on queries and mutations")

Query and mutation functions are further **restricted by the runtime to be [deterministic](https://en.wikipedia.org/wiki/Deterministic_algorithm)**. This allows Convex to automatically retry them by the system as necessary.

Determinism means that no matter how many times your function is run, as long as it is given the same arguments, it will have identical side effects and return the same value.

You don't have to think all that much about maintaining these properties of determinism when you write your Convex functions. Convex will provide helpful error messages as you go, so you can't *accidentally* do something forbidden.

#### Using randomness and time in queries and mutations[​](#using-randomness-and-time-in-queries-and-mutations "Direct link to Using randomness and time in queries and mutations")

Convex provides a "seeded" strong pseudo-random number generator at `Math.random()` so that it can guarantee the determinism of your function. The random number generator's seed is an implicit parameter to your function. Multiple calls to `Math.random()` in one function call will return different random values. Note that Convex does not reevaluate the JavaScript modules on every function run, so a call to `Math.random()` stored in a global variable will not change between function runs.

To ensure the logic within your function is reproducible, the system time used globally (outside of any function) is "frozen" at deploy time, while the system time during Convex function execution is "frozen" when the function begins. `Date.now()` will return the same result for the entirety of your function's execution. For example,

```
const globalRand = Math.random(); // `globalRand` does not change between runs.
const globalNow = Date.now(); // `globalNow` is the time when Convex functions were deployed.

export const updateSomething = mutation({
  args: {},
  handler: () => {
    const now1 = Date.now(); // `now1` is the time when the function execution started.
    const rand1 = Math.random(); // `rand1` has a new value for each function run.
    // implementation
    const now2 = Date.now(); // `now2` === `now1`
    const rand2 = Math.random(); // `rand1` !== `rand2`
  },
});
```

### Actions[​](#actions "Direct link to Actions")

Actions are unrestricted by the same rules of determinism as query and mutation functions. Notably actions are allowed to call third-party HTTP endpoints via the browser-standard [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) function.

By default actions also run in Convex’s custom JavaScript runtime with all of its advantages including no cold starts and a browser-like API environment. They can also live in the same file as your query and mutation functions.

## Node.js runtime[​](#nodejs-runtime "Direct link to Node.js runtime")

Some JavaScript and TypeScript libraries use features that are not included in the default Convex runtime. Convex actions provide an escape hatch to [Node.js](https://nodejs.org/en/about) via the `"use node"` directive at the top of a file that contains your action. [Learn more](/functions/actions.md#choosing-the-runtime-use-node).

Use of the Node.js environment is restricted to **action functions only**. If you want to use a library designed for Node.js and interact with the Convex database, you need to call the Node.js library from an action, and use [`runQuery`](/functions/actions.md#action-context) or [`runMutation`](/functions/actions.md#action-context) helper to call a query or mutation.

Every `.ts` and `.js` file in the convex directory [is bundled](/functions/bundling.md) either for the default Convex JavaScript runtime or Node.js, along with any code it imports.

Files with the `"use node"` directive should not contain any Convex queries or mutations since they cannot be run in the Node.js runtime. Additionally, files without the `"use node"` directive should not import any files with the `"use node"` directive. Files that contain no Convex functions, like a `convex/utils.ts` file, also need the "use node" directive if they use Node.js-specific libraries.

If you encounter bundling errors about Node.js-specific imports like `fs` / `node:fs` not being available when deploying convex functions, running `npx convex dev --once --debug-node-apis` gives more information about these. It uses a slower bundling method to track the train of imports, narrowing down which import is responsible for the error.

Note that argument size limits are lower (5MiB instead of 16MiB).

### Node.js version configuration[​](#nodejs-version-configuration "Direct link to Node.js version configuration")

By default, all actions ran in the Node.js environment are executed in Node.js 20. This version is configurable in the [convex.json](/production/project-configuration.md#configuring-the-nodejs-version) file. We currently support Node.js 20 and 22.

When pushing a new Node.js version to the server, the new code for your functions may be executed in the old Node.js version for up a few minutes.

Note: This configuration is not supported when running the self-hosted Convex backend. The node version that is specified in the [.nvmrc](https://github.com/get-convex/convex-backend/blob/main/.nvmrc) will be used instead.

---

# Source: https://docs.convex.dev/client/rust.md

# Source: https://docs.convex.dev/quickstart/rust.md

# Rust Quickstart

Learn how to query data from Convex in a Rust app with Tokio.

1. Create a Cargo project

   Create a new Cargo project.

   ```
   cargo new my_app
   cd my_app
   ```

2. Install the Convex client and server libraries

   To get started, install the `convex` npm package which enables you to write your backend.

   And also install the `convex` Rust client library, the `tokio` runtime, and `dotenvy` for working with `.env` files.

   ```
   npm init -y && npm install convex && cargo add convex tokio dotenvy
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `"tasks:get"`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     handler: async ({ db }) => {
       return await db.query("tasks").collect();
     },
   });
   ```

7. Connect the app to your backend

   In the file `src/main.rs`, create a `ConvexClient` and use it to fetch from your `"tasks:get"` API.

   src/main.rs

   ```
   use std::{
       collections::BTreeMap,
       env,
   };

   use convex::ConvexClient;

   #[tokio::main]
   async fn main() {
       dotenvy::from_filename(".env.local").ok();
       dotenvy::dotenv().ok();

       let deployment_url = env::var("CONVEX_URL").unwrap();

       let mut client = ConvexClient::new(&deployment_url).await.unwrap();
       let result = client.query("tasks:get", BTreeMap::new()).await.unwrap();
       println!("{result:#?}");
   }
   ```

8. Run the app

   Run the app and see the serialized list of tasks.

   ```
   cargo run
   ```

See the complete [Rust documentation](https://docs.rs/convex/latest/convex/).

---

# Source: https://docs.convex.dev/tutorial/scale.md

# Convex Tutorial: Scaling your app

Convex was designed from the ground up for scale. In the previous section we already talked about how keeping your actions small and most of your logic in queries and mutations are crucial to building fast scalable backends.

Let's talk about a few other ways to keep your app fast and scalable.

[YouTube video player](https://www.youtube.com/embed/7lOGqFHnEsA)

## Indexed queries[​](#indexed-queries "Direct link to Indexed queries")

Indexes tell the database to create a lookup structure to make it really fast to filter data. If, in our chat app we wanted to build a way to look up `messages` from just one user, we'd tell Convex to index the `user` field in the `messages` table and write the query with the `withIndex` syntax.

[Learn how to use indexes](/database/reading-data/indexes/.md).

## Too many writes on the same document[​](#too-many-writes-on-the-same-document "Direct link to Too many writes on the same document")

Let's say you decide to show a counter in your app. You may write a mutation that reads a number field, adds 1, and updates the same field in the database. At some point, this pattern may cause an [optimistic concurrency control conflict](/error.md#1). That means that the database isn't able to handle updating the document that fast. All databases have trouble with this sort of pattern.

There are a [few ways to deal with this](/error.md#remediation), including building something called a sharded counter...

But before you go learn advanced scaling techniques on your own, there is a better way with [Convex Components](/components.md).

## Scaling best practices with Convex Components[​](#scaling-best-practices-with-convex-components "Direct link to Scaling best practices with Convex Components")

In the case of the counter above, the Convex team has already built a [scalable counter](https://www.convex.dev/components/sharded-counter) Convex component for you to use.

Convex Components are deployed along with your Convex backend but have their own tables and functions.

As you build more complicated features like [AI agents](/agents.md), [workflows](https://www.convex.dev/components/workflow), [leaderboards](https://www.convex.dev/components/aggregate), [feature flags](https://www.convex.dev/components/launchdarkly) or [rate limiters](https://www.convex.dev/components/rate-limiter), you may find that there is already a Convex Component that solves this problem. [Learn more about Convex Components here](/components.md).

## [Components directory](https://www.convex.dev/components)

## Wrap up[​](#wrap-up "Direct link to Wrap up")

We've covered a lot of ground in this tutorial. We started by [building a chat app](/tutorial/.md) with queries, mutations and the database that form the fundamental building blocks of the Convex sync engine. We then called an [external API](/tutorial/actions.md) from our backend, using the scheduler to coordinate the work. Finally, we learned that [Convex Components](/components.md) give you scaling best practices in neat packages.

If you are looking for more tips, read our [best practices](/understanding/best-practices/.md) and join the [community](https://www.convex.dev/community).

Convex enables you to build your MVP fast and then scale to new heights. Many great products have already done so. You're in good company.

---

# Source: https://docs.convex.dev/scheduling/scheduled-functions.md

# Scheduled Functions

Convex allows you to schedule functions to run in the future. This allows you to build powerful durable workflows without the need to set up and maintain queues or other infrastructure.

Scheduled functions are stored in the database. This means you can schedule functions minutes, days, and even months in the future. Scheduling is resilient against unexpected downtime or system restarts.

**Example:** [Scheduling](https://github.com/get-convex/convex-demos/tree/main/scheduling)

## Scheduling functions[​](#scheduling-functions "Direct link to Scheduling functions")

You can schedule public functions and [internal functions](/functions/internal-functions.md) from mutations and actions via the [scheduler](/api/interfaces/server.Scheduler.md) provided in the respective function context.

* [runAfter](/api/interfaces/server.Scheduler.md#runafter) schedules a function to run after a delay (measured in milliseconds).
* [runAt](/api/interfaces/server.Scheduler.md#runat) schedules a function run at a date or timestamp (measured in milliseconds elapsed since the epoch).

The rest of the arguments are the path to the function and its arguments, similar to invoking a function from the client. For example, here is how to send a message that self-destructs in five seconds.

convex/messages.ts

TS

```
import { mutation, internalMutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";

export const sendExpiringMessage = mutation({
  args: { body: v.string(), author: v.string() },
  handler: async (ctx, args) => {
    const { body, author } = args;
    const id = await ctx.db.insert("messages", { body, author });
    await ctx.scheduler.runAfter(5000, internal.messages.destruct, {
      messageId: id,
    });
  },
});

export const destruct = internalMutation({
  args: {
    messageId: v.id("messages"),
  },
  handler: async (ctx, args) => {
    await ctx.db.delete("messages", args.messageId);
  },
});
```

A single function can schedule up to 1000 functions with total argument size of 8MB.

### Scheduling from mutations[​](#scheduling-from-mutations "Direct link to Scheduling from mutations")

Scheduling functions from [mutations](/functions/mutation-functions.md#transactions) is atomic with the rest of the mutation. This means that if the mutation succeeds, the scheduled function is guaranteed to be scheduled. On the other hand, if the mutations fails, no function will be scheduled, even if the function fails after the scheduling call.

### Scheduling from actions[​](#scheduling-from-actions "Direct link to Scheduling from actions")

Unlike mutations, [actions](/functions/actions.md) don't execute as a single database transaction and can have side effects. Thus, scheduling from actions does not depend on the outcome of the function. This means that an action might succeed to schedule some functions and later fail due to transient error or a timeout. The scheduled functions will still be executed.

### Scheduling immediately[​](#scheduling-immediately "Direct link to Scheduling immediately")

Using `runAfter()` with delay set to 0 is used to immediately add a function to the event queue. This usage may be familiar to you if you're used to calling `setTimeout(fn, 0)`.

As noted above, actions are not atomic and are meant to cause side effects. Scheduling immediately becomes useful when you specifically want to trigger an action from a mutation that is conditional on the mutation succeeding. [This post](https://stack.convex.dev/pinecone-and-embeddings#kick-off-a-background-action) goes over a direct example of this in action, where the application depends on an external service to fill in information to the database.

## Retrieving scheduled function status[​](#retrieving-scheduled-function-status "Direct link to Retrieving scheduled function status")

Every scheduled function is reflected as a document in the `"_scheduled_functions"` system table. `runAfter()` and `runAt()` return the id of scheduled function. You can read data from system tables using the `db.system.get` and `db.system.query` methods, which work the same as the standard `db.get` and `db.query` methods.

convex/messages.ts

TS

```
export const listScheduledMessages = query({
  args: {},
  handler: async (ctx, args) => {
    return await ctx.db.system.query("_scheduled_functions").collect();
  },
});

export const getScheduledMessage = query({
  args: {
    id: v.id("_scheduled_functions"),
  },
  handler: async (ctx, args) => {
    return await ctx.db.system.get("_scheduled_functions", args.id);
  },
});
```

This is an example of the returned document:

```
{
  "_creationTime": 1699931054642.111,
  "_id": "3ep33196167235462543626ss0scq09aj4gqn9kdxrdr",
  "args": [{}],
  "completedTime": 1699931054690.366,
  "name": "messages.js:destruct",
  "scheduledTime": 1699931054657,
  "state": { "kind": "success" }
}
```

The returned document has the following fields:

* `name`: the path of the scheduled function

* `args`: the arguments passed to the scheduled function

* `scheduledTime`: the timestamp of when the function is scheduled to run (measured in milliseconds elapsed since the epoch)

* `completedTime`: the timestamp of when the function finished running, if it has completed (measured in milliseconds elapsed since the epoch)

* `state`: the status of the scheduled function. Here are the possible states a scheduled function can be in:

  <!-- -->

  * `Pending`: the function has not been started yet
  * `InProgress`: the function has started running is not completed yet (only applies to actions)
  * `Success`: the function finished running successfully with no errors
  * `Failed`: the function hit an error while running, which can either be a user error or an internal server error
  * `Canceled`: the function was canceled via the dashboard, `ctx.scheduler.cancel`, or recursively by a parent scheduled function that was canceled while in progress

Scheduled function results are available for 7 days after they have completed.

## Canceling scheduled functions[​](#canceling-scheduled-functions "Direct link to Canceling scheduled functions")

You can cancel a previously scheduled function with [`cancel`](/api/interfaces/server.Scheduler.md#cancel) via the [scheduler](/api/interfaces/server.Scheduler.md) provided in the respective function context.

convex/messages.ts

TS

```
export const cancelMessage = mutation({
  args: {
    id: v.id("_scheduled_functions"),
  },
  handler: async (ctx, args) => {
    await ctx.scheduler.cancel(args.id);
  },
});
```

What `cancel` does depends on the state of the scheduled function:

* If it hasn't started running, it won't run.
* If it already started, it will continue to run, but any functions it schedules will not run.

## Debugging[​](#debugging "Direct link to Debugging")

You can view logs from previously executed scheduled functions in the Convex dashboard [Logs view](/dashboard/deployments/logs.md). You can view and cancel yet to be executed functions in the [Functions view](/dashboard/deployments/functions.md).

## Error handling[​](#error-handling "Direct link to Error handling")

Once scheduled, mutations are guaranteed to be executed exactly once. Convex will automatically retry any internal Convex errors, and only fail on developer errors. See [Error Handling](/functions/error-handling/.md) for more details on different error types.

Since actions may have side effects, they are not automatically retried by Convex. Thus, actions will be executed at most once, and permanently fail if there are transient errors while executing them. Developers can retry those manually by scheduling a mutation that checks if the desired outcome has been achieved and if not schedule the action again.

## Auth[​](#auth "Direct link to Auth")

The auth is not propagated from the scheduling to the scheduled function. If you want to authenticate or check authorization, you'll have to pass the requisite user information in as a parameter.

---

# Source: https://docs.convex.dev/dashboard/deployments/schedules.md

# Schedules

The [schedules page](https://dashboard.convex.dev/deployment/schedules) displays all [scheduled functions](/scheduling/scheduled-functions.md) and [cron jobs](/scheduling/cron-jobs.md) in your deployment. Use the tabs at the top of this page to switch between scheduled functions and cron jobs.

## Scheduled functions UI[​](#scheduled-functions-ui "Direct link to Scheduled functions UI")

The scheduled functions UI shows a list of all upcoming function invocation. From here, you can filter to scheduled runs for a specific function, and cancel scheduled functions runs.

![Scheduled functions](/assets/images/scheduled_functions-8dad14a0426380104964b52c68dbdc31.png)

## Cron jobs UI[​](#cron-jobs-ui "Direct link to Cron jobs UI")

The cron jobs UI lists all of your cron jobs, including their run frequency and scheduled run time.

![Cron jobs](/assets/images/cron_jobs-9986c12428ea362a4dc2b012249a4611.png)

Expanding a specific cron job will open the execution history for the selected job.

![Cron job history](/assets/images/cron_job_history-1be17ce3db8bb6772c2f8102f74436cd.png)

---

# Source: https://docs.convex.dev/scheduling.md

# Scheduling

Convex lets you easily schedule a function to run once or repeatedly in the future. This allows you to build durable workflows like sending a welcome email a day after someone joins or regularly reconciling your accounts with Stripe. Convex provides two different features for scheduling:

* [Scheduled Functions](/scheduling/scheduled-functions.md) can be scheduled durably by any other function to run at a later point in time. You can schedule functions minutes, days, and even months in the future.
* [Cron Jobs](/scheduling/cron-jobs.md) schedule functions to run on a recurring basis, such as daily.

## Durable function components[​](#durable-function-components "Direct link to Durable function components")

Built-in scheduled functions and crons work well for simpler apps and workflows. If you're operating at high scale or need more specific guarantees, use the following higher-level [components](/components.md) for durable functions.

[Convex Component](https://www.convex.dev/components/workpool)

### [Workpool](https://www.convex.dev/components/workpool)

[Workpool give critical tasks priority by organizing async operations into separate, customizable queues.](https://www.convex.dev/components/workpool)

[Convex Component](https://www.convex.dev/components/workflow)

### [Workflow](https://www.convex.dev/components/workflow)

[Simplify programming long running code flows. Workflows execute durably with configurable retries and delays.](https://www.convex.dev/components/workflow)

[Convex Component](https://www.convex.dev/components/crons)

### [Crons](https://www.convex.dev/components/crons)

[Use cronspec to run functions on a repeated schedule at runtime.](https://www.convex.dev/components/crons)

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/database/advanced/schema-philosophy.md

# Schema Philosophy

With Convex there is no need to write any `CREATE TABLE` statements, or think through your stored table structure ahead of time so you can name your field and types. You simply put your objects into Convex and keep building your app!

However, moving fast early can be problematic later. "Was that field a number or a string? I think I changed it when I fixed that one bug?"

Storage systems which are too permissive can sometimes become liabilities as your system matures and you want to be able to reason assuredly about exactly what data is in your system.

The good news is Convex is always typed. It's just implicitly typed! When you submit a document to Convex, tracks all the types of all the fields in your document. You can go to your [dashboard](/dashboard.md) and view the inferred schema of any table to understand what you've ended up with.

"What about that field I changed from a string to a number?" Convex can handle this too. Convex will track those changes, in this case the field is a union like `v.union(v.number(), v.string())`. That way even when you change your mind about your documents fields and types, Convex has your back.

Once you are ready to formalize your schema, you can define it using our [schema builder](/database/schemas.md) to enable schema validation and generate types based on it.

---

# Source: https://docs.convex.dev/database/schemas.md

# Schemas

A schema is a description of

1. the tables in your Convex project
2. the type of documents within your tables

While it is possible to use Convex *without* defining a schema, adding a `schema.ts` file will ensure that the documents in your tables are the correct type. If you're using [TypeScript](/understanding/best-practices/typescript.md), adding a schema will also give you end-to-end type safety throughout your app.

We recommend beginning your project without a schema for rapid prototyping and then adding a schema once you've solidified your plan. To learn more see our [Schema Philosophy](/database/advanced/schema-philosophy.md).

**Example:** [TypeScript and Schemas](https://github.com/get-convex/convex-demos/tree/main/typescript)

## Writing schemas[​](#writing-schemas "Direct link to Writing schemas")

Schemas are defined in a `schema.ts` file in your `convex/` directory and look like:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  messages: defineTable({
    body: v.string(),
    user: v.id("users"),
  }),
  users: defineTable({
    name: v.string(),
    tokenIdentifier: v.string(),
  }).index("by_token", ["tokenIdentifier"]),
});
```

This schema (which is based on our [users and auth example](https://github.com/get-convex/convex-demos/tree/main/users-and-auth)), has 2 tables: messages and users. Each table is defined using the [`defineTable`](/api/modules/server.md#definetable) function. Within each table, the document type is defined using the validator builder, [`v`](/api/modules/values.md#v). In addition to the fields listed, Convex will also automatically add `_id` and `_creationTime` fields. To learn more, see [System Fields](/database/types.md#system-fields).

Generating a Schema

While writing your schema, it can be helpful to consult the [Convex Dashboard](/dashboard/deployments/data.md#generating-a-schema). The "Generate Schema" button in the "Data" view suggests a schema declaration based on the data in your tables.

### Validators[​](#validators "Direct link to Validators")

The validator builder, [`v`](/api/modules/values.md#v) is used to define the type of documents in each table. It has methods for each of [Convex's types](/database/types.md):

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  documents: defineTable({
    id: v.id("documents"),
    string: v.string(),
    number: v.number(),
    boolean: v.boolean(),
    nestedObject: v.object({
      property: v.string(),
    }),
  }),
});
```

It additionally allows you to define unions, optional property, string literals, and more. [Argument validation](/functions/validation.md) and schemas both use the same validator builder, `v`.

#### Optional fields[​](#optional-fields "Direct link to Optional fields")

You can describe optional fields by wrapping their type with `v.optional(...)`:

```
defineTable({
  optionalString: v.optional(v.string()),
  optionalNumber: v.optional(v.number()),
});
```

This corresponds to marking fields as optional with `?` in TypeScript.

#### Unions[​](#unions "Direct link to Unions")

You can describe fields that could be one of multiple types using `v.union`:

```
defineTable({
  stringOrNumber: v.union(v.string(), v.number()),
});
```

If your table stores multiple different types of documents, you can use `v.union` at the top level:

```
defineTable(
  v.union(
    v.object({
      kind: v.literal("StringDocument"),
      value: v.string(),
    }),
    v.object({
      kind: v.literal("NumberDocument"),
      value: v.number(),
    }),
  ),
);
```

In this schema, documents either have a `kind` of `"StringDocument"` and a string for their `value`:

```
{
  "kind": "StringDocument",
  "value": "abc"
}
```

or they have a `kind` of `"NumberDocument"` and a number for their `value`:

```
{
  "kind": "NumberDocument",
  "value": 123
}
```

#### Literals[​](#literals "Direct link to Literals")

Fields that are a constant can be expressed with `v.literal`:

```
defineTable({
  oneTwoOrThree: v.union(
    v.literal("one"),
    v.literal("two"),
    v.literal("three"),
  ),
});
```

#### Record objects[​](#record-objects "Direct link to Record objects")

You can describe objects that map arbitrary keys to values with `v.record`:

```
defineTable({
  simpleMapping: v.record(v.string(), v.boolean()),
});
```

You can use other types of string validators for the keys:

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

export default mutation({
  args: {
    userIdToValue: v.record(v.id("users"), v.boolean()),
  },
  handler: async ({ db }, { userIdToValue }) => {
    //...
  },
});
```

Notes:

* This type corresponds to the [Record\<K,V>](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) type in TypeScript
* You cannot use string literals as a `record` key
* Using `v.string()` as a `record` key validator will only allow ASCII characters

#### Any[​](#any "Direct link to Any")

Fields or documents that could take on any value can be represented with `v.any()`:

```
defineTable({
  anyValue: v.any(),
});
```

This corresponds to the `any` type in TypeScript.

### Options[​](#options "Direct link to Options")

These options are passed as part of the [options](/api/interfaces/server.DefineSchemaOptions.md) argument to [`defineSchema`](/api/modules/server.md#defineschema).

#### `schemaValidation: boolean`[​](#schemavalidation-boolean "Direct link to schemavalidation-boolean")

Whether Convex should validate at runtime that your documents match your schema.

By default, Convex will enforce that all new and existing documents match your schema.

You can disable `schemaValidation` by passing in `schemaValidation: false`:

```
defineSchema(
  {
    // Define tables here.
  },
  {
    schemaValidation: false,
  },
);
```

When `schemaValidation` is disabled, Convex will not validate that new or existing documents match your schema. You'll still get schema-specific TypeScript types, but there will be no validation at runtime that your documents match those types.

#### `strictTableNameTypes: boolean`[​](#stricttablenametypes-boolean "Direct link to stricttablenametypes-boolean")

Whether the TypeScript types should allow accessing tables not in the schema.

By default, the TypeScript table name types produced by your schema are strict. That means that they will be a union of strings (ex. `"messages" | "users"`) and only support accessing tables explicitly listed in your schema.

Sometimes it's useful to only define part of your schema. For example, if you are rapidly prototyping, it could be useful to try out a new table before adding it your `schema.ts` file.

You can disable `strictTableNameTypes` by passing in `strictTableNameTypes: false`:

```
defineSchema(
  {
    // Define tables here.
  },
  {
    strictTableNameTypes: false,
  },
);
```

When `strictTableNameTypes` is disabled, the TypeScript types will allow access to tables not listed in the schema and their document type will be `any`.

Regardless of the value of `strictTableNameTypes`, your schema will only validate documents in the tables listed in the schema. You can still create and modify documents in other tables in JavaScript or on the dashboard (they just won't be validated).

## Schema validation[​](#schema-validation "Direct link to Schema validation")

Schemas are pushed automatically in [`npx convex dev`](/cli.md#run-the-convex-dev-server) and [`npx convex deploy`](/cli.md#deploy-convex-functions-to-production).

The first push after a schema is added or modified will validate that all existing documents match the schema. If there are documents that fail validation, the push will fail.

After the schema is pushed, Convex will validate that all future document inserts and updates match the schema.

Schema validation is skipped if [`schemaValidation`](#schemavalidation-boolean) is set to `false`.

Note that schemas only validate documents in the tables listed in the schema. You can still create and modify documents in other tables (they just won't be validated).

### Circular references[​](#circular-references "Direct link to Circular references")

You might want to define a schema with circular ID references like:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    preferencesId: v.id("preferences"),
  }),
  preferences: defineTable({
    userId: v.id("users"),
  }),
});
```

In this schema, documents in the `users` table contain a reference to documents in `preferences` and vice versa.

Because schema validation enforces your schema on every `db.insert`, `db.replace`, and `db.patch` call, creating circular references like this is not possible.

The easiest way around this is to make one of the references nullable:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    preferencesId: v.id("preferences"),
  }),
  preferences: defineTable({
    userId: v.union(v.id("users"), v.null()),
  }),
});
```

This way you can create a preferences document first, then create a user document, then set the reference on the preferences document:

convex/users.ts

TS

```
import { mutation } from "./_generated/server";

export default mutation({
  handler: async (ctx) => {
    const preferencesId = await ctx.db.insert("preferences", {});
    const userId = await ctx.db.insert("users", { preferencesId });
    await ctx.db.patch("preferences", preferencesId, { userId });
  },
});
```

[Let us know](/production/contact.md) if you need better support for circular references.

## TypeScript types[​](#typescript-types "Direct link to TypeScript types")

Once you've defined a schema, [`npx convex dev`](/cli.md#run-the-convex-dev-server) will produce new versions of [`dataModel.d.ts`](/generated-api/data-model.md) and [`server.d.ts`](/generated-api/server.md) with types based on your schema.

### `Doc<TableName>`[​](#doctablename "Direct link to doctablename")

The [`Doc`](/generated-api/data-model.md#doc) TypeScript type from [`dataModel.d.ts`](/generated-api/data-model.md) provides document types for all of your tables. You can use these both when writing Convex functions and in your React components:

MessageView\.tsx

```
import { Doc } from "../convex/_generated/dataModel";

function MessageView(props: { message: Doc<"messages"> }) {
  ...
}
```

If you need the type for a portion of a document, use the [`Infer` type helper](/functions/validation.md#extracting-typescript-types).

### `query` and `mutation`[​](#query-and-mutation "Direct link to query-and-mutation")

The [`query`](/generated-api/server.md#query) and [`mutation`](/generated-api/server.md#mutation) functions in [`server.js`](/generated-api/server.md) have the same API as before but now provide a `db` with more precise types. Functions like [`db.insert(table, document)`](/api/interfaces/server.GenericDatabaseWriter.md#insert) now understand your schema. Additionally [database queries](/database/reading-data/.md) will now return the correct document type (not `any`).

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/client/javascript/script-tag.md

# Source: https://docs.convex.dev/quickstart/script-tag.md

# Script Tag Quickstart

Learn how to query data from Convex from script tags in HTML.

1. Create a new npm project

   Create a new directory for your Convex project.

   ```
   mkdir my-project && cd my-project && npm init -y
   ```

2. Install the Convex client and server library

   Install the `convex` package which provides a convenient interface for working with Convex from JavaScript.

   ```
   npm install convex
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.js` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.js

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Copy the deployment URL

   Open the `.env.local` file and copy the `CONVEX_URL` of your development environment for use in the HTML file.

8. Add the script to your webpage

   In a new file `index.html`, create a `ConvexClient` using the URL of your development environment.

   Open this file in a web browser and you'll see it run each time the `tasks` table is modified.

   index.html

   ```
   <!doctype html>
   <script src="https://unpkg.com/convex@1.3.1/dist/browser.bundle.js"></script>
   <script>
     const CONVEX_URL = "CONVEX_URL_GOES_HERE";
     const client = new convex.ConvexClient(CONVEX_URL);
     client.onUpdate("tasks:get", {}, (tasks) =>
       console.log(tasks.map((task) => task.text)),
     );
   </script>
   ```

See the complete [Script Tag documentation](/client/javascript/script-tag.md).

---

# Source: https://docs.convex.dev/search.md

# AI & Search

Whether building RAG enabled chatbots or quick search in your applications, Convex provides easy apis to create powerful AI and search enabled products.

[Vector Search](/search/vector-search.md) enables searching for documents based on their semantic meaning. It uses vector embeddings to calculate similarity and retrieve documents that are similar to a given query. Vector search is a key part of common AI techniques like RAG.

[Full Text Search](/search/text-search.md) enables keyword and phrase search within your documents. It supports prefix matching to enable typeahead search. Convex full text search is also reactive and always up to date like all Convex queries, making it easy to build reliable quick search boxes.

[Convex Actions](/functions/actions.md) easily enable you to call AI apis, save data to your database, and drive your user interface. See examples of how you can use this to [build sophisticated AI applications](https://stack.convex.dev/tag/AI).

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/self-hosting.md

# Self Hosting

If you're excited about self-hosting, you can run the Convex backend on your own servers. Self-hosted Convex runs the [open-source backend](https://github.com/get-convex/convex-backend), and contains the same fully up-to-date code the cloud service uses.

To get started with self hosting, follow the self-hosting guide:

## [Self-hosting guide](https://github.com/get-convex/convex-backend/blob/main/self-hosted/README.md)

Join the `#self-hosted` channel in the [Discord community](https://convex.dev/community) for self-hosting support.

Self hosting is not for everyone. If you're looking for a more hands-off solution, we recommend using the [Convex-hosted product](https://convex.dev/pricing).

## Open Source Convex Backend[​](#open-source-convex-backend "Direct link to Open Source Convex Backend")

The majority of the backend is written in Rust, with a healthy dose of TypeScript supporting the server-side function environment.

You can learn more about open-sourcing at Convex in our [announcement](https://news.convex.dev/convex-goes-open-source/) and the [software engineering daily podcast](https://softwareengineeringdaily.com/2024/03/20/going-open-source-at-convex-with-james-cowling/). It is released under the [FSL Apache 2.0 License](https://fsl.software/).

## Other Convex Open Source Projects[​](#other-convex-open-source-projects "Direct link to Other Convex Open Source Projects")

The Convex backend, client libraries, dashboard, and CLI are all open-source. You can explore everything on the [Convex GitHub page](https://github.com/get-convex).

### Convex Clients[​](#convex-clients "Direct link to Convex Clients")

All Convex Clients are open-source.

* [Convex JavaScript/TypeScript clients & CLI](https://github.com/get-convex/convex-js)
* [Convex Python Client](https://github.com/get-convex/convex-py)
* [Convex Rust Client](https://github.com/get-convex/convex-rs)

### Much Much More[​](#much-much-more "Direct link to Much Much More")

Convex also open-sources many other helpful projects including [helpers](https://github.com/get-convex/convex-helpers), [templates](https://github.com/orgs/get-convex/repositories?type=all\&q=template), [demos](https://github.com/get-convex/convex-demos), a [testing harness](https://github.com/get-convex/convex-test) and much more. See the complete list of all our public repositories [at GitHub](https://github.com/orgs/get-convex/repositories?type=all).

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/file-storage/serve-files.md

# Serving Files

Files stored in Convex can be served to your users by generating a URL pointing to a given file.

## Generating file URLs in queries[​](#generating-file-urls-in-queries "Direct link to Generating file URLs in queries")

The simplest way to serve files is to return URLs along with other data required by your app from [queries](/functions/query-functions.md) and [mutations](/functions/mutation-functions.md).

A file URL can be generated from a storage ID by the [`storage.getUrl`](/api/interfaces/server.StorageReader.md#geturl) function of the [`QueryCtx`](/api/interfaces/server.GenericQueryCtx.md), [`MutationCtx`](/api/interfaces/server.GenericMutationCtx.md), or [`ActionCtx`](/api/interfaces/server.GenericActionCtx.md) object:

convex/listMessages.ts

TS

```
import { query } from "./_generated/server";

export const list = query({
  args: {},
  handler: async (ctx) => {
    const messages = await ctx.db.query("messages").collect();
    return Promise.all(
      messages.map(async (message) => ({
        ...message,
        // If the message is an "image" its `body` is an `Id<"_storage">`
        ...(message.format === "image"
          ? { url: await ctx.storage.getUrl(message.body) }
          : {}),
      })),
    );
  },
});
```

File URLs can be used in `img` elements to render images:

src/App.tsx

TS

```
function Image({ message }: { message: { url: string } }) {
  return <img src={message.url} height="300px" width="auto" />;
}
```

In your query you can control who gets access to a file when the URL is generated. If you need to control access when the file is *served*, you can define your own file serving HTTP actions instead.

## Serving files from HTTP actions[​](#serving-files-from-http-actions "Direct link to Serving files from HTTP actions")

You can serve files directly from [HTTP actions](/functions/http-actions.md). An HTTP action will need to take some parameter(s) that can be mapped to a storage ID, or a storage ID itself.

This enables access control at the time the file is served, such as when an image is displayed on a website. But note that the HTTP actions response size is [currently limited](/functions/http-actions.md#limits) to 20MB. For larger files you need to use file URLs as described [above](#generating-file-urls-in-queries).

A file [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object can be generated from a storage ID by the [`storage.get`](/api/interfaces/server.StorageActionWriter.md#get) function of the [`ActionCtx`](/api/interfaces/server.GenericActionCtx.md) object, which can be returned in a `Response`:

convex/http.ts

TS

```
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { Id } from "./_generated/dataModel";

const http = httpRouter();

http.route({
  path: "/getImage",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    const { searchParams } = new URL(request.url);
    const storageId = searchParams.get("storageId")! as Id<"_storage">;
    const blob = await ctx.storage.get(storageId);
    if (blob === null) {
      return new Response("Image not found", {
        status: 404,
      });
    }
    return new Response(blob);
  }),
});

export default http;
```

The URL of such an action can be used directly in `img` elements to render images:

src/App.tsx

TS

```
const convexSiteUrl = import.meta.env.VITE_CONVEX_SITE_URL;

function Image({ storageId }: { storageId: string }) {
  // e.g. https://happy-animal-123.convex.site/getImage?storageId=456
  const getImageUrl = new URL(`${convexSiteUrl}/getImage`);
  getImageUrl.searchParams.set("storageId", storageId);

  return <img src={getImageUrl.href} height="300px" width="auto" />;
}
```

---

# Source: https://docs.convex.dev/client/nextjs/app-router/server-rendering.md

# Next.js Server Rendering

Next.js automatically renders both Client and Server Components on the server during the initial page load.

By default Client Components will not wait for Convex data to be loaded, and your UI will render in a "loading" state. Read on to learn how to preload data during server rendering and how to interact with the Convex deployment from Next.js server-side.

**Example:** [Next.js App Router](https://github.com/get-convex/convex-demos/tree/main/nextjs-app-router)

This pages covers the App Router variant of Next.js.

Next.js Server Rendering support is in beta

Next.js Server Rendering support<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

## Preloading data for Client Components[​](#preloading-data-for-client-components "Direct link to Preloading data for Client Components")

If you want to preload data from Convex and leverage Next.js [server rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#server-rendering-strategies), but still retain reactivity after the initial page load, use [`preloadQuery`](/api/modules/nextjs.md#preloadquery) from [`convex/nextjs`](/api/modules/nextjs.md).

In a [Server Component](https://nextjs.org/docs/app/building-your-application/rendering/server-components) call `preloadQuery`:

app/TasksWrapper.tsx

TS

```
import { preloadQuery } from "convex/nextjs";
import { api } from "@/convex/_generated/api";
import { Tasks } from "./Tasks";

export async function TasksWrapper() {
  const preloadedTasks = await preloadQuery(api.tasks.list, {
    list: "default",
  });
  return <Tasks preloadedTasks={preloadedTasks} />;
}
```

In a [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) call [`usePreloadedQuery`](/api/modules/react.md#usepreloadedquery):

app/TasksWrapper.tsx

TS

```
"use client";

import { Preloaded, usePreloadedQuery } from "convex/react";
import { api } from "@/convex/_generated/api";

export function Tasks(props: {
  preloadedTasks: Preloaded<typeof api.tasks.list>;
}) {
  const tasks = usePreloadedQuery(props.preloadedTasks);
  // render `tasks`...
  return <div>...</div>;
}
```

[`preloadQuery`](/api/modules/nextjs.md#preloadquery) takes three arguments:

1. The query reference
2. Optionally the arguments object passed to the query
3. Optionally a [NextjsOptions](/api/modules/nextjs.md#nextjsoptions) object

`preloadQuery` uses the [`cache: 'no-store'` policy](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#opting-out-of-data-caching) so any Server Components using it will not be eligible for [static rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#server-rendering-strategies).

### Using the query result[​](#using-the-query-result "Direct link to Using the query result")

[`preloadQuery`](/api/modules/nextjs.md#preloadquery) returns an opaque `Preloaded` payload that should be passed through to `usePreloadedQuery`. If you want to use the return value of the query, perhaps to decide whether to even render the Client Component, you can pass the `Preloaded` payload to the [`preloadedQueryResult`](/api/modules/nextjs.md#preloadedqueryresult) function.

## Using Convex to render Server Components[​](#using-convex-to-render-server-components "Direct link to Using Convex to render Server Components")

If you need Convex data on the server, you can load data from Convex in your [Server Components](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching), but it will be non-reactive. To do this, use the [`fetchQuery`](/api/modules/nextjs.md#fetchquery) function from `convex/nextjs`:

app/StaticTasks.tsx

TS

```
import { fetchQuery } from "convex/nextjs";
import { api } from "@/convex/_generated/api";

export async function StaticTasks() {
  const tasks = await fetchQuery(api.tasks.list, { list: "default" });
  // render `tasks`...
  return <div>...</div>;
}
```

## Server Actions and Route Handlers[​](#server-actions-and-route-handlers "Direct link to Server Actions and Route Handlers")

Next.js supports building HTTP request handling routes, similar to Convex [HTTP Actions](/functions/http-actions.md). You can use Convex from a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations) or a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) as you would any other database service.

To load and edit Convex data in your Server Action or Route Handler, you can use the `fetchQuery`, `fetchMutation` and `fetchAction` functions.

Here's an example inline Server Action calling a Convex mutation:

app/example/page.tsx

TS

```
import { api } from "@/convex/_generated/api";
import { fetchMutation, fetchQuery } from "convex/nextjs";
import { revalidatePath } from "next/cache";

export default async function PureServerPage() {
  const tasks = await fetchQuery(api.tasks.list, { list: "default" });
  async function createTask(formData: FormData) {
    "use server";

    await fetchMutation(api.tasks.create, {
      text: formData.get("text") as string,
    });
    revalidatePath("/example");
  }
  // render tasks and task creation form
  return <form action={createTask}>...</form>;
}
```

Here's an example Route Handler calling a Convex mutation:

app/api/route.ts

TS

```
import { NextResponse } from "next/server";
// Hack for TypeScript before 5.2
const Response = NextResponse;

import { api } from "@/convex/_generated/api";
import { fetchMutation } from "convex/nextjs";

export async function POST(request: Request) {
  const args = await request.json();
  await fetchMutation(api.tasks.create, { text: args.text });
  return Response.json({ success: true });
}
```

## Server-side authentication[​](#server-side-authentication "Direct link to Server-side authentication")

To make authenticated requests to Convex during server rendering, pass a JWT token to [`preloadQuery`](/api/modules/nextjs.md#preloadquery) or [`fetchQuery`](/api/modules/nextjs.md#fetchquery) in the third options argument:

app/TasksWrapper.tsx

TS

```
import { preloadQuery } from "convex/nextjs";
import { api } from "@/convex/_generated/api";
import { Tasks } from "./Tasks";

export async function TasksWrapper() {
  const token = await getAuthToken();
  const preloadedTasks = await preloadQuery(
    api.tasks.list,
    { list: "default" },
    { token },
  );
  return <Tasks preloadedTasks={preloadedTasks} />;
}
```

The implementation of `getAuthToken` depends on your authentication provider.

* Clerk
* Auth0

app/auth.ts

TS

```
import { auth } from "@clerk/nextjs/server";

export async function getAuthToken() {
  return (await (await auth()).getToken({ template: "convex" })) ?? undefined;
}
```

app/auth.ts

TS

```
// You'll need v4.3 or later of @auth0/nextjs-auth0
import { getSession } from '@auth0/nextjs-auth0';

export async function getAuthToken() {
  const session = await getSession();
  const idToken = session.tokenSet.idToken;
  return idToken;
}
```

## Configuring Convex deployment URL[​](#configuring-convex-deployment-url "Direct link to Configuring Convex deployment URL")

Convex hooks used by Client Components are configured via the `ConvexReactClient` constructor, as shown in the [Next.js Quickstart](/quickstart/nextjs.md).

To use `preloadQuery`, `fetchQuery`, `fetchMutation` and `fetchAction` in Server Components, Server Actions and Route Handlers you must either:

1. have `NEXT_PUBLIC_CONVEX_URL` environment variable set to the Convex deployment URL
2. or pass the [`url` option](/api/modules/nextjs.md#nextjsoptions) in the third argument to `preloadQuery`, `fetchQuery`, `fetchMutation` or `fetchAction`

## Consistency[​](#consistency "Direct link to Consistency")

[`preloadQuery`](/api/modules/nextjs.md#preloadquery) and [`fetchQuery`](/api/modules/nextjs.md#fetchquery) use the `ConvexHTTPClient` under the hood. This client is stateless. This means that two calls to `preloadQuery` are not guaranteed to return consistent data based on the same database state. This is similar to more traditional databases, but is different from the [guaranteed consistency](/client/react.md#consistency) provided by the `ConvexReactClient`.

To prevent rendering an inconsistent UI avoid using multiple `preloadQuery` calls on the same page.

---

# Source: https://docs.convex.dev/api/interfaces/server.Auth.md

# Interface: Auth

[server](/api/modules/server.md).Auth

An interface to access information about the currently authenticated user within Convex query and mutation functions.

## Methods[​](#methods "Direct link to Methods")

### getUserIdentity[​](#getuseridentity "Direct link to getUserIdentity")

▸ **getUserIdentity**(): `Promise`<`null` | [`UserIdentity`](/api/interfaces/server.UserIdentity.md)>

Get details about the currently authenticated user.

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | [`UserIdentity`](/api/interfaces/server.UserIdentity.md)>

A promise that resolves to a [UserIdentity](/api/interfaces/server.UserIdentity.md) if the Convex client was configured with a valid ID token, or if not, will:

* returns `null` on Convex queries, mutations, actions.
* `throw` on HTTP Actions.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/authentication.ts:236](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L236)

---

# Source: https://docs.convex.dev/api/interfaces/server.BaseTableReader.md

# Interface: BaseTableReader\<DataModel, TableName>

[server](/api/modules/server.md).BaseTableReader

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)                        |
| `TableName` | extends [`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<`DataModel`> |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* **`BaseTableReader`**

  ↳ [`BaseTableWriter`](/api/interfaces/server.BaseTableWriter.md)

## Methods[​](#methods "Direct link to Methods")

### get[​](#get "Direct link to get")

▸ **get**(`id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the table by its [GenericId](/api/modules/values.md#genericid).

#### Parameters[​](#parameters "Direct link to Parameters")

| Name | Type                                                         | Description                                                                                   |
| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:88](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L88)

***

### query[​](#query "Direct link to query")

▸ **query**(): [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

Begin a query for the table.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

#### Returns[​](#returns-1 "Direct link to Returns")

[`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

* A [QueryInitializer](/api/interfaces/server.QueryInitializer.md) object to start building a query.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:100](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L100)

---

# Source: https://docs.convex.dev/api/interfaces/server.BaseTableWriter.md

# Interface: BaseTableWriter\<DataModel, TableName>

[server](/api/modules/server.md).BaseTableWriter

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)                        |
| `TableName` | extends [`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<`DataModel`> |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`BaseTableReader`](/api/interfaces/server.BaseTableReader.md)<`DataModel`, `TableName`>

  ↳ **`BaseTableWriter`**

## Methods[​](#methods "Direct link to Methods")

### get[​](#get "Direct link to get")

▸ **get**(`id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the table by its [GenericId](/api/modules/values.md#genericid).

#### Parameters[​](#parameters "Direct link to Parameters")

| Name | Type                                                         | Description                                                                                   |
| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[BaseTableReader](/api/interfaces/server.BaseTableReader.md).[get](/api/interfaces/server.BaseTableReader.md#get)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:88](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L88)

***

### query[​](#query "Direct link to query")

▸ **query**(): [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

Begin a query for the table.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

#### Returns[​](#returns-1 "Direct link to Returns")

[`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

* A [QueryInitializer](/api/interfaces/server.QueryInitializer.md) object to start building a query.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[BaseTableReader](/api/interfaces/server.BaseTableReader.md).[query](/api/interfaces/server.BaseTableReader.md#query)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:100](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L100)

***

### insert[​](#insert "Direct link to insert")

▸ **insert**(`value`): `Promise`<[`GenericId`](/api/modules/values.md#genericid)<`TableName`>>

Insert a new document into the table.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name    | Type                                                                                                                                                     | Description                                                               |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `value` | [`WithoutSystemFields`](/api/modules/server.md#withoutsystemfields)<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The [Value](/api/modules/values.md#value) to insert into the given table. |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<[`GenericId`](/api/modules/values.md#genericid)<`TableName`>>

* [GenericId](/api/modules/values.md#genericid) of the new document.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/database.ts:289](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L289)

***

### patch[​](#patch "Direct link to patch")

▸ **patch**(`id`, `value`): `Promise`<`void`>

Patch an existing document, shallow merging it with the given partial document.

New fields are added. Existing fields are overwritten. Fields set to `undefined` are removed.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type                                                                                              | Description                                                                                                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>                                      | The [GenericId](/api/modules/values.md#genericid) of the document to patch.                                                                                                                                             |
| `value` | `PatchValue`<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The partial [GenericDocument](/api/modules/server.md#genericdocument) to merge into the specified document. If this new value specifies system fields like `_id`, they must match the document's existing field values. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/database.ts:304](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L304)

***

### replace[​](#replace "Direct link to replace")

▸ **replace**(`id`, `value`): `Promise`<`void`>

Replace the value of an existing document, overwriting its old value.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name    | Type                                                                                                                                                               | Description                                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>                                                                                                       | The [GenericId](/api/modules/values.md#genericid) of the document to replace.                                                                                  |
| `value` | [`WithOptionalSystemFields`](/api/modules/server.md#withoptionalsystemfields)<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The new [GenericDocument](/api/modules/server.md#genericdocument) for the document. This value can omit the system fields, and the database will fill them in. |

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/database.ts:316](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L316)

***

### delete[​](#delete "Direct link to delete")

▸ **delete**(`id`): `Promise`<`void`>

Delete an existing document.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name | Type                                                         | Description                                                                  |
| ---- | ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> | The [GenericId](/api/modules/values.md#genericid) of the document to remove. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/database.ts:326](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L326)

---

# Source: https://docs.convex.dev/api/interfaces/server.CronJob.md

# Interface: CronJob

[server](/api/modules/server.md).CronJob

A schedule to run a Convex mutation or action on. You can schedule Convex functions to run regularly with interval and exporting it.

## Properties[​](#properties "Direct link to Properties")

### name[​](#name "Direct link to name")

• **name**: `string`

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/cron.ts:153](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L153)

***

### args[​](#args "Direct link to args")

• **args**: [`JSONValue`](/api/modules/values.md#jsonvalue)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/cron.ts:154](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L154)

***

### schedule[​](#schedule "Direct link to schedule")

• **schedule**: `Schedule`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/cron.ts:155](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L155)

---

# Source: https://docs.convex.dev/api/classes/server.Crons.md

# Class: Crons

[server](/api/modules/server.md).Crons

A class for scheduling cron jobs.

To learn more see the documentation at <https://docs.convex.dev/scheduling/cron-jobs>

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new Crons**()

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/cron.ts:246](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L246)

## Properties[​](#properties "Direct link to Properties")

### crons[​](#crons "Direct link to crons")

• **crons**: `Record`<`string`, [`CronJob`](/api/interfaces/server.CronJob.md)>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/cron.ts:244](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L244)

***

### isCrons[​](#iscrons "Direct link to isCrons")

• **isCrons**: `true`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/cron.ts:245](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L245)

## Methods[​](#methods "Direct link to Methods")

### interval[​](#interval "Direct link to interval")

▸ **interval**<`FuncRef`>(`cronIdentifier`, `schedule`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run at some interval.

```
crons.interval("Clear presence data", {seconds: 30}, api.presence.clear);
```

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | -                                                                                             |
| `schedule`          | `Interval`                                                               | The time between runs for this scheduled job.                                                 |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | The arguments to the function.                                                                |

#### Returns[​](#returns "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/cron.ts:283](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L283)

***

### hourly[​](#hourly "Direct link to hourly")

▸ **hourly**<`FuncRef`>(`cronIdentifier`, `schedule`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run on an hourly basis.

```
crons.hourly(
  "Reset high scores",
  {
    minuteUTC: 30,
  },
  api.scores.reset
)
```

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | A unique name for this scheduled job.                                                         |
| `schedule`          | `Hourly`                                                                 | What time (UTC) each day to run this function.                                                |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | The arguments to the function.                                                                |

#### Returns[​](#returns-1 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/cron.ts:331](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L331)

***

### daily[​](#daily "Direct link to daily")

▸ **daily**<`FuncRef`>(`cronIdentifier`, `schedule`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run on a daily basis.

```
crons.daily(
  "Reset high scores",
  {
    hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
    minuteUTC: 30,
  },
  api.scores.reset
)
```

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | A unique name for this scheduled job.                                                         |
| `schedule`          | `Daily`                                                                  | What time (UTC) each day to run this function.                                                |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | The arguments to the function.                                                                |

#### Returns[​](#returns-2 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/cron.ts:366](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L366)

***

### weekly[​](#weekly "Direct link to weekly")

▸ **weekly**<`FuncRef`>(`cronIdentifier`, `schedule`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run on a weekly basis.

```
crons.weekly(
  "Weekly re-engagement email",
  {
    dayOfWeek: "Tuesday",
    hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
    minuteUTC: 30,
  },
  api.emails.send
)
```

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | A unique name for this scheduled job.                                                         |
| `schedule`          | `Weekly`                                                                 | What day and time (UTC) each week to run this function.                                       |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | -                                                                                             |

#### Returns[​](#returns-3 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/cron.ts:402](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L402)

***

### monthly[​](#monthly "Direct link to monthly")

▸ **monthly**<`FuncRef`>(`cronIdentifier`, `schedule`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run on a monthly basis.

Note that some months have fewer days than others, so e.g. a function scheduled to run on the 30th will not run in February.

```
crons.monthly(
  "Bill customers at ",
  {
    hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
    minuteUTC: 30,
    day: 1,
  },
  api.billing.billCustomers
)
```

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | A unique name for this scheduled job.                                                         |
| `schedule`          | `Monthly`                                                                | What day and time (UTC) each month to run this function.                                      |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | The arguments to the function.                                                                |

#### Returns[​](#returns-4 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/cron.ts:443](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L443)

***

### cron[​](#cron "Direct link to cron")

▸ **cron**<`FuncRef`>(`cronIdentifier`, `cron`, `functionReference`, `...args`): `void`

Schedule a mutation or action to run on a recurring basis.

Like the unix command `cron`, Sunday is 0, Monday is 1, etc.

```
 ┌─ minute (0 - 59)
 │ ┌─ hour (0 - 23)
 │ │ ┌─ day of the month (1 - 31)
 │ │ │ ┌─ month (1 - 12)
 │ │ │ │ ┌─ day of the week (0 - 6) (Sunday to Saturday)
"* * * * *"
```

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                   |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `cronIdentifier`    | `string`                                                                 | A unique name for this scheduled job.                                                         |
| `cron`              | `string`                                                                 | Cron string like `"15 7 * * *"` (Every day at 7:15 UTC)                                       |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule. |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | The arguments to the function.                                                                |

#### Returns[​](#returns-5 "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/cron.ts:480](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L480)

---

# Source: https://docs.convex.dev/api/interfaces/server.DefineSchemaOptions.md

# Interface: DefineSchemaOptions\<StrictTableNameTypes>

[server](/api/modules/server.md).DefineSchemaOptions

Options for [defineSchema](/api/modules/server.md#defineschema).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name                   | Type              |
| ---------------------- | ----------------- |
| `StrictTableNameTypes` | extends `boolean` |

## Properties[​](#properties "Direct link to Properties")

### schemaValidation[​](#schemavalidation "Direct link to schemaValidation")

• `Optional` **schemaValidation**: `boolean`

Whether Convex should validate at runtime that all documents match your schema.

If `schemaValidation` is `true`, Convex will:

1. Check that all existing documents match your schema when your schema is pushed.
2. Check that all insertions and updates match your schema during mutations.

If `schemaValidation` is `false`, Convex will not validate that new or existing documents match your schema. You'll still get schema-specific TypeScript types, but there will be no validation at runtime that your documents match those types.

By default, `schemaValidation` is `true`.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/schema.ts:727](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L727)

***

### strictTableNameTypes[​](#stricttablenametypes "Direct link to strictTableNameTypes")

• `Optional` **strictTableNameTypes**: `StrictTableNameTypes`

Whether the TypeScript types should allow accessing tables not in the schema.

If `strictTableNameTypes` is `true`, using tables not listed in the schema will generate a TypeScript compilation error.

If `strictTableNameTypes` is `false`, you'll be able to access tables not listed in the schema and their document type will be `any`.

`strictTableNameTypes: false` is useful for rapid prototyping.

Regardless of the value of `strictTableNameTypes`, your schema will only validate documents in the tables listed in the schema. You can still create and modify other tables on the dashboard or in JavaScript mutations.

By default, `strictTableNameTypes` is `true`.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/schema.ts:746](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L746)

---

# Source: https://docs.convex.dev/api/classes/server.Expression.md

# Class: Expression\<T>

[server](/api/modules/server.md).Expression

Expressions are evaluated to produce a [Value](/api/modules/values.md#value) in the course of executing a query.

To construct an expression, use the [FilterBuilder](/api/interfaces/server.FilterBuilder.md) provided within [filter](/api/interfaces/server.OrderedQuery.md#filter).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type                                                           | Description                                 |
| ---- | -------------------------------------------------------------- | ------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) \| `undefined` | The type that this expression evaluates to. |

---

# Source: https://docs.convex.dev/api/interfaces/server.FilterBuilder.md

# Interface: FilterBuilder\<TableInfo>

[server](/api/modules/server.md).FilterBuilder

An interface for defining filters in queries.

`FilterBuilder` has various methods that produce [Expression](/api/classes/server.Expression.md)s. These expressions can be nested together along with constants to express a filter predicate.

`FilterBuilder` is used within [filter](/api/interfaces/server.OrderedQuery.md#filter) to create query filters.

Here are the available methods:

|                              |                                               |
| ---------------------------- | --------------------------------------------- |
| **Comparisons**              | Error when `l` and `r` are not the same type. |
| [`eq(l, r)`](#eq)            | `l === r`                                     |
| [`neq(l, r)`](#neq)          | `l !== r`                                     |
| [`lt(l, r)`](#lt)            | `l < r`                                       |
| [`lte(l, r)`](#lte)          | `l <= r`                                      |
| [`gt(l, r)`](#gt)            | `l > r`                                       |
| [`gte(l, r)`](#gte)          | `l >= r`                                      |
|                              |                                               |
| **Arithmetic**               | Error when `l` and `r` are not the same type. |
| [`add(l, r)`](#add)          | `l + r`                                       |
| [`sub(l, r)`](#sub)          | `l - r`                                       |
| [`mul(l, r)`](#mul)          | `l * r`                                       |
| [`div(l, r)`](#div)          | `l / r`                                       |
| [`mod(l, r)`](#mod)          | `l % r`                                       |
| [`neg(x)`](#neg)             | `-x`                                          |
|                              |                                               |
| **Logic**                    | Error if any param is not a `bool`.           |
| [`not(x)`](#not)             | `!x`                                          |
| [`and(a, b, ..., z)`](#and)  | `a && b && ... && z`                          |
| [`or(a, b, ..., z)`](#or)    | `a \|\| b \|\| ... \|\| z`                    |
|                              |                                               |
| **Other**                    |                                               |
| [`field(fieldPath)`](#field) | Evaluates to the field at `fieldPath`.        |

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

## Methods[​](#methods "Direct link to Methods")

### eq[​](#eq "Direct link to eq")

▸ **eq**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l === r`

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name | Type                                                           |
| ---- | -------------------------------------------------------------- |
| `T`  | extends `undefined` \| [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/filter\_builder.ts:87](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L87)

***

### neq[​](#neq "Direct link to neq")

▸ **neq**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l !== r`

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name | Type                                                           |
| ---- | -------------------------------------------------------------- |
| `T`  | extends `undefined` \| [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-1 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/filter\_builder.ts:97](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L97)

***

### lt[​](#lt "Direct link to lt")

▸ **lt**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l < r`

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name | Type                                            |
| ---- | ----------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-2 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/filter\_builder.ts:107](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L107)

***

### lte[​](#lte "Direct link to lte")

▸ **lte**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l <= r`

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name | Type                                            |
| ---- | ----------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-3 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/filter\_builder.ts:117](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L117)

***

### gt[​](#gt "Direct link to gt")

▸ **gt**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l > r`

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name | Type                                            |
| ---- | ----------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-4 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/filter\_builder.ts:127](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L127)

***

### gte[​](#gte "Direct link to gte")

▸ **gte**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`l >= r`

#### Type parameters[​](#type-parameters-6 "Direct link to Type parameters")

| Name | Type                                            |
| ---- | ----------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-5 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/filter\_builder.ts:137](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L137)

***

### add[​](#add "Direct link to add")

▸ **add**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`l + r`

#### Type parameters[​](#type-parameters-7 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-6 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/filter\_builder.ts:149](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L149)

***

### sub[​](#sub "Direct link to sub")

▸ **sub**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`l - r`

#### Type parameters[​](#type-parameters-8 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-7 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/filter\_builder.ts:159](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L159)

***

### mul[​](#mul "Direct link to mul")

▸ **mul**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`l * r`

#### Type parameters[​](#type-parameters-9 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-8 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-8 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/filter\_builder.ts:169](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L169)

***

### div[​](#div "Direct link to div")

▸ **div**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`l / r`

#### Type parameters[​](#type-parameters-10 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-9 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-9 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/filter\_builder.ts:179](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L179)

***

### mod[​](#mod "Direct link to mod")

▸ **mod**<`T`>(`l`, `r`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`l % r`

#### Type parameters[​](#type-parameters-11 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-10 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `l`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |
| `r`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-10 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/filter\_builder.ts:189](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L189)

***

### neg[​](#neg "Direct link to neg")

▸ **neg**<`T`>(`x`): [`Expression`](/api/classes/server.Expression.md)<`T`>

`-x`

#### Type parameters[​](#type-parameters-12 "Direct link to Type parameters")

| Name | Type                                                          |
| ---- | ------------------------------------------------------------- |
| `T`  | extends [`NumericValue`](/api/modules/values.md#numericvalue) |

#### Parameters[​](#parameters-11 "Direct link to Parameters")

| Name | Type                                                                 |
| ---- | -------------------------------------------------------------------- |
| `x`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`T`> |

#### Returns[​](#returns-11 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`T`>

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[server/filter\_builder.ts:199](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L199)

***

### and[​](#and "Direct link to and")

▸ **and**(`...exprs`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`exprs[0] && exprs[1] && ... && exprs[n]`

#### Parameters[​](#parameters-12 "Direct link to Parameters")

| Name       | Type                                                                          |
| ---------- | ----------------------------------------------------------------------------- |
| `...exprs` | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`>\[] |

#### Returns[​](#returns-12 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[server/filter\_builder.ts:208](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L208)

***

### or[​](#or "Direct link to or")

▸ **or**(`...exprs`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`exprs[0] || exprs[1] || ... || exprs[n]`

#### Parameters[​](#parameters-13 "Direct link to Parameters")

| Name       | Type                                                                          |
| ---------- | ----------------------------------------------------------------------------- |
| `...exprs` | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`>\[] |

#### Returns[​](#returns-13 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[server/filter\_builder.ts:215](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L215)

***

### not[​](#not "Direct link to not")

▸ **not**(`x`): [`Expression`](/api/classes/server.Expression.md)<`boolean`>

`!x`

#### Parameters[​](#parameters-14 "Direct link to Parameters")

| Name | Type                                                                       |
| ---- | -------------------------------------------------------------------------- |
| `x`  | [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`> |

#### Returns[​](#returns-14 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<`boolean`>

#### Defined in[​](#defined-in-14 "Direct link to Defined in")

[server/filter\_builder.ts:222](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L222)

***

### field[​](#field "Direct link to field")

▸ **field**<`FieldPath`>(`fieldPath`): [`Expression`](/api/classes/server.Expression.md)<[`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `FieldPath`>>

Evaluates to the field at the given `fieldPath`.

For example, in [filter](/api/interfaces/server.OrderedQuery.md#filter) this can be used to examine the values being filtered.

#### Example[​](#example "Direct link to Example")

On this object:

```
{
  "user": {
    "isActive": true
  }
}
```

`field("user.isActive")` evaluates to `true`.

#### Type parameters[​](#type-parameters-13 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `FieldPath` | extends `string` |

#### Parameters[​](#parameters-15 "Direct link to Parameters")

| Name        | Type        |
| ----------- | ----------- |
| `fieldPath` | `FieldPath` |

#### Returns[​](#returns-15 "Direct link to Returns")

[`Expression`](/api/classes/server.Expression.md)<[`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `FieldPath`>>

#### Defined in[​](#defined-in-15 "Direct link to Defined in")

[server/filter\_builder.ts:246](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L246)

---

# Source: https://docs.convex.dev/api/classes/server.FilterExpression.md

# Class: FilterExpression\<T>

[server](/api/modules/server.md).FilterExpression

Expressions are evaluated to produce a [Value](/api/modules/values.md#value) in the course of executing a query.

To construct an expression, use the [VectorFilterBuilder](/api/interfaces/server.VectorFilterBuilder.md) provided within [VectorSearchQuery](/api/interfaces/server.VectorSearchQuery.md).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type                                                           | Description                                 |
| ---- | -------------------------------------------------------------- | ------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) \| `undefined` | The type that this expression evaluates to. |

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericActionCtx.md

# Interface: GenericActionCtx\<DataModel>

[server](/api/modules/server.md).GenericActionCtx

A set of services for use within Convex action functions.

The context is passed as the first argument to any Convex action run on the server.

If you're using code generation, use the `ActionCtx` type in `convex/_generated/server.d.ts` which is typed for your data model.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Properties[​](#properties "Direct link to Properties")

### scheduler[​](#scheduler "Direct link to scheduler")

• **scheduler**: [`Scheduler`](/api/interfaces/server.Scheduler.md)

A utility for scheduling Convex functions to run in the future.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/registration.ts:236](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L236)

***

### auth[​](#auth "Direct link to auth")

• **auth**: [`Auth`](/api/interfaces/server.Auth.md)

Information about the currently authenticated user.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/registration.ts:241](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L241)

***

### storage[​](#storage "Direct link to storage")

• **storage**: [`StorageActionWriter`](/api/interfaces/server.StorageActionWriter.md)

A utility for reading and writing files in storage.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/registration.ts:246](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L246)

## Methods[​](#methods "Direct link to Methods")

### runQuery[​](#runquery "Direct link to runQuery")

▸ **runQuery**<`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Run the Convex query with the given name and arguments.

Consider using an internalQuery to prevent users from calling the query directly.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                                                           |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`, `"public"` \| `"internal"`> |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                   | Description                                                                           |
| --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `query`   | `Query`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the query to run. |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> | The arguments to the query function.                                                  |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

A promise of the query's result.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/registration.ts:196](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L196)

***

### runMutation[​](#runmutation "Direct link to runMutation")

▸ **runMutation**<`Mutation`>(`mutation`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

Run the Convex mutation with the given name and arguments.

Consider using an internalMutation to prevent users from calling the mutation directly.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name       | Type                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`, `"public"` \| `"internal"`> |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name       | Type                                                                      | Description                                                                              |
| ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `mutation` | `Mutation`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the mutation to run. |
| `...args`  | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Mutation`> | The arguments to the mutation function.                                                  |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

A promise of the mutation's result.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/registration.ts:211](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L211)

***

### runAction[​](#runaction "Direct link to runAction")

▸ **runAction**<`Action`>(`action`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

Run the Convex action with the given name and arguments.

Consider using an internalAction to prevent users from calling the action directly.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name     | Type                                                                                                            |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| `Action` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"action"`, `"public"` \| `"internal"`> |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name      | Type                                                                    | Description                                                                            |
| --------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `action`  | `Action`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the action to run. |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Action`> | The arguments to the action function.                                                  |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Action`>>

A promise of the action's result.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/registration.ts:228](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L228)

***

### vectorSearch[​](#vectorsearch "Direct link to vectorSearch")

▸ **vectorSearch**<`TableName`, `IndexName`>(`tableName`, `indexName`, `query`): `Promise`<{ `_id`: [`GenericId`](/api/modules/values.md#genericid)<`TableName`> ; `_score`: `number` }\[]>

Run a vector search on the given table and index.

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name        | Type                                     |
| ----------- | ---------------------------------------- |
| `TableName` | extends `string`                         |
| `IndexName` | extends `string` \| `number` \| `symbol` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name            | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Description                                                                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableName`     | `TableName`                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The name of the table to query.                                                                                                                                                  |
| `indexName`     | `IndexName`                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The name of the vector index on the table to query.                                                                                                                              |
| `query`         | `Object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | A [VectorSearchQuery](/api/interfaces/server.VectorSearchQuery.md) containing the vector to query, the number of results to return, and any filters.                             |
| `query.vector`  | `number`\[]                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The query vector. This must have the same length as the `dimensions` of the index. This vector search will return the IDs of the documents most similar to this vector.          |
| `query.limit?`  | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The number of results to return. If specified, must be between 1 and 256 inclusive. **`Default`** `ts 10`                                                                        |
| `query.filter?` | (`q`: [`VectorFilterBuilder`](/api/interfaces/server.VectorFilterBuilder.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>, [`NamedVectorIndex`](/api/modules/server.md#namedvectorindex)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>, `IndexName`>>) => [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`> | Optional filter expression made up of `q.or` and `q.eq` operating over the filter fields of the index. e.g. `filter: q => q.or(q.eq("genre", "comedy"), q.eq("genre", "drama"))` |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<{ `_id`: [`GenericId`](/api/modules/values.md#genericid)<`TableName`> ; `_score`: `number` }\[]>

A promise of IDs and scores for the documents with the nearest vectors

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/registration.ts:258](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L258)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericDatabaseReader.md

# Interface: GenericDatabaseReader\<DataModel>

[server](/api/modules/server.md).GenericDatabaseReader

An interface to read from the database within Convex query functions.

The two entry points are:

* [get](/api/interfaces/server.GenericDatabaseReader.md#get), which fetches a single document by its [GenericId](/api/modules/values.md#genericid).
* [query](/api/interfaces/server.GenericDatabaseReader.md#query), which starts building a query.

If you're using code generation, use the `DatabaseReader` type in `convex/_generated/server.d.ts` which is typed for your data model.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseDatabaseReader`<`DataModel`>

  ↳ **`GenericDatabaseReader`**

  ↳↳ [`GenericDatabaseWriter`](/api/interfaces/server.GenericDatabaseWriter.md)

## Properties[​](#properties "Direct link to Properties")

### system[​](#system "Direct link to system")

• **system**: `BaseDatabaseReader`<[`SystemDataModel`](/api/interfaces/server.SystemDataModel.md)>

An interface to read from the system tables within Convex query functions

The two entry points are:

* [get](/api/interfaces/server.GenericDatabaseReader.md#get), which fetches a single document by its [GenericId](/api/modules/values.md#genericid).
* [query](/api/interfaces/server.GenericDatabaseReader.md#query), which starts building a query.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:128](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L128)

## Methods[​](#methods "Direct link to Methods")

### get[​](#get "Direct link to get")

▸ **get**<`TableName`>(`table`, `id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the database by its [GenericId](/api/modules/values.md#genericid).

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name    | Type                                                                     | Description                                                                                   |
| ------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `table` | `TableName`                                                              | The name of the table to fetch the document from.                                             |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`NonUnion`<`TableName`>> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseDatabaseReader.get

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:23](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L23)

▸ **get**<`TableName`>(`id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the database by its [GenericId](/api/modules/values.md#genericid).

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name | Type                                                         | Description                                                                                   |
| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseDatabaseReader.get

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/database.ts:34](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L34)

***

### query[​](#query "Direct link to query")

▸ **query**<`TableName`>(`tableName`): [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

Begin a query for the given table name.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type        | Description                     |
| ----------- | ----------- | ------------------------------- |
| `tableName` | `TableName` | The name of the table to query. |

#### Returns[​](#returns-2 "Direct link to Returns")

[`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

* A [QueryInitializer](/api/interfaces/server.QueryInitializer.md) object to start building a query.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseDatabaseReader.query

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/database.ts:47](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L47)

***

### normalizeId[​](#normalizeid "Direct link to normalizeId")

▸ **normalizeId**<`TableName`>(`tableName`, `id`): `null` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>

Returns the string ID format for the ID in a given table, or null if the ID is from a different table or is not a valid ID.

This accepts the string ID format as well as the `.toString()` representation of the legacy class-based ID format.

This does not guarantee that the ID exists (i.e. `db.get(id)` may return `null`).

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type        | Description            |
| ----------- | ----------- | ---------------------- |
| `tableName` | `TableName` | The name of the table. |
| `id`        | `string`    | The ID string.         |

#### Returns[​](#returns-3 "Direct link to Returns")

`null` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseDatabaseReader.normalizeId

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/database.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L63)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericDatabaseReaderWithTable.md

# Interface: GenericDatabaseReaderWithTable\<DataModel>

[server](/api/modules/server.md).GenericDatabaseReaderWithTable

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseDatabaseReaderWithTable`<`DataModel`>

  ↳ **`GenericDatabaseReaderWithTable`**

  ↳↳ [`GenericDatabaseWriterWithTable`](/api/interfaces/server.GenericDatabaseWriterWithTable.md)

## Properties[​](#properties "Direct link to Properties")

### system[​](#system "Direct link to system")

• **system**: `BaseDatabaseReaderWithTable`<[`SystemDataModel`](/api/interfaces/server.SystemDataModel.md)>

An interface to read from the system tables within Convex query functions

The two entry points are:

* [get](/api/interfaces/server.GenericDatabaseReader.md#get), which fetches a single document by its [GenericId](/api/modules/values.md#genericid).
* [query](/api/interfaces/server.GenericDatabaseReader.md#query), which starts building a query.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:144](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L144)

## Methods[​](#methods "Direct link to Methods")

### table[​](#table "Direct link to table")

▸ **table**<`TableName`>(`tableName`): [`BaseTableReader`](/api/interfaces/server.BaseTableReader.md)<`DataModel`, `TableName`>

Scope the database to a specific table.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type        |
| ----------- | ----------- |
| `tableName` | `TableName` |

#### Returns[​](#returns "Direct link to Returns")

[`BaseTableReader`](/api/interfaces/server.BaseTableReader.md)<`DataModel`, `TableName`>

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseDatabaseReaderWithTable.table

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:73](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L73)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericDatabaseWriter.md

# Interface: GenericDatabaseWriter\<DataModel>

[server](/api/modules/server.md).GenericDatabaseWriter

An interface to read from and write to the database within Convex mutation functions.

Convex guarantees that all writes within a single mutation are executed atomically, so you never have to worry about partial writes leaving your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control) for the guarantees Convex provides your functions.

If you're using code generation, use the `DatabaseReader` type in `convex/_generated/server.d.ts` which is typed for your data model.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`GenericDatabaseReader`](/api/interfaces/server.GenericDatabaseReader.md)<`DataModel`>

  ↳ **`GenericDatabaseWriter`**

## Properties[​](#properties "Direct link to Properties")

### system[​](#system "Direct link to system")

• **system**: `BaseDatabaseReader`<[`SystemDataModel`](/api/interfaces/server.SystemDataModel.md)>

An interface to read from the system tables within Convex query functions

The two entry points are:

* [get](/api/interfaces/server.GenericDatabaseReader.md#get), which fetches a single document by its [GenericId](/api/modules/values.md#genericid).
* [query](/api/interfaces/server.GenericDatabaseReader.md#query), which starts building a query.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md).[system](/api/interfaces/server.GenericDatabaseReader.md#system)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:128](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L128)

## Methods[​](#methods "Direct link to Methods")

### get[​](#get "Direct link to get")

▸ **get**<`TableName`>(`table`, `id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the database by its [GenericId](/api/modules/values.md#genericid).

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name    | Type                                                                     | Description                                                                                   |
| ------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `table` | `TableName`                                                              | The name of the table to fetch the document from.                                             |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`NonUnion`<`TableName`>> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md).[get](/api/interfaces/server.GenericDatabaseReader.md#get)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:23](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L23)

▸ **get**<`TableName`>(`id`): `Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

Fetch a single document from the database by its [GenericId](/api/modules/values.md#genericid).

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name | Type                                                         | Description                                                                                   |
| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> | The [GenericId](/api/modules/values.md#genericid) of the document to fetch from the database. |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`null` | [`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>>

* The [GenericDocument](/api/modules/server.md#genericdocument) of the document at the given [GenericId](/api/modules/values.md#genericid), or `null` if it no longer exists.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md).[get](/api/interfaces/server.GenericDatabaseReader.md#get)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/database.ts:34](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L34)

***

### query[​](#query "Direct link to query")

▸ **query**<`TableName`>(`tableName`): [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

Begin a query for the given table name.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type        | Description                     |
| ----------- | ----------- | ------------------------------- |
| `tableName` | `TableName` | The name of the table to query. |

#### Returns[​](#returns-2 "Direct link to Returns")

[`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>>

* A [QueryInitializer](/api/interfaces/server.QueryInitializer.md) object to start building a query.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md).[query](/api/interfaces/server.GenericDatabaseReader.md#query)

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/database.ts:47](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L47)

***

### normalizeId[​](#normalizeid "Direct link to normalizeId")

▸ **normalizeId**<`TableName`>(`tableName`, `id`): `null` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>

Returns the string ID format for the ID in a given table, or null if the ID is from a different table or is not a valid ID.

This accepts the string ID format as well as the `.toString()` representation of the legacy class-based ID format.

This does not guarantee that the ID exists (i.e. `db.get(id)` may return `null`).

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type        | Description            |
| ----------- | ----------- | ---------------------- |
| `tableName` | `TableName` | The name of the table. |
| `id`        | `string`    | The ID string.         |

#### Returns[​](#returns-3 "Direct link to Returns")

`null` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md).[normalizeId](/api/interfaces/server.GenericDatabaseReader.md#normalizeid)

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/database.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L63)

***

### insert[​](#insert "Direct link to insert")

▸ **insert**<`TableName`>(`table`, `value`): `Promise`<[`GenericId`](/api/modules/values.md#genericid)<`TableName`>>

Insert a new document into a table.

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name    | Type                                                                                                                                                     | Description                                                               |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `table` | `TableName`                                                                                                                                              | The name of the table to insert a new document into.                      |
| `value` | [`WithoutSystemFields`](/api/modules/server.md#withoutsystemfields)<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The [Value](/api/modules/values.md#value) to insert into the given table. |

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<[`GenericId`](/api/modules/values.md#genericid)<`TableName`>>

* [GenericId](/api/modules/values.md#genericid) of the new document.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/database.ts:170](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L170)

***

### patch[​](#patch "Direct link to patch")

▸ **patch**<`TableName`>(`table`, `id`, `value`): `Promise`<`void`>

Patch an existing document, shallow merging it with the given partial document.

New fields are added. Existing fields are overwritten. Fields set to `undefined` are removed.

#### Type parameters[​](#type-parameters-6 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name    | Type                                                                                              | Description                                                                                                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table` | `TableName`                                                                                       | The name of the table the document is in.                                                                                                                                                                               |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`NonUnion`<`TableName`>>                          | The [GenericId](/api/modules/values.md#genericid) of the document to patch.                                                                                                                                             |
| `value` | `PatchValue`<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The partial [GenericDocument](/api/modules/server.md#genericdocument) to merge into the specified document. If this new value specifies system fields like `_id`, they must match the document's existing field values. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/database.ts:187](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L187)

▸ **patch**<`TableName`>(`id`, `value`): `Promise`<`void`>

Patch an existing document, shallow merging it with the given partial document.

New fields are added. Existing fields are overwritten. Fields set to `undefined` are removed.

#### Type parameters[​](#type-parameters-7 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name    | Type                                                                                              | Description                                                                                                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>                                      | The [GenericId](/api/modules/values.md#genericid) of the document to patch.                                                                                                                                             |
| `value` | `PatchValue`<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The partial [GenericDocument](/api/modules/server.md#genericdocument) to merge into the specified document. If this new value specifies system fields like `_id`, they must match the document's existing field values. |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/database.ts:204](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L204)

***

### replace[​](#replace "Direct link to replace")

▸ **replace**<`TableName`>(`table`, `id`, `value`): `Promise`<`void`>

Replace the value of an existing document, overwriting its old value.

#### Type parameters[​](#type-parameters-8 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name    | Type                                                                                                                                                               | Description                                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table` | `TableName`                                                                                                                                                        | The name of the table the document is in.                                                                                                                      |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`NonUnion`<`TableName`>>                                                                                           | The [GenericId](/api/modules/values.md#genericid) of the document to replace.                                                                                  |
| `value` | [`WithOptionalSystemFields`](/api/modules/server.md#withoptionalsystemfields)<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The new [GenericDocument](/api/modules/server.md#genericdocument) for the document. This value can omit the system fields, and the database will fill them in. |

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/database.ts:217](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L217)

▸ **replace**<`TableName`>(`id`, `value`): `Promise`<`void`>

Replace the value of an existing document, overwriting its old value.

#### Type parameters[​](#type-parameters-9 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-8 "Direct link to Parameters")

| Name    | Type                                                                                                                                                               | Description                                                                                                                                                    |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`TableName`>                                                                                                       | The [GenericId](/api/modules/values.md#genericid) of the document to replace.                                                                                  |
| `value` | [`WithOptionalSystemFields`](/api/modules/server.md#withoptionalsystemfields)<[`DocumentByName`](/api/modules/server.md#documentbyname)<`DataModel`, `TableName`>> | The new [GenericDocument](/api/modules/server.md#genericdocument) for the document. This value can omit the system fields, and the database will fill them in. |

#### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/database.ts:230](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L230)

***

### delete[​](#delete "Direct link to delete")

▸ **delete**<`TableName`>(`table`, `id`): `Promise`<`void`>

Delete an existing document.

#### Type parameters[​](#type-parameters-10 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters-9 "Direct link to Parameters")

| Name    | Type                                                                     | Description                                                                  |
| ------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `table` | `TableName`                                                              | The name of the table the document is in.                                    |
| `id`    | [`GenericId`](/api/modules/values.md#genericid)<`NonUnion`<`TableName`>> | The [GenericId](/api/modules/values.md#genericid) of the document to remove. |

#### Returns[​](#returns-9 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/database.ts:241](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L241)

▸ **delete**(`id`): `Promise`<`void`>

Delete an existing document.

#### Parameters[​](#parameters-10 "Direct link to Parameters")

| Name | Type                                                                                                                                  | Description                                                                  |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<[`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<`DataModel`>> | The [GenericId](/api/modules/values.md#genericid) of the document to remove. |

#### Returns[​](#returns-10 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[server/database.ts:251](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L251)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericDatabaseWriterWithTable.md

# Interface: GenericDatabaseWriterWithTable\<DataModel>

[server](/api/modules/server.md).GenericDatabaseWriterWithTable

An interface to read from and write to the database within Convex mutation functions.

Convex guarantees that all writes within a single mutation are executed atomically, so you never have to worry about partial writes leaving your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control) for the guarantees Convex provides your functions.

If you're using code generation, use the `DatabaseReader` type in `convex/_generated/server.d.ts` which is typed for your data model.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`GenericDatabaseReaderWithTable`](/api/interfaces/server.GenericDatabaseReaderWithTable.md)<`DataModel`>

  ↳ **`GenericDatabaseWriterWithTable`**

## Properties[​](#properties "Direct link to Properties")

### system[​](#system "Direct link to system")

• **system**: `BaseDatabaseReaderWithTable`<[`SystemDataModel`](/api/interfaces/server.SystemDataModel.md)>

An interface to read from the system tables within Convex query functions

The two entry points are:

* [get](/api/interfaces/server.GenericDatabaseReader.md#get), which fetches a single document by its [GenericId](/api/modules/values.md#genericid).
* [query](/api/interfaces/server.GenericDatabaseReader.md#query), which starts building a query.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[GenericDatabaseReaderWithTable](/api/interfaces/server.GenericDatabaseReaderWithTable.md).[system](/api/interfaces/server.GenericDatabaseReaderWithTable.md#system)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/database.ts:144](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L144)

## Methods[​](#methods "Direct link to Methods")

### table[​](#table "Direct link to table")

▸ **table**<`TableName`>(`tableName`): [`BaseTableWriter`](/api/interfaces/server.BaseTableWriter.md)<`DataModel`, `TableName`>

Scope the database to a specific table.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type        |
| ----------- | ----------- |
| `tableName` | `TableName` |

#### Returns[​](#returns "Direct link to Returns")

[`BaseTableWriter`](/api/interfaces/server.BaseTableWriter.md)<`DataModel`, `TableName`>

#### Overrides[​](#overrides "Direct link to Overrides")

[GenericDatabaseReaderWithTable](/api/interfaces/server.GenericDatabaseReaderWithTable.md).[table](/api/interfaces/server.GenericDatabaseReaderWithTable.md#table)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/database.ts:274](https://github.com/get-convex/convex-js/blob/main/src/server/database.ts#L274)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericMutationCtx.md

# Interface: GenericMutationCtx\<DataModel>

[server](/api/modules/server.md).GenericMutationCtx

A set of services for use within Convex mutation functions.

The mutation context is passed as the first argument to any Convex mutation function run on the server.

If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` which is typed for your data model.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Properties[​](#properties "Direct link to Properties")

### db[​](#db "Direct link to db")

• **db**: [`GenericDatabaseWriter`](/api/interfaces/server.GenericDatabaseWriter.md)<`DataModel`>

A utility for reading and writing data in the database.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/registration.ts:50](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L50)

***

### auth[​](#auth "Direct link to auth")

• **auth**: [`Auth`](/api/interfaces/server.Auth.md)

Information about the currently authenticated user.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/registration.ts:55](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L55)

***

### storage[​](#storage "Direct link to storage")

• **storage**: [`StorageWriter`](/api/interfaces/server.StorageWriter.md)

A utility for reading and writing files in storage.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/registration.ts:60](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L60)

***

### scheduler[​](#scheduler "Direct link to scheduler")

• **scheduler**: [`Scheduler`](/api/interfaces/server.Scheduler.md)

A utility for scheduling Convex functions to run in the future.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/registration.ts:65](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L65)

***

### runQuery[​](#runquery "Direct link to runQuery")

• **runQuery**: \<Query>(`query`: `Query`, ...`args`: [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`>) => `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

▸ <`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Call a query function within the same transaction.

NOTE: often you can call the query's function directly instead of using this. `runQuery` incurs overhead of running argument and return value validation, and creating a new isolated JS context.

##### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                                                           |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`, `"public"` \| `"internal"`> |

##### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                   |
| --------- | ---------------------------------------------------------------------- |
| `query`   | `Query`                                                                |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> |

##### Returns[​](#returns "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/registration.ts:74](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L74)

***

### runMutation[​](#runmutation "Direct link to runMutation")

• **runMutation**: \<Mutation>(`mutation`: `Mutation`, ...`args`: [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Mutation`>) => `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

▸ <`Mutation`>(`mutation`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

Call a mutation function within the same transaction.

NOTE: often you can call the mutation's function directly instead of using this. `runMutation` incurs overhead of running argument and return value validation, and creating a new isolated JS context.

The mutation runs in a sub-transaction, so if the mutation throws an error, all of its writes will be rolled back. Additionally, a successful mutation's writes will be serializable with other writes in the transaction.

##### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name       | Type                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `Mutation` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"`, `"public"` \| `"internal"`> |

##### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name       | Type                                                                      |
| ---------- | ------------------------------------------------------------------------- |
| `mutation` | `Mutation`                                                                |
| `...args`  | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Mutation`> |

##### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Mutation`>>

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/registration.ts:90](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L90)

---

# Source: https://docs.convex.dev/api/interfaces/server.GenericQueryCtx.md

# Interface: GenericQueryCtx\<DataModel>

[server](/api/modules/server.md).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.

This differs from the MutationCtx because all of the services are read-only.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

## Properties[​](#properties "Direct link to Properties")

### db[​](#db "Direct link to db")

• **db**: [`GenericDatabaseReader`](/api/interfaces/server.GenericDatabaseReader.md)<`DataModel`>

A utility for reading data in the database.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/registration.ts:130](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L130)

***

### auth[​](#auth "Direct link to auth")

• **auth**: [`Auth`](/api/interfaces/server.Auth.md)

Information about the currently authenticated user.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/registration.ts:135](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L135)

***

### storage[​](#storage "Direct link to storage")

• **storage**: [`StorageReader`](/api/interfaces/server.StorageReader.md)

A utility for reading files in storage.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/registration.ts:140](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L140)

***

### runQuery[​](#runquery "Direct link to runQuery")

• **runQuery**: \<Query>(`query`: `Query`, ...`args`: [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`>) => `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

▸ <`Query`>(`query`, `...args`): `Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

Call a query function within the same transaction.

NOTE: often you can call the query's function directly instead of using this. `runQuery` incurs overhead of running argument and return value validation, and creating a new isolated JS context.

##### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                                                                                           |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| `Query` | extends [`FunctionReference`](/api/modules/server.md#functionreference)<`"query"`, `"public"` \| `"internal"`> |

##### Parameters[​](#parameters "Direct link to Parameters")

| Name      | Type                                                                   |
| --------- | ---------------------------------------------------------------------- |
| `query`   | `Query`                                                                |
| `...args` | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`Query`> |

##### Returns[​](#returns "Direct link to Returns")

`Promise`<[`FunctionReturnType`](/api/modules/server.md#functionreturntype)<`Query`>>

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/registration.ts:149](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L149)

---

# Source: https://docs.convex.dev/api/classes/server.HttpRouter.md

# Class: HttpRouter

[server](/api/modules/server.md).HttpRouter

HTTP router for specifying the paths and methods of [httpActionGeneric](/api/modules/server.md#httpactiongeneric)s

An example `convex/http.js` file might look like this.

```
import { httpRouter } from "convex/server";
import { getMessagesByAuthor } from "./getMessagesByAuthor";
import { httpAction } from "./_generated/server";

const http = httpRouter();

// HTTP actions can be defined inline...
http.route({
  path: "/message",
  method: "POST",
  handler: httpAction(async ({ runMutation }, request) => {
    const { author, body } = await request.json();

    await runMutation(api.sendMessage.default, { body, author });
    return new Response(null, {
      status: 200,
    });
  })
});

// ...or they can be imported from other files.
http.route({
  path: "/getMessagesByAuthor",
  method: "GET",
  handler: getMessagesByAuthor,
});

// Convex expects the router to be the default export of `convex/http.js`.
export default http;
```

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new HttpRouter**()

## Properties[​](#properties "Direct link to Properties")

### exactRoutes[​](#exactroutes "Direct link to exactRoutes")

• **exactRoutes**: `Map`<`string`, `Map`<`"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, [`PublicHttpAction`](/api/modules/server.md#publichttpaction)>>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/router.ts:143](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L143)

***

### prefixRoutes[​](#prefixroutes "Direct link to prefixRoutes")

• **prefixRoutes**: `Map`<`"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, `Map`<`string`, [`PublicHttpAction`](/api/modules/server.md#publichttpaction)>>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/router.ts:144](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L144)

***

### isRouter[​](#isrouter "Direct link to isRouter")

• **isRouter**: `true`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/router.ts:145](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L145)

## Methods[​](#methods "Direct link to Methods")

### route[​](#route "Direct link to route")

▸ **route**(`spec`): `void`

Specify an HttpAction to be used to respond to requests for an HTTP method (e.g. "GET") and a path or pathPrefix.

Paths must begin with a slash. Path prefixes must also end in a slash.

```
// matches `/profile` (but not `/profile/`)
http.route({ path: "/profile", method: "GET", handler: getProfile})

// matches `/profiles/`, `/profiles/abc`, and `/profiles/a/c/b` (but not `/profile`)
http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile})
```

#### Parameters[​](#parameters "Direct link to Parameters")

| Name   | Type                                            |
| ------ | ----------------------------------------------- |
| `spec` | [`RouteSpec`](/api/modules/server.md#routespec) |

#### Returns[​](#returns "Direct link to Returns")

`void`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/router.ts:161](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L161)

***

### getRoutes[​](#getroutes "Direct link to getRoutes")

▸ **getRoutes**(): readonly \[`string`, `"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, [`PublicHttpAction`](/api/modules/server.md#publichttpaction)]\[]

Returns a list of routed HTTP actions.

These are used to populate the list of routes shown in the Functions page of the Convex dashboard.

#### Returns[​](#returns-1 "Direct link to Returns")

readonly \[`string`, `"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, [`PublicHttpAction`](/api/modules/server.md#publichttpaction)]\[]

* an array of \[path, method, endpoint] tuples.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/router.ts:229](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L229)

***

### lookup[​](#lookup "Direct link to lookup")

▸ **lookup**(`path`, `method`): `null` | readonly \[[`PublicHttpAction`](/api/modules/server.md#publichttpaction), `"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, `string`]

Returns the appropriate HTTP action and its routed request path and method.

The path and method returned are used for logging and metrics, and should match up with one of the routes returned by `getRoutes`.

For example,

```
http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile});

http.lookup("/profile/abc", "GET") // returns [getProfile, "GET", "/profile/*"]
```

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name     | Type                                                                                 |
| -------- | ------------------------------------------------------------------------------------ |
| `path`   | `string`                                                                             |
| `method` | `"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"` \| `"OPTIONS"` \| `"PATCH"` \| `"HEAD"` |

#### Returns[​](#returns-2 "Direct link to Returns")

`null` | readonly \[[`PublicHttpAction`](/api/modules/server.md#publichttpaction), `"GET"` | `"POST"` | `"PUT"` | `"DELETE"` | `"OPTIONS"` | `"PATCH"`, `string`]

* a tuple \[[PublicHttpAction](/api/modules/server.md#publichttpaction), method, path] or null.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/router.ts:275](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L275)

***

### runRequest[​](#runrequest "Direct link to runRequest")

▸ **runRequest**(`argsStr`, `requestRoute`): `Promise`<`string`>

Given a JSON string representation of a Request object, return a Response by routing the request and running the appropriate endpoint or returning a 404 Response.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name           | Type     | Description                                  |
| -------------- | -------- | -------------------------------------------- |
| `argsStr`      | `string` | a JSON string representing a Request object. |
| `requestRoute` | `string` | -                                            |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`string`>

* a Response object.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/router.ts:304](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L304)

---

# Source: https://docs.convex.dev/api/classes/server.IndexRange.md

# Class: IndexRange

[server](/api/modules/server.md).IndexRange

An expression representing an index range created by [IndexRangeBuilder](/api/interfaces/server.IndexRangeBuilder.md).

---

# Source: https://docs.convex.dev/api/interfaces/server.IndexRangeBuilder.md

# Interface: IndexRangeBuilder\<Document, IndexFields, FieldNum>

[server](/api/modules/server.md).IndexRangeBuilder

Builder to define an index range to query.

An index range is a description of which documents Convex should consider when running the query.

An index range is always a chained list of:

1. 0 or more equality expressions defined with `.eq`.
2. \[Optionally] A lower bound expression defined with `.gt` or `.gte`.
3. \[Optionally] An upper bound expression defined with `.lt` or `.lte`.

**You must step through fields in index order.**

Each equality expression must compare a different index field, starting from the beginning and in order. The upper and lower bounds must follow the equality expressions and compare the next field.

For example, if there is an index of messages on `["projectId", "priority"]`, a range searching for "messages in 'myProjectId' with priority at least 100" would look like:

```
q.eq("projectId", myProjectId)
 .gte("priority", 100)
```

**The performance of your query is based on the specificity of the range.**

This class is designed to only allow you to specify ranges that Convex can efficiently use your index to find. For all other filtering use [filter](/api/interfaces/server.OrderedQuery.md#filter).

To learn about indexes, see [Indexes](https://docs.convex.dev/using/indexes).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name          | Type                                                                      |
| ------------- | ------------------------------------------------------------------------- |
| `Document`    | extends [`GenericDocument`](/api/modules/server.md#genericdocument)       |
| `IndexFields` | extends [`GenericIndexFields`](/api/modules/server.md#genericindexfields) |
| `FieldNum`    | extends `number` = `0`                                                    |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `LowerBoundIndexRangeBuilder`<`Document`, `IndexFields`\[`FieldNum`]>

  ↳ **`IndexRangeBuilder`**

## Methods[​](#methods "Direct link to Methods")

### eq[​](#eq "Direct link to eq")

▸ **eq**(`fieldName`, `value`): `NextIndexRangeBuilder`<`Document`, `IndexFields`, `FieldNum`>

Restrict this range to documents where `doc[fieldName] === value`.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                                                                              | Description                                                            |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `fieldName` | `IndexFields`\[`FieldNum`]                                                                                        | The name of the field to compare. Must be the next field in the index. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `IndexFields`\[`FieldNum`]> | The value to compare against.                                          |

#### Returns[​](#returns "Direct link to Returns")

`NextIndexRangeBuilder`<`Document`, `IndexFields`, `FieldNum`>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/index\_range\_builder.ts:76](https://github.com/get-convex/convex-js/blob/main/src/server/index_range_builder.ts#L76)

***

### gt[​](#gt "Direct link to gt")

▸ **gt**(`fieldName`, `value`): `UpperBoundIndexRangeBuilder`<`Document`, `IndexFields`\[`FieldNum`]>

Restrict this range to documents where `doc[fieldName] > value`.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type                                                                                                              | Description                                                            |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `fieldName` | `IndexFields`\[`FieldNum`]                                                                                        | The name of the field to compare. Must be the next field in the index. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `IndexFields`\[`FieldNum`]> | The value to compare against.                                          |

#### Returns[​](#returns-1 "Direct link to Returns")

`UpperBoundIndexRangeBuilder`<`Document`, `IndexFields`\[`FieldNum`]>

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

LowerBoundIndexRangeBuilder.gt

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/index\_range\_builder.ts:115](https://github.com/get-convex/convex-js/blob/main/src/server/index_range_builder.ts#L115)

***

### gte[​](#gte "Direct link to gte")

▸ **gte**(`fieldName`, `value`): `UpperBoundIndexRangeBuilder`<`Document`, `IndexFields`\[`FieldNum`]>

Restrict this range to documents where `doc[fieldName] >= value`.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type                                                                                                              | Description                                                            |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `fieldName` | `IndexFields`\[`FieldNum`]                                                                                        | The name of the field to compare. Must be the next field in the index. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `IndexFields`\[`FieldNum`]> | The value to compare against.                                          |

#### Returns[​](#returns-2 "Direct link to Returns")

`UpperBoundIndexRangeBuilder`<`Document`, `IndexFields`\[`FieldNum`]>

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

LowerBoundIndexRangeBuilder.gte

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/index\_range\_builder.ts:126](https://github.com/get-convex/convex-js/blob/main/src/server/index_range_builder.ts#L126)

***

### lt[​](#lt "Direct link to lt")

▸ **lt**(`fieldName`, `value`): [`IndexRange`](/api/classes/server.IndexRange.md)

Restrict this range to documents where `doc[fieldName] < value`.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type                                                                                                              | Description                                                                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fieldName` | `IndexFields`\[`FieldNum`]                                                                                        | The name of the field to compare. Must be the same index field used in the lower bound (`.gt` or `.gte`) or the next field if no lower bound was specified. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `IndexFields`\[`FieldNum`]> | The value to compare against.                                                                                                                               |

#### Returns[​](#returns-3 "Direct link to Returns")

[`IndexRange`](/api/classes/server.IndexRange.md)

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

LowerBoundIndexRangeBuilder.lt

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/index\_range\_builder.ts:151](https://github.com/get-convex/convex-js/blob/main/src/server/index_range_builder.ts#L151)

***

### lte[​](#lte "Direct link to lte")

▸ **lte**(`fieldName`, `value`): [`IndexRange`](/api/classes/server.IndexRange.md)

Restrict this range to documents where `doc[fieldName] <= value`.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name        | Type                                                                                                              | Description                                                                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fieldName` | `IndexFields`\[`FieldNum`]                                                                                        | The name of the field to compare. Must be the same index field used in the lower bound (`.gt` or `.gte`) or the next field if no lower bound was specified. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `IndexFields`\[`FieldNum`]> | The value to compare against.                                                                                                                               |

#### Returns[​](#returns-4 "Direct link to Returns")

[`IndexRange`](/api/classes/server.IndexRange.md)

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

LowerBoundIndexRangeBuilder.lte

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/index\_range\_builder.ts:164](https://github.com/get-convex/convex-js/blob/main/src/server/index_range_builder.ts#L164)

---

# Source: https://docs.convex.dev/api/interfaces/server.OrderedQuery.md

# Interface: OrderedQuery\<TableInfo>

[server](/api/modules/server.md).OrderedQuery

A [Query](/api/interfaces/server.Query.md) with an order that has already been defined.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `AsyncIterable`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

  ↳ **`OrderedQuery`**

  ↳↳ [`Query`](/api/interfaces/server.Query.md)

## Methods[​](#methods "Direct link to Methods")

### \[asyncIterator][​](#asynciterator "Direct link to \[asyncIterator]")

▸ **\[asyncIterator]**(): `AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Returns[​](#returns "Direct link to Returns")

`AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

AsyncIterable.\[asyncIterator]

#### Defined in[​](#defined-in "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es2018.asynciterable.d.ts:38

***

### filter[​](#filter "Direct link to filter")

▸ **filter**(`predicate`): [`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

Filter the query output, returning only the values for which `predicate` evaluates to true.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                                                                                                                         | Description                                                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `predicate` | (`q`: [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md)<`TableInfo`>) => [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`> | An [Expression](/api/classes/server.Expression.md) constructed with the supplied [FilterBuilder](/api/interfaces/server.FilterBuilder.md) that specifies which documents to keep. |

#### Returns[​](#returns-1 "Direct link to Returns")

[`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

* A new [OrderedQuery](/api/interfaces/server.OrderedQuery.md) with the given filter predicate applied.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/query.ts:165](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L165)

***

### paginate[​](#paginate "Direct link to paginate")

▸ **paginate**(`paginationOpts`): `Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

Load a page of `n` results and obtain a [Cursor](/api/modules/server.md#cursor) for loading more.

Note: If this is called from a reactive query function the number of results may not match `paginationOpts.numItems`!

`paginationOpts.numItems` is only an initial value. After the first invocation, `paginate` will return all items in the original query range. This ensures that all pages will remain adjacent and non-overlapping.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name             | Type                                                               | Description                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `paginationOpts` | [`PaginationOptions`](/api/interfaces/server.PaginationOptions.md) | A [PaginationOptions](/api/interfaces/server.PaginationOptions.md) object containing the number of items to load and the cursor to start at. |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

A [PaginationResult](/api/interfaces/server.PaginationResult.md) containing the page of results and a cursor to continue paginating.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/query.ts:194](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L194)

***

### collect[​](#collect "Direct link to collect")

▸ **collect**(): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return all of the results as an array.

Note: when processing a query with a lot of results, it's often better to use the `Query` as an `AsyncIterable` instead.

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of all of the query's results.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/query.ts:206](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L206)

***

### take[​](#take "Direct link to take")

▸ **take**(`n`): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return the first `n` results.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name | Type     | Description                  |
| ---- | -------- | ---------------------------- |
| `n`  | `number` | The number of items to take. |

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of the first `n` results of the query (or less if the query doesn't have `n` results).

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/query.ts:215](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L215)

***

### first[​](#first "Direct link to first")

▸ **first**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the first result if there is one.

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The first value of the query or `null` if the query returned no results.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/query.ts:222](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L222)

***

### unique[​](#unique "Direct link to unique")

▸ **unique**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the singular result if there is one.

**`Throws`**

Will throw an error if the query returns more than one result.

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The single result returned from the query or null if none exists.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/query.ts:230](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L230)

---

# Source: https://docs.convex.dev/api/interfaces/server.PaginationOptions.md

# Interface: PaginationOptions

[server](/api/modules/server.md).PaginationOptions

The options passed to [paginate](/api/interfaces/server.OrderedQuery.md#paginate).

To use this type in [argument validation](https://docs.convex.dev/functions/validation), use the [paginationOptsValidator](/api/modules/server.md#paginationoptsvalidator).

## Properties[​](#properties "Direct link to Properties")

### numItems[​](#numitems "Direct link to numItems")

• **numItems**: `number`

Number of items to load in this page of results.

Note: This is only an initial value!

If you are running this paginated query in a reactive query function, you may receive more or less items than this if items were added to or removed from the query range.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/pagination.ts:78](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L78)

***

### cursor[​](#cursor "Direct link to cursor")

• **cursor**: `null` | `string`

A [Cursor](/api/modules/server.md#cursor) representing the start of this page or `null` to start at the beginning of the query results.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/pagination.ts:84](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L84)

---

# Source: https://docs.convex.dev/api/interfaces/server.PaginationResult.md

# Interface: PaginationResult\<T>

[server](/api/modules/server.md).PaginationResult

The result of paginating using [paginate](/api/interfaces/server.OrderedQuery.md#paginate).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name |
| ---- |
| `T`  |

## Properties[​](#properties "Direct link to Properties")

### page[​](#page "Direct link to page")

• **page**: `T`\[]

The page of results.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/pagination.ts:32](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L32)

***

### isDone[​](#isdone "Direct link to isDone")

• **isDone**: `boolean`

Have we reached the end of the results?

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/pagination.ts:37](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L37)

***

### continueCursor[​](#continuecursor "Direct link to continueCursor")

• **continueCursor**: `string`

A [Cursor](/api/modules/server.md#cursor) to continue loading more results.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/pagination.ts:42](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L42)

***

### splitCursor[​](#splitcursor "Direct link to splitCursor")

• `Optional` **splitCursor**: `null` | `string`

A [Cursor](/api/modules/server.md#cursor) to split the page into two, so the page from (cursor, continueCursor] can be replaced by two pages (cursor, splitCursor] and (splitCursor, continueCursor].

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/pagination.ts:49](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L49)

***

### pageStatus[​](#pagestatus "Direct link to pageStatus")

• `Optional` **pageStatus**: `null` | `"SplitRecommended"` | `"SplitRequired"`

When a query reads too much data, it may return 'SplitRecommended' to indicate that the page should be split into two with `splitCursor`. When a query reads so much data that `page` might be incomplete, its status becomes 'SplitRequired'.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/pagination.ts:57](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L57)

---

# Source: https://docs.convex.dev/api/interfaces/server.Query.md

# Interface: Query\<TableInfo>

[server](/api/modules/server.md).Query

The [Query](/api/interfaces/server.Query.md) interface allows functions to read values out of the database.

**If you only need to load an object by ID, use `db.get(id)` instead.**

Executing a query consists of calling

1. (Optional) [order](/api/interfaces/server.Query.md#order) to define the order
2. (Optional) [filter](/api/interfaces/server.OrderedQuery.md#filter) to refine the results
3. A *consumer* method to obtain the results

Queries are lazily evaluated. No work is done until iteration begins, so constructing and extending a query is free. The query is executed incrementally as the results are iterated over, so early terminating also reduces the cost of the query.

It is more efficient to use `filter` expression rather than executing JavaScript to filter.

|                                              |                                                                        |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| **Ordering**                                 |                                                                        |
| [`order("asc")`](#order)                     | Define the order of query results.                                     |
|                                              |                                                                        |
| **Filtering**                                |                                                                        |
| [`filter(...)`](#filter)                     | Filter the query results to only the values that match some condition. |
|                                              |                                                                        |
| **Consuming**                                | Execute a query and return results in different ways.                  |
| [`[Symbol.asyncIterator]()`](#asynciterator) | The query's results can be iterated over using a `for await..of` loop. |
| [`collect()`](#collect)                      | Return all of the results as an array.                                 |
| [`take(n: number)`](#take)                   | Return the first `n` results as an array.                              |
| [`first()`](#first)                          | Return the first result.                                               |
| [`unique()`](#unique)                        | Return the only result, and throw if there is more than one result.    |

To learn more about how to write queries, see [Querying the Database](https://docs.convex.dev/using/database-queries).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

  ↳ **`Query`**

  ↳↳ [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)

## Methods[​](#methods "Direct link to Methods")

### \[asyncIterator][​](#asynciterator "Direct link to \[asyncIterator]")

▸ **\[asyncIterator]**(): `AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Returns[​](#returns "Direct link to Returns")

`AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[\[asyncIterator\]](/api/interfaces/server.OrderedQuery.md#%5Basynciterator%5D)

#### Defined in[​](#defined-in "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es2018.asynciterable.d.ts:38

***

### order[​](#order "Direct link to order")

▸ **order**(`order`): [`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

Define the order of the query output.

Use `"asc"` for an ascending order and `"desc"` for a descending order. If not specified, the order defaults to ascending.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name    | Type                | Description                     |
| ------- | ------------------- | ------------------------------- |
| `order` | `"asc"` \| `"desc"` | The order to return results in. |

#### Returns[​](#returns-1 "Direct link to Returns")

[`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/query.ts:149](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L149)

***

### filter[​](#filter "Direct link to filter")

▸ **filter**(`predicate`): [`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

Filter the query output, returning only the values for which `predicate` evaluates to true.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type                                                                                                                                                         | Description                                                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `predicate` | (`q`: [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md)<`TableInfo`>) => [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`> | An [Expression](/api/classes/server.Expression.md) constructed with the supplied [FilterBuilder](/api/interfaces/server.FilterBuilder.md) that specifies which documents to keep. |

#### Returns[​](#returns-2 "Direct link to Returns")

[`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

* A new [OrderedQuery](/api/interfaces/server.OrderedQuery.md) with the given filter predicate applied.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[filter](/api/interfaces/server.OrderedQuery.md#filter)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/query.ts:165](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L165)

***

### paginate[​](#paginate "Direct link to paginate")

▸ **paginate**(`paginationOpts`): `Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

Load a page of `n` results and obtain a [Cursor](/api/modules/server.md#cursor) for loading more.

Note: If this is called from a reactive query function the number of results may not match `paginationOpts.numItems`!

`paginationOpts.numItems` is only an initial value. After the first invocation, `paginate` will return all items in the original query range. This ensures that all pages will remain adjacent and non-overlapping.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name             | Type                                                               | Description                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `paginationOpts` | [`PaginationOptions`](/api/interfaces/server.PaginationOptions.md) | A [PaginationOptions](/api/interfaces/server.PaginationOptions.md) object containing the number of items to load and the cursor to start at. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

A [PaginationResult](/api/interfaces/server.PaginationResult.md) containing the page of results and a cursor to continue paginating.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[paginate](/api/interfaces/server.OrderedQuery.md#paginate)

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/query.ts:194](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L194)

***

### collect[​](#collect "Direct link to collect")

▸ **collect**(): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return all of the results as an array.

Note: when processing a query with a lot of results, it's often better to use the `Query` as an `AsyncIterable` instead.

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of all of the query's results.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[collect](/api/interfaces/server.OrderedQuery.md#collect)

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/query.ts:206](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L206)

***

### take[​](#take "Direct link to take")

▸ **take**(`n`): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return the first `n` results.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name | Type     | Description                  |
| ---- | -------- | ---------------------------- |
| `n`  | `number` | The number of items to take. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of the first `n` results of the query (or less if the query doesn't have `n` results).

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[take](/api/interfaces/server.OrderedQuery.md#take)

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/query.ts:215](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L215)

***

### first[​](#first "Direct link to first")

▸ **first**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the first result if there is one.

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The first value of the query or `null` if the query returned no results.

#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[first](/api/interfaces/server.OrderedQuery.md#first)

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/query.ts:222](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L222)

***

### unique[​](#unique "Direct link to unique")

▸ **unique**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the singular result if there is one.

**`Throws`**

Will throw an error if the query returns more than one result.

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The single result returned from the query or null if none exists.

#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")

[OrderedQuery](/api/interfaces/server.OrderedQuery.md).[unique](/api/interfaces/server.OrderedQuery.md#unique)

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/query.ts:230](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L230)

---

# Source: https://docs.convex.dev/api/interfaces/server.QueryInitializer.md

# Interface: QueryInitializer\<TableInfo>

[server](/api/modules/server.md).QueryInitializer

The [QueryInitializer](/api/interfaces/server.QueryInitializer.md) interface is the entry point for building a [Query](/api/interfaces/server.Query.md) over a Convex database table.

There are two types of queries:

1. Full table scans: Queries created with [fullTableScan](/api/interfaces/server.QueryInitializer.md#fulltablescan) which iterate over all of the documents in the table in insertion order.
2. Indexed Queries: Queries created with [withIndex](/api/interfaces/server.QueryInitializer.md#withindex) which iterate over an index range in index order.

For convenience, [QueryInitializer](/api/interfaces/server.QueryInitializer.md) extends the [Query](/api/interfaces/server.Query.md) interface, implicitly starting a full table scan.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

  ↳ **`QueryInitializer`**

## Methods[​](#methods "Direct link to Methods")

### \[asyncIterator][​](#asynciterator "Direct link to \[asyncIterator]")

▸ **\[asyncIterator]**(): `AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Returns[​](#returns "Direct link to Returns")

`AsyncIterator`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, `any`, `undefined`>

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[\[asyncIterator\]](/api/interfaces/server.Query.md#%5Basynciterator%5D)

#### Defined in[​](#defined-in "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es2018.asynciterable.d.ts:38

***

### fullTableScan[​](#fulltablescan "Direct link to fullTableScan")

▸ **fullTableScan**(): [`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

Query by reading all of the values out of this table.

This query's cost is relative to the size of the entire table, so this should only be used on tables that will stay very small (say between a few hundred and a few thousand documents) and are updated infrequently.

#### Returns[​](#returns-1 "Direct link to Returns")

[`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

* The [Query](/api/interfaces/server.Query.md) that iterates over every document of the table.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/query.ts:40](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L40)

***

### withIndex[​](#withindex "Direct link to withIndex")

▸ **withIndex**<`IndexName`>(`indexName`, `indexRange?`): [`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

Query by reading documents from an index on this table.

This query's cost is relative to the number of documents that match the index range expression.

Results will be returned in index order.

To learn about indexes, see [Indexes](https://docs.convex.dev/using/indexes).

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type                                     |
| ----------- | ---------------------------------------- |
| `IndexName` | extends `string` \| `number` \| `symbol` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name          | Type                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indexName`   | `IndexName`                                                                                                                                                                                                                                                                              | The name of the index to query.                                                                                                                                                                                                                                                                             |
| `indexRange?` | (`q`: [`IndexRangeBuilder`](/api/interfaces/server.IndexRangeBuilder.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, [`NamedIndex`](/api/modules/server.md#namedindex)<`TableInfo`, `IndexName`>, `0`>) => [`IndexRange`](/api/classes/server.IndexRange.md) | An optional index range constructed with the supplied [IndexRangeBuilder](/api/interfaces/server.IndexRangeBuilder.md). An index range is a description of which documents Convex should consider when running the query. If no index range is present, the query will consider all documents in the index. |

#### Returns[​](#returns-2 "Direct link to Returns")

[`Query`](/api/interfaces/server.Query.md)<`TableInfo`>

* The query that yields documents in the index.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/query.ts:59](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L59)

***

### withSearchIndex[​](#withsearchindex "Direct link to withSearchIndex")

▸ **withSearchIndex**<`IndexName`>(`indexName`, `searchFilter`): [`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

Query by running a full text search against a search index.

Search queries must always search for some text within the index's `searchField`. This query can optionally add equality filters for any `filterFields` specified in the index.

Documents will be returned in relevance order based on how well they match the search text.

To learn about full text search, see [Indexes](https://docs.convex.dev/text-search).

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name        | Type                                     |
| ----------- | ---------------------------------------- |
| `IndexName` | extends `string` \| `number` \| `symbol` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name           | Type                                                                                                                                                                                                                                                                                                    | Description                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indexName`    | `IndexName`                                                                                                                                                                                                                                                                                             | The name of the search index to query.                                                                                                                                                                                                |
| `searchFilter` | (`q`: [`SearchFilterBuilder`](/api/interfaces/server.SearchFilterBuilder.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, [`NamedSearchIndex`](/api/modules/server.md#namedsearchindex)<`TableInfo`, `IndexName`>>) => [`SearchFilter`](/api/classes/server.SearchFilter.md) | A search filter expression constructed with the supplied [SearchFilterBuilder](/api/interfaces/server.SearchFilterBuilder.md). This defines the full text search to run along with equality filtering to run within the search index. |

#### Returns[​](#returns-3 "Direct link to Returns")

[`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

* A query that searches for matching documents, returning them in relevancy order.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/query.ts:88](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L88)

***

### order[​](#order "Direct link to order")

▸ **order**(`order`): [`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

Define the order of the query output.

Use `"asc"` for an ascending order and `"desc"` for a descending order. If not specified, the order defaults to ascending.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type                | Description                     |
| ------- | ------------------- | ------------------------------- |
| `order` | `"asc"` \| `"desc"` | The order to return results in. |

#### Returns[​](#returns-4 "Direct link to Returns")

[`OrderedQuery`](/api/interfaces/server.OrderedQuery.md)<`TableInfo`>

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[order](/api/interfaces/server.Query.md#order)

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/query.ts:149](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L149)

***

### filter[​](#filter "Direct link to filter")

▸ **filter**(`predicate`): [`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<`TableInfo`>

Filter the query output, returning only the values for which `predicate` evaluates to true.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type                                                                                                                                                         | Description                                                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `predicate` | (`q`: [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md)<`TableInfo`>) => [`ExpressionOrValue`](/api/modules/server.md#expressionorvalue)<`boolean`> | An [Expression](/api/classes/server.Expression.md) constructed with the supplied [FilterBuilder](/api/interfaces/server.FilterBuilder.md) that specifies which documents to keep. |

#### Returns[​](#returns-5 "Direct link to Returns")

[`QueryInitializer`](/api/interfaces/server.QueryInitializer.md)<`TableInfo`>

* A new [OrderedQuery](/api/interfaces/server.OrderedQuery.md) with the given filter predicate applied.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[filter](/api/interfaces/server.Query.md#filter)

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/query.ts:165](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L165)

***

### paginate[​](#paginate "Direct link to paginate")

▸ **paginate**(`paginationOpts`): `Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

Load a page of `n` results and obtain a [Cursor](/api/modules/server.md#cursor) for loading more.

Note: If this is called from a reactive query function the number of results may not match `paginationOpts.numItems`!

`paginationOpts.numItems` is only an initial value. After the first invocation, `paginate` will return all items in the original query range. This ensures that all pages will remain adjacent and non-overlapping.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name             | Type                                                               | Description                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `paginationOpts` | [`PaginationOptions`](/api/interfaces/server.PaginationOptions.md) | A [PaginationOptions](/api/interfaces/server.PaginationOptions.md) object containing the number of items to load and the cursor to start at. |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<[`PaginationResult`](/api/interfaces/server.PaginationResult.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>>

A [PaginationResult](/api/interfaces/server.PaginationResult.md) containing the page of results and a cursor to continue paginating.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[paginate](/api/interfaces/server.Query.md#paginate)

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/query.ts:194](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L194)

***

### collect[​](#collect "Direct link to collect")

▸ **collect**(): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return all of the results as an array.

Note: when processing a query with a lot of results, it's often better to use the `Query` as an `AsyncIterable` instead.

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of all of the query's results.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[collect](/api/interfaces/server.Query.md#collect)

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/query.ts:206](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L206)

***

### take[​](#take "Direct link to take")

▸ **take**(`n`): `Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

Execute the query and return the first `n` results.

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name | Type     | Description                  |
| ---- | -------- | ---------------------------- |
| `n`  | `number` | The number of items to take. |

#### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>\[]>

* An array of the first `n` results of the query (or less if the query doesn't have `n` results).

#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[take](/api/interfaces/server.Query.md#take)

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/query.ts:215](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L215)

***

### first[​](#first "Direct link to first")

▸ **first**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the first result if there is one.

#### Returns[​](#returns-9 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The first value of the query or `null` if the query returned no results.

#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[first](/api/interfaces/server.Query.md#first)

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/query.ts:222](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L222)

***

### unique[​](#unique "Direct link to unique")

▸ **unique**(): `Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

Execute the query and return the singular result if there is one.

**`Throws`**

Will throw an error if the query returns more than one result.

#### Returns[​](#returns-10 "Direct link to Returns")

`Promise`<`null` | [`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>>

* The single result returned from the query or null if none exists.

#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")

[Query](/api/interfaces/server.Query.md).[unique](/api/interfaces/server.Query.md#unique)

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/query.ts:230](https://github.com/get-convex/convex-js/blob/main/src/server/query.ts#L230)

---

# Source: https://docs.convex.dev/api/interfaces/server.Scheduler.md

# Interface: Scheduler

[server](/api/modules/server.md).Scheduler

An interface to schedule Convex functions.

You can schedule either mutations or actions. Mutations are guaranteed to execute exactly once - they are automatically retried on transient errors and either execute successfully or fail deterministically due to developer error in defining the function. Actions execute at most once - they are not retried and might fail due to transient errors.

Consider using an internalMutation or internalAction to enforce that these functions cannot be called directly from a Convex client.

## Methods[​](#methods "Direct link to Methods")

### runAfter[​](#runafter "Direct link to runAfter")

▸ **runAfter**<`FuncRef`>(`delayMs`, `functionReference`, `...args`): `Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`>>

Schedule a function to execute after a delay.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delayMs`           | `number`                                                                 | Delay in milliseconds. Must be non-negative. If the delay is zero, the scheduled function will be due to execute immediately after the scheduling one completes. |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule.                                                                    |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | Arguments to call the scheduled functions with.                                                                                                                  |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`>>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/scheduler.ts:41](https://github.com/get-convex/convex-js/blob/main/src/server/scheduler.ts#L41)

***

### runAt[​](#runat "Direct link to runAt")

▸ **runAt**<`FuncRef`>(`timestamp`, `functionReference`, `...args`): `Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`>>

Schedule a function to execute at a given timestamp.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name      | Type                                                                                          |
| --------- | --------------------------------------------------------------------------------------------- |
| `FuncRef` | extends [`SchedulableFunctionReference`](/api/modules/server.md#schedulablefunctionreference) |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name                | Type                                                                     | Description                                                                                                                                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`         | `number` \| `Date`                                                       | A Date or a timestamp (milliseconds since the epoch). If the timestamp is in the past, the scheduled function will be due to execute immediately after the scheduling one completes. The timestamp can't be more than five years in the past or more than five years in the future. |
| `functionReference` | `FuncRef`                                                                | A [FunctionReference](/api/modules/server.md#functionreference) for the function to schedule.                                                                                                                                                                                       |
| `...args`           | [`OptionalRestArgs`](/api/modules/server.md#optionalrestargs)<`FuncRef`> | arguments to call the scheduled functions with.                                                                                                                                                                                                                                     |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`>>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/scheduler.ts:58](https://github.com/get-convex/convex-js/blob/main/src/server/scheduler.ts#L58)

***

### cancel[​](#cancel "Direct link to cancel")

▸ **cancel**(`id`): `Promise`<`void`>

Cancels a previously scheduled function if it has not started yet. If the scheduled function is already in progress, it will continue running but any new functions that it tries to schedule will be canceled.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name | Type                                                                      |
| ---- | ------------------------------------------------------------------------- |
| `id` | [`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`> |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/scheduler.ts:71](https://github.com/get-convex/convex-js/blob/main/src/server/scheduler.ts#L71)

---

# Source: https://docs.convex.dev/api/classes/server.SchemaDefinition.md

# Class: SchemaDefinition\<Schema, StrictTableTypes>

[server](/api/modules/server.md).SchemaDefinition

The definition of a Convex project schema.

This should be produced by using [defineSchema](/api/modules/server.md#defineschema).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name               | Type                                                            |
| ------------------ | --------------------------------------------------------------- |
| `Schema`           | extends [`GenericSchema`](/api/modules/server.md#genericschema) |
| `StrictTableTypes` | extends `boolean`                                               |

## Properties[​](#properties "Direct link to Properties")

### tables[​](#tables "Direct link to tables")

• **tables**: `Schema`

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/schema.ts:658](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L658)

***

### strictTableNameTypes[​](#stricttablenametypes "Direct link to strictTableNameTypes")

• **strictTableNameTypes**: `StrictTableTypes`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/schema.ts:659](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L659)

***

### schemaValidation[​](#schemavalidation "Direct link to schemaValidation")

• `Readonly` **schemaValidation**: `boolean`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/schema.ts:660](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L660)

---

# Source: https://docs.convex.dev/api/classes/server.SearchFilter.md

# Class: SearchFilter

[server](/api/modules/server.md).SearchFilter

An expression representing a search filter created by [SearchFilterBuilder](/api/interfaces/server.SearchFilterBuilder.md).

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* **`SearchFilter`**

  ↳ [`SearchFilterFinalizer`](/api/interfaces/server.SearchFilterFinalizer.md)

---

# Source: https://docs.convex.dev/api/interfaces/server.SearchFilterBuilder.md

# Interface: SearchFilterBuilder\<Document, SearchIndexConfig>

[server](/api/modules/server.md).SearchFilterBuilder

Builder for defining search filters.

A search filter is a chained list of:

1. One search expression constructed with `.search`.
2. Zero or more equality expressions constructed with `.eq`.

The search expression must search for text in the index's `searchField`. The filter expressions can use any of the `filterFields` defined in the index.

For all other filtering use [filter](/api/interfaces/server.OrderedQuery.md#filter).

To learn about full text search, see [Indexes](https://docs.convex.dev/text-search).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name                | Type                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------- |
| `Document`          | extends [`GenericDocument`](/api/modules/server.md#genericdocument)                   |
| `SearchIndexConfig` | extends [`GenericSearchIndexConfig`](/api/modules/server.md#genericsearchindexconfig) |

## Methods[​](#methods "Direct link to Methods")

### search[​](#search "Direct link to search")

▸ **search**(`fieldName`, `query`): [`SearchFilterFinalizer`](/api/interfaces/server.SearchFilterFinalizer.md)<`Document`, `SearchIndexConfig`>

Search for the terms in `query` within `doc[fieldName]`.

This will do a full text search that returns results where any word of of `query` appears in the field.

Documents will be returned based on their relevance to the query. This takes into account:

* How many words in the query appear in the text?
* How many times do they appear?
* How long is the text field?

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                  | Description                                                                           |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------- |
| `fieldName` | `SearchIndexConfig`\[`"searchField"`] | The name of the field to search in. This must be listed as the index's `searchField`. |
| `query`     | `string`                              | The query text to search for.                                                         |

#### Returns[​](#returns "Direct link to Returns")

[`SearchFilterFinalizer`](/api/interfaces/server.SearchFilterFinalizer.md)<`Document`, `SearchIndexConfig`>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/search\_filter\_builder.ts:42](https://github.com/get-convex/convex-js/blob/main/src/server/search_filter_builder.ts#L42)

---

# Source: https://docs.convex.dev/api/interfaces/server.SearchFilterFinalizer.md

# Interface: SearchFilterFinalizer\<Document, SearchIndexConfig>

[server](/api/modules/server.md).SearchFilterFinalizer

Builder to define equality expressions as part of a search filter.

See [SearchFilterBuilder](/api/interfaces/server.SearchFilterBuilder.md).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name                | Type                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------- |
| `Document`          | extends [`GenericDocument`](/api/modules/server.md#genericdocument)                   |
| `SearchIndexConfig` | extends [`GenericSearchIndexConfig`](/api/modules/server.md#genericsearchindexconfig) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`SearchFilter`](/api/classes/server.SearchFilter.md)

  ↳ **`SearchFilterFinalizer`**

## Methods[​](#methods "Direct link to Methods")

### eq[​](#eq "Direct link to eq")

▸ **eq**<`FieldName`>(`fieldName`, `value`): [`SearchFilterFinalizer`](/api/interfaces/server.SearchFilterFinalizer.md)<`Document`, `SearchIndexConfig`>

Restrict this query to documents where `doc[fieldName] === value`.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `FieldName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                                                               | Description                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `fieldName` | `FieldName`                                                                                        | The name of the field to compare. This must be listed in the search index's `filterFields`. |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `FieldName`> | The value to compare against.                                                               |

#### Returns[​](#returns "Direct link to Returns")

[`SearchFilterFinalizer`](/api/interfaces/server.SearchFilterFinalizer.md)<`Document`, `SearchIndexConfig`>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/search\_filter\_builder.ts:66](https://github.com/get-convex/convex-js/blob/main/src/server/search_filter_builder.ts#L66)

---

# Source: https://docs.convex.dev/api/interfaces/server.SearchIndexConfig.md

# Interface: SearchIndexConfig\<SearchField, FilterFields>

[server](/api/modules/server.md).SearchIndexConfig

The configuration for a full text search index.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name           | Type             |
| -------------- | ---------------- |
| `SearchField`  | extends `string` |
| `FilterFields` | extends `string` |

## Properties[​](#properties "Direct link to Properties")

### searchField[​](#searchfield "Direct link to searchField")

• **searchField**: `SearchField`

The field to index for full text search.

This must be a field of type `string`.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/schema.ts:101](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L101)

***

### filterFields[​](#filterfields "Direct link to filterFields")

• `Optional` **filterFields**: `FilterFields`\[]

Additional fields to index for fast filtering when running search queries.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/schema.ts:106](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L106)

---

# Source: https://docs.convex.dev/api/interfaces/server.StorageActionWriter.md

# Interface: StorageActionWriter

[server](/api/modules/server.md).StorageActionWriter

An interface to read and write files to storage within Convex actions and HTTP actions.

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`StorageWriter`](/api/interfaces/server.StorageWriter.md)

  ↳ **`StorageActionWriter`**

## Methods[​](#methods "Direct link to Methods")

### getUrl[​](#geturl "Direct link to getUrl")

▸ **getUrl**(`storageId`): `Promise`<`null` | `string`>

Get the URL for a file in storage by its `Id<"_storage">`.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                          | Description                                                    |
| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file to fetch from Convex storage. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[getUrl](/api/interfaces/server.StorageWriter.md#geturl)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/storage.ts:51](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L51)

▸ **getUrl**<`T`>(`storageId`): `Promise`<`null` | `string`>

**`Deprecated`**

Passing a string is deprecated, use `storage.getUrl(Id<"_storage">)` instead.

Get the URL for a file in storage by its [StorageId](/api/modules/server.md#storageid).

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                                                 |
| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file to fetch from Convex storage. |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[getUrl](/api/interfaces/server.StorageWriter.md#geturl)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/storage.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L63)

***

### getMetadata[​](#getmetadata "Direct link to getMetadata")

▸ **getMetadata**(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type                                                          | Description                       |
| ----------- | ------------------------------------------------------------- | --------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file. |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[getMetadata](/api/interfaces/server.StorageWriter.md#getmetadata)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/storage.ts:75](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L75)

▸ **getMetadata**<`T`>(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                    |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[getMetadata](/api/interfaces/server.StorageWriter.md#getmetadata)

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/storage.ts:85](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L85)

***

### generateUploadUrl[​](#generateuploadurl "Direct link to generateUploadUrl")

▸ **generateUploadUrl**(): `Promise`<`string`>

Fetch a short-lived URL for uploading a file into storage.

Upon a POST request to this URL, the endpoint will return a JSON object containing a newly allocated `Id<"_storage">`.

The POST URL accepts an optional standard HTTP Digest header with a sha256 checksum.

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<`string`>

* A url that allows file upload via an HTTP POST.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[generateUploadUrl](/api/interfaces/server.StorageWriter.md#generateuploadurl)

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/storage.ts:105](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L105)

***

### delete[​](#delete "Direct link to delete")

▸ **delete**(`storageId`): `Promise`<`void`>

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by [getUrl](/api/interfaces/server.StorageReader.md#geturl) will return 404s.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name        | Type                                                          | Description                                                     |
| ----------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file to delete from Convex storage. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`void`>

#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[delete](/api/interfaces/server.StorageWriter.md#delete)

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/storage.ts:113](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L113)

▸ **delete**<`T`>(`storageId`): `Promise`<`void`>

**`Deprecated`**

Passing a string is deprecated, use `storage.delete(Id<"_storage">)` instead.

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by [getUrl](/api/interfaces/server.StorageReader.md#geturl) will return 404s.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                                                  |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file to delete from Convex storage. |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`void`>

#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")

[StorageWriter](/api/interfaces/server.StorageWriter.md).[delete](/api/interfaces/server.StorageWriter.md#delete)

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/storage.ts:124](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L124)

***

### get[​](#get "Direct link to get")

▸ **get**(`storageId`): `Promise`<`null` | `Blob`>

Get a Blob containing the file associated with the provided `Id<"_storage">`, or `null` if there is no file.

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name        | Type                                                          |
| ----------- | ------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> |

#### Returns[​](#returns-7 "Direct link to Returns")

`Promise`<`null` | `Blob`>

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/storage.ts:138](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L138)

▸ **get**<`T`>(`storageId`): `Promise`<`null` | `Blob`>

**`Deprecated`**

Passing a string is deprecated, use `storage.get(Id<"_storage">)` instead.

Get a Blob containing the file associated with the provided [StorageId](/api/modules/server.md#storageid), or `null` if there is no file.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name        | Type                                                 |
| ----------- | ---------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` |

#### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<`null` | `Blob`>

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/storage.ts:145](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L145)

***

### store[​](#store "Direct link to store")

▸ **store**(`blob`, `options?`): `Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_storage"`>>

Store the file contained in the Blob.

If provided, this will verify the sha256 checksum matches the contents of the file.

#### Parameters[​](#parameters-8 "Direct link to Parameters")

| Name              | Type     |
| ----------------- | -------- |
| `blob`            | `Blob`   |
| `options?`        | `Object` |
| `options.sha256?` | `string` |

#### Returns[​](#returns-9 "Direct link to Returns")

`Promise`<[`GenericId`](/api/modules/values.md#genericid)<`"_storage"`>>

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/storage.ts:153](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L153)

---

# Source: https://docs.convex.dev/api/interfaces/server.StorageReader.md

# Interface: StorageReader

[server](/api/modules/server.md).StorageReader

An interface to read files from storage within Convex query functions.

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* **`StorageReader`**

  ↳ [`StorageWriter`](/api/interfaces/server.StorageWriter.md)

## Methods[​](#methods "Direct link to Methods")

### getUrl[​](#geturl "Direct link to getUrl")

▸ **getUrl**(`storageId`): `Promise`<`null` | `string`>

Get the URL for a file in storage by its `Id<"_storage">`.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                          | Description                                                    |
| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file to fetch from Convex storage. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/storage.ts:51](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L51)

▸ **getUrl**<`T`>(`storageId`): `Promise`<`null` | `string`>

**`Deprecated`**

Passing a string is deprecated, use `storage.getUrl(Id<"_storage">)` instead.

Get the URL for a file in storage by its [StorageId](/api/modules/server.md#storageid).

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                                                 |
| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file to fetch from Convex storage. |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/storage.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L63)

***

### getMetadata[​](#getmetadata "Direct link to getMetadata")

▸ **getMetadata**(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type                                                          | Description                       |
| ----------- | ------------------------------------------------------------- | --------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file. |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/storage.ts:75](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L75)

▸ **getMetadata**<`T`>(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                    |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/storage.ts:85](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L85)

---

# Source: https://docs.convex.dev/api/interfaces/server.StorageWriter.md

# Interface: StorageWriter

[server](/api/modules/server.md).StorageWriter

An interface to write files to storage within Convex mutation functions.

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`StorageReader`](/api/interfaces/server.StorageReader.md)

  ↳ **`StorageWriter`**

  ↳↳ [`StorageActionWriter`](/api/interfaces/server.StorageActionWriter.md)

## Methods[​](#methods "Direct link to Methods")

### getUrl[​](#geturl "Direct link to getUrl")

▸ **getUrl**(`storageId`): `Promise`<`null` | `string`>

Get the URL for a file in storage by its `Id<"_storage">`.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                          | Description                                                    |
| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file to fetch from Convex storage. |

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[StorageReader](/api/interfaces/server.StorageReader.md).[getUrl](/api/interfaces/server.StorageReader.md#geturl)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/storage.ts:51](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L51)

▸ **getUrl**<`T`>(`storageId`): `Promise`<`null` | `string`>

**`Deprecated`**

Passing a string is deprecated, use `storage.getUrl(Id<"_storage">)` instead.

Get the URL for a file in storage by its [StorageId](/api/modules/server.md#storageid).

The GET response includes a standard HTTP Digest header with a sha256 checksum.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                                                 |
| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file to fetch from Convex storage. |

#### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`null` | `string`>

* A url which fetches the file via an HTTP GET, or `null` if it no longer exists.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[StorageReader](/api/interfaces/server.StorageReader.md).[getUrl](/api/interfaces/server.StorageReader.md#geturl)

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/storage.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L63)

***

### getMetadata[​](#getmetadata "Direct link to getMetadata")

▸ **getMetadata**(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type                                                          | Description                       |
| ----------- | ------------------------------------------------------------- | --------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file. |

#### Returns[​](#returns-2 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[StorageReader](/api/interfaces/server.StorageReader.md).[getMetadata](/api/interfaces/server.StorageReader.md#getmetadata)

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/storage.ts:75](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L75)

▸ **getMetadata**<`T`>(`storageId`): `Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

**`Deprecated`**

This function is deprecated, use `db.system.get(Id<"_storage">)` instead.

Get metadata for a file.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                    |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file. |

#### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`null` | [`FileMetadata`](/api/modules/server.md#filemetadata)>

* A [FileMetadata](/api/modules/server.md#filemetadata) object if found or `null` if not found.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[StorageReader](/api/interfaces/server.StorageReader.md).[getMetadata](/api/interfaces/server.StorageReader.md#getmetadata)

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/storage.ts:85](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L85)

***

### generateUploadUrl[​](#generateuploadurl "Direct link to generateUploadUrl")

▸ **generateUploadUrl**(): `Promise`<`string`>

Fetch a short-lived URL for uploading a file into storage.

Upon a POST request to this URL, the endpoint will return a JSON object containing a newly allocated `Id<"_storage">`.

The POST URL accepts an optional standard HTTP Digest header with a sha256 checksum.

#### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<`string`>

* A url that allows file upload via an HTTP POST.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/storage.ts:105](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L105)

***

### delete[​](#delete "Direct link to delete")

▸ **delete**(`storageId`): `Promise`<`void`>

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by [getUrl](/api/interfaces/server.StorageReader.md#geturl) will return 404s.

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name        | Type                                                          | Description                                                     |
| ----------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| `storageId` | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | The `Id<"_storage">` of the file to delete from Convex storage. |

#### Returns[​](#returns-5 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/storage.ts:113](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L113)

▸ **delete**<`T`>(`storageId`): `Promise`<`void`>

**`Deprecated`**

Passing a string is deprecated, use `storage.delete(Id<"_storage">)` instead.

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by [getUrl](/api/interfaces/server.StorageReader.md#geturl) will return 404s.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `T`  | extends `string` |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name        | Type                                                 | Description                                                                                  |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `storageId` | `T` extends { `__tableName`: `any` } ? `never` : `T` | The [StorageId](/api/modules/server.md#storageid) of the file to delete from Convex storage. |

#### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`void`>

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/storage.ts:124](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L124)

---

# Source: https://docs.convex.dev/api/interfaces/server.SystemDataModel.md

# Interface: SystemDataModel

[server](/api/modules/server.md).SystemDataModel

Internal type used in Convex code generation!

Convert a [SchemaDefinition](/api/classes/server.SchemaDefinition.md) into a [GenericDataModel](/api/modules/server.md#genericdatamodel).

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* [`DataModelFromSchemaDefinition`](/api/modules/server.md#datamodelfromschemadefinition)\<typeof `_systemSchema`>

  ↳ **`SystemDataModel`**

## Properties[​](#properties "Direct link to Properties")

### \_scheduled\_functions[​](#_scheduled_functions "Direct link to _scheduled_functions")

• **\_scheduled\_functions**: `Object`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name                       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document`                 | { `completedTime`: `undefined` \| `number` ; `name`: `string` ; `args`: `any`\[] ; `scheduledTime`: `number` ; `state`: { kind: "pending"; } \| { kind: "inProgress"; } \| { kind: "success"; } \| { kind: "failed"; error: string; } \| { kind: "canceled"; } ; `_creationTime`: `number` ; `_id`: [`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`> }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `document.completedTime`   | `undefined` \| `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `document.name`            | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `document.args`            | `any`\[]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `document.scheduledTime`   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `document.state`           | { kind: "pending"; } \| { kind: "inProgress"; } \| { kind: "success"; } \| { kind: "failed"; error: string; } \| { kind: "canceled"; }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `document._creationTime`   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `document._id`             | [`GenericId`](/api/modules/values.md#genericid)<`"_scheduled_functions"`>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `fieldPaths`               | `"_id"` \| `ExtractFieldPaths`<[`VObject`](/api/classes/values.VObject.md)<{ `completedTime`: `undefined` \| `number` ; `name`: `string` ; `args`: `any`\[] ; `scheduledTime`: `number` ; `state`: { kind: "pending"; } \| { kind: "inProgress"; } \| { kind: "success"; } \| { kind: "failed"; error: string; } \| { kind: "canceled"; } }, { `name`: [`VString`](/api/classes/values.VString.md)<`string`, `"required"`> ; `args`: [`VArray`](/api/classes/values.VArray.md)<`any`\[], [`VAny`](/api/classes/values.VAny.md)<`any`, `"required"`, `string`>, `"required"`> ; `scheduledTime`: [`VFloat64`](/api/classes/values.VFloat64.md)<`number`, `"required"`> ; `completedTime`: [`VFloat64`](/api/classes/values.VFloat64.md)<`undefined` \| `number`, `"optional"`> ; `state`: [`VUnion`](/api/classes/values.VUnion.md)<{ `kind`: `"pending"` } \| { `kind`: `"inProgress"` } \| { `kind`: `"success"` } \| { `kind`: `"failed"` ; `error`: `string` } \| { `kind`: `"canceled"` }, \[[`VObject`](/api/classes/values.VObject.md)<{ `kind`: `"pending"` }, { `kind`: [`VLiteral`](/api/classes/values.VLiteral.md)<`"pending"`, `"required"`> }, `"required"`, `"kind"`>, [`VObject`](/api/classes/values.VObject.md)<{ `kind`: `"inProgress"` }, { `kind`: [`VLiteral`](/api/classes/values.VLiteral.md)<`"inProgress"`, `"required"`> }, `"required"`, `"kind"`>, [`VObject`](/api/classes/values.VObject.md)<{ `kind`: `"success"` }, { `kind`: [`VLiteral`](/api/classes/values.VLiteral.md)<`"success"`, `"required"`> }, `"required"`, `"kind"`>, [`VObject`](/api/classes/values.VObject.md)<{ `kind`: `"failed"` ; `error`: `string` }, { `kind`: [`VLiteral`](/api/classes/values.VLiteral.md)<`"failed"`, `"required"`> ; `error`: [`VString`](/api/classes/values.VString.md)<`string`, `"required"`> }, `"required"`, `"kind"` \| `"error"`>, [`VObject`](/api/classes/values.VObject.md)<{ `kind`: `"canceled"` }, { `kind`: [`VLiteral`](/api/classes/values.VLiteral.md)<`"canceled"`, `"required"`> }, `"required"`, `"kind"`>], `"required"`, `"kind"` \| `"error"`> }, `"required"`, `"name"` \| `"args"` \| `"scheduledTime"` \| `"completedTime"` \| `"state"` \| `"state.kind"` \| `"state.error"`>> |
| `indexes`                  | { `by_id`: \[`"_id"`] ; `by_creation_time`: \[`"_creationTime"`] }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `indexes.by_id`            | \[`"_id"`]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `indexes.by_creation_time` | \[`"_creationTime"`]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `searchIndexes`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `vectorIndexes`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

DataModelFromSchemaDefinition.\_scheduled\_functions

***

### \_storage[​](#_storage "Direct link to _storage")

• **\_storage**: `Object`

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

| Name                       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`                 | { `contentType`: `undefined` \| `string` ; `sha256`: `string` ; `size`: `number` ; `_creationTime`: `number` ; `_id`: [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> }                                                                                                                                                                                                                                                                                                           |
| `document.contentType`     | `undefined` \| `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `document.sha256`          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `document.size`            | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `document._creationTime`   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `document._id`             | [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`>                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `fieldPaths`               | `"_id"` \| `ExtractFieldPaths`<[`VObject`](/api/classes/values.VObject.md)<{ `contentType`: `undefined` \| `string` ; `sha256`: `string` ; `size`: `number` }, { `sha256`: [`VString`](/api/classes/values.VString.md)<`string`, `"required"`> ; `size`: [`VFloat64`](/api/classes/values.VFloat64.md)<`number`, `"required"`> ; `contentType`: [`VString`](/api/classes/values.VString.md)<`undefined` \| `string`, `"optional"`> }, `"required"`, `"sha256"` \| `"size"` \| `"contentType"`>> |
| `indexes`                  | { `by_id`: \[`"_id"`] ; `by_creation_time`: \[`"_creationTime"`] }                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `indexes.by_id`            | \[`"_id"`]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `indexes.by_creation_time` | \[`"_creationTime"`]                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `searchIndexes`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `vectorIndexes`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

DataModelFromSchemaDefinition.\_storage

---

# Source: https://docs.convex.dev/api/classes/server.TableDefinition.md

# Class: TableDefinition\<DocumentType, Indexes, SearchIndexes, VectorIndexes>

[server](/api/modules/server.md).TableDefinition

The definition of a table within a schema.

This should be produced by using [defineTable](/api/modules/server.md#definetable).

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name            | Type                                                                                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DocumentType`  | extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> = [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> |
| `Indexes`       | extends [`GenericTableIndexes`](/api/modules/server.md#generictableindexes) =                                                                       |
| `SearchIndexes` | extends [`GenericTableSearchIndexes`](/api/modules/server.md#generictablesearchindexes) =                                                           |
| `VectorIndexes` | extends [`GenericTableVectorIndexes`](/api/modules/server.md#generictablevectorindexes) =                                                           |

## Properties[​](#properties "Direct link to Properties")

### validator[​](#validator "Direct link to validator")

• **validator**: `DocumentType`

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/schema.ts:199](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L199)

## Methods[​](#methods "Direct link to Methods")

### indexes[​](#indexes "Direct link to indexes")

▸ \*\* indexes\*\*(): { `indexDescriptor`: `string` ; `fields`: `string`\[] }\[]

This API is experimental: it may change or disappear.

Returns indexes defined on this table. Intended for the advanced use cases of dynamically deciding which index to use for a query. If you think you need this, please chime in on ths issue in the Convex JS GitHub repo. <https://github.com/get-convex/convex-js/issues/49>

#### Returns[​](#returns "Direct link to Returns")

{ `indexDescriptor`: `string` ; `fields`: `string`\[] }\[]

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/schema.ts:222](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L222)

***

### index[​](#index "Direct link to index")

▸ **index**<`IndexName`, `FirstFieldPath`, `RestFieldPaths`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, [`Expand`](/api/modules/server.md#expand)<`Indexes` & `Record`<`IndexName`, \[`FirstFieldPath`, ...RestFieldPaths\[], `"_creationTime"`]>>, `SearchIndexes`, `VectorIndexes`>

Define an index on this table.

To learn about indexes, see [Defining Indexes](https://docs.convex.dev/using/indexes).

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name             | Type                                           |
| ---------------- | ---------------------------------------------- |
| `IndexName`      | extends `string`                               |
| `FirstFieldPath` | extends `any`                                  |
| `RestFieldPaths` | extends `ExtractFieldPaths`<`DocumentType`>\[] |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name                  | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                   |
| --------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | `IndexName`                               | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`         | `Object`                                  | The index configuration object.                                                                                                                                                                                                                                                                                                                               |
| `indexConfig.fields`  | \[`FirstFieldPath`, ...RestFieldPaths\[]] | The fields to index, in order. Must specify at least one field.                                                                                                                                                                                                                                                                                               |
| `indexConfig.staged?` | `false`                                   | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-1 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, [`Expand`](/api/modules/server.md#expand)<`Indexes` & `Record`<`IndexName`, \[`FirstFieldPath`, ...RestFieldPaths\[], `"_creationTime"`]>>, `SearchIndexes`, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this index included.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/schema.ts:235](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L235)

▸ **index**<`IndexName`, `FirstFieldPath`, `RestFieldPaths`>(`name`, `fields`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, [`Expand`](/api/modules/server.md#expand)<`Indexes` & `Record`<`IndexName`, \[`FirstFieldPath`, ...RestFieldPaths\[], `"_creationTime"`]>>, `SearchIndexes`, `VectorIndexes`>

Define an index on this table.

To learn about indexes, see [Defining Indexes](https://docs.convex.dev/using/indexes).

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name             | Type                                           |
| ---------------- | ---------------------------------------------- |
| `IndexName`      | extends `string`                               |
| `FirstFieldPath` | extends `any`                                  |
| `RestFieldPaths` | extends `ExtractFieldPaths`<`DocumentType`>\[] |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name     | Type                                      | Description                                                     |
| -------- | ----------------------------------------- | --------------------------------------------------------------- |
| `name`   | `IndexName`                               | The name of the index.                                          |
| `fields` | \[`FirstFieldPath`, ...RestFieldPaths\[]] | The fields to index, in order. Must specify at least one field. |

#### Returns[​](#returns-2 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, [`Expand`](/api/modules/server.md#expand)<`Indexes` & `Record`<`IndexName`, \[`FirstFieldPath`, ...RestFieldPaths\[], `"_creationTime"`]>>, `SearchIndexes`, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this index included.

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/schema.ts:268](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L268)

▸ **index**<`IndexName`, `FirstFieldPath`, `RestFieldPaths`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

Define a staged index on this table.

For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.

If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries.

To learn about indexes, see [Defining Indexes](https://docs.convex.dev/using/indexes).

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name             | Type                                           |
| ---------------- | ---------------------------------------------- |
| `IndexName`      | extends `string`                               |
| `FirstFieldPath` | extends `any`                                  |
| `RestFieldPaths` | extends `ExtractFieldPaths`<`DocumentType`>\[] |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name                 | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                   |
| -------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | `IndexName`                               | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`        | `Object`                                  | The index configuration object.                                                                                                                                                                                                                                                                                                                               |
| `indexConfig.fields` | \[`FirstFieldPath`, ...RestFieldPaths\[]] | The fields to index, in order. Must specify at least one field.                                                                                                                                                                                                                                                                                               |
| `indexConfig.staged` | `true`                                    | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-3 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this index included.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/schema.ts:304](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L304)

***

### searchIndex[​](#searchindex "Direct link to searchIndex")

▸ **searchIndex**<`IndexName`, `SearchField`, `FilterFields`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, [`Expand`](/api/modules/server.md#expand)<`SearchIndexes` & `Record`<`IndexName`, { `searchField`: `SearchField` ; `filterFields`: `FilterFields` }>>, `VectorIndexes`>

Define a search index on this table.

To learn about search indexes, see [Search](https://docs.convex.dev/text-search).

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name           | Type                    |
| -------------- | ----------------------- |
| `IndexName`    | extends `string`        |
| `SearchField`  | extends `any`           |
| `FilterFields` | extends `any` = `never` |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name                        | Type              | Description                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                      | `IndexName`       | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`               | `Object`          | The search index configuration object.                                                                                                                                                                                                                                                                                                                        |
| `indexConfig.searchField`   | `SearchField`     | The field to index for full text search. This must be a field of type `string`.                                                                                                                                                                                                                                                                               |
| `indexConfig.filterFields?` | `FilterFields`\[] | Additional fields to index for fast filtering when running search queries.                                                                                                                                                                                                                                                                                    |
| `indexConfig.staged?`       | `false`           | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-4 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, [`Expand`](/api/modules/server.md#expand)<`SearchIndexes` & `Record`<`IndexName`, { `searchField`: `SearchField` ; `filterFields`: `FilterFields` }>>, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this search index included.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/schema.ts:357](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L357)

▸ **searchIndex**<`IndexName`, `SearchField`, `FilterFields`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

Define a staged search index on this table.

For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.

If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries.

To learn about search indexes, see [Search](https://docs.convex.dev/text-search).

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name           | Type                    |
| -------------- | ----------------------- |
| `IndexName`    | extends `string`        |
| `SearchField`  | extends `any`           |
| `FilterFields` | extends `any` = `never` |

#### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name                        | Type              | Description                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                      | `IndexName`       | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`               | `Object`          | The search index configuration object.                                                                                                                                                                                                                                                                                                                        |
| `indexConfig.searchField`   | `SearchField`     | The field to index for full text search. This must be a field of type `string`.                                                                                                                                                                                                                                                                               |
| `indexConfig.filterFields?` | `FilterFields`\[] | Additional fields to index for fast filtering when running search queries.                                                                                                                                                                                                                                                                                    |
| `indexConfig.staged`        | `true`            | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-5 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this search index included.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/schema.ts:401](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L401)

***

### vectorIndex[​](#vectorindex "Direct link to vectorIndex")

▸ **vectorIndex**<`IndexName`, `VectorField`, `FilterFields`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, [`Expand`](/api/modules/server.md#expand)<`VectorIndexes` & `Record`<`IndexName`, { `vectorField`: `VectorField` ; `dimensions`: `number` ; `filterFields`: `FilterFields` }>>>

Define a vector index on this table.

To learn about vector indexes, see [Vector Search](https://docs.convex.dev/vector-search).

#### Type parameters[​](#type-parameters-6 "Direct link to Type parameters")

| Name           | Type                    |
| -------------- | ----------------------- |
| `IndexName`    | extends `string`        |
| `VectorField`  | extends `any`           |
| `FilterFields` | extends `any` = `never` |

#### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name                        | Type              | Description                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                      | `IndexName`       | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`               | `Object`          | The vector index configuration object.                                                                                                                                                                                                                                                                                                                        |
| `indexConfig.vectorField`   | `VectorField`     | The field to index for vector search. This must be a field of type `v.array(v.float64())` (or a union)                                                                                                                                                                                                                                                        |
| `indexConfig.dimensions`    | `number`          | The length of the vectors indexed. This must be between 2 and 2048 inclusive.                                                                                                                                                                                                                                                                                 |
| `indexConfig.filterFields?` | `FilterFields`\[] | Additional fields to index for fast filtering when running vector searches.                                                                                                                                                                                                                                                                                   |
| `indexConfig.staged?`       | `false`           | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-6 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, [`Expand`](/api/modules/server.md#expand)<`VectorIndexes` & `Record`<`IndexName`, { `vectorField`: `VectorField` ; `dimensions`: `number` ; `filterFields`: `FilterFields` }>>>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this vector index included.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/schema.ts:448](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L448)

▸ **vectorIndex**<`IndexName`, `VectorField`, `FilterFields`>(`name`, `indexConfig`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

Define a staged vector index on this table.

For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.

If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries.

To learn about vector indexes, see [Vector Search](https://docs.convex.dev/vector-search).

#### Type parameters[​](#type-parameters-7 "Direct link to Type parameters")

| Name           | Type                    |
| -------------- | ----------------------- |
| `IndexName`    | extends `string`        |
| `VectorField`  | extends `any`           |
| `FilterFields` | extends `any` = `never` |

#### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name                        | Type              | Description                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                      | `IndexName`       | The name of the index.                                                                                                                                                                                                                                                                                                                                        |
| `indexConfig`               | `Object`          | The vector index configuration object.                                                                                                                                                                                                                                                                                                                        |
| `indexConfig.vectorField`   | `VectorField`     | The field to index for vector search. This must be a field of type `v.array(v.float64())` (or a union)                                                                                                                                                                                                                                                        |
| `indexConfig.dimensions`    | `number`          | The length of the vectors indexed. This must be between 2 and 2048 inclusive.                                                                                                                                                                                                                                                                                 |
| `indexConfig.filterFields?` | `FilterFields`\[] | Additional fields to index for fast filtering when running vector searches.                                                                                                                                                                                                                                                                                   |
| `indexConfig.staged`        | `true`            | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If `staged` is `true`, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |

#### Returns[​](#returns-7 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

A [TableDefinition](/api/classes/server.TableDefinition.md) with this vector index included.

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/schema.ts:491](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L491)

***

### self[​](#self "Direct link to self")

▸ `Protected` **self**(): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

Work around for <https://github.com/microsoft/TypeScript/issues/57035>

#### Returns[​](#returns-8 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`>

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/schema.ts:534](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L534)

---

# Source: https://docs.convex.dev/api/interfaces/server.UserIdentity.md

# Interface: UserIdentity

[server](/api/modules/server.md).UserIdentity

Information about an authenticated user, derived from a [JWT](https://datatracker.ietf.org/doc/html/rfc7519).

The only fields guaranteed to be present are [tokenIdentifier](/api/interfaces/server.UserIdentity.md#tokenidentifier) and [issuer](/api/interfaces/server.UserIdentity.md#issuer). All remaining fields may or may not be present depending on the information given by the identity provider.

The explicitly listed fields are derived from the OpenID Connect (OIDC) standard fields, see the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) for more information on these fields.

Any additional fields are custom claims that may be present in the JWT, and their type depends on your identity provider configuration. If you know the type of the field, you can assert it in TypeScript like this (for example as a `string`):

```
const identity = await ctx.auth.getUserIdentity();
if (identity === null) {
  return null;
}
const customClaim = identity.custom_claim as string;
```

## Indexable[​](#indexable "Direct link to Indexable")

▪ \[key: `string`]: [`JSONValue`](/api/modules/values.md#jsonvalue) | `undefined`

## Properties[​](#properties "Direct link to Properties")

### tokenIdentifier[​](#tokenidentifier "Direct link to tokenIdentifier")

• `Readonly` **tokenIdentifier**: `string`

A stable and globally unique string for this identity (i.e. no other user, even from a different identity provider, will have the same string.)

JWT claims: `sub` + `iss`

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/authentication.ts:107](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L107)

***

### subject[​](#subject "Direct link to subject")

• `Readonly` **subject**: `string`

Identifier for the end-user from the identity provider, not necessarily unique across different providers.

JWT claim: `sub`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/authentication.ts:115](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L115)

***

### issuer[​](#issuer "Direct link to issuer")

• `Readonly` **issuer**: `string`

The hostname of the identity provider used to authenticate this user.

JWT claim: `iss`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/authentication.ts:122](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L122)

***

### name[​](#name "Direct link to name")

• `Optional` `Readonly` **name**: `string`

JWT claim: `name`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/authentication.ts:127](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L127)

***

### givenName[​](#givenname "Direct link to givenName")

• `Optional` `Readonly` **givenName**: `string`

JWT claim: `given_name`

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/authentication.ts:132](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L132)

***

### familyName[​](#familyname "Direct link to familyName")

• `Optional` `Readonly` **familyName**: `string`

JWT claim: `family_name`

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/authentication.ts:137](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L137)

***

### nickname[​](#nickname "Direct link to nickname")

• `Optional` `Readonly` **nickname**: `string`

JWT claim: `nickname`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/authentication.ts:142](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L142)

***

### preferredUsername[​](#preferredusername "Direct link to preferredUsername")

• `Optional` `Readonly` **preferredUsername**: `string`

JWT claim: `preferred_username`

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/authentication.ts:147](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L147)

***

### profileUrl[​](#profileurl "Direct link to profileUrl")

• `Optional` `Readonly` **profileUrl**: `string`

JWT claim: `profile`

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/authentication.ts:152](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L152)

***

### pictureUrl[​](#pictureurl "Direct link to pictureUrl")

• `Optional` `Readonly` **pictureUrl**: `string`

JWT claim: `picture`

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/authentication.ts:157](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L157)

***

### email[​](#email "Direct link to email")

• `Optional` `Readonly` **email**: `string`

JWT claim: `email`

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/authentication.ts:162](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L162)

***

### emailVerified[​](#emailverified "Direct link to emailVerified")

• `Optional` `Readonly` **emailVerified**: `boolean`

JWT claim: `email_verified`

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[server/authentication.ts:167](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L167)

***

### gender[​](#gender "Direct link to gender")

• `Optional` `Readonly` **gender**: `string`

JWT claim: `gender`

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[server/authentication.ts:172](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L172)

***

### birthday[​](#birthday "Direct link to birthday")

• `Optional` `Readonly` **birthday**: `string`

JWT claim: `birthdate`

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[server/authentication.ts:177](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L177)

***

### timezone[​](#timezone "Direct link to timezone")

• `Optional` `Readonly` **timezone**: `string`

JWT claim: `zoneinfo`

#### Defined in[​](#defined-in-14 "Direct link to Defined in")

[server/authentication.ts:182](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L182)

***

### language[​](#language "Direct link to language")

• `Optional` `Readonly` **language**: `string`

JWT claim: `locale`

#### Defined in[​](#defined-in-15 "Direct link to Defined in")

[server/authentication.ts:187](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L187)

***

### phoneNumber[​](#phonenumber "Direct link to phoneNumber")

• `Optional` `Readonly` **phoneNumber**: `string`

JWT claim: `phone_number`

#### Defined in[​](#defined-in-16 "Direct link to Defined in")

[server/authentication.ts:192](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L192)

***

### phoneNumberVerified[​](#phonenumberverified "Direct link to phoneNumberVerified")

• `Optional` `Readonly` **phoneNumberVerified**: `boolean`

JWT claim: `phone_number_verified`

#### Defined in[​](#defined-in-17 "Direct link to Defined in")

[server/authentication.ts:197](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L197)

***

### address[​](#address "Direct link to address")

• `Optional` `Readonly` **address**: `string`

JWT claim: `address`

#### Defined in[​](#defined-in-18 "Direct link to Defined in")

[server/authentication.ts:202](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L202)

***

### updatedAt[​](#updatedat "Direct link to updatedAt")

• `Optional` `Readonly` **updatedAt**: `string`

JWT claim: `updated_at`

#### Defined in[​](#defined-in-19 "Direct link to Defined in")

[server/authentication.ts:207](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L207)

---

# Source: https://docs.convex.dev/api/interfaces/server.ValidatedFunction.md

# Interface: ValidatedFunction\<Ctx, ArgsValidator, Returns>

[server](/api/modules/server.md).ValidatedFunction

**`Deprecated`**

\-- See the type definition for `MutationBuilder` or similar for the types used for defining Convex functions.

The definition of a Convex query, mutation, or action function with argument validation.

Argument validation allows you to assert that the arguments to this function are the expected type.

Example:

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

export const func = query({
  args: {
    arg: v.string()
  },
  handler: ({ db }, { arg }) => {...},
});
```

**For security, argument validation should be added to all public functions in production apps.**

See [UnvalidatedFunction](/api/modules/server.md#unvalidatedfunction) for functions without argument validation.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name            | Type                                                                      |
| --------------- | ------------------------------------------------------------------------- |
| `Ctx`           | `Ctx`                                                                     |
| `ArgsValidator` | extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) |
| `Returns`       | `Returns`                                                                 |

## Properties[​](#properties "Direct link to Properties")

### args[​](#args "Direct link to args")

• **args**: `ArgsValidator`

A validator for the arguments of this function.

This is an object mapping argument names to validators constructed with [v](/api/modules/values.md#v).

```
import { v } from "convex/values";

const args = {
  stringArg: v.string(),
  optionalNumberArg: v.optional(v.number()),
}
```

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/registration.ts:528](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L528)

***

### handler[​](#handler "Direct link to handler")

• **handler**: (`ctx`: `Ctx`, `args`: [`ObjectType`](/api/modules/values.md#objecttype)<`ArgsValidator`>) => `Returns`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

▸ (`ctx`, `args`): `Returns`

The implementation of this function.

This is a function that takes in the appropriate context and arguments and produces some result.

##### Parameters[​](#parameters "Direct link to Parameters")

| Name   | Type                                                               | Description                                                                                            |
| ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `ctx`  | `Ctx`                                                              | The context object. This is one of QueryCtx, MutationCtx, or ActionCtx depending on the function type. |
| `args` | [`ObjectType`](/api/modules/values.md#objecttype)<`ArgsValidator`> | The arguments object for this function. This will match the type defined by the argument validator.    |

##### Returns[​](#returns "Direct link to Returns")

`Returns`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/registration.ts:542](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L542)

---

# Source: https://docs.convex.dev/api/interfaces/server.VectorFilterBuilder.md

# Interface: VectorFilterBuilder\<Document, VectorIndexConfig>

[server](/api/modules/server.md).VectorFilterBuilder

An interface for defining filters for vector searches.

This has a similar interface to [FilterBuilder](/api/interfaces/server.FilterBuilder.md), which is used in database queries, but supports only the methods that can be efficiently done in a vector search.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name                | Type                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------- |
| `Document`          | extends [`GenericDocument`](/api/modules/server.md#genericdocument)                   |
| `VectorIndexConfig` | extends [`GenericVectorIndexConfig`](/api/modules/server.md#genericvectorindexconfig) |

## Methods[​](#methods "Direct link to Methods")

### eq[​](#eq "Direct link to eq")

▸ **eq**<`FieldName`>(`fieldName`, `value`): [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

Is the field at `fieldName` equal to `value`

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `FieldName` | extends `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name        | Type                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------- |
| `fieldName` | `FieldName`                                                                                        |
| `value`     | [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`Document`, `FieldName`> |

#### Returns[​](#returns "Direct link to Returns")

[`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/vector\_search.ts:110](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L110)

***

### or[​](#or "Direct link to or")

▸ **or**(`...exprs`): [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

`exprs[0] || exprs[1] || ... || exprs[n]`

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name       | Type                                                                        |
| ---------- | --------------------------------------------------------------------------- |
| `...exprs` | [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>\[] |

#### Returns[​](#returns-1 "Direct link to Returns")

[`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/vector\_search.ts:122](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L122)

---

# Source: https://docs.convex.dev/api/interfaces/server.VectorIndexConfig.md

# Interface: VectorIndexConfig\<VectorField, FilterFields>

[server](/api/modules/server.md).VectorIndexConfig

The configuration for a vector index.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name           | Type             |
| -------------- | ---------------- |
| `VectorField`  | extends `string` |
| `FilterFields` | extends `string` |

## Properties[​](#properties "Direct link to Properties")

### vectorField[​](#vectorfield "Direct link to vectorField")

• **vectorField**: `VectorField`

The field to index for vector search.

This must be a field of type `v.array(v.float64())` (or a union)

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/schema.ts:123](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L123)

***

### dimensions[​](#dimensions "Direct link to dimensions")

• **dimensions**: `number`

The length of the vectors indexed. This must be between 2 and 2048 inclusive.

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/schema.ts:127](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L127)

***

### filterFields[​](#filterfields "Direct link to filterFields")

• `Optional` **filterFields**: `FilterFields`\[]

Additional fields to index for fast filtering when running vector searches.

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/schema.ts:131](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L131)

---

# Source: https://docs.convex.dev/api/interfaces/server.VectorSearchQuery.md

# Interface: VectorSearchQuery\<TableInfo, IndexName>

[server](/api/modules/server.md).VectorSearchQuery

An object with parameters for performing a vector search against a vector index.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name        | Type                                                                               |
| ----------- | ---------------------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo)              |
| `IndexName` | extends [`VectorIndexNames`](/api/modules/server.md#vectorindexnames)<`TableInfo`> |

## Properties[​](#properties "Direct link to Properties")

### vector[​](#vector "Direct link to vector")

• **vector**: `number`\[]

The query vector.

This must have the same length as the `dimensions` of the index. This vector search will return the IDs of the documents most similar to this vector.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/vector\_search.ts:30](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L30)

***

### limit[​](#limit "Direct link to limit")

• `Optional` **limit**: `number`

The number of results to return. If specified, must be between 1 and 256 inclusive.

**`Default`**

```
10
```

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/vector\_search.ts:37](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L37)

***

### filter[​](#filter "Direct link to filter")

• `Optional` **filter**: (`q`: [`VectorFilterBuilder`](/api/interfaces/server.VectorFilterBuilder.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, [`NamedVectorIndex`](/api/modules/server.md#namedvectorindex)<`TableInfo`, `IndexName`>>) => [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

▸ (`q`): [`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

Optional filter expression made up of `q.or` and `q.eq` operating over the filter fields of the index.

e.g. `filter: q => q.or(q.eq("genre", "comedy"), q.eq("genre", "drama"))`

##### Parameters[​](#parameters "Direct link to Parameters")

| Name | Type                                                                                                                                                                                                                                    |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`  | [`VectorFilterBuilder`](/api/interfaces/server.VectorFilterBuilder.md)<[`DocumentByInfo`](/api/modules/server.md#documentbyinfo)<`TableInfo`>, [`NamedVectorIndex`](/api/modules/server.md#namedvectorindex)<`TableInfo`, `IndexName`>> |

##### Returns[​](#returns "Direct link to Returns")

[`FilterExpression`](/api/classes/server.FilterExpression.md)<`boolean`>

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/vector\_search.ts:47](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L47)

---

# Source: https://docs.convex.dev/generated-api/server.md

# Source: https://docs.convex.dev/api/modules/server.md

# Module: server

Utilities for implementing server-side Convex query and mutation functions.

## Usage[​](#usage "Direct link to Usage")

### Code Generation[​](#code-generation "Direct link to Code Generation")

This module is typically used alongside generated server code.

To generate the server code, run `npx convex dev` in your Convex project. This will create a `convex/_generated/server.js` file with the following functions, typed for your schema:

* [query](https://docs.convex.dev/generated-api/server#query)
* [mutation](https://docs.convex.dev/generated-api/server#mutation)

If you aren't using TypeScript and code generation, you can use these untyped functions instead:

* [queryGeneric](/api/modules/server.md#querygeneric)
* [mutationGeneric](/api/modules/server.md#mutationgeneric)

### Example[​](#example "Direct link to Example")

Convex functions are defined by using either the `query` or `mutation` wrappers.

Queries receive a `db` that implements the [GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md) interface.

```
import { query } from "./_generated/server";

export default query({
  handler: async ({ db }, { arg1, arg2 }) => {
    // Your (read-only) code here!
  },
});
```

If your function needs to write to the database, such as inserting, updating, or deleting documents, use `mutation` instead which provides a `db` that implements the [GenericDatabaseWriter](/api/interfaces/server.GenericDatabaseWriter.md) interface.

```
import { mutation } from "./_generated/server";

export default mutation({
  handler: async ({ db }, { arg1, arg2 }) => {
    // Your mutation code here!
  },
});
```

## Classes[​](#classes "Direct link to Classes")

* [Crons](/api/classes/server.Crons.md)
* [Expression](/api/classes/server.Expression.md)
* [IndexRange](/api/classes/server.IndexRange.md)
* [HttpRouter](/api/classes/server.HttpRouter.md)
* [TableDefinition](/api/classes/server.TableDefinition.md)
* [SchemaDefinition](/api/classes/server.SchemaDefinition.md)
* [SearchFilter](/api/classes/server.SearchFilter.md)
* [FilterExpression](/api/classes/server.FilterExpression.md)

## Interfaces[​](#interfaces "Direct link to Interfaces")

* [UserIdentity](/api/interfaces/server.UserIdentity.md)
* [Auth](/api/interfaces/server.Auth.md)
* [CronJob](/api/interfaces/server.CronJob.md)
* [BaseTableReader](/api/interfaces/server.BaseTableReader.md)
* [GenericDatabaseReader](/api/interfaces/server.GenericDatabaseReader.md)
* [GenericDatabaseReaderWithTable](/api/interfaces/server.GenericDatabaseReaderWithTable.md)
* [GenericDatabaseWriter](/api/interfaces/server.GenericDatabaseWriter.md)
* [GenericDatabaseWriterWithTable](/api/interfaces/server.GenericDatabaseWriterWithTable.md)
* [BaseTableWriter](/api/interfaces/server.BaseTableWriter.md)
* [FilterBuilder](/api/interfaces/server.FilterBuilder.md)
* [IndexRangeBuilder](/api/interfaces/server.IndexRangeBuilder.md)
* [PaginationResult](/api/interfaces/server.PaginationResult.md)
* [PaginationOptions](/api/interfaces/server.PaginationOptions.md)
* [QueryInitializer](/api/interfaces/server.QueryInitializer.md)
* [Query](/api/interfaces/server.Query.md)
* [OrderedQuery](/api/interfaces/server.OrderedQuery.md)
* [GenericMutationCtx](/api/interfaces/server.GenericMutationCtx.md)
* [GenericQueryCtx](/api/interfaces/server.GenericQueryCtx.md)
* [GenericActionCtx](/api/interfaces/server.GenericActionCtx.md)
* [ValidatedFunction](/api/interfaces/server.ValidatedFunction.md)
* [Scheduler](/api/interfaces/server.Scheduler.md)
* [SearchIndexConfig](/api/interfaces/server.SearchIndexConfig.md)
* [VectorIndexConfig](/api/interfaces/server.VectorIndexConfig.md)
* [DefineSchemaOptions](/api/interfaces/server.DefineSchemaOptions.md)
* [SystemDataModel](/api/interfaces/server.SystemDataModel.md)
* [SearchFilterBuilder](/api/interfaces/server.SearchFilterBuilder.md)
* [SearchFilterFinalizer](/api/interfaces/server.SearchFilterFinalizer.md)
* [StorageReader](/api/interfaces/server.StorageReader.md)
* [StorageWriter](/api/interfaces/server.StorageWriter.md)
* [StorageActionWriter](/api/interfaces/server.StorageActionWriter.md)
* [VectorSearchQuery](/api/interfaces/server.VectorSearchQuery.md)
* [VectorFilterBuilder](/api/interfaces/server.VectorFilterBuilder.md)

## References[​](#references "Direct link to References")

### UserIdentityAttributes[​](#useridentityattributes "Direct link to UserIdentityAttributes")

Re-exports [UserIdentityAttributes](/api/modules/browser.md#useridentityattributes)

## Type Aliases[​](#type-aliases "Direct link to Type Aliases")

### FunctionType[​](#functiontype "Direct link to FunctionType")

Ƭ **FunctionType**: `"query"` | `"mutation"` | `"action"`

The type of a Convex function.

#### Defined in[​](#defined-in "Direct link to Defined in")

[server/api.ts:19](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L19)

***

### FunctionReference[​](#functionreference "Direct link to FunctionReference")

Ƭ **FunctionReference**<`Type`, `Visibility`, `Args`, `ReturnType`, `ComponentPath`>: `Object`

A reference to a registered Convex function.

You can create a [FunctionReference](/api/modules/server.md#functionreference) using the generated `api` utility:

```
import { api } from "../convex/_generated/api";

const reference = api.myModule.myFunction;
```

If you aren't using code generation, you can create references using [anyApi](/api/modules/server.md#anyapi-1):

```
import { anyApi } from "convex/server";

const reference = anyApi.myModule.myFunction;
```

Function references can be used to invoke functions from the client. For example, in React you can pass references to the [useQuery](/api/modules/react.md#usequery) hook:

```
const result = useQuery(api.myModule.myFunction);
```

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name            | Type                                                                                   | Description                                                                              |
| --------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Type`          | extends [`FunctionType`](/api/modules/server.md#functiontype)                          | The type of the function ("query", "mutation", or "action").                             |
| `Visibility`    | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) = `"public"` | The visibility of the function ("public" or "internal").                                 |
| `Args`          | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) = `any`    | The arguments to this function. This is an object mapping argument names to their types. |
| `ReturnType`    | `any`                                                                                  | The return type of this function.                                                        |
| `ComponentPath` | `string` \| `undefined`                                                                | -                                                                                        |

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name             | Type            |
| ---------------- | --------------- |
| `_type`          | `Type`          |
| `_visibility`    | `Visibility`    |
| `_args`          | `Args`          |
| `_returnType`    | `ReturnType`    |
| `_componentPath` | `ComponentPath` |

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[server/api.ts:52](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L52)

***

### ApiFromModules[​](#apifrommodules "Direct link to ApiFromModules")

Ƭ **ApiFromModules**<`AllModules`>: [`FilterApi`](/api/modules/server.md#filterapi)<`ApiFromModulesAllowEmptyNodes`<`AllModules`>, [`FunctionReference`](/api/modules/server.md#functionreference)<`any`, `any`, `any`, `any`>>

Given the types of all modules in the `convex/` directory, construct the type of `api`.

`api` is a utility for constructing [FunctionReference](/api/modules/server.md#functionreference)s.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                 | Description                                                                      |
| ------------ | ------------------------------------ | -------------------------------------------------------------------------------- |
| `AllModules` | extends `Record`<`string`, `object`> | A type mapping module paths (like `"dir/myModule"`) to the types of the modules. |

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[server/api.ts:255](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L255)

***

### FilterApi[​](#filterapi "Direct link to FilterApi")

Ƭ **FilterApi**<`API`, `Predicate`>: [`Expand`](/api/modules/server.md#expand)<{ \[mod in keyof API as API\[mod] extends Predicate ? mod : API\[mod] extends FunctionReference\<any, any, any, any> ? never : FilterApi\<API\[mod], Predicate> extends Record\<string, never> ? never : mod]: API\[mod] extends Predicate ? API\[mod] : FilterApi\<API\[mod], Predicate> }>

Filter a Convex deployment api object for functions which meet criteria, for example all public queries.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name        |
| ----------- |
| `API`       |
| `Predicate` |

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[server/api.ts:279](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L279)

***

### AnyApi[​](#anyapi "Direct link to AnyApi")

Ƭ **AnyApi**: `Record`<`string`, `Record`<`string`, `AnyModuleDirOrFunc`>>

The type that Convex api objects extend. If you were writing an api from scratch it should extend this type.

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[server/api.ts:393](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L393)

***

### PartialApi[​](#partialapi "Direct link to PartialApi")

Ƭ **PartialApi**<`API`>: { \[mod in keyof API]?: API\[mod] extends FunctionReference\<any, any, any, any> ? API\[mod] : PartialApi\<API\[mod]> }

Recursive partial API, useful for defining a subset of an API when mocking or building custom api objects.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name  |
| ----- |
| `API` |

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[server/api.ts:401](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L401)

***

### FunctionArgs[​](#functionargs "Direct link to FunctionArgs")

Ƭ **FunctionArgs**<`FuncRef`>: `FuncRef`\[`"_args"`]

Given a [FunctionReference](/api/modules/server.md#functionreference), get the return type of the function.

This is represented as an object mapping argument names to values.

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name      | Type                           |
| --------- | ------------------------------ |
| `FuncRef` | extends `AnyFunctionReference` |

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[server/api.ts:435](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L435)

***

### OptionalRestArgs[​](#optionalrestargs "Direct link to OptionalRestArgs")

Ƭ **OptionalRestArgs**<`FuncRef`>: `FuncRef`\[`"_args"`] extends `EmptyObject` ? \[args?: EmptyObject] : \[args: FuncRef\["\_args"]]

A tuple type of the (maybe optional) arguments to `FuncRef`.

This type is used to make methods involving arguments type safe while allowing skipping the arguments for functions that don't require arguments.

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name      | Type                           |
| --------- | ------------------------------ |
| `FuncRef` | extends `AnyFunctionReference` |

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[server/api.ts:446](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L446)

***

### ArgsAndOptions[​](#argsandoptions "Direct link to ArgsAndOptions")

Ƭ **ArgsAndOptions**<`FuncRef`, `Options`>: `FuncRef`\[`"_args"`] extends `EmptyObject` ? \[args?: EmptyObject, options?: Options] : \[args: FuncRef\["\_args"], options?: Options]

A tuple type of the (maybe optional) arguments to `FuncRef`, followed by an options object of type `Options`.

This type is used to make methods like `useQuery` type-safe while allowing

1. Skipping arguments for functions that don't require arguments.
2. Skipping the options object.

#### Type parameters[​](#type-parameters-6 "Direct link to Type parameters")

| Name      | Type                           |
| --------- | ------------------------------ |
| `FuncRef` | extends `AnyFunctionReference` |
| `Options` | `Options`                      |

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[server/api.ts:460](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L460)

***

### FunctionReturnType[​](#functionreturntype "Direct link to FunctionReturnType")

Ƭ **FunctionReturnType**<`FuncRef`>: `FuncRef`\[`"_returnType"`]

Given a [FunctionReference](/api/modules/server.md#functionreference), get the return type of the function.

#### Type parameters[​](#type-parameters-7 "Direct link to Type parameters")

| Name      | Type                           |
| --------- | ------------------------------ |
| `FuncRef` | extends `AnyFunctionReference` |

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[server/api.ts:472](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L472)

***

### AuthConfig[​](#authconfig "Direct link to AuthConfig")

Ƭ **AuthConfig**: `Object`

The value exported by your Convex project in `auth.config.ts`.

```
import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: "https://your.issuer.url.com",
      applicationID: "your-application-id",
    },
  ],
} satisfies AuthConfig;
```

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

| Name        | Type                                                     |
| ----------- | -------------------------------------------------------- |
| `providers` | [`AuthProvider`](/api/modules/server.md#authprovider)\[] |

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[server/authentication.ts:19](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L19)

***

### AuthProvider[​](#authprovider "Direct link to AuthProvider")

Ƭ **AuthProvider**: { `applicationID`: `string` ; `domain`: `string` } | { `type`: `"customJwt"` ; `applicationID?`: `string` ; `issuer`: `string` ; `jwks`: `string` ; `algorithm`: `"RS256"` | `"ES256"` }

An authentication provider allowed to issue JWTs for your app.

See: <https://docs.convex.dev/auth/advanced/custom-auth> and <https://docs.convex.dev/auth/advanced/custom-jwt>

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[server/authentication.ts:28](https://github.com/get-convex/convex-js/blob/main/src/server/authentication.ts#L28)

***

### FunctionHandle[​](#functionhandle "Direct link to FunctionHandle")

Ƭ **FunctionHandle**<`Type`, `Args`, `ReturnType`>: `string` & [`FunctionReference`](/api/modules/server.md#functionreference)<`Type`, `"internal"`, `Args`, `ReturnType`>

A serializable reference to a Convex function. Passing a this reference to another component allows that component to call this function during the current function execution or at any later time. Function handles are used like `api.folder.function` FunctionReferences, e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.

A function reference is stable across code pushes but it's possible the Convex function it refers to might no longer exist.

This is a feature of components, which are in beta. This API is unstable and may change in subsequent releases.

#### Type parameters[​](#type-parameters-8 "Direct link to Type parameters")

| Name         | Type                                                                                |
| ------------ | ----------------------------------------------------------------------------------- |
| `Type`       | extends [`FunctionType`](/api/modules/server.md#functiontype)                       |
| `Args`       | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) = `any` |
| `ReturnType` | `any`                                                                               |

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[server/components/index.ts:35](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L35)

***

### ComponentDefinition[​](#componentdefinition "Direct link to ComponentDefinition")

Ƭ **ComponentDefinition**<`Exports`>: `Object`

An object of this type should be the default export of a convex.config.ts file in a component definition directory.

This is a feature of components, which are in beta. This API is unstable and may change in subsequent releases.

#### Type parameters[​](#type-parameters-9 "Direct link to Type parameters")

| Name      | Type                               |
| --------- | ---------------------------------- |
| `Exports` | extends `ComponentExports` = `any` |

#### Type declaration[​](#type-declaration-2 "Direct link to Type declaration")

| Name        | Type                                                                                                               | Description                                                                                                                                                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `use`       | \<Definition>(`definition`: `Definition`, `options?`: { `name?`: `string` }) => `InstalledComponent`<`Definition`> | Install a component with the given definition in this component definition. Takes a component definition and an optional name. For editor tooling this method expects a [ComponentDefinition](/api/modules/server.md#componentdefinition) but at runtime the object that is imported will be a ImportedComponentDefinition |
| `__exports` | `Exports`                                                                                                          | Internal type-only property tracking exports provided. **`Deprecated`** This is a type-only property, don't use it.                                                                                                                                                                                                        |

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[server/components/index.ts:84](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L84)

***

### AnyChildComponents[​](#anychildcomponents "Direct link to AnyChildComponents")

Ƭ **AnyChildComponents**: `Record`<`string`, `AnyComponentReference`>

#### Defined in[​](#defined-in-14 "Direct link to Defined in")

[server/components/index.ts:414](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L414)

***

### AnyComponents[​](#anycomponents "Direct link to AnyComponents")

Ƭ **AnyComponents**: [`AnyChildComponents`](/api/modules/server.md#anychildcomponents)

#### Defined in[​](#defined-in-15 "Direct link to Defined in")

[server/components/index.ts:454](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L454)

***

### GenericDocument[​](#genericdocument "Direct link to GenericDocument")

Ƭ **GenericDocument**: `Record`<`string`, [`Value`](/api/modules/values.md#value)>

A document stored in Convex.

#### Defined in[​](#defined-in-16 "Direct link to Defined in")

[server/data\_model.ts:9](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L9)

***

### GenericFieldPaths[​](#genericfieldpaths "Direct link to GenericFieldPaths")

Ƭ **GenericFieldPaths**: `string`

A type describing all of the document fields in a table.

These can either be field names (like "name") or references to fields on nested objects (like "properties.name").

#### Defined in[​](#defined-in-17 "Direct link to Defined in")

[server/data\_model.ts:18](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L18)

***

### GenericIndexFields[​](#genericindexfields "Direct link to GenericIndexFields")

Ƭ **GenericIndexFields**: `string`\[]

A type describing the ordered fields in an index.

These can either be field names (like "name") or references to fields on nested objects (like "properties.name").

#### Defined in[​](#defined-in-18 "Direct link to Defined in")

[server/data\_model.ts:29](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L29)

***

### GenericTableIndexes[​](#generictableindexes "Direct link to GenericTableIndexes")

Ƭ **GenericTableIndexes**: `Record`<`string`, [`GenericIndexFields`](/api/modules/server.md#genericindexfields)>

A type describing the indexes in a table.

It's an object mapping each index name to the fields in the index.

#### Defined in[​](#defined-in-19 "Direct link to Defined in")

[server/data\_model.ts:37](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L37)

***

### GenericSearchIndexConfig[​](#genericsearchindexconfig "Direct link to GenericSearchIndexConfig")

Ƭ **GenericSearchIndexConfig**: `Object`

A type describing the configuration of a search index.

#### Type declaration[​](#type-declaration-3 "Direct link to Type declaration")

| Name           | Type     |
| -------------- | -------- |
| `searchField`  | `string` |
| `filterFields` | `string` |

#### Defined in[​](#defined-in-20 "Direct link to Defined in")

[server/data\_model.ts:43](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L43)

***

### GenericTableSearchIndexes[​](#generictablesearchindexes "Direct link to GenericTableSearchIndexes")

Ƭ **GenericTableSearchIndexes**: `Record`<`string`, [`GenericSearchIndexConfig`](/api/modules/server.md#genericsearchindexconfig)>

A type describing all of the search indexes in a table.

This is an object mapping each index name to the config for the index.

#### Defined in[​](#defined-in-21 "Direct link to Defined in")

[server/data\_model.ts:54](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L54)

***

### GenericVectorIndexConfig[​](#genericvectorindexconfig "Direct link to GenericVectorIndexConfig")

Ƭ **GenericVectorIndexConfig**: `Object`

A type describing the configuration of a vector index.

#### Type declaration[​](#type-declaration-4 "Direct link to Type declaration")

| Name           | Type     |
| -------------- | -------- |
| `vectorField`  | `string` |
| `dimensions`   | `number` |
| `filterFields` | `string` |

#### Defined in[​](#defined-in-22 "Direct link to Defined in")

[server/data\_model.ts:63](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L63)

***

### GenericTableVectorIndexes[​](#generictablevectorindexes "Direct link to GenericTableVectorIndexes")

Ƭ **GenericTableVectorIndexes**: `Record`<`string`, [`GenericVectorIndexConfig`](/api/modules/server.md#genericvectorindexconfig)>

A type describing all of the vector indexes in a table.

This is an object mapping each index name to the config for the index.

#### Defined in[​](#defined-in-23 "Direct link to Defined in")

[server/data\_model.ts:75](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L75)

***

### FieldTypeFromFieldPath[​](#fieldtypefromfieldpath "Direct link to FieldTypeFromFieldPath")

Ƭ **FieldTypeFromFieldPath**<`Document`, `FieldPath`>: [`FieldTypeFromFieldPathInner`](/api/modules/server.md#fieldtypefromfieldpathinner)<`Document`, `FieldPath`> extends [`Value`](/api/modules/values.md#value) | `undefined` ? [`FieldTypeFromFieldPathInner`](/api/modules/server.md#fieldtypefromfieldpathinner)<`Document`, `FieldPath`> : [`Value`](/api/modules/values.md#value) | `undefined`

The type of a field in a document.

Note that this supports both simple fields like "name" and nested fields like "properties.name".

If the field is not present in the document it is considered to be `undefined`.

#### Type parameters[​](#type-parameters-10 "Direct link to Type parameters")

| Name        | Type                                                                |
| ----------- | ------------------------------------------------------------------- |
| `Document`  | extends [`GenericDocument`](/api/modules/server.md#genericdocument) |
| `FieldPath` | extends `string`                                                    |

#### Defined in[​](#defined-in-24 "Direct link to Defined in")

[server/data\_model.ts:104](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L104)

***

### FieldTypeFromFieldPathInner[​](#fieldtypefromfieldpathinner "Direct link to FieldTypeFromFieldPathInner")

Ƭ **FieldTypeFromFieldPathInner**<`Document`, `FieldPath`>: `FieldPath` extends \`${infer First}.${infer Second}\` ? `ValueFromUnion`<`Document`, `First`, `Record`<`never`, `never`>> extends infer FieldValue ? `FieldValue` extends [`GenericDocument`](/api/modules/server.md#genericdocument) ? [`FieldTypeFromFieldPath`](/api/modules/server.md#fieldtypefromfieldpath)<`FieldValue`, `Second`> : `undefined` : `undefined` : `ValueFromUnion`<`Document`, `FieldPath`, `undefined`>

The inner type of [FieldTypeFromFieldPath](/api/modules/server.md#fieldtypefromfieldpath).

It's wrapped in a helper to coerce the type to `Value | undefined` since some versions of TypeScript fail to infer this type correctly.

#### Type parameters[​](#type-parameters-11 "Direct link to Type parameters")

| Name        | Type                                                                |
| ----------- | ------------------------------------------------------------------- |
| `Document`  | extends [`GenericDocument`](/api/modules/server.md#genericdocument) |
| `FieldPath` | extends `string`                                                    |

#### Defined in[​](#defined-in-25 "Direct link to Defined in")

[server/data\_model.ts:120](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L120)

***

### GenericTableInfo[​](#generictableinfo "Direct link to GenericTableInfo")

Ƭ **GenericTableInfo**: `Object`

A type describing the document type and indexes in a table.

#### Type declaration[​](#type-declaration-5 "Direct link to Type declaration")

| Name            | Type                                                                            |
| --------------- | ------------------------------------------------------------------------------- |
| `document`      | [`GenericDocument`](/api/modules/server.md#genericdocument)                     |
| `fieldPaths`    | [`GenericFieldPaths`](/api/modules/server.md#genericfieldpaths)                 |
| `indexes`       | [`GenericTableIndexes`](/api/modules/server.md#generictableindexes)             |
| `searchIndexes` | [`GenericTableSearchIndexes`](/api/modules/server.md#generictablesearchindexes) |
| `vectorIndexes` | [`GenericTableVectorIndexes`](/api/modules/server.md#generictablevectorindexes) |

#### Defined in[​](#defined-in-26 "Direct link to Defined in")

[server/data\_model.ts:145](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L145)

***

### DocumentByInfo[​](#documentbyinfo "Direct link to DocumentByInfo")

Ƭ **DocumentByInfo**<`TableInfo`>: `TableInfo`\[`"document"`]

The type of a document in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

#### Type parameters[​](#type-parameters-12 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-27 "Direct link to Defined in")

[server/data\_model.ts:157](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L157)

***

### FieldPaths[​](#fieldpaths "Direct link to FieldPaths")

Ƭ **FieldPaths**<`TableInfo`>: `TableInfo`\[`"fieldPaths"`]

The field paths in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

These can either be field names (like "name") or references to fields on nested objects (like "properties.name").

#### Type parameters[​](#type-parameters-13 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-28 "Direct link to Defined in")

[server/data\_model.ts:167](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L167)

***

### Indexes[​](#indexes "Direct link to Indexes")

Ƭ **Indexes**<`TableInfo`>: `TableInfo`\[`"indexes"`]

The database indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

This will be an object mapping index names to the fields in the index.

#### Type parameters[​](#type-parameters-14 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-29 "Direct link to Defined in")

[server/data\_model.ts:176](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L176)

***

### IndexNames[​](#indexnames "Direct link to IndexNames")

Ƭ **IndexNames**<`TableInfo`>: keyof [`Indexes`](/api/modules/server.md#indexes)<`TableInfo`>

The names of indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

#### Type parameters[​](#type-parameters-15 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-30 "Direct link to Defined in")

[server/data\_model.ts:182](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L182)

***

### NamedIndex[​](#namedindex "Direct link to NamedIndex")

Ƭ **NamedIndex**<`TableInfo`, `IndexName`>: [`Indexes`](/api/modules/server.md#indexes)<`TableInfo`>\[`IndexName`]

Extract the fields of an index from a [GenericTableInfo](/api/modules/server.md#generictableinfo) by name.

#### Type parameters[​](#type-parameters-16 "Direct link to Type parameters")

| Name        | Type                                                                   |
| ----------- | ---------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo)  |
| `IndexName` | extends [`IndexNames`](/api/modules/server.md#indexnames)<`TableInfo`> |

#### Defined in[​](#defined-in-31 "Direct link to Defined in")

[server/data\_model.ts:189](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L189)

***

### SearchIndexes[​](#searchindexes "Direct link to SearchIndexes")

Ƭ **SearchIndexes**<`TableInfo`>: `TableInfo`\[`"searchIndexes"`]

The search indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

This will be an object mapping index names to the search index config.

#### Type parameters[​](#type-parameters-17 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-32 "Direct link to Defined in")

[server/data\_model.ts:200](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L200)

***

### SearchIndexNames[​](#searchindexnames "Direct link to SearchIndexNames")

Ƭ **SearchIndexNames**<`TableInfo`>: keyof [`SearchIndexes`](/api/modules/server.md#searchindexes)<`TableInfo`>

The names of search indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

#### Type parameters[​](#type-parameters-18 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-33 "Direct link to Defined in")

[server/data\_model.ts:207](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L207)

***

### NamedSearchIndex[​](#namedsearchindex "Direct link to NamedSearchIndex")

Ƭ **NamedSearchIndex**<`TableInfo`, `IndexName`>: [`SearchIndexes`](/api/modules/server.md#searchindexes)<`TableInfo`>\[`IndexName`]

Extract the config of a search index from a [GenericTableInfo](/api/modules/server.md#generictableinfo) by name.

#### Type parameters[​](#type-parameters-19 "Direct link to Type parameters")

| Name        | Type                                                                               |
| ----------- | ---------------------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo)              |
| `IndexName` | extends [`SearchIndexNames`](/api/modules/server.md#searchindexnames)<`TableInfo`> |

#### Defined in[​](#defined-in-34 "Direct link to Defined in")

[server/data\_model.ts:214](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L214)

***

### VectorIndexes[​](#vectorindexes "Direct link to VectorIndexes")

Ƭ **VectorIndexes**<`TableInfo`>: `TableInfo`\[`"vectorIndexes"`]

The vector indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

This will be an object mapping index names to the vector index config.

#### Type parameters[​](#type-parameters-20 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-35 "Direct link to Defined in")

[server/data\_model.ts:225](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L225)

***

### VectorIndexNames[​](#vectorindexnames "Direct link to VectorIndexNames")

Ƭ **VectorIndexNames**<`TableInfo`>: keyof [`VectorIndexes`](/api/modules/server.md#vectorindexes)<`TableInfo`>

The names of vector indexes in a table for a given [GenericTableInfo](/api/modules/server.md#generictableinfo).

#### Type parameters[​](#type-parameters-21 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo) |

#### Defined in[​](#defined-in-36 "Direct link to Defined in")

[server/data\_model.ts:232](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L232)

***

### NamedVectorIndex[​](#namedvectorindex "Direct link to NamedVectorIndex")

Ƭ **NamedVectorIndex**<`TableInfo`, `IndexName`>: [`VectorIndexes`](/api/modules/server.md#vectorindexes)<`TableInfo`>\[`IndexName`]

Extract the config of a vector index from a [GenericTableInfo](/api/modules/server.md#generictableinfo) by name.

#### Type parameters[​](#type-parameters-22 "Direct link to Type parameters")

| Name        | Type                                                                               |
| ----------- | ---------------------------------------------------------------------------------- |
| `TableInfo` | extends [`GenericTableInfo`](/api/modules/server.md#generictableinfo)              |
| `IndexName` | extends [`VectorIndexNames`](/api/modules/server.md#vectorindexnames)<`TableInfo`> |

#### Defined in[​](#defined-in-37 "Direct link to Defined in")

[server/data\_model.ts:239](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L239)

***

### GenericDataModel[​](#genericdatamodel "Direct link to GenericDataModel")

Ƭ **GenericDataModel**: `Record`<`string`, [`GenericTableInfo`](/api/modules/server.md#generictableinfo)>

A type describing the tables in a Convex project.

This is designed to be code generated with `npx convex dev`.

#### Defined in[​](#defined-in-38 "Direct link to Defined in")

[server/data\_model.ts:252](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L252)

***

### AnyDataModel[​](#anydatamodel "Direct link to AnyDataModel")

Ƭ **AnyDataModel**: `Object`

A [GenericDataModel](/api/modules/server.md#genericdatamodel) that considers documents to be `any` and does not support indexes.

This is the default before a schema is defined.

#### Index signature[​](#index-signature "Direct link to Index signature")

▪ \[tableName: `string`]: { `document`: `any` ; `fieldPaths`: [`GenericFieldPaths`](/api/modules/server.md#genericfieldpaths) ; `indexes`: <!-- -->; `searchIndexes`: <!-- -->; `vectorIndexes`: <!-- -->}

#### Defined in[​](#defined-in-39 "Direct link to Defined in")

[server/data\_model.ts:261](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L261)

***

### TableNamesInDataModel[​](#tablenamesindatamodel "Direct link to TableNamesInDataModel")

Ƭ **TableNamesInDataModel**<`DataModel`>: keyof `DataModel` & `string`

A type of all of the table names defined in a [GenericDataModel](/api/modules/server.md#genericdatamodel).

#### Type parameters[​](#type-parameters-23 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

#### Defined in[​](#defined-in-40 "Direct link to Defined in")

[server/data\_model.ts:275](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L275)

***

### NamedTableInfo[​](#namedtableinfo "Direct link to NamedTableInfo")

Ƭ **NamedTableInfo**<`DataModel`, `TableName`>: `DataModel`\[`TableName`]

Extract the `TableInfo` for a table in a [GenericDataModel](/api/modules/server.md#genericdatamodel) by table name.

#### Type parameters[​](#type-parameters-24 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |
| `TableName` | extends keyof `DataModel`                                             |

#### Defined in[​](#defined-in-41 "Direct link to Defined in")

[server/data\_model.ts:284](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L284)

***

### DocumentByName[​](#documentbyname "Direct link to DocumentByName")

Ƭ **DocumentByName**<`DataModel`, `TableName`>: `DataModel`\[`TableName`]\[`"document"`]

The type of a document in a [GenericDataModel](/api/modules/server.md#genericdatamodel) by table name.

#### Type parameters[​](#type-parameters-25 "Direct link to Type parameters")

| Name        | Type                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)                        |
| `TableName` | extends [`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<`DataModel`> |

#### Defined in[​](#defined-in-42 "Direct link to Defined in")

[server/data\_model.ts:293](https://github.com/get-convex/convex-js/blob/main/src/server/data_model.ts#L293)

***

### ExpressionOrValue[​](#expressionorvalue "Direct link to ExpressionOrValue")

Ƭ **ExpressionOrValue**<`T`>: [`Expression`](/api/classes/server.Expression.md)<`T`> | `T`

An [Expression](/api/classes/server.Expression.md) or a constant [Value](/api/modules/values.md#value)

#### Type parameters[​](#type-parameters-26 "Direct link to Type parameters")

| Name | Type                                                           |
| ---- | -------------------------------------------------------------- |
| `T`  | extends [`Value`](/api/modules/values.md#value) \| `undefined` |

#### Defined in[​](#defined-in-43 "Direct link to Defined in")

[server/filter\_builder.ts:38](https://github.com/get-convex/convex-js/blob/main/src/server/filter_builder.ts#L38)

***

### Cursor[​](#cursor "Direct link to Cursor")

Ƭ **Cursor**: `string`

An opaque identifier used for paginating a database query.

Cursors are returned from [paginate](/api/interfaces/server.OrderedQuery.md#paginate) and represent the point of the query where the page of results ended.

To continue paginating, pass the cursor back into [paginate](/api/interfaces/server.OrderedQuery.md#paginate) in the [PaginationOptions](/api/interfaces/server.PaginationOptions.md) object to fetch another page of results.

Note: Cursors can only be passed to *exactly* the same database query that they were generated from. You may not reuse a cursor between different database queries.

#### Defined in[​](#defined-in-44 "Direct link to Defined in")

[server/pagination.ts:21](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L21)

***

### GenericMutationCtxWithTable[​](#genericmutationctxwithtable "Direct link to GenericMutationCtxWithTable")

Ƭ **GenericMutationCtxWithTable**<`DataModel`>: `Omit`<[`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`DataModel`>, `"db"`> & { `db`: [`GenericDatabaseWriterWithTable`](/api/interfaces/server.GenericDatabaseWriterWithTable.md)<`DataModel`> }

A set of services for use within Convex mutation functions.

The mutation context is passed as the first argument to any Convex mutation function run on the server.

If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-27 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

#### Defined in[​](#defined-in-45 "Direct link to Defined in")

[server/registration.ts:109](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L109)

***

### GenericQueryCtxWithTable[​](#genericqueryctxwithtable "Direct link to GenericQueryCtxWithTable")

Ƭ **GenericQueryCtxWithTable**<`DataModel`>: `Omit`<[`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`DataModel`>, `"db"`> & { `db`: [`GenericDatabaseReaderWithTable`](/api/interfaces/server.GenericDatabaseReaderWithTable.md)<`DataModel`> }

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.

This differs from the MutationCtx because all of the services are read-only.

#### Type parameters[​](#type-parameters-28 "Direct link to Type parameters")

| Name        | Type                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel) |

#### Defined in[​](#defined-in-46 "Direct link to Defined in")

[server/registration.ts:167](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L167)

***

### DefaultFunctionArgs[​](#defaultfunctionargs "Direct link to DefaultFunctionArgs")

Ƭ **DefaultFunctionArgs**: `Record`<`string`, `unknown`>

The default arguments type for a Convex query, mutation, or action function.

Convex functions always take an arguments object that maps the argument names to their values.

#### Defined in[​](#defined-in-47 "Direct link to Defined in")

[server/registration.ts:278](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L278)

***

### ArgsArray[​](#argsarray "Direct link to ArgsArray")

Ƭ **ArgsArray**: `OneArgArray` | `NoArgsArray`

An array of arguments to a Convex function.

Convex functions can take either a single [DefaultFunctionArgs](/api/modules/server.md#defaultfunctionargs) object or no args at all.

#### Defined in[​](#defined-in-48 "Direct link to Defined in")

[server/registration.ts:301](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L301)

***

### ArgsArrayToObject[​](#argsarraytoobject "Direct link to ArgsArrayToObject")

Ƭ **ArgsArrayToObject**<`Args`>: `Args` extends `OneArgArray`\<infer ArgsObject> ? `ArgsObject` : `EmptyObject`

Convert an [ArgsArray](/api/modules/server.md#argsarray) into a single object type.

Empty arguments arrays are converted to EmptyObject.

#### Type parameters[​](#type-parameters-29 "Direct link to Type parameters")

| Name   | Type                                                    |
| ------ | ------------------------------------------------------- |
| `Args` | extends [`ArgsArray`](/api/modules/server.md#argsarray) |

#### Defined in[​](#defined-in-49 "Direct link to Defined in")

[server/registration.ts:316](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L316)

***

### FunctionVisibility[​](#functionvisibility "Direct link to FunctionVisibility")

Ƭ **FunctionVisibility**: `"public"` | `"internal"`

A type representing the visibility of a Convex function.

#### Defined in[​](#defined-in-50 "Direct link to Defined in")

[server/registration.ts:324](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L324)

***

### RegisteredMutation[​](#registeredmutation "Direct link to RegisteredMutation")

Ƭ **RegisteredMutation**<`Visibility`, `Args`, `Returns`>: { `isConvexFunction`: `true` ; `isMutation`: `true` } & `VisibilityProperties`<`Visibility`>

A mutation function that is part of this app.

You can create a mutation by wrapping your function in [mutationGeneric](/api/modules/server.md#mutationgeneric) or [internalMutationGeneric](/api/modules/server.md#internalmutationgeneric) and exporting it.

#### Type parameters[​](#type-parameters-30 "Direct link to Type parameters")

| Name         | Type                                                                        |
| ------------ | --------------------------------------------------------------------------- |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility)   |
| `Args`       | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) |
| `Returns`    | `Returns`                                                                   |

#### Defined in[​](#defined-in-51 "Direct link to Defined in")

[server/registration.ts:347](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L347)

***

### RegisteredQuery[​](#registeredquery "Direct link to RegisteredQuery")

Ƭ **RegisteredQuery**<`Visibility`, `Args`, `Returns`>: { `isConvexFunction`: `true` ; `isQuery`: `true` } & `VisibilityProperties`<`Visibility`>

A query function that is part of this app.

You can create a query by wrapping your function in [queryGeneric](/api/modules/server.md#querygeneric) or [internalQueryGeneric](/api/modules/server.md#internalquerygeneric) and exporting it.

#### Type parameters[​](#type-parameters-31 "Direct link to Type parameters")

| Name         | Type                                                                        |
| ------------ | --------------------------------------------------------------------------- |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility)   |
| `Args`       | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) |
| `Returns`    | `Returns`                                                                   |

#### Defined in[​](#defined-in-52 "Direct link to Defined in")

[server/registration.ts:376](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L376)

***

### RegisteredAction[​](#registeredaction "Direct link to RegisteredAction")

Ƭ **RegisteredAction**<`Visibility`, `Args`, `Returns`>: { `isConvexFunction`: `true` ; `isAction`: `true` } & `VisibilityProperties`<`Visibility`>

An action that is part of this app.

You can create an action by wrapping your function in [actionGeneric](/api/modules/server.md#actiongeneric) or [internalActionGeneric](/api/modules/server.md#internalactiongeneric) and exporting it.

#### Type parameters[​](#type-parameters-32 "Direct link to Type parameters")

| Name         | Type                                                                        |
| ------------ | --------------------------------------------------------------------------- |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility)   |
| `Args`       | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) |
| `Returns`    | `Returns`                                                                   |

#### Defined in[​](#defined-in-53 "Direct link to Defined in")

[server/registration.ts:405](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L405)

***

### PublicHttpAction[​](#publichttpaction "Direct link to PublicHttpAction")

Ƭ **PublicHttpAction**: `Object`

An HTTP action that is part of this app's public API.

You can create public HTTP actions by wrapping your function in [httpActionGeneric](/api/modules/server.md#httpactiongeneric) and exporting it.

#### Type declaration[​](#type-declaration-6 "Direct link to Type declaration")

| Name     | Type   |
| -------- | ------ |
| `isHttp` | `true` |

#### Defined in[​](#defined-in-54 "Direct link to Defined in")

[server/registration.ts:434](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L434)

***

### UnvalidatedFunction[​](#unvalidatedfunction "Direct link to UnvalidatedFunction")

Ƭ **UnvalidatedFunction**<`Ctx`, `Args`, `Returns`>: (`ctx`: `Ctx`, ...`args`: `Args`) => `Returns` | { `handler`: (`ctx`: `Ctx`, ...`args`: `Args`) => `Returns` }

**`Deprecated`**

\-- See the type definition for `MutationBuilder` or similar for the types used for defining Convex functions.

The definition of a Convex query, mutation, or action function without argument validation.

Convex functions always take a context object as their first argument and an (optional) args object as their second argument.

This can be written as a function like:

```
import { query } from "./_generated/server";

export const func = query(({ db }, { arg }) => {...});
```

or as an object like:

```
import { query } from "./_generated/server";

export const func = query({
  handler: ({ db }, { arg }) => {...},
});
```

See [ValidatedFunction](/api/interfaces/server.ValidatedFunction.md) to add argument validation.

#### Type parameters[​](#type-parameters-33 "Direct link to Type parameters")

| Name      | Type                                                    |
| --------- | ------------------------------------------------------- |
| `Ctx`     | `Ctx`                                                   |
| `Args`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) |
| `Returns` | `Returns`                                               |

#### Defined in[​](#defined-in-55 "Direct link to Defined in")

[server/registration.ts:472](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L472)

***

### ReturnValueForOptionalValidator[​](#returnvalueforoptionalvalidator "Direct link to ReturnValueForOptionalValidator")

Ƭ **ReturnValueForOptionalValidator**<`ReturnsValidator`>: \[`ReturnsValidator`] extends \[[`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`>] ? `ValidatorTypeToReturnType`<[`Infer`](/api/modules/values.md#infer)<`ReturnsValidator`>> : \[`ReturnsValidator`] extends \[[`PropertyValidators`](/api/modules/values.md#propertyvalidators)] ? `ValidatorTypeToReturnType`<[`ObjectType`](/api/modules/values.md#objecttype)<`ReturnsValidator`>> : `any`

There are multiple syntaxes for defining a Convex function:

```
 - query(async (ctx, args) => {...})
 - query({ handler: async (ctx, args) => {...} })
 - query({ args: { a: v.string }, handler: async (ctx, args) => {...} } })
 - query({ args: { a: v.string }, returns: v.string(), handler: async (ctx, args) => {...} } })
```

In each of these, we want to correctly infer the type for the arguments and return value, preferring the type derived from a validator if it's provided.

To avoid having a separate overload for each, which would show up in error messages, we use the type params -- ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs.

The type for ReturnValue and OneOrZeroArgs are constrained by the type or ArgsValidator and ReturnsValidator if they're present, and inferred from any explicit type annotations to the arguments or return value of the function.

Below are a few utility types to get the appropriate type constraints based on an optional validator.

Additional tricks:

* We use Validator | void instead of Validator | undefined because the latter does not work with `strictNullChecks` since it's equivalent to just `Validator`.
* We use a tuple type of length 1 to avoid distribution over the union <https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532>

#### Type parameters[​](#type-parameters-34 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                        |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ReturnsValidator` | extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators) \| `void` |

#### Defined in[​](#defined-in-56 "Direct link to Defined in")

[server/registration.ts:574](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L574)

***

### ArgsArrayForOptionalValidator[​](#argsarrayforoptionalvalidator "Direct link to ArgsArrayForOptionalValidator")

Ƭ **ArgsArrayForOptionalValidator**<`ArgsValidator`>: \[`ArgsValidator`] extends \[[`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`>] ? `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> : \[`ArgsValidator`] extends \[[`PropertyValidators`](/api/modules/values.md#propertyvalidators)] ? `OneArgArray`<[`ObjectType`](/api/modules/values.md#objecttype)<`ArgsValidator`>> : [`ArgsArray`](/api/modules/server.md#argsarray)

#### Type parameters[​](#type-parameters-35 "Direct link to Type parameters")

| Name            | Type                                                                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ArgsValidator` | extends [`GenericValidator`](/api/modules/values.md#genericvalidator) \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators) \| `void` |

#### Defined in[​](#defined-in-57 "Direct link to Defined in")

[server/registration.ts:582](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L582)

***

### DefaultArgsForOptionalValidator[​](#defaultargsforoptionalvalidator "Direct link to DefaultArgsForOptionalValidator")

Ƭ **DefaultArgsForOptionalValidator**<`ArgsValidator`>: \[`ArgsValidator`] extends \[[`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`>] ? \[[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>] : \[`ArgsValidator`] extends \[[`PropertyValidators`](/api/modules/values.md#propertyvalidators)] ? \[[`ObjectType`](/api/modules/values.md#objecttype)<`ArgsValidator`>] : `OneArgArray`

#### Type parameters[​](#type-parameters-36 "Direct link to Type parameters")

| Name            | Type                                                                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ArgsValidator` | extends [`GenericValidator`](/api/modules/values.md#genericvalidator) \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators) \| `void` |

#### Defined in[​](#defined-in-58 "Direct link to Defined in")

[server/registration.ts:590](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L590)

***

### MutationBuilder[​](#mutationbuilder "Direct link to MutationBuilder")

Ƭ **MutationBuilder**<`DataModel`, `Visibility`>: \<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(`mutation`: { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } | (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue`) => [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Type parameters[​](#type-parameters-37 "Direct link to Type parameters")

| Name         | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `DataModel`  | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)     |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) |

#### Type declaration[​](#type-declaration-7 "Direct link to Type declaration")

▸ <`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`mutation`): [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Internal type helper used by Convex code generation.

Used to give [mutationGeneric](/api/modules/server.md#mutationgeneric) a type specific to your data model.

##### Type parameters[​](#type-parameters-38 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

##### Parameters[​](#parameters "Direct link to Parameters")

| Name       | Type                                                                                                                                                                                                                                                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mutation` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

##### Returns[​](#returns "Direct link to Returns")

[`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Defined in[​](#defined-in-59 "Direct link to Defined in")

[server/registration.ts:604](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L604)

***

### MutationBuilderWithTable[​](#mutationbuilderwithtable "Direct link to MutationBuilderWithTable")

Ƭ **MutationBuilderWithTable**<`DataModel`, `Visibility`>: \<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(`mutation`: { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtxWithTable`](/api/modules/server.md#genericmutationctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } | (`ctx`: [`GenericMutationCtxWithTable`](/api/modules/server.md#genericmutationctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue`) => [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Type parameters[​](#type-parameters-39 "Direct link to Type parameters")

| Name         | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `DataModel`  | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)     |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) |

#### Type declaration[​](#type-declaration-8 "Direct link to Type declaration")

▸ <`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`mutation`): [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Internal type helper used by Convex code generation.

Used to give [mutationGeneric](/api/modules/server.md#mutationgeneric) a type specific to your data model.

##### Type parameters[​](#type-parameters-40 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

##### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name       | Type                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mutation` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtxWithTable`](/api/modules/server.md#genericmutationctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericMutationCtxWithTable`](/api/modules/server.md#genericmutationctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

##### Returns[​](#returns-1 "Direct link to Returns")

[`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Defined in[​](#defined-in-60 "Direct link to Defined in")

[server/registration.ts:697](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L697)

***

### QueryBuilder[​](#querybuilder "Direct link to QueryBuilder")

Ƭ **QueryBuilder**<`DataModel`, `Visibility`>: \<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(`query`: { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } | (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue`) => [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Type parameters[​](#type-parameters-41 "Direct link to Type parameters")

| Name         | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `DataModel`  | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)     |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) |

#### Type declaration[​](#type-declaration-9 "Direct link to Type declaration")

▸ <`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`query`): [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Internal type helper used by Convex code generation.

Used to give [queryGeneric](/api/modules/server.md#querygeneric) a type specific to your data model.

##### Type parameters[​](#type-parameters-42 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

##### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type                                                                                                                                                                                                                                                                                                                                              |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

##### Returns[​](#returns-2 "Direct link to Returns")

[`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Defined in[​](#defined-in-61 "Direct link to Defined in")

[server/registration.ts:790](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L790)

***

### QueryBuilderWithTable[​](#querybuilderwithtable "Direct link to QueryBuilderWithTable")

Ƭ **QueryBuilderWithTable**<`DataModel`, `Visibility`>: \<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(`query`: { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtxWithTable`](/api/modules/server.md#genericqueryctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } | (`ctx`: [`GenericQueryCtxWithTable`](/api/modules/server.md#genericqueryctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue`) => [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Type parameters[​](#type-parameters-43 "Direct link to Type parameters")

| Name         | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `DataModel`  | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)     |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) |

#### Type declaration[​](#type-declaration-10 "Direct link to Type declaration")

▸ <`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`query`): [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Internal type helper used by Convex code generation.

Used to give [queryGeneric](/api/modules/server.md#querygeneric) a type specific to your data model.

##### Type parameters[​](#type-parameters-44 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

##### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name    | Type                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtxWithTable`](/api/modules/server.md#genericqueryctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericQueryCtxWithTable`](/api/modules/server.md#genericqueryctxwithtable)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

##### Returns[​](#returns-3 "Direct link to Returns")

[`RegisteredQuery`](/api/modules/server.md#registeredquery)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Defined in[​](#defined-in-62 "Direct link to Defined in")

[server/registration.ts:879](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L879)

***

### ActionBuilder[​](#actionbuilder "Direct link to ActionBuilder")

Ƭ **ActionBuilder**<`DataModel`, `Visibility`>: \<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(`func`: { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } | (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue`) => [`RegisteredAction`](/api/modules/server.md#registeredaction)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Type parameters[​](#type-parameters-45 "Direct link to Type parameters")

| Name         | Type                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `DataModel`  | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)     |
| `Visibility` | extends [`FunctionVisibility`](/api/modules/server.md#functionvisibility) |

#### Type declaration[​](#type-declaration-11 "Direct link to Type declaration")

▸ <`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`func`): [`RegisteredAction`](/api/modules/server.md#registeredaction)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Internal type helper used by Convex code generation.

Used to give [actionGeneric](/api/modules/server.md#actiongeneric) a type specific to your data model.

##### Type parameters[​](#type-parameters-46 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

##### Parameters[​](#parameters-4 "Direct link to Parameters")

| Name   | Type                                                                                                                                                                                                                                                                                                                                                  |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `func` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`DataModel`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

##### Returns[​](#returns-4 "Direct link to Returns")

[`RegisteredAction`](/api/modules/server.md#registeredaction)<`Visibility`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

#### Defined in[​](#defined-in-63 "Direct link to Defined in")

[server/registration.ts:968](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L968)

***

### HttpActionBuilder[​](#httpactionbuilder "Direct link to HttpActionBuilder")

Ƭ **HttpActionBuilder**: (`func`: (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, `request`: `Request`) => `Promise`<`Response`>) => [`PublicHttpAction`](/api/modules/server.md#publichttpaction)

#### Type declaration[​](#type-declaration-12 "Direct link to Type declaration")

▸ (`func`): [`PublicHttpAction`](/api/modules/server.md#publichttpaction)

Internal type helper used by Convex code generation.

Used to give [httpActionGeneric](/api/modules/server.md#httpactiongeneric) a type specific to your data model and functions.

##### Parameters[​](#parameters-5 "Direct link to Parameters")

| Name   | Type                                                                                                                            |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `func` | (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, `request`: `Request`) => `Promise`<`Response`> |

##### Returns[​](#returns-5 "Direct link to Returns")

[`PublicHttpAction`](/api/modules/server.md#publichttpaction)

#### Defined in[​](#defined-in-64 "Direct link to Defined in")

[server/registration.ts:1063](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L1063)

***

### RoutableMethod[​](#routablemethod "Direct link to RoutableMethod")

Ƭ **RoutableMethod**: typeof [`ROUTABLE_HTTP_METHODS`](/api/modules/server.md#routable_http_methods)\[`number`]

A type representing the methods supported by Convex HTTP actions.

HEAD is handled by Convex by running GET and stripping the body. CONNECT is not supported and will not be supported. TRACE is not supported and will not be supported.

#### Defined in[​](#defined-in-65 "Direct link to Defined in")

[server/router.ts:31](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L31)

***

### RouteSpecWithPath[​](#routespecwithpath "Direct link to RouteSpecWithPath")

Ƭ **RouteSpecWithPath**: `Object`

A type representing a route to an HTTP action using an exact request URL path match.

Used by [HttpRouter](/api/classes/server.HttpRouter.md) to route requests to HTTP actions.

#### Type declaration[​](#type-declaration-13 "Direct link to Type declaration")

| Name      | Type                                                          | Description                                |
| --------- | ------------------------------------------------------------- | ------------------------------------------ |
| `path`    | `string`                                                      | Exact HTTP request path to route.          |
| `method`  | [`RoutableMethod`](/api/modules/server.md#routablemethod)     | HTTP method ("GET", "POST", ...) to route. |
| `handler` | [`PublicHttpAction`](/api/modules/server.md#publichttpaction) | The HTTP action to execute.                |

#### Defined in[​](#defined-in-66 "Direct link to Defined in")

[server/router.ts:56](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L56)

***

### RouteSpecWithPathPrefix[​](#routespecwithpathprefix "Direct link to RouteSpecWithPathPrefix")

Ƭ **RouteSpecWithPathPrefix**: `Object`

A type representing a route to an HTTP action using a request URL path prefix match.

Used by [HttpRouter](/api/classes/server.HttpRouter.md) to route requests to HTTP actions.

#### Type declaration[​](#type-declaration-14 "Direct link to Type declaration")

| Name         | Type                                                          | Description                                                                                                            |
| ------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `pathPrefix` | `string`                                                      | An HTTP request path prefix to route. Requests with a path starting with this value will be routed to the HTTP action. |
| `method`     | [`RoutableMethod`](/api/modules/server.md#routablemethod)     | HTTP method ("GET", "POST", ...) to route.                                                                             |
| `handler`    | [`PublicHttpAction`](/api/modules/server.md#publichttpaction) | The HTTP action to execute.                                                                                            |

#### Defined in[​](#defined-in-67 "Direct link to Defined in")

[server/router.ts:78](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L78)

***

### RouteSpec[​](#routespec "Direct link to RouteSpec")

Ƭ **RouteSpec**: [`RouteSpecWithPath`](/api/modules/server.md#routespecwithpath) | [`RouteSpecWithPathPrefix`](/api/modules/server.md#routespecwithpathprefix)

A type representing a route to an HTTP action.

Used by [HttpRouter](/api/classes/server.HttpRouter.md) to route requests to HTTP actions.

#### Defined in[​](#defined-in-68 "Direct link to Defined in")

[server/router.ts:101](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L101)

***

### SchedulableFunctionReference[​](#schedulablefunctionreference "Direct link to SchedulableFunctionReference")

Ƭ **SchedulableFunctionReference**: [`FunctionReference`](/api/modules/server.md#functionreference)<`"mutation"` | `"action"`, `"public"` | `"internal"`>

A [FunctionReference](/api/modules/server.md#functionreference) that can be scheduled to run in the future.

Schedulable functions are mutations and actions that are public or internal.

#### Defined in[​](#defined-in-69 "Direct link to Defined in")

[server/scheduler.ts:11](https://github.com/get-convex/convex-js/blob/main/src/server/scheduler.ts#L11)

***

### GenericSchema[​](#genericschema "Direct link to GenericSchema")

Ƭ **GenericSchema**: `Record`<`string`, [`TableDefinition`](/api/classes/server.TableDefinition.md)>

A type describing the schema of a Convex project.

This should be constructed using [defineSchema](/api/modules/server.md#defineschema), [defineTable](/api/modules/server.md#definetable), and [v](/api/modules/values.md#v).

#### Defined in[​](#defined-in-70 "Direct link to Defined in")

[server/schema.ts:645](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L645)

***

### DataModelFromSchemaDefinition[​](#datamodelfromschemadefinition "Direct link to DataModelFromSchemaDefinition")

Ƭ **DataModelFromSchemaDefinition**<`SchemaDef`>: `MaybeMakeLooseDataModel`<{ \[TableName in keyof SchemaDef\["tables"] & string]: SchemaDef\["tables"]\[TableName] extends TableDefinition\<infer DocumentType, infer Indexes, infer SearchIndexes, infer VectorIndexes> ? Object : never }, `SchemaDef`\[`"strictTableNameTypes"`]>

Internal type used in Convex code generation!

Convert a [SchemaDefinition](/api/classes/server.SchemaDefinition.md) into a [GenericDataModel](/api/modules/server.md#genericdatamodel).

#### Type parameters[​](#type-parameters-47 "Direct link to Type parameters")

| Name        | Type                                                                                    |
| ----------- | --------------------------------------------------------------------------------------- |
| `SchemaDef` | extends [`SchemaDefinition`](/api/classes/server.SchemaDefinition.md)<`any`, `boolean`> |

#### Defined in[​](#defined-in-71 "Direct link to Defined in")

[server/schema.ts:786](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L786)

***

### SystemTableNames[​](#systemtablenames "Direct link to SystemTableNames")

Ƭ **SystemTableNames**: [`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<[`SystemDataModel`](/api/interfaces/server.SystemDataModel.md)>

#### Defined in[​](#defined-in-72 "Direct link to Defined in")

[server/schema.ts:844](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L844)

***

### StorageId[​](#storageid "Direct link to StorageId")

Ƭ **StorageId**: `string`

A reference to a file in storage.

This is used in the [StorageReader](/api/interfaces/server.StorageReader.md) and [StorageWriter](/api/interfaces/server.StorageWriter.md) which are accessible in Convex queries and mutations via QueryCtx and MutationCtx respectively.

#### Defined in[​](#defined-in-73 "Direct link to Defined in")

[server/storage.ts:11](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L11)

***

### FileStorageId[​](#filestorageid "Direct link to FileStorageId")

Ƭ **FileStorageId**: [`GenericId`](/api/modules/values.md#genericid)<`"_storage"`> | [`StorageId`](/api/modules/server.md#storageid)

#### Defined in[​](#defined-in-74 "Direct link to Defined in")

[server/storage.ts:12](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L12)

***

### FileMetadata[​](#filemetadata "Direct link to FileMetadata")

Ƭ **FileMetadata**: `Object`

Metadata for a single file as returned by [storage.getMetadata](/api/interfaces/server.StorageReader.md#getmetadata).

#### Type declaration[​](#type-declaration-15 "Direct link to Type declaration")

| Name          | Type                                            | Description                                                                                            |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `storageId`   | [`StorageId`](/api/modules/server.md#storageid) | ID for referencing the file (eg. via [storage.getUrl](/api/interfaces/server.StorageReader.md#geturl)) |
| `sha256`      | `string`                                        | Hex encoded sha256 checksum of file contents                                                           |
| `size`        | `number`                                        | Size of the file in bytes                                                                              |
| `contentType` | `string` \| `null`                              | ContentType of the file if it was provided on upload                                                   |

#### Defined in[​](#defined-in-75 "Direct link to Defined in")

[server/storage.ts:18](https://github.com/get-convex/convex-js/blob/main/src/server/storage.ts#L18)

***

### SystemFields[​](#systemfields "Direct link to SystemFields")

Ƭ **SystemFields**: `Object`

The fields that Convex automatically adds to documents, not including `_id`.

This is an object type mapping field name to field type.

#### Type declaration[​](#type-declaration-16 "Direct link to Type declaration")

| Name            | Type     |
| --------------- | -------- |
| `_creationTime` | `number` |

#### Defined in[​](#defined-in-76 "Direct link to Defined in")

[server/system\_fields.ts:11](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L11)

***

### IdField[​](#idfield "Direct link to IdField")

Ƭ **IdField**<`TableName`>: `Object`

The `_id` field that Convex automatically adds to documents.

#### Type parameters[​](#type-parameters-48 "Direct link to Type parameters")

| Name        | Type             |
| ----------- | ---------------- |
| `TableName` | extends `string` |

#### Type declaration[​](#type-declaration-17 "Direct link to Type declaration")

| Name  | Type                                                         |
| ----- | ------------------------------------------------------------ |
| `_id` | [`GenericId`](/api/modules/values.md#genericid)<`TableName`> |

#### Defined in[​](#defined-in-77 "Direct link to Defined in")

[server/system\_fields.ts:19](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L19)

***

### WithoutSystemFields[​](#withoutsystemfields "Direct link to WithoutSystemFields")

Ƭ **WithoutSystemFields**<`Document`>: [`Expand`](/api/modules/server.md#expand)<[`BetterOmit`](/api/modules/server.md#betteromit)<`Document`, keyof [`SystemFields`](/api/modules/server.md#systemfields) | `"_id"`>>

A Convex document with the system fields like `_id` and `_creationTime` omitted.

#### Type parameters[​](#type-parameters-49 "Direct link to Type parameters")

| Name       | Type                                                                |
| ---------- | ------------------------------------------------------------------- |
| `Document` | extends [`GenericDocument`](/api/modules/server.md#genericdocument) |

#### Defined in[​](#defined-in-78 "Direct link to Defined in")

[server/system\_fields.ts:28](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L28)

***

### WithOptionalSystemFields[​](#withoptionalsystemfields "Direct link to WithOptionalSystemFields")

Ƭ **WithOptionalSystemFields**<`Document`>: [`Expand`](/api/modules/server.md#expand)<[`WithoutSystemFields`](/api/modules/server.md#withoutsystemfields)<`Document`> & `Partial`<`Pick`<`Document`, keyof [`SystemFields`](/api/modules/server.md#systemfields) | `"_id"`>>>

A Convex document with the system fields like `_id` and `_creationTime` optional.

#### Type parameters[​](#type-parameters-50 "Direct link to Type parameters")

| Name       | Type                                                                |
| ---------- | ------------------------------------------------------------------- |
| `Document` | extends [`GenericDocument`](/api/modules/server.md#genericdocument) |

#### Defined in[​](#defined-in-79 "Direct link to Defined in")

[server/system\_fields.ts:37](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L37)

***

### SystemIndexes[​](#systemindexes "Direct link to SystemIndexes")

Ƭ **SystemIndexes**: `Object`

The indexes that Convex automatically adds to every table.

This is an object mapping index names to index field paths.

#### Type declaration[​](#type-declaration-18 "Direct link to Type declaration")

| Name               | Type                 |
| ------------------ | -------------------- |
| `by_id`            | \[`"_id"`]           |
| `by_creation_time` | \[`"_creationTime"`] |

#### Defined in[​](#defined-in-80 "Direct link to Defined in")

[server/system\_fields.ts:48](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L48)

***

### IndexTiebreakerField[​](#indextiebreakerfield "Direct link to IndexTiebreakerField")

Ƭ **IndexTiebreakerField**: `"_creationTime"`

Convex automatically appends "\_creationTime" to the end of every index to break ties if all of the other fields are identical.

#### Defined in[​](#defined-in-81 "Direct link to Defined in")

[server/system\_fields.ts:61](https://github.com/get-convex/convex-js/blob/main/src/server/system_fields.ts#L61)

***

### VectorSearch[​](#vectorsearch "Direct link to VectorSearch")

Ƭ **VectorSearch**<`DataModel`, `TableName`, `IndexName`>: (`tableName`: `TableName`, `indexName`: `IndexName`, `query`: [`VectorSearchQuery`](/api/interfaces/server.VectorSearchQuery.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>, `IndexName`>) => `Promise`<{ `_id`: [`GenericId`](/api/modules/values.md#genericid)<`TableName`> ; `_score`: `number` }\[]>

#### Type parameters[​](#type-parameters-51 "Direct link to Type parameters")

| Name        | Type                                                                                                                                                       |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataModel` | extends [`GenericDataModel`](/api/modules/server.md#genericdatamodel)                                                                                      |
| `TableName` | extends [`TableNamesInDataModel`](/api/modules/server.md#tablenamesindatamodel)<`DataModel`>                                                               |
| `IndexName` | extends [`VectorIndexNames`](/api/modules/server.md#vectorindexnames)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>> |

#### Type declaration[​](#type-declaration-19 "Direct link to Type declaration")

▸ (`tableName`, `indexName`, `query`): `Promise`<{ `_id`: [`GenericId`](/api/modules/values.md#genericid)<`TableName`> ; `_score`: `number` }\[]>

##### Parameters[​](#parameters-6 "Direct link to Parameters")

| Name        | Type                                                                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableName` | `TableName`                                                                                                                                                          |
| `indexName` | `IndexName`                                                                                                                                                          |
| `query`     | [`VectorSearchQuery`](/api/interfaces/server.VectorSearchQuery.md)<[`NamedTableInfo`](/api/modules/server.md#namedtableinfo)<`DataModel`, `TableName`>, `IndexName`> |

##### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<{ `_id`: [`GenericId`](/api/modules/values.md#genericid)<`TableName`> ; `_score`: `number` }\[]>

#### Defined in[​](#defined-in-82 "Direct link to Defined in")

[server/vector\_search.ts:55](https://github.com/get-convex/convex-js/blob/main/src/server/vector_search.ts#L55)

***

### Expand[​](#expand "Direct link to Expand")

Ƭ **Expand**<`ObjectType`>: `ObjectType` extends `Record`<`any`, `any`> ? { \[Key in keyof ObjectType]: ObjectType\[Key] } : `never`

Hack! This type causes TypeScript to simplify how it renders object types.

It is functionally the identity for object types, but in practice it can simplify expressions like `A & B`.

#### Type parameters[​](#type-parameters-52 "Direct link to Type parameters")

| Name         | Type                           |
| ------------ | ------------------------------ |
| `ObjectType` | extends `Record`<`any`, `any`> |

#### Defined in[​](#defined-in-83 "Direct link to Defined in")

[type\_utils.ts:12](https://github.com/get-convex/convex-js/blob/main/src/type_utils.ts#L12)

***

### BetterOmit[​](#betteromit "Direct link to BetterOmit")

Ƭ **BetterOmit**<`T`, `K`>: { \[Property in keyof T as Property extends K ? never : Property]: T\[Property] }

An `Omit<>` type that:

1. Applies to each element of a union.
2. Preserves the index signature of the underlying type.

#### Type parameters[​](#type-parameters-53 "Direct link to Type parameters")

| Name | Type              |
| ---- | ----------------- |
| `T`  | `T`               |
| `K`  | extends keyof `T` |

#### Defined in[​](#defined-in-84 "Direct link to Defined in")

[type\_utils.ts:24](https://github.com/get-convex/convex-js/blob/main/src/type_utils.ts#L24)

## Variables[​](#variables "Direct link to Variables")

### anyApi[​](#anyapi-1 "Direct link to anyApi")

• `Const` **anyApi**: [`AnyApi`](/api/modules/server.md#anyapi)

A utility for constructing [FunctionReference](/api/modules/server.md#functionreference)s in projects that are not using code generation.

You can create a reference to a function like:

```
const reference = anyApi.myModule.myFunction;
```

This supports accessing any path regardless of what directories and modules are in your project. All function references are typed as AnyFunctionReference.

If you're using code generation, use `api` from `convex/_generated/api` instead. It will be more type-safe and produce better auto-complete in your editor.

#### Defined in[​](#defined-in-85 "Direct link to Defined in")

[server/api.ts:427](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L427)

***

### paginationOptsValidator[​](#paginationoptsvalidator "Direct link to paginationOptsValidator")

• `Const` **paginationOptsValidator**: [`VObject`](/api/classes/values.VObject.md)<{ `id`: `undefined` | `number` ; `endCursor`: `undefined` | `null` | `string` ; `maximumRowsRead`: `undefined` | `number` ; `maximumBytesRead`: `undefined` | `number` ; `numItems`: `number` ; `cursor`: `null` | `string` }, { `numItems`: [`VFloat64`](/api/classes/values.VFloat64.md)<`number`, `"required"`> ; `cursor`: [`VUnion`](/api/classes/values.VUnion.md)<`null` | `string`, \[[`VString`](/api/classes/values.VString.md)<`string`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"required"`, `never`> ; `endCursor`: [`VUnion`](/api/classes/values.VUnion.md)<`undefined` | `null` | `string`, \[[`VString`](/api/classes/values.VString.md)<`string`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"optional"`, `never`> ; `id`: [`VFloat64`](/api/classes/values.VFloat64.md)<`undefined` | `number`, `"optional"`> ; `maximumRowsRead`: [`VFloat64`](/api/classes/values.VFloat64.md)<`undefined` | `number`, `"optional"`> ; `maximumBytesRead`: [`VFloat64`](/api/classes/values.VFloat64.md)<`undefined` | `number`, `"optional"`> }, `"required"`, `"id"` | `"numItems"` | `"cursor"` | `"endCursor"` | `"maximumRowsRead"` | `"maximumBytesRead"`>

A [Validator](/api/modules/values.md#validator) for [PaginationOptions](/api/interfaces/server.PaginationOptions.md).

This includes the standard [PaginationOptions](/api/interfaces/server.PaginationOptions.md) properties along with an optional cache-busting `id` property used by [usePaginatedQuery](/api/modules/react.md#usepaginatedquery).

#### Defined in[​](#defined-in-86 "Direct link to Defined in")

[server/pagination.ts:133](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L133)

***

### ROUTABLE\_HTTP\_METHODS[​](#routable_http_methods "Direct link to ROUTABLE_HTTP_METHODS")

• `Const` **ROUTABLE\_HTTP\_METHODS**: readonly \[`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"OPTIONS"`, `"PATCH"`]

A list of the methods supported by Convex HTTP actions.

HEAD is handled by Convex by running GET and stripping the body. CONNECT is not supported and will not be supported. TRACE is not supported and will not be supported.

#### Defined in[​](#defined-in-87 "Direct link to Defined in")

[server/router.ts:14](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L14)

## Functions[​](#functions "Direct link to Functions")

### getFunctionName[​](#getfunctionname "Direct link to getFunctionName")

▸ **getFunctionName**(`functionReference`): `string`

Get the name of a function from a [FunctionReference](/api/modules/server.md#functionreference).

The name is a string like "myDir/myModule<!-- -->:myFunction<!-- -->". If the exported name of the function is `"default"`, the function name is omitted (e.g. "myDir/myModule").

#### Parameters[​](#parameters-7 "Direct link to Parameters")

| Name                | Type                   | Description                                                                         |
| ------------------- | ---------------------- | ----------------------------------------------------------------------------------- |
| `functionReference` | `AnyFunctionReference` | A [FunctionReference](/api/modules/server.md#functionreference) to get the name of. |

#### Returns[​](#returns-7 "Direct link to Returns")

`string`

A string of the function's name.

#### Defined in[​](#defined-in-88 "Direct link to Defined in")

[server/api.ts:78](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L78)

***

### makeFunctionReference[​](#makefunctionreference "Direct link to makeFunctionReference")

▸ **makeFunctionReference**<`type`, `args`, `ret`>(`name`): [`FunctionReference`](/api/modules/server.md#functionreference)<`type`, `"public"`, `args`, `ret`>

FunctionReferences generally come from generated code, but in custom clients it may be useful to be able to build one manually.

Real function references are empty objects at runtime, but the same interface can be implemented with an object for tests and clients which don't use code generation.

#### Type parameters[​](#type-parameters-54 "Direct link to Type parameters")

| Name   | Type                                                                                |
| ------ | ----------------------------------------------------------------------------------- |
| `type` | extends [`FunctionType`](/api/modules/server.md#functiontype)                       |
| `args` | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) = `any` |
| `ret`  | `any`                                                                               |

#### Parameters[​](#parameters-8 "Direct link to Parameters")

| Name   | Type     | Description                                                      |
| ------ | -------- | ---------------------------------------------------------------- |
| `name` | `string` | The identifier of the function. E.g. `path/to/file:functionName` |

#### Returns[​](#returns-8 "Direct link to Returns")

[`FunctionReference`](/api/modules/server.md#functionreference)<`type`, `"public"`, `args`, `ret`>

#### Defined in[​](#defined-in-89 "Direct link to Defined in")

[server/api.ts:122](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L122)

***

### filterApi[​](#filterapi-1 "Direct link to filterApi")

▸ **filterApi**<`API`, `Predicate`>(`api`): [`FilterApi`](/api/modules/server.md#filterapi)<`API`, `Predicate`>

Given an api of type API and a FunctionReference subtype, return an api object containing only the function references that match.

```
const q = filterApi<typeof api, FunctionReference<"query">>(api)
```

#### Type parameters[​](#type-parameters-55 "Direct link to Type parameters")

| Name        |
| ----------- |
| `API`       |
| `Predicate` |

#### Parameters[​](#parameters-9 "Direct link to Parameters")

| Name  | Type  |
| ----- | ----- |
| `api` | `API` |

#### Returns[​](#returns-9 "Direct link to Returns")

[`FilterApi`](/api/modules/server.md#filterapi)<`API`, `Predicate`>

#### Defined in[​](#defined-in-90 "Direct link to Defined in")

[server/api.ts:301](https://github.com/get-convex/convex-js/blob/main/src/server/api.ts#L301)

***

### createFunctionHandle[​](#createfunctionhandle "Direct link to createFunctionHandle")

▸ **createFunctionHandle**<`Type`, `Args`, `ReturnType`>(`functionReference`): `Promise`<[`FunctionHandle`](/api/modules/server.md#functionhandle)<`Type`, `Args`, `ReturnType`>>

Create a serializable reference to a Convex function. Passing a this reference to another component allows that component to call this function during the current function execution or at any later time. Function handles are used like `api.folder.function` FunctionReferences, e.g. `ctx.scheduler.runAfter(0, functionReference, args)`.

A function reference is stable across code pushes but it's possible the Convex function it refers to might no longer exist.

This is a feature of components, which are in beta. This API is unstable and may change in subsequent releases.

#### Type parameters[​](#type-parameters-56 "Direct link to Type parameters")

| Name         | Type                                                                        |
| ------------ | --------------------------------------------------------------------------- |
| `Type`       | extends [`FunctionType`](/api/modules/server.md#functiontype)               |
| `Args`       | extends [`DefaultFunctionArgs`](/api/modules/server.md#defaultfunctionargs) |
| `ReturnType` | `ReturnType`                                                                |

#### Parameters[​](#parameters-10 "Direct link to Parameters")

| Name                | Type                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `functionReference` | [`FunctionReference`](/api/modules/server.md#functionreference)<`Type`, `"public"` \| `"internal"`, `Args`, `ReturnType`> |

#### Returns[​](#returns-10 "Direct link to Returns")

`Promise`<[`FunctionHandle`](/api/modules/server.md#functionhandle)<`Type`, `Args`, `ReturnType`>>

#### Defined in[​](#defined-in-91 "Direct link to Defined in")

[server/components/index.ts:54](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L54)

***

### defineComponent[​](#definecomponent "Direct link to defineComponent")

▸ **defineComponent**<`Exports`>(`name`): [`ComponentDefinition`](/api/modules/server.md#componentdefinition)<`Exports`>

Define a component, a piece of a Convex deployment with namespaced resources.

The default the default export of a module like "cool-component/convex.config.js" is a \`@link ComponentDefinition}, but during component definition evaluation this is its type instead.

@param name Name must be alphanumeric plus underscores. Typically these are lowercase with underscores like `"onboarding_flow_tracker"`.

This is a feature of components, which are in beta. This API is unstable and may change in subsequent releases.

#### Type parameters[​](#type-parameters-57 "Direct link to Type parameters")

| Name      | Type                               |
| --------- | ---------------------------------- |
| `Exports` | extends `ComponentExports` = `any` |

#### Parameters[​](#parameters-11 "Direct link to Parameters")

| Name   | Type     |
| ------ | -------- |
| `name` | `string` |

#### Returns[​](#returns-11 "Direct link to Returns")

[`ComponentDefinition`](/api/modules/server.md#componentdefinition)<`Exports`>

#### Defined in[​](#defined-in-92 "Direct link to Defined in")

[server/components/index.ts:371](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L371)

***

### defineApp[​](#defineapp "Direct link to defineApp")

▸ **defineApp**(): `AppDefinition`

Attach components, reuseable pieces of a Convex deployment, to this Convex app.

This is a feature of components, which are in beta. This API is unstable and may change in subsequent releases.

#### Returns[​](#returns-12 "Direct link to Returns")

`AppDefinition`

#### Defined in[​](#defined-in-93 "Direct link to Defined in")

[server/components/index.ts:397](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L397)

***

### componentsGeneric[​](#componentsgeneric "Direct link to componentsGeneric")

▸ **componentsGeneric**(): [`AnyChildComponents`](/api/modules/server.md#anychildcomponents)

#### Returns[​](#returns-13 "Direct link to Returns")

[`AnyChildComponents`](/api/modules/server.md#anychildcomponents)

#### Defined in[​](#defined-in-94 "Direct link to Defined in")

[server/components/index.ts:452](https://github.com/get-convex/convex-js/blob/main/src/server/components/index.ts#L452)

***

### getFunctionAddress[​](#getfunctionaddress "Direct link to getFunctionAddress")

▸ **getFunctionAddress**(`functionReference`): { `functionHandle`: `string` = functionReference; `name?`: `undefined` ; `reference?`: `undefined` = referencePath } | { `functionHandle?`: `undefined` = functionReference; `name`: `any` ; `reference?`: `undefined` = referencePath } | { `functionHandle?`: `undefined` = functionReference; `name?`: `undefined` ; `reference`: `string` = referencePath }

#### Parameters[​](#parameters-12 "Direct link to Parameters")

| Name                | Type  |
| ------------------- | ----- |
| `functionReference` | `any` |

#### Returns[​](#returns-14 "Direct link to Returns")

{ `functionHandle`: `string` = functionReference; `name?`: `undefined` ; `reference?`: `undefined` = referencePath } | { `functionHandle?`: `undefined` = functionReference; `name`: `any` ; `reference?`: `undefined` = referencePath } | { `functionHandle?`: `undefined` = functionReference; `name?`: `undefined` ; `reference`: `string` = referencePath }

#### Defined in[​](#defined-in-95 "Direct link to Defined in")

[server/components/paths.ts:20](https://github.com/get-convex/convex-js/blob/main/src/server/components/paths.ts#L20)

***

### cronJobs[​](#cronjobs "Direct link to cronJobs")

▸ **cronJobs**(): [`Crons`](/api/classes/server.Crons.md)

Create a CronJobs object to schedule recurring tasks.

```
// convex/crons.js
import { cronJobs } from 'convex/server';
import { api } from "./_generated/api";

const crons = cronJobs();
crons.weekly(
  "weekly re-engagement email",
  {
    hourUTC: 17, // (9:30am Pacific/10:30am Daylight Savings Pacific)
    minuteUTC: 30,
  },
  api.emails.send
)
export default crons;
```

#### Returns[​](#returns-15 "Direct link to Returns")

[`Crons`](/api/classes/server.Crons.md)

#### Defined in[​](#defined-in-96 "Direct link to Defined in")

[server/cron.ts:180](https://github.com/get-convex/convex-js/blob/main/src/server/cron.ts#L180)

***

### mutationGeneric[​](#mutationgeneric "Direct link to mutationGeneric")

▸ **mutationGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`mutation`): [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define a mutation in this Convex app's public API.

This function will be allowed to modify your Convex database and will be accessible from the client.

If you're using code generation, use the `mutation` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-58 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-13 "Direct link to Parameters")

| Name       | Type                                                                                                                                                                                                                                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mutation` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

#### Returns[​](#returns-16 "Direct link to Returns")

[`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped mutation. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-97 "Direct link to Defined in")

[server/registration.ts:608](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L608)

***

### internalMutationGeneric[​](#internalmutationgeneric "Direct link to internalMutationGeneric")

▸ **internalMutationGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`mutation`): [`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define a mutation that is only accessible from other Convex functions (but not from the client).

This function will be allowed to modify your Convex database. It will not be accessible from the client.

If you're using code generation, use the `internalMutation` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-59 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-14 "Direct link to Parameters")

| Name       | Type                                                                                                                                                                                                                                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mutation` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericMutationCtx`](/api/interfaces/server.GenericMutationCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

#### Returns[​](#returns-17 "Direct link to Returns")

[`RegisteredMutation`](/api/modules/server.md#registeredmutation)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped mutation. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-98 "Direct link to Defined in")

[server/registration.ts:608](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L608)

***

### queryGeneric[​](#querygeneric "Direct link to queryGeneric")

▸ **queryGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`query`): [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define a query in this Convex app's public API.

This function will be allowed to read your Convex database and will be accessible from the client.

If you're using code generation, use the `query` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-60 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-15 "Direct link to Parameters")

| Name    | Type                                                                                                                                                                                                                                                                                                                                  |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

#### Returns[​](#returns-18 "Direct link to Returns")

[`RegisteredQuery`](/api/modules/server.md#registeredquery)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped query. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-99 "Direct link to Defined in")

[server/registration.ts:794](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L794)

***

### internalQueryGeneric[​](#internalquerygeneric "Direct link to internalQueryGeneric")

▸ **internalQueryGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`query`): [`RegisteredQuery`](/api/modules/server.md#registeredquery)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define a query that is only accessible from other Convex functions (but not from the client).

This function will be allowed to read from your Convex database. It will not be accessible from the client.

If you're using code generation, use the `internalQuery` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-61 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-16 "Direct link to Parameters")

| Name    | Type                                                                                                                                                                                                                                                                                                                                  |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericQueryCtx`](/api/interfaces/server.GenericQueryCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` |

#### Returns[​](#returns-19 "Direct link to Returns")

[`RegisteredQuery`](/api/modules/server.md#registeredquery)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped query. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-100 "Direct link to Defined in")

[server/registration.ts:794](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L794)

***

### actionGeneric[​](#actiongeneric "Direct link to actionGeneric")

▸ **actionGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`func`): [`RegisteredAction`](/api/modules/server.md#registeredaction)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define an action in this Convex app's public API.

If you're using code generation, use the `action` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-62 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-17 "Direct link to Parameters")

| Name   | Type                                                                                                                                                                                                                                                                                                                                      | Description                                                                                                       |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `func` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` | The function. It receives a [GenericActionCtx](/api/interfaces/server.GenericActionCtx.md) as its first argument. |

#### Returns[​](#returns-20 "Direct link to Returns")

[`RegisteredAction`](/api/modules/server.md#registeredaction)<`"public"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped function. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-101 "Direct link to Defined in")

[server/registration.ts:972](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L972)

***

### internalActionGeneric[​](#internalactiongeneric "Direct link to internalActionGeneric")

▸ **internalActionGeneric**<`ArgsValidator`, `ReturnsValidator`, `ReturnValue`, `OneOrZeroArgs`>(`func`): [`RegisteredAction`](/api/modules/server.md#registeredaction)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

Define an action that is only accessible from other Convex functions (but not from the client).

If you're using code generation, use the `internalAction` function in `convex/_generated/server.d.ts` which is typed for your data model.

#### Type parameters[​](#type-parameters-63 "Direct link to Type parameters")

| Name               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ArgsValidator`    | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnsValidator` | extends `void` \| [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators)                                                                                                                                                                                                                                                                                                                                     |
| `ReturnValue`      | extends `any` = `any`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `OneOrZeroArgs`    | extends [`ArgsArray`](/api/modules/server.md#argsarray) \| `OneArgArray`<[`Infer`](/api/modules/values.md#infer)<`ArgsValidator`>> \| `OneArgArray`<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<ArgsValidator\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<ArgsValidator\[Property]> }>> = [`DefaultArgsForOptionalValidator`](/api/modules/server.md#defaultargsforoptionalvalidator)<`ArgsValidator`> |

#### Parameters[​](#parameters-18 "Direct link to Parameters")

| Name   | Type                                                                                                                                                                                                                                                                                                                                      | Description                                                                                                       |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `func` | { `args?`: `ArgsValidator` ; `returns?`: `ReturnsValidator` ; `handler`: (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` } \| (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<`any`>, ...`args`: `OneOrZeroArgs`) => `ReturnValue` | The function. It receives a [GenericActionCtx](/api/interfaces/server.GenericActionCtx.md) as its first argument. |

#### Returns[​](#returns-21 "Direct link to Returns")

[`RegisteredAction`](/api/modules/server.md#registeredaction)<`"internal"`, [`ArgsArrayToObject`](/api/modules/server.md#argsarraytoobject)<`OneOrZeroArgs`>, `ReturnValue`>

The wrapped function. Include this as an `export` to name it and make it accessible.

#### Defined in[​](#defined-in-102 "Direct link to Defined in")

[server/registration.ts:972](https://github.com/get-convex/convex-js/blob/main/src/server/registration.ts#L972)

***

### httpActionGeneric[​](#httpactiongeneric "Direct link to httpActionGeneric")

▸ **httpActionGeneric**(`func`): [`PublicHttpAction`](/api/modules/server.md#publichttpaction)

Define a Convex HTTP action.

#### Parameters[​](#parameters-19 "Direct link to Parameters")

| Name   | Type                                                                                                                                                                                    | Description                                                                                                                                              |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `func` | (`ctx`: [`GenericActionCtx`](/api/interfaces/server.GenericActionCtx.md)<[`GenericDataModel`](/api/modules/server.md#genericdatamodel)>, `request`: `Request`) => `Promise`<`Response`> | The function. It receives an [GenericActionCtx](/api/interfaces/server.GenericActionCtx.md) as its first argument, and a `Request` object as its second. |

#### Returns[​](#returns-22 "Direct link to Returns")

[`PublicHttpAction`](/api/modules/server.md#publichttpaction)

The wrapped function. Route a URL path to this function in `convex/http.js`.

#### Defined in[​](#defined-in-103 "Direct link to Defined in")

[server/impl/registration\_impl.ts:467](https://github.com/get-convex/convex-js/blob/main/src/server/impl/registration_impl.ts#L467)

***

### paginationResultValidator[​](#paginationresultvalidator "Direct link to paginationResultValidator")

▸ **paginationResultValidator**<`T`>(`itemValidator`): [`VObject`](/api/classes/values.VObject.md)<{ `splitCursor`: `undefined` | `null` | `string` ; `pageStatus`: `undefined` | `null` | `"SplitRecommended"` | `"SplitRequired"` ; `page`: `T`\[`"type"`]\[] ; `continueCursor`: `string` ; `isDone`: `boolean` }, { `page`: [`VArray`](/api/classes/values.VArray.md)<`T`\[`"type"`]\[], `T`, `"required"`> ; `continueCursor`: [`VString`](/api/classes/values.VString.md)<`string`, `"required"`> ; `isDone`: [`VBoolean`](/api/classes/values.VBoolean.md)<`boolean`, `"required"`> ; `splitCursor`: [`VUnion`](/api/classes/values.VUnion.md)<`undefined` | `null` | `string`, \[[`VString`](/api/classes/values.VString.md)<`string`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"optional"`, `never`> ; `pageStatus`: [`VUnion`](/api/classes/values.VUnion.md)<`undefined` | `null` | `"SplitRecommended"` | `"SplitRequired"`, \[[`VLiteral`](/api/classes/values.VLiteral.md)<`"SplitRecommended"`, `"required"`>, [`VLiteral`](/api/classes/values.VLiteral.md)<`"SplitRequired"`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"optional"`, `never`> }, `"required"`, `"page"` | `"continueCursor"` | `"isDone"` | `"splitCursor"` | `"pageStatus"`>

A [Validator](/api/modules/values.md#validator) factory for [PaginationResult](/api/interfaces/server.PaginationResult.md).

Create a validator for the result of calling [paginate](/api/interfaces/server.OrderedQuery.md#paginate) with a given item validator.

For example:

```
const paginationResultValidator = paginationResultValidator(v.object({
  _id: v.id("users"),
  _creationTime: v.number(),
  name: v.string(),
}));
```

#### Type parameters[​](#type-parameters-64 "Direct link to Type parameters")

| Name | Type                                                                                                                     |
| ---- | ------------------------------------------------------------------------------------------------------------------------ |
| `T`  | extends [`Validator`](/api/modules/values.md#validator)<[`Value`](/api/modules/values.md#value), `"required"`, `string`> |

#### Parameters[​](#parameters-20 "Direct link to Parameters")

| Name            | Type | Description                           |
| --------------- | ---- | ------------------------------------- |
| `itemValidator` | `T`  | A validator for the items in the page |

#### Returns[​](#returns-23 "Direct link to Returns")

[`VObject`](/api/classes/values.VObject.md)<{ `splitCursor`: `undefined` | `null` | `string` ; `pageStatus`: `undefined` | `null` | `"SplitRecommended"` | `"SplitRequired"` ; `page`: `T`\[`"type"`]\[] ; `continueCursor`: `string` ; `isDone`: `boolean` }, { `page`: [`VArray`](/api/classes/values.VArray.md)<`T`\[`"type"`]\[], `T`, `"required"`> ; `continueCursor`: [`VString`](/api/classes/values.VString.md)<`string`, `"required"`> ; `isDone`: [`VBoolean`](/api/classes/values.VBoolean.md)<`boolean`, `"required"`> ; `splitCursor`: [`VUnion`](/api/classes/values.VUnion.md)<`undefined` | `null` | `string`, \[[`VString`](/api/classes/values.VString.md)<`string`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"optional"`, `never`> ; `pageStatus`: [`VUnion`](/api/classes/values.VUnion.md)<`undefined` | `null` | `"SplitRecommended"` | `"SplitRequired"`, \[[`VLiteral`](/api/classes/values.VLiteral.md)<`"SplitRecommended"`, `"required"`>, [`VLiteral`](/api/classes/values.VLiteral.md)<`"SplitRequired"`, `"required"`>, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"optional"`, `never`> }, `"required"`, `"page"` | `"continueCursor"` | `"isDone"` | `"splitCursor"` | `"pageStatus"`>

A validator for the pagination result

#### Defined in[​](#defined-in-104 "Direct link to Defined in")

[server/pagination.ts:162](https://github.com/get-convex/convex-js/blob/main/src/server/pagination.ts#L162)

***

### httpRouter[​](#httprouter "Direct link to httpRouter")

▸ **httpRouter**(): [`HttpRouter`](/api/classes/server.HttpRouter.md)

Return a new [HttpRouter](/api/classes/server.HttpRouter.md) object.

#### Returns[​](#returns-24 "Direct link to Returns")

[`HttpRouter`](/api/classes/server.HttpRouter.md)

#### Defined in[​](#defined-in-105 "Direct link to Defined in")

[server/router.ts:47](https://github.com/get-convex/convex-js/blob/main/src/server/router.ts#L47)

***

### defineTable[​](#definetable "Direct link to defineTable")

▸ **defineTable**<`DocumentSchema`>(`documentSchema`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentSchema`>

Define a table in a schema.

You can either specify the schema of your documents as an object like

```
defineTable({
  field: v.string()
});
```

or as a schema type like

```
defineTable(
 v.union(
   v.object({...}),
   v.object({...})
 )
);
```

#### Type parameters[​](#type-parameters-65 "Direct link to Type parameters")

| Name             | Type                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `DocumentSchema` | extends [`Validator`](/api/modules/values.md#validator)<`Record`<`string`, `any`>, `"required"`, `any`> |

#### Parameters[​](#parameters-21 "Direct link to Parameters")

| Name             | Type             | Description                                 |
| ---------------- | ---------------- | ------------------------------------------- |
| `documentSchema` | `DocumentSchema` | The type of documents stored in this table. |

#### Returns[​](#returns-25 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<`DocumentSchema`>

A [TableDefinition](/api/classes/server.TableDefinition.md) for the table.

#### Defined in[​](#defined-in-106 "Direct link to Defined in")

[server/schema.ts:593](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L593)

▸ **defineTable**<`DocumentSchema`>(`documentSchema`): [`TableDefinition`](/api/classes/server.TableDefinition.md)<[`VObject`](/api/classes/values.VObject.md)<[`ObjectType`](/api/modules/values.md#objecttype)<`DocumentSchema`>, `DocumentSchema`>>

Define a table in a schema.

You can either specify the schema of your documents as an object like

```
defineTable({
  field: v.string()
});
```

or as a schema type like

```
defineTable(
 v.union(
   v.object({...}),
   v.object({...})
 )
);
```

#### Type parameters[​](#type-parameters-66 "Direct link to Type parameters")

| Name             | Type                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `DocumentSchema` | extends `Record`<`string`, [`GenericValidator`](/api/modules/values.md#genericvalidator)> |

#### Parameters[​](#parameters-22 "Direct link to Parameters")

| Name             | Type             | Description                                 |
| ---------------- | ---------------- | ------------------------------------------- |
| `documentSchema` | `DocumentSchema` | The type of documents stored in this table. |

#### Returns[​](#returns-26 "Direct link to Returns")

[`TableDefinition`](/api/classes/server.TableDefinition.md)<[`VObject`](/api/classes/values.VObject.md)<[`ObjectType`](/api/modules/values.md#objecttype)<`DocumentSchema`>, `DocumentSchema`>>

A [TableDefinition](/api/classes/server.TableDefinition.md) for the table.

#### Defined in[​](#defined-in-107 "Direct link to Defined in")

[server/schema.ts:621](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L621)

***

### defineSchema[​](#defineschema "Direct link to defineSchema")

▸ **defineSchema**<`Schema`, `StrictTableNameTypes`>(`schema`, `options?`): [`SchemaDefinition`](/api/classes/server.SchemaDefinition.md)<`Schema`, `StrictTableNameTypes`>

Define the schema of this Convex project.

This should be exported from a `schema.ts` file in your `convex/` directory like:

```
export default defineSchema({
  ...
});
```

#### Type parameters[​](#type-parameters-67 "Direct link to Type parameters")

| Name                   | Type                                                            |
| ---------------------- | --------------------------------------------------------------- |
| `Schema`               | extends [`GenericSchema`](/api/modules/server.md#genericschema) |
| `StrictTableNameTypes` | extends `boolean` = `true`                                      |

#### Parameters[​](#parameters-23 "Direct link to Parameters")

| Name       | Type                                                                                           | Description                                                                                                               |
| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `schema`   | `Schema`                                                                                       | A map from table name to [TableDefinition](/api/classes/server.TableDefinition.md) for all of the tables in this project. |
| `options?` | [`DefineSchemaOptions`](/api/interfaces/server.DefineSchemaOptions.md)<`StrictTableNameTypes`> | Optional configuration. See [DefineSchemaOptions](/api/interfaces/server.DefineSchemaOptions.md) for a full description.  |

#### Returns[​](#returns-27 "Direct link to Returns")

[`SchemaDefinition`](/api/classes/server.SchemaDefinition.md)<`Schema`, `StrictTableNameTypes`>

The schema.

#### Defined in[​](#defined-in-108 "Direct link to Defined in")

[server/schema.ts:769](https://github.com/get-convex/convex-js/blob/main/src/server/schema.ts#L769)

---

# Source: https://docs.convex.dev/production/state.md

# Status and Guarantees

Please [contact us](mailto:support@convex.dev) with any specific requirements or if you want to build a project on Convex that is not yet satisfied by our guarantees.

## Guarantees[​](#guarantees "Direct link to Guarantees")

The official Convex Terms of Service, Privacy Policy and Customer Agreements are [outlined in our official terms](https://www.convex.dev/legal/tos). We do not yet have contractual agreements beyond what is listed in our official terms and the discussions within this document don't constitute an amendment to these terms.

Convex is always under continual development and future releases may require code changes in order to upgrade to a new version. Code developed on Convex 1.0 or later will continue to operate as-is. If we are required to make a breaking change in future we will contact teams directly to provide substantial advance notice.

All user data in Convex is encrypted at rest. Database state is replicated durably across multiple physical availability zones. Regular periodic and incremental database backups are performed and stored with 99.999999999% (11 9's) durability.

We target an availability of 99.99% (4 9's) for Convex deployments although these may experience downtime for maintenance without notice. A physical outage may affect availability of a deployment but will not affect durability of the data stored in Convex.

## Limits[​](#limits "Direct link to Limits")

For information on limits, see [here](/production/state/limits.md).

## Beta Features[​](#beta-features "Direct link to Beta Features")

Features tagged with **beta** in these docs are still in development. They can be used in production but their APIs might change in the future, requiring additional effort when upgrading to a new version of the Convex NPM package and other Convex client libraries.

## Future Features[​](#future-features "Direct link to Future Features")

Convex is still under very active development and here we list some of the missing functionality on our radar. We'd love to hear more about your requirements in the [Convex Discord Community](https://convex.dev/community).

### Authorization[​](#authorization "Direct link to Authorization")

Convex currently has an [*authentication framework*](/auth.md) which verifies user identities. In the future we plan to add an *authorization framework* which will allow developers to define what data a user can access.

For now, you can implement manual authorization checks within your queries and mutations, but stay tuned for a more comprehensive, fool-proof solution in the future.

### Telemetry[​](#telemetry "Direct link to Telemetry")

Currently, the dashboard provides only basic metrics. Serious sites at scale are going to need to integrate our logs and metrics into more fully fledged observability systems that categorize them and empower things like alerting.

Convex will eventually have methods to publish deployment data in formats that can be ingested by third parties.

### Analytics / OLAP[​](#analytics--olap "Direct link to Analytics / OLAP")

Convex is designed to primarily service all your app's realtime implementation (OLTP) needs. It is less suited to be a good solution for the kinds of complex queries and huge table scans that are necessary to address the requirements of analytics (OLAP) use cases.

Convex exposes [Fivetran and Airbyte connectors](/production/integrations/streaming-import-export.md) to export Convex data to external analytics systems.

### Browser support[​](#browser-support "Direct link to Browser support")

Convex does not yet have an official browser support policy, but we strive to support most modern browsers with significant [usage](https://caniuse.com/usage-table).

---

# Source: https://docs.convex.dev/file-storage/store-files.md

# Storing Generated Files

Files can be uploaded to Convex from a client and stored directly, see [Upload](/file-storage/upload-files.md).

Alternatively files can also be stored after they've been fetched or generated in [actions](/functions/actions.md) and [HTTP actions](/functions/http-actions.md). For example you might call a third-party API to generate an image based on a user prompt and then store that image in Convex.

**Example:** [Dall-E Storage & Action](https://github.com/get-convex/convex-demos/tree/main/dall-e-storage-action)

## Storing files in actions[​](#storing-files-in-actions "Direct link to Storing files in actions")

Storing files in actions is similar to [uploading a file via an HTTP action](/file-storage/upload-files.md#uploading-files-via-an-http-action).

The action takes these steps:

1. Fetch or generate an image.
2. Store the image using [`storage.store()`](/api/interfaces/server.StorageActionWriter.md#store) and receive a storage ID.
3. Save the storage ID into your data model via a mutation.

Storage IDs correspond to documents in the `"_storage"` system table (see [Metadata](/file-storage/file-metadata.md)), so they can be validated using the `v.id("_storage")` validator and typed as `Id<"_storage">` in TypeScript.

convex/images.ts

TS

```
import { action, internalMutation, query } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
import { Id } from "./_generated/dataModel";

export const generateAndStore = action({
  args: { prompt: v.string() },
  handler: async (ctx, args) => {
    // Not shown: generate imageUrl from `prompt`
    const imageUrl = "https://....";

    // Download the image
    const response = await fetch(imageUrl);
    const image = await response.blob();

    // Store the image in Convex
    const storageId: Id<"_storage"> = await ctx.storage.store(image);

    // Write `storageId` to a document
    await ctx.runMutation(internal.images.storeResult, {
      storageId,
      prompt: args.prompt,
    });
  },
});

export const storeResult = internalMutation({
  args: {
    storageId: v.id("_storage"),
    prompt: v.string(),
  },
  handler: async (ctx, args) => {
    const { storageId, prompt } = args;
    await ctx.db.insert("images", { storageId, prompt });
  },
});
```

---

# Source: https://docs.convex.dev/streaming-export-api.md

# Streaming Export

Convex supports streaming export. Convex provides connector implementations for [Fivetran and Airbyte](/production/integrations/streaming-import-export.md). Those connectors use the following APIs.

Sign up for a [Professional plan](https://www.convex.dev/pricing) for streaming export support. You can also read the [documentation on streaming export](/production/integrations/streaming-import-export.md).

Streaming Export HTTP APIs are in beta

Streaming Export HTTP APIs<!-- --> <!-- -->are<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

Streaming export requests require deployment admin authorization via the HTTP header `Authorization`. The value is `Convex <access_key>` where the access key comes from "Deploy key" on the Convex dashboard and gives full read and write access to your Convex data.

### GET `/api/json_schemas`[​](#get-apijson_schemas "Direct link to get-apijson_schemas")

The JSON Schemas endpoint lists tables, and for each table describes how documents will be encoded, given as [JSON Schema](https://json-schema.org/). This endpoint returns `$description` tags throughout the schema to describe unintuitive encodings and give extra information like the table referenced by `Id` fields.

**Query parameters**

| Name        | Type    | Required | Description                                                                                                       |
| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| deltaSchema | boolean | n        | If set, include metadata fields returned by document\_deltas and list\_snapshot (`_ts`, `_deleted`, and `_table`) |
| format      | string  | n        | Output format for values. Valid values: \[`json`]                                                                 |

### GET `/api/list_snapshot`[​](#get-apilist_snapshot "Direct link to get-apilist_snapshot")

The `list_snapshot` endpoint walks a consistent snapshot of documents. It may take one or more calls to `list_snapshot` to walk a full snapshot.

**Query parameters**

| Name      | Type   | Required | Description                                                                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| snapshot  | int    | n        | Database timestamp at which to continue the snapshot. The timestamp must not be older than 30 days. If omitted, select the latest timestamp. |
| cursor    | string | n        | An opaque cursor representing the progress in paginating through the snapshot. If omitted, start from the first page of the snapshot.        |
| tableName | string | n        | If provided, filters the snapshot to a table. If omitted, provide snapshot across all tables.                                                |
| format    | string | n        | Output format for values. Valid values: \[`json`]                                                                                            |

**Result JSON**

| Field Name | Type               | Description                                                                                             |
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| values     | List\[ConvexValue] | List of convex values in the requested format. Each value includes extra fields `_ts` and `_table`.     |
| hasMore    | boolean            | True if there are more pages to the snapshot.                                                           |
| snapshot   | int                | A value that represents the database timestamp at which the snapshot was taken.                         |
| cursor     | string             | An opaque cursor representing the end of the progress on the given page. Pass this to subsequent calls. |

Expected API usage (pseudocode):

```
def list_full_snapshot()
    snapshot_values = []
    snapshot = None
    cursor = None
    while True:
        result = api.list_snapshot(cursor, snapshot)
        snapshot_values.extend(result.values)
        (cursor, snapshot) = (result.cursor, result.snapshot)
        if !result.hasMore:
            break
    return (snapshot_values, result.snapshot)
```

### GET `/api/document_deltas`[​](#get-apidocument_deltas "Direct link to get-apidocument_deltas")

The `document_deltas` endpoint walks the change log of documents to find new, updated, and deleted documents in the order of their mutations. This order is given by a `_ts` field on the returned documents. Deletions are represented as JSON objects with fields `_id`, `_ts`, and `_deleted: true`.

**Query parameters**

| Name      | Type   | Required | Description                                                                                                                               |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| cursor    | int    | y        | Database timestamp after which to continue streaming document deltas. Initial value is the `snapshot` field returned from list\_snapshot. |
| tableName | string | n        | If provided, filters the document deltas to a table. If omitted, provide deltas across all tables.                                        |
| format    | string | n        | Output format for values. Valid values: \[`json`]                                                                                         |

**Result JSON**

| Field Name | Type               | Description                                                                                                                                    |
| ---------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| values     | List\[ConvexValue] | List of convex values in the requested format. Each value includes extra fields for `_ts`, and `_table`. Deletions include a field `_deleted`. |
| hasMore    | boolean            | True if there are more pages to the snapshot.                                                                                                  |
| cursor     | int                | A value that represents the database timestamp at the end of the page. Pass to subsequent calls to document\_deltas.                           |

Expected API usage (pseudocode):

```
def delta_sync(delta_cursor):
    delta_values = []
    while True:
        result = api.document_deltas(cursor)
        delta_values.extend(result.values)
        cursor = result.cursor
        if !hasMore:
            break
    return (delta_values, delta_cursor)

(snapshot_values, delta_cursor) = list_full_snapshot()
(delta_values, delta_cursor) = delta_sync(delta_cursor)
# Save delta_cursor for the next sync
```

---

# Source: https://docs.convex.dev/streaming-import-api.md

# Streaming Import

Convex supports streaming import. Convex provides a connector implementation for [Airbyte](/production/integrations/streaming-import-export.md). Those connectors use the following APIs.

Streaming import support is automatically enabled for all Convex projects.

Streaming import requests require deployment admin authorization via the HTTP header `Authorization`. The value is `Convex <access_key>` where the access key comes from "Deploy key" on the Convex dashboard and gives full read and write access to your Convex data.

### Headers[​](#headers "Direct link to Headers")

Streaming import endpoints accept a `Convex-Client: streaming-import-<version>` header, where the version follows [Semver](https://semver.org/) guidelines. If this header is not specified, Convex will default to the latest version. We recommend using the header to ensure the consumer of this API does not break as the API changes.

### GET `/api/streaming_import/primary_key_indexes_ready`[​](#get-apistreaming_importprimary_key_indexes_ready "Direct link to get-apistreaming_importprimary_key_indexes_ready")

The `primary_key_indexes_ready` endpoint takes a list of table names and returns true if the primary key indexes (created by `add_primary_key_indexes`) on all those tables are ready. If the tables are newly created, the indexes should be ready immediately; however if there are existing documents in the tables, it may take some time to backfill the primary key indexes. The response looks like:

```
{
  "indexesReady": true
}
```

### PUT `/api/streaming_import/add_primary_key_indexes`[​](#put-apistreaming_importadd_primary_key_indexes "Direct link to put-apistreaming_importadd_primary_key_indexes")

The `add_primary_key_indexes` endpoint takes a JSON body containing the primary keys for tables and creates indexes on the primary keys to be backfilled. Note that they are not immediately ready to query - the `primary_key_indexes_ready` endpoint needs to be polled until it returns True before calling `import_airbyte_records` with records that require primary key indexes. Also note that Convex queries will not have access to these added indexes. These are solely for use in `import_airbyte_records`. The body takes the form of a map of index names to list of field paths to index. Each field path is represented by a list of fields that can represent nested field paths.

```
{
  "indexes": {
    "<table_name>": [["<field1>"], ["<field2>", "<nested_field>"]]
  }
}
```

Expected API Usage:

1. Add indexes for primary keys by making a request to `add_primary_key_indexes`.
2. Poll `primary_key_indexes_ready` until the response is true.
3. Query using the added indexes.

### PUT `api/streaming_import/clear_tables`[​](#put-apistreaming_importclear_tables "Direct link to put-apistreaming_importclear_tables")

The `clear_tables` endpoint deletes all documents from the specified tables. Note that this may require multiple transactions. If there is an intermediate error only some documents may be deleted. The JSON body to use this API request contains a list of table names:

```
{
  "tableNames": ["<table_1>", "<table_2>"]
}
```

### POST `api/streaming_import/replace_tables`[​](#post-apistreaming_importreplace_tables "Direct link to post-apistreaming_importreplace_tables")

This endpoint is no longer supported. Use `api/streaming_import/clear_tables` instead.

The `replace_tables` endpoint renames tables with temporary names to their final names, deleting any existing tables with the final names.

The JSON body to use this API request contains a list of table names:

```
{
  "tableNames": { "<table_1_temp>": "<table_1>", "<table_2_temp>": "<table_2>" }
}
```

### POST `api/streaming_import/import_airbyte_records`[​](#post-apistreaming_importimport_airbyte_records "Direct link to post-apistreaming_importimport_airbyte_records")

The `import_airbyte_records` endpoint enables streaming ingress into a Convex deployment and is designed to be called from an Airbyte destination connector.

It takes a map of streams and a list of messages in the JSON body. Each stream has a name and JSON schema that will correspond to a Convex table. Streams where records should be deduplicated include a primary key as well, which is represented as a list of lists of strings that are field paths. Records for streams without a primary key are appended to tables; records for streams with a primary key replace an existing record where the primary key value matches or are appended if there is no match. If you are using primary keys, you must call the `add_primary_key_indexes` endpoint first and wait for them to backfill by polling `primary_key_indexes_ready`.

Each message contains a stream name and a JSON document that will be inserted (or replaced, in the case of deduplicated sync) into the table with the corresponding stream name. Table names are same as the stream names. Airbyte records become Convex documents.

```
{
   "tables": {
      "<stream_name>": {
         "primaryKey": [["<field1>"], ["<field2>", "<nested_field>"]],
         "jsonSchema": // see https://json-schema.org/ for examples
      }
   },
   "messages": [{
      "tableName": "<table_name>",
      "data": {} // JSON object conforming to the `json_schema` for that stream
   }]
}
```

Similar to `clear_tables`, it is possible to execute a partial import using `import_airbyte_records` if there is a failure after a transaction has committed.

Expected API Usage:

1. \[Optional] Add any indexes if using primary keys and [deduplicated sync](https://docs.airbyte.com/understanding-airbyte/connections/incremental-deduped-history/) (see `add_primary_key_indexes` above).
2. \[Optional] Delete all documents in specified tables using `clear_tables` if using [overwrite sync](https://docs.airbyte.com/understanding-airbyte/connections/full-refresh-overwrite).
3. Make a request to `import_airbyte_records` with new records to sync and stream information.

---

# Source: https://docs.convex.dev/production/integrations/streaming-import-export.md

# Streaming Data in and out of Convex

[Fivetran](https://www.fivetran.com) and [Airbyte](https://airbyte.com) are data integration platforms that allow you to sync your Convex data with other databases.

Fivetran enables streaming export from Convex to any of their [supported destinations](https://fivetran.com/docs/destinations). The Convex team maintains a Convex source connector, for streaming export. Streaming import into Convex via Fivetran is not supported at the moment.

Using Airbyte enables streaming import from any of their [supported sources](https://airbyte.com/connectors?connector-type=Sources) into Convex and streaming export from Convex into any of their [supported destinations](https://airbyte.com/connectors?connector-type=Destinations). The Convex team maintains a Convex source connector for streaming export and a Convex destination connector for streaming import.

Fivetran & Airbyte integrations are in beta

Fivetran & Airbyte integrations<!-- --> <!-- -->are<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

## Streaming Export[​](#streaming-export "Direct link to Streaming Export")

Exporting data can be useful for handling workloads that aren't supported by Convex directly. Some use cases include:

1. Analytics
   <!-- -->
   * Convex isn't optimized for queries that load huge amounts of data. A data platform like [Databricks](https://www.databricks.com) or [Snowflake](https://www.snowflake.com/) is more appropriate.
2. Flexible querying
   <!-- -->
   * While Convex has powerful [database queries](/database/reading-data/.md#querying-documents) and built-in [full text search](/search.md) support, there are still some queries that are difficult to write within Convex. If you need very dynamic sorting and filtering for something like an "advanced search" view, databases like [ElasticSearch](https://www.elastic.co) can be helpful.
3. Machine learning training
   <!-- -->
   * Convex isn't optimized for queries running computationally intensive machine learning algorithms.

Streaming export requires a Convex Pro plan.

Streaming export<!-- --> <!-- -->requires<!-- --> a Convex Pro plan. [Learn more](https://convex.dev/pricing) about our plans or [upgrade](https://dashboard.convex.dev/team/settings/billing).

See the [Fivetran](https://fivetran.com/integrations/convex) or [Airbyte](https://docs.airbyte.com/integrations/sources/convex) docs to learn how to set up a streaming export. [Contact us](https://convex.dev/community) if you need help or have questions.

## Streaming Import[​](#streaming-import "Direct link to Streaming Import")

Adopting new technologies can be a slow, daunting process, especially when the technologies involve databases. Streaming import enables adopting Convex alongside your existing stack without having to write your own migration or data sync tooling. Some use cases include:

1. Prototyping how Convex could replace your project's existing backend using its own data.
2. Building new products faster by using Convex alongside existing databases.
3. Developing a reactive UI-layer on top of an existing dataset.
4. Migrating your data to Convex (if the [CLI](/cli.md) tool doesn't meet your needs).

Make imported tables read-only

A common use case is to "mirror" a table in the source database to Convex to build something new using Convex. We recommend leaving imported tables as read-only in Convex because syncing the results back to the source database could result in dangerous write conflicts. While Convex doesn't yet have access controls that would ensure a table is read-only, you can make sure that there are no mutations or actions writing to imported tables in your code and avoid editing documents in imported tables in the dashboard.

Streaming import is included with all Convex plans. See the Airbyte docs on how to set up the Convex destination connector [here](https://docs.airbyte.com/integrations/destinations/convex).

---

# Source: https://docs.convex.dev/agents/streaming.md

# Streaming

Streaming messages is a great way to give a user feedback and keep an application feeling responsive while using LLMs.

Traditionally streaming happens via HTTP streaming, where the client sends a request and waits until the full response is streamed back. This works out of the box when using the Agent, in the same way you would with the AI SDK. See [below](#consuming-the-stream-yourself-with-the-agent) if that is all you're looking for.

However, with the Agent component you can also stream messages asynchronously, meaning the generation doesn't have to happen in an HTTP handler (`httpAction`), and the response can be streamed back to one or more clients even if their network connection is interrupted.

It works by saving the streaming parts to the database in groups (deltas), and the clients subscribe to new deltas for the given thread, as they're generated. As a bonus, you don't even need to use the Agent's version of `streamText` to use the delta streaming approach (see [below](#advanced-streaming-deltas-asynchronously-without-using-an-agent)).

Example:

* Server: [streaming.ts](https://github.com/get-convex/agent/blob/main/example/convex/chat/streaming.ts)
* Client: [ChatStreaming.tsx](https://github.com/get-convex/agent/blob/main/example/ui/chat/ChatStreaming.tsx)

## Streaming message deltas[​](#streaming-message-deltas "Direct link to Streaming message deltas")

The easiest way to stream is to pass `{ saveStreamDeltas: true }` to `agent.streamText`. This will save chunks of the response as deltas as they're generated, so all clients can subscribe to the stream and get live-updating text via normal Convex queries.

```
agent.streamText(ctx, { threadId }, { prompt }, { saveStreamDeltas: true });
```

This can be done in an async function, where http streaming to a client is not possible. Under the hood it will chunk up the response and debounce saving the deltas to prevent excessive bandwidth usage. You can pass more options to `saveStreamDeltas` to configure the chunking and debouncing.

```
  { saveStreamDeltas: { chunking: "line", throttleMs: 1000 } },
```

* `chunking` can be "word", "line", a regex, or a custom function.
* `throttleMs` is how frequently the deltas are saved. This will send multiple chunks per delta, writes sequentially, and will not write faster than the throttleMs ([single-flighted](https://stack.convex.dev/throttling-requests-by-single-flighting) ).

## Retrieving streamed deltas[​](#retrieving-streamed-deltas "Direct link to Retrieving streamed deltas")

For clients to stream messages, you need to expose a query that returns the stream deltas. This is very similar to [retrieving messages](/agents/messages.md#retrieving-messages), with a few changes:

```
import { paginationOptsValidator } from "convex/server";
import { vStreamArgs, listUIMessages, syncStreams } from "@convex-dev/agent";
import { components } from "./_generated/api";

export const listThreadMessages = query({
  args: {
    threadId: v.string(),
    // Pagination options for the non-streaming messages.
    paginationOpts: paginationOptsValidator,
    streamArgs: vStreamArgs,
  },
  handler: async (ctx, args) => {
    await authorizeThreadAccess(ctx, threadId);

    // Fetches the regular non-streaming messages.
    const paginated = await listUIMessages(ctx, components.agent, args);

    const streams = await syncStreams(ctx, components.agent, args);

    return { ...paginated, streams };
  },
});
```

Similar to with [non-streaming messages](/agents/messages.md#useuimessages-hook), you can use the `useUIMessages` hook to fetch the messages, passing in `stream: true` to enable streaming.

```
const { results, status, loadMore } = useUIMessages(
  api.chat.streaming.listMessages,
  { threadId },
  { initialNumItems: 10, stream: true },
);
```

### Text smoothing with `SmoothText` and `useSmoothText`[​](#text-smoothing-with-smoothtext-and-usesmoothtext "Direct link to text-smoothing-with-smoothtext-and-usesmoothtext")

The `useSmoothText` hook is a simple hook that smooths the text as it changes. It can work with any text, but is especially handy for streaming text.

```
import { useSmoothText } from "@convex-dev/agent/react";

// in the component
const [visibleText] = useSmoothText(message.text);
```

You can configure the initial characters per second. It will adapt over time to match the average speed of the text coming in.

By default it won't stream the first text it receives unless you pass in `startStreaming: true`. To start streaming immediately when you have a mix of streaming and non-streaming messages, do:

```
import { useSmoothText, type UIMessage } from "@convex-dev/agent/react";

function Message({ message }: { message: UIMessage }) {
  const [visibleText] = useSmoothText(message.text, {
    startStreaming: message.status === "streaming",
  });
  return <div>{visibleText}</div>;
}
```

If you don't want to use the hook, you can use the `SmoothText` component.

```
import { SmoothText } from "@convex-dev/agent/react";

//...
<SmoothText text={message.text} />;
```

## Consuming the stream yourself with the Agent[​](#consuming-the-stream-yourself-with-the-agent "Direct link to Consuming the stream yourself with the Agent")

You can consume the stream in all the ways you can with the underlying AI SDK - for instance iterating over the content, or using [`result.toDataStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#to-data-stream-response).

If you are not also saving the deltas, it might look like this:

```
const result = await agent.streamText(ctx, { threadId }, { prompt });

for await (const textPart of result.textStream) {
  console.log(textPart);
}
```

If you want to both iterate as the stream is happening, as well as save the deltas, you can pass `{ saveStreamDeltas: { returnImmediately: true } }` to `streamText`. This will return immediately, and you can then iterate over the stream live, or return the stream in an HTTP Response.

```
const result = await agent.streamText(
  ctx,
  { threadId },
  { prompt },
  { saveStreamDeltas: { returnImmediately: true } },
);

return result.toUIMessageStreamResponse();
```

If you don't want to have the Agent involved at all, the next section will show you how to save the deltas yourself.

## Advanced: Streaming deltas asynchronously without using an Agent[​](#advanced-streaming-deltas-asynchronously-without-using-an-agent "Direct link to Advanced: Streaming deltas asynchronously without using an Agent")

To stream messages without using the Agent's wrapper of `streamText`, you can use the `streamText` function from the AI SDK directly.

It consists of using the `DeltaStreamer` class to save the deltas to the database, and then using the above approach to retrieve the messages, though you can use a more direct `useStreamingUIMessages` hook that doesn't involve reading any non-streaming messages from the database.

The requirements for reading and writing the streams are just that they use a `threadId` from the Agent component, and that each stream is saved with a distinct `order`, for ordering on the client side.

```
import { components } from "./_generated/api";
import { type ActionCtx } from "./_generated/server";
import { DeltaStreamer, compressUIMessageChunks } from "@convex-dev/agent";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

async function stream(ctx: ActionCtx, threadId: string, order: number) {
  const streamer = new DeltaStreamer(
    components.agent,
    ctx,
    {
      throttleMs: 100,
      onAsyncAbort: async () => console.error("Aborted asynchronously"),
      // This will collapse multiple tiny deltas into one if they're being sent
      // in quick succession.
      compress: compressUIMessageChunks,
      abortSignal: undefined,
    },
    {
      threadId,
      format: "UIMessageChunk",
      order,
      stepOrder: 0,
      userId: undefined,
    },
  );
  // Do the normal streaming with the AI SDK
  const response = streamText({
    model: openai.chat("gpt-4o-mini"),
    prompt: "Tell me a joke",
    abortSignal: streamer.abortController.signal,
    onError: (error) => {
      console.error(error);
      streamer.fail(errorToString(error.error));
    },
  });

  // We could await here if we wanted to wait for the stream to finish,
  // but instead we have it process asynchronously so we can return a streaming
  // http Response.
  void streamer.consumeStream(response.toUIMessageStream());

  return {
    // e.g. to do `response.toTextStreamResponse()` for HTTP streaming.
    response,
    // We don't need this on the client, but with it we can have some clients
    // selectively not stream down deltas when they're using HTTP streaming
    // already.
    streamId: await streamer.getStreamId(),
  };
}
```

To fetch the deltas for the client, you can use the `syncStreams` function, as you would with normal Agent streaming. If you don't want to fetch the non-streaming messages, it can be simplified to:

```
import { v } from "convex/values";
import { vStreamArgs, syncStreams } from "@convex-dev/agent";
import { query } from "./_generated/server";
import { components } from "./_generated/api";

export const listStreams = query({
  args: {
    threadId: v.string(),
    streamArgs: vStreamArgs,
  },
  handler: async (ctx, args) => {
    // await authorizeThreadAccess(ctx, args.threadId);
    const streams = await syncStreams(ctx, components.agent, {
      ...args,
      // By default syncStreams only returns streaming messages. However, if
      // your messages aren't saved in the same transaction as the streaming
      // ends, you might want to include them here to avoid UI flashes.
      includeStatuses: ["streaming", "aborted", "finished"],
    });
    return { streams };
  },
});
```

On the client side, you can use the `useStreamingUIMessages` hook to fetch the messages. If you defined more arguments than just `threadId`, they'll get passed along with `threadId` here.

```
const messages = useStreamingUIMessages(api.example.listStreams, { threadId });
```

You can pass in another parameter to either skip certain `streamId`s or to start at some `order` to ignore previous streams.

---

# Source: https://docs.convex.dev/client/svelte.md

# Source: https://docs.convex.dev/quickstart/svelte.md

# Svelte Quickstart

Learn how to query data from Convex in a Svelte app.

1. Create a SvelteKit app

   Create a SvelteKit app using the `npx sv create` command.

   Other sets of options will work with the library but for this quickstart guide:

   * For "Which Svelte app template," choose **"SvelteKit minimal."**
   * For a package manager, choose **"npm."**
   * For "Add type checking with TypeScript," choose **"Yes, using TypeScript syntax."**
   * For "Select additional options," you don't need to enable anything.

   <br />

   ```
   npx sv@latest create my-app
   ```

2. Install the Convex client and server library

   To get started, install the `convex` and `convex-svelte` packages.

   ```
   cd my-app && npm install convex convex-svelte
   ```

3. Customize the convex path

   SvelteKit doesn't like referencing code outside of source, so customize the convex functionsDir to be under `src/`.

   convex.json

   ```
   {
   	"functions": "src/convex/"
   }
   ```

4. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `src/convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

5. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

6. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

7. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   src/convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       const tasks = await ctx.db.query("tasks").collect();
       return tasks.map((task) => ({ ...task, assigner: "tom" }));
     },
   });
   ```

8. Set up Convex

   Create a new file `src/routes/+layout.svelte` and set up the Convex client there to make it available on every page of your app.

   src/routes/+layout.svelte

   ```
   <script lang="ts">
   	import { PUBLIC_CONVEX_URL } from '$env/static/public';
   	import { setupConvex } from 'convex-svelte';

   	const { children } = $props();
   	setupConvex(PUBLIC_CONVEX_URL);
   </script>

   {@render children()}
   ```

9. Display the data in your app

   In `src/routes/+page.svelte` use `useQuery` to subscribe your `api.tasks.get` API function.

   src/routes/+page.svelte

   ```
   <script lang="ts">
   	import { useQuery } from 'convex-svelte';
   	import { api } from '../convex/_generated/api.js';

   	const query = useQuery(api.tasks.get, {});
   </script>

   {#if query.isLoading}
   	Loading...
   {:else if query.error}
   	failed to load: {query.error.toString()}
   {:else}
   	<ul>
   		{#each query.data as task}
   			<li>
   				{task.isCompleted ? '☑' : '☐'}
   				<span>{task.text}</span>
   				<span>assigned by {task.assigner}</span>
   			</li>
   		{/each}
   	</ul>
   {/if}
   ```

10. Start the app

    Start the app, open <http://localhost:5173> in a browser, and see the list of tasks.

    ```
    npm run dev
    ```

See the [Svelte npm package documentation](https://www.npmjs.com/package/convex-svelte).

---

# Source: https://docs.convex.dev/client/swift.md

# Source: https://docs.convex.dev/quickstart/swift.md

# iOS Swift Quickstart

Learn how to query data from Convex in an application targeting iOS and MacOS devices built with Swift and SwiftUI.

This quickstart assumes that you have a Mac with Xcode, node and npm installed. If you don’t have those tools, take time to install them first.

1. Create a new iOS app in Xcode

   1. Click *Create New Project*
   2. Select iOS App and click *Next*
   3. Name your project something like “ConvexQuickstart”
   4. Ensure Language is set to Swift and User Interface is SwiftUI
   5. Click *Next*

   ![Create new iOS project](/screenshots/swift_qs_step_1.png)

2. Configure dependencies

   1. Click on the top-level ConvexQuickstart app container in the project navigator on the left
   2. Click on ConvexQuickstart under the PROJECT heading
   3. Click the Package Dependencies tab
   4. Click the + button (See Screenshot)
   5. Paste
      <!-- -->
      ```
      https://github.com/get-convex/convex-swift
      ```
      <!-- -->
      into the search box and press enter
   6. When the `convex-swift` package loads, click the *Add Package* button
   7. In the *Package Products* dialog, select ConvexQuickstart in the *Add to Target* dropdown
   8. Click the Add Package button

   ![Add Convex dependency to package](/screenshots/swift_qs_step_2.png)

3. <br />

   Install the Convex backend

   Open a terminal and `cd` to the directory for the Xcode project you created. Run the following commands to install the Convex client and server library.

   ```
   npm init -y
   npm install convex
   ```

4. Start Convex

   Start a Convex dev deployment. Follow the command line instructions to create a new project.

   ```
   npx convex dev
   ```

5. Create sample data for your database

   Create a new `sampleData.jsonl` file in your Swift project directory with these contents

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

6. Add the sample data to a table called \`tasks\` in your database

   Open another terminal tab by pressing ⌘+T which should open in your Swift project directory and run

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

7. Expose a database query

   Create a `tasks.ts` file in the `convex/` directory within your Swift project with the following contents

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

8. Create a Swift struct

   Back in Xcode, create a `struct` at the bottom of the `ContentView` file to match the sample data

   ```
   // We're using the name Todo instead of Task to avoid clashing with
   // Swift's builtin Task type.
   struct Todo: Decodable {
     let _id: String
     let text: String
     let isCompleted: Bool
   }
   ```

9. Connect the app to your backend

   1. Get the deployment URL of your dev server with `cat .env.local | grep CONVEX_URL`
   2. Create a `ConvexClient` instance near the top of the file, just above the `ContentView` struct

   ```
   import SwiftUI
   import ConvexMobile

   let convex = ConvexClient(deploymentUrl: "YOUR_CONVEX_URL")

   struct ContentView: View {
   ...
   ```

10. Create your UI

    Replace the default `ContentView` with the following code that will refresh the list of todo items whenever the backend data changes.

    ```
    struct ContentView: View {
      @State private var todos: [Todo] = []

      var body: some View {
        List {
          ForEach(todos, id: \._id) { todo in
            Text(todo.text)
          }
        }.task {
          for await todos: [Todo] in convex.subscribe(to: "tasks:get")
            .replaceError(with: []).values
          {
            self.todos = todos
          }
        }.padding()
      }
    }
    ```

11. Run the app

    1. Press ⌘+R or click *Product → Run*
    2. You can also try adding, updating or deleting documents in your `tasks` table at `dashboard.convex.dev` - the app will update with the changes in real-time.

    ![App preview](/screenshots/swift_qs_final.png)

See the complete [iOS Swift documentation](/client/swift.md).

---

# Source: https://docs.convex.dev/database/advanced/system-tables.md

# System Tables

System tables enable read-only access to metadata for built-in Convex features. Currently there are two system tables exposed:

* `"_scheduled_functions"` table contains metadata for [scheduled functions](/scheduling/scheduled-functions.md#retrieving-scheduled-function-status)
* `"_storage"` table contains metadata for [stored files](/file-storage/file-metadata.md)

You can read data from system tables using the `db.system.get` and `db.system.query` methods, which work the same as the standard `db.get` and `db.query` methods. Queries reading from system tables are reactive and realtime just like queries reading from all other tables, and pagination can be used to enumerate all documents even when there are too many to read in a single query.

---

# Source: https://docs.convex.dev/client/tanstack/tanstack-query.md

# Convex with TanStack Query

[TanStack Query](https://tanstack.com/query/latest) is an excellent, popular library for managing requests to a server.

The [`@convex-dev/react-query`](https://www.npmjs.com/package/@convex-dev/react-query) library provides [Query Option](https://tanstack.com/query/latest/docs/framework/react/guides/query-options) functions for use with TanStack Query.

Not all features of the standard [Convex React client](/client/react.md) are available through the TanStack Query APIs but you can use the two alongside each other, dropping into the standard Convex React hooks as necessary.

The TanStack Query adapter is in beta

The TanStack Query adapter<!-- --> <!-- -->is<!-- --> currently a [beta feature](/production/state/.md#beta-features). If you have feedback or feature requests, [let us know on Discord](https://convex.dev/community)!

This makes subscribing to a Convex query function using the TanStack Query `useQuery` hook look like this:

```
const { data, isPending, error } = useQuery(convexQuery(api.messages.list, {}));
```

Instead of the typical polling pattern for API endpoints used with TanStack Query, the code above receives updates for this `api.messages.list` query from the Convex server reactively. New results for all relevant subscriptions are pushed to the client where they update at the same time so data is never stale and there's no need to manually invalidate queries.

Support for other frameworks

Currently only [React Query](https://tanstack.com/query/latest/docs/framework/react/overview) is supported via [`@convex-dev/react-query`](https://www.npmjs.com/package/@convex-dev/react-query). [Let us know](https://convex.dev/community) if you would find support for vue-query, svelte-query, solid-query, or angular-query helpful.

## Setup[​](#setup "Direct link to Setup")

To get live updates in TanStack Query create a `ConvexQueryClient` and connect it to the TanStack Query [QueryClient](https://tanstack.com/query/latest/docs/reference/QueryClient). After installing the adapter library with

```
npm i @convex-dev/react-query
```

wire up Convex to TanStack Query like this:

src/main.tsx

```
import { ConvexQueryClient } from "@convex-dev/react-query";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ConvexProvider, ConvexReactClient } from "convex/react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convex);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: convexQueryClient.hashFn(),
      queryFn: convexQueryClient.queryFn(),
    },
  },
});
convexQueryClient.connect(queryClient);

ReactDOM.createRoot(document.getElementById("root")!).render(
  <ConvexProvider client={convex}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ConvexProvider>,
);
```

Note that when your create your React tree you should both:

* wrap your app in the TanStack Query [`QueryClientProvider`](https://tanstack.com/query/latest/docs/framework/react/reference/QueryClientProvider) so you can use [TanStack Query hooks](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) and
* wrap your app in the [`ConvexProvider`](/api/modules/react.md#convexprovider) so you can also use normal [Convex React](/client/react.md) hooks

## Queries[​](#queries "Direct link to Queries")

A live-updating subscription to a Convex [query](/functions/query-functions.md) is as simple as calling TanStack [`useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) with `convexQuery`:

```
import { useQuery } from "@tanstack/react-query";
import { convexQuery } from "@convex-dev/react-query";
import { api } from "../convex/_generated/api";

export function App() {
  const { data, isPending, error } = useQuery(
    convexQuery(api.functions.myQuery, { id: 123 }),
  );
  return isPending ? "Loading..." : data;
}
```

You can spread the object returned by `convexQuery` into an object specifying additional [arguments of `useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).

```
const { data, isPending, error } = useQuery({
  ...convexQuery(api.functions.myQuery, { id: 123 }),
  initialData: [], // use an empty list if no data is available yet
  gcTime: 10000, // stay subscribed for 10 seconds after this component unmounts
});
```

## Mutations[​](#mutations "Direct link to Mutations")

Your app can call Convex [mutations](/functions/mutation-functions.md) by using the TanStack [`useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) hook, and setting the `mutationFn` property to the result of calling `useConvexMutation`:

```
import { useMutation } from "@tanstack/react-query";
import { useConvexMutation } from "@convex-dev/react-query";
import { api } from "../convex/_generated/api";

export function App() {
  const { mutate, isPending } = useMutation({
    mutationFn: useConvexMutation(api.functions.doSomething),
  });
  return <button onClick={() => mutate({a: "Hello"})}>Click me</button>;
}
```

`useConvexMutation` is just a re-export of the [`useMutation`](/client/react.md#editing-data) hook from [Convex React](/client/react.md).

## Differences from using `fetch` with TanStack Query[​](#differences-from-using-fetch-with-tanstack-query "Direct link to differences-from-using-fetch-with-tanstack-query")

Convex provides stronger guarantees than other methods of fetching data with React Query, so some options and return value properties are no longer necessary.

Subscriptions to Convex queries will remain active after the last component using `useQuery` for a given function unmounts for `gcTime` milliseconds. This value is 5 minutes by default; if this results in unwanted function activity use a smaller value.

Data provided by Convex is never stale, so the `isStale` property of the return value of `useQuery` will always be false. `retry`-related options are ignored, since Convex provides its own retry mechanism over its WebSocket protocol. `refetch`-related options are similarly ignored since Convex queries are always up to date.

---

# Source: https://docs.convex.dev/client/tanstack/tanstack-start.md

# Source: https://docs.convex.dev/quickstart/tanstack-start.md

# TanStack Start Quickstart

TanStack Start is in Release Candidate

[TanStack Start](https://tanstack.com/start/latest) is a new React framework currently in the Release Candidate stage. You can try it today but there might still be bug or issues.

To get setup quickly with Convex and TanStack Start run

**`npm create convex@latest -- -t tanstack-start`**

**``**

or follow the guide below.

To use Clerk with Convex and TanStack Start, see the [TanStack Start + Clerk guide](/client/tanstack/tanstack-start/clerk.md)

***

Learn how to query data from Convex in a TanStack Start site.

1. Create a TanStack Start site

   Create a TanStack Start app using the `create-start-app` command:

   ```
   npx create-start-app@latest
   ```

2. Install the Convex client and server library

   To get started with Convex install the `convex` package and a few React Query-related packages.

   ```
   npm install convex @convex-dev/react-query @tanstack/react-router-with-query @tanstack/react-query
   ```

3. Update app/routes/\_\_root.tsx

   Add a `QueryClient` to the router context to make React Query usable anywhere in the TanStack Start site.

   app/routes/\_\_root.tsx

   ```
   import { QueryClient } from "@tanstack/react-query";
   import { createRootRouteWithContext } from "@tanstack/react-router";
   import { Outlet, Scripts, HeadContent } from "@tanstack/react-router";
   import * as React from "react";

   export const Route = createRootRouteWithContext<{
     queryClient: QueryClient;
   }>()({
     head: () => ({
       meta: [
         {
           charSet: "utf-8",
         },
         {
           name: "viewport",
           content: "width=device-width, initial-scale=1",
         },
         {
           title: "TanStack Start Starter",
         },
       ],
     }),
     component: RootComponent,
   });

   function RootComponent() {
     return (
       <RootDocument>
         <Outlet />
       </RootDocument>
     );
   }

   function RootDocument({ children }: { children: React.ReactNode }) {
     return (
       <html>
         <head>
           <HeadContent />
         </head>
         <body>
           {children}
           <Scripts />
         </body>
       </html>
     );
   }
   ```

4. Update app/router.tsx

   Replace the file `app/router.tsx` with these contents.

   This creates a `ConvexClient` and a `ConvexQueryClient` and wires in a `ConvexProvider`.

   app/router.tsx

   ```
   import { createRouter } from "@tanstack/react-router";
   import { QueryClient } from "@tanstack/react-query";
   import { routerWithQueryClient } from "@tanstack/react-router-with-query";
   import { ConvexQueryClient } from "@convex-dev/react-query";
   import { ConvexProvider } from "convex/react";
   import { routeTree } from "./routeTree.gen";

   export function getRouter() {
     const CONVEX_URL = (import.meta as any).env.VITE_CONVEX_URL!;
     if (!CONVEX_URL) {
       console.error("missing envar VITE_CONVEX_URL");
     }
     const convexQueryClient = new ConvexQueryClient(CONVEX_URL);

     const queryClient: QueryClient = new QueryClient({
       defaultOptions: {
         queries: {
           queryKeyHashFn: convexQueryClient.hashFn(),
           queryFn: convexQueryClient.queryFn(),
         },
       },
     });
     convexQueryClient.connect(queryClient);

     const router = routerWithQueryClient(
       createRouter({
         routeTree,
         defaultPreload: "intent",
         context: { queryClient },
         scrollRestoration: true,
         Wrap: ({ children }) => (
           <ConvexProvider client={convexQueryClient.convexClient}>
             {children}
           </ConvexProvider>
         ),
       }),
       queryClient,
     );

     return router;
   }
   ```

5. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

6. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

7. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

8. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

9. Display the data in your app

   Replace the file `app/routes/index.tsx` with these contents.

   The `useSuspenseQuery` hook renders the API function `api.tasks.get` query result on the server initially, then it updates live in the browser.

   app/routes/index.tsx

   ```
   import { convexQuery } from "@convex-dev/react-query";
   import { useSuspenseQuery } from "@tanstack/react-query";
   import { createFileRoute } from "@tanstack/react-router";
   import { api } from "../../convex/_generated/api";

   export const Route = createFileRoute("/")({
     component: Home,
   });

   function Home() {
     const { data } = useSuspenseQuery(convexQuery(api.tasks.get, {}));

     return (
       <div>
         {data.map(({ _id, text }) => (
           <div key={_id}>{text}</div>
         ))}
       </div>
     );
   }
   ```

10. Start the app

    Start the app, open <http://localhost:3000> in a browser, and see the list of tasks.

    ```
    npm run dev
    ```

For more see the [TanStack Start with Convex](/client/tanstack/tanstack-start/.md) client documentation page.

---

# Source: https://docs.convex.dev/dashboard/teams.md

# Teams

In Convex, your projects are organized by team. Teams are used to share access to your projects with other people. You may switch between teams or create a new team by clicking on the name of your team located on the top of the Convex dashboard. This will open the project selector, where you can switch teams by clicking on the team name once again.

![Team switcher](/assets/images/team_selector-4f2055dd3c3513c29d2232ed7365ce1b.png)

You may change the name of a team or invite new members to a team by clicking on the "Team Settings" button located on the top of the project list page.

## General[​](#general "Direct link to General")

The [general page](https://dashboard.convex.dev/team/settings) allows changing the team name and slug.

You may also delete the team from this page. You can only delete a team after deleting all of it's projects, and removing all other team members from your team. Deleting your team will automatically cancel your Convex subscription.

![General team settings page](/assets/images/teams_general-be57d90397e8c7890730dfd5d52f29a3.png)

## Team Members[​](#team-members "Direct link to Team Members")

Use the [members settings page](https://dashboard.convex.dev/team/settings/members) to invite or remove members from your team.

![Team members page](/assets/images/teams_members-a49899c63f9a183cb0b684f0353bc678.png)

### Roles and permissions[​](#roles-and-permissions "Direct link to Roles and permissions")

Convex has two levels of control for managing access to your team, projects, and deployments. Team-level roles control what a user can do within the team, while project-level permissions control what a user can do within a specific project.

#### Team roles[​](#team-roles "Direct link to Team roles")

Your team members can have one of the following roles:

* Admin
* Developer

The creator of the team is automatically assigned the Admin role. When inviting new team members, you may select a role for them. You may also change the role of a team member at any time.

Developers can:

* Create new projects and deployments. When a new project is created, the creator of the project is automatically granted the [Project Admin](#project-admins) role for that project.
* View existing projects, and create development and preview deployments for these projects. Developers may read data from production deployments, but cannot write to them.
* View the team's usage and billing status (such as previous and upcoming invoices)

Admins can do everything developers can, as well as:

* Invite new team members
* Remove members from the team
* Change the role of other team members
* Manage the team's Convex subscription and billing details.
* Change the team name and slug
* Team Admins are also implicitly granted project admin access to all projects within the team. See [Project Admins](#project-admins) for more information.

#### Project Admins[​](#project-admins "Direct link to Project Admins")

In addition to team roles, you may also grant admin access to individual projects by granting team members the "Project Admin" role.

If you are a Project Admin for a given project, you may:

* Update the project name and slug
* Update the project's default environment variables
* Delete the project
* Write to production deployments

You may assign and remove the Project Admin role for multiple projects at the same time on the member settings page. To assign or remove the Project Admin role for multiple members at the same time, visit the [Project Settings](/dashboard/projects.md#project-settings) page instead.

## Billing[​](#billing "Direct link to Billing")

Use the [billing page](https://dashboard.convex.dev/team/settings/billing) to upgrade your Convex subscription to a higher tier, or manage your existing subscription.

On paid plans, you can also update your billing contact details, payment method, and view your invoices.

[Learn more about Convex pricing](https://www.convex.dev/pricing).

![Team billing page](/assets/images/teams_billing-52fb5e7787443bac74030153c75f3a80.png)

### Spending limits[​](#spending-limits "Direct link to Spending limits")

When you have an active Convex subscription, you can set the spending limits for your team on the [billing page](https://dashboard.convex.dev/team/settings/billing):

* The **warning threshold** is only a soft limit: if it is exceeded, the team will be notified by email, but no other action will be taken.
* The **disable threshold** is a hard limit: if it is exceeded, all projects in the team will be disabled. This will cause errors to be thrown when attempting to run functions in your projects. You can re-enable projects by increasing or removing the limit.

Spending limits only apply to the resources used by your team’s projects beyond the amounts included in your plan. The seat fees (the amount paid for each developer in your team) are not counted towards the limits. For instance, if you send the spending limit to $0/month, you will be billed for the seat fees only and the projects will be disabled if you exceed the built-in resources included in your plan.

![The team billing page with some spending limits set.](/assets/images/teams_billing_spending_limits-3288d9eefd1e795c3e73baa05fcecb9e.png)

## Usage[​](#usage "Direct link to Usage")

On the [usage page](https://dashboard.convex.dev/team/settings/usage) you can see all the resources consumed by your team, and how you're tracking against your plan's limits.

[Learn more about Convex pricing](https://www.convex.dev/pricing).

![Team usage page](/assets/images/teams_usage-714de6c9b025dd8a5724545347f16ff7.png)

All metrics are available in daily breakdowns:

![Team usage page graphs](/assets/images/teams_usage_2-be702e62f3542f613dceeb4464d8a724.png)

## Audit Log[​](#audit-log "Direct link to Audit Log")

info

The Audit Log is only available on Convex Professional.

The [audit log page](https://dashboard.convex.dev/team/settings/audit-log) shows all the actions taken by members within the team. This includes creating and managing projects and deployments, inviting and removing team members, and more.

![Team audit log page](/assets/images/teams_audit_log-c22793879705a616a42ab4f72274358a.png)

You may also view a history of deployment-related events on the [deployment history page](/dashboard/deployments/history.md).

---

# Source: https://docs.convex.dev/testing.md

# Testing

Convex makes it easy to test your app via automated tests running in JS or against a real backend, and manually in dev, preview and staging environments.

## Automated tests[​](#automated-tests "Direct link to Automated tests")

### `convex-test` library[​](#convex-test-library "Direct link to convex-test-library")

[Use the `convex-test` library](/testing/convex-test.md) to test your functions in JS via the excellent Vitest testing framework.

### Testing against a real backend[​](#testing-against-a-real-backend "Direct link to Testing against a real backend")

Convex open source builds allow you to test all of your backend logic running on a real [local Convex backend](/testing/convex-backend.md).

### Set up testing in CI[​](#set-up-testing-in-ci "Direct link to Set up testing in CI")

It's a good idea to test your app continuously in a controlled environment. No matter which way automated method you use, it's easy to run them with [GitHub Actions](/testing/ci.md).

<!-- -->

<!-- -->

## Manual tests[​](#manual-tests "Direct link to Manual tests")

### Running a function in dev[​](#running-a-function-in-dev "Direct link to Running a function in dev")

Manually run a function in dev to quickly see if things are working:

* [Run functions from the command line](/cli.md#run-convex-functions)
* [Run functions from the dashboard](/dashboard/deployments/functions.md#running-functions)

### Preview deployments[​](#preview-deployments "Direct link to Preview deployments")

[Use preview deployments](/production/hosting/preview-deployments.md) to get early feedback from your team for your in-progress features.

### Staging environment[​](#staging-environment "Direct link to Staging environment")

You can set up a separate project as a staging environment to test against. See [Deploying Your App to Production](/production.md#staging-environment).

---

# Source: https://docs.convex.dev/search/text-search.md

# Full Text Search

Full text search allows you to find Convex documents that approximately match a search query.

Unlike normal [document queries](/database/reading-data/.md#querying-documents), search queries look *within* a string field to find the keywords. Search queries are useful for building features like searching for messages that contain certain words.

Search queries are automatically reactive, consistent, transactional, and work seamlessly with pagination. They even include new documents created with a mutation!

**Example:** [Search App](https://github.com/get-convex/convex-demos/tree/main/search)

To use full text search you need to:

1. Define a search index.
2. Run a search query.

Search indexes are built and queried using Convex's multi-segment search algorithm on top of [Tantivy](https://github.com/quickwit-oss/tantivy), a powerful, open-source, full-text search library written in Rust.

## Defining search indexes[​](#defining-search-indexes "Direct link to Defining search indexes")

Like [database indexes](/database/reading-data/indexes/.md), search indexes are a data structure that is built in advance to enable efficient querying. Search indexes are defined as part of your Convex [schema](/database/schemas.md).

Every search index definition consists of:

1. A name.
   <!-- -->
   * Must be unique per table.

2. A `searchField`

   * This is the field which will be indexed for full text search.
   * It must be of type `string`.

3. \[Optional] A list of `filterField`s
   <!-- -->
   * These are additional fields that are indexed for fast equality filtering within your search index.

4. \[Optional] A boolean `staged` flag
   <!-- -->
   * If set to `true`, the index will be backfilled asynchronously from the deploy similar to [staged database indexes](/database/reading-data/indexes/.md#staged-indexes). This is useful for large tables where the index backfill time is significant. Defaults to `false`.

To add a search index onto a table, use the [`searchIndex`](/api/classes/server.TableDefinition.md#searchindex) method on your table's schema. For example, if you want an index which can search for messages matching a keyword in a channel, your schema could look like:

convex/schema.ts

```
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  messages: defineTable({
    body: v.string(),
    channel: v.string(),
  }).searchIndex("search_body", {
    searchField: "body",
    filterFields: ["channel"],
    staged: false,
  }),
});
```

You can specify search and filter fields on nested documents by using a dot-separated path like `properties.name`.

## Running search queries[​](#running-search-queries "Direct link to Running search queries")

A query for "10 messages in channel '#general' that best match the query 'hello hi' in their body" would look like:

```
const messages = await ctx.db
  .query("messages")
  .withSearchIndex("search_body", (q) =>
    q.search("body", "hello hi").eq("channel", "#general"),
  )
  .take(10);
```

This is just a normal [database read](/database/reading-data/.md) that begins by querying the search index!

The [`.withSearchIndex`](/api/interfaces/server.QueryInitializer.md#withsearchindex) method defines which search index to query and how Convex will use that search index to select documents. The first argument is the name of the index and the second is a *search filter expression*. A search filter expression is a description of which documents Convex should consider when running the query.

A search filter expression is always a chained list of:

1. 1 search expression against the index's search field defined with [`.search`](/api/interfaces/server.SearchFilterBuilder.md#search).
2. 0 or more equality expressions against the index's filter fields defined with [`.eq`](/api/interfaces/server.SearchFilterFinalizer.md#eq).

### Search expressions[​](#search-expressions "Direct link to Search expressions")

Search expressions are issued against a search index, filtering and ranking documents by their relevance to the search expression's query. Internally, Convex will break up the query into separate words (called *terms*) and approximately rank documents matching these terms.

In the example above, the expression `search("body", "hello hi")` would internally be split into `"hi"` and `"hello"` and matched against words in your document (ignoring case and punctuation).

The behavior of search incorporates [prefix matching rules](#search-behavior).

### Equality expressions[​](#equality-expressions "Direct link to Equality expressions")

Unlike search expressions, equality expressions will filter to only documents that have an exact match in the given field. In the example above, `eq("channel", "#general")` will only match documents that have exactly `"#general"` in their `channel` field.

Equality expressions support fields of any type (not just text).

To filter to documents that are missing a field, use `q.eq("fieldName", undefined)`.

### Other filtering[​](#other-filtering "Direct link to Other filtering")

Because search queries are normal database queries, you can also [filter results](/database/reading-data/filters.md) using the [`.filter` method](/api/interfaces/server.Query.md#filter)!

Here's a query for "messages containing 'hi' sent in the last 10 minutes":

```
const messages = await ctx.db
  .query("messages")
  .withSearchIndex("search_body", (q) => q.search("body", "hi"))
  .filter((q) => q.gt(q.field("_creationTime", Date.now() - 10 * 60000)))
  .take(10);
```

**For performance, always put as many of your filters as possible into `.withSearchIndex`.**

Every search query is executed by:

1. First, querying the search index using the search filter expression in `withSearchIndex`.
2. Then, filtering the results one-by-one using any additional `filter` expressions.

Having a very specific search filter expression will make your query faster and less likely to hit Convex's limits because Convex will use the search index to efficiently cut down on the number of results to consider.

### Retrieving results and paginating[​](#retrieving-results-and-paginating "Direct link to Retrieving results and paginating")

Just like ordinary database queries, you can [retrieve the results](/database/reading-data/.md#retrieving-results) using [`.collect()`](/api/interfaces/server.Query.md#collect), [`.take(n)`](/api/interfaces/server.Query.md#take), [`.first()`](/api/interfaces/server.Query.md#first), and [`.unique()`](/api/interfaces/server.Query.md#unique).

Additionally, search results can be [paginated](/database/pagination.md) using [`.paginate(paginationOpts)`](/api/interfaces/server.OrderedQuery.md#paginate).

Note that `collect()` will throw an exception if it attempts to collect more than the limit of 1024 documents. It is often better to pick a smaller limit and use `take(n)` or paginate the results.

### Ordering[​](#ordering "Direct link to Ordering")

Search queries always return results in [relevance order](#relevance-order) based on how well the document matches the search query. Different ordering of results are not supported.

## Search Behavior[​](#search-behavior "Direct link to Search Behavior")

### Typeahead Search[​](#typeahead-search "Direct link to Typeahead Search")

Convex full-text search is designed to power as-you-type search experiences. In your search queries, the final search term has *prefix search* enabled, matching any term that is a prefix of the original term. For example, the expression `search("body", "r")` would match the documents:

* `"rabbit"`
* `"send request"`

Fuzzy search matches are deprecated. After January 15, 2025, search results will not include `"snake"` for a typo like `"stake"`.

### Relevance order[​](#relevance-order "Direct link to Relevance order")

**Relevance order is subject to change.** The relevance of search results and the exact rules Convex applies is subject to change to improve the quality of search results.

Search queries return results in relevance order. Internally, Convex ranks the relevance of a document based on a combination of its [BM25 score](https://en.wikipedia.org/wiki/Okapi_BM25) and several other criteria such as the proximity of matches, the number of exact matches, and more. The BM25 score takes into account:

* How many words in the search query appear in the field?
* How many times do they appear?
* How long is the text field?

If multiple documents have the same score, the newest documents are returned first.

## Limits[​](#limits "Direct link to Limits")

Search indexes work best with English or other Latin-script languages. Text is tokenized using Tantivy's [`SimpleTokenizer`](https://docs.rs/tantivy/latest/tantivy/tokenizer/struct.SimpleTokenizer.html), which splits on whitespace and punctuation. We also limit terms to 32 characters in length and lowercase them.

Search indexes must have:

* Exactly 1 search field.
* Up to 16 filter fields.

Search indexes count against the [limit of 32 indexes per table](/database/reading-data/indexes/.md#limits).

Search queries can have:

* Up to 16 terms (words) in the search expression.
* Up to 8 filter expressions.

Additionally, search queries can scan up to 1024 results from the search index.

The source of truth for these limits is our [source code](https://github.com/get-convex/convex-backend/blob/main/crates/search/src/constants.rs).

For information on other limits, see [here](/production/state/limits.md).

---

# Source: https://docs.convex.dev/agents/threads.md

# Threads

Threads are a way to group messages together in a linear history. All messages saved in the Agent component are associated with a thread. When a message is generated based on a prompt, it saves the user message and generated agent message(s) automatically.

Threads can be associated with a user, and messages can each individually be associated with a user. By default, messages are associated with the thread's user.

## Creating a thread[​](#creating-a-thread "Direct link to Creating a thread")

You can create a thread in a mutation or action. If you create it in an action, it will also return a `thread` (see below) and you can start calling LLMs and generating messages. If you specify a userId, the thread will be associated with that user and messages will be saved to the user's history.

```
import { createThread } from "@convex-dev/agent";

const threadId = await createThread(ctx, components.agent);
```

You may also pass in metadata to set on the thread:

```
const userId = await getAuthUserId(ctx);
const threadId = await createThread(ctx, components.agent, {
  userId,
  title: "My thread",
  summary: "This is a summary of the thread",
});
```

Metadata may be provided as context to the agent automatically in the future, but for now it's a convenience that helps organize threads in the [Playground](/agents/playground.md).

## Generating a message in a thread[​](#generating-a-message-in-a-thread "Direct link to Generating a message in a thread")

You can generate a message in a thread via the agent functions: `agent.generateText`, `agent.generateObject`, `agent.streamText`, and `agent.streamObject`. Any agent can generate a message in a thread created by any other agent.

```
const agent = new Agent(components.agent, { languageModel, instructions });

export const generateReplyToPrompt = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    // await authorizeThreadAccess(ctx, threadId);
    const result = await agent.generateText(ctx, { threadId }, { prompt });
    return result.text;
  },
});
```

See [Messages](/agents/messages.md) for more details on creating and saving messages.

## Continuing a thread using the `thread` object from `agent.continueThread`[​](#continuing-a-thread-using-the-thread-object-from-agentcontinuethread "Direct link to continuing-a-thread-using-the-thread-object-from-agentcontinuethread")

You can also continue a thread by creating an agent-specific `thread` object, either when calling `agent.createThread` or `agent.continueThread` from within an action. This allows calling methods without specifying those parameters each time.

```
const { thread } = await agent.continueThread(ctx, { threadId });
const result = await thread.generateText({ prompt });
```

The `thread` from `continueThread` or `createThread` (available in actions only) is a `Thread` object, which has convenience methods that are thread-specific:

* `thread.getMetadata()` to get the `userId`, `title`, `summary` etc.
* `thread.updateMetadata({ patch: { title, summary, userId} })` to update the metadata
* `thread.generateText({ prompt, ... })` - equivalent to `agent.generateText(ctx, { threadId }, { prompt, ... })`
* `thread.streamText({ prompt, ... })` - equivalent to `agent.streamText(ctx, { threadId }, { prompt, ... })`
* `thread.generateObject({ prompt, ... })` - equivalent to `agent.generateObject(ctx, { threadId }, { prompt, ... })`
* `thread.streamObject({ prompt, ... })` - equivalent to `agent.streamObject(ctx, { threadId }, { prompt, ... })`

See [Messages docs](/agents/messages.md) for more details on generating messages.

## Deleting threads[​](#deleting-threads "Direct link to Deleting threads")

You can delete threads by their `threadId`.

Asynchronously (from a mutation or action):

```
await agent.deleteThreadAsync(ctx, { threadId });
```

Synchronously in batches (from an action):

```
await agent.deleteThreadSync(ctx, { threadId });
```

You can also delete all threads by a user by their `userId`.

```
await agent.deleteThreadsByUserId(ctx, { userId });
```

## Getting all threads owned by a user[​](#getting-all-threads-owned-by-a-user "Direct link to Getting all threads owned by a user")

```
const threads = await ctx.runQuery(
  components.agent.threads.listThreadsByUserId,
  { userId, paginationOpts: args.paginationOpts },
);
```

## Deleting all threads and messages associated with a user[​](#deleting-all-threads-and-messages-associated-with-a-user "Direct link to Deleting all threads and messages associated with a user")

Asynchronously (from a mutation or action):

```
await ctx.runMutation(components.agent.users.deleteAllForUserIdAsync, {
  userId,
});
```

Synchronously (from an action):

```
await ctx.runMutation(components.agent.users.deleteAllForUserId, { userId });
```

## Getting messages in a thread[​](#getting-messages-in-a-thread "Direct link to Getting messages in a thread")

See [messages.mdx](/agents/messages.md) for more details.

```
import { listMessages } from "@convex-dev/agent";

const messages = await listMessages(ctx, components.agent, {
  threadId,
  excludeToolMessages: true,
  paginationOpts: { cursor: null, numItems: 10 }, // null means start from the beginning
});
```

Or for the UIMessage type (easier for rendering UIs):

```
import { listUIMessages } from "@convex-dev/agent";

const messages = await listUIMessages(ctx, components.agent, {
  threadId,
  paginationOpts: { cursor: null, numItems: 10 },
});
```

---

# Source: https://docs.convex.dev/agents/tools.md

# Tools

The Agent component supports tool calls, which are a way to allow an LLM to call out to external services or functions. This can be useful for:

* Retrieving data from the database
* Writing or updating data in the database
* Searching the web for more context
* Calling an external API
* Requesting that a user takes an action before proceeding (human-in-the-loop)

## Defining tools[​](#defining-tools "Direct link to Defining tools")

You can provide tools at different times:

* Agent constructor: (`new Agent(components.agent, { tools: {...} })`)
* Creating a thread: `createThread(ctx, { tools: {...} })`
* Continuing a thread: `continueThread(ctx, { tools: {...} })`
* On thread functions: `thread.generateText({ tools: {...} })`
* Outside of a thread: `supportAgent.generateText(ctx, {}, { tools: {...} })`

Specifying tools at each layer will overwrite the defaults. The tools will be `args.tools ?? thread.tools ?? agent.options.tools`. This allows you to create tools in a context that is convenient.

## Using tools[​](#using-tools "Direct link to Using tools")

The Agent component will automatically handle passing tool call results back in and re-generating if you pass `stopWhen: stepCountIs(num)` where `num > 1` to `generateText` or `streamText`.

The tool call and result will be stored as messages in the thread associated with the source message. See [Messages](/agents/messages.md) for more details.

## Creating a tool with a Convex context[​](#creating-a-tool-with-a-convex-context "Direct link to Creating a tool with a Convex context")

There are two ways to create a tool that has access to the Convex context.

1. Use the `createTool` function, which is a wrapper around the AI SDK's `tool` function.

```
export const ideaSearch = createTool({
  description: "Search for ideas in the database",
  args: z.object({ query: z.string().describe("The query to search for") }),
  handler: async (ctx, args, options): Promise<Array<Idea>> => {
    // ctx has agent, userId, threadId, messageId
    // as well as ActionCtx properties like auth, storage, runMutation, and runAction
    const ideas = await ctx.runQuery(api.ideas.searchIdeas, {
      query: args.query,
    });
    console.log("found ideas", ideas);
    return ideas;
  },
});
```

2. Define tools at runtime in a context with the variables you want to use.

```
async function createTool(ctx: ActionCtx, teamId: Id<"teams">) {
  const myTool = tool({
    description: "My tool",
    parameters: z.object({...}).describe("The arguments for the tool"),
    execute: async (args, options): Promise<BarReturnType> => {
      return await ctx.runQuery(internal.foo.bar, args);
    },
  });
}
```

In both cases, the args and options match the underlying AI SDK's `tool` function.

If you run into type errors, ensure you're annotating the return type of the execute function, and if necessary, the return type of the `handler`s of any functions you call with `ctx.run*`.

Note: it's highly recommended to use zod with `.describe` to provide details about each parameter. This will be used to provide a description of the tool to the LLM.

### Adding custom context to tools[​](#adding-custom-context-to-tools "Direct link to Adding custom context to tools")

It's often useful to have extra metadata in the context of a tool.

By default, the context passed to a tool is a `ToolCtx` with:

* `agent` - the Agent instance calling it
* `userId` - the user ID associated with the call, if any
* `threadId` - the thread ID, if any
* `messageId` - the message ID of the prompt message passed to generate/stream.
* Everything in `ActionCtx`, such as `auth`, `storage`, `runQuery`, etc. Note: in scheduled functions, workflows, etc, the auth user will be `null`.

To add more fields to the context, you can pass a custom context to the call, such as `agent.generateText({ ...ctx, orgId: "123" })`.

You can enforce the type of the context by passing a type when constructing the Agent.

```
const myAgent = new Agent<{ orgId: string }>(...);
```

Then, in your tools, you can use the `orgId` field.

```
type MyCtx = ToolCtx & { orgId: string };

const myTool = createTool({
  args: z.object({ ... }),
  description: "...",
  handler: async (ctx: MyCtx, args) => {
    // use ctx.orgId
  },
});
```

## Using an LLM or Agent as a tool[​](#using-an-llm-or-agent-as-a-tool "Direct link to Using an LLM or Agent as a tool")

You can do generation within a tool call, for instance if you wanted one Agent to ask another Agent a question.

Note: you don't have to structure agents calling each other as tool calls. You could instead decide which Agent should respond next based on other context and have many Agents contributing in the same thread.

The simplest way to model Agents as tool calls is to have each tool call work in an independent thread, or do generation without a thread at all. Then, the output is returned as the tool call result for the next LLM step to use. When you do it this way, you **don't** need to explicitly save the tool call result to the parent thread.

### Direct LLM generation without a thread:[​](#direct-llm-generation-without-a-thread "Direct link to Direct LLM generation without a thread:")

```
const llmTool = createTool({
  description: "Ask a question to some LLM",
  args: z.object({
    message: z.string().describe("The message to ask the LLM"),
  }),
  handler: async (ctx, args): Promise<string> => {
    const result = await generateText({
      system: "You are a helpful assistant.",
      // Pass through all messages from the current generation
      prompt: [...options.messages, { role: "user", content: args.message }],
      model: myLanguageModel,
    });
    return result.text;
  },
});
```

### Using an Agent as a tool[​](#using-an-agent-as-a-tool "Direct link to Using an Agent as a tool")

```
const agentTool = createTool({
  description: `Ask a question to agent ${agent.name}`,
  args: z.object({
    message: z.string().describe("The message to ask the agent"),
  }),
  handler: async (ctx, args, options): Promise<string> => {
    const { userId } = ctx;
    const { thread } = await agent.createThread(ctx, { userId });
    const result = await thread.generateText(
      {
        // Pass through all messages from the current generation
        prompt: [...options.messages, { role: "user", content: args.message }],
      },
      // Save all the messages from the current generation to this thread.
      { storageOptions: { saveMessages: "all" } },
    );
    // Optionally associate the child thread with the parent thread in your own
    // tables.
    await saveThreadAsChild(ctx, ctx.threadId, thread.threadId);
    return result.text;
  },
});
```

---

# Source: https://docs.convex.dev/auth/authkit/troubleshooting.md

# AuthKit Troubleshooting

## Platform not authorized[​](#platform-not-authorized "Direct link to Platform not authorized")

```
WorkOSPlatformNotAuthorized: Your WorkOS platform API key is not authorized to
access this team. Please ensure the API key has the correct permissions in the
WorkOS dashboard.
```

This error occurs when your WorkOS platform API key is not authorized to access the WorkOS team associated with your Convex team.

This typically happens when the WorkOS workspace has had Convex removed.

You can contact WorkOS support to ask to restore this permission, or unlink the current workspace and create a new one:

```
npx convex integration workos disconnect-team
npx convex integration workos provision-team
```

You'll need to use a different email address to create your new WorkOS Workspace as an email address can only be associated with a single WorkOS workspace.

---

# Source: https://docs.convex.dev/tutorial.md

# Convex Tutorial: A chat app

Convex provides you with a fully featured backend with cloud functions, database, scheduling, and a sync engine that keeps your frontend and backend up to date in real-time.

Today, in about **10 lines of code,** we'll build a backend that reads and writes to the database and automatically updates all users in a chat app.

After that we'll see how to connect to external services and setup your product for success and scale.

[YouTube video player](https://www.youtube.com/embed/608khv7qqOI?si=ce-M8pt6EWDZ8tfd)

## Start developing with Convex[​](#start-developing-with-convex "Direct link to Start developing with Convex")

Before you begin: You'll need Node.js 18+ and Git

Ensure you have Node.js version 18 or greater installed on your computer. You can check your version of Node.js by running `node --version` in your terminal. If you don't have the appropriate version of Node.js installed, [install it from the Node.js website.](https://nodejs.org/en)

In addition, this walkthrough requires Git, so verify you have it installed by running `git -v` in your terminal. If not, head over to the [Git website](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for installation instructions.

First, clone the example project repo from GitHub and install the dependencies:

```
git clone https://github.com/get-convex/convex-tutorial.git
cd convex-tutorial
npm install
```

This app's `dev` npm command sets up Convex and then runs the web app:

```
npm run dev
```

During setup, you'll see that Convex uses your GitHub account for authentication. Sign into Convex with GitHub and then accept the default project setup prompts.

This will **automatically create your backend** and a folder called `convex/` in your project, where you'll write your backend code.

**Make sure you keep this command (`npm run dev`) running in the background throughout this tutorial.** It's running both the dev web server for the frontend as well as the `convex` command in the background to keep your backend in sync with your local codebase.

Once your server is up and running, open [localhost:5173](http://localhost:5173) and check it out:

![Chat UI](/assets/images/tut_chat_ui-9ab95f331e3132c9c61a0e2fc4eaf16c.png)

If you try sending a message now, you'll see an alert telling you the mutation is not yet implemented. We'll do that in a bit, but first here's a quick summary of how Convex works.

## How Convex works[​](#how-convex-works "Direct link to How Convex works")

![Overview of the sync engine](/assets/images/ConvexSyncEngine-3271d28868180073da72479d72a5d93e.png)

**Database.** The Convex database is a document-relational database, which means you have tables with JSON like documents in them. All documents have an auto-generated `_id` that can be used to create relations between documents. You interact with the database through mutation and query functions that are written entirely in TypeScript.

**Mutation functions.** Mutations are TypeScript functions that update the database. All mutation functions in Convex run as a database transaction. So either all the changes are committed, or none are.

**Query functions.** Queries are TypeScript functions that can only read from the database. As we'll see in a bit, you subscribe to them from your frontend to keep your app automatically up to date.

Your frontend registers to listen to query updates through the **client library**. The client libraries talk to Convex via WebSockets for fast realtime updates.

The **sync engine** reruns query functions when any input to the function changes, including any changes to the documents in the database that the query reads. It then updates every app listening to the query. The sync engine is the combination of queries, mutations and the database.

Now, let's dive into the code!

## Your first `mutation`[​](#your-first-mutation "Direct link to your-first-mutation")

Create a new file in your `convex/` folder called `chat.ts`. This is where you'll write your Convex backend functions for this application.

**Add the following to your `convex/chat.ts` file.**

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

export const sendMessage = mutation({
  args: {
    user: v.string(),
    body: v.string(),
  },
  handler: async (ctx, args) => {
    console.log("This TypeScript function is running on the server.");
    await ctx.db.insert("messages", {
      user: args.user,
      body: args.body,
    });
  },
});
```

Let's break this down:

1. You've added a new backend `mutation` function called `sendMessage` and exposed it as a public api.
2. The whole function automatically runs as a transaction that will roll back if an exception is thrown.
3. Since this is just a TypeScript function you can drop `console.log` lines to do simple debugging on the server.
4. `args:` ensures the function arguments are two strings named `user` and `body`, both as types and runtime values.
5. `ctx.db.insert` tells Convex to insert a new message document into the table.

Now, let's connect this mutation to your web app.

**Update your `src/App.tsx` file like so:**

```
// Import `useMutation` and `api` from Convex.
import { useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

//...

export default function App() {
  // Replace the "TODO: Add mutation hook here." with:
  const sendMessage = useMutation(api.chat.sendMessage);

  //...

  return (
    <main className="chat">
      {/* ... */}
      <form
        onSubmit={async (e) => {
          e.preventDefault();
          // Replace "alert("Mutation not implemented yet");" with:
          await sendMessage({ user: NAME, body: newMessageText });

          setNewMessageText("");
        }}
      >
        {/* ... */}
      </form>
    </main>
  );
}
```

There are two steps to call a mutation in your frontend:

1. `const sendMessage = useMutation(api.chat.sendMessage);` gives your frontend app a handle to the mutation function
2. `await sendMessage({ user: NAME, body: newMessageText });` calls the mutation with the proper parameters.

This is a good time to **open up the Convex dashboard**. Open a new browser window and go to <https://dashboard.convex.dev> and find new `convex-tutorial` project.

**Go to the "Data" screen**. So far, there is no data in your database.

**Keep your chat app and dashboard windows open side by side**. Now try to send some messages from your chat app.

Mutations hooked up to the Convex backend and database.

You'll notice new chat messages showing up live in the `messages` table.

Convex automatically created a `messages` table when you sent the first message. In Convex, [schemas](/database/schemas.md) are optional. Eventually, you'll want to enforce the structure of your tables, but for the purposes of the tutorial we'll skip this.

In the dashboard you can also go to the [logs screen](https://dashboard.convex.dev/deployment/logs) and see every call to the mutation as you ran with the log line we added earlier. The logs screen is a critical part of debugging your backend in development.

You've successfully created a `mutation` function, which is also a database transaction, and connected it to your UI.

Now, let's make sure your app can update live the same way the dashboard is updating live.

## Your first `query`[​](#your-first-query "Direct link to your-first-query")

**Update your `convex/chat.ts` file like this:**

```
// Update your server import like this:
import { query, mutation } from "./_generated/server";

// ...

// Add the following function to the file:
export const getMessages = query({
  args: {},
  handler: async (ctx) => {
    // Get most recent messages first
    const messages = await ctx.db.query("messages").order("desc").take(50);
    // Reverse the list so that it's in a chronological order.
    return messages.reverse();
  },
});
```

Let's break this down:

1. You've added a new backend `query` function called `getMessages` and exposed it as a public api.
2. Since this is a query function, the `ctx.db` in this function only lets you read data.
3. In the first line of the `handler` you are querying the most recent 50 messages from newest to oldest.
4. In the second line you're reversing the list using plain old TypeScript.

**Now update `src/App.tsx` to read from your query:**

```
// Update your convex/react import like this:
import { useQuery, useMutation } from "convex/react";

//...

export default function App() {
  // Replace the `const messages = ...` line with the following
  const messages = useQuery(api.chat.getMessages);

  //...
}
```

That one `useQuery` line is doing a lot of work automatically for you. It's telling the Convex client library to subscribe to your `getMessages` function. Anytime there are new messages to show the query function is automatically rerun. The result is put in `const messages` variable and React rerenders your UI component to show the latest messages.

That's it. Now go back to your app and try sending messages.

Your app should be showing live updates as new messages arrive:

Queries hooked up and live updating to the app.

<br />

<br />

Don't believe it? Try opening two chat windows side by side and send some messages:

Live syncing chat app.

## What you built[​](#what-you-built "Direct link to What you built")

With just a few lines of code you've built a live updating chat app.

1. You created a `mutation` TypeScript function that, in a transaction, adds new chat messages to your database.
2. You created a `query` TypeScript function updates your app with the latest data.
3. You used the client library that keeps your frontend in live sync with the backend.

You've learned the fundamentals of Convex and the sync engine that powers everything.

## Next up[​](#next-up "Direct link to Next up")

In this tutorial we just touched on the very basics. It's ok to just stop here and go explore the rest of the docs, including [efficient queries via indexes](/database/reading-data/indexes/.md) and traversing [relationships through joins](/database/reading-data/.md#join). If you're deeply curious about how Convex works, you can read this [excellent deep dive](https://stack.convex.dev/how-convex-works).

But if you want to see how to call external services and build sophisticated backend workflows, jump into the [next section →](/tutorial/actions.md).

## [Calling external services](/tutorial/actions.md)

[Extend your chat app by calling external APIs using Convex actions and the scheduler to integrate Wikipedia summaries into your application.](/tutorial/actions.md)

---

# Source: https://docs.convex.dev/database/types.md

# Data Types

All Convex documents are defined as JavaScript objects. These objects can have field values of any of the types below.

You can codify the shape of documents within your tables by [defining a schema](/database/schemas.md).

## Convex values[​](#convex-values "Direct link to Convex values")

Convex supports the following types of values:

| Convex Type | TS/JS Type                                                                                                                      | Example Usage          | Validator for [Argument Validation](/functions/validation.md) and [Schemas](/database/schemas.md) | `json` Format for [Export](/database/import-export/.md) | Notes                                                                                                                                                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Id          | [Id](/database/document-ids.md) ([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)) | `doc._id`              | `v.id(tableName)`                                                                                 | string                                                  | See [Document IDs](/database/document-ids.md).                                                                                                                                                                                                                                                                                                         |
| Null        | [null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type)                                       | `null`                 | `v.null()`                                                                                        | null                                                    | JavaScript's `undefined` is not a valid Convex value. Functions the return `undefined` or do not return will return `null` when called from a client. Use `null` instead.                                                                                                                                                                              |
| Int64       | [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type)                                   | `3n`                   | `v.int64()`                                                                                       | string (base10)                                         | Int64s only support BigInts between -2^63 and 2^63-1. Convex supports `bigint`s in [most modern browsers](https://caniuse.com/bigint).                                                                                                                                                                                                                 |
| Float64     | [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)                                   | `3.1`                  | `v.number()`                                                                                      | number / string                                         | Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings.                                                                                                                                                                                                                       |
| Boolean     | [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)                                 | `true`                 | `v.boolean()`                                                                                     | bool                                                    |                                                                                                                                                                                                                                                                                                                                                        |
| String      | [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)                                   | `"abc"`                | `v.string()`                                                                                      | string                                                  | Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.                                                                                                                                                                                                          |
| Bytes       | [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                     | `new ArrayBuffer(8)`   | `v.bytes()`                                                                                       | string (base64)                                         | Convex supports first class bytestrings, passed in as `ArrayBuffer`s. Bytestrings must be smaller than the 1MB total size limit for Convex types.                                                                                                                                                                                                      |
| Array       | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                 | `[1, 3.2, "abc"]`      | `v.array(values)`                                                                                 | array                                                   | Arrays can have at most 8192 values.                                                                                                                                                                                                                                                                                                                   |
| Object      | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)                                       | `{a: "abc"}`           | `v.object({property: value})`                                                                     | object                                                  | Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Convex includes all [enumerable properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "\_". |
| Record      | [Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)                                       | `{"a": "1", "b": "2"}` | `v.record(keys, values)`                                                                          | object                                                  | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "\_".                                                                                                                                                                                                               |

## System fields[​](#system-fields "Direct link to System fields")

Every document in Convex has two automatically-generated system fields:

* `_id`: The [document ID](/database/document-ids.md) of the document.
* `_creationTime`: The time this document was created, in milliseconds since the Unix epoch.

## Limits[​](#limits "Direct link to Limits")

Convex values must be less than 1MB in total size. This is an approximate limit for now, but if you're running into these limits and would like a more precise method to calculate a document's size, [reach out to us](https://convex.dev/community). Documents can have nested values, either objects or arrays that contain other Convex types. Convex types can have at most 16 levels of nesting, and the cumulative size of a nested tree of values must be under the 1MB limit.

Table names may contain alphanumeric characters ("a" to "z", "A" to "Z", and "0" to "9") and underscores ("\_"), and they cannot start with an underscore.

For information on other limits, see [here](/production/state/limits.md).

If any of these limits don't work for you, [let us know](https://convex.dev/community)!

## Working with `undefined`[​](#working-with-undefined "Direct link to working-with-undefined")

The TypeScript value `undefined` is not a valid Convex value, so it cannot be used in Convex function arguments or return values, or in stored documents.

1. Objects/records with `undefined` values are the same as if the field were missing: `{a: undefined}` is transformed into `{}` when passed to a function or stored in the database. You can think of Convex function calls and the Convex database as serializing the data with `JSON.stringify`, which similarly removes `undefined` values.

2. Validators for object fields can use `v.optional(...)` to indicate that the field might not be present.
   <!-- -->
   * If an object's field "a" is missing, i.e. `const obj = {};`, then `obj.a === undefined`. This is a property of TypeScript/JavaScript, not specific to Convex.

3. You can use `undefined` in filters and index queries, and it will match documents that do not have the field. i.e. `.withIndex("by_a", q=>q.eq("a", undefined))` matches document `{}` and `{b: 1}`, but not `{a: 1}` or `{a: null, b: 1}`.
   <!-- -->
   * In Convex's ordering scheme, `undefined < null < all other values`, so you can match documents that *have* a field via `q.gte("a", null as any)` or `q.gt("a", undefined)`.

4. There is exactly one case where `{a: undefined}` is different from `{}`: when passed to `ctx.db.patch`. Passing `{a: undefined}` removes the field "a" from the document, while passing `{}` does not change the field "a". See [Updating existing documents](/database/writing-data.md#updating-existing-documents).

5. Since `undefined` gets stripped from function arguments but has meaning in `ctx.db.patch`, there are some tricks to pass patch's argument from the client.

   <!-- -->

   * If the client passing `args={}` (or `args={a: undefined}` which is equivalent) should leave the field "a" unchanged, use `ctx.db.patch(id, args)`.
   * If the client passing `args={}` should remove the field "a", use `ctx.db.patch(id, {a: undefined, ...args})`.
   * If the client passing `args={}` should leave the field "a" unchanged and `args={a: null}` should remove it, you could do
     <!-- -->
     ```
     if (args.a === null) {
       args.a = undefined;
     }
     await ctx.db.patch(tableName, id, args);
     ```

6. Functions that return a plain `undefined`/`void` are treated as if they returned `null`.

7. Arrays containing `undefined` values, like `[undefined]`, throw an error when used as Convex values.

If you would prefer to avoid the special behaviors of `undefined`, you can use `null` instead, which *is* a valid Convex value.

## Working with dates and times[​](#working-with-dates-and-times "Direct link to Working with dates and times")

Convex does not have a special data type for working with dates and times. How you store dates depends on the needs of your application:

1. If you only care about a point in time, you can store a [UTC timestamp](https://en.wikipedia.org/wiki/Unix_time). We recommend following the `_creationTime` field example, which stores the timestamp as a `number` in milliseconds. In your functions and on the client you can create a JavaScript `Date` by passing the timestamp to its constructor: `new Date(timeInMsSinceEpoch)`. You can then print the date and time in the desired time zone (such as your user's machine's configured time zone).
   <!-- -->
   * To get the current UTC timestamp in your function and store it in the database, use `Date.now()`
2. If you care about a calendar date or a specific clock time, such as when implementing a booking app, you should store the actual date and/or time as a string. If your app supports multiple timezones you should store the timezone as well. [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) is a common format for storing dates and times together in a single string like `"2024-03-21T14:37:15Z"`. If your users can choose a specific time zone you should probably store it in a separate `string` field, usually using the [IANA time zone name](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) (although you could concatenate the two fields with unique character like `"|"`).

For more sophisticated printing (formatting) and manipulation of dates and times use one of the popular JavaScript libraries: [date-fns](https://date-fns.org/), [Day.js](https://day.js.org/), [Luxon](https://moment.github.io/luxon/) or [Moment.js](https://momentjs.com/).

---

# Source: https://docs.convex.dev/understanding/best-practices/typescript.md

# TypeScript

Convex provides end-to-end type support when Convex functions are written in [TypeScript](https://www.typescriptlang.org/).

You can gradually add TypeScript to a Convex project: the following steps provide progressively better type support. For the best support you'll want to complete them all.

**Example:** [TypeScript and Schema](https://github.com/get-convex/convex-demos/tree/main/typescript)

## Writing Convex functions in TypeScript[​](#writing-convex-functions-in-typescript "Direct link to Writing Convex functions in TypeScript")

The first step to improving type support in a Convex project is to writing your Convex functions in TypeScript by using the `.ts` extension.

If you are using [argument validation](/functions/validation.md), Convex will infer the types of your functions arguments automatically:

convex/sendMessage.ts

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

export default mutation({
  args: {
    body: v.string(),
    author: v.string(),
  },
  // Convex knows that the argument type is `{body: string, author: string}`.
  handler: async (ctx, args) => {
    const { body, author } = args;
    await ctx.db.insert("messages", { body, author });
  },
});
```

Otherwise you can annotate the arguments type manually:

convex/sendMessage.ts

```
import { internalMutation } from "./_generated/server";

export default internalMutation({
  // To convert this function from JavaScript to
  // TypeScript you annotate the type of the arguments object.
  handler: async (ctx, args: { body: string; author: string }) => {
    const { body, author } = args;
    await ctx.db.insert("messages", { body, author });
  },
});
```

This can be useful for [internal functions](/functions/internal-functions.md) accepting complicated types.

If TypeScript is installed in your project `npx convex dev` and `npx convex deploy` will typecheck Convex functions before sending code to the Convex backend.

Convex functions are typechecked with the `tsconfig.json` in the Convex folder: you can modify some parts of this file to change typechecking settings, or delete this file to disable this typecheck.

You'll find most database methods have a return type of `Promise<any>` until you add a schema.

## Adding a schema[​](#adding-a-schema "Direct link to Adding a schema")

Once you [define a schema](/database/schemas.md) the type signature of database methods will be known. You'll also be able to use types imported from `convex/_generated/dataModel` in both Convex functions and clients written in TypeScript (React, React Native, Node.js etc.).

The types of documents in tables can be described using the [`Doc`](/generated-api/data-model.md#doc) type from the generated data model and references to documents can be described with parametrized [Document IDs](/database/document-ids.md).

convex/messages.ts

```
import { query } from "./_generated/server";

export const list = query({
  args: {},
  // The inferred return type of `handler` is now `Promise<Doc<"messages">[]>`
  handler: (ctx) => {
    return ctx.db.query("messages").collect();
  },
});
```

## Type annotating server-side helpers[​](#type-annotating-server-side-helpers "Direct link to Type annotating server-side helpers")

When you want to reuse logic across Convex functions you'll want to define helper TypeScript functions, and these might need some of the provided context, to access the database, authentication and any other Convex feature.

Convex generates types corresponding to documents and IDs in your database, `Doc` and `Id`, as well as `QueryCtx`, `MutationCtx` and `ActionCtx` types based on your schema and declared Convex functions:

convex/helpers.ts

```
// Types based on your schema
import { Doc, Id } from "./_generated/dataModel";
// Types based on your schema and declared functions
import {
  QueryCtx,
  MutationCtx,
  ActionCtx,
  DatabaseReader,
  DatabaseWriter,
} from "./_generated/server";
// Types that don't depend on schema or function
import {
  Auth,
  StorageReader,
  StorageWriter,
  StorageActionWriter,
} from "convex/server";

// Note that a `MutationCtx` also satisfies the `QueryCtx` interface
export function myReadHelper(ctx: QueryCtx, id: Id<"channels">) {
  /* ... */
}

export function myActionHelper(ctx: ActionCtx, doc: Doc<"messages">) {
  /* ... */
}
```

### Inferring types from validators[​](#inferring-types-from-validators "Direct link to Inferring types from validators")

Validators can be reused between [argument validation](/functions/validation.md) and [schema validation](/database/schemas.md). You can use the provided [`Infer`](/api/modules/values.md#infer) type to get a TypeScript type corresponding to a validator:

convex/helpers.ts

```
import { Infer, v } from "convex/values";

export const courseValidator = v.union(
  v.literal("appetizer"),
  v.literal("main"),
  v.literal("dessert"),
);

// The corresponding type can be used in server or client-side helpers:
export type Course = Infer<typeof courseValidator>;
// is inferred as `'appetizer' | 'main' | 'dessert'`
```

### Document types without system fields[​](#document-types-without-system-fields "Direct link to Document types without system fields")

All documents in Convex include the built-in `_id` and `_creationTime` fields, and so does the generated `Doc` type. When creating or updating a document you might want use the type without the system fields. Convex provides [`WithoutSystemFields`](/api/modules/server.md#withoutsystemfields) for this purpose:

convex/helpers.ts

```
import { MutationCtx } from "./_generated/server";
import { WithoutSystemFields } from "convex/server";
import { Doc } from "./_generated/dataModel";

export async function insertMessageHelper(
  ctx: MutationCtx,
  values: WithoutSystemFields<Doc<"messages">>,
) {
  // ...
  await ctx.db.insert("messages", values);
  // ...
}
```

## Writing frontend code in TypeScript[​](#writing-frontend-code-in-typescript "Direct link to Writing frontend code in TypeScript")

All Convex JavaScript clients, including React hooks like [`useQuery`](/api/modules/react.md#usequery) and [`useMutation`](/api/modules/react.md#usemutation) provide end to end type safety by ensuring that arguments and return values match the corresponding Convex functions declarations. For React, install and configure TypeScript so you can write your React components in `.tsx` files instead of `.jsx` files.

Follow our [React](/quickstart/react.md) or [Next.js](/quickstart/nextjs.md) quickstart to get started with Convex and TypeScript.

### Type annotating client-side code[​](#type-annotating-client-side-code "Direct link to Type annotating client-side code")

When you want to pass the result of calling a function around your client codebase, you can use the generated types `Doc` and `Id`, just like on the backend:

src/App.tsx

```
import { Doc, Id } from "../convex/_generated/dataModel";

function Channel(props: { channelId: Id<"channels"> }) {
  // ...
}

function MessagesView(props: { message: Doc<"messages"> }) {
  // ...
}
```

You can also declare custom types inside your backend codebase which include `Doc`s and `Id`s, and import them in your client-side code.

You can also use `WithoutSystemFields` and any types inferred from validators via `Infer`.

#### Using inferred function return types[​](#using-inferred-function-return-types "Direct link to Using inferred function return types")

Sometimes you might want to annotate a type on the client based on whatever your backend function returns. Beside manually declaring the type (on the backend or on the frontend), you can use the generic `FunctionReturnType` and `UsePaginatedQueryReturnType` types with a function reference:

src/Components.tsx

```
import { FunctionReturnType } from "convex/server";
import { UsePaginatedQueryReturnType } from "convex/react";
import { api } from "../convex/_generated/api";

export function MyHelperComponent(props: {
  data: FunctionReturnType<typeof api.myFunctions.getSomething>;
}) {
  // ...
}

export function MyPaginationHelperComponent(props: {
  paginatedData: UsePaginatedQueryReturnType<
    typeof api.myFunctions.getSomethingPaginated
  >;
}) {
  // ...
}
```

## Turning `string`s into valid document IDs[​](#turning-strings-into-valid-document-ids "Direct link to turning-strings-into-valid-document-ids")

See [Serializing IDs](/database/document-ids.md#serializing-ids).

## Required TypeScript version[​](#required-typescript-version "Direct link to Required TypeScript version")

Convex requires TypeScript version [5.0.3](https://www.npmjs.com/package/typescript/v/5.0.3) or newer.

Related posts from

<!-- -->

[![Stack](/img/stack-logo-dark.svg)![Stack](/img/stack-logo-light.svg)](https://stack.convex.dev/)

---

# Source: https://docs.convex.dev/components/understanding.md

# Source: https://docs.convex.dev/understanding.md

# Convex Overview

Convex is the open source, reactive database where queries are TypeScript code running right in the database. Just like React components react to state changes, Convex queries react to database changes.

Convex provides a database, a place to write your server functions, and client libraries. It makes it easy to build and scale dynamic live-updating apps.

The following diagram shows the standard three-tier app architecture that Convex enables. We'll start at the bottom and work our way up to the top of this diagram.

![Convex in your app](/assets/images/basic-diagram-8ad312f058c3cf7e15c3396e46eedb48.png)

## Database[​](#database "Direct link to Database")

The [database](/database.md) is at the core of Convex. The Convex database is automatically provisioned when you create your project. There is no connection setup or cluster management.

info

In Convex, your database queries are just [TypeScript code](/database/reading-data/.md) written in your [server functions](/functions.md). There is no SQL to write. There are no ORMs needed.

The Convex database is reactive. Whenever any data on which a query depends changes, the query is rerun, and client subscriptions are updated.

Convex is a "document-relational" database. "Document" means you put JSON-like nested objects into your database. "Relational" means you have tables with relations, like `tasks` assigned to a `user` using IDs to reference documents in other tables.

The Convex cloud offering runs on top of Amazon RDS using MySQL as its persistence layer. The Open Source version uses SQLite, Postgres and MySQL. The database is ACID-compliant and uses [serializable isolation and optimistic concurrency control](/database/advanced/occ.md). All that to say, Convex provides the strictest possible transactional guarantees, and you never see inconsistent data.

## Server functions[​](#server-functions "Direct link to Server functions")

When you create a new Convex project, you automatically get a `convex/` folder where you write your [server functions](/functions.md). This is where all your backend application logic and database query code live.

Example TypeScript server functions that read (query) and write (mutation) to the database.

convex/tasks.ts

```
// A Convex query function
export const getAllOpenTasks = query({
  args: {},
  handler: async (ctx, args) => {
    // Query the database to get all items that are not completed
    const tasks = await ctx.db
      .query("tasks")
      .withIndex("by_completed", (q) => q.eq("completed", false))
      .collect();
    return tasks;
  },
});

// A Convex mutation function
export const setTaskCompleted = mutation({
  args: { taskId: v.id("tasks"), completed: v.boolean() },
  handler: async (ctx, { taskId, completed }) => {
    // Update the database using TypeScript
    await ctx.db.patch("tasks", taskId, { completed });
  },
});
```

You read and write to your database through query or mutation functions. [Query functions](/functions/query-functions.md) are pure functions that can only read from the database. [Mutation functions](/functions/mutation-functions.md) are transactions that can read or write from the database. These two database functions are [not allowed to take any non-deterministic](/functions/runtimes.md#restrictions-on-queries-and-mutations) actions like network requests to ensure transactional guarantees.

info

The entire Convex mutation function is a transaction. There are no `begin` or `end` transaction statements to write. Convex automatically retries the function on conflicts, and you don't have to manage anything.

Convex also provides standard general-purpose serverless functions called actions. [Action functions](/functions/actions.md) can make network requests. They have to call query or mutation functions to read and write to the database. You use actions to call LLMs or send emails.

You can also durably schedule Convex functions via the [scheduler](/scheduling/scheduled-functions.md) or [cron jobs](/scheduling/cron-jobs.md). Scheduling lets you build workflows like emailing a new user a day later if they haven't performed an onboarding task.

You call your Convex functions via [client libraries](/client/react.md) or directly via [HTTP](/http-api/.md#functions-api).

## Client libraries[​](#client-libraries "Direct link to Client libraries")

Convex client libraries keep your frontend synced with the results of your server functions.

```
// In your React component
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

export function TaskList() {
  const data = useQuery(api.tasks.getAllOpenTasks);
  return data ?? "Loading...";
}
```

Like the `useState` hook that updates your React component when local state changes, the Convex `useQuery` hook automatically updates your component whenever the result of your query changes. There's no manual subscription management or state synchronization needed.

When calling query functions, the client library subscribes to the results of the function. Convex tracks the dependencies of your query functions, including what data was read from the database. Whenever relevant data in the database changes, the Convex automatically reruns the query and sends the result to the client.

The client library also queues up mutations in memory to send to the server. As mutations execute and cause query results to update, the client library keeps your app state consistent. It updates all subscriptions to the same logical moment in time in the database.

Convex provides client libraries for nearly all popular web and native app frameworks. Client libraries connect to your Convex deployment via WebSockets. You can then call your public Convex functions [through the library](/client/react.md#fetching-data). You can also use Convex with [HTTP directly](/http-api/.md#functions-api), you just won't get the automatic subscriptions.

## Putting it all together[​](#putting-it-all-together "Direct link to Putting it all together")

Let's return to the `getAllOpenTasks` Convex query function from earlier that gets all tasks that are not marked as `completed`:

convex/tasks.ts

```
export const getAllOpenTasks = query({
  args: {},
  handler: async (ctx, args) => {
    // Query the database to get all items that are not completed
    const tasks = await ctx.db
      .query("tasks")
      .withIndex("by_completed", (q) => q.eq("completed", false))
      .collect();
    return tasks;
  },
});
```

Let's follow along what happens when you subscribe to this query:

![Convex data flow](/assets/images/convex-query-subscription-945e7990515e438ab4385f9b4803bbd4.png)

The web app uses the `useQuery` hook to subscribe to this query, and the following happens to get an initial value:

* The Convex client sends a message to the Convex server to subscribe to the query
* The Convex server runs the function, which reads data from the database
* The Convex server sends a message to the client with the function's result

In this case the initial result looks like this (1):

```
[
  { _id: "e4g", title: "Grocery shopping", complete: false },
  { _id: "u9v", title: "Plant new flowers", complete: false },
];
```

Then you use a mutation to mark an item as completed (2). Convex then reruns the query (3) to get an updated result. And pushes the result to the web app via the WebSocket connection (4):

```
[
  { _id: "e4g", title: "Grocery shopping", complete: false },
];
```

## Beyond reactivity[​](#beyond-reactivity "Direct link to Beyond reactivity")

Beyond reactivity, Convex's architecture is crucial for a deeper reason. Convex does not let your app have inconsistent state at any layer of the stack.

To illustrate this, let's imagine you're building a shopping cart for an e-commerce store.

![Convex in your app](/assets/images/convex-swaghaus-dcc9919685db6a7f34378afc500f68cd.png)

On the product listing page, you have two numbers, one showing the number of items remaining in stock and another showing the number of items in your shopping cart. Each number is a result of a different query function.

Every time you press the "Add to Cart" button, a mutation is called to remove one item from the stock and add it to the shopping cart.

The mutation to change the cart runs in a transaction, so your database is always in a consistent state. The reactive database knows that the queries showing the number of items in stock and the number of items in the shopping cart both need to be updated. The queries are invalidated and rerun. The results are pushed to the web app via the WebSocket connection.

The client library makes sure that both queries update at the same time in the web app since they reflect a singular moment in time in your database. You never have a moment where those numbers don't add up. Your app always shows consistent data.

You can see this example in action in the [Swaghaus sample app](https://swaghaus.biz/).

## For human and AI generated code[​](#for-human-and-ai-generated-code "Direct link to For human and AI generated code")

Convex is designed around a small set of composable abstractions with strong guarantees that result in code that is not only faster to write, it’s easier to read and maintain, whether written by a team member or an LLM. Key features make sure you get bug-free AI generated code:

1. **Queries are Just TypeScript** Your database queries are pure TypeScript functions with end-to-end type safety and IDE support. This means AI can generate database code using the large training set of TypeScript code without switching to SQL.
2. **Less Code for the Same Work** Since so much infrastructure and boiler plate is automatically managed by Convex there is less code to write, and thus less code to get wrong.
3. **Automatic Reactivity** The reactive system automatically tracks data dependencies and updates your UI. AI doesn't need to manually manage subscriptions, WebSocket connections, or complex state synchronization—Convex handles all of this automatically.
4. **Transactional Guarantees** Queries are read-only and mutations run in transactions. These constraints make it nearly impossible for AI to write code that could corrupt your data or leave your app in an inconsistent state.

Together, these features mean AI can focus on your business logic while Convex's guarantees prevent common failure modes.

## Learn more[​](#learn-more "Direct link to Learn more")

[YouTube video player](https://www.youtube.com/embed/3d29eKJ2Vws)

If you are intrigued about the details of how Convex pulls this all off, you can read Convex co-founder Sujay's excellent [How Convex Works](https://stack.convex.dev/how-convex-works) blog post.

Now that you have a good sense of how Convex fits in your app. Let's walk through the overall workflow of setting up and launching a Convex app.

---

# Source: https://docs.convex.dev/deployment-api/unpause-deployment.md

# Unpause deployment

```
POST 
/unpause_deployment
```

Reenables a deployment that was previously paused. The deployment will resume normal operation, including any scheduled jobs that were queued while paused.

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/update-canonical-url.md

# Update canonical URL

```
POST 
/update_canonical_url
```

Set or unset the canonical URL for a deployment's convex.cloud or convex.site domain. This allows you to customize the CONVEX\_SITE\_URL and CONVEX\_CLOUD\_URL environment variables in your deployment.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/update-environment-variables.md

# Update environment variables

```
POST 
/update_environment_variables
```

Update one or many environment variables in a deployment. This will invalidate all subscriptions, since environment variables are accessible in queries but are not part of the cache key of a query result.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/deployment-api/update-log-stream.md

# Update log stream

```
POST 
/update_log_stream/:id
```

Update an existing log stream for the deployment. Omit a field to keep the existing value, and use `null` to unset a field.

## Request[​](#request "Direct link to Request")

## Responses[​](#responses "Direct link to Responses")

* 200

---

# Source: https://docs.convex.dev/agents/usage-tracking.md

# Usage Tracking

You can provide a `usageHandler` to the agent to track token usage. See an example in [this demo](https://github.com/get-convex/agent/blob/main/example/convex/usage_tracking/usageHandler.ts) that captures usage to a table, then scans it to generate per-user invoices.

You can provide a `usageHandler` to the agent, per-thread, or per-message.

```
const supportAgent = new Agent(components.agent, {
  ...
  usageHandler: async (ctx, args) => {
    const {
      // Who used the tokens
      userId, threadId, agentName,
      // What LLM was used
      model, provider,
      // How many tokens were used (extra info is available in providerMetadata)
      usage, providerMetadata
    } = args;
    // ... log, save usage to your database, etc.
  },
});
```

Tip: Define the `usageHandler` within a function where you have more variables available to attribute the usage to a different user, team, project, etc.

## Storing usage in a table[​](#storing-usage-in-a-table "Direct link to Storing usage in a table")

To track usage for e.g. billing, you can define a table in your schema and insert usage into it for later processing.

```
export const usageHandler: UsageHandler = async (ctx, args) => {
  if (!args.userId) {
    console.debug("Not tracking usage for anonymous user");
    return;
  }
  await ctx.runMutation(internal.example.insertRawUsage, {
    userId: args.userId,
    agentName: args.agentName,
    model: args.model,
    provider: args.provider,
    usage: args.usage,
    providerMetadata: args.providerMetadata,
  });
};

export const insertRawUsage = internalMutation({
  args: {
    userId: v.string(),
    agentName: v.optional(v.string()),
    model: v.string(),
    provider: v.string(),
    usage: vUsage,
    providerMetadata: v.optional(vProviderMetadata),
  },
  handler: async (ctx, args) => {
    const billingPeriod = getBillingPeriod(Date.now());
    return await ctx.db.insert("rawUsage", {
      ...args,
      billingPeriod,
    });
  },
});

function getBillingPeriod(at: number) {
  const now = new Date(at);
  const startOfMonth = new Date(now.getFullYear(), now.getMonth());
  return startOfMonth.toISOString().split("T")[0];
}
```

With an associated schema in `convex/schema.ts`:

```
export const schema = defineSchema({
  rawUsage: defineTable({
    userId: v.string(),
    agentName: v.optional(v.string()),
    model: v.string(),
    provider: v.string(),

    // stats
    usage: vUsage,
    providerMetadata: v.optional(vProviderMetadata),

    // In this case, we're setting it to the first day of the current month,
    // using UTC time for the month boundaries.
    // You could alternatively store it as a timestamp number.
    // You can then fetch all the usage at the end of the billing period
    // and calculate the total cost.
    billingPeriod: v.string(), // When the usage period ended
  }).index("billingPeriod_userId", ["billingPeriod", "userId"]),

  invoices: defineTable({
    userId: v.string(),
    billingPeriod: v.string(),
    amount: v.number(),
    status: v.union(
      v.literal("pending"),
      v.literal("paid"),
      v.literal("failed"),
    ),
  }).index("billingPeriod_userId", ["billingPeriod", "userId"]),
  // ... other tables
});
```

## Generating invoices via a cron job[​](#generating-invoices-via-a-cron-job "Direct link to Generating invoices via a cron job")

You can use a cron job to generate invoices at the end of the billing period.

See [usage\_tracking/invoicing.ts](https://github.com/get-convex/agent/blob/main/example/convex/usage_tracking/invoicing.ts) for an example of how to generate invoices.

You can then add it to `convex/crons.ts`:

```
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

// Generate invoices for the previous month
crons.monthly(
  "generateInvoices",
  // Wait a day after the new month starts to generate invoices
  { day: 2, hourUTC: 0, minuteUTC: 0 },
  internal.usage.generateInvoices,
  {},
);

export default crons;
```

---

# Source: https://docs.convex.dev/ai/using-cursor.md

# Using Cursor with Convex

[Cursor](https://cursor.com), the AI code editor, makes it easy to write and maintain apps built with Convex. Let's walk through how to setup Cursor for the best possible results with Convex.

## Add Convex `.cursor/rules`[​](#add-convex-cursorrules "Direct link to add-convex-cursorrules")

To get the best results from Cursor put the model specific `.mdc` files in your project's `.cursor/rules` directory.

* [Convex Cursor Rules](https://convex.link/convex_rules.mdc)

[](/video/showing_where_to_put_convex_rules.mp4)

We're constantly working on improving the quality of these rules for Convex by using rigorous evals. You can help by [contributing to our evals repo](https://github.com/get-convex/convex-evals).

## Setup the Convex MCP Server[​](#setup-the-convex-mcp-server "Direct link to Setup the Convex MCP Server")

The Convex CLI comes with a [Convex Model Context Protocol](/ai/convex-mcp-server.md) (MCP) server built in. The Convex MCP server gives your AI coding agent access to the your Convex deployment to query and optimize your project.

### Quick Install[​](#quick-install "Direct link to Quick Install")

You can click this handy deep-link below:

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=convex\&config=eyJjb21tYW5kIjoibnB4IC15IGNvbnZleEBsYXRlc3QgbWNwIHN0YXJ0In0%3D)

### Manual Install[​](#manual-install "Direct link to Manual Install")

To get started with Cursor, open "Cursor Settings > Tools & Integrations", click on "New MCP Server", and add a "convex" section to "mcpServers" in the `mcp.json` file that's opened.

```
{
  "mcpServers": {
    "convex": {
      "command": "npx",
      "args": ["-y", "convex@latest", "mcp", "start"]
    }
  }
}
```

You can also install the Convex MCP [for just one project](https://docs.cursor.com/en/context/mcp#configuration-locations).

After adding the server, ensure the "convex" server is enabled and lit up green (it make take a minute the first time while the NPM package downloads).

Now start asking it questions like:

* Evaluate my convex schema and suggest improvements
* What are this app's public endpoints?
* Run the `my_convex_function` query

## Tips and tricks[​](#tips-and-tricks "Direct link to Tips and tricks")

### Install and run Convex yourself[​](#install-and-run-convex-yourself "Direct link to Install and run Convex yourself")

Keeping Convex running is crucial because [it automatically generates](https://docs.convex.dev/cli#run-the-convex-dev-server) the client-side types. Without this, the agent can get stuck in a linting loop since it can't access the types for the queries and mutations it created.

We recommended that you install (`npm install convex`) and run convex (`npx convex dev`) yourself in a terminal window.

### Keep your requests small[​](#keep-your-requests-small "Direct link to Keep your requests small")

The best results when using agentic LLMs can be found when keeping the amount of changes you want to make small and git commit frequently. This lets you be more specific around the context you provide the agent and it means the agent doesn't need to do a lot of searching for context.

After each successful prompt or series of prompts it is a good idea to commit your changes so that its simple to rollback to that point should the next prompt cause issues.

### Update and reference your `README.md`[​](#update-and-reference-your-readmemd "Direct link to update-and-reference-your-readmemd")

The agent needs context about the specific business goals for your project. While it can infer some details from the files it reads, this becomes more challenging as your project grows. Providing general information about your project gives the agent a helpful head start.

Rather than including this information in each prompt, it's better to write a comprehensive README.md file in your project root and reference it.

[Some people](https://youtu.be/2PjmPU07KNs?t=145) advocate for crafting a Product Requirements Document (PRD), this may be a good idea for more complex projects.

### Add Convex docs[​](#add-convex-docs "Direct link to Add Convex docs")

Adding Convex docs can let you specifically refer to Convex features when building your app.

From **`Cursor Settings`** > **`Indexing & Docs`** > **`Docs`** add new doc, use the URL "<https://docs.convex.dev/home>"

![Chat UI](data:image/webp;base64,UklGRioQAABXRUJQVlA4WAoAAAAIAAAAxwIAtwAAVlA4IEoPAABwWwCdASrIArgAPm02mEkkIyKhIxRoaIANiWlu56AOKacwricHdL8p/RO/Gqz9UWrN5Php/oHqm/7PTz9FHmA/QD9kveJ9AHQ8f+H2QvQA/Y71wvVe/z3SAf//gnfEXX//fvC3wkeoM7vHn1I6jvxr8Lfs/7r5595Pw01Avxz+WeYj67/ke0K0T+w/9b1AvbD6b3nWov7Mfav1f+AD+R/0f/nepX+R8Ab6r/l/2I+AD+X/27/0f4P3Qv5n/0/5/zX/nv+L/83+e+AP+X/2X9gvaw9eP7n+zj+8Afklr8gKqLtmQisC1+QFVF2zIRV9WhjAK7YRWBa/ICqi7ZkIrAtfkBVRdsx+cx03GIhBEn33Vs7nGk++6tnc40n33Vs7nGbeqErGPkYVUXbMhFYFr8gKqLtmQisC1+Jj4KrtkwzBk/3QQcSfJ2jkJFGWNALX5AVUXbMhFYFr8gHfHreowkztt6086WygVFHMh3zVobE9AH+RJHY5/5hi9sSeUu0Jhoe55xtv//kpCmf/+GfB/WHwCqi7ZkIrAtfkBVRdrYmrMnuf1OsbdEi4YimtTsnPK6AYtohUktI5EiU0X68G1PIb+oNmxm/acSbAdpOKfLhKN3P/vnCfdYEsrDpDw7aPGDCYV9D1UyRtpYx9fN3kO9R9UcqQR9u8kpeteWqZCKwLX5AVUVoIhrjLj6Z05p7mYw/nkaktYxh/IWs07xV/sIz2RY90DCqi7ZkIrAtfri1SNUpiP0PtBZKWD9UAXP89HPOtGvs8GpnmXEJzIu/aOMGmoYQbrNKAkEavpaYYUN2B7Rj1bADOzKJSs16ECkP/rn3aNDJnHbVMW04Qq9QCXqS8qudJfaBwZlLlK69R4N6SAWvyAqou2ZB7siKtMh0QC1+QFVF2zIRWBa/ICqi6Rqku/hLAX31UpIk++6tnc40n33Vs7nGk++6tkTlsehkrZgwqou2ZCKwLX5AVUXbMhFYFrb4uAAD+/6XVIiHfE26tm6tm6tmAAt9pCZYWPxBtiMPM+ZXAkCvAC0yZhTgq5cxNTZSAB5XrwUAADAiMROKuXyhL+YTGHHTZgV88/bFAoaemKxBxlaHlwXLu3ltF7lIUE9sIlX5pEqC+2LeSXVktHV8ru6ioG4TAj2XMxps/rpGFSkU+YiM4fbB+tq+wpdDeqmMAbJm3oq+Q6iP9QkU24SfpuKnXIpZKO9bv/dI/VaV3yg0G7l1cocZ6FacPqXrMiZv1Vb3T7vCFk/ATtoL2xbPIgR9sYBBLl5gwX6AGudbsevWLFTQ3PtblZrFmBZMrQS0v4HJRTLe3nRYGFet5BVh8OSWpHxzpjeBmSeB5tLeTuKLTD7Ev1+sz+e3qjlWb247YMLHnrdwuRbfdtzoRI28kO1bB1kfT6FL5SR62dQ4OCLUpzMwGPhq/ExiIo6yixqI12WnDA9P6Poymr7fQSiYq4aDu2O+Rk34MJScxpfrdpLtJ4maPIjXwwkcTV7/L9EbjlLH1SYycrUgRxtvT+KDnFPFXo7ZoRairxaBBSpPc8yjf6pB50c+u17QWll27Ue4zFPAwad78g8tXBucLj77Lp9kMWWrjelHc6ZlIjm5FLHKaMOiMMSp+s/AlGKq2sjJ87QXf5KbJUAeE9VqHTq+PY/1yZig7BRyh/7hCdO51pLRHveWWdAb5vjmZslkR3VFNJ5TrrbDiLDEi6fjcAKhb9Yrj+judlnfbImM9BSqsh4Su3vfyJ2X1ezwj93lKWj095iM0sm5DrNoLsDcbQE7WQrG7D0+6WX1juPOVAmmdd0tDzCeq6+wU7RKhL5Mz1FwWtX2JH//72Wa1BU0uOKYyX8S9hu8C/GUfX//lk8cLaGabEQFkfoqDXUj86LZiysSR8HynYEQ3fVujz9EEW+X5anJGSZ6Xf5jTLxYRtgdezBBakaUNJwvdLHr74wNh6m7x1JlPCd4IFHUKWj4NdM9T0ZDbcRMBGSUfwrDKgaTcCBi4TboEpK2rrex464sl4IFuMUGAJgzCKpIvNNhDPoqNkHFM7jsyoxs+PssHvY9zyskcqp76Ldo9FpBpIXfP/AfMpveODyigBCFPjQ3L4utbccgdZup+P7royBeiDzynez9/I5XT7jf392hj4rby74bwTlDFL3X9e+DHOOcnC6/YlCSPkmtbAbuLNOujJRPX3SPuwVehYAA6yPs8Xn36xZg9358IjJTbNo+rpGKNslUq1qFHdW0sZB18Ajy9bu6/69UFVI4Q6MDwv0FLXhWfqac98myRlU70iv7difZ0ZNgUz2+/lo2Spg8zIivJcthciJi7qFJE/EdhuN8ki0TqogaP0UKXDeA7iswSmX7wWfUdzX/SxUCrmOY9vl+pAPvY7EcnEwRJCGvzm7yzddbsMDI6BJH9D/LDZhAcCDs0Qayy0kSyE8oS6MXXEV5w1sJxJuwQVj6tM/qMqSo6H9Lwh9LJxN+p7BQPa1fABsq6uI6YPlsb209di84INwHrBRGTOmPVQAPKPppuIEoVKtsw1ksyb+9Tdk8ZzoJZZiuAt4Yo/BlCyp707Z3XHpXcrLCDjhJgDGporrb2C9dPTK+H+OW85rgt0OTaUkzX2ROl71I3uijFUGVtDTMvfAI97luMg27SurpFVNfJNkicb5ilFLunAConZZah3BUEPK3AbQtG+29PmRk3t7bNGIKr0p/K37XBfVGZ4a7dPQfEQ1sQlsPeYFyTyNQ/G04O/DhDP3r2z2ACyRNjeczUpPwE7U6z/9YkSiJl1CDhJsBA8JT7p4p1wpw5OoBfcgphbY8UIbS7wS+JNrktIUA+J3PcwFjIg1PNG8E4j7Lu3BXYGyc8L86EuIiA4RVajze1G6I7BVM4r81mz9SaSkJsbbfEg8tsrUfLxp2mm96a4+5+EfwJ+MZEeG2Sgjok/LkkdR3xrBgt5+H17chTnfNhCvOVCC3GTOwl6CD61jgH5pXDy0u9w7kg126N/Dsiw6zJz7MNhH/vI2QrGTZSyxKXB1fdYtReFWTUHsgsR5IETm89n44TN9kcHlHVJxZCjQwa7Q80aAwUnk/QZdvFJh5e2zzIOFgCGoS7tMWVzdrczSTjgzbsLmIck7CCZapSyqOL/C1II15IfuQ8VW3gV3M1cVXuQkHCWb386hzSQDBSwGJbJdjDKn6CbOqHYvhnFWFEo+Wfy/o1TZsD30oC2iiv6TwU+zIzzwHlM538/WOQPbEvS4/rIcANXPa/48/SiWuOlEsBvYK2Rr7J+/mhIYvHfLanjf3kIZSgqoQPgq+CfCzVMwQ8a1dOdPzdhPmWJ+W5tLgQ1lzXi1cViWRMXT/IC5ueLFYvdNhUSBkpbafrRISoFHvDVSG+tr5RBbbxA3tGDq1aryYE+xEAavFx7VQnrKEl1Kp5znBJy0d9IUu0ONWvvNHPzrsyMeid/Rf1pkXq6AJM88223NUjZZsLxJr/+NyEqg1orzbIbUo6k5uSha3/uEzqrmFJ2ahspFHSQrM17EAnG/25COrPFbWK+/p3wlJfo2MPVbuwYi/f8OQUmGo6sCmm53RDAZxOEPWLU076v7bG6fkstbEpzPZc/uPZNKPrBZ34OxaC/2whiyTWHpq0J2E2yUq5jA4MQFyo7f+4kGA7B1mGwP8UVGJO39Jz8ClFAAAABekHtleniGp8UH9sn7KEwPCcAAAA6sn1hmHO3PeA1s6r5cz4C1IQY4zfazA6PJLmeoWkQKUgAGEKt0D7uBruTMrmMk6pTJpkCTFT4P8+AmSuLnFCN0pFTyQ2AkS1Lr+zTHy9wWSx4YNobr9FvkIh7t/Dz6bPdZ0Mjm6ciodWiTO2muI3wN9HO3igaNTRXZAJAUXuYq7BbIHgBfTCvZnNNDZ1mMeIQzQm9tiEdrRbeg+zIRshCk5grIbRb1OUHgboo3gBRWS6EKYJEDOFYCWGjWprISrCmYydKB2fjbWM+Nj3i9vyHlse/FDj/6DlZWktNqRRSFW2071ExQKzBtXQSVJNsZ9zCcEwlQCmP1p16MB9NSv7WezLLkmVY4ILtVIRyFj52n4LmJK9+8Id1+GllESQNBY1FlxFHzvpSe5Tvq9d0j3mg/nKthAdtedk/lTtR1fK0uZBe4k1L6Uy7T8eIJuuuEgUyYIoCeUR12Oxxha13sY/qFpZILh4YWsfzfLs6PUpOmWnmLB1Kb2kQIxU5PpRlqVKX4hrZWV1SlDO8kAb8VQMhm2Y+fKxWWlIaMElnAEvmpFChnC4Cf2BOb5gA6UHb+pEH0JErS/V0sFMBKApqZQWtn1pMGGT89A1I9+7CFLVJSI6ST8pSCK3PsR+LCMkypcgkI3lw45G5P4DxruhP5QdDpAI726Tcf27sIQirtTgOUm8Wi+3S9dNOTd4I5jE7y9IMwClAzDZu08UhCAWIgIrX0sjXN23uYsL/LG5MexaRwdIgoZoBWfL30QrvVeVJeYJynjg5kRbWnAZ1AUNRXTBYjE4iyrghlC+M+4qvpguo7yS9odJjECMwIUB2otY0epHAjBbUIjspcEzaSiTcKbiVbjc7X5K7uicFJGHjYgbx6eDDfbnSV72LXuaNtoGWpDxgi9hAWjHMvT4qbr0BZRWcP9K/niJDT6JNtWw+iCTqP3SyLdzwOqqctIz+d5nptTJZGNSM/R2RFT04feG+Eoipi27DXekBdT+xuI5fFEGx/OA1R+OFaKW8g6qFLiBwQrdpEksEA++T2Q0TMaTQ+dvyrSilUYaHDjWczc88eD/M4hpXBLYa6y4GkcmPmNBr2KTkoeE/AqE4GO5kw7e9VCrWn6fLrAAt4ZRSk1St3oP/X+QyENCNHf0I0cAia/dkWTgMV00Cnl9UNkqqiNbK0lF4dYpmaLo6YQxifAiObMjq8J4bZ/EDzXxAxVn+0rKhZewee6rn+Fywe4IjccVWdgGBV6mDEIDZurmU25N/lDq0pSQxz3pLiAsnhIei5dL5A9GeNq9zpZTU1C5Z3eyN3IVFjJFve2Q9BmlmwUmb3iJ+aDCxt38Fj3Q3N/NFvWzwisqGNNeE0ZeGaQNhC0VeIO3GiYImZUav0hu5zyzSC5MBgUlgxOpIt7mkQe4mRfZbdEdUQjxOkn5jPOAJGYaa7kiaMEa+7iTms9nJkUP0NNqd+7MBSL3R/z3lB7LNHiWNxSnh17JaQeXXvlG+B0XbGSKjrCleT7wn6EE1Hag0G5+lJIAAF7dn8Hyv8ABaAA8jdFi4AAAAEVYSUa6AAAARXhpZgAASUkqAAgAAAAGABIBAwABAAAAAQAAABoBBQABAAAAVgAAABsBBQABAAAAXgAAACgBAwABAAAAAgAAABMCAwABAAAAAQAAAGmHBAABAAAAZgAAAAAAAABIAAAAAQAAAEgAAAABAAAABgAAkAcABAAAADAyMTABkQcABAAAAAECAwAAoAcABAAAADAxMDABoAMAAQAAAP//AAACoAQAAQAAAMgCAAADoAQAAQAAALgAAAAAAAAA)

Cursor will then index all of the Convex docs for the LLM to use.

![Chat UI](/assets/images/indexed_docs-90bb59330756c00540015c53da6a484c.webp)

You can then reference those docs in your prompt with the `@Convex` symbol.

![Chat UI](/assets/images/reference_convex_docs-c791c41ddbd7663244fda1c4c59a43d9.webp)

Add more Convex knowledge

You can perform the above steps for <https://stack.convex.dev/> too if you would like to provide even more context to the agent.

---

# Source: https://docs.convex.dev/ai/using-github-copilot.md

# Using GitHub Copilot with Convex

[GitHub Copilot](https://github.com/features/copilot), the AI built into VS Code, makes it easy to write and maintain apps built with Convex. Let's walk through how to setup GitHub Copilot for the best possible results with Convex.

## Add Convex Instructions[​](#add-convex-instructions "Direct link to Add Convex Instructions")

Add the following [instructions](https://code.visualstudio.com/docs/copilot/copilot-customization#_instruction-files) file to your `.github/instructions` directory in your project and it will automatically be included when working with TypeScript or JavaScript files:

* [convex.instructions.md](https://convex.link/convex_github_copilot_instructions)

![Showing Where to Put GitHub Copilot Instructions](/assets/images/showing-where-to-put-convex-instructions-1d22c1b802b42443b4808e0dd27f0746.png)

If you would rather that the instructions file is NOT automatically pulled into context then open the file in your editor and alter the `applyTo` field at the top. Read more about instructions files here: <https://code.visualstudio.com/docs/copilot/copilot-customization#_use-instructionsmd-files>

We're constantly working on improving the quality of these rules for Convex by using rigorous evals. You can help by [contributing to our evals repo](https://github.com/get-convex/convex-evals).

## Setup the Convex MCP Server[​](#setup-the-convex-mcp-server "Direct link to Setup the Convex MCP Server")

The Convex CLI comes with a [Convex Model Context Protocol](/ai/convex-mcp-server.md) (MCP) server built in. The Convex MCP server gives your AI coding agent access to the your Convex deployment to query and optimize your project.

To get started with [MCP in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) then create a file in `.vscode/mcp.json` and add the following:

```
{
  "servers": {
    "convex-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "convex@latest", "mcp", "start"]
    }
  }
}
```

Once this is done it will take a few seconds to start up the MCP server and then you should see the Convex tool listed in the codelens:

![Convex Tool in Codelens](/assets/images/convex-tool-in-codelens-0cf36ed79938643797e93dd08ef3565c.png)

and in the selection of tools that the model has access to in chat:

![Convex Tool in Chat](/assets/images/convex-tools-in-chat-eef97848e328479e7e1b06452b7934ea.png)

Now start asking it questions like:

* Evaluate and convex schema and suggest improvements
* What are this app's public endpoints?
* Run the `my_convex_function` query

If you want to use the MCP server globally for all your projects then you can add it to your user settings, please see these docs for more information: <https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-user-settings>

---

# Source: https://docs.convex.dev/ai/using-windsurf.md

# Using Windsurf with Convex

[Windsurf](https://codeium.com/windsurf), the AI code editor, makes it easy to write and maintain apps built with Convex. Let's walk through how to setup Windsurf for the best possible results with Convex.

## Add Convex Rules[​](#add-convex-rules "Direct link to Add Convex Rules")

Add the following rules file to your project and refer to it directly when prompting for changes:

* [Convex Rules](https://convex.link/convex_rules.txt)

We're constantly working on improving the quality of these rules for Convex by using rigorous evals. You can help by [contributing to our evals repo](https://github.com/get-convex/convex-evals).

## Setup the Convex MCP Server[​](#setup-the-convex-mcp-server "Direct link to Setup the Convex MCP Server")

The Convex CLI comes with a [Convex Model Context Protocol](/ai/convex-mcp-server.md) (MCP) server built in. The Convex MCP server gives your AI coding agent access to the your Convex deployment to query and optimize your project.

To get started with Windsurf, open "Windsurf Settings > Cascade > Model Context Protocol (MCP) Servers", click on "Add Server", click "Add custom server", and add the following configuration for Convex.

```
{
  "mcpServers": {
    "convex": {
      "command": "npx",
      "args": ["-y", "convex@latest", "mcp", "start"]
    }
  }
}
```

After adding the server return to the "Windsurf Settings > Cascade > Model Context Protocol (MCP) Servers" screen an click "Refresh" button for Windsurf to pick up the new server.

Once this is done you should see the Convex tool listed in the servers:

![Chat UI](/assets/images/windsurf_convex_mcp-ed91858fc5df64ae0b900f95b69ae2ad.png)

Now start asking it questions like:

* Evaluate and convex schema and suggest improvements
* What are this app's public endpoints?
* Run the `my_convex_function` query

---

# Source: https://docs.convex.dev/components/using.md

# Using Components

Convex Components add new features to your backend in their own sandbox with their own functions, schema and data, scheduled functions and all other fundamental Convex features.

You can see the full list of components in the [directory](https://convex.dev/components).

## Installation[​](#installation "Direct link to Installation")

We'll use the [Agent](https://www.npmjs.com/package/@convex-dev/agent) component as an example.

1. Install from \`npm\`

   ```
   npm i @convex-dev/agent
   ```

2. Add the component to your app

   Create or update the `convex.config.ts` file in your app's `convex/` folder and install the component by calling `use`. Multiple instances of the same component can be installed by calling `use` multiple times with different names. Each will have their own tables and functions.

   convex/convex.config.ts

   TS

   ```
   import { defineApp } from "convex/server";
   import agent from "@convex-dev/agent/convex.config.js";

   const app = defineApp();

   app.use(agent);
   app.use(agent, { name: "agent2" });
   //... Add other components here

   export default app;
   ```

3. Run convex dev

   The `convex dev` CLI command will generate code necessary for using the component.

   ```
   npx convex dev
   ```

4. Access the component through its API

   Each instance of a component has its API listed under the `components` object by its name. Some components wrap this API with classes or functions. Check out each component's documentation for more details on its usage.

   ```
   import { components } from "./_generated/api.js";

   const agent = new Agent(components.agent, { ... });
   ```

## Using the component's API directly[​](#using-the-components-api-directly "Direct link to Using the component's API directly")

Though components may expose higher level TypeScript APIs, under the hood they are called via normal Convex functions over the component sandbox boundary.

Queries, mutations, and action rules still apply - queries can only call component queries, mutations can also call component mutations, and actions can also call component actions. As a result, queries into components are reactive by default, and mutations have the same transaction guarantees.

Component functions can be called from your application using the following syntax:

```
import { internalAction } from "./_generated/server";
import { components } from "./_generated/api";

export const myAction = internalAction({
  args: { threadId: v.string() },
  handler: async (ctx, args) => {
    // Call the component's API to get the thread status.
    const { status } = await ctx.runQuery(components.agent.threads.getThread, {
      threadId: args.threadId,
    });
    //...
  },
});
```

Some components abstract away the component's API. For instance, the `Agent` class from `@convex-dev/agent` is initialized with `components.agent`, and its methods take in `ctx` so they can call the component's API internally. [Learn more about the Agent Component here](/agents.md).

## Transactions[​](#transactions "Direct link to Transactions")

Remember that mutation functions in Convex are [transactions](/functions/mutation-functions.md#transactions). Either all the changes in the mutation get written at once or none are written at all.

All writes for a top-level mutation call, including writes performed by calls into other components' mutations, are committed at the same time. If the top-level mutation throws an error, all of the writes are rolled back, and the mutation doesn't change the database at all.

However, if a component mutation call throws an exception, only its writes are rolled back. Then, if the caller catches the exception, it can continue, perform more writes, and return successfully. If the caller doesn't catch the exception, then it's treated as failed and all the writes associated with the caller mutation are rolled back. This means your code can choose a different code path depending on the semantics of your component.

As an example, take the [Rate Limiter](https://www.npmjs.com/package/@convex-dev/ratelimiter) component. One API of the Rate Limiter throws an error if a rate limit is hit:

```
// Automatically throw an error if the rate limit is hit.
await rateLimiter.limit(ctx, "failedLogins", { key: userId, throws: true });
```

If the call to `rateLimiter.limit` throws an exception, we're over the rate limit. Then, if the calling mutation doesn't catch this exception, the whole transaction is rolled back.

The calling mutation, on the other hand, could also decide to ignore the rate limit by catching the exception and proceeding. For example, an app may want to ignore rate limits if there is a development environment override. In this case, only the component mutation will be rolled back, and the rest of the mutation will continue.

## Dashboard[​](#dashboard "Direct link to Dashboard")

You can see your component’s data, functions, files, logs, and other info using the dropdown in the Dashboard. You can also use the dropdown to exclude info from certain components.

![Screenshot of the component dropdown](/screenshots/component_dropdown.png)

## Testing components[​](#testing-components "Direct link to Testing components")

When writing tests with [`convex-test`](/testing/convex-test.md), that use components, you must register the component with the test instance. This tells it what schema to validate and where to find the component source code. Most components export convenient helper functions on `/test` to make this easy:

convex/some.test.ts

TS

```
import agentTest from "@convex-dev/agent/test";
import { expect, test } from "vitest";
import { convexTest } from "convex-test";
import { components } from "./_generated/api";
import { createThread } from "@convex-dev/agent";

// Define this once, often in a shared test helper file.
export function initConvexTest() {
  const t = convexTest();
  agentTest.register(t);
  return t;
}

test("Agent createThread", async () => {
  const t = initConvexTest();

  const threadId = await t.run(async (ctx) => {
    // Calling functions that use ctx and components.agent
    return await createThread(ctx, components.agent, {
      title: "Hello, world!",
    });
  });
  // Calling functions directly on the component's API
  const thread = await t.query(components.agent.threads.getThread, {
    threadId,
  });
  expect(thread).toMatchObject({
    title: "Hello, world!",
  });
});
```

If you need to register the component yourself, you can do so by passing the component's schema and modules to the test instance.

convex/manual.test.ts

TS

```
/// <reference types="vite/client" />
import { test } from "vitest";
import { convexTest } from "convex-test";
import schema from "./path/to/component/schema.ts";
const modules = import.meta.glob("./path/to/component/**/*.ts");

test("Test something with a local component", async () => {
  const t = convexTest();
  t.registerComponent("componentName", schema, modules);

  await t.run(async (ctx) => {
    await ctx.runQuery(components.componentName.someQuery, {
      arg: "value",
    });
  });
});
```

## Log Streams[​](#log-streams "Direct link to Log Streams")

You can use the `data.function.component_path` field in [log streams](/production/integrations/log-streams/.md) to separate log lines based on the component they came from.

---

# Source: https://docs.convex.dev/functions/validation.md

# Argument and Return Value Validation

Argument and return value validators ensure that [queries](/functions/query-functions.md), [mutations](/functions/mutation-functions.md), and [actions](/functions/actions.md) are called with the correct types of arguments and return the expected types of return values.

**This is important for security!** Without argument validation, a malicious user can call your public functions with unexpected arguments and cause surprising results. [TypeScript](/understanding/best-practices/typescript.md) alone won't help because TypeScript types aren't present at runtime. We recommend adding argument validation for all public functions in production apps. For non-public functions that are not called by clients, we recommend [internal functions](/functions/internal-functions.md) and optionally validation.

**Example:** [Argument Validation](https://github.com/get-convex/convex-demos/tree/main/args-validation)

## Adding validators[​](#adding-validators "Direct link to Adding validators")

To add argument validation to your functions, pass an object with `args` and `handler` properties to the `query`, `mutation` or `action` constructor. To add return value validation, use the `returns` property in this object:

convex/message.ts

TS

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

export const send = mutation({
  args: {
    body: v.string(),
    author: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const { body, author } = args;
    await ctx.db.insert("messages", { body, author });
  },
});
```

If you define your function with an argument validator, there is no need to include [TypeScript](/understanding/best-practices/typescript.md) type annotations! The type of your function will be inferred automatically. Similarly, if you define a return value validator, the return type of your function will be inferred from the validator, and TypeScript will check that it matches the inferred return type of the `handler` function.

Unlike TypeScript, validation for an object will throw if the object contains properties that are not declared in the validator.

If the client supplies arguments not declared in `args`, or if the function returns a value that does not match the validator declared in `returns`. This is helpful to prevent bugs caused by mistyped names of arguments or returning more data than intended to a client.

Even `args: {}` is a helpful use of validators because TypeScript will show an error on the client if you try to pass any arguments to the function which doesn't expect them.

## Supported types[​](#supported-types "Direct link to Supported types")

All functions, both public and internal, can accept and return the following data types. Each type has a corresponding validator that can be accessed on the [`v`](/api/modules/values.md#v) object imported from `"convex/values"`.

The [database](/database.md) can store the exact same set of [data types](/database/types.md).

Additionally you can also express type unions, literals, `any` types, and optional fields.

### Convex values[​](#convex-values "Direct link to Convex values")

Convex supports the following types of values:

| Convex Type | TS/JS Type                                                                                                                      | Example Usage          | Validator for [Argument Validation](/functions/validation.md) and [Schemas](/database/schemas.md) | `json` Format for [Export](/database/import-export/.md) | Notes                                                                                                                                                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Id          | [Id](/database/document-ids.md) ([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)) | `doc._id`              | `v.id(tableName)`                                                                                 | string                                                  | See [Document IDs](/database/document-ids.md).                                                                                                                                                                                                                                                                                                         |
| Null        | [null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type)                                       | `null`                 | `v.null()`                                                                                        | null                                                    | JavaScript's `undefined` is not a valid Convex value. Functions the return `undefined` or do not return will return `null` when called from a client. Use `null` instead.                                                                                                                                                                              |
| Int64       | [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type)                                   | `3n`                   | `v.int64()`                                                                                       | string (base10)                                         | Int64s only support BigInts between -2^63 and 2^63-1. Convex supports `bigint`s in [most modern browsers](https://caniuse.com/bigint).                                                                                                                                                                                                                 |
| Float64     | [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)                                   | `3.1`                  | `v.number()`                                                                                      | number / string                                         | Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings.                                                                                                                                                                                                                       |
| Boolean     | [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)                                 | `true`                 | `v.boolean()`                                                                                     | bool                                                    |                                                                                                                                                                                                                                                                                                                                                        |
| String      | [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)                                   | `"abc"`                | `v.string()`                                                                                      | string                                                  | Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.                                                                                                                                                                                                          |
| Bytes       | [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                     | `new ArrayBuffer(8)`   | `v.bytes()`                                                                                       | string (base64)                                         | Convex supports first class bytestrings, passed in as `ArrayBuffer`s. Bytestrings must be smaller than the 1MB total size limit for Convex types.                                                                                                                                                                                                      |
| Array       | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                 | `[1, 3.2, "abc"]`      | `v.array(values)`                                                                                 | array                                                   | Arrays can have at most 8192 values.                                                                                                                                                                                                                                                                                                                   |
| Object      | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)                                       | `{a: "abc"}`           | `v.object({property: value})`                                                                     | object                                                  | Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Convex includes all [enumerable properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "\_". |
| Record      | [Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)                                       | `{"a": "1", "b": "2"}` | `v.record(keys, values)`                                                                          | object                                                  | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "\_".                                                                                                                                                                                                               |

### Unions[​](#unions "Direct link to Unions")

You can describe fields that could be one of multiple types using `v.union`:

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

export default mutation({
  args: {
    stringOrNull: v.union(v.string(), v.null()),
  },
  handler: async (ctx, { stringOrNull }) => {
    //...
  },
});
```

For convenience, `v.nullable(foo)` is equivalent to `v.union(foo, v.null())`.

### Literals[​](#literals "Direct link to Literals")

Fields that are a constant can be expressed with `v.literal`. This is especially useful when combined with unions:

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

export default mutation({
  args: {
    oneTwoOrThree: v.union(
      v.literal("one"),
      v.literal("two"),
      v.literal("three"),
    ),
  },
  handler: async (ctx, { oneTwoOrThree }) => {
    //...
  },
});
```

### Record objects[​](#record-objects "Direct link to Record objects")

You can describe objects that map arbitrary keys to values with `v.record`:

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

export default mutation({
  args: {
    simpleMapping: v.record(v.string(), v.boolean()),
  },
  handler: async (ctx, { simpleMapping }) => {
    //...
  },
});
```

You can use other types of string validators for the keys:

```
defineTable({
  userIdToValue: v.record(v.id("users"), v.boolean()),
});
```

Notes:

* This type corresponds to the [Record\<K,V>](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) type in TypeScript.
* You cannot use string literals as a `record` key.
* Using `v.string()` as a `record` key validator will only allow ASCII characters.

### Any[​](#any "Direct link to Any")

Fields that could take on any value can be represented with `v.any()`:

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

export default mutation({
  args: {
    anyValue: v.any(),
  },
  handler: async (ctx, { anyValue }) => {
    //...
  },
});
```

This corresponds to the `any` type in TypeScript.

### Optional fields[​](#optional-fields "Direct link to Optional fields")

You can describe optional fields by wrapping their type with `v.optional(...)`:

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

export default mutation({
  args: {
    optionalString: v.optional(v.string()),
    optionalNumber: v.optional(v.number()),
  },
  handler: async (ctx, { optionalString, optionalNumber }) => {
    //...
  },
});
```

This corresponds to marking fields as optional with `?` in TypeScript.

## Extracting TypeScript types[​](#extracting-typescript-types "Direct link to Extracting TypeScript types")

The [`Infer`](/api/modules/values.md#infer) type allows you to turn validator calls into TypeScript types. This can be useful to remove duplication between your validators and TypeScript types:

```
import { mutation } from "./_generated/server";
import { Infer, v } from "convex/values";

const nestedObject = v.object({
  property: v.string(),
});

// Resolves to `{property: string}`.
export type NestedObject = Infer<typeof nestedObject>;

export default mutation({
  args: {
    nested: nestedObject,
  },
  handler: async (ctx, { nested }) => {
    //...
  },
});
```

### Reusing and extending validators[​](#reusing-and-extending-validators "Direct link to Reusing and extending validators")

Validators can be defined once and shared between functions and table schemas.

```
const statusValidator = v.union(v.literal("active"), v.literal("inactive"));

const userValidator = v.object({
  name: v.string(),
  email: v.email(),
  status: statusValidator,
  profileUrl: v.optional(v.string()),
});

const schema = defineSchema({
  users: defineTable(userValidator).index("by_email", ["email"]),
});
```

You can create new object validators from existing ones by adding or removing fields using `.pick`, `.omit`, `.extend`, and `.partial` on object validators.

```
// Creates a new validator with only the name and profileUrl fields.
const publicUser = userValidator.pick("name", "profileUrl");

// Creates a new validator with all fields except the specified fields.
const userWithoutStatus = userValidator.omit("status", "profileUrl");

// Creates a validator where all fields are optional.
// This is useful for validating patches to a document.
const userPatch = userWithoutStatus.partial();

// Creates a new validator adding system fields to the user validator.
const userDocument = userValidator.extend({
  _id: v.id("users"),
  _creationTime: v.number(),
});
```

Notes:

* Object validators don't allow extra properties, objects with properties that aren't specified will fail validation.
* Top-level table fields cannot start with `_` because they are reserved for system fields like `_id` and `_creationTime`.

---

# Source: https://docs.convex.dev/api/namespaces/values.Base64.md

# Namespace: Base64

[values](/api/modules/values.md).Base64

## Functions[​](#functions "Direct link to Functions")

### byteLength[​](#bytelength "Direct link to byteLength")

▸ **byteLength**(`b64`): `number`

#### Parameters[​](#parameters "Direct link to Parameters")

| Name  | Type     |
| ----- | -------- |
| `b64` | `string` |

#### Returns[​](#returns "Direct link to Returns")

`number`

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/base64.ts:44](https://github.com/get-convex/convex-js/blob/main/src/values/base64.ts#L44)

***

### toByteArray[​](#tobytearray "Direct link to toByteArray")

▸ **toByteArray**(`b64`): `Uint8Array`

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name  | Type     |
| ----- | -------- |
| `b64` | `string` |

#### Returns[​](#returns-1 "Direct link to Returns")

`Uint8Array`

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/base64.ts:56](https://github.com/get-convex/convex-js/blob/main/src/values/base64.ts#L56)

***

### fromByteArray[​](#frombytearray "Direct link to fromByteArray")

▸ **fromByteArray**(`uint8`): `string`

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type         |
| ------- | ------------ |
| `uint8` | `Uint8Array` |

#### Returns[​](#returns-2 "Direct link to Returns")

`string`

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/base64.ts:123](https://github.com/get-convex/convex-js/blob/main/src/values/base64.ts#L123)

***

### fromByteArrayUrlSafeNoPadding[​](#frombytearrayurlsafenopadding "Direct link to fromByteArrayUrlSafeNoPadding")

▸ **fromByteArrayUrlSafeNoPadding**(`uint8`): `string`

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name    | Type         |
| ------- | ------------ |
| `uint8` | `Uint8Array` |

#### Returns[​](#returns-3 "Direct link to Returns")

`string`

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/base64.ts:158](https://github.com/get-convex/convex-js/blob/main/src/values/base64.ts#L158)

---

# Source: https://docs.convex.dev/api/classes/values.ConvexError.md

# Class: ConvexError\<TData>

[values](/api/modules/values.md).ConvexError

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name    | Type                                            |
| ------- | ----------------------------------------------- |
| `TData` | extends [`Value`](/api/modules/values.md#value) |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `Error`

  ↳ **`ConvexError`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new ConvexError**<`TData`>(`data`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name    | Type                                            |
| ------- | ----------------------------------------------- |
| `TData` | extends [`Value`](/api/modules/values.md#value) |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name   | Type    |
| ------ | ------- |
| `data` | `TData` |

#### Overrides[​](#overrides "Direct link to Overrides")

Error.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/errors.ts:10](https://github.com/get-convex/convex-js/blob/main/src/values/errors.ts#L10)

## Properties[​](#properties "Direct link to Properties")

### stackTraceLimit[​](#stacktracelimit "Direct link to stackTraceLimit")

▪ `Static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

Error.stackTraceLimit

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/@types+node\@18.19.130/node\_modules/@types/node/globals.d.ts:68

***

### cause[​](#cause "Direct link to cause")

• `Optional` **cause**: `unknown`

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

Error.cause

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es2022.error.d.ts:24

***

### message[​](#message "Direct link to message")

• **message**: `string`

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

Error.message

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es5.d.ts:1055

***

### stack[​](#stack "Direct link to stack")

• `Optional` **stack**: `string`

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

Error.stack

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/typescript\@5.0.4/node\_modules/typescript/lib/lib.es5.d.ts:1056

***

### name[​](#name "Direct link to name")

• **name**: `string` = `"ConvexError"`

#### Overrides[​](#overrides-1 "Direct link to Overrides")

Error.name

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/errors.ts:6](https://github.com/get-convex/convex-js/blob/main/src/values/errors.ts#L6)

***

### data[​](#data "Direct link to data")

• **data**: `TData`

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/errors.ts:7](https://github.com/get-convex/convex-js/blob/main/src/values/errors.ts#L7)

***

### \[IDENTIFYING\_FIELD][​](#identifying_field "Direct link to \[IDENTIFYING_FIELD]")

• **\[IDENTIFYING\_FIELD]**: `boolean` = `true`

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[values/errors.ts:8](https://github.com/get-convex/convex-js/blob/main/src/values/errors.ts#L8)

## Methods[​](#methods "Direct link to Methods")

### captureStackTrace[​](#capturestacktrace "Direct link to captureStackTrace")

▸ `Static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns a string representing the location in the code at which `Error.captureStackTrace()` was called.

```
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with `${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames above `constructorOpt`, including `constructorOpt`, will be omitted from the generated stack trace.

The `constructorOpt` argument is useful for hiding implementation details of error generation from the user. For instance:

```
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name              | Type       |
| ----------------- | ---------- |
| `targetObject`    | `object`   |
| `constructorOpt?` | `Function` |

#### Returns[​](#returns "Direct link to Returns")

`void`

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

Error.captureStackTrace

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/@types+node\@18.19.130/node\_modules/@types/node/globals.d.ts:52

***

### prepareStackTrace[​](#preparestacktrace "Direct link to prepareStackTrace")

▸ `Static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**`See`**

<https://v8.dev/docs/stack-trace-api#customizing-stack-traces>

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name          | Type          |
| ------------- | ------------- |
| `err`         | `Error`       |
| `stackTraces` | `CallSite`\[] |

#### Returns[​](#returns-1 "Direct link to Returns")

`any`

#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")

Error.prepareStackTrace

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

../../common/temp/node\_modules/.pnpm/@types+node\@18.19.130/node\_modules/@types/node/globals.d.ts:56

---

# Source: https://docs.convex.dev/api/classes/values.VAny.md

# Class: VAny\<Type, IsOptional, FieldPaths>

[values](/api/modules/values.md).VAny

The type of the `v.any()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `any`                                                                                |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |
| `FieldPaths` | extends `string` = `string`                                                          |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`, `FieldPaths`>

  ↳ **`VAny`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VAny**<`Type`, `IsOptional`, `FieldPaths`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `any`                                                                                |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |
| `FieldPaths` | extends `string` = `string`                                                          |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional, FieldPaths>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `FieldPaths`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"any"`

The kind of validator, `"any"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:261](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L261)

---

# Source: https://docs.convex.dev/api/classes/values.VArray.md

# Class: VArray\<Type, Element, IsOptional>

[values](/api/modules/values.md).VArray

The type of the `v.array()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `Element`    | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>  |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VArray`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VArray**<`Type`, `Element`, `IsOptional`>(`«destructured»`)

Usually you'd use `v.array(element)` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `Element`    | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>  |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |
| › `element`      | `Element`    |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:490](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L490)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### element[​](#element "Direct link to element")

• `Readonly` **element**: `Element`

The validator for the elements of the array.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:480](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L480)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"array"`

The kind of validator, `"array"`.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:485](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L485)

---

# Source: https://docs.convex.dev/api/classes/values.VBoolean.md

# Class: VBoolean\<Type, IsOptional>

[values](/api/modules/values.md).VBoolean

The type of the `v.boolean()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `boolean`                                                                            |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VBoolean`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VBoolean**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `boolean`                                                                            |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"boolean"`

The kind of validator, `"boolean"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:168](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L168)

---

# Source: https://docs.convex.dev/api/classes/values.VBytes.md

# Class: VBytes\<Type, IsOptional>

[values](/api/modules/values.md).VBytes

The type of the `v.bytes()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `ArrayBuffer`                                                                        |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VBytes`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VBytes**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `ArrayBuffer`                                                                        |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"bytes"`

The kind of validator, `"bytes"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:192](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L192)

---

# Source: https://docs.convex.dev/api/classes/values.VFloat64.md

# Class: VFloat64\<Type, IsOptional>

[values](/api/modules/values.md).VFloat64

The type of the `v.float64()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `number`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VFloat64`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VFloat64**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `number`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"float64"`

The kind of validator, `"float64"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:120](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L120)

---

# Source: https://docs.convex.dev/api/classes/values.VId.md

# Class: VId\<Type, IsOptional>

[values](/api/modules/values.md).VId

The type of the `v.id(tableName)` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VId`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VId**<`Type`, `IsOptional`>(`«destructured»`)

Usually you'd use `v.id(tableName)` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type                        |
| ---------------- | --------------------------- |
| `«destructured»` | `Object`                    |
| › `isOptional`   | `IsOptional`                |
| › `tableName`    | `TableNameFromType`<`Type`> |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:84](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L84)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### tableName[​](#tablename "Direct link to tableName")

• `Readonly` **tableName**: `TableNameFromType`<`Type`>

The name of the table that the validated IDs must belong to.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:74](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L74)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"id"`

The kind of validator, `"id"`.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:79](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L79)

---

# Source: https://docs.convex.dev/api/classes/values.VInt64.md

# Class: VInt64\<Type, IsOptional>

[values](/api/modules/values.md).VInt64

The type of the `v.int64()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `bigint`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VInt64`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VInt64**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `bigint`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"int64"`

The kind of validator, `"int64"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:145](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L145)

---

# Source: https://docs.convex.dev/api/classes/values.VLiteral.md

# Class: VLiteral\<Type, IsOptional>

[values](/api/modules/values.md).VLiteral

The type of the `v.literal()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VLiteral`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VLiteral**<`Type`, `IsOptional`>(`«destructured»`)

Usually you'd use `v.literal(value)` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |
| › `value`        | `Type`       |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:441](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L441)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### value[​](#value "Direct link to value")

• `Readonly` **value**: `Type`

The value that the validated values must be equal to.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:431](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L431)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"literal"`

The kind of validator, `"literal"`.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:436](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L436)

---

# Source: https://docs.convex.dev/api/classes/values.VNull.md

# Class: VNull\<Type, IsOptional>

[values](/api/modules/values.md).VNull

The type of the `v.null()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `null`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VNull`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VNull**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `null`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"null"`

The kind of validator, `"null"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:238](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L238)

---

# Source: https://docs.convex.dev/api/classes/values.VObject.md

# Class: VObject\<Type, Fields, IsOptional, FieldPaths>

[values](/api/modules/values.md).VObject

The type of the `v.object()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                                                                                             |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                                                                                           |
| `Fields`     | extends `Record`<`string`, [`GenericValidator`](/api/modules/values.md#genericvalidator)>                                                                        |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`                                                                             |
| `FieldPaths` | extends `string` = { \[Property in keyof Fields]: JoinFieldPaths\<Property & string, Fields\[Property]\["fieldPaths"]> \| Property }\[keyof `Fields`] & `string` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`, `FieldPaths`>

  ↳ **`VObject`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VObject**<`Type`, `Fields`, `IsOptional`, `FieldPaths`>(`«destructured»`)

Usually you'd use `v.object({ ... })` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                                                                                                 |
| `Fields`     | extends `Record`<`string`, [`GenericValidator`](/api/modules/values.md#genericvalidator)>                                                                              |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`                                                                                   |
| `FieldPaths` | extends `string` = { \[Property in string \| number \| symbol]: Property \| \`${Property & string}.${Fields\[Property]\["fieldPaths"]}\` }\[keyof `Fields`] & `string` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |
| › `fields`       | `Fields`     |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional, FieldPaths\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:304](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L304)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `FieldPaths`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### fields[​](#fields "Direct link to fields")

• `Readonly` **fields**: `Fields`

An object with the validator for each property.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:294](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L294)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"object"`

The kind of validator, `"object"`.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:299](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L299)

## Methods[​](#methods "Direct link to Methods")

### omit[​](#omit "Direct link to omit")

▸ **omit**<`K`>(`...fields`): [`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Omit`<`Type`, `K`>>, [`Expand`](/api/modules/server.md#expand)<`Omit`<`Fields`, `K`>>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Omit\<Fields, K>>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Omit`<`Fields`, `K`>>] & `string`>

Create a new VObject with the specified fields omitted.

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `K`  | extends `string` |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name        | Type   | Description                                |
| ----------- | ------ | ------------------------------------------ |
| `...fields` | `K`\[] | The field names to omit from this VObject. |

#### Returns[​](#returns "Direct link to Returns")

[`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Omit`<`Type`, `K`>>, [`Expand`](/api/modules/server.md#expand)<`Omit`<`Fields`, `K`>>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Omit\<Fields, K>>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Omit`<`Fields`, `K`>>] & `string`>

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[values/validators.ts:349](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L349)

***

### pick[​](#pick "Direct link to pick")

▸ **pick**<`K`>(`...fields`): [`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Pick`<`Type`, `Extract`\<keyof `Type`, `K`>>>, [`Expand`](/api/modules/server.md#expand)<`Pick`<`Fields`, `K`>>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Pick\<Fields, K>>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Pick`<`Fields`, `K`>>] & `string`>

Create a new VObject with only the specified fields.

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name | Type             |
| ---- | ---------------- |
| `K`  | extends `string` |

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name        | Type   | Description                                |
| ----------- | ------ | ------------------------------------------ |
| `...fields` | `K`\[] | The field names to pick from this VObject. |

#### Returns[​](#returns-1 "Direct link to Returns")

[`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Pick`<`Type`, `Extract`\<keyof `Type`, `K`>>>, [`Expand`](/api/modules/server.md#expand)<`Pick`<`Fields`, `K`>>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Pick\<Fields, K>>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Pick`<`Fields`, `K`>>] & `string`>

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[values/validators.ts:366](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L366)

***

### partial[​](#partial "Direct link to partial")

▸ **partial**(): [`VObject`](/api/classes/values.VObject.md)<{ \[K in string | number | symbol]?: Type\[K] }, { \[K in string | number | symbol]: VOptional\<Fields\[K]> }, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${{ \[K in string | number | symbol]: VOptional\<Fields\[K]> }\[Property]\["fieldPaths"]}\` }\[keyof `Fields`] & `string`>

Create a new VObject with all fields marked as optional.

#### Returns[​](#returns-2 "Direct link to Returns")

[`VObject`](/api/classes/values.VObject.md)<{ \[K in string | number | symbol]?: Type\[K] }, { \[K in string | number | symbol]: VOptional\<Fields\[K]> }, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${{ \[K in string | number | symbol]: VOptional\<Fields\[K]> }\[Property]\["fieldPaths"]}\` }\[keyof `Fields`] & `string`>

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[values/validators.ts:386](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L386)

***

### extend[​](#extend "Direct link to extend")

▸ **extend**<`NewFields`>(`fields`): [`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Type` & [`ObjectType`](/api/modules/values.md#objecttype)<`NewFields`>>, [`Expand`](/api/modules/server.md#expand)<`Fields` & `NewFields`>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Fields & NewFields>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Fields` & `NewFields`>] & `string`>

Create a new VObject with additional fields merged in.

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name        | Type                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------- |
| `NewFields` | extends `Record`<`string`, [`GenericValidator`](/api/modules/values.md#genericvalidator)> |

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name     | Type        | Description                                                      |
| -------- | ----------- | ---------------------------------------------------------------- |
| `fields` | `NewFields` | An object with additional validators to merge into this VObject. |

#### Returns[​](#returns-3 "Direct link to Returns")

[`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<`Type` & [`ObjectType`](/api/modules/values.md#objecttype)<`NewFields`>>, [`Expand`](/api/modules/server.md#expand)<`Fields` & `NewFields`>, `IsOptional`, { \[Property in string | number | symbol]: Property | \`${Property & string}.${Expand\<Fields & NewFields>\[Property]\["fieldPaths"]}\` }\[keyof [`Expand`](/api/modules/server.md#expand)<`Fields` & `NewFields`>] & `string`>

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[values/validators.ts:407](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L407)

---

# Source: https://docs.convex.dev/api/classes/values.VRecord.md

# Class: VRecord\<Type, Key, Value, IsOptional, FieldPaths>

[values](/api/modules/values.md).VRecord

The type of the `v.record()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                 |
| `Key`        | extends [`Validator`](/api/modules/values.md#validator)<`string`, `"required"`, `any`> |
| `Value`      | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>    |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`   |
| `FieldPaths` | extends `string` = `string`                                                            |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`, `FieldPaths`>

  ↳ **`VRecord`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VRecord**<`Type`, `Key`, `Value`, `IsOptional`, `FieldPaths`>(`«destructured»`)

Usually you'd use `v.record(key, value)` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                 |
| `Key`        | extends [`Validator`](/api/modules/values.md#validator)<`string`, `"required"`, `any`> |
| `Value`      | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>    |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`   |
| `FieldPaths` | extends `string` = `string`                                                            |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |
| › `key`          | `Key`        |
| › `value`        | `Value`      |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional, FieldPaths\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:547](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L547)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `FieldPaths`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### key[​](#key "Direct link to key")

• `Readonly` **key**: `Key`

The validator for the keys of the record.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:532](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L532)

***

### value[​](#value "Direct link to value")

• `Readonly` **value**: `Value`

The validator for the values of the record.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:537](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L537)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"record"`

The kind of validator, `"record"`.

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[values/validators.ts:542](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L542)

---

# Source: https://docs.convex.dev/api/classes/values.VString.md

# Class: VString\<Type, IsOptional>

[values](/api/modules/values.md).VString

The type of the `v.string()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `string`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`>

  ↳ **`VString`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VString**<`Type`, `IsOptional`>(`«destructured»`)

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `string`                                                                             |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator\<Type, IsOptional>.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:54](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L54)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `never`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"string"`

The kind of validator, `"string"`.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:214](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L214)

---

# Source: https://docs.convex.dev/api/classes/values.VUnion.md

# Class: VUnion\<Type, T, IsOptional, FieldPaths>

[values](/api/modules/values.md).VUnion

The type of the `v.union()` validator.

## Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name         | Type                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                 |
| `T`          | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>\[] |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`   |
| `FieldPaths` | extends `string` = `T`\[`number`]\[`"fieldPaths"`]                                     |

## Hierarchy[​](#hierarchy "Direct link to Hierarchy")

* `BaseValidator`<`Type`, `IsOptional`, `FieldPaths`>

  ↳ **`VUnion`**

## Constructors[​](#constructors "Direct link to Constructors")

### constructor[​](#constructor "Direct link to constructor")

• **new VUnion**<`Type`, `T`, `IsOptional`, `FieldPaths`>(`«destructured»`)

Usually you'd use `v.union(...members)` instead.

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name         | Type                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| `Type`       | `Type`                                                                                 |
| `T`          | extends [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>\[] |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"`   |
| `FieldPaths` | extends `string` = `T`\[`number`]\[`"fieldPaths"`]                                     |

#### Parameters[​](#parameters "Direct link to Parameters")

| Name             | Type         |
| ---------------- | ------------ |
| `«destructured»` | `Object`     |
| › `isOptional`   | `IsOptional` |
| › `members`      | `T`          |

#### Overrides[​](#overrides "Direct link to Overrides")

BaseValidator\&lt;Type, IsOptional, FieldPaths\&gt;.constructor

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validators.ts:619](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L619)

## Properties[​](#properties "Direct link to Properties")

### type[​](#type "Direct link to type")

• `Readonly` **type**: `Type`

Only for TypeScript, the TS type of the JS values validated by this validator.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

BaseValidator.type

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validators.ts:37](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L37)

***

### fieldPaths[​](#fieldpaths "Direct link to fieldPaths")

• `Readonly` **fieldPaths**: `FieldPaths`

Only for TypeScript, if this an Object validator, then this is the TS type of its property names.

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

BaseValidator.fieldPaths

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validators.ts:42](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L42)

***

### isOptional[​](#isoptional "Direct link to isOptional")

• `Readonly` **isOptional**: `IsOptional`

Whether this is an optional Object property value validator.

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

BaseValidator.isOptional

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validators.ts:47](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L47)

***

### isConvexValidator[​](#isconvexvalidator "Direct link to isConvexValidator")

• `Readonly` **isConvexValidator**: `true`

Always `"true"`.

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

BaseValidator.isConvexValidator

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validators.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L52)

***

### members[​](#members "Direct link to members")

• `Readonly` **members**: `T`

The array of validators, one of which must match the value.

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:609](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L609)

***

### kind[​](#kind "Direct link to kind")

• `Readonly` **kind**: `"union"`

The kind of validator, `"union"`.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:614](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L614)

---

# Source: https://docs.convex.dev/api/modules/values.md

# Module: values

Utilities for working with values stored in Convex.

You can see the full set of supported types at [Types](https://docs.convex.dev/using/types).

## Namespaces[​](#namespaces "Direct link to Namespaces")

* [Base64](/api/namespaces/values.Base64.md)

## Classes[​](#classes "Direct link to Classes")

* [ConvexError](/api/classes/values.ConvexError.md)
* [VId](/api/classes/values.VId.md)
* [VFloat64](/api/classes/values.VFloat64.md)
* [VInt64](/api/classes/values.VInt64.md)
* [VBoolean](/api/classes/values.VBoolean.md)
* [VBytes](/api/classes/values.VBytes.md)
* [VString](/api/classes/values.VString.md)
* [VNull](/api/classes/values.VNull.md)
* [VAny](/api/classes/values.VAny.md)
* [VObject](/api/classes/values.VObject.md)
* [VLiteral](/api/classes/values.VLiteral.md)
* [VArray](/api/classes/values.VArray.md)
* [VRecord](/api/classes/values.VRecord.md)
* [VUnion](/api/classes/values.VUnion.md)

## Type Aliases[​](#type-aliases "Direct link to Type Aliases")

### GenericValidator[​](#genericvalidator "Direct link to GenericValidator")

Ƭ **GenericValidator**: [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`>

The type that all validators must extend.

#### Defined in[​](#defined-in "Direct link to Defined in")

[values/validator.ts:27](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L27)

***

### AsObjectValidator[​](#asobjectvalidator "Direct link to AsObjectValidator")

Ƭ **AsObjectValidator**<`V`>: `V` extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) ? [`Validator`](/api/modules/values.md#validator)<[`ObjectType`](/api/modules/values.md#objecttype)<`V`>> : `never`

Coerce an object with validators as properties to a validator. If a validator is passed, return it.

#### Type parameters[​](#type-parameters "Direct link to Type parameters")

| Name | Type                                                                                                                                              |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `V`  | extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> \| [`PropertyValidators`](/api/modules/values.md#propertyvalidators) |

#### Defined in[​](#defined-in-1 "Direct link to Defined in")

[values/validator.ts:61](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L61)

***

### PropertyValidators[​](#propertyvalidators "Direct link to PropertyValidators")

Ƭ **PropertyValidators**: `Record`<`string`, [`Validator`](/api/modules/values.md#validator)<`any`, [`OptionalProperty`](/api/modules/values.md#optionalproperty), `any`>>

Validators for each property of an object.

This is represented as an object mapping the property name to its [Validator](/api/modules/values.md#validator).

#### Defined in[​](#defined-in-2 "Direct link to Defined in")

[values/validator.ts:242](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L242)

***

### ObjectType[​](#objecttype "Direct link to ObjectType")

Ƭ **ObjectType**<`Fields`>: [`Expand`](/api/modules/server.md#expand)<{ \[Property in OptionalKeys\<Fields>]?: Exclude\<Infer\<Fields\[Property]>, undefined> } & { \[Property in RequiredKeys\<Fields>]: Infer\<Fields\[Property]> }>

Compute the type of an object from [PropertyValidators](/api/modules/values.md#propertyvalidators).

#### Type parameters[​](#type-parameters-1 "Direct link to Type parameters")

| Name     | Type                                                                      |
| -------- | ------------------------------------------------------------------------- |
| `Fields` | extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) |

#### Defined in[​](#defined-in-3 "Direct link to Defined in")

[values/validator.ts:252](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L252)

***

### Infer[​](#infer "Direct link to Infer")

Ƭ **Infer**<`T`>: `T`\[`"type"`]

Extract a TypeScript type from a validator.

Example usage:

```
const objectSchema = v.object({
  property: v.string(),
});
type MyObject = Infer<typeof objectSchema>; // { property: string }
```

**`Type Param`**

The type of a [Validator](/api/modules/values.md#validator) constructed with [v](/api/modules/values.md#v).

#### Type parameters[​](#type-parameters-2 "Direct link to Type parameters")

| Name | Type                                                                                                                                 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `T`  | extends [`Validator`](/api/modules/values.md#validator)<`any`, [`OptionalProperty`](/api/modules/values.md#optionalproperty), `any`> |

#### Defined in[​](#defined-in-4 "Direct link to Defined in")

[values/validator.ts:294](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L294)

***

### VOptional[​](#voptional "Direct link to VOptional")

Ƭ **VOptional**<`T`>: `T` extends [`VId`](/api/classes/values.VId.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VId`](/api/classes/values.VId.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VString`](/api/classes/values.VString.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VString`](/api/classes/values.VString.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VFloat64`](/api/classes/values.VFloat64.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VFloat64`](/api/classes/values.VFloat64.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VInt64`](/api/classes/values.VInt64.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VInt64`](/api/classes/values.VInt64.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VBoolean`](/api/classes/values.VBoolean.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VBoolean`](/api/classes/values.VBoolean.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VNull`](/api/classes/values.VNull.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VNull`](/api/classes/values.VNull.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VAny`](/api/classes/values.VAny.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VAny`](/api/classes/values.VAny.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VLiteral`](/api/classes/values.VLiteral.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VLiteral`](/api/classes/values.VLiteral.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VBytes`](/api/classes/values.VBytes.md)\<infer Type, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VBytes`](/api/classes/values.VBytes.md)<`Type` | `undefined`, `"optional"`> : `T` extends [`VObject`](/api/classes/values.VObject.md)\<infer Type, infer Fields, [`OptionalProperty`](/api/modules/values.md#optionalproperty), infer FieldPaths> ? [`VObject`](/api/classes/values.VObject.md)<`Type` | `undefined`, `Fields`, `"optional"`, `FieldPaths`> : `T` extends [`VArray`](/api/classes/values.VArray.md)\<infer Type, infer Element, [`OptionalProperty`](/api/modules/values.md#optionalproperty)> ? [`VArray`](/api/classes/values.VArray.md)<`Type` | `undefined`, `Element`, `"optional"`> : `T` extends [`VRecord`](/api/classes/values.VRecord.md)\<infer Type, infer Key, infer Value, [`OptionalProperty`](/api/modules/values.md#optionalproperty), infer FieldPaths> ? [`VRecord`](/api/classes/values.VRecord.md)<`Type` | `undefined`, `Key`, `Value`, `"optional"`, `FieldPaths`> : `T` extends [`VUnion`](/api/classes/values.VUnion.md)\<infer Type, infer Members, [`OptionalProperty`](/api/modules/values.md#optionalproperty), infer FieldPaths> ? [`VUnion`](/api/classes/values.VUnion.md)<`Type` | `undefined`, `Members`, `"optional"`, `FieldPaths`> : `never`

#### Type parameters[​](#type-parameters-3 "Direct link to Type parameters")

| Name | Type                                                                                                                                 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `T`  | extends [`Validator`](/api/modules/values.md#validator)<`any`, [`OptionalProperty`](/api/modules/values.md#optionalproperty), `any`> |

#### Defined in[​](#defined-in-5 "Direct link to Defined in")

[values/validators.ts:648](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L648)

***

### OptionalProperty[​](#optionalproperty "Direct link to OptionalProperty")

Ƭ **OptionalProperty**: `"optional"` | `"required"`

Type representing whether a property in an object is optional or required.

#### Defined in[​](#defined-in-6 "Direct link to Defined in")

[values/validators.ts:681](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L681)

***

### Validator[​](#validator "Direct link to Validator")

Ƭ **Validator**<`Type`, `IsOptional`, `FieldPaths`>: [`VId`](/api/classes/values.VId.md)<`Type`, `IsOptional`> | [`VString`](/api/classes/values.VString.md)<`Type`, `IsOptional`> | [`VFloat64`](/api/classes/values.VFloat64.md)<`Type`, `IsOptional`> | [`VInt64`](/api/classes/values.VInt64.md)<`Type`, `IsOptional`> | [`VBoolean`](/api/classes/values.VBoolean.md)<`Type`, `IsOptional`> | [`VNull`](/api/classes/values.VNull.md)<`Type`, `IsOptional`> | [`VAny`](/api/classes/values.VAny.md)<`Type`, `IsOptional`> | [`VLiteral`](/api/classes/values.VLiteral.md)<`Type`, `IsOptional`> | [`VBytes`](/api/classes/values.VBytes.md)<`Type`, `IsOptional`> | [`VObject`](/api/classes/values.VObject.md)<`Type`, `Record`<`string`, [`Validator`](/api/modules/values.md#validator)<`any`, [`OptionalProperty`](/api/modules/values.md#optionalproperty), `any`>>, `IsOptional`, `FieldPaths`> | [`VArray`](/api/classes/values.VArray.md)<`Type`, [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>, `IsOptional`> | [`VRecord`](/api/classes/values.VRecord.md)<`Type`, [`Validator`](/api/modules/values.md#validator)<`string`, `"required"`, `any`>, [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>, `IsOptional`, `FieldPaths`> | [`VUnion`](/api/classes/values.VUnion.md)<`Type`, [`Validator`](/api/modules/values.md#validator)<`any`, `"required"`, `any`>\[], `IsOptional`, `FieldPaths`>

A validator for a Convex value.

This should be constructed using the validator builder, [v](/api/modules/values.md#v).

A validator encapsulates:

* The TypeScript type of this value.
* Whether this field should be optional if it's included in an object.
* The TypeScript type for the set of index field paths that can be used to build indexes on this value.
* A JSON representation of the validator.

Specific types of validators contain additional information: for example an `ArrayValidator` contains an `element` property with the validator used to validate each element of the list. Use the shared 'kind' property to identity the type of validator.

More validators can be added in future releases so an exhaustive switch statement on validator `kind` should be expected to break in future releases of Convex.

#### Type parameters[​](#type-parameters-4 "Direct link to Type parameters")

| Name         | Type                                                                                 |
| ------------ | ------------------------------------------------------------------------------------ |
| `Type`       | `Type`                                                                               |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values.md#optionalproperty) = `"required"` |
| `FieldPaths` | extends `string` = `never`                                                           |

#### Defined in[​](#defined-in-7 "Direct link to Defined in")

[values/validators.ts:706](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L706)

***

### ObjectFieldType[​](#objectfieldtype "Direct link to ObjectFieldType")

Ƭ **ObjectFieldType**: `Object`

#### Type declaration[​](#type-declaration "Direct link to Type declaration")

| Name        | Type                                                    |
| ----------- | ------------------------------------------------------- |
| `fieldType` | [`ValidatorJSON`](/api/modules/values.md#validatorjson) |
| `optional`  | `boolean`                                               |

#### Defined in[​](#defined-in-8 "Direct link to Defined in")

[values/validators.ts:747](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L747)

***

### ValidatorJSON[​](#validatorjson "Direct link to ValidatorJSON")

Ƭ **ValidatorJSON**: { `type`: `"null"` } | { `type`: `"number"` } | { `type`: `"bigint"` } | { `type`: `"boolean"` } | { `type`: `"string"` } | { `type`: `"bytes"` } | { `type`: `"any"` } | { `type`: `"literal"` ; `value`: [`JSONValue`](/api/modules/values.md#jsonvalue) } | { `type`: `"id"` ; `tableName`: `string` } | { `type`: `"array"` ; `value`: [`ValidatorJSON`](/api/modules/values.md#validatorjson) } | { `type`: `"record"` ; `keys`: [`RecordKeyValidatorJSON`](/api/modules/values.md#recordkeyvalidatorjson) ; `values`: [`RecordValueValidatorJSON`](/api/modules/values.md#recordvaluevalidatorjson) } | { `type`: `"object"` ; `value`: `Record`<`string`, [`ObjectFieldType`](/api/modules/values.md#objectfieldtype)> } | { `type`: `"union"` ; `value`: [`ValidatorJSON`](/api/modules/values.md#validatorjson)\[] }

#### Defined in[​](#defined-in-9 "Direct link to Defined in")

[values/validators.ts:749](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L749)

***

### RecordKeyValidatorJSON[​](#recordkeyvalidatorjson "Direct link to RecordKeyValidatorJSON")

Ƭ **RecordKeyValidatorJSON**: { `type`: `"string"` } | { `type`: `"id"` ; `tableName`: `string` } | { `type`: `"union"` ; `value`: [`RecordKeyValidatorJSON`](/api/modules/values.md#recordkeyvalidatorjson)\[] }

#### Defined in[​](#defined-in-10 "Direct link to Defined in")

[values/validators.ts:768](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L768)

***

### RecordValueValidatorJSON[​](#recordvaluevalidatorjson "Direct link to RecordValueValidatorJSON")

Ƭ **RecordValueValidatorJSON**: [`ObjectFieldType`](/api/modules/values.md#objectfieldtype) & { `optional`: `false` }

#### Defined in[​](#defined-in-11 "Direct link to Defined in")

[values/validators.ts:773](https://github.com/get-convex/convex-js/blob/main/src/values/validators.ts#L773)

***

### JSONValue[​](#jsonvalue "Direct link to JSONValue")

Ƭ **JSONValue**: `null` | `boolean` | `number` | `string` | [`JSONValue`](/api/modules/values.md#jsonvalue)\[] | { `[key: string]`: [`JSONValue`](/api/modules/values.md#jsonvalue); }

The type of JavaScript values serializable to JSON.

#### Defined in[​](#defined-in-12 "Direct link to Defined in")

[values/value.ts:24](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L24)

***

### GenericId[​](#genericid "Direct link to GenericId")

Ƭ **GenericId**<`TableName`>: `string` & { `__tableName`: `TableName` }

An identifier for a document in Convex.

Convex documents are uniquely identified by their `Id`, which is accessible on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/database/document-ids).

Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.

IDs are base 32 encoded strings which are URL safe.

IDs are just strings at runtime, but this type can be used to distinguish them from other strings at compile time.

If you're using code generation, use the `Id` type generated for your data model in `convex/_generated/dataModel.d.ts`.

#### Type parameters[​](#type-parameters-5 "Direct link to Type parameters")

| Name        | Type             | Description                                             |
| ----------- | ---------------- | ------------------------------------------------------- |
| `TableName` | extends `string` | A string literal type of the table name (like "users"). |

#### Defined in[​](#defined-in-13 "Direct link to Defined in")

[values/value.ts:52](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L52)

***

### Value[​](#value "Direct link to Value")

Ƭ **Value**: `null` | `bigint` | `number` | `boolean` | `string` | `ArrayBuffer` | [`Value`](/api/modules/values.md#value)\[] | { `[key: string]`: `undefined` | [`Value`](/api/modules/values.md#value); }

A value supported by Convex.

Values can be:

* stored inside of documents.
* used as arguments and return types to queries and mutation functions.

You can see the full set of supported types at [Types](https://docs.convex.dev/using/types).

#### Defined in[​](#defined-in-14 "Direct link to Defined in")

[values/value.ts:66](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L66)

***

### NumericValue[​](#numericvalue "Direct link to NumericValue")

Ƭ **NumericValue**: `bigint` | `number`

The types of [Value](/api/modules/values.md#value) that can be used to represent numbers.

#### Defined in[​](#defined-in-15 "Direct link to Defined in")

[values/value.ts:81](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L81)

## Variables[​](#variables "Direct link to Variables")

### v[​](#v "Direct link to v")

• `Const` **v**: `Object`

The validator builder.

This builder allows you to build validators for Convex values.

Validators can be used in [schema definitions](https://docs.convex.dev/database/schemas) and as input validators for Convex functions.

#### Type declaration[​](#type-declaration-1 "Direct link to Type declaration")

| Name       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | \<TableName>(`tableName`: `TableName`) => [`VId`](/api/classes/values.VId.md)<[`GenericId`](/api/modules/values.md#genericid)<`TableName`>, `"required"`>                                                                                                                                                                                                                                                                                    |
| `null`     | () => [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                          |
| `number`   | () => [`VFloat64`](/api/classes/values.VFloat64.md)<`number`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                  |
| `float64`  | () => [`VFloat64`](/api/classes/values.VFloat64.md)<`number`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                  |
| `bigint`   | () => [`VInt64`](/api/classes/values.VInt64.md)<`bigint`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                      |
| `int64`    | () => [`VInt64`](/api/classes/values.VInt64.md)<`bigint`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                      |
| `boolean`  | () => [`VBoolean`](/api/classes/values.VBoolean.md)<`boolean`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                 |
| `string`   | () => [`VString`](/api/classes/values.VString.md)<`string`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                    |
| `bytes`    | () => [`VBytes`](/api/classes/values.VBytes.md)<`ArrayBuffer`, `"required"`>                                                                                                                                                                                                                                                                                                                                                                 |
| `literal`  | \<T>(`literal`: `T`) => [`VLiteral`](/api/classes/values.VLiteral.md)<`T`, `"required"`>                                                                                                                                                                                                                                                                                                                                                     |
| `array`    | \<T>(`element`: `T`) => [`VArray`](/api/classes/values.VArray.md)<`T`\[`"type"`]\[], `T`, `"required"`>                                                                                                                                                                                                                                                                                                                                      |
| `object`   | \<T>(`fields`: `T`) => [`VObject`](/api/classes/values.VObject.md)<[`Expand`](/api/modules/server.md#expand)<{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<T\[Property]>, undefined> } & { \[Property in string \| number \| symbol]: Infer\<T\[Property]> }>, `T`, `"required"`, { \[Property in string \| number \| symbol]: Property \| \`${Property & string}.${T\[Property]\["fieldPaths"]}\` }\[keyof `T`] & `string`> |
| `record`   | \<Key, Value>(`keys`: `Key`, `values`: `Value`) => [`VRecord`](/api/classes/values.VRecord.md)<`Record`<[`Infer`](/api/modules/values.md#infer)<`Key`>, `Value`\[`"type"`]>, `Key`, `Value`, `"required"`, `string`>                                                                                                                                                                                                                         |
| `union`    | \<T>(...`members`: `T`) => [`VUnion`](/api/classes/values.VUnion.md)<`T`\[`number`]\[`"type"`], `T`, `"required"`, `T`\[`number`]\[`"fieldPaths"`]>                                                                                                                                                                                                                                                                                          |
| `any`      | () => [`VAny`](/api/classes/values.VAny.md)<`any`, `"required"`, `string`>                                                                                                                                                                                                                                                                                                                                                                   |
| `optional` | \<T>(`value`: `T`) => [`VOptional`](/api/modules/values.md#voptional)<`T`>                                                                                                                                                                                                                                                                                                                                                                   |
| `nullable` | \<T>(`value`: `T`) => [`VUnion`](/api/classes/values.VUnion.md)<`T` \| [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>\[`"type"`], \[`T`, [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>], `"required"`, `T` \| [`VNull`](/api/classes/values.VNull.md)<`null`, `"required"`>\[`"fieldPaths"`]>                                                                                                                 |

#### Defined in[​](#defined-in-16 "Direct link to Defined in")

[values/validator.ts:80](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L80)

## Functions[​](#functions "Direct link to Functions")

### compareValues[​](#comparevalues "Direct link to compareValues")

▸ **compareValues**(`k1`, `k2`): `number`

#### Parameters[​](#parameters "Direct link to Parameters")

| Name | Type                                                   |
| ---- | ------------------------------------------------------ |
| `k1` | `undefined` \| [`Value`](/api/modules/values.md#value) |
| `k2` | `undefined` \| [`Value`](/api/modules/values.md#value) |

#### Returns[​](#returns "Direct link to Returns")

`number`

#### Defined in[​](#defined-in-17 "Direct link to Defined in")

[values/compare.ts:4](https://github.com/get-convex/convex-js/blob/main/src/values/compare.ts#L4)

***

### asObjectValidator[​](#asobjectvalidator-1 "Direct link to asObjectValidator")

▸ **asObjectValidator**<`V`>(`obj`): `V` extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) ? [`Validator`](/api/modules/values.md#validator)<[`ObjectType`](/api/modules/values.md#objecttype)<`V`>> : `never`

Coerce an object with validators as properties to a validator. If a validator is passed, return it.

#### Type parameters[​](#type-parameters-6 "Direct link to Type parameters")

| Name | Type                                                                                                                                              |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `V`  | extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) \| [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> |

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Name  | Type |
| ----- | ---- |
| `obj` | `V`  |

#### Returns[​](#returns-1 "Direct link to Returns")

`V` extends [`Validator`](/api/modules/values.md#validator)<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values.md#propertyvalidators) ? [`Validator`](/api/modules/values.md#validator)<[`ObjectType`](/api/modules/values.md#objecttype)<`V`>> : `never`

#### Defined in[​](#defined-in-18 "Direct link to Defined in")

[values/validator.ts:39](https://github.com/get-convex/convex-js/blob/main/src/values/validator.ts#L39)

***

### jsonToConvex[​](#jsontoconvex "Direct link to jsonToConvex")

▸ **jsonToConvex**(`value`): [`Value`](/api/modules/values.md#value)

Parse a Convex value from its JSON representation.

This function will deserialize serialized Int64s to `BigInt`s, Bytes to `ArrayBuffer`s etc.

To learn more about Convex values, see [Types](https://docs.convex.dev/using/types).

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Name    | Type                                            | Description                                                                                                            |
| ------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `value` | [`JSONValue`](/api/modules/values.md#jsonvalue) | The JSON representation of a Convex value previously created with [convexToJson](/api/modules/values.md#convextojson). |

#### Returns[​](#returns-2 "Direct link to Returns")

[`Value`](/api/modules/values.md#value)

The JavaScript representation of the Convex value.

#### Defined in[​](#defined-in-19 "Direct link to Defined in")

[values/value.ts:187](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L187)

***

### convexToJson[​](#convextojson "Direct link to convexToJson")

▸ **convexToJson**(`value`): [`JSONValue`](/api/modules/values.md#jsonvalue)

Convert a Convex value to its JSON representation.

Use [jsonToConvex](/api/modules/values.md#jsontoconvex) to recreate the original value.

To learn more about Convex values, see [Types](https://docs.convex.dev/using/types).

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Name    | Type                                    | Description                          |
| ------- | --------------------------------------- | ------------------------------------ |
| `value` | [`Value`](/api/modules/values.md#value) | A Convex value to convert into JSON. |

#### Returns[​](#returns-3 "Direct link to Returns")

[`JSONValue`](/api/modules/values.md#jsonvalue)

The JSON representation of `value`.

#### Defined in[​](#defined-in-20 "Direct link to Defined in")

[values/value.ts:429](https://github.com/get-convex/convex-js/blob/main/src/values/value.ts#L429)

---

# Source: https://docs.convex.dev/search/vector-search.md

# Vector Search

Vector search allows you to find Convex documents similar to a provided vector. Typically, vectors will be embeddings which are numerical representations of text, images, or audio.

Embeddings and vector search enable you to provide useful context to LLMs for AI powered applications, recommendations for similar content and more.

Vector search is consistent and fully up-to-date. You can write a vector and immediately read it from a vector search. Unlike [full text search](/search.md), however, vector search is only available in [Convex actions](/functions/actions.md).

**Example:** [Vector Search App](https://github.com/get-convex/convex-demos/tree/main/vector-search)

To use vector search you need to:

1. Define a vector index.
2. Run a vector search from within an [action](/functions/actions.md).

## Defining vector indexes[​](#defining-vector-indexes "Direct link to Defining vector indexes")

Like [database indexes](/database/reading-data/indexes/.md), vector indexes are a data structure that is built in advance to enable efficient querying. Vector indexes are defined as part of your Convex [schema](/database/schemas.md).

To add a vector index onto a table, use the [`vectorIndex`](/api/classes/server.TableDefinition.md#vectorindex) method on your table's schema. Every vector index has a unique name and a definition with:

1. `vectorField` string
   <!-- -->
   * The name of the field indexed for vector search.
2. `dimensions` number
   <!-- -->
   * The fixed size of the vectors index. If you're using embeddings, this dimension should match the size of your embeddings (e.g. `1536` for OpenAI).
3. \[Optional] `filterFields` array
   <!-- -->
   * The names of additional fields that are indexed for fast filtering within your vector index.
4. \[Optional] `staged` boolean
   <!-- -->
   * If set to `true`, the index will be backfilled asynchronously from the deploy similar to [staged database indexes](/database/reading-data/indexes/.md#staged-indexes). This is useful for large tables where the index backfill time is significant. Defaults to `false`.

For example, if you want an index that can search for similar foods within a given cuisine, your table definition could look like:

convex/schema.ts

```
foods: defineTable({
  description: v.string(),
  cuisine: v.string(),
  embedding: v.array(v.float64()),
}).vectorIndex("by_embedding", {
  vectorField: "embedding",
  dimensions: 1536,
  filterFields: ["cuisine"],
}),
```

You can specify vector and filter fields on nested documents by using a dot-separated path like `properties.name`.

## Running vector searches[​](#running-vector-searches "Direct link to Running vector searches")

Unlike database queries or full text search, vector searches can only be performed in a [Convex action](/functions/actions.md).

They generally involve three steps:

1. Generate a vector from provided input (e.g. using OpenAI)
2. Use [`ctx.vectorSearch`](/api/interfaces/server.GenericActionCtx.md#vectorsearch) to fetch the IDs of similar documents
3. Load the desired information for the documents

Here's an example of the first two steps for searching for similar French foods based on a description:

convex/foods.ts

TS

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

export const similarFoods = action({
  args: {
    descriptionQuery: v.string(),
  },
  handler: async (ctx, args) => {
    // 1. Generate an embedding from your favorite third party API:
    const embedding = await embed(args.descriptionQuery);
    // 2. Then search for similar foods!
    const results = await ctx.vectorSearch("foods", "by_embedding", {
      vector: embedding,
      limit: 16,
      filter: (q) => q.eq("cuisine", "French"),
    });
    // ...
  },
});
```

An example of the first step can be found [here](https://github.com/get-convex/convex-demos/blob/main/vector-search/convex/foods.ts#L18) in the vector search demo app.

Focusing on the second step, the `vectorSearch` API takes in the table name, the index name, and finally a [`VectorSearchQuery`](/api/interfaces/server.VectorSearchQuery.md) object describing the search. This object has the following fields:

1. `vector` array

   <!-- -->

   * An array of numbers (e.g. embedding) to use in the search.
   * The search will return the document IDs of the documents with the most similar stored vectors.
   * It must have the same length as the `dimensions` of the index.

2. \[Optional] `limit` number
   <!-- -->
   * The number of results to get back. If specified, this value must be between 1 and 256.

3. \[Optional] `filter`
   * An expression that restricts the set of results based on the `filterFields` in the `vectorIndex` in your schema. See [Filter expressions](#filter-expressions) for details.

It returns an `Array` of objects containing exactly two fields:

1. `_id`
   * The [Document ID](https://docs.convex.dev/database/document-ids) for the matching document in the table
2. `_score`
   * An indicator of how similar the result is to the vector you were searching for, ranging from -1 (least similar) to 1 (most similar)

Neither the underlying document nor the vector are included in `results`, so once you have the list of results, you will want to load the desired information about the results.

There are a few strategies for loading this information documented in the [Advanced Patterns](#advanced-patterns) section.

For now, let's load the documents and return them from the action. To do so, we'll pass the list of results to a Convex query and run it inside of our action, returning the result:

convex/foods.ts

TS

```
export const fetchResults = internalQuery({
  args: { ids: v.array(v.id("foods")) },
  handler: async (ctx, args) => {
    const results = [];
    for (const id of args.ids) {
      const doc = await ctx.db.get("foods", id);
      if (doc === null) {
        continue;
      }
      results.push(doc);
    }
    return results;
  },
});
```

convex/foods.ts

TS

```
export const similarFoods = action({
  args: {
    descriptionQuery: v.string(),
  },
  handler: async (ctx, args) => {
    // 1. Generate an embedding from your favorite third party API:
    const embedding = await embed(args.descriptionQuery);
    // 2. Then search for similar foods!
    const results = await ctx.vectorSearch("foods", "by_embedding", {
      vector: embedding,
      limit: 16,
      filter: (q) => q.eq("cuisine", "French"),
    });
    // 3. Fetch the results
    const foods: Array<Doc<"foods">> = await ctx.runQuery(
      internal.foods.fetchResults,
      { ids: results.map((result) => result._id) },
    );
    return foods;
  },
});
```

### Filter expressions[​](#filter-expressions "Direct link to Filter expressions")

As mentioned above, vector searches support efficiently filtering results by additional fields on your document using either exact equality on a single field, or an `OR` of expressions.

For example, here's a filter for foods with cuisine exactly equal to "French":

```
filter: (q) => q.eq("cuisine", "French"),
```

You can also filter documents by a single field that contains several different values using an `or` expression. Here's a filter for French or Indonesian dishes:

```
filter: (q) =>
  q.or(q.eq("cuisine", "French"), q.eq("cuisine", "Indonesian")),
```

For indexes with multiple filter fields, you can also use `.or()` filters on different fields. Here's a filter for dishes whose cuisine is French or whose main ingredient is butter:

```
filter: (q) =>
  q.or(q.eq("cuisine", "French"), q.eq("mainIngredient", "butter")),
```

**Both `cuisine` and `mainIngredient` would need to be included in the `filterFields` in the `.vectorIndex` definition.**

### Other filtering[​](#other-filtering "Direct link to Other filtering")

Results can be filtered based on how similar they are to the provided vector using the `_score` field in your action:

```
const results = await ctx.vectorSearch("foods", "by_embedding", {
  vector: embedding,
});
const filteredResults = results.filter((result) => result._score >= 0.9);
```

Additional filtering can always be done by passing the vector search results to a query or mutation function that loads the documents and performs filtering using any of the fields on the document.

**For performance, always put as many of your filters as possible into `.vectorSearch`.**

### Ordering[​](#ordering "Direct link to Ordering")

Vector queries always return results in relevance order.

Currently Convex searches vectors using an [approximate nearest neighbor search](https://en.wikipedia.org/wiki/Nearest_neighbor_search#Approximate_nearest_neighbor) based on [cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity). Support for more similarity metrics [will come in the future](#future-development).

If multiple documents have the same score, ties are broken by the document ID.

## Advanced patterns[​](#advanced-patterns "Direct link to Advanced patterns")

### Using a separate table to store vectors[​](#using-a-separate-table-to-store-vectors "Direct link to Using a separate table to store vectors")

There are two main options for setting up a vector index:

1. Storing vectors in the same table as other metadata
2. Storing vectors in a separate table, with a reference

The examples above show the first option, which is simpler and works well for reading small amounts of documents. The second option is more complex, but better supports reading or returning large amounts of documents.

Since vectors are typically large and not useful beyond performing vector searches, it's nice to avoid loading them from the database when reading other data (e.g. `db.get()`) or returning them from functions by storing them in a separate table.

A table definition for movies, and a vector index supporting search for similar movies filtering by genre would look like this:

convex/schema.ts

```
movieEmbeddings: defineTable({
  embedding: v.array(v.float64()),
  genre: v.string(),
}).vectorIndex("by_embedding", {
  vectorField: "embedding",
  dimensions: 1536,
  filterFields: ["genre"],
}),
movies: defineTable({
  title: v.string(),
  genre: v.string(),
  description: v.string(),
  votes: v.number(),
  embeddingId: v.optional(v.id("movieEmbeddings")),
}).index("by_embedding", ["embeddingId"]),
```

Generating an embedding and running a vector search are the same as using a single table. Loading the relevant documents given the vector search result is different since we have an ID for `movieEmbeddings` but want to load a `movies` document. We can do this using the `by_embedding` database index on the `movies` table:

convex/movies.ts

TS

```
export const fetchMovies = query({
  args: {
    ids: v.array(v.id("movieEmbeddings")),
  },
  handler: async (ctx, args) => {
    const results = [];
    for (const id of args.ids) {
      const doc = await ctx.db
        .query("movies")
        .withIndex("by_embedding", (q) => q.eq("embeddingId", id))
        .unique();
      if (doc === null) {
        continue;
      }
      results.push(doc);
    }
    return results;
  },
});
```

### Fetching results and adding new documents[​](#fetching-results-and-adding-new-documents "Direct link to Fetching results and adding new documents")

Returning information from a vector search involves an action (since vector search is only available in actions) and a query or mutation to load the data.

The example above used a query to load data and return it from an action. Since this is an action, the data returned is not reactive. An alternative would be to return the results of the vector search in the action, and have a separate query that reactively loads the data. The search results will not update reactively, but the data about each result would be reactive.

The [Vector Search Demo App](https://github.com/get-convex/convex-demos/tree/main/vector-search) uses this strategy to show similar movies with a reactive "Votes" count.

## Limits[​](#limits "Direct link to Limits")

Convex supports millions of vectors today. This is an ongoing project and we will continue to scale this offering out with the rest of Convex.

Vector indexes must have:

* Exactly 1 vector index field.
  <!-- -->
  * The field must be of type `v.array(v.float64())` (or a union in which one of the possible types is `v.array(v.float64())`)
* Exactly 1 dimension field with a value between 2 and 4096.
* Up to 16 filter fields.

Vector indexes count towards the [limit of 32 indexes per table](/database/reading-data/indexes/.md#limits). In addition you can have up to 4 vector indexes per table.

Vector searches can have:

* Exactly 1 vector to search by in the `vector` field
* Up to 64 filter expressions
* Up to 256 requested results (defaulting to 10).

If your action performs a vector search then passes the results to a query or mutation function, you may find that one or more results from the vector search have been deleted or mutated. Because vector search is only available in actions, you cannot perform additional transactional queries or mutations based on the results. If this is important for your use case, please [let us know on Discord](https://convex.dev/community)!

Only documents that contain a vector of the size and in the field specified by a vector index will be included in the index and returned by the vector search.

For information on limits, see [here](/production/state/limits.md).

## Future development[​](#future-development "Direct link to Future development")

We're always open to customer feedback and requests. Some ideas we've considered for improving vector search in Convex include:

* More sophisticated filters and filter syntax
* Filtering by score in the `vectorSearch` API
* Better support for generating embeddings

If any of these features is important for your app, [let us know on Discord](https://convex.dev/community)!

---

# Source: https://docs.convex.dev/production/hosting/vercel.md

# Using Convex with Vercel

Hosting your Convex app on Vercel allows you to automatically re-deploy both your backend and your frontend whenever you push your code.

## Deploying to Vercel[​](#deploying-to-vercel "Direct link to Deploying to Vercel")

### Using the Vercel Marketplace[​](#using-the-vercel-marketplace "Direct link to Using the Vercel Marketplace")

info

Projects deployed with the Vercel marketplace will be a part of their own Convex team. If you already have a Convex team, you may [follow these instructions](/production/hosting/vercel.md#connecting-your-convex-project-to-vercel).

Convex is available on the [Vercel Marketplace](https://vercel.com/marketplace/convex). You may create, deploy, and pay for (if using a paid subscription) for your Convex projects through Vercel by using the marketplace.

Convex projects created through the Vercel Marketplace will automatically be configured to deploy automatically.

Quickly deploy a template project to the Vercel Marketplace:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fget-convex%2Fvercel-marketplace-convex\&project-name=vercel-with-convex\&repository-name=vercel-with-convex\&demo-title=Convex%20with%20Vercel\&demo-description=A%20minimal%20template%20showcasing%20using%20Convex%20with%20Vercel\&demo-url=https%3A%2F%2Fconvex-vercel-template-demo.previews.convex.dev%2F\&products=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22convex%22%2C%22productSlug%22%3A%22convex%22%2C%22protocol%22%3A%22storage%22%7D%5D)

### Connecting your Convex project to Vercel[​](#connecting-your-convex-project-to-vercel "Direct link to Connecting your Convex project to Vercel")

#### Using a template[​](#using-a-template "Direct link to Using a template")

To start a new project quickly, you may click this button and follow the instructions to quickly deploy your Convex project to Vercel.

**Note:** You'll need to create a project on the Convex dashboard to use this template.

[![Deploy with
Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fget-convex%2Fvercel-marketplace-convex\&project-name=vercel-with-convex\&repository-name=vercel-with-convex\&demo-title=Convex%20with%20Vercel\&demo-description=A%20minimal%20template%20showcasing%20using%20Convex%20with%20Vercel\&demo-url=https%3A%2F%2Fconvex-vercel-template-demo.previews.convex.dev%2F\&products=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22convex%22%2C%22productSlug%22%3A%22convex%22%2C%22protocol%22%3A%22storage%22%7D%5D)

#### From scratch[​](#from-scratch "Direct link to From scratch")

This guide assumes you already have a working React app with Convex. If not follow the [Convex React Quickstart](/quickstart/react.md) first. Then:

1. Create a Vercel account

   If you haven't done so, create a [Vercel](https://vercel.com) account. This is free for small projects and should take less than a minute to set up.

2. Link your project on Vercel

   Create a Vercel project at <https://vercel.com/new> and link it to the source code repository for your project on GitHub or other Git platform.

   ![Vercel import project](/assets/images/vercel_import-ea7ec18cd8c5e5575158bcf032698bc7.png)

3. Override the Build command

   Override the "Build command" to be `npx convex deploy --cmd 'npm run build'`.

   If your project lives in a subdirectory of your repository you'll also need to change *Root Directory* above accordingly.

   ![Vercel build settings](/assets/images/vercel_build_command-236a66a2e7e2091d610883c56954dcb9.png)

4. Set up the CONVEX\_DEPLOY\_KEY environment variable

   Go to the [Project Settings](https://dashboard.convex.dev/project/settings#production-deploy-keys) page in the Convex Dashboard. Click the *Generate Production Deploy Key* button to generate a **Production** deploy key. Then click the copy button to copy the key.

   In Vercel, click *Environment Variables*. Create an environment variable named `CONVEX_DEPLOY_KEY` and paste in your deploy key. Under *Environment*, uncheck all except *Production* and click *Save*.

   ![Vercel environment variable CONVEX\_DEPLOY\_KEY](/assets/images/vercel_prod_deploy_key-df730e5f65427ae68f68b48af225995b.png)

5. Deploy your site

   Now click the *Deploy* button and your work here is done!

Vercel will automatically publish your site to an URL like `https://<site-name>.vercel.app`, shown on the page after deploying. Every time you push to your Git repository, Vercel will automatically deploy your Convex functions and publish your site changes.

Using a Custom Domain?

If you're using a custom domain to serve your Convex functions, you'll need additional configuration. See [Custom Domains](/production/hosting/custom.md#hosting-with-a-custom-domain) for more information.

### How it works[​](#how-it-works "Direct link to How it works")

In Vercel, we overrode the *Build Command* to be `npx convex deploy --cmd 'npm run build'`.

`npx convex deploy` will read `CONVEX_DEPLOY_KEY` from the environment and use it to set the `CONVEX_URL` (or similarly named) environment variable to point to your **production** deployment.

Your frontend framework of choice invoked by `npm run build` will read the `CONVEX_URL` (or similarly named) environment variable to point your deployed site (via `ConvexReactClient`) at your **production** deployment.

Finally, `npx convex deploy` will push your Convex functions to your production deployment.

Now, your production deployment has your newest functions and your app is configured to connect to it.

You can use `--cmd-url-env-var-name` to customize the variable name used by your frontend code if the `deploy` command cannot infer it, like

```
npx convex deploy --cmd-url-env-var-name CUSTOM_CONVEX_URL --cmd 'npm run build'
```

### Authentication[​](#authentication "Direct link to Authentication")

You will want to configure your [authentication](/auth.md) provider (Clerk, Auth0 or other) to accept your production URL. Note that Clerk does not support `https://<site-name>.vercel.app`, so you'll have to configure a custom domain.

## Preview Deployments[​](#preview-deployments "Direct link to Preview Deployments")

Vercel Preview Deployments allow you to preview changes to your app before they're merged in. In order to preview both changes to frontend code and Convex functions, you can set up [Convex preview deployments](/production/hosting/preview-deployments.md).

This will create a fresh Convex backend for each preview and leave your production and development deployments unaffected.

This assumes you have already followed the steps in [Deploying to Vercel](#deploying-to-vercel) above.

1. Set up the CONVEX\_DEPLOY\_KEY environment variable

   On your [Convex Dashboard](https://dashboard.convex.dev/) go to your project's *Settings* page. Click the *Generate Preview Deploy Key* button to generate a **Preview** deploy key. Then click the copy button to copy the key.

   In Vercel, click *Environment Variables*. Create an environment variable named `CONVEX_DEPLOY_KEY` and paste in your deploy key. Under *Environment*, uncheck all except *Preview* and click *Save*.

   ![Vercel environment variable CONVEX\_DEPLOY\_KEY](/assets/images/vercel_preview_deploy_key-bb1badeb35323ef9c06516982aa5c8c7.png)

2. (optional) Set up default environment variables

   If your app depends on certain Convex environment variables, you can set up [default environment variables](/production/environment-variables.md#project-environment-variable-defaults) for preview and development deployments in your project.

   ![Project Default Environment Variables](/assets/images/project_default_environment_variables-94be77c692d0a3c9564cb7f642b6cb64.png)

3. (optional) Run a function to set up initial data

   Vercel Preview Deployments run against fresh Convex backends, which do not share data with development or production Convex deployments. You can call a Convex function to set up data by adding `--preview-run 'functionName'` to the `npx convex deploy` command. This function will only be run for preview deployments, and will be ignored when deploying to production.

   Vercel > Settings > Build & Development settings > Build Command

   ```
   npx convex deploy --cmd 'npm run build' --preview-run 'functionName'
   ```

4. Now test out creating a PR and generating a Preview Deployment!

   You can find the Convex deployment for your branch in the Convex dashboard.

   ![Preview Deployment in Deployment Picker](/assets/images/preview_deployment_deployment_picker-bc5b5e7cd3ac7e0e44ec7ed4c8b40c1c.png)

### How it works[​](#how-it-works-1 "Direct link to How it works")

For Preview Deployments, `npx convex deploy` will read `CONVEX_DEPLOY_KEY` from the environment, and use it to create a Convex deployment associated with the Git branch name for the Vercel Preview Deployment. It will set the `CONVEX_URL` (or similarly named) environment variable to point to the new Convex deployment.

Your frontend framework of choice invoked by `npm run build` will read the `CONVEX_URL` environment variable and point your deployed site (via `ConvexReactClient`) at the Convex preview deployment.

Finally, `npx convex deploy` will push your Convex functions to the preview deployment and run the `--preview-run` function (if provided). This deployment has separate functions, data, crons and all other configuration from any other deployments.

`npx convex deploy` will infer the Git branch name for Vercel, Netlify, GitHub, and GitLab environments, but the `--preview-create` option can be used to customize the name associated with the newly created deployment.

Production deployments will work exactly the same as before.

---

# Source: https://docs.convex.dev/client/vue.md

# Source: https://docs.convex.dev/quickstart/vue.md

# Vue Quickstart

Learn how to query data from Convex in a Vue app.

This quickstart guide uses a [community-maintained](/client/vue.md) Vue client for Convex.

1. Create a Vue site

   Create a Vue site using the `npm create vue@latest my-vue-app` command.

   Convex will work with any set of options but to follow this quickstart most closely choose:

   * Yes to "Add TypeScript?"
   * No to everything else

   <br />

   ```
   npm create vue@latest my-vue-app
   ```

2. Install the Convex library

   To get started, install the `convex` package.

   ```
   cd my-vue-app && npm install convex convex-vue
   ```

3. Set up a Convex dev deployment

   Next, run `npx convex dev`. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a `convex/` folder for you to write your backend API functions in. The `dev` command will then continue running to sync your functions with your dev deployment in the cloud.

   ```
   npx convex dev
   ```

4. Create sample data for your database

   In a new terminal window, create a `sampleData.jsonl` file with some sample data.

   sampleData.jsonl

   ```
   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
   ```

5. Add the sample data to your database

   Now that your project is ready, add a `tasks` table with the sample data into your Convex database with the `import` command.

   ```
   npx convex import --table tasks sampleData.jsonl
   ```

6. Expose a database query

   Add a new file `tasks.ts` in the `convex/` folder with a query function that loads the data.

   Exporting a query function from this file declares an API function named after the file and the export name, `api.tasks.get`.

   convex/tasks.ts

   ```
   import { query } from "./_generated/server";

   export const get = query({
     args: {},
     handler: async (ctx) => {
       return await ctx.db.query("tasks").collect();
     },
   });
   ```

7. Wire up the ConvexProvider

   In `src/main.ts` set up the Convex client there to make it available on every page of your app.

   src/main.ts

   ```
   import { convexVue } from 'convex-vue'
   import { createApp } from 'vue'
   import App from './App.vue'

   const app = createApp(App)

   app.use(convexVue, {
     url: import.meta.env.VITE_CONVEX_URL,
   })

   app.mount('#app')
   ```

8. Display the data in your app

   In `src/App.vue` use `useQuery` to subscribe your `api.tasks.get` API function.

   src/App.vue

   ```
   <script setup lang="ts">
   import { useConvexQuery } from "convex-vue";
   import { api } from "../convex/_generated/api";

   const { data, isPending } = useConvexQuery(api.tasks.get);
   </script>

   <template>
     <span v-if="isPending"> Loading... </span>
     <ul v-else>
       <li v-for="todo in data">
         {{ todo.text }} {{ todo.isCompleted ? "☑" : "☐" }}
       </li>
     </ul>
   </template>
   ```

9. Start the app

   Start the app, open <http://localhost:5173> in a browser, and see the list of tasks.

   ```
   npm run dev
   ```

See the complete [Vue npm package documentation](https://www.npmjs.com/package/convex-vue).

---

# Source: https://docs.convex.dev/understanding/workflow.md

# Dev workflow

Let's walk through everything that needs to happen from creating a new project to launching your app in production.

This doc assumes you are building an app with Convex and React and you already have a basic React app already up and running. You can follow one of our [quickstarts](/quickstarts) to set this up.

## Installing and running Convex[​](#installing-and-running-convex "Direct link to Installing and running Convex")

You install Convex adding the npm dependency to your app:

```
npm i convex
```

Then you create your Convex project and start the backend dev loop:

```
npx convex dev
```

The first time you run the `npx convex dev` command you'll be asked whether you want start developing locally without an account or create an account.

### Developing without an account[​](#developing-without-an-account "Direct link to Developing without an account")

`npx convex dev` will prompt you for the name of your project, and then start running the open-source Convex backend locally on your machine (this is also called a "deployment").

The data for your project will be saved in the `~/.convex` directory.

1. The name of your project will get saved to your `.env.local` file so future runs of `npx convex dev` will know to use this project.
2. A `convex/` folder will be created (if it doesn't exist), where you'll write your Convex backend functions.

You can run `npx convex login` in the future to create an account and link any existing projects.

### Developing with an account[​](#developing-with-an-account "Direct link to Developing with an account")

`npx convex dev` will prompt you through creating an account if one doesn't exist, and will add your credentials to `~/.convex/config.json` on your machine. You can run `npx convex logout` to log you machine out of the account in the future.

Next, `npx convex dev` will create a new project and provision a new personal development deployment for this project:

1. Deployment details will automatically be added to your `.env.local` file so future runs of `npx convex dev` will know which dev deployment to connect to.
2. A `convex/` folder will be created (if it doesn't exist), where you'll write your Convex backend functions.

![Convex directory in your app](/assets/images/convex-directory-1ede9882007bf42d249b0561f2892c54.png)

## Running the dev loop[​](#running-the-dev-loop "Direct link to Running the dev loop")

Keep the `npx convex dev` command running while you're working on your Convex app. This continuously pushes backend code you write in the `convex/` folder to your deployment. It also keeps the necessary TypeScript types up-to-date as you write your backend code.

When you're developing with a locally running deployment, `npx convex dev` is also responsible for running your deployment.

You can then add new server functions to your Convex backend:

convex/tasks.ts

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

// Return the last 100 tasks in a given task list.
export const getTaskList = query({
  args: { taskListId: v.id("taskLists") },
  handler: async (ctx, args) => {
    const tasks = await ctx.db
      .query("tasks")
      .withIndex("taskListId", (q) => q.eq("taskListId", args.taskListId))
      .order("desc")
      .take(100);
    return tasks;
  },
});
```

When you write and save this code in your editor, several things happen:

1. The `npx convex dev` command typechecks your code and updates the `convex/_generated` directory.
2. The contents of your `convex/` directory get uploaded to your dev deployment.
3. Your Convex dev deployment analyzes your code and finds all Convex functions. In this example, it determines that `tasks.getTaskList` is a new public query function.
4. If there are any changes to the [schema](/database/schemas.md), the deployment will automatically enforce them.
5. The `npx convex dev` command updates generated TypeScript code in the `convex/_generated` directory to provide end to end type safety for your functions.

tip

Check in everything in your `convex/_generated/` directory. This it ensures that your code immediately type checks and runs without having to first run `npx convex dev`. It's particularly useful when non-backend developers are writing frontend code and want to ensure their code type checks against currently deployed backend code.

Once this is done you can use your new server function in your frontend:

src/App.tsx

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

export function App() {
  const data = useQuery(api.tasks.getTaskList);
  return data ?? "Loading...";
}
```

If you have other configuration like [crons](/scheduling/cron-jobs.md) or [auth](/auth.md) in your `convex/` folder, Convex ensures that they are applied and enforced on your backend.

## Convex dashboard[​](#convex-dashboard "Direct link to Convex dashboard")

The [Convex dashboard](/dashboard/deployments/.md) will be a trusty helper throughout your dev, debug and deploy workflow in Convex.

`npx convex dashboard` will open a link to the dashboard for your deployment.

### Logs[​](#logs "Direct link to Logs")

Since Convex functions are TypeScript functions you can always use the standard `console.log` and `console.time` functions to debug your apps.

Logs from your functions show up [in your dashboard](/dashboard/deployments/logs.md).

![Logs Dashboard Page](/assets/images/logs-ed208103a42edfb005e9089a8edad58e.png)

### Health, Data, Functions and more[​](#health-data-functions-and-more "Direct link to Health, Data, Functions and more")

* [Health](/dashboard/deployments/health.md) - provides invaluable information on how your app is performing in production, with deep insights on how your Convex queries are doing.
* [Data](/dashboard/deployments/data.md) - gives you a complete data browser to spot check your data.
* [Functions](/dashboard/deployments/functions.md) - gives you stats and run functions to debug them.

There is a lot more to to the dashboard. Be sure to click around or [check out the docs](/dashboard.md).

## Deploying your app[​](#deploying-your-app "Direct link to Deploying your app")

So far you've been working on your app against your personal dev deployment.

All Convex projects have one production deployment running in the cloud. It has separate data and has a separate push process from personal dev deployments, which allows you and your teammates to work on new features using personal dev deployments without disrupting your app running in production.

If you have not created a Convex account yet, you will need to do so with `npx convex login`. This will automatically link any projects you've started with your new account, and enable using your production deployment.

To push your code to your production deployment for your project you run the deploy command:

```
npx convex deploy
```

info

If you're running this command for the first time, it will automatically provision the prod deployment for your project.

### Setting up your deployment pipeline[​](#setting-up-your-deployment-pipeline "Direct link to Setting up your deployment pipeline")

It's rare to run `npx convex deploy` directly. Most production applications run an automated workflow that runs tests and deploys your backend and frontend together.

You can see detailed deployment and frontend configuration instructions in the [Hosting and Deployment](/production/hosting/.md) doc. For most React meta-frameworks Convex [automatically sets the correct environment variable](/production/hosting/vercel.md#how-it-works) to connect to the production deployment.

## Up next[​](#up-next "Direct link to Up next")

You now know the basics of how Convex works and fits in your app. Go head and explore the docs further to learn more about the specific features you want to use.

Whenever you're ready be sure the read the [Best Practices](/understanding/best-practices/.md), and then the [Zen of Convex](/understanding/zen.md) once you are ready to "think in Convex."

---

# Source: https://docs.convex.dev/agents/workflows.md

# Workflows

Agentic Workflows can be decomposed into two elements:

1. Prompting an LLM (including message history, context, etc.).
2. Deciding what to do with the LLM's response.

We generally call them workflows when there are multiple steps involved, they involve dynamically deciding what to do next, are long-lived, or have a mix of business logic and LLM calls.

Tool calls and MCP come into play when the LLM's response is a specific request for an action to take. The list of available tools and result of the calls are used in the prompt to the LLM.

One especially powerful form of Workflows are those that can be modeled as [durable functions](https://stack.convex.dev/durable-workflows-and-strong-guarantees) that can be long-lived, survive server restarts, and have strong guarantees around retrying, idempotency, and completing.

The simplest version of this could be doing a couple pre-defined steps, such as first getting the weather forecast, then getting fashion advice based on the weather. For a code example, see [workflows/chaining.ts](https://github.com/get-convex/agent/blob/main/example/convex/workflows/chaining.ts).

```
export const getAdvice = action({
  args: { location: v.string(), threadId: v.string() },
  handler: async (ctx, { location, threadId }) => {
    // This uses tool calls to get the weather forecast.
    await weatherAgent.generateText(
      ctx,
      { threadId },
      { prompt: `What is the weather in ${location}?` },
    );
    // This includes previous message history from the thread automatically and
    // uses tool calls to get user-specific fashion advice.
    await fashionAgent.generateText(
      ctx,
      { threadId },
      { prompt: `What should I wear based on the weather?` },
    );
    // We don't need to return anything, since the messages are saved
    // automatically and clients will get the response via subscriptions.
  },
});
```

## Building reliable workflows[​](#building-reliable-workflows "Direct link to Building reliable workflows")

One common pitfall when working with LLMs is their unreliability. API providers have outages, and LLMs can be flaky. To build reliable workflows, you often need three properties:

1. Reliable retries
2. Load balancing
3. Durability and idempotency for multi-step workflows

Thankfully there are Convex components to leverage for these properties.

### Retries[​](#retries "Direct link to Retries")

By default, Convex mutations have these properties by default. However, calling LLMs require side-effects and using the network calls, which necessitates using actions. If you are only worried about retries, you can use the [Action Retrier](https://convex.dev/components/retrier) component.

However, keep reading, as the [Workpool](https://convex.dev/components/workpool) and [Workflow](https://convex.dev/components/workflow) components provide more robust solutions, including retries.

### Load balancing[​](#load-balancing "Direct link to Load balancing")

With long-running actions in a serverless environment, you may consume a lot of resources. And with tasks like ingesting data for RAG or other spiky workloads, there's a risk of running out of resources. To mitigate this, you can use the [Workpool](https://convex.dev/components/workpool) component. You can set a limit on the number of concurrent workers and add work asynchronously, with configurable retries and a callback to handle eventual success / failure.

However, if you also want to manage multi-step workflows, you should use the [Workflow](https://convex.dev/components/workflow) component, which also provides retries and load balancing out of the box.

### Durability and idempotency for multi-step workflows[​](#durability-and-idempotency-for-multi-step-workflows "Direct link to Durability and idempotency for multi-step workflows")

When doing multi-step workflows that can fail mid-way, you need to ensure that the workflow can be resumed from where it left off, without duplicating work. The [Workflow](https://convex.dev/components/workflow) builds on the [Workpool](https://convex.dev/components/workpool) to provide durable execution of long running functions with retries and delays.

Each step in the workflow is run, with the result recorded. Even if the server fails mid-way, it will resume with the latest incomplete step, with configurable retry settings.

## Using the Workflow component for long-lived durable workflows[​](#using-the-workflow-component-for-long-lived-durable-workflows "Direct link to Using the Workflow component for long-lived durable workflows")

The [Workflow component](https://convex.dev/components/workflow) is a great way to build long-lived, durable workflows. It handles retries and guarantees of eventually completing, surviving server restarts, and more. Read more about durable workflows in [this Stack post](https://stack.convex.dev/durable-workflows-and-strong-guarantees).

To use the agent alongside workflows, you can run individual idempotent steps that the workflow can run, each with configurable retries, with guarantees that the workflow will eventually complete. Even if the server crashes mid-workflow, the workflow will pick up from where it left off and run the next step. If a step fails and isn't caught by the workflow, the workflow's onComplete handler will get the error result.

### Using the Agent within a workflow[​](#using-the-agent-within-a-workflow "Direct link to Using the Agent within a workflow")

You can use the [Workflow component](https://convex.dev/components/workflow) to run agent flows. It handles retries and guarantees of eventually completing, surviving server restarts, and more. Read more about durable workflows [in this Stack post](https://stack.convex.dev/durable-workflows-and-strong-guarantees).

Within a workflow, each "step" is a single idempotent operation. The arguments and return values are stored as part of the workflow's state, so it can resume wherever it left off by replaying the history. This allows workflows to run for a long time, survive server restarts, retry individual steps, pause, and more.

Some Agent functions can be called directly from a workflow, passing `step` instead of `ctx`. Under the hood, these functions are calling `step.runMutation` instead of the `ctx.runMutation` that is otherwise done. The two calls are roughly the same, though there is more overhead associated with calling steps since the arguments and return values count towards the workflow's overall database bandwidth limit. As such, try to avoid passing large amounts of data in as arguments or returned from steps, and prefer to save that data and pass around IDs instead.

```
const workflow = new WorkflowManager(components.workflow);

export const supportAgentWorkflow = workflow.define({
  args: { prompt: v.string(), userId: v.string() },
  handler: async (step, { prompt, userId }) => {
    // Some functions can be called directly from a workflow, passing `step`
    // instead of `ctx`. This doesn't work for anything action-related.
    const { threadId } = await createThread(step, components.agent, {
      userId,
      title: prompt,
    });
    // Under the hood, these functions are calling step.runMutation,
    // so saving the message is a workflow step. The equivalent would be to call
    // step.runMutation with your own mutation that called saveMessage with ctx.
    const { messageId } = await saveMessage(step, components.agent, {
      threadId,
      prompt,
    });
    // For functions that require `fetch` or otherwise need an action, run them
    // as steps explicitly.
    const { text } = await step.runAction(
      internal.example.getSupport,
      { threadId, userId, promptMessageId: messageId },
      // Passing in a promptMessageId allows us to safely retry the step.
      // If it fails partway, the retry will re-use the same prompt message and
      // any existing responses.
      { retry: true },
    );
    const { object } = await step.runAction(
      internal.example.getStructuredSupport,
      {
        userId,
        prompt: text,
      },
    );
    // You can also run mutations as steps explicitly.
    await step.runMutation(internal.example.sendUserMessage, {
      userId,
      message: object.instruction,
    });
  },
});
```

### Exposing Agent functions as Convex Actions[​](#exposing-agent-functions-as-convex-actions "Direct link to Exposing Agent functions as Convex Actions")

You can expose the agent's capabilities as Convex functions to be used as steps in a workflow, as an alternative to writing an action for each step.

For an action that generates or streams text in a thread:

```
// Similar to thread.generateText / thread.streamText
export const getSupport = supportAgent.asTextAction({
  stopWhen: stepCountIs(10),
});
```

You can also expose a standalone action that generates an object.

```
// Similar to thread.generateObject / thread.streamObject
export const getStructuredSupport = supportAgent.asObjectAction({
  schema: z.object({
    analysis: z.string().describe("A detailed analysis of the user's request."),
    instruction: z.string().describe("A suggested action to take."),
  }),
});
```

See example code in [workflows/chaining.ts](https://github.com/get-convex/agent/blob/main/example/convex/workflows/chaining.ts).

## Complex workflow patterns[​](#complex-workflow-patterns "Direct link to Complex workflow patterns")

While there is only an example of a simple workflow here, there are many complex patterns that can be built with the Agent component:

* Dynamic routing to agents based on an LLM call or vector search
* Fanning out to LLM calls, then combining the results
* Orchestrating multiple agents
* Cycles of Reasoning and Acting (ReAct)
* Modeling a network of agents messaging each other
* Workflows that can be paused and resumed

<!-- -->

[Convex Component](https://www.convex.dev/components/workpool)

### [Workpool](https://www.convex.dev/components/workpool)

[Builds on the Action Retrier to provide parallelism limits and retries to manage large numbers of external requests efficiently.](https://www.convex.dev/components/workpool)

[Convex Component](https://www.convex.dev/components/workflow)

### [Workflow](https://www.convex.dev/components/workflow)

[Builds on the Workpool to provide durable execution of long running functions with retries and delays.](https://www.convex.dev/components/workflow)

---

# Source: https://docs.convex.dev/database/writing-data.md

# Writing Data

[Mutations](/functions/mutation-functions.md) can insert, update, and remove data from database tables.

## Inserting new documents[​](#inserting-new-documents "Direct link to Inserting new documents")

You can create new documents in the database with the [`db.insert`](/api/interfaces/server.GenericDatabaseWriter.md#insert) method:

convex/tasks.ts

TS

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

export const createTask = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    const taskId = await ctx.db.insert("tasks", { text: args.text });
    // do something with `taskId`
  },
});
```

The second argument to `db.insert` is a JavaScript object with data for the new document.

The same types of values that can be passed into and returned from [queries](/functions/query-functions.md) and [mutations](/functions/mutation-functions.md) can be written into the database. See [Data Types](/database/types.md) for the full list of supported types.

The `insert` method returns a globally unique ID for the newly inserted document.

## Updating existing documents[​](#updating-existing-documents "Direct link to Updating existing documents")

Given an existing document ID the document can be updated using the following methods:

1. The [`db.patch`](/api/interfaces/server.GenericDatabaseWriter.md#patch) method will patch an existing document, shallow merging it with the given partial document. New fields are added. Existing fields are overwritten. Fields set to `undefined` are removed.

convex/tasks.ts

TS

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

export const updateTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    const { id } = args;
    console.log(await ctx.db.get("tasks", id));
    // { text: "foo", status: { done: true }, _id: ... }

    // Add `tag` and overwrite `status`:
    await ctx.db.patch("tasks", id, { tag: "bar", status: { archived: true } });
    console.log(await ctx.db.get("tasks", id));
    // { text: "foo", tag: "bar", status: { archived: true }, _id: ... }

    // Unset `tag` by setting it to `undefined`
    await ctx.db.patch("tasks", id, { tag: undefined });
    console.log(await ctx.db.get("tasks", id));
    // { text: "foo", status: { archived: true }, _id: ... }
  },
});
```

2. The [`db.replace`](/api/interfaces/server.GenericDatabaseWriter.md#replace) method will replace the existing document entirely, potentially removing existing fields:

convex/tasks.ts

TS

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

export const replaceTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    const { id } = args;
    console.log(await ctx.db.get("tasks", id));
    // { text: "foo", _id: ... }

    // Replace the whole document
    await ctx.db.replace("tasks", id, { invalid: true });
    console.log(await ctx.db.get("tasks", id));
    // { invalid: true, _id: ... }
  },
});
```

## Deleting documents[​](#deleting-documents "Direct link to Deleting documents")

Given an existing document ID the document can be removed from the table with the [`db.delete`](/api/interfaces/server.GenericDatabaseWriter.md#delete) method.

convex/tasks.ts

TS

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

export const deleteTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, args) => {
    await ctx.db.delete("tasks", args.id);
  },
});
```

## Bulk inserts or updates[​](#bulk-inserts-or-updates "Direct link to Bulk inserts or updates")

If you are used to SQL you might be looking for some sort of bulk insert or bulk update statement. In Convex the entire `mutation` function is automatically a single transaction.

You can just insert or update in a loop in the mutation function. Convex queues up all database changes in the function and executes them all in a single transaction when the function ends, leading to a single efficient change to the database.

````
/**
 * Bulk insert multiple products into the database.
 *
 * Equivalent to the SQL:
 * ```sql
 * INSERT INTO products (product_id, product_name, category, price, in_stock)
 * VALUES
 *     ('Laptop Pro', 'Electronics', 1299.99, true),
 *     ('Wireless Mouse', 'Electronics', 24.95, true),
 *     ('Ergonomic Keyboard', 'Electronics', 89.50, true),
 *     ('Ultra HD Monitor', 'Electronics', 349.99, false),
 *     ('Wireless Headphones', 'Audio', 179.99, true);
 * ```
 */
export const bulkInsertProducts = mutation({
  args: {
    products: v.array(
      v.object({
        product_name: v.string(),
        category: v.string(),
        price: v.number(),
        in_stock: v.boolean(),
      }),
    ),
  },
  handler: async (ctx, args) => {
    const { products } = args;

    // Insert in a loop. This is efficient because Convex queues all the changes
    // to be executed in a single transaction when the mutation ends.
    for (const product of products) {
      const id = await ctx.db.insert("products", {
        product_name: product.product_name,
        category: product.category,
        price: product.price,
        in_stock: product.in_stock,
      });
    }
  },
});
````

## Migrations[​](#migrations "Direct link to Migrations")

Database migrations are done through the migration component. The component is designed to run online migrations to safely evolve your database schema over time. It allows you to resume from failures, and validate changes with dry runs.

[Convex Component](https://www.convex.dev/components/migrations)

### [Migrations](https://www.convex.dev/components/migrations)

[Framework for long running data migrations of live data.](https://www.convex.dev/components/migrations)

## Write performance and limits[​](#write-performance-and-limits "Direct link to Write performance and limits")

To prevent accidental writes of large amounts of records, queries and mutations enforce limits detailed [here](/production/state/limits.md#transactions).

---

# Source: https://docs.convex.dev/understanding/zen.md

# The Zen of Convex

[YouTube video player](https://www.youtube.com/embed/dyEWQ9s2ji4?si=ce-M8pt6EWDZ8tfd)

Convex is an opinionated framework, with every element designed to pull developers into [the pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/).

The Zen of Convex is a set of guidelines & best practices developers have discovered that keep their projects falling into this wonderful pit.

## Performance<!-- -->

### Double down on the [sync engine](/tutorial/.md#how-convex-works)

There's a reason why a deterministic, reactive database is the beating heart of Convex: the more you center your apps around its properties, the better your projects will fare over time. Your projects will be easier to understand and refactor. Your app's performance will stay screaming fast. You won't have any consistency or state management problems.

Use a query for nearly every app read

Queries are the reactive, automatically cacheable, consistent and resilient way to propagate data to your application and its jobs. With very few exceptions, every read operation in your app should happen via a query function.

Keep sync engine functions light & fast

In general, your mutations and queries should be working with less than a few hundred records and should aim to finish in less than 100ms. It's nearly impossible to maintain a snappy, responsive app if your synchronous transactions involve a lot more work than this.

Use actions sparingly and incrementally

Actions are wonderful for batch jobs and/or integrating with outside services. They're very powerful, but they're slower, more expensive, and Convex provides a lot fewer guarantees about their behavior. So never use an action if a query or mutation will get the job done.

### <!-- -->Don't over-complicate client-side state management

Convex builds in a ton of its own caching and consistency controls into the app's client library. Rather than reinvent the wheel, let your client-side code take advantage of these built-in performance boosts.

Let Convex handle caching & consistency

You might be tempted to quickly build your own local cache or state aggregation layer in Convex to sit between your components and your Convex functions. With Convex, most of the time, you won't end up needing this. More often than not, you can bind your components to Convex functions in pretty simple ways and things will Just Work and be plenty fast.

Be thoughtful about the return values of mutations

Mutation return values can be useful to trigger state changes in your app, but it's rarely a good idea to use them to set in-app state to update the UI. Let queries and the sync engine do that.

## Architecture<!-- -->

### <!-- -->Create server-side frameworks using "just code"

Convex's built-in primitives are pretty low level! They're just functions. What about authentication frameworks? What about object-relational mappings? Do you need to wait until Convex ships some in-built feature to get those? Nope. In general, you should solve composition and encapsulation problems in your server-side Convex code using the same methods you use for the rest of your TypeScript code bases. After all, this is why Convex is "just code!" [Stack](https://stack.convex.dev) always has [great](https://stack.convex.dev/functional-relationships-helpers) [examples](https://stack.convex.dev/wrappers-as-middleware-authentication) of ways to tackle [these needs](https://stack.convex.dev/row-level-security).

### <!-- -->Don't misuse actions

Actions are powerful, but it's important to be intentional in how they fit into your app's data flow.

Don't invoke actions directly from your app

In general, it's an anti-pattern to call actions from the browser. Usually, actions are running on some dependent record that should be living in a Convex table. So it's best trigger actions by invoking a mutation that both *writes* that dependent record and *schedules* the subsequent action to run in the background.

Don't think 'background jobs', think 'workflow'

When actions are involved, it's useful to write chains of effects and mutations, such as:

action code → mutation → more action code → mutation.

Then apps or other jobs can follow along with queries.

Record progress one step at a time

While actions *could* work with thousands of records and call dozens of APIs, it's normally best to do smaller batches of work and/or to perform individual transformations with outside services. Then record your progress with a mutation, of course. Using this pattern makes it easy to debug issues, resume partial jobs, and report incremental progress in your app's UI.

## Development workflow<!-- -->

### <!-- -->Keep the dashboard by your side

Working on your Convex project without using the dashboard is like driving a car with your eyes closed. The dashboard lets you view logs, give mutations/queries/actions a test run, make sure your configuration and codebase are as you expect, inspect your tables, generate schemas, etc. It's an invaluable part of your rapid development cycle.

### <!-- -->Don't go it alone

Between these [docs](https://docs.convex.dev), [Stack](https://stack.convex.dev), and [our community](https://convex.dev/community), someone has *probably* encountered the design or architectural issue you're facing. So why try to figure things out the hard way, when you can take advantage of a whole community's experience?

Leverage Convex developer search

With so many great resources from the Convex team & community, it can be hard to know where to look first. If you want a quick way to search across all of these, [we have a portal for that](https://search.convex.dev)!

Join the Convex community

Whether you're stuck on a tricky use case, you have a question or feature request for the Convex team, or you're excited to share the amazing app(s) you've built and help others learn, the Convex community is there for you! Join the party on [Discord](https://convex.dev/community).