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 A newly allocated mongoc_cursor_t that must be freed with mongoc_cur‐
60 sor_destroy().
61
63 Print First Ten Documents in a Collection
64 #include <bson/bson.h>
66 #include <mongoc/mongoc.h>
67 #include <stdio.h>
68 static void
70 print_ten_documents (mongoc_collection_t *collection)
71 {
72 bson_t *filter;
73 bson_t *opts;
74 mongoc_cursor_t *cursor;
75 bson_error_t error;
76 const bson_t *doc;
77 char *str;
78 /* filter by "foo": 1, order by "bar" descending */
80 filter = BCON_NEW ("foo", BCON_INT32 (1));
81 opts = BCON_NEW (
82 "limit", BCON_INT64 (10), "sort", "{", "bar", BCON_INT32 (-1), "}");
83 cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
85 while (mongoc_cursor_next (cursor, &doc)) {
87 str = bson_as_canonical_extended_json (doc, NULL);
88 printf ("%s\n", str);
89 bson_free (str);
90 }
91 if (mongoc_cursor_error (cursor, &error)) {
93 fprintf (stderr, "An error occurred: %s\n", error.message);
94 }
95 mongoc_cursor_destroy (cursor);
97 bson_destroy (filter);
98 bson_destroy (opts);
99 }
100 More examples of modifying the query with opts:
102 bson_t *filter;
104 bson_t *opts;
105 mongoc_read_prefs_t *read_prefs;
106 filter = BCON_NEW ("foo", BCON_INT32 (1));
108 /* Include "field_name_one" and "field_name_two" in "projection", omit
110 * others. "_id" must be specifically removed or it is included by default.
111 */
112 opts = BCON_NEW ("projection", "{",
113 "field_name_one", BCON_BOOL (true),
114 "field_name_two", BCON_BOOL (true),
115 "_id", BCON_BOOL (false),
116 "}",
117 "tailable", BCON_BOOL (true),
118 "awaitData", BCON_BOOL (true),
119 "sort", "{", "bar", BCON_INT32 (-1), "}",
120 "collation", "{",
121 "locale", BCON_UTF8("en_US"),
122 "caseFirst", BCON_UTF8 ("lower"),
123 "}");
124 read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
126 cursor =
128 mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
129 The following options are supported.
131 ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
134 │Option │ BSON type │ Option │ BSON type │
135 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
136 │projection │ document │ max │ document │
137 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
138 │sort │ document │ maxTimeMS │ non-negative │
139 │ │ │ │ int64 │
140 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
141 │skip │ non-negative │ maxAwaitTimeMS │ non-negative │
142 │ │ int64 │ │ int64 │
143 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
144 │limit │ non-negative │ min │ document │
145 │ │ int64 │ │ │
146 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
147 │batchSize │ non-negative │ noCursorTimeout │ bool │
148 │ │ int64 │ │ │
149 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
150 │exhaust │ bool │ oplogReplay │ bool │
151 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
152 │hint │ string or docu‐ │ readConcern │ document │
153 │ │ ment │ │ │
154 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
155 │allowPartialRe‐ │ bool │ returnKey │ bool │
156 │sults │ │ │ │
157 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
158 │awaitData │ bool │ sessionId │ (none) │
159 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
160 │collation │ document │ showRecordId │ bool │
161 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
162 │comment │ string │ singleBatch │ bool │
163 ├────────────────┼──────────────────┼─────────────────┼──────────────┤
164 │allowDiskUse │ bool │ │ │
165 └────────────────┴──────────────────┴─────────────────┴──────────────┘
166 All options are documented in the reference page for the "find" command
168 in the MongoDB server manual, except for "maxAwaitTimeMS" and "ses‐
169 sionId".
170 "maxAwaitTimeMS" is the maximum amount of time for the server to wait
172 on new documents to satisfy a query, if "tailable" and "awaitData" are
173 both true. If no new documents are found, the tailable cursor receives
174 an empty batch. The "maxAwaitTimeMS" option is ignored for MongoDB
175 older than 3.4.
176 To add a "sessionId", construct a mongoc_client_session_t with mon‐
178 goc_client_start_session. You can begin a transaction with mon‐
179 goc_client_session_start_transaction, optionally with a mongoc_transac‐
180 tion_opt_t that overrides the options inherited from collection. Then
181 use mongoc_client_session_append to add the session to opts. See the
182 example code for mongoc_client_session_t.
183 To add a "readConcern", construct a mongoc_read_concern_t with mon‐
185 goc_read_concern_new and configure it with mongoc_read_con‐
186 cern_set_level. Then use mongoc_read_concern_append to add the read
187 concern to opts.
188 For some options like "collation", the driver returns an error if the
190 server version is too old to support the feature. Any fields in opts
191 that are not listed here are passed to the server unmodified.
192 allowDiskUse is only supported in MongoDB 4.4+.
194
196 The snapshot boolean option is removed in MongoDB 4.0. The maxScan
197 option, a non-negative int64, is deprecated in MongoDB 4.0 and will be
198 removed in a future MongoDB version. The oplogReplay boolean option is
199 deprecated in MongoDB 4.4. All of these options are supported by the C
200 Driver with older MongoDB versions.
201
203 The "find" command in the MongoDB Manual. All options listed there are
204 supported by the C Driver. For MongoDB servers before 3.2, or for
205 exhaust queries, the driver transparently converts the query to a
206 legacy OP_QUERY message.
207
209 With MongoDB before 3.2, a query with option $explain: true returns
210 information about the query plan, instead of the query results. Begin‐
211 ning in MongoDB 3.2, there is a separate "explain" command. The driver
212 will not convert "$explain" queries to "explain" commands, you must
213 call the "explain" command explicitly:
214 /* MongoDB 3.2+, "explain" command syntax */
216 command = BCON_NEW ("explain", "{",
217 "find", BCON_UTF8 ("collection_name"),
218 "filter", "{", "foo", BCON_INT32 (1), "}",
219 "}");
220 mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
222
224 The "explain" command in the MongoDB Manual.
225
227 MongoDB, Inc
228
230 2017-present, MongoDB, Inc
2311.17.4 Feb 04, 202M1ONGOC_COLLECTION_FIND_WITH_OPTS(3)