findOne() (Query a Single Document)
Last updated: 2026-10-09
findOne() (Query a Single Document)
findOne() returns the first document matching a filter directly as a document, not a cursor, e.g. `db.users.findOne({ name: 'Alice' })`. When several match, it returns the first in natural order; with no match it returns null. It skips cursor iteration, making it ideal for lookups by a unique field such as _id or username.
| Category | Read |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
db.<collection>.findOne(<filter>, <projection>)⚙️ Parameters
| filter | Predicate object; supports query operators. |
|---|---|
| projection | Optional. Controls returned fields: 1 include / 0 exclude. |
Returns：The first matching document; null when nothing matches.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// findOne: look up a user by _id
const user = db.users.findOne(
{ _id: ObjectId('64c8a1b20000000000000001') },
{ name: 1, age: 1, _id: 0 }
)
userOutput：
{ name: 'Alice', age: 21 }📌 Notes
- Only the first match is returned; natural order is not guaranteed stable
- Returns null when nothing matches — guard with if (doc)
- Cleaner than find().limit(1) for single-document reads
🏷️ Related Tags
💡 Related Cases
Deleting Documents and Getting Started with Node.js
Documents and BSON: The Cornerstone of MongoDB Data
Mongoose Models and Schema Design
📚 Related Tutorials
❓ FAQ
QIs findOne the same as find().limit(1)?
ASimilar, but findOne() returns the document directly while find() returns a cursor to iterate; prefer findOne() for unique-field lookups.
QWhat does findOne return when nothing is found?
AIt returns null without throwing; typically consumed as if (doc) { ... }.
QCan findOne return only some fields?
AYes — pass a projection as the second argument, e.g. {name: 1}.
