$eq (Equals)
Last updated: 2026-10-09
$eq (Equals)
$eq selects documents where the field value equals the specified value. It is MongoDB's most common exact-match predicate: `{ age: { $eq: 21 } }` is equivalent to `{ age: 21 }`, but $eq makes the equality intent explicit and also acts as a comparison operator in aggregation expressions. Note $eq is type-sensitive: the string "21" does not match the number 21. Also note: an explicit { $eq: /pattern/ } only matches BSON regex values, unlike implicit { field: /pattern/ } which performs regex matching.
| Category | Comparison |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ <field>: { $eq: <value> } }⚙️ Parameters
| field | The document field to match; dotted paths access nested fields (e.g. "address.city"). |
|---|---|
| value | The value to match. May be a literal or expression; sensitive to BSON type. |
Returns：Cursor of matching documents
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $eq: exact match on age = 21
db.users.find({ age: { $eq: 21 } })
// Equivalent implicit equality
db.users.find({ age: 21 })
// Nested field + type sensitivity
db.users.find({ "address.city": { $eq: "Beijing" } })Output：
// Returns all documents whose age is exactly 21 (number type)
{ "_id": ObjectId("..."), "name": "Alice", "age": 21, "address": { "city": "Beijing" } }📌 Notes
- Type-sensitive: { $eq: "21" } will not match number 21
- With a scalar value, $eq matches an array field if any element equals it (same as $elemMatch: { $eq: value }); with an array value, the field must equal the whole array or contain an element that equals it exactly
- $eq: null matches documents where the field is missing OR null (differs from $exists: false)
🏷️ Related Tags
💡 Related Cases
Document Query Basics: The `find` Method and Projections
Query Operators: A Complete Guide to the 30+ Operator
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $eq and writing { age: 21 } directly?
AFunctionally identical; $eq merely makes equality intent explicit and reads better inside $and/$or combinations.
QCan $eq match null?
AYes. $eq: null matches documents where the field is missing or null. To match only literal null, combine with $type: 10 (Null).
QHow does $eq behave on array fields?
AIt matches if any array element equals the value (equivalent to $elemMatch). For an exact whole-array match, use the array literal directly or combine with $size.
