mongoc_collection_find_with_opts(3)

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                    ├─────────────────┼──────────────┼───────────┤
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
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.INDENT 0.0
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          }
100More examples of modifying the query with opts:.INDENT 0.0
101
102          bson_t *filter;
103          bson_t *opts;
104          mongoc_read_prefs_t *read_prefs;
105
106          filter = BCON_NEW ("foo", BCON_INT32 (1));
107
108          /* Include "field_name_one" and "field_name_two" in "projection", omit
109           * others. "_id" must be specifically removed or it is included by default.
110           */
111          opts = BCON_NEW ("projection", "{",
112                              "field_name_one", BCON_BOOL (true),
113                              "field_name_two", BCON_BOOL (true),
114                              "_id", BCON_BOOL (false),
115                           "}",
116                           "tailable", BCON_BOOL (true),
117                           "awaitData", BCON_BOOL (true),
118                           "sort", "{", "bar", BCON_INT32 (-1), "}",
119                           "collation", "{",
120                              "locale", BCON_UTF8("en_US"),
121                              "caseFirst", BCON_UTF8 ("lower"),
122                           "}");
123
124          read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
125
126          cursor =
127             mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
128
129The following options are supported.
130
131
132
133    ┌────────────────┬──────────────────┬─────────────────┬──────────────┐
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
165All options are documented in the reference page for the "find" command in the
166MongoDB server manual, except for "maxAwaitTimeMS" and "sessionId".
167
168"maxAwaitTimeMS" is the maximum amount of time for the server to wait  on  new
169documents to satisfy a query, if "tailable" and "awaitData" are both true.  If
170no new documents are found, the tailable cursor receives an empty  batch.  The
171"maxAwaitTimeMS" option is ignored for MongoDB older than 3.4.
172
173To   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‐

176rides 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.

179
180To  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

182use mongoc_read_concern_append to add the read concern to opts.
183
184For some options like "collation", the driver returns an error if  the  server
185version  is  too  old to support the feature.  Any fields in opts that are not
186listed here are passed to the server unmodified.
187

DEPRECATED OPTIONS

189       The snapshot boolean option is removed  in  MongoDB  4.0.  The  maxScan
190       option,  a non-negative int64, is deprecated in MongoDB 4.0 and will be
191       removed in a future MongoDB version. Both options are supported by  the
192       C Driver with older MongoDB versions.
193

THE EXPLAIN COMMAND

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

AUTHOR

219       MongoDB, Inc
220

COPYRIGHT

222       2017-present, MongoDB, Inc
223
224
225
226
2271.16.2                           Feb 25, 202M0ONGOC_COLLECTION_FIND_WITH_OPTS(3)

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

EXAMPLES

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‐

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

goc_client_session_t.

goc_read_concern_new and configure it with mongoc_read_concern_set_level. Then

DEPRECATED OPTIONS

SEE ALSO

THE EXPLAIN COMMAND

SEE ALSO

AUTHOR

COPYRIGHT