Provided by: libmongoc-doc_1.21.0-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 string singleBatch bool
───────────────────────────────────────────────────────────────────────────────────
allowDiskUse bool
┌─────────────────────┬────────────────────┬─────────────────┬────────────────────┐
│ │ │ │ │
--
--
--
AUTHOR
MongoDB, Inc
COPYRIGHT
2017-present, MongoDB, Inc
1.21.0 Feb 09, 2022 MONGOC_COLLECTION_FIND_WITH_OPTS(3)