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:
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 GenericDatabaseReader interface.
import { query } from "./_generated/server";
export default query({
handler: async ({ db }, { arg1, arg2 }) => {
// Your (read-only) code here!
},
});
If your function needs to write to the database, such as inserting, updating,
or deleting documents, use mutation
instead which provides a db
that
implements the GenericDatabaseWriter interface.
import { mutation } from "./_generated/server";
export default mutation({
handler: 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
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
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
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
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
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
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
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
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
- Skipping arguments for functions that don't require arguments.
- Skipping the options object.
Type parameters
Name | Type |
---|---|
FuncRef | extends AnyFunctionReference |
Options | Options |
Defined in
FunctionReturnType
Ƭ FunctionReturnType<FuncRef
>: FuncRef
["_returnType"
]
Given a FunctionReference, get the return type of the function.
Type parameters
Name | Type |
---|---|
FuncRef | extends AnyFunctionReference |
Defined in
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
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
AnyChildComponents
Ƭ AnyChildComponents: Record
<string
, AnyComponentReference
>
Defined in
server/components/index.ts:402
AnyComponents
Ƭ AnyComponents: AnyChildComponents
Defined in
server/components/index.ts:442
GenericDocument
Ƭ GenericDocument: Record
<string
, Value
>
A document stored in Convex.
Defined in
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
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
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
GenericSearchIndexConfig
Ƭ GenericSearchIndexConfig: Object
A type describing the configuration of a search index.
Type declaration
Name | Type |
---|---|
searchField | string |
filterFields | string |
Defined in
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
GenericVectorIndexConfig
Ƭ GenericVectorIndexConfig: Object
A type describing the configuration of a vector index.
Type declaration
Name | Type |
---|---|
vectorField | string |
dimensions | number |
filterFields | string |
Defined in
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
FieldTypeFromFieldPath
Ƭ FieldTypeFromFieldPath<Document
, FieldPath
>: FieldTypeFromFieldPathInner
<Document
, FieldPath
> extends Value
| undefined
? FieldTypeFromFieldPathInner
<Document
, FieldPath
> : Value
| undefined
The type of a field in a document.
Note that this supports both simple fields like "name" and nested fields like "properties.name".
If the field is not present in the document it is considered to be undefined
.
Type parameters
Name | Type |
---|---|
Document | extends GenericDocument |
FieldPath | extends string |
Defined in
FieldTypeFromFieldPathInner
Ƭ FieldTypeFromFieldPathInner<Document
, FieldPath
>: FieldPath
extends `${infer First}.${infer Second}` ? ValueFromUnion
<Document
, First
, Record
<never
, never
>> extends infer FieldValue ? FieldValue
extends GenericDocument
? FieldTypeFromFieldPath
<FieldValue
, Second
> : undefined
: undefined
: ValueFromUnion
<Document
, FieldPath
, undefined
>
The inner type of FieldTypeFromFieldPath.
It's wrapped in a helper to coerce the type to Value | undefined
since some
versions of TypeScript fail to infer this type correctly.
Type parameters
Name | Type |
---|---|
Document | extends GenericDocument |
FieldPath | extends string |
Defined in
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
ExpressionOrValue
Ƭ ExpressionOrValue<T
>: Expression
<T
> | T
An Expression or a constant Value
Type parameters
Name | Type |
---|---|
T | extends Value | undefined |
Defined in
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
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
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
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.