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
- UserIdentity
- Auth
- DatabaseReader
- DatabaseWriter
- FilterBuilder
- IndexRangeBuilder
- PaginationResult
- PaginationOptions
- QueryInitializer
- Query
- OrderedQuery
- StorageReader
- StorageWriter
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
| Name | Type |
|---|---|
searchField | string |
filterFields | string |
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
| Name | Type |
|---|---|
Document | extends GenericDocument |
FieldPath | extends string |
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 |
DocumentByInfo
Ƭ DocumentByInfo<TableInfo>: TableInfo["document"]
The type of a document in a table for a given GenericTableInfo.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends 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
| Name | Type |
|---|---|
TableInfo | extends 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
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
IndexNames
Ƭ IndexNames<TableInfo>: keyof Indexes<TableInfo>
The names of indexes in a table for a given GenericTableInfo.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
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> |
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 |
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 |
NamedSearchIndex
Ƭ NamedSearchIndex<TableInfo, IndexName>: SearchIndexes<TableInfo>[IndexName]
Extract the fields of an index from a GenericTableInfo by name.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
IndexName | extends 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
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
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 |
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> |
ExpressionOrValue
Ƭ ExpressionOrValue<T>: Expression<T> | T
An Expression or a constant Value
Type parameters
| Name | Type |
|---|---|
T | extends 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
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Type declaration
| Name | Type |
|---|---|
db | DatabaseWriter<DataModel> |
auth | Auth |
storage | StorageWriter |
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
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Type declaration
| Name | Type |
|---|---|
db | DatabaseReader<DataModel> |
auth | Auth |
storage | StorageReader |
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
| Name | Type |
|---|---|
API | extends GenericAPI |
Type declaration
| Name | Type |
|---|---|
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>>> |
auth | Auth |
PublicMutation
Ƭ PublicMutation<DataModel, Args, Output>: Object
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
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
| Name | Type |
|---|---|
ctx | MutationCtx<DataModel> |
...args | Args |
Returns
Output
Type declaration
| Name | Type |
|---|---|
args | Args |
output | Output |
isMutation | true |
isRegistered? | true |
PublicQuery
Ƭ PublicQuery<DataModel, Args, Output>: Object
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
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
| Name | Type |
|---|---|
ctx | QueryCtx<DataModel> |
...args | Args |
Returns
Output
Type declaration
| Name | Type |
|---|---|
args | Args |
output | Output |
isQuery | true |
isRegistered? | true |
PublicAction
Ƭ PublicAction<API, Args, Output>: Object
Type parameters
| Name | Type |
|---|---|
API | extends GenericAPI |
Args | extends any[] |
Output | Output |
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
| Name | Type |
|---|---|
ctx | ActionCtx<API> |
...args | Args |
Returns
Output
Type declaration
| Name | Type |
|---|---|
args | Args |
output | Output |
isAction | true |
isRegistered? | true |
MutationBuilderForDataModel
Ƭ MutationBuilderForDataModel<DataModel>: <Args, Output>(func: (ctx: MutationCtx<DataModel>, ...args: Args) => Output) => PublicMutation<DataModel, Args, Output>
Type parameters
| Name | Type |
|---|---|
DataModel | extends 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
| Name | Type |
|---|---|
Args | extends any[] |
Output | Output |
Parameters
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
DataModel | extends 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
| Name | Type |
|---|---|
Args | extends any[] |
Output | Output |
Parameters
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
API | extends 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
| Name | Type |
|---|---|
Args | extends any[] |
Output | Output |
Parameters
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
Document | extends 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
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Parameters
| Name | Type | Description |
|---|---|---|
func | (ctx: MutationCtx<DataModel>, ...args: Args) => Output | The 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
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Parameters
| Name | Type | Description |
|---|---|---|
func | (ctx: QueryCtx<DataModel>, ...args: Args) => Output | The 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
| Name | Type |
|---|---|
API | extends GenericAPI |
Args | extends any[] |
Output | Output |
Parameters
| Name | Type | Description |
|---|---|---|
func | (ctx: ActionCtx<API>, ...args: Args) => Output | The 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.