Skip to main content

Module: schema

Utilities for defining the schema of your Convex project.

Usage

Schemas should be placed in a schema.ts file in your convex/ directory.

Schema definitions should be built using defineSchema, defineTable, and s. Make sure to export the schema as the default export.

import { defineSchema, defineTable, s } from "convex/schema";

export default defineSchema({
messages: defineTable({
body: s.string(),
user: s.id("users"),
}),
users: defineTable({
name: s.string(),
}),
});

To learn more about schemas, see Defining a Schema.

Classes

Variables

s

Const s: Object

The schema builder.

This builder allows you to define the types of documents stored in Convex.

Type declaration

NameType
id<TableName>(tableName: TableName) => SchemaType<GenericId<TableName>, never>
null() => SchemaType<null, never>
number() => SchemaType<number, never>
bigint() => SchemaType<bigint, never>
boolean() => SchemaType<boolean, never>
string() => SchemaType<string, never>
bytes() => SchemaType<ArrayBuffer, never>
literal<T>(literal: T) => SchemaType<T, never>
array<T>(values: SchemaType<T, any>) => SchemaType<T[], never>
set<T>(values: SchemaType<T, any>) => SchemaType<Set<T>, never>
map<K, V>(keys: SchemaType<K, any>, values: SchemaType<V, any>) => SchemaType<Map<K, V>, never>
object<T>(schema: T) => ObjectSchemaType<T>
union<T>(...schemaTypes: T) => SchemaType<T[number][``"type"``], T[number][``"fieldPaths"``]>

Functions

defineTable

defineTable<DocumentSchema>(documentSchema): TableDefinition<ExtractDocument<DocumentSchema>, ExtractFieldPaths<DocumentSchema>>

Define a table in a schema.

You can either specify the schema of your documents as an object like

defineTable({
field: s.string()
});

or as a schema type like

defineTable(s.object({
field: s.string()
}));

Type parameters

NameType
DocumentSchemaextends SchemaType<Record<string, any>, any, DocumentSchema>

Parameters

NameTypeDescription
documentSchemaDocumentSchemaThe type of documents stored in this table.

Returns

TableDefinition<ExtractDocument<DocumentSchema>, ExtractFieldPaths<DocumentSchema>>

A TableDefinition for the table.

defineTable<DocumentSchema>(documentSchema): TableDefinition<ExtractDocument<ObjectSchemaType<DocumentSchema>>, ExtractFieldPaths<ObjectSchemaType<DocumentSchema>>>

Define a table in a schema.

You can either specify the schema of your documents as an object like

defineTable({
field: s.string()
});

or as a schema type like

defineTable(s.object({
field: s.string()
}));

Type parameters

NameType
DocumentSchemaextends Record<string, SchemaType<any, any>>

Parameters

NameTypeDescription
documentSchemaDocumentSchemaThe type of documents stored in this table.

Returns

TableDefinition<ExtractDocument<ObjectSchemaType<DocumentSchema>>, ExtractFieldPaths<ObjectSchemaType<DocumentSchema>>>

A TableDefinition for the table.


defineSchema

defineSchema<Schema>(schema): SchemaDefinition<Schema>

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

NameType
Schemaextends GenericSchema

Parameters

NameTypeDescription
schemaSchemaA map from table name to TableDefinition for all of the tables in this project.

Returns

SchemaDefinition<Schema>

The schema.

Type Aliases

GenericSchema

Ƭ GenericSchema: Record<string, TableDefinition>

A type describing the schema of a Convex project.

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


DataModelFromSchemaDefinition

Ƭ DataModelFromSchemaDefinition<SchemaDef>: SchemaDef extends SchemaDefinition<infer Schema> ? { [TableName in keyof Schema & string]: Schema[TableName] extends TableDefinition<infer Document, infer FieldPaths, infer TableIndexes> ? Object : never } : never

Internal type used in Convex code generation!

Convert a SchemaDefinition into a GenericDataModel.

Type parameters

NameType
SchemaDefextends SchemaDefinition<any>

DocumentMapFromSchemaDefinition

Ƭ DocumentMapFromSchemaDefinition<SchemaDef>: SchemaDef extends SchemaDefinition<infer Schema> ? { [TableName in keyof Schema & string]: Schema[TableName] extends TableDefinition<infer Document, any, any> ? Expand<IdField<TableName> & Document> : never } : never

Internal type used in Convex code generation!

Convert a SchemaDefinition into an object type that maps table names to their document types.

This is similar to GenericDataModel but it doesn't contain index information. This is nice for making some types appear simpler in VSCode.

Type parameters

NameType
SchemaDefextends SchemaDefinition<any>