Skip to main content

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 codegen in your Convex project. This will create a convex/_generated/server.ts file with the following functions, typed for your schema:

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

Example

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

Queries receive a db that implements the DatabaseReader interface.

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

export default query(async ({ db }, ...args: any[]): Promise<any> => {
// 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 DatabaseWriter interface.

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

export default mutation(async ({ db }, ...args: any[]): Promise<any> => {
// Your mutation code here!
});

Interfaces

Classes

Type Aliases

GenericDocument

Ƭ GenericDocument: Record<string, Value>

A document stored in Convex.


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").


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").


GenericTableIndexes

Ƭ GenericTableIndexes: Record<string, GenericIndexFields>

A type describing the indexes in a table.

It's a map from index name to fields in the index.


FieldTypeFromFieldPath

Ƭ FieldTypeFromFieldPath<Document, FieldPath>: FieldPath extends `${infer First}.${infer Second}` ? First extends keyof Document ? Document[First] extends GenericDocument ? FieldTypeFromFieldPath<Document[First], Second> : null : null : FieldPath extends keyof Document ? Document[FieldPath] : null

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

Type parameters

NameType
Documentextends GenericDocument
FieldPathextends string

GenericTableInfo

Ƭ GenericTableInfo: Object

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

Type declaration

NameType
documentGenericDocument
fieldPathsGenericFieldPaths
indexesGenericTableIndexes

DocumentByInfo

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

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

Type parameters

NameType
TableInfoextends GenericTableInfo

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

NameType
TableInfoextends GenericTableInfo

IndexNames

Ƭ IndexNames<TableInfo>: keyof TableInfo["indexes"]

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

Type parameters

NameType
TableInfoextends GenericTableInfo

NamedIndex

Ƭ NamedIndex<TableInfo, IndexName>: TableInfo["indexes"][`IndexName`]

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

Type parameters

NameType
TableInfoextends GenericTableInfo
IndexNameextends IndexNames<TableInfo>

GenericDataModel

Ƭ GenericDataModel: Record<string, GenericTableInfo>

A type describing the tables in a Convex deployment.

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


AnyDataModel

Ƭ AnyDataModel: Record<string, { document: any ; fieldPaths: GenericFieldPaths ; indexes: {} }>

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

This is the default before a schema is defined.


TableNamesInDataModel

Ƭ TableNamesInDataModel<DataModel>: keyof DataModel & string

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

Type parameters

NameType
DataModelextends GenericDataModel

NamedTableInfo

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

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

Type parameters

NameType
DataModelextends GenericDataModel
TableNameextends keyof DataModel

DocumentByName

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

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

Type parameters

NameType
DataModelextends GenericDataModel
TableNameextends TableNamesInDataModel<DataModel>

ExpressionOrValue

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

An Expression or a constant Value

Type parameters

NameType
Textends Value

MutationCtx

Ƭ MutationCtx<DataModel>: Object

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 TypeScript, use the MutationCtx type in convex/_generated/server.ts which is typed for your data model.

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

NameType
dbDatabaseWriter<DataModel>
authAuth

QueryCtx

Ƭ QueryCtx<DataModel>: Object

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.

If you're using TypeScript, use the QueryCtx type in convex/_generated/server.ts which is typed for your data model.

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

NameType
dbDatabaseReader<DataModel>
authAuth

PublicMutation

Ƭ PublicMutation<DataModel, Args, Output>: Object

Type parameters

NameType
DataModelextends GenericDataModel
Argsextends any[]
OutputOutput

Call signature

▸ (ctx, ...args): Output

A mutation function that is part of this app's public API.

You can create public mutations by wrapping your function in mutationGeneric and exporting it.

Parameters
NameType
ctxMutationCtx<DataModel>
...argsArgs
Returns

Output

Type declaration

NameType
isMutationtrue
isRegistered?true

PublicQuery

Ƭ PublicQuery<DataModel, Args, Output>: Object

Type parameters

NameType
DataModelextends GenericDataModel
Argsextends any[]
OutputOutput

Call signature

▸ (ctx, ...args): Output

A query function that is part of this app's public API.

You can create public queries by wrapping your function in queryGeneric and exporting it.

Parameters
NameType
ctxQueryCtx<DataModel>
...argsArgs
Returns

Output

Type declaration

NameType
isQuerytrue
isRegistered?true

ClientMutation

Ƭ ClientMutation<Mutation>: Mutation extends PublicMutation<any, infer Args, infer Output> ? (...args: Args) => UndefinedToNull<Awaited<Output>> : never

Internal type helper used by Convex code generation.

Used to convert from PublicMutation to the type exposed to the client.

Type parameters

NameType
Mutationextends PublicMutation<any, any, any>

ClientQuery

Ƭ ClientQuery<Query>: Query extends PublicQuery<any, infer Args, infer Output> ? (...args: Args) => UndefinedToNull<Awaited<Output>> : never

Internal type helper used by Convex code generation.

Used to convert from PublicQuery to the type exposed to the client.

Type parameters

NameType
Queryextends PublicQuery<any, any, any>

WithoutSystemFields

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

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

Type parameters

NameType
Documentextends GenericDocument

Functions

mutationGeneric

mutationGeneric<DataModel, Args, Output>(func): PublicMutation<DataModel, Args, Output>

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 TypeScript, use the mutation function in convex/_generated/server.ts which is typed for your data model.

Type parameters

NameType
DataModelextends GenericDataModel
Argsextends any[]
OutputOutput

Parameters

NameTypeDescription
func(ctx: MutationCtx<DataModel>, ...args: Args) => OutputThe mutation function. It receives a MutationCtx as its first argument.

Returns

PublicMutation<DataModel, Args, Output>

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


makeMutation

makeMutation<DataModel>(): <Args, Output>(func: (ctx: MutationCtx<DataModel>, ...args: Args) => Output) => PublicMutation<DataModel, Args, Output>

Internal method used by Convex code generation.

Type parameters

NameType
DataModelextends GenericDataModel

Returns

fn

▸ <Args, Output>(func): PublicMutation<DataModel, Args, Output>

Type parameters
NameType
Argsextends any[]
OutputOutput
Parameters
NameType
func(ctx: MutationCtx<DataModel>, ...args: Args) => Output
Returns

PublicMutation<DataModel, Args, Output>


queryGeneric

queryGeneric<DataModel, Args, Output>(func): PublicQuery<DataModel, Args, Output>

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 TypeScript, use the query function in convex/_generated/server.ts which is typed for your data model.

Type parameters

NameType
DataModelextends GenericDataModel
Argsextends any[]
OutputOutput

Parameters

NameTypeDescription
func(ctx: QueryCtx<DataModel>, ...args: Args) => OutputThe query function. It receives a QueryCtx as its first argument.

Returns

PublicQuery<DataModel, Args, Output>

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


makeQuery

makeQuery<DataModel>(): <Args, Output>(func: (ctx: QueryCtx<DataModel>, ...args: Args) => Output) => PublicQuery<DataModel, Args, Output>

Internal method used by Convex code generation.

Type parameters

NameType
DataModelextends GenericDataModel

Returns

fn

▸ <Args, Output>(func): PublicQuery<DataModel, Args, Output>

Type parameters
NameType
Argsextends any[]
OutputOutput
Parameters
NameType
func(ctx: QueryCtx<DataModel>, ...args: Args) => Output
Returns

PublicQuery<DataModel, Args, Output>