Class: TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.
server.TableDefinition
The definition of a table within a schema.
This should be produced by using defineTable.
Type parameters
| Name | Type |
|---|---|
DocumentType | extends Validator<any, any, any> = Validator<any, any, any> |
Indexes | extends GenericTableIndexes = |
SearchIndexes | extends GenericTableSearchIndexes = |
VectorIndexes | extends GenericTableVectorIndexes = |
Properties
validator
• validator: DocumentType
Defined in
Methods
indexes
▸ ** indexes**(): { indexDescriptor: string ; fields: string[] }[]
This API is experimental: it may change or disappear.
Returns indexes defined on this table. Intended for the advanced use cases of dynamically deciding which index to use for a query.
Returns
{ indexDescriptor: string ; fields: string[] }[]
Defined in
index
▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, indexConfig): TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, ...RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes>
Define an index on this table.
Indexes speed up queries by allowing efficient lookups on specific fields.
Use .withIndex() in your queries to leverage them.
Index fields must be queried in the same order they are defined. If you
need to query by field2 then field1, create a separate index with
that field order.
Example
defineTable({
userId: v.id("users"),
status: v.string(),
updatedAt: v.number(),
})
// Name indexes after their fields:
.index("by_userId", ["userId"])
.index("by_status_updatedAt", ["status", "updatedAt"])
Best practice: Always include all index fields in the index name
(e.g., "by_field1_and_field2").
See
https://docs.convex.dev/database/reading-data/indexes
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
FirstFieldPath | extends any |
RestFieldPaths | extends ExtractFieldPaths<DocumentType>[] |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The index configuration object. |
indexConfig.fields | [FirstFieldPath, ...RestFieldPaths[]] | The fields to index, in order. Must specify at least one field. |
indexConfig.staged? | false | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, ...RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes>
A TableDefinition with this index included.
Defined in
▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, fields): TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, ...RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes>
Define an index on this table.
To learn about indexes, see Defining Indexes.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
FirstFieldPath | extends any |
RestFieldPaths | extends ExtractFieldPaths<DocumentType>[] |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
fields | [FirstFieldPath, ...RestFieldPaths[]] | The fields to index, in order. Must specify at least one field. |
Returns
TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, ...RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes>
A TableDefinition with this index included.
Defined in
▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
Define a staged index on this table.
For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.
If staged is true, the index will be staged and will not be enabled
until the staged flag is removed. Staged indexes do not block push
completion. Staged indexes cannot be used in queries.
To learn about indexes, see Defining Indexes.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
FirstFieldPath | extends any |
RestFieldPaths | extends ExtractFieldPaths<DocumentType>[] |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The index configuration object. |
indexConfig.fields | [FirstFieldPath, ...RestFieldPaths[]] | The fields to index, in order. Must specify at least one field. |
indexConfig.staged | true | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
A TableDefinition with this index included.
Defined in
searchIndex
▸ searchIndex<IndexName, SearchField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, Expand<SearchIndexes & Record<IndexName, { searchField: SearchField ; filterFields: FilterFields }>>, VectorIndexes>
Define a search index on this table.
To learn about search indexes, see Search.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
SearchField | extends any |
FilterFields | extends any = never |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The search index configuration object. |
indexConfig.searchField | SearchField | The field to index for full text search. This must be a field of type string. |
indexConfig.filterFields? | FilterFields[] | Additional fields to index for fast filtering when running search queries. |
indexConfig.staged? | false | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Indexes, Expand<SearchIndexes & Record<IndexName, { searchField: SearchField ; filterFields: FilterFields }>>, VectorIndexes>
A TableDefinition with this search index included.
Defined in
▸ searchIndex<IndexName, SearchField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
Define a staged search index on this table.
For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.
If staged is true, the index will be staged and will not be enabled
until the staged flag is removed. Staged indexes do not block push
completion. Staged indexes cannot be used in queries.
To learn about search indexes, see Search.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
SearchField | extends any |
FilterFields | extends any = never |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The search index configuration object. |
indexConfig.searchField | SearchField | The field to index for full text search. This must be a field of type string. |
indexConfig.filterFields? | FilterFields[] | Additional fields to index for fast filtering when running search queries. |
indexConfig.staged | true | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
A TableDefinition with this search index included.
Defined in
vectorIndex
▸ vectorIndex<IndexName, VectorField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, Expand<VectorIndexes & Record<IndexName, { vectorField: VectorField ; dimensions: number ; filterFields: FilterFields }>>>
Define a vector index on this table.
To learn about vector indexes, see Vector Search.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
VectorField | extends any |
FilterFields | extends any = never |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The vector index configuration object. |
indexConfig.vectorField | VectorField | The field to index for vector search. This must be a field of type v.array(v.float64()) (or a union) |
indexConfig.dimensions | number | The length of the vectors indexed. This must be between 2 and 2048 inclusive. |
indexConfig.filterFields? | FilterFields[] | Additional fields to index for fast filtering when running vector searches. |
indexConfig.staged? | false | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, Expand<VectorIndexes & Record<IndexName, { vectorField: VectorField ; dimensions: number ; filterFields: FilterFields }>>>
A TableDefinition with this vector index included.
Defined in
▸ vectorIndex<IndexName, VectorField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
Define a staged vector index on this table.
For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later.
If staged is true, the index will be staged and will not be enabled
until the staged flag is removed. Staged indexes do not block push
completion. Staged indexes cannot be used in queries.
To learn about vector indexes, see Vector Search.
Type parameters
| Name | Type |
|---|---|
IndexName | extends string |
VectorField | extends any |
FilterFields | extends any = never |
Parameters
| Name | Type | Description |
|---|---|---|
name | IndexName | The name of the index. |
indexConfig | Object | The vector index configuration object. |
indexConfig.vectorField | VectorField | The field to index for vector search. This must be a field of type v.array(v.float64()) (or a union) |
indexConfig.dimensions | number | The length of the vectors indexed. This must be between 2 and 2048 inclusive. |
indexConfig.filterFields? | FilterFields[] | Additional fields to index for fast filtering when running vector searches. |
indexConfig.staged | true | Whether the index should be staged. For large tables, index backfill can be slow. Staging an index allows you to push the schema and enable the index later. If staged is true, the index will be staged and will not be enabled until the staged flag is removed. Staged indexes do not block push completion. Staged indexes cannot be used in queries. |
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
A TableDefinition with this vector index included.
Defined in
staged
▸ staged(documentSchema): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
Stage changes to this table's document validator.
Convex validates the staged validator against the table's existing
documents in the background, while the validator passed to
defineTable remains the one enforced on writes. Once
the background validation succeeds, apply the staged changes
and remove .staged().
For an object validator, pass only the fields to add or replace. Fields
omitted from the changes keep their enforced validators.
Set a field to undefined to remove it from the staged validator.
For nested objects, you must specify the full object validator.
defineTable({
apple: v.string(),
banana: v.number(),
legacy: v.optional(v.string()),
}).staged({
banana: v.union(v.string(), v.number()),
legacy: undefined,
})
See Staged validators.
Parameters
| Name | Type | Description |
|---|---|---|
documentSchema | Validator<Record<string, any>, "required", any> | Record<string, undefined | GenericValidator> | Field changes for a table defined as an object or v.any(), or a full schema validator specifying the proposed next document type. Use a full schema validator for a table defined as a union. |
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
A TableDefinition with the staged validator attached.
Defined in
self
▸ Protected self(): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>
Work around for https://github.com/microsoft/TypeScript/issues/57035
Returns
TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes>