Interface: LogicalQuery<TableInfo>

server.LogicalQuery A population over a logical domain. The engine chooses an index that delivers its order, (field, _creationTime, _id), and refuses the read with ReadIndexRequired when no declared index does. Every admitted index returns the same rows in the same order; pagination continues on the index that served its first page and authorizes every page again.

const page = await ctx.db
  .query("documents")
  .visible()
  .where({ projectId })
  .orderBy("_creationTime", "desc")
  .select(["title"])
  .paginate(paginationOpts);

Type parameters

Name	Type
`TableInfo`	extends `GenericTableInfo`

Hierarchy

SelectableOrderedQuery<TableInfo> ↳ LogicalQuery

Methods

groupBy

▸ groupBy<Path>(field): SelectionAnalysis<TableInfo["fieldPaths"], true, false, false> Group this selection’s samples by one record field.

Type parameters

Name	Type
`Path`	extends `TableInfo`[`"fieldPaths"`]

Parameters

Name	Type
`field`	`SeriesSelectionOnly`<`TableInfo`, `Path`>

Returns

SelectionAnalysis<TableInfo["fieldPaths"], true, false, false>

Inherited from

SelectableOrderedQuery.groupBy

window

▸ window(spec): SelectionAnalysis<TableInfo["fieldPaths"], false, true, false> Window this selection’s event time on a fixed-duration grid.

Parameters

Name	Type
`spec`	`SeriesSelectionOnly`<`TableInfo`, `WindowSpec`>

Returns

SelectionAnalysis<TableInfo["fieldPaths"], false, true, false>

Inherited from

SelectableOrderedQuery.window

signal

▸ signal(policy): SelectionAnalysis<TableInfo["fieldPaths"], false, false, true> Interpret one series’ samples over the selection’s bounded interval.

Parameters

Name	Type
`policy`	`SeriesSelectionOnly`<`TableInfo`, `SignalPolicy`<`TableInfo`[`"fieldPaths"`]>>

Returns

SelectionAnalysis<TableInfo["fieldPaths"], false, false, true>

Inherited from

SelectableOrderedQuery.signal

explain

▸ explain(): ReadPath Inspect the structural plan without consuming the query or deciding authority.

Returns

ReadPath

Inherited from

SelectableOrderedQuery.explain

withBudget

▸ withBudget(budget): SelectableOrderedQuery<TableInfo>

Parameters

Name	Type
`budget`	`ReadBudget`

Returns

SelectableOrderedQuery<TableInfo>

Inherited from

SelectableOrderedQuery.withBudget

collectWithDiagnostics

▸ collectWithDiagnostics(): Promise<ReadReport<DocumentByInfo<TableInfo>, ReadUsage>>

Returns

Promise<ReadReport<DocumentByInfo<TableInfo>, ReadUsage>>

Inherited from

SelectableOrderedQuery.collectWithDiagnostics

takeWithDiagnostics

▸ takeWithDiagnostics(n): Promise<ReadReport<DocumentByInfo<TableInfo>, ReadUsage>>

Parameters

Name	Type
`n`	`number`

Returns

Promise<ReadReport<DocumentByInfo<TableInfo>, ReadUsage>>

Inherited from

SelectableOrderedQuery.takeWithDiagnostics

filter

▸ filter(predicate): LogicalQuery<TableInfo> Filter the query output, returning only the values for which predicate evaluates to true. Important: Prefer using .withIndex() over .filter() whenever possible. Filters scan all documents matched so far and discard non-matches, while indexes efficiently skip non-matching documents. Define an index in your schema for fields you filter on frequently.

Parameters

Name	Type	Description
`predicate`	(`q`: `FilterBuilder`<`TableInfo`>) => `ExpressionOrValue`<`boolean`>	An Expression constructed with the supplied FilterBuilder that specifies which documents to keep.

Returns

LogicalQuery<TableInfo>

A new OrderedQuery with the given filter predicate applied.

Inherited from

SelectableOrderedQuery.filter

take

▸ take(n, options): Promise<ReadResult<DocumentByInfo<TableInfo>[]>> Execute the query and return the first n results.

Parameters

Name	Type	Description
`n`	`number`	The number of items to take.
`options`	`ReadAvailabilityOptions`	-

Returns

Promise<ReadResult<DocumentByInfo<TableInfo>[]>>

An array of the first n results of the query (or less if the query doesn’t have n results).

Inherited from

SelectableOrderedQuery.take ▸ take(n): Promise<DocumentByInfo<TableInfo>[]>

Parameters

Name	Type
`n`	`number`

Returns

Promise<DocumentByInfo<TableInfo>[]>

Inherited from

SelectableOrderedQuery.take

collect

▸ collect(options): Promise<ReadResult<DocumentByInfo<TableInfo>[]>> Execute the query and return all of the results as an array. Warning: This loads every matching document into memory. If the result set can grow unbounded as your database grows, .collect() will eventually cause performance problems or hit limits. Only use .collect() when the result set is tightly bounded (e.g., a known small number of items). Prefer .first(), .unique(), .take(n), or .paginate() when the result set may be large or unbounded. For processing many results without loading all into memory, use the Query as an AsyncIterable with for await...of.

Parameters

Name	Type
`options`	`ReadAvailabilityOptions`

Returns

Promise<ReadResult<DocumentByInfo<TableInfo>[]>>

An array of all of the query’s results.

Inherited from

SelectableOrderedQuery.collect ▸ collect(): Promise<DocumentByInfo<TableInfo>[]>

Returns

Promise<DocumentByInfo<TableInfo>[]>

Inherited from

SelectableOrderedQuery.collect

first

▸ first(options): Promise<ReadResult<null | DocumentByInfo<TableInfo>>> Execute the query and return the first result if there is one.

Parameters

Name	Type
`options`	`ReadAvailabilityOptions`

Returns

Promise<ReadResult<null | DocumentByInfo<TableInfo>>>

The first value of the query or null if the query returned no results.

Inherited from

SelectableOrderedQuery.first ▸ first(): Promise<null | DocumentByInfo<TableInfo>>

Returns

Promise<null | DocumentByInfo<TableInfo>>

Inherited from

SelectableOrderedQuery.first

unique

▸ unique(options): Promise<ReadResult<null | DocumentByInfo<TableInfo>>> Execute the query and return the singular result if there is one. Use this when you expect exactly zero or one result, for example when querying by a unique field. If the query matches more than one document, this will throw an error. Example

const user = await ctx.db
  .query("users")
  .withIndex("by_email", (q) => q.eq("email", "alice@example.com"))
  .unique();

Throws Will throw an error if the query returns more than one result.

Parameters

Name	Type
`options`	`ReadAvailabilityOptions`

Returns

Promise<ReadResult<null | DocumentByInfo<TableInfo>>>

The single result returned from the query or null if none exists.

Inherited from

SelectableOrderedQuery.unique ▸ unique(): Promise<null | DocumentByInfo<TableInfo>>

Returns

Promise<null | DocumentByInfo<TableInfo>>

Inherited from

SelectableOrderedQuery.unique

paginate

▸ paginate(paginationOpts, options): Promise<ReadResult<PaginationResult<DocumentByInfo<TableInfo>>>> Load a page of n results and obtain a Cursor for loading more. Note: If this is called from a reactive query function the number of results may not match paginationOpts.numItems! paginationOpts.numItems is only an initial value. After the first invocation, paginate will return all items in the original query range. This ensures that all pages will remain adjacent and non-overlapping.

Parameters

Name	Type	Description
`paginationOpts`	`PaginationOptions`	A PaginationOptions object containing the number of items to load and the cursor to start at.
`options`	`ReadAvailabilityOptions`	-

Returns

Promise<ReadResult<PaginationResult<DocumentByInfo<TableInfo>>>> A PaginationResult containing the page of results and a cursor to continue paginating.

Inherited from

SelectableOrderedQuery.paginate ▸ paginate(paginationOpts): Promise<PaginationResult<DocumentByInfo<TableInfo>>>

Parameters

Name	Type
`paginationOpts`	`PaginationOptions`

Returns

Promise<PaginationResult<DocumentByInfo<TableInfo>>>

Inherited from

SelectableOrderedQuery.paginate

require

▸ require(requirement): SelectableOrderedQuery<TableInfo> Add source evidence before any terminal read; repeated requirements combine. The table’s floor still applies.

Parameters

Name	Type
`requirement`	`SourceReadRequirement`

Returns

SelectableOrderedQuery<TableInfo>

Inherited from

SelectableOrderedQuery.require

iterate

▸ iterate(options): AsyncIterableIterator<DocumentByInfo<TableInfo>, any, any> Iterate with at most this many candidates per native index fetch (1–1024). Use 1 when merging queues so unopened pages are not fetched speculatively. Filters and access checks may require multiple fetches to yield one row.

Parameters

Name	Type
`options`	`Object`
`options.prefetch`	`number`

Returns

AsyncIterableIterator<DocumentByInfo<TableInfo>, any, any>

Inherited from

SelectableOrderedQuery.iterate

aggregate

▸ aggregate<Measures, By>(measures, options?): AggregateResult<TableInfo, Measures, By> Reduce the whole population before any limit or projection. Work and authorization failures refuse the total rather than returning a partial value.

Type parameters

Name	Type
`Measures`	extends `AggregateMeasures`<`TableInfo`>
`By`	extends `undefined` \| readonly `DocumentFields`<`DocumentByInfo`<`TableInfo`>>[] = `undefined`

Parameters

Name	Type
`measures`	`Measures`
`options?`	`TableInfo` extends { `nativeSeries`: `true` } ? `never` : { `by`: `By` }

Returns

AggregateResult<TableInfo, Measures, By>

Inherited from

SelectableOrderedQuery.aggregate

readPage

▸ readPage(options): Promise<QueryReadPage<DocumentByInfo<TableInfo>>> Read one bounded traversal step. This does not register a reactive page boundary; ordinary read dependencies and current access still apply.

Parameters

Name	Type
`options`	`PaginationOptions`

Returns

Promise<QueryReadPage<DocumentByInfo<TableInfo>>>

Inherited from

SelectableOrderedQuery.readPage

select

▸ select<Fields>(fields): ProjectedOrderedQuery<TableInfo, Fields, "strict"> Select top-level properties while retaining _id and _creationTime. Omitted properties are not evaluated merely to return this projection. Filters, index order and membership keep their original meaning and access requirements. A refused property refuses the read; it is never replaced by null. Selection may be specified once, before consumption.

Type parameters

Name	Type
`Fields`	extends `DocumentFields`<`DocumentByInfo`<`TableInfo`>>

Parameters

Name	Type
`fields`	readonly `Fields`[]

Returns

ProjectedOrderedQuery<TableInfo, Fields, "strict">

Inherited from

SelectableOrderedQuery.select

selectCells

▸ selectCells<Fields>(fields): ProjectedOrderedQuery<TableInfo, Fields, "visible"> Return explicit value, missing or restricted cells. Index, predicate and ordering inputs remain strictly authorized. Selection is terminal and cannot change which rows or cursors the range returns.

Type parameters

Name	Type
`Fields`	extends `DocumentFields`<`DocumentByInfo`<`TableInfo`>>

Parameters

Name	Type
`fields`	readonly `Fields`[]

Returns

ProjectedOrderedQuery<TableInfo, Fields, "visible">

Inherited from

SelectableOrderedQuery.selectCells

where

▸ where(domain): LogicalQuery<TableInfo> Narrow the domain by more equalities; a field keeps one value.

Parameters

Name	Type
`domain`	`LogicalDomain`<`TableInfo`>

Returns

LogicalQuery<TableInfo>

orderBy

▸ orderBy(field, order?): SelectableOrderedQuery<TableInfo> The logical order, ascending unless stated. Defaults to _creationTime.

Parameters

Name	Type
`field`	`LogicalOrderField`<`TableInfo`>
`order?`	`"asc"` \| `"desc"`

Returns

SelectableOrderedQuery<TableInfo>

[asyncIterator]

▸ [asyncIterator](): AsyncIterator<DocumentByInfo<TableInfo>, any, any>

Returns

AsyncIterator<DocumentByInfo<TableInfo>, any, any>

Inherited from

SelectableOrderedQuery.[asyncIterator]

​Type parameters

​Hierarchy

​Methods

​groupBy

​Type parameters

​Parameters

​Returns

​Inherited from

​window

​Parameters

​Returns

​Inherited from

​signal

​Parameters

​Returns

​Inherited from

​explain

​Returns

​Inherited from

​withBudget

​Parameters

​Returns

​Inherited from

​collectWithDiagnostics

​Returns

​Inherited from

​takeWithDiagnostics

​Parameters

​Returns

​Inherited from

​filter

​Parameters

​Returns

​Inherited from

​take

​Parameters

​Returns

​Inherited from

​Parameters

​Returns

​Inherited from

​collect

​Parameters

​Returns

​Inherited from

​Returns

​Inherited from

​first

​Parameters

​Returns

​Inherited from

​Returns

​Inherited from

​unique

​Parameters

​Returns

​Inherited from

​Returns

​Inherited from

​paginate

​Parameters

​Returns

​Inherited from

​Parameters

​Returns

​Inherited from

​require

​Parameters

​Returns

​Inherited from

​iterate

​Parameters

​Returns

​Inherited from

​aggregate

​Type parameters

​Parameters

​Returns

​Inherited from

​readPage

Type parameters

Hierarchy

Methods

groupBy

Type parameters

Parameters

Returns

Inherited from

window

Parameters

Returns

Inherited from

signal

Parameters

Returns

Inherited from

explain

Returns

Inherited from

withBudget

Parameters

Returns

Inherited from

collectWithDiagnostics

Returns

Inherited from

takeWithDiagnostics

Parameters

Returns

Inherited from

filter

Parameters

Returns

Inherited from

take

Parameters

Returns

Inherited from

Parameters

Returns

Inherited from

collect

Parameters

Returns

Inherited from

Returns

Inherited from

first

Parameters

Returns

Inherited from

Returns

Inherited from

unique

Parameters

Returns

Inherited from

Returns

Inherited from

paginate

Parameters

Returns

Inherited from

Parameters

Returns

Inherited from

require

Parameters

Returns

Inherited from

iterate

Parameters

Returns

Inherited from

aggregate

Type parameters

Parameters

Returns

Inherited from

readPage