Skip to content

Commit 6e10941

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

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
@@ -90,7 +90,9 @@ parameters:
9090
- document
9191
- .. _method-find-options:
9292

93-
.. include:: /includes/find-options-description.rst
93+
Optional. Specifies additional options for the query. These options
94+
modify query behavior and how results are returned. For details,
95+
see :ref:`find-options`.
9496

9597
Behavior
9698
--------
@@ -112,6 +114,13 @@ of the following form:
112114

113115
.. include:: /includes/extracts/projection-values-table.rst
114116

117+
.. _find-options:
118+
119+
Options
120+
~~~~~~~
121+
122+
.. include:: /includes/find-options-values-table.rst
123+
115124
Embedded Field Specification
116125
````````````````````````````
117126

@@ -662,8 +671,6 @@ You can also specify embedded fields using the nested form. For example:
662671
{ _id: 0, name: { last: 1 }, contribs: { $slice: 2 } }
663672
)
664673

665-
666-
667674
Use Aggregation Expression
668675
``````````````````````````
669676

@@ -991,8 +998,97 @@ Perform the following steps to retrieve the documents accessible to
991998

992999
.. include:: /includes/user-roles-system-variable-example-output-jane.rst
9931000

1001+
Modify a Query with options
1002+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
1003+
1004+
The following examples show how you can use the ``options`` field
1005+
in a ``find()`` query. Use the following
1006+
:method:`~db.collection.insertMany()` to setup the ``users`` collection:
1007+
1008+
.. code-block:: javascript
1009+
:copyable: true
1010+
1011+
db.users.insertMany( [
1012+
{ username: "david", age: 27 },
1013+
{ username: "amanda", age: 25 },
1014+
{ username: "rajiv", age: 32 },
1015+
{ username: "rajiv", age: 90 }
1016+
] )
1017+
1018+
limit with options
1019+
``````````````````
1020+
1021+
The following query limits the number of documents in the result set
1022+
with the ``limit`` options parameter:
1023+
1024+
.. code-block:: javascript
1025+
:copyable: true
1026+
:emphasize-lines: 4
1027+
1028+
db.users.find(
1029+
{ username : "rajiv"}, // query
1030+
{ age : 1 }, // projection
1031+
{ limit : 1 } // options
1032+
)
1033+
1034+
allowDiskUse with options
1035+
`````````````````````````
1036+
1037+
The following query uses the ``options`` parameter to enable
1038+
``allowDiskUse``:
1039+
1040+
.. code-block:: javascript
1041+
:copyable: true
1042+
:emphasize-lines: 4
1043+
1044+
db.users.find(
1045+
{ username : "david" },
1046+
{ age : 1 },
1047+
{ allowDiskUse : true }
1048+
)
1049+
1050+
explain with options
1051+
````````````````````
1052+
1053+
The following query uses the ``options`` parameter to get the
1054+
``executionStats`` explain output:
1055+
1056+
.. code-block:: javascript
1057+
:copyable: true
1058+
:emphasize-lines: 4
1059+
1060+
var cursor = db.users.find(
1061+
{ username: "amanda" },
1062+
{ age : 1 },
1063+
{ explain : "executionStats" }
1064+
)
1065+
cursor.next()
1066+
1067+
Specify Multiple options in a query
1068+
```````````````````````````````````
1069+
1070+
The following query uses multiple ``options`` in a single query. This
1071+
query uses ``limit`` set to ``2`` to return only two documents, and
1072+
``showRecordId`` set to ``true`` to return the position of the document
1073+
in the result set:
1074+
1075+
.. code-block:: javascript
1076+
:copyable: true
1077+
:emphasize-lines: 4-7
1078+
1079+
db.users.find(
1080+
{},
1081+
{ username: 1, age: 1 },
1082+
{
1083+
limit: 2,
1084+
showRecordId: true
1085+
}
1086+
)
1087+
9941088
Learn More
9951089
----------
9961090

997-
To see all available query options, see :node-api-4.0:`FindOptions
998-
</interfaces/findoptions.html>`.
1091+
- :method:`~db.collection.findOne()`
1092+
- :method:`~db.collection.findAndModify()`
1093+
- :method:`~db.collection.findOneAndDelete()`
1094+
- :method:`~db.collection.findOneAndReplace()`

0 commit comments

Comments
 (0)