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.js 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) => {
// 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) => {
// 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 an object mapping each index name to the fields in the index.


GenericSearchIndexConfig

Ƭ GenericSearchIndexConfig: Object

A type describing the configuration of a search index.

Type declaration

NameType
searchFieldstring
filterFieldsstring

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.


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
searchIndexesGenericTableSearchIndexes

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

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

NameType
TableInfoextends GenericTableInfo

IndexNames

Ƭ IndexNames<TableInfo>: keyof Indexes<TableInfo>

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

Type parameters

NameType
TableInfoextends GenericTableInfo

NamedIndex

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

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

Type parameters

NameType
TableInfoextends GenericTableInfo
IndexNameextends IndexNames<TableInfo>

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

NameType
TableInfoextends GenericTableInfo

SearchIndexNames

Ƭ SearchIndexNames<TableInfo>: keyof SearchIndexes<TableInfo>

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

Type parameters

NameType
TableInfoextends GenericTableInfo

NamedSearchIndex

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

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

Type parameters

NameType
TableInfoextends GenericTableInfo
IndexNameextends SearchIndexNames<TableInfo>

GenericDataModel

Ƭ GenericDataModel: Record<string, GenericTableInfo>

A type describing the tables in a Convex project.

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


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: {} }


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

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.


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

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

NameType
dbDatabaseWriter<DataModel>
authAuth
storageStorageWriter

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

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

NameType
dbDatabaseReader<DataModel>
authAuth
storageStorageReader

ActionCtx

Ƭ ActionCtx<API>: Object

A set of services for use within Convex action.

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

NameType
APIextends GenericAPI

Type declaration

NameType
query<Name>(name: Name, ...args: Parameters<NamedQuery<API, Name>>) => Promise<ReturnType<NamedQuery<API, Name>>>
mutation<Name>(name: Name, ...args: Parameters<NamedMutation<API, Name>>) => Promise<ReturnType<NamedMutation<API, Name>>>
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
argsArgs
outputOutput
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
argsArgs
outputOutput
isQuerytrue
isRegistered?true

PublicAction

Ƭ PublicAction<API, Args, Output>: Object

Type parameters

NameType
APIextends GenericAPI
Argsextends any[]
OutputOutput

Call signature

▸ (ctx, ...args): Output

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

You can create public action by wrapping your function in actionGeneric and exporting it.

Parameters
NameType
ctxActionCtx<API>
...argsArgs
Returns

Output

Type declaration

NameType
argsArgs
outputOutput
isActiontrue
isRegistered?true

MutationBuilderForDataModel

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

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

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

Internal type helper used by Convex code generation.

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

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

PublicMutation<DataModel, Args, Output>


QueryBuilderForDataModel

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

Type parameters

NameType
DataModelextends GenericDataModel

Type declaration

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

Internal type helper used by Convex code generation.

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

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

PublicQuery<DataModel, Args, Output>


ActionBuilderForAPI

Ƭ ActionBuilderForAPI<API>: <Args, Output>(func: (ctx: ActionCtx<API>, ...args: Args) => Output) => PublicAction<API, Args, Output>

Type parameters

NameType
APIextends GenericAPI

Type declaration

▸ <Args, Output>(func): PublicAction<API, Args, Output>

Internal type helper used by Convex code generation.

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

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

PublicAction<API, Args, Output>


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.


WithoutSystemFields

Ƭ WithoutSystemFields<Document>: Expand<BetterOmit<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 code generation, use the mutation function in convex/_generated/server.d.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.


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 code generation, use the query function in convex/_generated/server.d.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.


actionGeneric

actionGeneric<API, Args, Output>(func): PublicAction<API, Args, Output>

Define an action in this Convex app's public API.

Type parameters

NameType
APIextends GenericAPI
Argsextends any[]
OutputOutput

Parameters

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

Returns

PublicAction<API, Args, Output>

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