find() (Query Documents)
Last updated: 2026-10-09
find() (Query Documents)
find() queries documents matching a condition and returns a Cursor. It is the most basic read method: the first argument is the query predicate, the second is the projection controlling returned fields. The cursor is lazy — data is fetched only when iterated (toArray/forEach/next).
| Category | Read |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
db.<collection>.find(<query>, <projection>)⚙️ Parameters
| query | Predicate object supporting query operators; omitted matches all. |
|---|---|
| projection | Optional. Controls returned fields: 1 include / 0 exclude. |
Returns：Cursor
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// find: users older than 20, name only
const cursor = db.users.find(
{ age: { $gt: 20 } },
{ name: 1, age: 1, _id: 0 }
)
cursor.forEach(u => print(u.name))Output：
Alice
Bob📌 Notes
- Returns a Cursor, not an array; consume with toArray()/forEach()/next()
- Projection cannot mix 1 and 0 (except _id)
- find() is read-only; documents are never modified
- In mongosh, bare find() prints the first 20 documents; type it to page more
🏷️ Related Tags
💡 Related Cases
Deleting Documents and Getting Started with Node.js
Integrating Express with Mongoose: Web Application Architecture
Mongoose Advanced Patterns: Performance and Flexibility
Mongoose Models and Schema Design
Performance Optimization and Monitoring: Production-Level Tuning
RESTful API in Practice: A Complete Guide to CRUD Design
📚 Related Tutorials
❓ FAQ
QDoes find() return an array?
ANo, it returns a Cursor. Convert with .toArray() (or iterate) when you need an array.
QWhat does find() return?
Afind() returns a cursor, not an array. Convert it with toArray(), or iterate with forEach/next; the cursor is lazy and only fetches documents from the server as you read.
QWhat does the second argument of find() do?
AIt is the projection: 1 includes fields, 0 excludes them (mixing is allowed only for _id). Use it to reduce network payload and result size.
