Skip to content

Commit 9d63746

Browse files
ianf-mongodbianf-mongodb
authored
DOCSP-35805 Add Find Options to Manual (#6011) (#7074)
* DOCSP-35805 Add Find Options to Manual * * * * * * * * * * * * * * * * * * * * * * * * * examples * * * * * * * * * * * * * IR Joe * * * * * * * * * * * * * * * * * * * * * *
1 parent ea9ad22 commit 9d63746

File tree

2 files changed

+194
-5
lines changed

2 files changed

+194
-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: 104 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

@@ -902,5 +909,97 @@ Output:
902909

903910
[ { flavor: 'chocolate' } ]
904911

905-
To see all available query options, see :node-api-4.0:`FindOptions
906-
</interfaces/findoptions.html>`.
912+
Modify a Query with options
913+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
914+
915+
The following examples show how you can use the ``options`` field
916+
in a ``find()`` query. Use the following
917+
:method:`~db.collection.insertMany()` to setup the ``users`` collection:
918+
919+
.. code-block:: javascript
920+
:copyable: true
921+
922+
db.users.insertMany( [
923+
{ username: "david", age: 27 },
924+
{ username: "amanda", age: 25 },
925+
{ username: "rajiv", age: 32 },
926+
{ username: "rajiv", age: 90 }
927+
] )
928+
929+
limit with options
930+
``````````````````
931+
932+
The following query limits the number of documents in the result set
933+
with the ``limit`` options parameter:
934+
935+
.. code-block:: javascript
936+
:copyable: true
937+
:emphasize-lines: 4
938+
939+
db.users.find(
940+
{ username : "rajiv"}, // query
941+
{ age : 1 }, // projection
942+
{ limit : 1 } // options
943+
)
944+
945+
allowDiskUse with options
946+
`````````````````````````
947+
948+
The following query uses the ``options`` parameter to enable
949+
``allowDiskUse``:
950+
951+
.. code-block:: javascript
952+
:copyable: true
953+
:emphasize-lines: 4
954+
955+
db.users.find(
956+
{ username : "david" },
957+
{ age : 1 },
958+
{ allowDiskUse : true }
959+
)
960+
961+
explain with options
962+
````````````````````
963+
964+
The following query uses the ``options`` parameter to get the
965+
``executionStats`` explain output:
966+
967+
.. code-block:: javascript
968+
:copyable: true
969+
:emphasize-lines: 4
970+
971+
var cursor = db.users.find(
972+
{ username: "amanda" },
973+
{ age : 1 },
974+
{ explain : "executionStats" }
975+
)
976+
cursor.next()
977+
978+
Specify Multiple options in a query
979+
```````````````````````````````````
980+
981+
The following query uses multiple ``options`` in a single query. This
982+
query uses ``limit`` set to ``2`` to return only two documents, and
983+
``showRecordId`` set to ``true`` to return the position of the document
984+
in the result set:
985+
986+
.. code-block:: javascript
987+
:copyable: true
988+
:emphasize-lines: 4-7
989+
990+
db.users.find(
991+
{},
992+
{ username: 1, age: 1 },
993+
{
994+
limit: 2,
995+
showRecordId: true
996+
}
997+
)
998+
999+
Learn More
1000+
----------
1001+
1002+
- :method:`~db.collection.findOne()`
1003+
- :method:`~db.collection.findAndModify()`
1004+
- :method:`~db.collection.findOneAndDelete()`
1005+
- :method:`~db.collection.findOneAndReplace()`

0 commit comments

Comments
 (0)