1MONGOC_COLLECTION_FIND_WITH_OPTS(3)libmongocMONGOC_COLLECTION_FIND_WITH_OPTS(3)
2
6 mongoc_cursor_t *
7 mongoc_collection_find_with_opts (mongoc_collection_t *collection,
8 const bson_t *filter,
9 const bson_t *opts,
10 const mongoc_read_prefs_t *read_prefs)
11 BSON_GNUC_WARN_UNUSED_RESULT;
12
14 • collection: A mongoc_collection_t.
15 • filter: A bson_t containing the query to execute.
17 • opts: A bson_t query options, including sort order and which fields
19 to return. Can be NULL.
20 • read_prefs: A mongoc_read_prefs_t or NULL.
22
24 Query on collection, passing arbitrary query options to the server in
25 opts.
26 To target a specific server, include an integer "serverId" field in
28 opts with an id obtained first by calling
29 mongoc_client_select_server(), then mongoc_server_description_id() on
30 its return value.
31 Read preferences, read concern, and collation can be overridden by var‐
33 ious sources. In a transaction, read concern and write concern are pro‐
34 hibited in opts and the read preference must be primary or NULL. The
35 highest-priority sources for these options are listed first in the fol‐
36 lowing table. No write concern is applied.
37 ┌─────────────────┬──────────────┬───────────┐
39 │Read Preferences │ Read Concern │ Collation │
40 ├─────────────────┼──────────────┼───────────┤
41 │read_prefs │ opts │ opts │
42 ├─────────────────┼──────────────┼───────────┤
43 │Transaction │ Transaction │ │
44 ├─────────────────┼──────────────┼───────────┤
45 │collection │ │ │
46 └─────────────────┴──────────────┴───────────┘
47 See the example for transactions and for the "distinct" command with
49 opts.
50 This function is considered a retryable read operation. Upon a tran‐
52 sient error (a network error, errors due to replica set failover, etc.)
53 the operation is safely retried once. If retryreads is false in the
54 URI (see mongoc_uri_t) the retry behavior does not apply.
55
57 This function returns a newly allocated mongoc_cursor_t that should be
58 freed with mongoc_cursor_destroy() when no longer in use. The returned
59 mongoc_cursor_t is never NULL, even on error. The user must call
60 mongoc_cursor_next() on the returned mongoc_cursor_t to execute the
61 initial command.
62 Cursor errors can be checked with mongoc_cursor_error_document(). It
64 always fills out the bson_error_t if an error occurred, and optionally
65 includes a server reply document if the error occurred server-side.
66 WARNING:
68 Failure to handle the result of this function is a programming er‐
69 ror.
70
72 Print First Ten Documents in a Collection
73 #include <bson/bson.h>
75 #include <mongoc/mongoc.h>
76 #include <stdio.h>
77 static void
79 print_ten_documents (mongoc_collection_t *collection)
80 {
81 bson_t *filter;
82 bson_t *opts;
83 mongoc_cursor_t *cursor;
84 bson_error_t error;
85 const bson_t *doc;
86 char *str;
87 /* filter by "foo": 1, order by "bar" descending */
89 filter = BCON_NEW ("foo", BCON_INT32 (1));
90 opts = BCON_NEW (
91 "limit", BCON_INT64 (10), "sort", "{", "bar", BCON_INT32 (-1), "}");
92 cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
94 while (mongoc_cursor_next (cursor, &doc)) {
96 str = bson_as_canonical_extended_json (doc, NULL);
97 printf ("%s\n", str);
98 bson_free (str);
99 }
100 if (mongoc_cursor_error (cursor, &error)) {
102 fprintf (stderr, "An error occurred: %s\n", error.message);
103 }
104 mongoc_cursor_destroy (cursor);
106 bson_destroy (filter);
107 bson_destroy (opts);
108 }
109 More examples of modifying the query with opts:
111 bson_t *filter;
113 bson_t *opts;
114 mongoc_read_prefs_t *read_prefs;
115 filter = BCON_NEW ("foo", BCON_INT32 (1));
117 /* Include "field_name_one" and "field_name_two" in "projection", omit
119 * others. "_id" must be specifically removed or it is included by default.
120 */
121 opts = BCON_NEW ("projection", "{",
122 "field_name_one", BCON_BOOL (true),
123 "field_name_two", BCON_BOOL (true),
124 "_id", BCON_BOOL (false),
125 "}",
126 "tailable", BCON_BOOL (true),
127 "awaitData", BCON_BOOL (true),
128 "sort", "{", "bar", BCON_INT32 (-1), "}",
129 "collation", "{",
130 "locale", BCON_UTF8("en_US"),
131 "caseFirst", BCON_UTF8 ("lower"),
132 "}");
133 read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
135 cursor =
137 mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
138 The following options are supported.
140 ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
142 │Option │ BSON type │ Option │ BSON type │
143 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
144 │projection │ document │ max │ document │
145 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
146 │sort │ document │ maxTimeMS │ non-negative │
147 │ │ │ │ int64 │
148 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
149 │skip │ non-negative │ maxAwaitTimeMS │ non-negative │
150 │ │ int64 │ │ int64 │
151 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
152 │limit │ non-negative │ min │ document │
153 │ │ int64 │ │ │
154 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
155 │batchSize │ non-negative │ noCursorTimeout │ bool │
156 │ │ int64 │ │ │
157 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
158 │exhaust │ bool │ oplogReplay │ bool │
159 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
160 │hint │ string or docu‐ │ readConcern │ document │
161 │ │ ment │ │ │
162 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
163 │allowPartialRe‐ │ bool │ returnKey │ bool │
164 │sults │ │ │ │
165 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
166 │awaitData │ bool │ sessionId │ (none) │
167 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
168 │collation │ document │ showRecordId │ bool │
169 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
170 │comment │ any │ singleBatch │ bool │
171 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
172 │allowDiskUse │ bool │ let │ document │
173 └────────────────┴──────────────────┴─────────────────┴──────────────┘
174 All options are documented in the reference page for the "find" command
176 in the MongoDB server manual, except for "maxAwaitTimeMS", "sessionId",
177 and "exhaust".
178 "maxAwaitTimeMS" is the maximum amount of time for the server to wait
180 on new documents to satisfy a query, if "tailable" and "awaitData" are
181 both true. If no new documents are found, the tailable cursor receives
182 an empty batch. The "maxAwaitTimeMS" option is ignored for MongoDB
183 older than 3.4.
184 To add a "sessionId", construct a mongoc_client_session_t with
186 mongoc_client_start_session(). You can begin a transaction with
187 mongoc_client_session_start_transaction(), optionally with a
188 mongoc_transaction_opt_t that overrides the options inherited from col‐
189 lection. Then use mongoc_client_session_append() to add the session to
190 opts. See the example code for mongoc_client_session_t.
191 To add a "readConcern", construct a mongoc_read_concern_t with
193 mongoc_read_concern_new() and configure it with
194 mongoc_read_concern_set_level(). Then use mongoc_read_concern_append()
195 to add the read concern to opts.
196 "exhaust" requests the construction of an exhaust cursor.
198 For some options like "collation", the driver returns an error if the
200 server version is too old to support the feature. Any fields in opts
201 that are not listed here are passed to the server unmodified.
202 allowDiskUse is only supported in MongoDB 4.4+.
204 comment only supports string values prior to MongoDB 4.4.
206
208 The snapshot boolean option is removed in MongoDB 4.0. The maxScan op‐
209 tion, a non-negative int64, is deprecated in MongoDB 4.0 and will be
210 removed in a future MongoDB version. The oplogReplay boolean option is
211 deprecated in MongoDB 4.4. All of these options are supported by the C
212 Driver with older MongoDB versions.
213 SEE ALSO:
215 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.
216
219 With MongoDB before 3.2, a query with option $explain: true returns in‐
220 formation about the query plan, instead of the query results. Beginning
221 in MongoDB 3.2, there is a separate "explain" command. The driver will
222 not convert "$explain" queries to "explain" commands, you must call the
223 "explain" command explicitly:
224 /* MongoDB 3.2+, "explain" command syntax */
226 command = BCON_NEW ("explain", "{",
227 "find", BCON_UTF8 ("collection_name"),
228 "filter", "{", "foo", BCON_INT32 (1), "}",
229 "}");
230 mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
232 SEE ALSO:
234 The "explain" command in the MongoDB Manual.
235
238 MongoDB, Inc
239
241 2017-present, MongoDB, Inc
2421.25.1 Nov 08, 202M3ONGOC_COLLECTION_FIND_WITH_OPTS(3)