Retrieve Data

Sample Data

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Find Documents Example

The following example uses the mongoc_collection_find_with_opts() function to find all documents in which the value of the cuisine field is "Spanish":

bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Spanish"));
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, NULL, NULL);

The mongoc_collection_find_with_opts() operation in the preceding example returns a mongoc_cursor_t *, which you can iterate through by using the mongoc_cursor_next() function and a while loop. The following example iterates through and prints the results returned in the previous query:

const bson_t *doc;
bson_error_t error;
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
// Ensure we iterated through cursor without error
if (mongoc_cursor_error (results, &error)) {
    fprintf (stderr, "Error getting results: %s\n", error.message);
}
mongoc_cursor_destroy (results);
bson_destroy (filter);

{ "_id" : { "$oid" : "..." }, "name" : "Charle'S Corner Restaurant & Deli", "cuisine" : "Spanish", ... }
{ "_id" : { "$oid" : "..." }, "name" : "Real Madrid Restaurant", "cuisine" : "Spanish", ... }
{ "_id" : { "$oid" : "..." }, "name" : "Malaga Restaurant", "cuisine" : "Spanish", ... }
{ "_id" : { "$oid" : "..." }, "name" : "Cafe Espanol", "cuisine" : "Spanish", ... }
{ "_id" : { "$oid" : "..." }, "name" : "Cafe Riazor", "cuisine" : "Spanish", ... }
...

bson_t *empty_filter = bson_new ();
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, empty_filter, NULL, NULL);
mongoc_cursor_destroy (results);
bson_destroy (empty_filter);

Modify Find Behavior

You can modify the behavior of the mongoc_collection_find_with_opts() function by by passing in a bson_t structure that contains the options you want to configure. The following table describes options commonly used for modifying queries:

The following example uses the limit and maxTimeMS options to limit the number of documents returned by the query to 10 and set a maximum execution time of 10000 milliseconds on the operation:

bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Spanish"));
bson_t *opts = BCON_NEW ("limit", BCON_INT32 (10), "maxTimeMS", BCON_INT32 (10000));
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
mongoc_cursor_destroy (results);
bson_destroy (filter);
bson_destroy (opts);

For a full list of options that modify the behavior of mongoc_collection_find_with_opts(), see the find method documentation in the MongoDB Server manual.

API Documentation

To learn more about any of the functions discussed in this guide, see the following API documentation:

• mongoc_collection_find_with_opts()