DOCSP-24399 cherry-pick/merge (#1782)

Author: kennethdyer

source/includes/fact-dbcommand-tip.rst

@@ -0,0 +1,10 @@
+
+.. tip::
+
+   In :program:`mongosh`, this command can also be run through the |method|.
+
+   Helper methods are convenient for :program:`mongosh` users, but they may not
+   return the same level of information as database commands.  In cases where
+   the convenience is not needed or the additional return fields are required,
+   use the database command.
+

source/includes/fact-mongosh-shell-method-alt.rst

@@ -0,0 +1,14 @@
+.. important:: ``mongosh`` Method
+
+   This page documents a :binary:`~bin.mongosh` method. This is *not*
+   the documentation for database commands or language-specific drivers,
+   such as Node.js. To use the database command, see the |dbcommand|.
+
+   For MongoDB API drivers, refer to the language-specific
+   :driver:`MongoDB driver documentation </>`.
+
+   For the legacy ``mongo`` shell documentation, refer to the
+   documentation for the corresponding MongoDB Server release:
+
+   - :v4.4:`mongo shell v4.4 </mongo>`
+   - :v4.2:`mongo shell v4.2 </mongo>`

source/reference/command/aggregate.txt

@@ -20,6 +20,10 @@ Definition
    to process data from a collection or other source with a sequence of 
    stage-based manipulations.
 
+   .. |method| replace:: :method:`db.aggregate()` and 
+      :method:`db.collection.aggregate()` helper methods
+   .. include:: /includes/fact-dbcommand-tip
+
 Syntax
 ------
 

source/reference/command/createIndexes.txt

@@ -17,6 +17,10 @@ Definition
 
    Builds one or more indexes on a collection.
 
+   .. |method| replace:: :method:`db.collection.createIndex()` and
+      :method:`db.collection.createIndexes()` helper methods.
+   .. include:: /includes/fact-dbcommand-tip
+
    The :dbcommand:`createIndexes` command takes the following form:
 
    .. code-block:: javascript

source/reference/command/distinct.txt

@@ -20,6 +20,9 @@ Definition
    an array of the distinct values. The return document also contains
    an embedded document with query statistics and the query plan.
 
+   .. |method| replace:: :method:`db.collection.distinct()` helper method.
+   .. include:: /includes/fact-dbcommand-tip
+
    The command takes the following form
 
    .. code-block:: javascript

source/reference/command/dropIndexes.txt

@@ -16,8 +16,12 @@ dropIndexes
    (except the index on the ``_id`` field) from the specified
    collection.
 
+   .. |method| replace:: :method:`db.collection.dropIndex()` and
+      :method:`db.collection.dropIndexes()` helper methods.
+   .. include:: /includes/fact-dbcommand-tip
+
    The command has the following form:
-   
+
    .. code-block:: javascript
 
       { dropIndexes: <string>, index: <string|document|arrayofstrings>, writeConcern: <document>, comment: <any> }

source/reference/command/explain.txt

@@ -21,9 +21,10 @@ Definition
    :dbcommand:`findAndModify`, :dbcommand:`delete`,
    :dbcommand:`mapReduce`, and :dbcommand:`update`.
 
-   Although MongoDB provides the :dbcommand:`explain` command, the
-   preferred method for running :dbcommand:`explain` is to use the
-   :method:`db.collection.explain()` and :method:`cursor.explain()` helpers.
+   .. |method| replace:: :method:`db.collection.explain()` and 
+      :method:`cursor.explain()` helper methods
+
+   .. include:: /includes/fact-dbcommand-tip
 
    The :dbcommand:`explain` command has the following syntax:
 

source/reference/command/find.txt

@@ -20,12 +20,9 @@ Definition
    Executes a query and returns the first batch of results and the
    cursor id, from which the client can construct a cursor.
 
-   .. tip::
-
-      Rather than run the :dbcommand:`find` command directly, you can
-      use the :method:`db.collection.find()` helper provided in
-      :binary:`~bin.mongosh` or the equivalent helper in the
-      drivers.
+   .. |method| replace:: :method:`db.collection.find()` or
+      :method:`db.collection.findOne()` helper methods
+   .. include:: /includes/fact-dbcommand-tip
 
 Syntax
 ------

source/reference/command/findAndModify.txt

@@ -24,6 +24,9 @@ Definition
    modifications made on the update. To return the document with the
    modifications made on the update, use the ``new`` option.
 
+   .. |method| replace:: :method:`db.collection.findAndModify()` helper method
+   .. include:: /includes/fact-dbcommand-tip
+
    .. versionchanged:: 5.0
 
    The command has the following syntax:

source/reference/command/insert.txt

@@ -19,6 +19,10 @@ Definition
    returns a document containing the status of all inserts. The insert
    methods provided by the MongoDB drivers use this command internally.
 
+   .. |method| replace:: :method:`db.collection.insertOne()` and
+      :method:`db.collection.insertMany()` helper methods
+   .. include:: /includes/fact-dbcommand-tip
+
    The command has the following syntax:
 
    .. code-block:: javascript

source/reference/command/listIndexes.txt

@@ -18,9 +18,11 @@ Definition
    Returns information about the indexes on the specified collection. Returned 
    index information includes the keys and options used to create the index, as 
    well as :doc:`hidden indexes </core/index-hidden>`. You can optionally set 
-   the batch size for the first batch of results. :binary:`~bin.mongosh` 
-   provides the :method:`db.collection.getIndexes()` helper.
+   the batch size for the first batch of results. 
 
+   .. |method| replace:: :method:`db.collection.getIndexes()` helper method
+   .. include:: /includes/fact-dbcommand-tip
+   
 Syntax
 ------
 

source/reference/method/db.collection.aggregate.txt

@@ -16,12 +16,12 @@ Definition
 .. method:: db.collection.aggregate(pipeline, options)
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`aggregate` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Calculates aggregate values for the data in a collection or a :doc:`view </core/views>`.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80

source/reference/method/db.collection.createIndex.txt

@@ -17,12 +17,15 @@ Definition
 
 .. method:: db.collection.createIndex(keys, options, commitQuorum)
 
-
-   .. include:: /includes/fact-mongosh-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`createIndexes` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Creates indexes on collections.
 
+   To minimize the impact of building an index on replica sets and
+   sharded clusters, use a rolling index build procedure as described
+   on :doc:`/tutorial/build-indexes-on-replica-sets`.
+
    :method:`db.collection.createIndex()` takes the following parameters:
 
    .. list-table::
@@ -141,14 +144,6 @@ Definition
 
           .. versionadded:: 4.4
 
-
-   The :method:`db.collection.createIndex()` is a wrapper around the
-   :dbcommand:`createIndexes` command.
-
-   To minimize the impact of building an index on replica sets and
-   sharded clusters, use a rolling index build procedure as described
-   on :doc:`/tutorial/build-indexes-on-replica-sets`.
-
 .. _ensureIndex-options:
 .. _createIndex-options:
 

source/reference/method/db.collection.createIndexes.txt

@@ -15,12 +15,15 @@ Definition
 
 .. method:: db.collection.createIndexes( [ keyPatterns ], options, commitQuorum )
 
-
-   .. include:: /includes/fact-mongosh-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`createIndexes` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Creates one or more indexes on a collection.
 
+   To minimize the impact of building an index on replica sets and sharded
+   clusters, use a rolling index build procedure
+   as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
+
    :method:`db.collection.createIndexes()` takes the following
    parameters:
 
@@ -144,14 +147,6 @@ Definition
 
           .. versionadded:: 4.4
 
-
-   The :method:`db.collection.createIndexes()` is a wrapper around the
-   :dbcommand:`createIndexes` command.
-
-   To minimize the impact of building an index on replica sets and sharded
-   clusters, use a rolling index build procedure
-   as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
-
 .. _createIndexes-method-options:
 
 Options

source/reference/method/db.collection.distinct.txt

@@ -16,13 +16,15 @@ Definition
 .. method:: db.collection.distinct(field, query, options)
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`distinct` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Finds the distinct
    values for a specified field across a single collection or view and returns
    the results in an array.
 
+   This method takes the following parameters:
 
    .. list-table::
       :header-rows: 1
@@ -57,11 +59,6 @@ Definition
         - Optional. A document that specifies the options.  See :ref:`distinct-method-options`.
 
 
-   
-
-
-   The :method:`db.collection.distinct()` method provides a wrapper
-   around the :dbcommand:`distinct` command.
 
    .. include:: /includes/note-distinct-bson-limit-agg-alternative.rst
 

source/reference/method/db.collection.dropIndex.txt

@@ -16,13 +16,12 @@ Definition
 .. method:: db.collection.dropIndex(index)
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`dropIndexes` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
-   Drops or removes the specified index from a collection. The
-   :method:`db.collection.dropIndex()` method provides a wrapper around
-   the :dbcommand:`dropIndexes` command.
-
+   Drops or removes the specified index from a collection. 
+   
    .. note::
 
       - You cannot drop the default index on the ``_id`` field.
@@ -32,6 +31,10 @@ Definition
         <db.collection.dropIndex>` to drop all non-``_id`` indexes. Use
         :method:`db.collection.dropIndexes()` instead.
 
+   To get the index name or the index specification document for the
+   :method:`db.collection.dropIndex()` method, use the
+   :method:`db.collection.getIndexes()` method.
+
    The :method:`db.collection.dropIndex()` method takes the following
    parameter:
 
@@ -72,9 +75,6 @@ Definition
              :ref:`dropIndex-method-index-builds` for more complete
              documentation.
 
-   To get the index name or the index specification document for the
-   :method:`db.collection.dropIndex()` method, use the
-   :method:`db.collection.getIndexes()` method.
 
 Behavior
 --------

source/reference/method/db.collection.dropIndexes.txt

@@ -17,7 +17,8 @@ Definition
 .. method:: db.collection.dropIndexes()
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`dropIndexes` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Drops the specified index or indexes (except the index on the
@@ -102,9 +103,6 @@ Definition
           **To drop multiple indexes** (Available starting in MongoDB
           4.2), specify an array of the index names.
 
-
-   The :method:`db.collection.dropIndexes()` is a wrapper around the
-   :dbcommand:`dropIndexes` command.
 
 Behavior
 --------

source/reference/method/db.collection.explain.txt

@@ -16,7 +16,8 @@ Description
 .. method:: db.collection.explain()
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`explain` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Returns information on the query plan for the following methods:

source/reference/method/db.collection.find.txt

@@ -16,13 +16,12 @@ Definition
 .. method:: db.collection.find(query, projection, options)
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`find` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Selects documents in a collection or view and returns a
    :term:`cursor` to the selected documents.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80

source/reference/method/db.collection.findAndModify.txt

@@ -19,14 +19,13 @@ Definition
 
 .. method:: db.collection.findAndModify(document)
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`findAndModify` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Modifies and returns a single document. By default, the returned
    document does not include the modifications made on the update. To
    return the document with the modifications made on the update, use
-   the ``new`` option. The :method:`~db.collection.findAndModify()`
-   method is a shell helper around the :dbcommand:`findAndModify`
-   command.
+   the ``new`` option. 
 
    .. versionchanged:: 5.0
 

source/reference/method/db.collection.findOne.txt

@@ -16,7 +16,8 @@ Definition
 .. method:: db.collection.findOne(query, projection, options)
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`find` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Returns one document that satisfies the specified query criteria on

source/reference/method/db.collection.getIndexes.txt

@@ -16,12 +16,15 @@ Definition
 .. method:: db.collection.getIndexes()
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`listIndexes` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
 
    Returns an array that holds a list of documents that identify and
    describe the existing indexes on the collection, including
-   :doc:`hidden indexes </core/index-hidden>`. You must call
+   :doc:`hidden indexes </core/index-hidden>`. 
+
+   You must call
    :method:`db.collection.getIndexes()` on a collection. For example:
 
    .. code-block:: javascript

source/reference/method/db.collection.insertMany.txt

@@ -16,7 +16,8 @@ Definition
 .. method:: db.collection.insertMany()
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`insert` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Inserts multiple documents into a collection.
 

source/reference/method/db.collection.insertOne.txt

@@ -16,7 +16,8 @@ Definition
 .. method:: db.collection.insertOne()
 
 
-   .. include:: /includes/fact-mongosh-shell-method.rst
+   .. |dbcommand| replace:: :dbcommand:`insert` command
+   .. include:: /includes/fact-mongosh-shell-method-alt.rst
 
    Inserts a single document into a collection.