/ /

/ /

$eq

$eq: Specifies equality condition. The $eq operator matches documents where the value of a field equals the specified value.

Compatibility

You can use $eq for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The $eq operator has the following form:

{ <field>: { $eq: <value> } }

The $eq operator is equivalent to the { field: <value> } form, except when <value> is a regular expression. See below for examples.

Behavior

Comparison Order

For comparison of different BSON type values, see the specified BSON comparison order.

Match a Document Value

If <value> is a document, the order of the fields in the document matters.

Match an Array Value

If <value> is an array, MongoDB matches documents where <field> matches the array exactly or <field> contains an element that matches the array exactly. The order of the elements matters. For an example, see Equals an Array Value.

Match a Regular Expression

The expression { field: <value> } implicitly specifies a match on <value>. MongoDB translates the implicit match to a more explicit form.

When <value> is fixed, like a particular string, the expression is equivalent to using the $eq operator { field: { $eq: <value> } }.

If <value> is a regular expression, MongoDB expands the statement to use the $regex operator { field: { $regex: <value> } }.

For examples, see Regex Match Behavior.

Security Implications

Always use the explicit form { field: { $eq: <value> } } with user-supplied input to avoid problems with maliciously formed queries.

Examples

The examples use the inventory collection:

db.inventory.insertMany( [
   { _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] },
   { _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] },
   { _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] },
   { _id: 4, item: { name: "xy", code: "456" }, qty: 30, tags: [ "B", "A" ] },
   { _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }
] )

Equals a Specified Value

This example selects all documents in the inventory collection where the qty field value equals 20:

db.inventory.find( { qty: { $eq: 20 } } )

The query is equivalent to:

db.inventory.find( { qty: 20 } )

Both queries match the following documents:

[
   { _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] },
   { _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }
]

Field in Embedded Document Equals a Value

The following example selects all documents in the inventory collection where the item.name field value equals "ab". To specify a condition on a field in an embedded document, use the dot notation.

db.inventory.find( { "item.name": { $eq: "ab" } } )

The query is equivalent to:

db.inventory.find( { "item.name": "ab" } )

Both queries match the following document:

[ { _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] } ]

Tip

Query Embedded Documents

Array Element Equals a Value

The following example selects all documents in the inventory collection where the tags array contains an element with the value "B" [1]:

db.inventory.find( { tags: { $eq: "B" } } )

The query is equivalent to:

db.inventory.find( { tags: "B" } )

Both queries match the following documents:

[
   { _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] },
   { _id: 2, item: { name: "cd", code: "123" }, qty: 20, tags: [ "B" ] },
   { _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] },
   { _id: 4, item: { name: "xy", code: "456" }, qty: 30, tags: [ "B", "A" ] }
]

Tip

[1]	The query will also match documents where the value of the `tags` field is the string `"B"`.

Equals an Array Value

This example selects all documents in the inventory collection where the tags array equals the specified array or contains an element that equals the array [ "A", "B" ].

db.inventory.find( { tags: { $eq: [ "A", "B" ] } } )

The query is equivalent to:

db.inventory.find( { tags: [ "A", "B" ] } )

Both queries match the following documents:

[
   { _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] },
   { _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }
]

Regex Match Behavior

The following examples show the difference between implicit and explicit regular expression matching. Consider a collection with these documents:

db.companies.insertMany( [
   { _id: 001, company: "MongoDB" },
   { _id: 002, company: "MongoDB2" }
] )

$eq Match on a String

Strings return the same values whether you use an implicit match or an explicit use of $eq. The following queries return the same result:

db.collection.find( { company: "MongoDB" }, {_id: 0 })
db.collection.find( { company: { $eq: "MongoDB" } }, {_id: 0 } )

The result is:

[ { company: "MongoDB" } ]

$eq Match on a Regular Expression

An explicit query that uses $eq and a regular expression only matches an object that is also a regular expression. The example query returns no results because values in the company field are strings.

db.companies.find( { company: { $eq: /MongoDB/ } }, {_id: 0 } )

Regular Expression Matches

A query with an implicit match against a regular expression is equivalent to a query that uses the $regex operator. The following queries return the same result:

db.companies.find( { company: /MongoDB/ }, {_id: 0 })
db.companies.find( { company: { $regex: /MongoDB/ } }, {_id: 0 } )

The results are:

[
   { company: "MongoDB" },
   { company: "MongoDB2" }
]

Back

Comparison

$gt