diff --git a/source/core/document.txt b/source/core/document.txt index b0761476f9c..605220c32d4 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -199,6 +199,37 @@ Document Size Limit Document Field Order ~~~~~~~~~~~~~~~~~~~~ +Unlike JavaScript objects, the fields in a BSON document are ordered. + +Field Order in Queries +`````````````````````` + +For queries, the field order behavior is as follows: + +- When comparing documents, field ordering is significant. For + example, when comparing documents with fields ``a`` and ``b`` in a + query: + + - ``{a: 1, b: 1}`` is equal to ``{a: 1, b: 1}`` + + - ``{a: 1, b: 1}`` is not equal to ``{b: 1, a: 1}`` + +- For efficient query execution, the query engine may reorder fields + during query processing. Among other cases, reordering fields may + occur when processing these projection operators: + :pipeline:`$project`, :pipeline:`$addFields`, :pipeline:`$set`, and + :pipeline:`$unset`. + + - Field reordering may occur in intermediate results as well as the + final results returned by a query. + + - Because some operations may reorder fields, you should not rely on + specific field ordering in the results returned by a query that + uses the projection operators listed earlier. + +Field Order in Write Operations +``````````````````````````````` + .. include:: /includes/fact-update-field-order.rst :start-after: order-of-document-fields diff --git a/source/includes/fact-update-field-order.rst b/source/includes/fact-update-field-order.rst index 179752df4d6..c87dd51cd83 100644 --- a/source/includes/fact-update-field-order.rst +++ b/source/includes/fact-update-field-order.rst @@ -1,7 +1,7 @@ .. order-of-document-fields -MongoDB preserves the order of the document fields following write -operations *except* for the following cases: +For write operations, MongoDB preserves the order of the document fields +*except* for the following cases: - The ``_id`` field is always the first field in the document.