DOCSP 32904 emphasizing dot notation (#4781) (#4948)

* DOCSP-32904 emphasizing dot notation for querying embedded fields

* DOCSP-32904 emphasizing dot notation for querying embedded fields

* DOCSP-32904 tech edit

Author: ltran-mdb2

source/tutorial/query-embedded-documents.txt

@@ -36,28 +36,11 @@ methods:
 
 .. include:: /includes/driver-examples/driver-example-query-14.rst
 
-Match an Embedded/Nested Document
----------------------------------
-
-.. include:: /includes/extracts/filter-equality-embedded.rst
-
-For example, the following query selects all documents where the field
-``size`` equals the document ``{ h: 14, w: 21, uom: "cm" }``:
-
-.. include:: /includes/driver-examples/driver-example-query-15.rst
-
-Equality matches on the whole embedded document require an *exact*
-match of the specified ``<value>`` document, including the field order.
-For example, the following query does not match any documents in the
-``inventory`` collection:
-
-.. include:: /includes/driver-examples/driver-example-query-16.rst
-
-Query on Nested Field
----------------------
+Query on Nested Field with Dot Notation
+---------------------------------------
 
 To specify a query condition on fields in an embedded/nested document,
-use :term:`dot notation` (``"field.nestedField"``).
+use :term:`dot notation` (``"field.nestedField"``). 
 
 .. note::
 
@@ -91,6 +74,32 @@ is less than ``15``, the nested field ``uom`` equals ``"in"``, and the
 
 .. include:: /includes/driver-examples/driver-example-query-19.rst
 
+Match an Embedded/Nested Document
+---------------------------------
+
+.. include:: /includes/extracts/filter-equality-embedded.rst
+
+For example, the following query selects all documents where the field
+``size`` equals the document ``{ h: 14, w: 21, uom: "cm" }``:
+
+.. include:: /includes/driver-examples/driver-example-query-15.rst
+
+
+.. warning::
+
+   MongoDB does not recommend equality matches on embedded documents 
+   because the operations require an *exact* match of the specified ``<value>`` 
+   document, including the field order.
+
+   For example, the following query does not match any documents in the
+   ``inventory`` collection:
+
+   .. include:: /includes/driver-examples/driver-example-query-16.rst
+
+   The result of queries that use equality matches on embedded documents
+   is undefined when used with a driver that does not use ordered data
+   structures for expressing queries. 
+
 .. _query-embedded-documents-atlas-ui:
 
 Query Embedded Documents with {+atlas+}