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

17       · collection: A mongoc_collection_t.
18
19       · filter: A bson_t containing the query to execute.
20
21       · opts:  A  bson_t query options, including sort order and which fields
22         to return. Can be NULL.
23
24       · read_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       A  newly  allocated mongoc_cursor_t that must be freed with mongoc_cur‐
60       sor_destroy().
61

EXAMPLES

63       Print First Ten Documents in a Collection
64
65          #include <bson/bson.h>
66          #include <mongoc/mongoc.h>
67          #include <stdio.h>
68
69          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
79             /* 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
84             cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
85
86             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
92             if (mongoc_cursor_error (cursor, &error)) {
93                fprintf (stderr, "An error occurred: %s\n", error.message);
94             }
95
96             mongoc_cursor_destroy (cursor);
97             bson_destroy (filter);
98             bson_destroy (opts);
99          }
100
101       More examples of modifying the query with opts:
102
103          bson_t *filter;
104          bson_t *opts;
105          mongoc_read_prefs_t *read_prefs;
106
107          filter = BCON_NEW ("foo", BCON_INT32 (1));
108
109          /* 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
125          read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
126
127          cursor =
128             mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
129
130       The following options are supported.
131
132
133        ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
134        │Option          │ BSON type        │ Option          │ BSON type    │
135        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
136projection      │ document         │ max             │ document     │
137        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
138sort            │ document         │ maxTimeMS       │ non-negative │
139        │                │                  │                 │ int64        │
140        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
141skip            │ non-negative     │ maxAwaitTimeMS  │ non-negative │
142        │                │ int64            │                 │ int64        │
143        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
144limit           │ non-negative     │ min             │ document     │
145        │                │ int64            │                 │              │
146        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
147batchSize       │ non-negative     │ noCursorTimeout │ bool         │
148        │                │ int64            │                 │              │
149        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
150exhaust         │ bool             │ oplogReplay     │ bool         │
151        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
152hint            │ string  or docu‐ │ readConcern     │ document     │
153        │                │ ment             │                 │              │
154        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
155allowPartialRe‐ │ bool             │ returnKey       │ bool         │
156sults           │                  │                 │              │
157        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
158awaitData       │ bool             │ sessionId       │ (none)       │
159        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
160collation       │ document         │ showRecordId    │ bool         │
161        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
162comment         │ string           │ singleBatch     │ bool         │
163        ├────────────────┼──────────────────┼─────────────────┼──────────────┤
164allowDiskUse    │ bool             │                 │              │
165        └────────────────┴──────────────────┴─────────────────┴──────────────┘
166
167       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
171       "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
177       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
184       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
189       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
193       allowDiskUse is only supported in MongoDB 4.4+.
194

DEPRECATED OPTIONS

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

SEE ALSO

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

THE EXPLAIN COMMAND

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
215          /* 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
221          mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
222

SEE ALSO

224       The "explain" command in the MongoDB Manual.
225

AUTHOR

227       MongoDB, Inc
228
230       2017-present, MongoDB, Inc
231
232
233
234
2351.17.4                           Feb 04, 202M1ONGOC_COLLECTION_FIND_WITH_OPTS(3)
Impressum