1MONGOC_COLLECTION_FIND_WITH_OPTS(3)libmongocMONGOC_COLLECTION_FIND_WITH_OPTS(3)
2
3
4

NAME

6       mongoc_collection_find_with_opts - mongoc_collection_find_with_opts()
7

SYNOPSIS

9          mongoc_cursor_t *
10          mongoc_collection_find_with_opts (mongoc_collection_t *collection,
11                                            const bson_t *filter,
12                                            const bson_t *opts,
13                                            const mongoc_read_prefs_t *read_prefs)
14             BSON_GNUC_WARN_UNUSED_RESULT;
15

PARAMETERS

17collection: A mongoc_collection_t.
18
19filter: A bson_t containing the query to execute.
20
21opts:  A  bson_t query options, including sort order and which fields
22         to return. Can be NULL.
23
24read_prefs: A mongoc_read_prefs_t or NULL.
25

DESCRIPTION

27       Query on collection, passing arbitrary query options to the  server  in
28       opts.
29
30       To  target  a  specific  server, include an integer "serverId" field in
31       opts with an id obtained first by calling  mongoc_client_select_server,
32       then mongoc_server_description_id on its return value.
33
34       Read preferences, read concern, and collation can be overridden by var‐
35       ious sources. In a transaction, read concern and write concern are pro‐
36       hibited  in  opts  and the read preference must be primary or NULL. The
37       highest-priority sources for these options are listed first in the fol‐
38       lowing table. No write concern is applied.
39
40                    ┌─────────────────┬──────────────┬───────────┐
41                    │Read Preferences │ Read Concern │ Collation │
42                    ├─────────────────┼──────────────┼───────────┤
43read_prefs       opts         opts      
44                    ├─────────────────┼──────────────┼───────────┤
45                    │Transaction      │ Transaction  │           │
46                    ├─────────────────┼──────────────┼───────────┤
47collection       │              │           │
48                    └─────────────────┴──────────────┴───────────┘
49
50       See  the  example  for transactions and for the "distinct" command with
51       opts.
52
53       This function is considered a retryable read operation.  Upon  a  tran‐
54       sient error (a network error, errors due to replica set failover, etc.)
55       the operation is safely retried once.  If retryreads is  false  in  the
56       URI (see mongoc_uri_t) the retry behavior does not apply.
57

RETURNS

59       This  function returns a newly allocated mongoc_cursor_t that should be
60       freed with mongoc_cursor_destroy() when no longer in use. The  returned
61       mongoc_cursor_t  is  never NULL, even on error. The user must call mon‐
62       goc_cursor_next() on the returned mongoc_cursor_t to execute  the  ini‐
63       tial command.
64
65       Cursor  errors can be checked with mongoc_cursor_error_document. It al‐
66       ways fills out the bson_error_t if an error  occurred,  and  optionally
67       includes a server reply document if the error occurred server-side.
68
69       WARNING:
70          Failure  to  handle the result of this function is a programming er‐
71          ror.
72

EXAMPLES

74       Print First Ten Documents in a Collection
75
76          #include <bson/bson.h>
77          #include <mongoc/mongoc.h>
78          #include <stdio.h>
79
80          static void
81          print_ten_documents (mongoc_collection_t *collection)
82          {
83             bson_t *filter;
84             bson_t *opts;
85             mongoc_cursor_t *cursor;
86             bson_error_t error;
87             const bson_t *doc;
88             char *str;
89
90             /* filter by "foo": 1, order by "bar" descending */
91             filter = BCON_NEW ("foo", BCON_INT32 (1));
92             opts = BCON_NEW (
93                "limit", BCON_INT64 (10), "sort", "{", "bar", BCON_INT32 (-1), "}");
94
95             cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
96
97             while (mongoc_cursor_next (cursor, &doc)) {
98                str = bson_as_canonical_extended_json (doc, NULL);
99                printf ("%s\n", str);
100                bson_free (str);
101             }
102
103             if (mongoc_cursor_error (cursor, &error)) {
104                fprintf (stderr, "An error occurred: %s\n", error.message);
105             }
106
107             mongoc_cursor_destroy (cursor);
108             bson_destroy (filter);
109             bson_destroy (opts);
110          }
111
112       More examples of modifying the query with opts:
113
114          bson_t *filter;
115          bson_t *opts;
116          mongoc_read_prefs_t *read_prefs;
117
118          filter = BCON_NEW ("foo", BCON_INT32 (1));
119
120          /* Include "field_name_one" and "field_name_two" in "projection", omit
121           * others. "_id" must be specifically removed or it is included by default.
122           */
123          opts = BCON_NEW ("projection", "{",
124                              "field_name_one", BCON_BOOL (true),
125                              "field_name_two", BCON_BOOL (true),
126                              "_id", BCON_BOOL (false),
127                           "}",
128                           "tailable", BCON_BOOL (true),
129                           "awaitData", BCON_BOOL (true),
130                           "sort", "{", "bar", BCON_INT32 (-1), "}",
131                           "collation", "{",
132                              "locale", BCON_UTF8("en_US"),
133                              "caseFirst", BCON_UTF8 ("lower"),
134                           "}");
135
136          read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
137
138          cursor =
139             mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
140
141       The following options are supported.
142
143        ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
144        │Option          │ BSON type        │ Option          │ BSON type    │
145        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
146projection      │ document         │ max             │ document     │
147        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
148sort            │ document         │ maxTimeMS       │ non-negative │
149        │                │                  │                 │ int64        │
150        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
151skip            │ non-negative     │ maxAwaitTimeMS  │ non-negative │
152        │                │ int64            │                 │ int64        │
153        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
154limit           │ non-negative     │ min             │ document     │
155        │                │ int64            │                 │              │
156        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
157batchSize       │ non-negative     │ noCursorTimeout │ bool         │
158        │                │ int64            │                 │              │
159        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
160exhaust         │ bool             │ oplogReplay     │ bool         │
161        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
162hint            │ string  or docu‐ │ readConcern     │ document     │
163        │                │ ment             │                 │              │
164        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
165allowPartialRe‐ │ bool             │ returnKey       │ bool         │
166sults           │                  │                 │              │
167        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
168awaitData       │ bool             │ sessionId       │ (none)       │
169        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
170collation       │ document         │ showRecordId    │ bool         │
171        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
172comment         │ string           │ singleBatch     │ bool         │
173        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
174allowDiskUse    │ bool             │                 │              │
175        └────────────────┴──────────────────┴─────────────────┴──────────────┘
176
177       All options are documented in the reference page for the "find" command
178       in the MongoDB server manual, except for "maxAwaitTimeMS", "sessionId",
179       and "exhaust".
180
181       "maxAwaitTimeMS"  is  the maximum amount of time for the server to wait
182       on new documents to satisfy a query, if "tailable" and "awaitData"  are
183       both true.  If no new documents are found, the tailable cursor receives
184       an empty batch. The "maxAwaitTimeMS"  option  is  ignored  for  MongoDB
185       older than 3.4.
186
187       To  add  a  "sessionId",  construct a mongoc_client_session_t with mon‐
188       goc_client_start_session.  You  can  begin  a  transaction  with   mon‐
189       goc_client_session_start_transaction, optionally with a mongoc_transac‐
190       tion_opt_t that overrides the options inherited from  collection.  Then
191       use  mongoc_client_session_append  to  add the session to opts. See the
192       example code for mongoc_client_session_t.
193
194       To add a "readConcern", construct  a  mongoc_read_concern_t  with  mon‐
195       goc_read_concern_new    and    configure   it   with   mongoc_read_con‐
196       cern_set_level. Then use mongoc_read_concern_append  to  add  the  read
197       concern to opts.
198
199       "exhaust"  requests  the construction of an exhaust cursor. For MongoDB
200       servers before 5.1, this option converts  the  command  into  a  legacy
201       OP_QUERY message. For MongoDB servers 5.1 and newer, this option is ig‐
202       nored and a normal cursor is constructed instead.
203
204       For some options like "collation", the driver returns an error  if  the
205       server  version  is too old to support the feature.  Any fields in opts
206       that are not listed here are passed to the server unmodified.
207
208       allowDiskUse is only supported in MongoDB 4.4+.
209

DEPRECATED OPTIONS

211       The snapshot boolean option is removed in MongoDB 4.0. The maxScan  op‐
212       tion,  a  non-negative  int64, is deprecated in MongoDB 4.0 and will be
213       removed in a future MongoDB version. The oplogReplay boolean option  is
214       deprecated  in MongoDB 4.4. All of these options are supported by the C
215       Driver with older MongoDB versions.
216
217       SEE ALSO:
218          The "find" command in the MongoDB Manual. All options listed there are supported by the C Driver.  For MongoDB servers before 3.2, the driver transparently converts the query to a legacy OP_QUERY message.
219
220

THE EXPLAIN COMMAND

222       With MongoDB before 3.2, a query with option $explain: true returns in‐
223       formation about the query plan, instead of the query results. Beginning
224       in MongoDB 3.2, there is a separate "explain" command. The driver  will
225       not convert "$explain" queries to "explain" commands, you must call the
226       "explain" command explicitly:
227
228          /* MongoDB 3.2+, "explain" command syntax */
229          command = BCON_NEW ("explain", "{",
230                              "find", BCON_UTF8 ("collection_name"),
231                              "filter", "{", "foo", BCON_INT32 (1), "}",
232                              "}");
233
234          mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
235
236       SEE ALSO:
237          The "explain" command in the MongoDB Manual.
238
239

AUTHOR

241       MongoDB, Inc
242
244       2017-present, MongoDB, Inc
245
246
247
248
2491.21.1                           Mar 02, 202M2ONGOC_COLLECTION_FIND_WITH_OPTS(3)
Impressum