Type parameters
Hierarchy
-
VirtualTableDefinition<Row> ↳VirtualSeriesDefinition
Constructors
constructor
• new VirtualSeriesDefinition<Row, Key, M>(source, contract, executor?)
Type parameters
Parameters
Overrides
VirtualTableDefinition.constructorProperties
[nativeTableType]
•Readonly [nativeTableType]: [Validator<Row, "required", any>, {}, {}, {}, false]
Type-only projection retained in emitted schema declarations.
Inherited from
VirtualTableDefinition.[nativeTableType]isSource
•Readonly isSource: false
Type-only source ownership, preserved by every builder method.
Inherited from
VirtualTableDefinition.isSourcerelations
•Readonly relations: Object
Type-only declared relations, preserved by every builder method.
Inherited from
VirtualTableDefinition.relationsvalidator
• validator:Validator<Row, "required", any>
Inherited from
VirtualTableDefinition.validatorvirtualSeriesDefinition
•Readonly virtualSeriesDefinition: true
temporal
•Readonly temporal: Readonly<{ key: Key ; observationId: FieldsOfType<Row, string> ; time: FieldsOfType<Row, bigint> ; correctionOrder: FieldsOfType<Row, bigint> ; measures: M }>
virtualTableDefinition
•Readonly virtualTableDefinition: true
Inherited from
VirtualTableDefinition.virtualTableDefinitionMethods
implements
▸ implements<I, Mappings, Writable>(contract, mapping): VirtualSeriesDefinition<Row, Key, M> & InterfaceMembership<I> & InterfaceWriteMappings<I, Writable[number] | RelationshipWriteKeys<Mappings>> & InterfaceNavigationIdentity<{ readonly [Name in string]: Mappings }>
Bind this concrete type to a shared object contract.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & InterfaceMembership<I> & InterfaceWriteMappings<I, Writable[number] | RelationshipWriteKeys<Mappings>> & InterfaceNavigationIdentity<{ readonly [Name in string]: Mappings }>
Inherited from
VirtualTableDefinition.implementsresource
▸ resource<Projection>(projection): VirtualSeriesDefinition<Row, Key, M> & { componentResource: Projection }
Protect this component table through its installation’s resource policy.
Schema assembly derives the read, write and disclosure policy entries.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & { componentResource: Projection }
Inherited from
VirtualTableDefinition.resourcepartitionLimit
▸ partitionLimit(name, limit): VirtualSeriesDefinition<Row, Key, M>
Enforce a maximum number of rows per exact index partition at every commit.
Deployment validates existing rows; authorization may reference this name.
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.partitionLimitaccess
▸ access<R, B>(definition, ...binding): VirtualSeriesDefinition<Row, Key, M> & ProtectedTable & { [accessTableBinding]: { resource: R ; options: B } }
Bind a semantic resource to this table’s storage. defineSchema infers
its table identity and parent index, validates the field bindings, and
installs the model’s read, write and disclosure policies.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & ProtectedTable & { [accessTableBinding]: { resource: R ; options: B } }
Inherited from
VirtualTableDefinition.access ▸ access<R>(definition, options): VirtualSeriesDefinition<Row, Key, M> & ProtectedTable & { [accessTableBinding]: { resource: R ; options: {} } }
Grant one read permission on an explicit list of source-owned fields.
Unlisted fields stay unreadable, including fields a connector adds later.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & ProtectedTable & { [accessTableBinding]: { resource: R ; options: {} } }
Inherited from
VirtualTableDefinition.access ▸ access(definition): VirtualSeriesDefinition<Row, Key, M> & ProtectedTable
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & ProtectedTable
Inherited from
VirtualTableDefinition.accessinput
▸ input(...limits): TableInput<Validator<Row, "required", any>>
The operation arguments of this table’s documents, each file field an
upload with its limits:
args: reports.input({ files: { maxSize: "10 MB", maxFiles: 2 } }).
Select the fields a caller may set with .pick(...) or .omit(...):
args: invoices.input().omit("archived").
Parameters
Returns
TableInput<Validator<Row, "required", any>>
Inherited from
VirtualTableDefinition.inputwriters
▸ writers<Path>(functions, options?): VirtualSeriesDefinition<Row, Key, M> & { isWriterOwned: true }
Restrict writes to these internal mutations, named by reference or by
"module:export" path. Pass the generated path type to check names as
you write them, without importing the modules that depend on this
schema: .writers<InternalMutationPath>(["orders:apply"]) with
import type { InternalMutationPath } from "./_generated/writers.js".
Deployment refuses a path that names no internal mutation. An optional
program names the installed component that must actually retain and
call that code; ordinary named calls gain no authority. An empty set
forbids all writes. Resource policies still apply. fields restricts a
top-level field to some of these writers, checked natively at commit:
.writers(["orders:apply", "orders:cancel"], \{ fields: \{ status: ["orders:cancel"] \} \}) lets only orders:cancel set or change status.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M> & { isWriterOwned: true }
Inherited from
VirtualTableDefinition.writersresourceRequests
▸ resourceRequests(options): VirtualSeriesDefinition<Row, Key, M>
Declare the native access-request writer. Attach the access model’s
read and original-basis write rules; ordinary mutations cannot change
this table. Approval inserts the requested grant and schedules expiry
in the decision’s transaction.
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.resourceRequestsretain
▸ retain(options): VirtualSeriesDefinition<Row, Key, M>
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
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.retainerasable
▸ erasable():VirtualSeriesDefinition<Row, Key, M>
Seal every revision of this table’s rows under a key that belongs to
that one record, so ctx.db.erase(id) reaches every retained copy of its
content: history, write-ahead logs, database backups and its search
index objects. Indexes may cover only top-level v.id fields, because
index keys are stored outside the sealed row. Search indexes are allowed:
erasing records rebuilds them without those records and destroys the
key of the index they replace. Vector indexes, maintained aggregates and
retained custody are refused. Declared transitions are sealed with the
row and erased with it; a process history is refused. A table becomes or
stops being erasable only while it is empty.
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.erasabletransitions
▸ transitions<Field>(field, options?): VirtualSeriesDefinition<Row, Key, M>
Record every change of a required top-level string field in the
native _transitions history, for every writer: ordinary mutations,
operations, administrative writes and source publication. Each commit
that changes the field records one transition from the committed value
to the final one, even if the transaction changed it several times,
with the commit timestamp, the committing identity or retained program,
and how long the row had been in the state it left.
An optional state graph classifies each change: initial states for
inserts, edges from each state and terminal states no change may
leave. A change the graph does not declare refuses the whole
transaction (TransitionRefused) under the default
undeclared: "refuse", or is kept and recorded with declared: false
under undeclared: "record", which a source-owned table requires.
Without a graph every present-state change is recorded and none refused; ordinary deletion requires a removable stage. A changed
graph applies to later commits only; each record names the revision it
was checked against.
Read the history with ctx.db.transitions(table, id, field), under the
reader’s current access to the row. Records are kept for retain.days
(default 730). Rows written before the declaration begin their history
with an observed entry whose time is unknown. Views and published
relations cannot declare transitions. On an erasable table each record
is sealed under its own key and erased with its row (at most 1024 per
row), and no process history may be named.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.transitionsaggregate
▸ aggregate(name, options): VirtualSeriesDefinition<Row, Key, M>
Maintain exact totals of this table per value of one to four 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
second, minute, hour, day, Monday-based week and calendar month. Compatible
finer buckets answer coarser summaries, including quarter and year, only
when the requested bucket contains complete stored buckets. 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. A write adds its change to each group it touches as a new record
and reads none, so concurrent writers of one group do not conflict; the
engine folds a group’s records into one shortly after. While the totals
are being built from existing rows, a writer conflicts only with the
build step counting its row and once with the step that completes the
build, and summaries use the bounded read until the build completes. One
answer reads at most 256 matching non-empty groups and 4,096 unfolded
records (compacting past that, until the engine catches up); a view’s
grouped lookup reads at most 64 before it evaluates the group from its
rows, within the view’s limits. 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. Once folded, records are one per
distinct key, the product of the dimensions’ cardinalities at most. A sum
past the int64 range refuses the summaries that serve it (overflow)
until the rows fit again; writes are never refused.
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 and target.covers: true: no row it counts is
presented on its own. Protected maintained totals require the native
access model, which enforces authority over every counted row. A custom
read rule uses bounded row evaluation; declaring collectionReaders does
not authorize its maintained totals. A group of a single row is served
like any other: under a read rule the
answer is fenced at release by the group terms it read, so deleting a
counted row restarts it.
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.aggregatelink
▸ link<Fields, Names>(this, endpoints, names?, options?): TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, LinkRelations<Validator<Row, "required", any>, Fields, Names, undefined>>
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.
One endpoint may name _storage when its minimum is zero and the relationship
declares read access and a governing rule. Such attachments require sealed
content and preserve the file’s existing source restrictions.
Each endpoint is a required reference of the link table, with the same
navigation defaults as reference: as reaches the
endpoint from a link row, inverse (default: this table’s name) lists an
endpoint’s incident link rows, and opposite, when named, lists the
endpoints linked to it. A link between two rows of one table needs
explicit names for both roles. With symmetric: true, both roles name
one typed population, with equal incident bounds and shared inverse and
opposite names. Insertion canonicalizes the pair; reversing a pair does
not create a second association. Self-pairs are allowed and count once.
Type parameters
Parameters
Returns
TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, LinkRelations<Validator<Row, "required", any>, Fields, Names, undefined>>
Inherited from
VirtualTableDefinition.link ▸ link<Fields, Names, Options>(this, endpoints, names, options): TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, LinkRelations<Validator<Row, "required", any>, Fields, Names, Options>>
Type parameters
Parameters
Returns
TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, LinkRelations<Validator<Row, "required", any>, Fields, Names, Options>>
Inherited from
VirtualTableDefinition.linkreference
▸ reference<Field, Options>(this, field, options?): TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, ReferenceRelation<Validator<Row, "required", any>, Field, Options>>
Declare a typed ID, interface reference, or distinct-target array at an object field path.
Concrete object parents may be optional; parent arrays and unions do not expand.
Array members must be distinct typed identities. Every member is validated
at commit; empty and absent optional arrays name no targets. Inverse bounds
count holder rows once per target, through a complete-or-refuse table scan
under the shared relationship work and byte limits. Array navigation orders
by typed identity and supports exact-basis pages, without property ordering
or seek windows. No multi-entry index or retained query support is implied.
The deployment keeps it true at every commit, for every writer: the
field names a live row of its table, deleting a row still referenced is
refused, and the rows naming one target stay within inverse.count
(default [0, "many"]; [0, 1] makes it one-to-one, a positive minimum
requires every target row to be referenced). The field may be optional;
changing it moves the reference, checking both targets.
It also names navigation for ctx.db.related and the application: as
(default: the field without its _id or Id suffix) reaches the
target, and inverse.as (default: this table’s name) lists the rows
naming a target. Names are unique among a table’s fields and navigations; a
collision is refused, never resolved by order. An undeclared v.id
keeps its plain meaning.
Type parameters
Parameters
Returns
TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, ReferenceRelation<Validator<Row, "required", any>, Field, Options>>
Inherited from
VirtualTableDefinition.referenceunchecked
▸ unchecked<Field>(this, field): VirtualSeriesDefinition<Row, Key, M>
Keep a top-level typed ID field as a plain ID, deliberately.
A plain v.id gains no integrity: it may name a deleted row, any number
of rows may name one target, and it has no navigation. Deploy reports
list every top-level ID of a table in the same schema that is neither a
.reference(...), a link endpoint nor marked here, so marking a field
records the choice and changes nothing else.
Type parameters
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.uncheckedrequire
▸ require(this, requirement): VirtualSeriesDefinition<Row, Key, M>
Strengthen the evidence required for every read of this source table.
Requirements compose with its existing floor; a later declaration cannot
weaken population, consistency or freshness requirements. Native admission
and reads check that the source can establish the requested evidence.
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.requireindexes
▸ ** 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[] }[]
Inherited from
VirtualTableDefinition.[ indexes](server.VirtualTableDefinition.md# indexes)self
▸Protected self(): TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, {}>
Work around for https://github.com/microsoft/TypeScript/issues/57035
Returns
TableDefinition<Validator<Row, "required", any>, {}, {}, {}, false, {}>
Inherited from
VirtualTableDefinition.selfvirtualTableBinding
▸ virtualTableBinding():Object
Returns
Object
Overrides
VirtualTableDefinition.virtualTableBindingmeasure
▸ measure<Name>(name): SeriesRelation<SeriesRelationType<Derive<Joined<Rel<{ __observation_id?: any = row.__observation_id; __observation_order: any }, "group", string, string, string, never, false>, Omit<Rel<{ __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint }, "group", string, string, string, never, false>, "origins"> & { origins: { observation: never } }, { __observation_id?: any = row.__observation_id; __observation_order: any } & { observation: { __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint } }, never, never>, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, string, never, "group">, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, never>, KeyValue<Row, Key>>
Build a resolved sample relation over all keys, for population reductions.
Type parameters
Parameters
Returns
SeriesRelation<SeriesRelationType<Derive<Joined<Rel<{ __observation_id?: any = row.__observation_id; __observation_order: any }, "group", string, string, string, never, false>, Omit<Rel<{ __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint }, "group", string, string, string, never, false>, "origins"> & { origins: { observation: never } }, { __observation_id?: any = row.__observation_id; __observation_order: any } & { observation: { __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint } }, never, never>, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, string, never, "group">, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, never>, KeyValue<Row, Key>>
for
▸ for(key): Readonly<{ measure: <Name>(name: Name) => SeriesRelation<SeriesRelationType<Derive<Joined<Rel<{ __observation_id?: any = row.__observation_id; __observation_order: any }, "group", string, string, string, never, false>, Omit<Rel<{ __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint }, "group", string, string, string, never, false>, "origins"> & { origins: { observation: never } }, { __observation_id?: any = row.__observation_id; __observation_order: any } & { observation: { __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint } }, never, never>, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, string, never, "group">, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, never>, KeyValue<Row, Key>> }>
Select one typed key without changing the source’s identity or lifetime.
Parameters
Returns
Readonly<{ measure: <Name>(name: Name) => SeriesRelation<SeriesRelationType<Derive<Joined<Rel<{ __observation_id?: any = row.__observation_id; __observation_order: any }, "group", string, string, string, never, false>, Omit<Rel<{ __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint }, "group", string, string, string, never, false>, "origins"> & { origins: { observation: never } }, { __observation_id?: any = row.__observation_id; __observation_order: any } & { observation: { __observation_id?: any = row.__observation_id; __observation_time?: any = row.__observation_time; __observation_order?: any = row.__observation_order; copies: bigint } }, never, never>, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, string, never, "group">, { time?: any = row.observation.__observation_time; order?: any = row.observation.__observation_order; value?: any }, never>, KeyValue<Row, Key>> }>
index
▸ index(_name, ..._configuration): never
Remote rows have no local storage on which to build an index.
Parameters
Returns
never
Inherited from
VirtualTableDefinition.indexsearchIndex
▸ searchIndex(_name, ..._configuration): never
Define a search index on this table.
To learn about search indexes, see Search.
Parameters
Returns
never
A TableDefinition with this search index included.
Inherited from
VirtualTableDefinition.searchIndexvectorIndex
▸ vectorIndex(_name, ..._configuration): never
Define a vector index on this table.
To learn about vector indexes, see Vector Search.
Parameters
Returns
never
A TableDefinition with this vector index included.
Inherited from
VirtualTableDefinition.vectorIndexspatialIndex
▸ spatialIndex(_name, ..._configuration): never
Index geometry without adding a field to its documents. Each index
generation derives its own private keys; changing the declaration uses
ordinary backfill and activation, without rewriting documents.
Parameters
Returns
never
Inherited from
VirtualTableDefinition.spatialIndexstaged
▸ staged(_schema): never
The provider’s boundary schema is not a staged local document schema.
Parameters
Returns
never
Inherited from
VirtualTableDefinition.stagedexport
▸ export():Object
Returns
Object
Inherited from
VirtualTableDefinition.exportkey
▸ key(...fields): VirtualSeriesDefinition<Row, Key, M>
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>
Inherited from
VirtualTableDefinition.keynavigation
▸ navigation(name, reference): VirtualSeriesDefinition<Row, Key, M>
Parameters
Returns
VirtualSeriesDefinition<Row, Key, M>