Skip to main content
server.Query The Query interface allows functions to read values out of the database. If you only need to load an object by ID, use db.get(tableName, id) instead. Executing a query consists of calling
  1. (Optional) order to define the order
  2. (Optional) filter to refine the results
  3. A consumer method to obtain the results
Queries are lazily evaluated. No work is done until iteration begins, so constructing and extending a query is free. The query is executed incrementally as the results are iterated over, so early terminating also reduces the cost of the query. Example
Common mistake: .collect() loads all matching documents into memory. If the result set can grow unbounded as your database grows, this will eventually cause problems. Prefer .first(), .unique(), .take(n), or pagination instead. Only use .collect() on queries with a tightly bounded result set (e.g., items belonging to a single user with a known small limit). To learn more about how to write queries, see Querying the Database.

​
Type parameters

​
Hierarchy

​
Methods

​
order

▸ order(order): OrderedQuery<TableInfo> Define the order of the query output. Use "asc" for an ascending order and "desc" for a descending order. If not specified, the order defaults to ascending.

​
Parameters

​
Returns

OrderedQuery<TableInfo>

​
filter

▸ filter(predicate): Query<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

​
Returns

Query<TableInfo>
  • A new OrderedQuery with the given filter predicate applied.

​
Inherited from

OrderedQuery.filter

​
paginate

▸ paginate(paginationOpts): Promise<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

​
Returns

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

​
Inherited from

OrderedQuery.paginate

​
collect

▸ collect(): Promise<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.

​
Returns

Promise<DocumentByInfo<TableInfo>[]>
  • An array of all of the query’s results.

​
Inherited from

OrderedQuery.collect

​
take

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

​
Parameters

​
Returns

Promise<DocumentByInfo<TableInfo>[]>
  • An array of the first n results of the query (or less if the query doesn’t have n results).

​
Inherited from

OrderedQuery.take

​
first

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

​
Returns

Promise<null | DocumentByInfo<TableInfo>>
  • The first value of the query or null if the query returned no results.

​
Inherited from

OrderedQuery.first

​
unique

▸ unique(): Promise<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
Throws Will throw an error if the query returns more than one result.

​
Returns

Promise<null | DocumentByInfo<TableInfo>>
  • The single result returned from the query or null if none exists.

​
Inherited from

OrderedQuery.unique

​
[asyncIterator]

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

​
Returns

AsyncIterator<DocumentByInfo<TableInfo>, any, undefined>

​
Inherited from

OrderedQuery.[asyncIterator]