QueryBuilder

Class: QueryBuilder<T, Q>

A fluent, chainable query builder that generates parameterized Cosmos DB SQL queries. Implements PromiseLike so it can be awaited directly.

// Obtained from Model methods
const query = User.find({ role: 'admin' });

The type parameter Q determines the return type when the query is awaited.

Chainable Methods

sort(fields)

sort(fields: Record<string, 1 | -1>): this

Set sort order. 1 for ascending, -1 for descending.

User.find().sort({ name: 1, createdAt: -1 });

limit(value)

limit(value: number): this

Set maximum number of results.

offset(value)

offset(value: number): this

Set the number of results to skip (for offset-based pagination).

Execution Methods

exec()

async exec(): Promise<Result>

Executes the query and returns the result. The return type depends on Q:

then()

then(onfulfilled?, onrejected?): Promise<Result>

Implements PromiseLike so queries can be awaited directly:

const users = await User.find({ role: 'admin' });

buildQuery()

buildQuery(): SqlQuerySpec

Returns the generated SQL query specification without executing it. Useful for debugging:

const spec = User.find({ age: { $gt: 18 } }).buildQuery();
console.log(spec.query);      // SELECT * FROM root r WHERE r.age > @age_0 ...
console.log(spec.parameters); // [{ name: '@age_0', value: 18 }]

Filter Operators

Filters are passed as the first argument to query methods:

Interface: Cursor<T>

An iterator for processing large result sets in batches.

interface Cursor<T> {
  each(fn: (doc: Document<T>, index: number) => Promise<void> | void): Promise<void>;
}

each(fn)

Iterates over all matching documents, fetching in batches (configurable via batchSize). The callback receives each document and its zero-based index.

const cursor = await User.findAsCursor({}, { batchSize: 100 });
await cursor.each(async (doc, index) => {
  // process each document
});

Interface: TokenPaginationResult<T>

Result of a token-based paginated query.

interface TokenPaginationResult<T> {
  data: Document<T>[];
  pagination: {
    next: string | undefined;
  };
}

The token is a base64url-encoded Cosmos DB continuation token.