Provided by: libmongoc-doc_1.23.1-1build1_all 
NAME
mongoc_collection_find_with_opts - mongoc_collection_find_with_opts()
SYNOPSIS
mongoc_cursor_t *
mongoc_collection_find_with_opts (mongoc_collection_t *collection,
const bson_t *filter,
const bson_t *opts,
const mongoc_read_prefs_t *read_prefs)
BSON_GNUC_WARN_UNUSED_RESULT;
PARAMETERS
• collection: A mongoc_collection_t.
• filter: A bson_t containing the query to execute.
• opts: A bson_t query options, including sort order and which fields to return. Can be
NULL.
• read_prefs: A mongoc_read_prefs_t or NULL.
DESCRIPTION
Query on collection, passing arbitrary query options to the server in opts.
To target a specific server, include an integer "serverId" field in opts with an id
obtained first by calling mongoc_client_select_server(), then
mongoc_server_description_id() on its return value.
Read preferences, read concern, and collation can be overridden by various sources. In a
transaction, read concern and write concern are prohibited in opts and the read preference
must be primary or NULL. The highest-priority sources for these options are listed first
in the following table. No write concern is applied.
┌─────────────────┬──────────────┬───────────┐
│Read Preferences │ Read Concern │ Collation │
├─────────────────┼──────────────┼───────────┤
│read_prefs │ opts │ opts │
├─────────────────┼──────────────┼───────────┤
│Transaction │ Transaction │ │
├─────────────────┼──────────────┼───────────┤
│collection │ │ │
└─────────────────┴──────────────┴───────────┘
See the example for transactions and for the "distinct" command with opts.
This function is considered a retryable read operation. Upon a transient error (a network
error, errors due to replica set failover, etc.) the operation is safely retried once. If
retryreads is false in the URI (see mongoc_uri_t) the retry behavior does not apply.
RETURNS
This function returns a newly allocated mongoc_cursor_t that should be freed with
mongoc_cursor_destroy() when no longer in use. The returned mongoc_cursor_t is never NULL,
even on error. The user must call mongoc_cursor_next() on the returned mongoc_cursor_t to
execute the initial command.
Cursor errors can be checked with mongoc_cursor_error_document(). It always fills out the
bson_error_t if an error occurred, and optionally includes a server reply document if the
error occurred server-side.
WARNING:
Failure to handle the result of this function is a programming error.
EXAMPLES
Print First Ten Documents in a Collection
#include <bson/bson.h>
#include <mongoc/mongoc.h>
#include <stdio.h>
static void
print_ten_documents (mongoc_collection_t *collection)
{
bson_t *filter;
bson_t *opts;
mongoc_cursor_t *cursor;
bson_error_t error;
const bson_t *doc;
char *str;
/* filter by "foo": 1, order by "bar" descending */
filter = BCON_NEW ("foo", BCON_INT32 (1));
opts = BCON_NEW (
"limit", BCON_INT64 (10), "sort", "{", "bar", BCON_INT32 (-1), "}");
cursor = mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (cursor, &doc)) {
str = bson_as_canonical_extended_json (doc, NULL);
printf ("%s\n", str);
bson_free (str);
}
if (mongoc_cursor_error (cursor, &error)) {
fprintf (stderr, "An error occurred: %s\n", error.message);
}
mongoc_cursor_destroy (cursor);
bson_destroy (filter);
bson_destroy (opts);
}
More examples of modifying the query with opts:
bson_t *filter;
bson_t *opts;
mongoc_read_prefs_t *read_prefs;
filter = BCON_NEW ("foo", BCON_INT32 (1));
/* Include "field_name_one" and "field_name_two" in "projection", omit
* others. "_id" must be specifically removed or it is included by default.
*/
opts = BCON_NEW ("projection", "{",
"field_name_one", BCON_BOOL (true),
"field_name_two", BCON_BOOL (true),
"_id", BCON_BOOL (false),
"}",
"tailable", BCON_BOOL (true),
"awaitData", BCON_BOOL (true),
"sort", "{", "bar", BCON_INT32 (-1), "}",
"collation", "{",
"locale", BCON_UTF8("en_US"),
"caseFirst", BCON_UTF8 ("lower"),
"}");
read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
cursor =
mongoc_collection_find_with_opts (collection, filter, opts, read_prefs);
The following options are supported.
┌────────────────────┬────────────────────┬─────────────────┬────────────────────┐
│Option │ BSON type │ Option │ BSON type │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│projection │ document │ max │ document │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│sort │ document │ maxTimeMS │ non-negative int64 │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│skip │ non-negative int64 │ maxAwaitTimeMS │ non-negative int64 │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│limit │ non-negative int64 │ min │ document │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│batchSize │ non-negative int64 │ noCursorTimeout │ bool │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│exhaust │ bool │ oplogReplay │ bool │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│hint │ string or document │ readConcern │ document │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│allowPartialResults │ bool │ returnKey │ bool │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│awaitData │ bool │ sessionId │ (none) │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│collation │ document │ showRecordId │ bool │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│comment │ any │ singleBatch │ bool │
├────────────────────┼────────────────────┼─────────────────┼────────────────────┤
│allowDiskUse │ bool │ let │ document │
└────────────────────┴────────────────────┴─────────────────┴────────────────────┘
All options are documented in the reference page for the "find" command in the MongoDB
server manual, except for "maxAwaitTimeMS", "sessionId", and "exhaust".
"maxAwaitTimeMS" is the maximum amount of time for the server to wait on new documents to
satisfy a query, if "tailable" and "awaitData" are both true. If no new documents are
found, the tailable cursor receives an empty batch. The "maxAwaitTimeMS" option is ignored
for MongoDB older than 3.4.
To add a "sessionId", construct a mongoc_client_session_t with
mongoc_client_start_session(). You can begin a transaction with
mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that
overrides the options inherited from collection. Then use mongoc_client_session_append()
to add the session to opts. See the example code for mongoc_client_session_t.
To add a "readConcern", construct a mongoc_read_concern_t with mongoc_read_concern_new()
and configure it with mongoc_read_concern_set_level(). Then use
mongoc_read_concern_append() to add the read concern to opts.
"exhaust" requests the construction of an exhaust cursor. For MongoDB servers before 5.1,
this option converts the command into a legacy OP_QUERY message. For MongoDB servers 5.1
and newer, this option is ignored and a normal cursor is constructed instead.
For some options like "collation", the driver returns an error if the server version is
too old to support the feature. Any fields in opts that are not listed here are passed to
the server unmodified.
allowDiskUse is only supported in MongoDB 4.4+.
comment only supports string values prior to MongoDB 4.4.
DEPRECATED OPTIONS
The snapshot boolean option is removed in MongoDB 4.0. The maxScan option, a non-negative
int64, is deprecated in MongoDB 4.0 and will be removed in a future MongoDB version. The
oplogReplay boolean option is deprecated in MongoDB 4.4. All of these options are
supported by the C Driver with older MongoDB versions.
SEE ALSO:
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.
THE EXPLAIN COMMAND
With MongoDB before 3.2, a query with option $explain: true returns information about the
query plan, instead of the query results. Beginning in MongoDB 3.2, there is a separate
"explain" command. The driver will not convert "$explain" queries to "explain" commands,
you must call the "explain" command explicitly:
/* MongoDB 3.2+, "explain" command syntax */
command = BCON_NEW ("explain", "{",
"find", BCON_UTF8 ("collection_name"),
"filter", "{", "foo", BCON_INT32 (1), "}",
"}");
mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
SEE ALSO:
The "explain" command in the MongoDB Manual.
AUTHOR
MongoDB, Inc
COPYRIGHT
2017-present, MongoDB, Inc