(DOCSP-17336): Add query options for find and findOne (#1752)

* add query options for find

* (DOCSP-17336): Add query options for find and findOne

* use include for example intro

* wording

* add 'options' to prototype

* change example to 'let'

* remove old include

* fix findOne output

* fix broken substitutions

Author: jeff-allen-mongo

source/includes/find-options-description.rst

@@ -0,0 +1,3 @@
+Optional. Specifies additional options for the query. These options
+modify query behavior and how results are returned. To see available
+options, see :node-api-4.0:`FindOptions </interfaces/findoptions.html>`.

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

@@ -13,7 +13,7 @@ db.collection.find()
 Definition
 ----------
 
-.. method:: db.collection.find(query, projection)
+.. method:: db.collection.find(query, projection, options)
 
 
    .. include:: /includes/fact-mongosh-shell-method.rst
@@ -33,11 +33,13 @@ Definition
 
         - Description
 
-      * - ``query``
+      * - :ref:`query <method-find-query>`
 
         - document
 
-        - Optional. Specifies selection filter using :doc:`query operators
+        - .. _method-find-query:
+        
+          Optional. Specifies selection filter using :doc:`query operators
           </reference/operator>`. To return all documents in a collection, omit
           this parameter or pass an empty document (``{}``).
 
@@ -52,10 +54,14 @@ Definition
           Optional. Specifies the fields to return in the documents that match the
           query filter. To return all fields in the matching documents, omit this
           parameter.  For details, see :ref:`find-projection`.
-          
-          
-   
 
+      * - :ref:`options <method-find-options>`
+
+        - document
+
+        - .. _method-find-options:
+
+          .. include:: /includes/find-options-description.rst
 
    :returns:
 
@@ -851,3 +857,36 @@ Available ``mongosh`` Cursor Methods
    - :method:`cursor.sort()`
    - :method:`cursor.tailable()`
    - :method:`cursor.toArray()`
+
+Use Variables in ``let`` Option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify query options to modify query behavior and indicate how
+results are returned.
+
+For example, to define variables that you can access elsewhere in the
+``find`` method, use the ``let`` option. To filter results using a
+variable, you must access the variable within the :query:`$expr`
+operator.
+
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines a ``targetFlavor`` variable in ``let`` and
+uses the variable to retrieve the chocolate cake flavor:
+
+.. code-block:: javascript
+
+   db.cakeFlavors.find(
+      { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+      { _id: 0 },
+      { let : { targetFlavor: "chocolate" }
+   } )
+
+Output:
+
+.. code-block:: javascript
+
+   [ { flavor: 'chocolate' } ]
+
+To see all available query options, see :node-api-4.0:`FindOptions
+</interfaces/findoptions.html>`.

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

@@ -13,7 +13,7 @@ db.collection.findOne()
 Definition
 ----------
 
-.. method:: db.collection.findOne(query, projection)
+.. method:: db.collection.findOne(query, projection, options)
 
 
    .. include:: /includes/fact-mongosh-shell-method.rst
@@ -55,6 +55,12 @@ Definition
           Omit this parameter to return all fields in the matching
           document. For details, see :ref:`findOne-projection`.
 
+      * - ``options``
+
+        - document
+
+        - .. include:: /includes/find-options-description.rst
+
    :returns:
       One document that satisfies the criteria specified as the first
       argument to this method. If you specify a ``projection``
@@ -215,3 +221,36 @@ returned. You have access to the document directly:
 
       print (tojson(myName));
    }
+
+Use Variables in ``let`` Option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify query options to modify query behavior and indicate how
+results are returned.
+
+For example, to define variables that you can access elsewhere in the
+``findOne`` method, use the ``let`` option. To filter results using a
+variable, you must access the variable within the :query:`$expr`
+operator.
+
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines a ``targetFlavor`` variable in ``let`` and
+uses the variable to retrieve the chocolate cake flavor:
+
+.. code-block:: javascript
+
+   db.cakeFlavors.findOne(
+      { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+      { _id: 0 },
+      { let : { targetFlavor: "chocolate" }
+   } )
+
+Output:
+
+.. code-block:: javascript
+
+   { flavor: 'chocolate' }
+
+To see all available query options, see :node-api-4.0:`FindOptions
+</interfaces/findoptions.html>`.