1MONGOC_COLLECTION_FIND_WITH_OPTS(3)libmongocMONGOC_COLLECTION_FIND_WITH_OPTS(3)
2
6 mongoc_collection_find_with_opts - mongoc_collection_find_with_opts()
7
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
17 • collection: A mongoc_collection_t.
18 • filter: A bson_t containing the query to execute.
20 • opts: A bson_t query options, including sort order and which fields
22 to return. Can be NULL.
23 • read_prefs: A mongoc_read_prefs_t or NULL.
25
27 Query on collection, passing arbitrary query options to the server in
28 opts.
29 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 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 ┌─────────────────┬──────────────┬───────────┐
41 │Read Preferences │ Read Concern │ Collation │
42 ├─────────────────┼──────────────┼───────────┤
43 │read_prefs │ opts │ opts │
44 ├─────────────────┼──────────────┼───────────┤
45 │Transaction │ Transaction │ │
46 ├─────────────────┼──────────────┼───────────┤
47 │collection │ │ │
48 └─────────────────┴──────────────┴───────────┘
49 See the example for transactions and for the "distinct" command with
51 opts.
52 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
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 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 WARNING:
70 Failure to handle the result of this function is a programming er‐
71 ror.
72
74 Print First Ten Documents in a Collection
75 #include <bson/bson.h>
77 #include <mongoc/mongoc.h>
78 #include <stdio.h>
79 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 /* 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 cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
96 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 if (mongoc_cursor_error (cursor, &error)) {
104 fprintf (stderr, "An error occurred: %s\n", error.message);
105 }
106 mongoc_cursor_destroy (cursor);
108 bson_destroy (filter);
109 bson_destroy (opts);
110 }
111 More examples of modifying the query with opts:
113 bson_t *filter;
115 bson_t *opts;
116 mongoc_read_prefs_t *read_prefs;
117 filter = BCON_NEW ("foo", BCON_INT32 (1));
119 /* 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 read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
137 cursor =
139 mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
140 The following options are supported.
142 ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
144 │Option │ BSON type │ Option │ BSON type │
145 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
146 │projection │ document │ max │ document │
147 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
148 │sort │ document │ maxTimeMS │ non-negative │
149 │ │ │ │ int64 │
150 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
151 │skip │ non-negative │ maxAwaitTimeMS │ non-negative │
152 │ │ int64 │ │ int64 │
153 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
154 │limit │ non-negative │ min │ document │
155 │ │ int64 │ │ │
156 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
157 │batchSize │ non-negative │ noCursorTimeout │ bool │
158 │ │ int64 │ │ │
159 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
160 │exhaust │ bool │ oplogReplay │ bool │
161 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
162 │hint │ string or docu‐ │ readConcern │ document │
163 │ │ ment │ │ │
164 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
165 │allowPartialRe‐ │ bool │ returnKey │ bool │
166 │sults │ │ │ │
167 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
168 │awaitData │ bool │ sessionId │ (none) │
169 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
170 │collation │ document │ showRecordId │ bool │
171 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
172 │comment │ string │ singleBatch │ bool │
173 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
174 │allowDiskUse │ bool │ │ │
175 └────────────────┴──────────────────┴─────────────────┴──────────────┘
176 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 "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 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 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 "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 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 allowDiskUse is only supported in MongoDB 4.4+.
209
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 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
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 /* 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 mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
235 SEE ALSO:
237 The "explain" command in the MongoDB Manual.
238
241 MongoDB, Inc
242
244 2017-present, MongoDB, Inc
2451.21.1 Mar 02, 202M2ONGOC_COLLECTION_FIND_WITH_OPTS(3)