Queries Reference
FindQuery and FindOneQuery method signatures
Model.find(), Model.findOne(), and Model.findById() return thenable query builders. You can await them directly or keep chaining before the cursor runs. This page lists every method available on the builders.
For workflows and design guidance, see the Querying guide and the Populate guide.
FindQuery
Returned by Model.find(filter?, options?).
Chainable helpers
| Method | Purpose |
|---|---|
sort(spec) | Sort by one or more fields. Same shape as MongoDB sort. |
limit(n) | Cap the result size. Throws on non-positive integers. |
skip(n) | Skip the first n results. Throws on non-positive integers. |
include(paths) | Typed inclusion projection. Cumulative with exclude. |
exclude(paths) | Typed exclusion projection. Cumulative with include. |
project(record) | Pass a raw MongoDB projection. Merged with include / exclude. |
populate(field, options?) | Resolve a M.objectId().ref(() => Model) field. See Populate. |
import { } from "./models";
const = await .({ : false })
.(["title", "completed", "ownerId"])
.({ : -1 })
.(20)
.(10);Execution
| Method | Returns | Notes |
|---|---|---|
exec() | Promise<Doc[]> | Runs the query. |
.then / .catch | thenable | Lets you await q directly. Call .exec() first if you need .finally() or Promise.all. |
explain() | Promise<Document> | Returns the MongoDB explain output for the query. |
getCursor() | FindCursor<Doc> | Hands you the raw cursor for streaming or advanced workflows. |
getCursor() is the escape hatch when you need streaming, session pinning, or anything else the builder does not wrap.
FindOneQuery
FindOneQuery is intentionally narrower than FindQuery — findOne returns one document, so cursor-level helpers (sort, limit, skip, getCursor, explain) do not apply.
Returned by Model.findOne(filter) and Model.findById(_id).
Chainable helpers
| Method | Purpose |
|---|---|
populate(field, options?) | Same semantics as on FindQuery, but the result is a single document or null. |
Execution
| Method | Returns | Notes |
|---|---|---|
exec() | Promise<Doc | null> | Runs the query. |
.then / .catch | thenable | Lets you await q directly. Call .exec() first if you need .finally() or Promise.all. |
If you need cursor-level access for a findOne-shaped query, drop to the model aggregate() or use find().limit(1).