mongoc_collection_find_with_opts man page

mongoc_collection_find_with_opts() — Query on collection, passing arbitrary query options to the server in opts.


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)


A mongoc_collection_t
A bson_t containing the query to execute.
A bson_t query options, including sort order and which fields to return. Can be NULL
A mongoc_read_prefs_t or NULL


Query on collection , passing arbitrary query options to the server in opts


A newly allocated mongoc_cursor_t that must be freed with mongoc_cursor_destroy(3)


#include <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_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),
                 "orderby", "{", "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.

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.

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, or for exhaust queries, 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.


This page is part of MongoDB C Driver. Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.


Explore man page connections for mongoc_collection_find_with_opts(3).