Skip to content

Commit ddb8fd6

Browse files
ianf-mongodbianf-mongodb
authored
DOCSP-35805 Add Find Options to Manual (#6011) (#7073)
* DOCSP-35805 Add Find Options to Manual * * * * * * * * * * * * * * * * * * * * * * * * * examples * * * * * * * * * * * * * IR Joe * * * * * * * * * * * * * * * * * * * * * *
1 parent d2cad8a commit ddb8fd6

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
@@ -80,7 +80,9 @@ parameters:
8080
- document
8181
- .. _method-find-options:
8282

83-
.. include:: /includes/find-options-description.rst
83+
Optional. Specifies additional options for the query. These options
84+
modify query behavior and how results are returned. For details,
85+
see :ref:`find-options`.
8486

8587
Behavior
8688
--------
@@ -102,6 +104,13 @@ of the following form:
102104

103105
.. include:: /includes/extracts/projection-values-table.rst
104106

107+
.. _find-options:
108+
109+
Options
110+
~~~~~~~
111+
112+
.. include:: /includes/find-options-values-table.rst
113+
105114
Embedded Field Specification
106115
````````````````````````````
107116

@@ -620,8 +629,6 @@ You can also specify embedded fields using the nested form. For example:
620629
{ _id: 0, name: { last: 1 }, contribs: { $slice: 2 } }
621630
)
622631

623-
624-
625632
Use Aggregation Expression
626633
``````````````````````````
627634

@@ -949,8 +956,97 @@ Perform the following steps to retrieve the documents accessible to
949956

950957
.. include:: /includes/user-roles-system-variable-example-output-jane.rst
951958

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

955-
To see all available query options, see :node-api-4.0:`FindOptions
956-
</interfaces/findoptions.html>`.
1049+
- :method:`~db.collection.findOne()`
1050+
- :method:`~db.collection.findAndModify()`
1051+
- :method:`~db.collection.findOneAndDelete()`
1052+
- :method:`~db.collection.findOneAndReplace()`

0 commit comments

Comments
 (0)