(DOCS-13305): meta and natural tweaks for 4.4

Author: jeff-allen-mongo

source/includes/extracts-4.4-changes.yaml

@@ -132,5 +132,107 @@ content: |
    Starting in MongoDB 4.4, |timestampfmt| no longer supports ``ctime``.
    An example of ``ctime`` formatted date is: ``Wed Dec 31
    18:17:54.811``.
+---
+ref: 4.4-changes-projection-sort-meta
+content: |
+
+   Starting in MongoDB 4.4:
+
+   - You can specify :projection:`$meta` in the projection document
+     of a :dbcommand:`find` command without specifying the
+     :projection:`$meta` expression as part of a
+     :method:`~cursor.sort()` document:
+     
+     .. code-block:: javascript 
+
+       db.collection.find(
+           <query>,
+           { score: { $meta: "textScore" } }
+       )
+
+     As a result, you can project the
+     :ref:`textScore <text-operator-text-score>` metadata without
+     sorting the results by their search relevance.
+
+   - You can specify the :projection:`$meta` expression as part of
+     a :method:`~cursor.sort()` document without specifying
+     :projection:`$meta` in the projection document of a 
+     :dbcommand:`find` command:
+
+     .. code-block:: javascript 
+
+       db.collection.find(
+           <query>
+       ).sort( { score: { $meta: "textScore" } } )
+
+     As a result, you can sort the resulting documents by their
+     search relevance without projecting the ``textScore``. 
+
+   - If you specify the :projection:`$meta` expression as part of a
+     :method:`~cursor.sort()` document and the :term:`projection`
+     document of a :dbcommand:`find` command, you can specify different
+     field names for the :method:`~cursor.sort()` document and the
+     :term:`projection` document.
+
+     In the following example, the ``score`` field associated with the
+     :projection:`$meta` expression in the projection document contains
+     the document's :ref:`textScore <text-operator-text-score>`
+     metadata. In contrast, the ``ignoredName`` field in the
+     :method:`~cursor.sort()` document has an arbitrary name which
+     does not affect the query.
+
+     .. code-block:: javascript 
+
+        db.collection.find(
+          <query>, 
+          { score: { $meta: "textScore" } }
+        ).sort( { ignoredName: { $meta: "textScore" } } )
+
+   In previous versions of MongoDB, the *same* :projection:`$meta`
+   expression, including the ``<projectedFieldName>``, must appear in
+   the :method:`~cursor.sort()` document and the :dbcommand:`find`
+   command's projection document.
+---
+ref: 4.4-changes-textscore-predicate
+content: |
+
+   Starting in MongoDB 4.4, you must specify the :query:`$text` operator
+   in the query predicate to use ``{ $meta: "textScore" }`` in either
+   the :term:`projection` document or a :method:`~cursor.sort()`
+   document.
+
+   If you do not specify the :query:`$text` operator in the query
+   predicate, the operation fails.
+
+   .. example::
+
+      The following :dbcommand:`find` command fails because it specifies
+      ``{ $meta: "textScore" }`` in the :term:`projection` document, but
+      does not specify :query:`$text` operator in the query predicate:
+
+      .. code-block:: javascript
+         :copyable: false
+
+         // This command fails:
+
+         db.articles.find( { }, { score: { $meta: "textScore" } } )
+
+      To successfully execute the command, include the :query:`$text`
+      operator in the query predicate:
+
+      .. code-block:: javascript
+
+         // This command succeeds:
+
+         db.articles.find(
+            { $text: { $search: "coffee" } },
+            { score: { $meta: "textScore" } }
+         )
+---
+ref: 4.4-changes-natural-sort-views
+content: |
 
+   Starting in MongoDB 4.4, you can specify a :operator:`$natural`
+   sort when running a :dbcommand:`find` operation against a
+   :doc:`view </core/views>`.
 ...

source/reference/method/cursor.sort.txt

@@ -262,12 +262,8 @@ Return in Natural Order
 
 The :operator:`$natural` parameter returns items according to their
 :term:`natural order` within the database. This ordering is an internal
-implementation feature, and you should not rely on any particular structure
-within it.
-
-.. note::
-
-   .. include:: /includes/extracts/views-unsupported-natural-sort.rst
+implementation feature, and you should not rely on any particular
+ordering of the documents.
 
 Index Use
 ~~~~~~~~~

source/reference/operator/meta/natural.txt

@@ -10,12 +10,12 @@ Definition
 
 .. operator:: $natural
 
-.. versionchanged:: 3.2
+.. versionchanged:: 4.4
 
    Use in conjunction with :method:`cursor.hint()` to perform a
    collection scan to return documents in :term:`natural order`.
 
    For usage, see :ref:`hint-collection-scans` example in the
    :method:`cursor.hint()` reference page.
 
-.. include:: /includes/extracts/views-unsupported-natural-sort.rst
+   .. include:: /includes/extracts/4.4-changes-natural-sort-views.rst

source/reference/operator/projection/meta.txt

@@ -33,7 +33,10 @@ expression as:
 
    { <projectedFieldName>: { $meta: "textScore" } }
 
-.. include:: /includes/extracts/views-unsupported-projection-$meta.rst
+:query:`$text` search is not fully supported by read-only
+non-materialized :doc:`views </core/views>`. In particular,
+:method:`db.collection.find()` operations on views do not support
+``{ $meta: "textScore" }``.
 
 Projected Field Name
 ~~~~~~~~~~~~~~~~~~~~
@@ -77,7 +80,7 @@ Sort
 ~~~~
 
 The :projection:`$meta` expression can be part of a
-:method:`~cursor.sort()` expression, as in:
+:method:`~cursor.sort()` document, as in:
 
 .. code-block:: javascript
 
@@ -86,14 +89,23 @@ The :projection:`$meta` expression can be part of a
       { score: { $meta: "textScore" } }
    ).sort( { score: { $meta: "textScore" } } )
 
-To include a :projection:`$meta` expression in a
-:method:`~cursor.sort()` expression, the *same* :projection:`$meta`
-expression, including the ``<projectedFieldName>``, must appear in the
-projection document. The specified metadata determines the sort order.
+The specified metadata determines the sort order.
 For example, the ``"textScore"`` metadata sorts in descending order.
 
+Projection and Sort Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/4.4-changes-projection-sort-meta.rst
+
 For additional examples, see :ref:`text-operator-example-compound-sort`.
 
+.. _meta-text-predicate:
+
+Query Predicate Must Include ``$text``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/4.4-changes-textscore-predicate.rst
+
 Examples
 --------
 

source/release-notes/4.4-compatibility.txt

@@ -80,7 +80,16 @@ That is, the method no longer accepts
 Projection Restrictions
 -----------------------
 
-.. include:: /includes/fact-projection-path-collision.rst
+- .. include:: /includes/fact-projection-path-collision.rst
+
+``$meta`` Behavior Changes 
+--------------------------
+
+- Starting in MongoDB 4.4, when using :projection:`$meta` as a
+  projection operator or as part of a :method:`~cursor.sort()`
+  expression, you must specify the :query:`$text` operator in the
+  query predicate to use ``{ $meta: "textScore" }``. See
+  :ref:`meta-text-predicate` for an example.
 
 General Changes
 ---------------

source/release-notes/4.4.txt

@@ -413,7 +413,17 @@ db.auth() Can Prompt for Password
 Starting in MongoDB 4.4, the :binary:`~bin.mongo` shell method
 :ref:`db-auth-syntax-username-password` prompts for the password if
 you do not pass in the password or the :method:`passwordPrompt()`
-method for the ``<password>``. 
+method for the ``<password>``.
+
+Support for ``$natural`` Sort on Views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/4.4-changes-natural-sort-views.rst
+
+Validation Changes for ``$meta``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/4.4-changes-projection-sort-meta.rst
 
 :doc:`Changes Affecting Compatibility </release-notes/4.4-compatibility>`
 -------------------------------------------------------------------------