Skip to content

Commit 26f6b40

Browse files
mungitoperritoandf-mongodb
authored andcommitted
DOCSP-10981 implicit matching with eq, query update
1 parent 62910ad commit 26f6b40

File tree

1 file changed

+81
-1
lines changed
  • source/reference/operator/query

1 file changed

+81
-1
lines changed

source/reference/operator/query/eq.txt

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ $eq
2121

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

24-
The :query:`$eq` expression is equivalent to ``{ field: <value> }``.
24+
The :query:`$eq` operator is equivalent to using the form ``{ field: <value> }``
25+
except when the ``<value>`` is a regular expression. See :ref:`match-regex`
26+
for further details.
27+
2528

2629
Behavior
2730
--------
@@ -45,6 +48,23 @@ where the ``<field>`` matches the array exactly or the ``<field>``
4548
contains an element that matches the array exactly. The order of the
4649
elements matters. For an example, see :ref:`eq-match-array-value`.
4750

51+
.. _match-regex:
52+
53+
Match a Regular Expression
54+
~~~~~~~~~~~~~~~~~~~~~~~~~~
55+
56+
The expression ``{ field: <value> }`` implicitly specifies a match on
57+
``<value>``. MongoDB translates the implicit match to a more explicit
58+
form.
59+
60+
When the ``<value>`` is fixed, like a particular string, the expression
61+
is equivalent to using the ``$eq`` operator ``{ field: { $eq: <value> } }``.
62+
63+
If ``<value>`` is a regular expression, the statement is expanded
64+
using the ``$regex`` operator ``{ field: { $regex: <value> } }``.
65+
66+
For examples illustrating this behaviour, see :ref:`eq-regex-matching`.
67+
4868
Examples
4969
--------
5070

@@ -165,3 +185,63 @@ Both queries match the following documents:
165185

166186
{ _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] }
167187
{ _id: 5, item: { name: "mn", code: "000" }, qty: 20, tags: [ [ "A", "B" ], "C" ] }
188+
189+
190+
.. _eq-regex-matching:
191+
192+
Regex Match Behaviour
193+
~~~~~~~~~~~~~~~~~~~~~
194+
195+
The following examples demonstrate the differences in behavior between
196+
implicit and explict regular expression matching. Consider a collection
197+
with these documents:
198+
199+
.. code-block:: javascript
200+
201+
{ _id: 001, company: "MongoDB" }
202+
{ _id: 002, company: "MongoDB2" }
203+
204+
$eq match on a string
205+
A string expands to return the same values whether an implicit match
206+
or an explicit use of ``$eq``. Both of these queries:
207+
208+
.. code-block:: javascript
209+
210+
db.collection.find( { company: "MongoDB" }, {_id: 0 })
211+
db.collection.find( { company: { $eq: "MongoDB" } }, {_id: 0 } )
212+
213+
return the following result:
214+
215+
.. code-block:: javascript
216+
:copyable: false
217+
218+
{ "company" : "MongoDB" }
219+
220+
$eq match on a regular expression
221+
An explicit query using ``$eq`` and a regular expression will only
222+
match an object which is also a regular expresssion. The example
223+
query won't return anything since values in the ``company`` field
224+
are strings.
225+
226+
.. code-block:: javascript
227+
228+
db.collection.find( { company: { $eq: /MongoDB/ } }, {_id: 0 } )
229+
230+
Regular expression matches
231+
A query with an implicit match against a regular expression is
232+
equivalent to a making a query with the ``$regex`` operator. Both of
233+
these queries:
234+
235+
.. code-block:: javascript
236+
237+
db.collection.find( { company: /MongoDB/ }, {_id: 0 })
238+
db.collection.find( { company: { $regex: /MongoDB/ } }, {_id: 0 } )
239+
240+
return the same results:
241+
242+
.. code-block:: javascript
243+
:copyable: false
244+
245+
{ "company" : "MongoDB" }
246+
{ "company" : "MongoDB2" }
247+

0 commit comments

Comments
 (0)