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

RETURNS

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

EXAMPLES

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

DEPRECATED OPTIONS

214       The  snapshot boolean option is removed in MongoDB 4.0. The maxScan op‐
215       tion, a non-negative int64, is deprecated in MongoDB 4.0  and  will  be
216       removed  in a future MongoDB version. The oplogReplay boolean option is
217       deprecated in MongoDB 4.4. All of these options are supported by the  C
218       Driver with older MongoDB versions.
219
220       SEE ALSO:
221          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.
222
223

THE EXPLAIN COMMAND

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

AUTHOR

244       MongoDB, Inc
245
247       2017-present, MongoDB, Inc
248
249
250
251
2521.23.1                           Oct 20, 202M2ONGOC_COLLECTION_FIND_WITH_OPTS(3)
Impressum