Module: server

Utilities for implementing server-side Convex query and mutation functions.

Usage

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
• mutation

If you aren't using TypeScript and code generation, you can use these untyped functions instead:

• queryGeneric
• mutationGeneric

Example

Convex functions are defined by using either the query or mutation wrappers.

Queries receive a db that implements the GenericDatabaseReader interface.

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

export default query(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 interface.

import { mutation } from "./_generated/server";

export default mutation(async ({ db }, { arg1, arg2 }) => {
  // Your mutation code here!
});

Classes

• Crons
• Expression
• IndexRange
• HttpRouter
• TableDefinition
• SchemaDefinition
• SearchFilter
• FilterExpression

Interfaces

• UserIdentity
• Auth
• CronJob
• BaseTableReader
• GenericDatabaseReader
• GenericDatabaseReaderWithTable
• GenericDatabaseWriter
• GenericDatabaseWriterWithTable
• BaseTableWriter
• FilterBuilder
• IndexRangeBuilder
• PaginationResult
• PaginationOptions
• QueryInitializer
• Query
• OrderedQuery
• GenericMutationCtx
• GenericQueryCtx
• GenericActionCtx
• ValidatedFunction
• Scheduler
• SearchIndexConfig
• VectorIndexConfig
• DefineSchemaOptions
• SystemDataModel
• SearchFilterBuilder
• SearchFilterFinalizer
• StorageReader
• StorageWriter
• StorageActionWriter
• VectorSearchQuery
• VectorFilterBuilder

References

UserIdentityAttributes

Re-exports UserIdentityAttributes

Type Aliases

FunctionType

Ƭ FunctionType: "query" | "mutation" | "action"

The type of a Convex function.

Defined in

server/api.ts:19

---

FunctionReference

Ƭ FunctionReference<Type, Visibility, Args, ReturnType, ComponentPath>: Object

A reference to a registered Convex function.

You can create a 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:

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 hook:

const result = useQuery(api.myModule.myFunction);

Type parameters

Name	Type	Description
Type	extends FunctionType	The type of the function ("query", "mutation", or "action").
Visibility	extends FunctionVisibility = "public"	The visibility of the function ("public" or "internal").
Args	extends 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

Name	Type
_type	Type
_visibility	Visibility
_args	Args
_returnType	ReturnType
_componentPath	ComponentPath

Defined in

server/api.ts:52

---

ApiFromModules

Ƭ ApiFromModules<AllModules>: FilterApi<ApiFromModulesAllowEmptyNodes<AllModules>, 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 FunctionReferences.

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

server/api.ts:255

---

FilterApi

Ƭ FilterApi<API, Predicate>: 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

Name
API
Predicate

Defined in

server/api.ts:279

---

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

server/api.ts:393

---

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

Name
API

Defined in

server/api.ts:401

---

FunctionArgs

Ƭ FunctionArgs<FuncRef>: FuncRef["_args"]

Given a FunctionReference, get the return type of the function.

This is represented as an object mapping argument names to values.

Type parameters

Name	Type
FuncRef	extends AnyFunctionReference

Defined in

server/api.ts:435

---

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

Name	Type
FuncRef	extends AnyFunctionReference

Defined in

server/api.ts:446

---

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

Name	Type
FuncRef	extends AnyFunctionReference
Options	Options

Defined in

server/api.ts:460

---

FunctionReturnType

Ƭ FunctionReturnType<FuncRef>: FuncRef["_returnType"]

Given a FunctionReference, get the return type of the function.

Type parameters

Name	Type
FuncRef	extends AnyFunctionReference

Defined in

server/api.ts:472

---

FunctionHandle

Ƭ FunctionHandle<Type, Args, ReturnType>: string & 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

Name	Type
Type	extends FunctionType
Args	extends DefaultFunctionArgs = any
ReturnType	any

Defined in

server/components/index.ts:35

---

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

Name	Type
Exports	extends ComponentExports = any

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 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

server/components/index.ts:84

---

AnyComponents

Ƭ AnyComponents: AnyChildComponents

Defined in

server/components/index.ts:442

---

GenericDocument

Ƭ GenericDocument: Record<string, Value>

A document stored in Convex.

Defined in

server/data_model.ts:9

---

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

server/data_model.ts:18

---

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

server/data_model.ts:29

---

GenericTableIndexes

Ƭ GenericTableIndexes: Record<string, 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

server/data_model.ts:37

---

GenericSearchIndexConfig

Ƭ GenericSearchIndexConfig: Object

A type describing the configuration of a search index.

Type declaration

Name	Type
searchField	string
filterFields	string

Defined in

server/data_model.ts:43

---

GenericTableSearchIndexes

Ƭ GenericTableSearchIndexes: Record<string, 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

server/data_model.ts:54

---

GenericVectorIndexConfig

Ƭ GenericVectorIndexConfig: Object

A type describing the configuration of a vector index.

Type declaration

Name	Type
vectorField	string
dimensions	number
filterFields	string

Defined in

server/data_model.ts:63

---

GenericTableVectorIndexes

Ƭ GenericTableVectorIndexes: Record<string, 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

server/data_model.ts:75

---

FieldTypeFromFieldPath

Ƭ FieldTypeFromFieldPath<Document, FieldPath>: FieldPath extends `${infer First}.${infer Second}` ? ValueFromUnion<Document, First, Record<never, never>> extends GenericDocument ? FieldTypeFromFieldPath<ValueFromUnion<Document, First, Record<never, never>>, Second> : ValueFromUnion<Document, First, Record<never, never>> extends GenericDocument | undefined ? FieldTypeFromFieldPath<ValueFromUnion<Document, First, Record<never, never>>, Second> | undefined : undefined : ValueFromUnion<Document, FieldPath, 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

Name	Type
Document	extends GenericDocument
FieldPath	extends string

Defined in

server/data_model.ts:104

---

GenericTableInfo

Ƭ GenericTableInfo: Object

A type describing the document type and indexes in a table.

Type declaration

Name	Type
document	GenericDocument
fieldPaths	GenericFieldPaths
indexes	GenericTableIndexes
searchIndexes	GenericTableSearchIndexes
vectorIndexes	GenericTableVectorIndexes

Defined in

server/data_model.ts:135

---

DocumentByInfo

Ƭ DocumentByInfo<TableInfo>: TableInfo["document"]

The type of a document in a table for a given GenericTableInfo.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:147

---

FieldPaths

Ƭ FieldPaths<TableInfo>: TableInfo["fieldPaths"]

The field paths in a table for a given GenericTableInfo.

These can either be field names (like "name") or references to fields on nested objects (like "properties.name").

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:157

---

Indexes

Ƭ Indexes<TableInfo>: TableInfo["indexes"]

The database indexes in a table for a given GenericTableInfo.

This will be an object mapping index names to the fields in the index.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:166

---

IndexNames

Ƭ IndexNames<TableInfo>: keyof Indexes<TableInfo>

The names of indexes in a table for a given GenericTableInfo.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:172

---

NamedIndex

Ƭ NamedIndex<TableInfo, IndexName>: Indexes<TableInfo>[IndexName]

Extract the fields of an index from a GenericTableInfo by name.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo
IndexName	extends IndexNames<TableInfo>

Defined in

server/data_model.ts:179

---

SearchIndexes

Ƭ SearchIndexes<TableInfo>: TableInfo["searchIndexes"]

The search indexes in a table for a given GenericTableInfo.

This will be an object mapping index names to the search index config.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:190

---

SearchIndexNames

Ƭ SearchIndexNames<TableInfo>: keyof SearchIndexes<TableInfo>

The names of search indexes in a table for a given GenericTableInfo.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:197

---

NamedSearchIndex

Ƭ NamedSearchIndex<TableInfo, IndexName>: SearchIndexes<TableInfo>[IndexName]

Extract the config of a search index from a GenericTableInfo by name.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo
IndexName	extends SearchIndexNames<TableInfo>

Defined in

server/data_model.ts:204

---

VectorIndexes

Ƭ VectorIndexes<TableInfo>: TableInfo["vectorIndexes"]

The vector indexes in a table for a given GenericTableInfo.

This will be an object mapping index names to the vector index config.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:215

---

VectorIndexNames

Ƭ VectorIndexNames<TableInfo>: keyof VectorIndexes<TableInfo>

The names of vector indexes in a table for a given GenericTableInfo.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo

Defined in

server/data_model.ts:222

---

NamedVectorIndex

Ƭ NamedVectorIndex<TableInfo, IndexName>: VectorIndexes<TableInfo>[IndexName]

Extract the config of a vector index from a GenericTableInfo by name.

Type parameters

Name	Type
TableInfo	extends GenericTableInfo
IndexName	extends VectorIndexNames<TableInfo>

Defined in

server/data_model.ts:229

---

GenericDataModel

Ƭ GenericDataModel: Record<string, GenericTableInfo>

A type describing the tables in a Convex project.

This is designed to be code generated with npx convex dev.

Defined in

server/data_model.ts:242

---

AnyDataModel

Ƭ AnyDataModel: Object

A GenericDataModel that considers documents to be any and does not support indexes.

This is the default before a schema is defined.

Index signature

▪ [tableName: string]: { document: any ; fieldPaths: GenericFieldPaths ; indexes: ; searchIndexes: ; vectorIndexes: }

Defined in

server/data_model.ts:251

---

TableNamesInDataModel

Ƭ TableNamesInDataModel<DataModel>: keyof DataModel & string

A type of all of the table names defined in a GenericDataModel.

Type parameters

Name	Type
DataModel	extends GenericDataModel

Defined in

server/data_model.ts:265

---

NamedTableInfo

Ƭ NamedTableInfo<DataModel, TableName>: DataModel[TableName]

Extract the TableInfo for a table in a GenericDataModel by table name.

Type parameters

Name	Type
DataModel	extends GenericDataModel
TableName	extends keyof DataModel

Defined in

server/data_model.ts:274

---

DocumentByName

Ƭ DocumentByName<DataModel, TableName>: DataModel[TableName]["document"]

The type of a document in a GenericDataModel by table name.

Type parameters

Name	Type
DataModel	extends GenericDataModel
TableName	extends TableNamesInDataModel<DataModel>

Defined in

server/data_model.ts:283

---

ExpressionOrValue

Ƭ ExpressionOrValue<T>: Expression<T> | T

An Expression or a constant Value

Type parameters

Name	Type
T	extends Value | undefined

Defined in

server/filter_builder.ts:38

---

Cursor

Ƭ Cursor: string

An opaque identifier used for paginating a database query.

Cursors are returned from paginate and represent the point of the query where the page of results ended.

To continue paginating, pass the cursor back into paginate in the PaginationOptions 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

server/pagination.ts:19

---

GenericMutationCtxWithTable

Ƭ GenericMutationCtxWithTable<DataModel>: Omit<GenericMutationCtx<DataModel>, "db"> & { db: GenericDatabaseWriterWithTable<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

Name	Type
DataModel	extends GenericDataModel

Defined in

server/registration.ts:109

---

GenericQueryCtxWithTable

Ƭ GenericQueryCtxWithTable<DataModel>: Omit<GenericQueryCtx<DataModel>, "db"> & { db: GenericDatabaseReaderWithTable<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

Name	Type
DataModel	extends GenericDataModel

Defined in

server/registration.ts:167

---

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

server/registration.ts:278

---

ArgsArray

Ƭ ArgsArray: OneArgArray | NoArgsArray

An array of arguments to a Convex function.

Convex functions can take either a single DefaultFunctionArgs object or no args at all.

Defined in

server/registration.ts:301

---

ArgsArrayToObject

Ƭ ArgsArrayToObject<Args>: Args extends OneArgArray<infer ArgsObject> ? ArgsObject : EmptyObject

Convert an ArgsArray into a single object type.

Empty arguments arrays are converted to EmptyObject.

Type parameters

Name	Type
Args	extends ArgsArray

Defined in

server/registration.ts:316

---

FunctionVisibility

Ƭ FunctionVisibility: "public" | "internal"

A type representing the visibility of a Convex function.

Defined in

server/registration.ts:324

---

RegisteredMutation

Ƭ RegisteredMutation<Visibility, Args, Returns>: (ctx: GenericMutationCtx<any>, args: Args) => Returns & VisibilityProperties<Visibility>

A mutation function that is part of this app.

You can create a mutation by wrapping your function in mutationGeneric or internalMutationGeneric and exporting it.

Type parameters

Name	Type
Visibility	extends FunctionVisibility
Args	extends DefaultFunctionArgs
Returns	Returns

Defined in

server/registration.ts:347

---

RegisteredQuery

Ƭ RegisteredQuery<Visibility, Args, Returns>: (ctx: GenericQueryCtx<any>, args: Args) => Returns & VisibilityProperties<Visibility>

A query function that is part of this app.

You can create a query by wrapping your function in queryGeneric or internalQueryGeneric and exporting it.

Type parameters

Name	Type
Visibility	extends FunctionVisibility
Args	extends DefaultFunctionArgs
Returns	Returns

Defined in

server/registration.ts:378

---

RegisteredAction

Ƭ RegisteredAction<Visibility, Args, Returns>: (ctx: GenericActionCtx<any>, args: Args) => Returns & VisibilityProperties<Visibility>

An action that is part of this app.

You can create an action by wrapping your function in actionGeneric or internalActionGeneric and exporting it.

Type parameters

Name	Type
Visibility	extends FunctionVisibility
Args	extends DefaultFunctionArgs
Returns	Returns

Defined in

server/registration.ts:409

---

PublicHttpAction

Ƭ PublicHttpAction: Object

Call signature

▸ (ctx, request): Promise<Response>

An HTTP action that is part of this app's public API.

You can create public HTTP actions by wrapping your function in httpActionGeneric and exporting it.

Parameters

Name	Type
ctx	GenericActionCtx<any>
request	Request

Returns

Promise<Response>

Type declaration

Name	Type
isHttp	true

Defined in

server/registration.ts:440

---

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 to add argument validation.

Type parameters

Name	Type
Ctx	Ctx
Args	extends ArgsArray
Returns	Returns

Defined in

server/registration.ts:479

---

ReturnValueForOptionalValidator

Ƭ ReturnValueForOptionalValidator<ReturnsValidator>: [ReturnsValidator] extends [Validator<any, any, any>] ? ValidatorTypeToReturnType<Infer<ReturnsValidator>> : [ReturnsValidator] extends [PropertyValidators] ? ValidatorTypeToReturnType<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

Name	Type
ReturnsValidator	extends Validator<any, any, any> | PropertyValidators | void

Defined in

server/registration.ts:581

---

ArgsArrayForOptionalValidator

Ƭ ArgsArrayForOptionalValidator<ArgsValidator>: [ArgsValidator] extends [Validator<any, any, any>] ? OneArgArray<Infer<ArgsValidator>> : [ArgsValidator] extends [PropertyValidators] ? OneArgArray<ObjectType<ArgsValidator>> : ArgsArray

Type parameters

Name	Type
ArgsValidator	extends GenericValidator | PropertyValidators | void

Defined in

server/registration.ts:589

---

DefaultArgsForOptionalValidator

Ƭ DefaultArgsForOptionalValidator<ArgsValidator>: [ArgsValidator] extends [Validator<any, any, any>] ? [Infer<ArgsValidator>] : [ArgsValidator] extends [PropertyValidators] ? [ObjectType<ArgsValidator>] : OneArgArray

Type parameters

Name	Type
ArgsValidator	extends GenericValidator | PropertyValidators | void

Defined in

server/registration.ts:597

---

MutationBuilder

Ƭ MutationBuilder<DataModel, Visibility>: <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation: { args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue) => RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Type parameters

Name	Type
DataModel	extends GenericDataModel
Visibility	extends FunctionVisibility

Type declaration

▸ <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation): RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Internal type helper used by Convex code generation.

Used to give mutationGeneric a type specific to your data model.

Type parameters

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
mutation	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Defined in

server/registration.ts:611

---

MutationBuilderWithTable

Ƭ MutationBuilderWithTable<DataModel, Visibility>: <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation: { args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue) => RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Type parameters

Name	Type
DataModel	extends GenericDataModel
Visibility	extends FunctionVisibility

Type declaration

▸ <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation): RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Internal type helper used by Convex code generation.

Used to give mutationGeneric a type specific to your data model.

Type parameters

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
mutation	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredMutation<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Defined in

server/registration.ts:704

---

QueryBuilder

Ƭ QueryBuilder<DataModel, Visibility>: <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query: { args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue) => RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Type parameters

Name	Type
DataModel	extends GenericDataModel
Visibility	extends FunctionVisibility

Type declaration

▸ <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Internal type helper used by Convex code generation.

Used to give queryGeneric a type specific to your data model.

Type parameters

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
query	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Defined in

server/registration.ts:797

---

QueryBuilderWithTable

Ƭ QueryBuilderWithTable<DataModel, Visibility>: <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query: { args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue) => RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Type parameters

Name	Type
DataModel	extends GenericDataModel
Visibility	extends FunctionVisibility

Type declaration

▸ <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query): RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Internal type helper used by Convex code generation.

Used to give queryGeneric a type specific to your data model.

Type parameters

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
query	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtxWithTable<DataModel>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredQuery<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Defined in

server/registration.ts:886

---

ActionBuilder

Ƭ ActionBuilder<DataModel, Visibility>: <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(func: { args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericActionCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericActionCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue) => RegisteredAction<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Type parameters

Name	Type
DataModel	extends GenericDataModel
Visibility	extends FunctionVisibility

Type declaration

▸ <ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(func): RegisteredAction<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Internal type helper used by Convex code generation.

Used to give actionGeneric a type specific to your data model.

Type parameters

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
func	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericActionCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericActionCtx<DataModel>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredAction<Visibility, ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

Defined in

server/registration.ts:975

---

HttpActionBuilder

Ƭ HttpActionBuilder: (func: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>) => PublicHttpAction

Type declaration

▸ (func): PublicHttpAction

Internal type helper used by Convex code generation.

Used to give httpActionGeneric a type specific to your data model and functions.

Parameters

Name	Type
func	(ctx: GenericActionCtx<any>, request: Request) => Promise<Response>

Returns

PublicHttpAction

Defined in

server/registration.ts:1070

---

RoutableMethod

Ƭ RoutableMethod: typeof 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

server/router.ts:31

---

RouteSpecWithPath

Ƭ RouteSpecWithPath: Object

A type representing a route to an HTTP action using an exact request URL path match.

Used by HttpRouter to route requests to HTTP actions.

Type declaration

Name	Type	Description
path	string	Exact HTTP request path to route.
method	RoutableMethod	HTTP method ("GET", "POST", ...) to route.
handler	PublicHttpAction	The HTTP action to execute.

Defined in

server/router.ts:56

---

RouteSpecWithPathPrefix

Ƭ RouteSpecWithPathPrefix: Object

A type representing a route to an HTTP action using a request URL path prefix match.

Used by HttpRouter to route requests to HTTP actions.

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	HTTP method ("GET", "POST", ...) to route.
handler	PublicHttpAction	The HTTP action to execute.

Defined in

server/router.ts:78

---

RouteSpec

Ƭ RouteSpec: RouteSpecWithPath | RouteSpecWithPathPrefix

A type representing a route to an HTTP action.

Used by HttpRouter to route requests to HTTP actions.

Defined in

server/router.ts:101

---

SchedulableFunctionReference

Ƭ SchedulableFunctionReference: FunctionReference<"mutation" | "action", "public" | "internal">

A FunctionReference that can be scheduled to run in the future.

Schedulable functions are mutations and actions that are public or internal.

Defined in

server/scheduler.ts:11

---

GenericSchema

Ƭ GenericSchema: Record<string, TableDefinition>

A type describing the schema of a Convex project.

This should be constructed using defineSchema, defineTable, and v.

Defined in

server/schema.ts:399

---

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 into a GenericDataModel.

Type parameters

Name	Type
SchemaDef	extends SchemaDefinition<any, boolean>

Defined in

server/schema.ts:530

---

SystemTableNames

Ƭ SystemTableNames: TableNamesInDataModel<SystemDataModel>

Defined in

server/schema.ts:588

---

StorageId

Ƭ StorageId: string

A reference to a file in storage.

This is used in the StorageReader and StorageWriter which are accessible in Convex queries and mutations via QueryCtx and MutationCtx respectively.

Defined in

server/storage.ts:11

---

FileStorageId

Ƭ FileStorageId: GenericId<"_storage"> | StorageId

Defined in

server/storage.ts:12

---

FileMetadata

Ƭ FileMetadata: Object

Metadata for a single file as returned by storage.getMetadata.

Type declaration

Name	Type	Description
storageId	StorageId	ID for referencing the file (eg. via storage.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

server/storage.ts:18

---

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

Name	Type
_creationTime	number

Defined in

server/system_fields.ts:11

---

IdField

Ƭ IdField<TableName>: Object

The _id field that Convex automatically adds to documents.

Type parameters

Name	Type
TableName	extends string

Type declaration

Name	Type
_id	GenericId<TableName>

Defined in

server/system_fields.ts:19

---

WithoutSystemFields

Ƭ WithoutSystemFields<Document>: Expand<BetterOmit<Document, keyof SystemFields | "_id">>

A Convex document with the system fields like _id and _creationTime omitted.

Type parameters

Name	Type
Document	extends GenericDocument

Defined in

server/system_fields.ts:28

---

WithOptionalSystemFields

Ƭ WithOptionalSystemFields<Document>: Expand<WithoutSystemFields<Document> & Partial<Pick<Document, keyof SystemFields | "_id">>>

A Convex document with the system fields like _id and _creationTime optional.

Type parameters

Name	Type
Document	extends GenericDocument

Defined in

server/system_fields.ts:37

---

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

Name	Type
by_id	["_id"]
by_creation_time	["_creationTime"]

Defined in

server/system_fields.ts:48

---

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

server/system_fields.ts:61

---

VectorSearch

Ƭ VectorSearch<DataModel, TableName, IndexName>: (tableName: TableName, indexName: IndexName, query: VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>) => Promise<{ _id: GenericId<TableName> ; _score: number }[]>

Type parameters

Name	Type
DataModel	extends GenericDataModel
TableName	extends TableNamesInDataModel<DataModel>
IndexName	extends VectorIndexNames<NamedTableInfo<DataModel, TableName>>

Type declaration

▸ (tableName, indexName, query): Promise<{ _id: GenericId<TableName> ; _score: number }[]>

Parameters

Name	Type
tableName	TableName
indexName	IndexName
query	VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>

Returns

Promise<{ _id: GenericId<TableName> ; _score: number }[]>

Defined in

server/vector_search.ts:55

---

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

Name	Type
ObjectType	extends Record<any, any>

Defined in

type_utils.ts:12

---

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

Name	Type
T	T
K	extends keyof T

Defined in

type_utils.ts:24

Variables

anyApi

• Const anyApi: AnyApi

A utility for constructing FunctionReferences 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

server/api.ts:427

---

paginationOptsValidator

• Const paginationOptsValidator: VObject<{ id: undefined | number ; endCursor: undefined | null | string ; maximumRowsRead: undefined | number ; maximumBytesRead: undefined | number ; numItems: number ; cursor: null | string }, { numItems: VFloat64<number, "required"> ; cursor: VUnion<null | string, [VString<string, "required">, VNull<null, "required">], "required", never> ; endCursor: VUnion<undefined | null | string, [VString<string, "required">, VNull<null, "required">], "optional", never> ; id: VFloat64<undefined | number, "optional"> ; maximumRowsRead: VFloat64<undefined | number, "optional"> ; maximumBytesRead: VFloat64<undefined | number, "optional"> }, "required", "id" | "numItems" | "cursor" | "endCursor" | "maximumRowsRead" | "maximumBytesRead">

A Validator for PaginationOptions.

This includes the standard PaginationOptions properties along with an optional cache-busting id property used by usePaginatedQuery.

Defined in

server/pagination.ts:131

---

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

server/router.ts:14

Functions

getFunctionName

▸ getFunctionName(functionReference): string

Get the name of a function from a 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

Name	Type	Description
functionReference	AnyFunctionReference	A FunctionReference to get the name of.

Returns

string

A string of the function's name.

Defined in

server/api.ts:78

---

makeFunctionReference

▸ makeFunctionReference<type, args, ret>(name): 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

Name	Type
type	extends FunctionType
args	extends DefaultFunctionArgs = any
ret	any

Parameters

Name	Type	Description
name	string	The identifier of the function. E.g. path/to/file:functionName

Returns

FunctionReference<type, "public", args, ret>

Defined in

server/api.ts:122

---

filterApi

▸ filterApi<API, Predicate>(api): 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

Name
API
Predicate

Parameters

Name	Type
api	API

Returns

FilterApi<API, Predicate>

Defined in

server/api.ts:301

---

createFunctionHandle

▸ createFunctionHandle<Type, Args, ReturnType>(functionReference): Promise<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

Name	Type
Type	extends FunctionType
Args	extends DefaultFunctionArgs
ReturnType	ReturnType

Parameters

Name	Type
functionReference	FunctionReference<Type, "public" | "internal", Args, ReturnType>

Returns

Promise<FunctionHandle<Type, Args, ReturnType>>

Defined in

server/components/index.ts:54

---

defineComponent

▸ defineComponent<Exports>(name): 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

Name	Type
Exports	extends ComponentExports = any

Parameters

Name	Type
name	string

Returns

ComponentDefinition<Exports>

Defined in

server/components/index.ts:359

---

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

AppDefinition

Defined in

server/components/index.ts:385

---

componentsGeneric

▸ componentsGeneric(): AnyChildComponents

Returns

AnyChildComponents

Defined in

server/components/index.ts:440

---

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

Name	Type
functionReference	any

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

server/components/paths.ts:20

---

cronJobs

▸ cronJobs(): Crons

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

Crons

Defined in

server/cron.ts:180

---

mutationGeneric

▸ mutationGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation): RegisteredMutation<"public", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
mutation	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtx<any>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredMutation<"public", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped mutation. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:615

---

internalMutationGeneric

▸ internalMutationGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(mutation): RegisteredMutation<"internal", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
mutation	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericMutationCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericMutationCtx<any>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredMutation<"internal", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped mutation. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:615

---

queryGeneric

▸ queryGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query): RegisteredQuery<"public", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
query	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtx<any>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredQuery<"public", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped query. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:801

---

internalQueryGeneric

▸ internalQueryGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(query): RegisteredQuery<"internal", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type
query	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericQueryCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericQueryCtx<any>, ...args: OneOrZeroArgs) => ReturnValue

Returns

RegisteredQuery<"internal", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped query. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:801

---

actionGeneric

▸ actionGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(func): RegisteredAction<"public", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type	Description
func	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericActionCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericActionCtx<any>, ...args: OneOrZeroArgs) => ReturnValue	The function. It receives a GenericActionCtx as its first argument.

Returns

RegisteredAction<"public", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped function. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:979

---

internalActionGeneric

▸ internalActionGeneric<ArgsValidator, ReturnsValidator, ReturnValue, OneOrZeroArgs>(func): RegisteredAction<"internal", 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

Name	Type
ArgsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnsValidator	extends void | Validator<any, "required", any> | PropertyValidators
ReturnValue	extends any = any
OneOrZeroArgs	extends ArgsArray | OneArgArray<Infer<ArgsValidator>> | OneArgArray<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<ArgsValidator[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<ArgsValidator[Property]> }>> = DefaultArgsForOptionalValidator<ArgsValidator>

Parameters

Name	Type	Description
func	{ args?: ArgsValidator ; returns?: ReturnsValidator ; handler: (ctx: GenericActionCtx<any>, ...args: OneOrZeroArgs) => ReturnValue } | (ctx: GenericActionCtx<any>, ...args: OneOrZeroArgs) => ReturnValue	The function. It receives a GenericActionCtx as its first argument.

Returns

RegisteredAction<"internal", ArgsArrayToObject<OneOrZeroArgs>, ReturnValue>

The wrapped function. Include this as an export to name it and make it accessible.

Defined in

server/registration.ts:979

---

httpActionGeneric

▸ httpActionGeneric(func): PublicHttpAction

Define a Convex HTTP action.

Parameters

Name	Type	Description
func	(ctx: GenericActionCtx<GenericDataModel>, request: Request) => Promise<Response>	The function. It receives an GenericActionCtx as its first argument, and a Request object as its second.

Returns

PublicHttpAction

The wrapped function. Route a URL path to this function in convex/http.js.

Defined in

server/impl/registration_impl.ts:454

---

httpRouter

▸ httpRouter(): HttpRouter

Return a new HttpRouter object.

Returns

HttpRouter

Defined in

server/router.ts:47

---

defineTable

▸ defineTable<DocumentSchema>(documentSchema): TableDefinition<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

Name	Type
DocumentSchema	extends Validator<Record<string, any>, "required", any>

Parameters

Name	Type	Description
documentSchema	DocumentSchema	The type of documents stored in this table.

Returns

TableDefinition<DocumentSchema>

A TableDefinition for the table.

Defined in

server/schema.ts:347

▸ defineTable<DocumentSchema>(documentSchema): TableDefinition<VObject<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

Name	Type
DocumentSchema	extends Record<string, GenericValidator>

Parameters

Name	Type	Description
documentSchema	DocumentSchema	The type of documents stored in this table.

Returns

TableDefinition<VObject<ObjectType<DocumentSchema>, DocumentSchema>>

A TableDefinition for the table.

Defined in

server/schema.ts:375

---

defineSchema

▸ defineSchema<Schema, StrictTableNameTypes>(schema, options?): SchemaDefinition<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

Name	Type
Schema	extends GenericSchema
StrictTableNameTypes	extends boolean = true

Parameters

Name	Type	Description
schema	Schema	A map from table name to TableDefinition for all of the tables in this project.
options?	DefineSchemaOptions<StrictTableNameTypes>	Optional configuration. See DefineSchemaOptions for a full description.

Returns

SchemaDefinition<Schema, StrictTableNameTypes>

The schema.

Defined in

server/schema.ts:513