Skip to content

Commit 31ea363

Browse files
ianf-mongodbianf-mongodb
authored
DOCSP-35805 Add Find Options to Manual (#6011) (#7072)
* DOCSP-35805 Add Find Options to Manual * * * * * * * * * * * * * * * * * * * * * * * * * examples * * * * * * * * * * * * * IR Joe * * * * * * * * * * * * * * * * * * * * * *
1 parent b1fbb51 commit 31ea363

File tree

2 files changed

+191
-5
lines changed

2 files changed

+191
-5
lines changed

‎source/includes/find-options-values-table.rst

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
.. Note to author: This page duplicates the content from the github.io page:
2+
.. https://mongodb.github.io/node-mongodb-native/6.5/interfaces/FindOptions.html
3+
.. All the options defined here also work in mongosh
4+
5+
.. list-table::
6+
:header-rows: 1
7+
:widths: 25 75
8+
9+
* - Option
10+
- Description
11+
12+
* - allowDiskUse
13+
- Whether or not pipelines that require more than 100 megabytes of
14+
memory to execute write to temporary files on disk. For details,
15+
see :method:`cursor.allowDiskUse()`.
16+
17+
* - allowPartialResults
18+
- For queries against a sharded collection, allows the command
19+
(or subsequent getMore commands) to return partial results,
20+
rather than an error, if one or more queried shards are
21+
unavailable.
22+
23+
* - awaitData
24+
- If the cursor is a a tailable-await cursor.
25+
Requires ``tailable`` to be ``true``.
26+
27+
* - collation
28+
- Collation settings for update operation.
29+
30+
* - comment
31+
- Adds a ``$comment`` to the query that shows in the
32+
:ref:`profiler <profiler>` logs.
33+
34+
* - explain
35+
- Adds explain output based on the verbosity mode provided.
36+
37+
* - hint
38+
- Forces the query optimizer to use specific indexes in the
39+
query.
40+
41+
* - limit
42+
- Sets a limit of documents returned in the result set.
43+
44+
* - max
45+
- The exclusive upper bound for a specific index.
46+
47+
* - maxAwaitTimeMS
48+
- The maximum amount of time for the server to wait on
49+
new documents to satisfy a tailable cursor query. Requires
50+
``tailable`` and ``awaitData`` to be ``true``.
51+
52+
* - maxTimeMS
53+
- The maximum amount of time (in milliseconds) the
54+
server should allow the query to run.
55+
56+
* - min
57+
- The inclusive lower bound for a specific index.
58+
59+
* - noCursorTimeout
60+
- Whether the server should timeout the cursor
61+
after a period of inactivity (by default 10 minutes).
62+
63+
* - readConcern
64+
- Specifies the read concern level for the query.
65+
66+
* - readPreference
67+
- Specifies the read preference level for the query.
68+
69+
* - returnKey
70+
- Whether only the index keys are returned for a
71+
query.
72+
73+
* - showRecordId
74+
- If the ``$recordId`` field is added to the returned
75+
documents. The ``$recordId`` indicates the position of the
76+
document in the result set.
77+
78+
* - skip
79+
- How many documents to skip before returning the
80+
first document in the result set.
81+
82+
* - sort
83+
- The order of the documents returned in the result
84+
set. Fields specified in the sort, must have an index.
85+
86+
* - tailable
87+
- Indicates if the cursor is tailable. Tailable cursors remain
88+
open after the intial results of the query are exhausted.
89+
Tailable cursors are only available on
90+
:ref:`manual-capped-collection`.

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

Lines changed: 101 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,9 @@ parameters:
8484
- document
8585
- .. _method-find-options:
8686

87-
.. include:: /includes/find-options-description.rst
87+
Optional. Specifies additional options for the query. These options
88+
modify query behavior and how results are returned. For details,
89+
see :ref:`find-options`.
8890

8991
Behavior
9092
--------
@@ -106,6 +108,13 @@ of the following form:
106108

107109
.. include:: /includes/extracts/projection-values-table.rst
108110

111+
.. _find-options:
112+
113+
Options
114+
~~~~~~~
115+
116+
.. include:: /includes/find-options-values-table.rst
117+
109118
Embedded Field Specification
110119
````````````````````````````
111120

@@ -624,8 +633,6 @@ You can also specify embedded fields using the nested form. For example:
624633
{ _id: 0, name: { last: 1 }, contribs: { $slice: 2 } }
625634
)
626635

627-
628-
629636
Use Aggregation Expression
630637
``````````````````````````
631638

@@ -953,8 +960,97 @@ Perform the following steps to retrieve the documents accessible to
953960

954961
.. include:: /includes/user-roles-system-variable-example-output-jane.rst
955962

963+
Modify a Query with options
964+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
965+
966+
The following examples show how you can use the ``options`` field
967+
in a ``find()`` query. Use the following
968+
:method:`~db.collection.insertMany()` to setup the ``users`` collection:
969+
970+
.. code-block:: javascript
971+
:copyable: true
972+
973+
db.users.insertMany( [
974+
{ username: "david", age: 27 },
975+
{ username: "amanda", age: 25 },
976+
{ username: "rajiv", age: 32 },
977+
{ username: "rajiv", age: 90 }
978+
] )
979+
980+
limit with options
981+
``````````````````
982+
983+
The following query limits the number of documents in the result set
984+
with the ``limit`` options parameter:
985+
986+
.. code-block:: javascript
987+
:copyable: true
988+
:emphasize-lines: 4
989+
990+
db.users.find(
991+
{ username : "rajiv"}, // query
992+
{ age : 1 }, // projection
993+
{ limit : 1 } // options
994+
)
995+
996+
allowDiskUse with options
997+
`````````````````````````
998+
999+
The following query uses the ``options`` parameter to enable
1000+
``allowDiskUse``:
1001+
1002+
.. code-block:: javascript
1003+
:copyable: true
1004+
:emphasize-lines: 4
1005+
1006+
db.users.find(
1007+
{ username : "david" },
1008+
{ age : 1 },
1009+
{ allowDiskUse : true }
1010+
)
1011+
1012+
explain with options
1013+
````````````````````
1014+
1015+
The following query uses the ``options`` parameter to get the
1016+
``executionStats`` explain output:
1017+
1018+
.. code-block:: javascript
1019+
:copyable: true
1020+
:emphasize-lines: 4
1021+
1022+
var cursor = db.users.find(
1023+
{ username: "amanda" },
1024+
{ age : 1 },
1025+
{ explain : "executionStats" }
1026+
)
1027+
cursor.next()
1028+
1029+
Specify Multiple options in a query
1030+
```````````````````````````````````
1031+
1032+
The following query uses multiple ``options`` in a single query. This
1033+
query uses ``limit`` set to ``2`` to return only two documents, and
1034+
``showRecordId`` set to ``true`` to return the position of the document
1035+
in the result set:
1036+
1037+
.. code-block:: javascript
1038+
:copyable: true
1039+
:emphasize-lines: 4-7
1040+
1041+
db.users.find(
1042+
{},
1043+
{ username: 1, age: 1 },
1044+
{
1045+
limit: 2,
1046+
showRecordId: true
1047+
}
1048+
)
1049+
9561050
Learn More
9571051
----------
9581052

959-
To see all available query options, see :node-api-4.0:`FindOptions
960-
</interfaces/findoptions.html>`.
1053+
- :method:`~db.collection.findOne()`
1054+
- :method:`~db.collection.findAndModify()`
1055+
- :method:`~db.collection.findOneAndDelete()`
1056+
- :method:`~db.collection.findOneAndReplace()`

0 commit comments

Comments
 (0)