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

Interfaces

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>, false, never>
null() => SchemaType<null, false, never>
number() => SchemaType<number, false, never>
bigint() => SchemaType<bigint, false, never>
boolean() => SchemaType<boolean, false, never>
string() => SchemaType<string, false, never>
bytes() => SchemaType<ArrayBuffer, false, never>
literal<T>(literal: T) => SchemaType<T, false, never>
array<T>(values: SchemaType<T, false, any>) => SchemaType<T[], false, never>
set<T>(values: SchemaType<T, false, any>) => SchemaType<Set<T>, false, never>
map<K, V>(keys: SchemaType<K, false, any>, values: SchemaType<V, false, any>) => SchemaType<Map<K, V>, false, never>
object<T>(schema: T) => ObjectSchemaType<T>
union<T>(...schemaTypes: T) => SchemaType<T[number][``"type"``], false, T[number][``"fieldPaths"``]>
any() => SchemaType<any, false, string>
optional<T>(inner: T) => SchemaType<T["type"], true, T["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.union(
s.object({...}),
s.object({...})
)
);

Type parameters

NameType
DocumentSchemaextends SchemaType<Record<string, any>, false, 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.union(
s.object({...}),
s.object({...})
)
);

Type parameters

NameType
DocumentSchemaextends Record<string, SchemaType<any, 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, IsStrict>(schema, options?): SchemaDefinition<Schema, IsStrict>

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
IsStrictextends boolean = true

Parameters

NameTypeDescription
schemaSchemaA map from table name to TableDefinition for all of the tables in this project.
options?DefineSchemaOptions<IsStrict>Optional configuration. See DefineSchemaOptions for a full description.

Returns

SchemaDefinition<Schema, IsStrict>

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>: MaybeMakeLooseDataModel<{ [TableName in keyof SchemaDef["tables"] & string]: SchemaDef["tables"][TableName] extends TableDefinition<infer Document, infer FieldPaths, infer Indexes, infer SearchIndexes> ? MaybeMakeLooseTableInfo<Object, SchemaDef["isStrict"]> : never }, SchemaDef["isStrict"]>

Internal type used in Convex code generation!

Convert a SchemaDefinition into a GenericDataModel.

Type parameters

NameType
SchemaDefextends SchemaDefinition<any, boolean>