1MONGOC_COLLECTION_FIND_WITH_OPTSM(o3n)goDB C DriMvOeNrGOC_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                    ├─────────────────┼──────────────┼───────────┤
43                    │read_prefs       │ opts         │ opts      │
44                    ├─────────────────┼──────────────┼───────────┤
45                    │Transaction      │ Transaction  │           │
46                    ├─────────────────┼──────────────┼───────────┤
47                    │collection       │              │           │
48                    └─────────────────┴──────────────┴───────────┘
49
50       See  the  example  for transactions and for the "distinct" command with
51       opts.
52

RETURNS

54       A newly allocated mongoc_cursor_t that must be freed  with  mongoc_cur‐
55       sor_destroy().
56

EXAMPLES

58       Print First Ten Documents in a Collection.INDENT 0.0
59
60          #include <bson/bson.h>
61          #include <mongoc/mongoc.h>
62          #include <stdio.h>
63
64          static void
65          print_ten_documents (mongoc_collection_t *collection)
66          {
67             bson_t *filter;
68             bson_t *opts;
69             mongoc_cursor_t *cursor;
70             bson_error_t error;
71             const bson_t *doc;
72             char *str;
73
74             /* filter by "foo": 1, order by "bar" descending */
75             filter = BCON_NEW ("foo", BCON_INT32 (1));
76             opts = BCON_NEW (
77                "limit", BCON_INT64 (10), "sort", "{", "bar", BCON_INT32 (-1), "}");
78
79             cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
80
81             while (mongoc_cursor_next (cursor, &doc)) {
82                str = bson_as_canonical_extended_json (doc, NULL);
83                printf ("%s\n", str);
84                bson_free (str);
85             }
86
87             if (mongoc_cursor_error (cursor, &error)) {
88                fprintf (stderr, "An error occurred: %s\n", error.message);
89             }
90
91             mongoc_cursor_destroy (cursor);
92             bson_destroy (filter);
93             bson_destroy (opts);
94          }
95More examples of modifying the query with opts:.INDENT 0.0
96
97          bson_t *filter;
98          bson_t *opts;
99          mongoc_read_prefs_t *read_prefs;
100
101          filter = BCON_NEW ("foo", BCON_INT32 (1));
102
103          /* Include "field_name_one" and "field_name_two" in "projection", omit
104           * others. "_id" must be specifically removed or it is included by default.
105           */
106          opts = BCON_NEW ("projection", "{",
107                              "field_name_one", BCON_BOOL (true),
108                              "field_name_two", BCON_BOOL (true),
109                              "_id", BCON_BOOL (false),
110                           "}",
111                           "tailable", BCON_BOOL (true),
112                           "awaitData", BCON_BOOL (true),
113                           "sort", "{", "bar", BCON_INT32 (-1), "}",
114                           "collation", "{",
115                              "locale", BCON_UTF8("en_US"),
116                              "caseFirst", BCON_UTF8 ("lower"),
117                           "}");
118
119          read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
120
121          cursor =
122             mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
123
124The following options are supported.
125
126    ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
127    │Option          │ BSON type        │ Option          │ BSON type    │
128    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
129    │projection      │ document         │ max             │ document     │
130    └────────────────┴──────────────────┴─────────────────┴──────────────┘
131
132
133    │sort            │ document         │ maxTimeMS       │ non-negative │
134    │                │                  │                 │ int64        │
135    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
136    │skip            │ non-negative     │ maxAwaitTimeMS  │ non-negative │
137    │                │ int64            │                 │ int64        │
138    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
139    │limit           │ non-negative     │ min             │ document     │
140    │                │ int64            │                 │              │
141    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
142    │batchSize       │ non-negative     │ noCursorTimeout │ bool         │
143    │                │ int64            │                 │              │
144    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
145    │exhaust         │ bool             │ oplogReplay     │ bool         │
146    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
147    │hint            │ string or  docu‐ │ readConcern     │ document     │
148    │                │ ment             │                 │              │
149    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
150    │allowPartialRe‐ │ bool             │ returnKey       │ bool         │
151    │sults           │                  │                 │              │
152    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
153    │awaitData       │ bool             │ sessionId       │ (none)       │
154    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
155    │collation       │ document         │ showRecordId    │ bool         │
156    ├────────────────┼──────────────────┼─────────────────┼──────────────┤
157    │comment         │ string           │ singleBatch     │ bool         │
158    └────────────────┴──────────────────┴─────────────────┴──────────────┘
159
160All options are documented in the reference page for the "find" command in the
161MongoDB server manual, except for "maxAwaitTimeMS" and "sessionId".
162
163"maxAwaitTimeMS"  is  the maximum amount of time for the server to wait on new
164documents to satisfy a query, if "tailable" and "awaitData" are both true.  If
165no  new  documents are found, the tailable cursor receives an empty batch. The
166"maxAwaitTimeMS" option is ignored for MongoDB older than 3.4.
167
168To  add  a  "sessionId",  construct  a   mongoc_client_session_t   with   mon‐

goc_client_start_session. You can begin a transaction with mongoc_client_ses‐

sion_start_transaction, optionally with a mongoc_transaction_opt_t that over‐

171rides  the  options  inherited  from  collection.  Then use mongoc_client_ses‐

sion_append to add the session to opts. See the example code for mon‐

goc_client_session_t.

174
175To   add   a   "readConcern",  construct  a  mongoc_read_concern_t  with  mon‐

goc_read_concern_new and configure it with mongoc_read_concern_set_level. Then

177use mongoc_read_concern_append to add the read concern to opts.
178
179For  some  options like "collation", the driver returns an error if the server
180version is too old to support the feature.  Any fields in opts  that  are  not
181listed here are passed to the server unmodified.
182

DEPRECATED OPTIONS

184       The  snapshot  boolean  option  is  removed in MongoDB 4.0. The maxScan
185       option, a non-negative int64, is deprecated in MongoDB 4.0 and will  be
186       removed  in a future MongoDB version. Both options are supported by the
187       C Driver with older MongoDB versions.
188

SEE ALSO

190       The "find" command in the MongoDB Manual. All options listed there  are
191       supported  by  the  C  Driver.   For MongoDB servers before 3.2, or for
192       exhaust queries, the driver  transparently  converts  the  query  to  a
193       legacy OP_QUERY message.
194

THE EXPLAIN COMMAND

196       With  MongoDB  before  3.2,  a query with option $explain: true returns
197       information about the query plan, instead of the query results.  Begin‐
198       ning  in MongoDB 3.2, there is a separate "explain" command. The driver
199       will not convert "$explain" queries to  "explain"  commands,  you  must
200       call the "explain" command explicitly:
201
202          /* MongoDB 3.2+, "explain" command syntax */
203          command = BCON_NEW ("explain", "{",
204                              "find", BCON_UTF8 ("collection_name"),
205                              "filter", "{", "foo", BCON_INT32 (1), "}",
206                              "}");
207
208          mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
209

SEE ALSO

211       The "explain" command in the MongoDB Manual.
212

AUTHOR

214       MongoDB, Inc
215

COPYRIGHT

217       2017-present, MongoDB, Inc
218
219
220
221
2221.13.1                           Jan 24, 201M9ONGOC_COLLECTION_FIND_WITH_OPTS(3)