QueryBuilder

Constructor

Internal — use collection.query().

Methods

where()

where(field: string, value: unknown): this
where(field: string, op: string, value: unknown): this

Supported operators: ==, !=, >, <, >=, <=.

orWhere()

orWhere(callback: (q: QueryBuilder<T>) => void): this

Groups conditions with OR logic. Multiple where calls inside the same orWhere are AND'd within the group.

// Find items that are either completed OR high priority
const items = await todos
  .query()
  .where("status", "active")
  .orWhere((q) => q.where("priority", "high").where("assigned", true))
  .fetch()

sort()

sort(spec: Partial<Record<keyof T, "asc" | "desc">>): this

Only the first entry is used. Example: query.sort({ createdAt: "desc" }).

limit()

limit(n: number): this

offset()

offset(n: number): this

Pagination example:

const pageSize = 20
const page = 2

const results = await todos
  .query()
  .sort({ createdAt: "desc" })
  .offset((page - 1) * pageSize)
  .limit(pageSize)
  .fetch()

search()

search(field: string, query: string): this

Case-insensitive substring search. With FTS plugin, uses the index.

fetch()

fetch(): Promise<(Model<T> & T)[]>

Executes the query and returns results.

first()

first(): Promise<(Model<T> & T) | undefined>

Shortcut for .limit(1).fetch() returning results[0].

count()

count(): Promise<number>

Shortcut for fetch() returning results.length.

toArray()

toArray(): Promise<T[]>

Like fetch() but returns plain objects via .toJSON().

const items = await todos.query().toArray()
// items[0] is { id: 1, title: "...", completed: false }
// Not a Model — no .update() / .delete() methods