Class: TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

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` = {}
`IsSource`	extends `boolean` = `false`

Hierarchy

TableDefinition ↳ ViewDefinition ↳ PublishedDefinition

Properties

isSource

• Readonly isSource: IsSource Type-only source ownership, preserved by every builder method.

validator

• validator: DocumentType

Methods

access

▸ access(definition): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Authorize reads of this complete table or view, without filtering rows or redacting fields. View inputs must independently permit disclosure. The query returns null or the existing positive validity result; throwing refuses access. Declare at most 32 distinct ordinary policy input tables.

Parameters

Name	Type
`definition`	`ReadAccess`

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

retain

▸ retain(options): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Keep derived data in retained custody. A write into this table is not a release: the engine retains the writing transaction’s source read obligations for every custody container the row is in, and every later read of a row in that container must satisfy them under current source policy. by names the containers: _id or a top-level string field that begins a declared index, or several of them (_id first), one container per named field. keys: "registered" declares that the containers are identities this component creates: a row may only enter a container whose name is the identity of a row inserted into a registered table keyed by _id, or that a transaction which read nothing wrote first. Reads confined to one container then carry that container alone, and an unregistered name reveals nothing. The default, keys: "derived", allows a key taken from protected data, with one container field, and decides the absence of a key by every write the table ever received. Removing or rekeying custody requires a migration.

Parameters

Name	Type
`options`	`Object`
`options.by`	`string` \| `string`[]
`options.keys?`	`"registered"` \| `"derived"`

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

aggregate

▸ aggregate(name, options): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Maintain exact totals of this table per value of one to three top-level dimensions: a row count and, for each sum field (a required v.int64()), an exact sum. A measure may also be a grouping dimension when totals need equality filters on that measure. The engine updates them in the same commit as every write to the table and rebuilds them from the rows when the declaration first appears or its shape changes, so application summaries grouped by these dimensions — over the whole table, or restricted by equality on declared dimensions — are exact at any size instead of bounded by one read. A view that only scans this table is answered from them too, including one with its own .access() rule, which is then asked the same question as this table’s. Calendar totals. time: { field: "at", unit: "day" } stores a UTC bucket instead of each raw instant for that grouping field. Units are day, Monday-based week and calendar month. Daily records also answer week and month summaries. Closed-open time ranges must align with the stored unit; put the time dimension immediately after any equality-pinned dimensions. Partial boundaries use the bounded ordinary read. Calendar totals do not provide indexed min/max. Values are milliseconds or exact UTC strings like 2026-03-02T12:34:56.789Z; null and missing stay distinct. Costs. Each distinct dimension-value key is one record that every write to a row in that group reads and rewrites, so concurrent writers of the same group serialize (one of them retries), exactly like writers of one row; writers of different existing groups do not. While the totals are being built from existing rows, writers also conflict with the build step that advances past their rows, and summaries use the bounded read until the build completes. One answer reads at most 256 matching groups. An equality filter on a later dimension is reached by stepping over the distinct values of the unfiltered dimensions before it, at most 256 of them, so put the dimensions a scope filters on first. Records are one per distinct key, the product of the dimensions’ cardinalities at most. Extremes. A group’s smallest and largest sum value are not stored: they are read from an ordinary index whose fields are the grouped and filtered dimensions, in any order, then that field, e.g. .index("by_status_amount", ["status", "amount"]) for a summary of amount by status. Two single-row reads per group keep them exact under inserts, updates and deletes; without such an index a summary’s min/max are null and it names the index that would serve them. Visibility. A total covers every row. On a table with .access() it is served only with visibility: "collectionReaders", and the rule is then asked about the whole table (or the rows an equality filter pins) with the aggregated properties. Declare it only for a rule that refuses that domain to any caller who may not read every row in it — a rule that decides per object must refuse an unpinned query demand to any caller without a role covering the whole table, as the access model’s generated read rules do. A rule that permits every query demand and filters object by object would leak totals of rows it hides. A group of a single row is served like any other: under a read rule the answer is fenced at release by the group records it read, so deleting a counted row restarts it.

Parameters

Name	Type
`name`	`string`
`options`	`Object`
`options.by`	`string`[]
`options.sum?`	`string`[]
`options.time?`	`Object`
`options.time.field`	`string`
`options.time.unit`	`"day"` \| `"month"` \| `"week"`
`options.visibility?`	`"collectionReaders"`

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

govern

▸ govern(this, definition): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Check every net change to this locally owned table before commit. The query observes the complete tentative transaction. Return one result per change, in order (readAccessResults): null for clock-independent permission, or { validUntil } for bounded permission; throw to reject the changes. A bare result or a missing one refuses. This applies to every writer, including ordinary composed mutations; it is not a mutation wrapper. The object form confines private reads to declared input tables. Use basis: "original" to authorize permission changes from the transaction’s original state; ordinary governing queries retain final-state reads.

Parameters

Name	Type
`this`	`GovernableTable`<`IsSource`, `TableDefinition`<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`, `IsSource`>>
`definition`	`GoverningDefinition`<`Expand`<`SystemFields` & `DocumentType`[`"type"`]> & { `_id`: `GenericId`<`string`> }>

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

link

▸ link<Fields>(this, endpoints): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Declare a binary association on required typed ID fields. Each bound counts live associations incident on an endpoint. A nonzero minimum applies to every live row in that endpoint’s declared table. Endpoints are immutable; ending and restoring a pair preserves its retained identity. Native identity and commit enforcement are required for admission.

Type parameters

Name	Type
`Fields`	extends `never`

Parameters

Name	Type
`this`	`LinkableTable`<`DocumentType`, `IsSource`, `TableDefinition`<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`, `IsSource`>>
`endpoints`	`Record`<`Fields`, readonly [`number`, `number` \| `"many"`]>

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

source

▸ source<S>(this, handle): TableDefinition<SourceDocumentType<DocumentType>, Indexes, SearchIndexes, VectorIndexes, true> Internal until native source admission is connected.

Type parameters

Name	Type
`S`	extends `Record`<`string`, `GenericValidator`>

Parameters

Name	Type
`this`	`TableDefinition`<`DocumentType`, `Indexes`, `SearchIndexes`, `VectorIndexes`, `IsSource`>
`handle`	`SourceHandle`<`S`> & [`DocumentType`[`"type"`]] extends [`Expand`<{ [Property in string \| number \| symbol]?: Exclude<Infer<S[Property]>, undefined> } & { [Property in string \| number \| symbol]: Infer<S[Property]> }>] ? [`Expand`<{ [Property in string \| number \| symbol]?: Exclude<Infer<S[Property]>, undefined> } & { [Property in string \| number \| symbol]: Infer<S[Property]> }>] extends [`any`[`any`]] ? `unknown` : `never` : `never`

Returns

TableDefinition<SourceDocumentType<DocumentType>, Indexes, SearchIndexes, VectorIndexes, true>

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. If you think you need this, please chime in on ths issue in the Bijection JS GitHub repo.

Returns

{ indexDescriptor: string ; fields: string[] }[]

index

▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, indexConfig): TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, …RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes, IsSource> 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.bijection.com/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, IsSource> A TableDefinition with this index included. ▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, fields): TableDefinition<DocumentType, Expand<Indexes & Record<IndexName, [FirstFieldPath, …RestFieldPaths[], "_creationTime"]>>, SearchIndexes, VectorIndexes, IsSource> 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, IsSource> A TableDefinition with this index included. ▸ index<IndexName, FirstFieldPath, RestFieldPaths>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> 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, IsSource> A TableDefinition with this index included.

searchIndex

▸ searchIndex<IndexName, SearchField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, Expand<SearchIndexes & Record<IndexName, { searchField: SearchField ; filterFields: FilterFields }>>, VectorIndexes, IsSource> 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, IsSource> A TableDefinition with this search index included. ▸ searchIndex<IndexName, SearchField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> 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, IsSource> A TableDefinition with this search index included.

vectorIndex

▸ vectorIndex<IndexName, VectorField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, Expand<VectorIndexes & Record<IndexName, { vectorField: VectorField ; dimensions: number ; filterFields: FilterFields }>>, IsSource> 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 }>>, IsSource> A TableDefinition with this vector index included. ▸ vectorIndex<IndexName, VectorField, FilterFields>(name, indexConfig): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> 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, IsSource> A TableDefinition with this vector index included.

self

▸ Protected self(): TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource> Work around for https://github.com/microsoft/TypeScript/issues/57035

Returns

TableDefinition<DocumentType, Indexes, SearchIndexes, VectorIndexes, IsSource>

​Type parameters

​Hierarchy

​Properties

​isSource

​validator

​Methods

​access

​Parameters

​Returns

​retain

​Parameters

​Returns

​aggregate

​Parameters

​Returns

​govern

​Parameters

​Returns

​link

​Type parameters

​Parameters

​Returns

​source

​Type parameters

​Parameters

​Returns

​indexes

​Returns

​index

​Type parameters

​Parameters

​Returns

​Type parameters

​Parameters

​Returns

​Type parameters

​Parameters

​Returns

​searchIndex

​Type parameters

​Parameters

​Returns

​Type parameters

​Parameters

​Returns

​vectorIndex

​Type parameters

​Parameters

​Returns

​Type parameters

​Parameters

​Returns

​self

​Returns

Type parameters

Hierarchy

Properties

isSource

validator

Methods

access

Parameters

Returns

retain

Parameters

Returns

aggregate

Parameters

Returns

govern

Parameters

Returns

link

Type parameters

Parameters

Returns

source

Type parameters

Parameters

Returns

indexes

Returns

index

Type parameters

Parameters

Returns

Type parameters

Parameters

Returns

Type parameters

Parameters

Returns

searchIndex

Type parameters

Parameters

Returns

Type parameters

Parameters

Returns

vectorIndex

Type parameters

Parameters

Returns

Type parameters

Parameters

Returns

self

Returns