Specify Documents to Return

Overview

In this guide, you can learn how to specify which documents to return from a read operation by using the following operations:

• limit: Specifies the maximum number of documents to return from a query

• sort: Specifies the sort order for the returned documents

• skip: Specifies the number of documents to skip before returning query results

Limit

To specify the maximum number of documents returned from a read operation, pass the limit option to your mongoc_collection_find_with_opts() function call.

The following example finds all restaurants that have a cuisine field value of "Italian" and limits the results to 5 documents:

const bson_t *doc;
bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Italian"));
bson_t *opts = BCON_NEW ("limit", BCON_INT64 (5));
mongoc_cursor_t *results =
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "V & T Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Mimis Restaurant & Bar", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Venice Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Areo Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Tre Giovani Pizza & Pasta", ... }

Sort

To return documents in a specified order, use the sort option. The sort option takes a sort direction as a parameter. To specify the sort direction, pass a 1 for an ascending sort or a -1 for a descending sort. Ascending sorts order values from lowest to highest, and descending sorts order values from highest to lowest.

The following example returns all documents with a cuisine field value of "Italian", sorted by the value of the name field in ascending order:

const bson_t *doc;
bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Italian"));
bson_t *opts = BCON_NEW ("sort", "{", "name", BCON_INT32 (1), "}");
mongoc_cursor_t *results =
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "(Lewis Drug Store) Locanda Vini E Olii", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "101 Restaurant And Bar", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "44 Sw Ristorante & Bar", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "900 Park", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "A Voce", ... }
...

Skip

To skip a specified number of documents before returning your query results, use the skip option and pass in the number of documents to skip. The skip option ignores the specified number of documents in your query results, then returns the rest.

The following example returns all documents that have a cuisine field value of "Italian" and skips the first 10 documents:

const bson_t *doc;
bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Italian"));
bson_t *opts = BCON_NEW ("skip", BCON_INT64 (10));
mongoc_cursor_t *results =
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Trattoria Alba", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Da Umberto Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "La Strada Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Pasta Lovers Trattoria", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Nanni Restaurant", ... }
...

Combine Limit, Sort, and Skip

You can combine the limit, sort, and skip options in a single operation. This allows you to set a maximum number of sorted documents to return, skipping a specified number of documents before returning.

The following example returns documents with the cuisine field value of "Italian". The results are sorted in alphabetical order, skipping the first 10 documents and limiting the results to 5 documents:

const bson_t *doc;
bson_t *filter = BCON_NEW ("cuisine", BCON_UTF8 ("Italian"));
bson_t *opts = BCON_NEW ("limit", BCON_INT64 (5),
                        "skip", BCON_INT64 (10), 
                        "sort", "{", "name", BCON_INT32 (1), "}");
                        
mongoc_cursor_t *results =
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Acqua", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Acqua Restaurant", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Acqua Santa", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Acquista Trattoria", ... }
{ "_id" : { "$oid" : "..." }, "cuisine" : "Italian", "name" : "Acquolina Catering", ... }

Additional Information

For more information about specifying a query, see Specify a Query.

For more information about retrieving documents, see Retrieve Data.