/ /

Skip Returned Results

Overview

In this guide, you can learn how to use the MongoDB Rust Driver to perform a read operation that skips a specified number of documents when returning results.

Sample Data for Examples

The examples in this guide use the following Book struct as a model for documents in the books collection:

#[derive(Debug, Serialize, Deserialize)]
struct Book {
    name: String,
    author: String,
    length: i32,
}

The following code shows how to insert sample data into the books collection:

let uri = "connection string";
let client = Client::with_uri_str(uri).await?;
let my_coll: Collection<Book> = client.database("db").collection("books");
let books = vec![
    Book {
        name: "The Brothers Karamazov".to_string(),
        author: "Dostoyevsky".to_string(),
        length: 824,
    },
    Book {
        name: "Atlas Shrugged".to_string(),
        author: "Rand".to_string(),
        length: 1088,
    },
    Book {
        name: "Les Misérables".to_string(),
        author: "Hugo".to_string(),
        length: 1462,
    },
    Book {
        name: "A Dance with Dragons".to_string(),
        author: "Martin".to_string(),
        length: 1104,
    },
];
my_coll.insert_many(books, None).await?;

Skip Documents

You can skip results retrieved by a query, or you can skip results within an aggregation pipeline.

If the number of skipped documents exceeds the number of matched documents for a query, then that query returns no documents.

Find operations return documents in a natural order that is not sorted on any fields. To avoid skipping random documents, use the sort() method to sort documents on a field with a unique value before setting a skip option. To learn more, see the Sort Results guide.

Query Results Example

To skip documents, you can initialize a FindOptions instance and specify the number of documents you want to skip using the skip() method. Then, pass your FindOptions struct as a parameter to the find() method.

This example runs a find() operation that performs the following actions:

Sorts the results in ascending order of their author field values
Skips the first two documents
Returns the remaining documents

let find_options = FindOptions::builder()
    .sort(doc! { "author": 1 })
    .skip(2)
    .build();
let mut cursor = my_coll.find(doc! {}, find_options).await?;
while let Some(result) = cursor.try_next().await? {
    println!("{:?}", result);
}

Book { name: "A Dance with Dragons", author: "Martin", length: 1104 }
Book { name: "Atlas Shrugged", author: "Rand", length: 1088 }

Aggregation Example

You can use the $skip stage in an aggregation pipeline to skip documents. To learn more about aggregation operations, see the Aggregation guide.

This example runs an aggregation pipeline that performs the following actions:

Sorts the results in ascending order of their author field values
Skips the first document
Returns the remaining documents

let pipeline = vec![
    doc! { "$match": {} },
    doc! { "$sort": { "author": 1 } },
    doc! { "$skip": 1 },
];
let mut cursor = my_coll.aggregate(pipeline, None).await?;
while let Some(result) = cursor.try_next().await? {
    println!("{:?}", result);
}

Document({"_id": ObjectId("..."), "name": String("Les Misérables"), "author": String("Hugo"), "length": Int32(1462)})
Document({"_id": ObjectId("..."), "name": String("A Dance with Dragons"), "author": String("Martin"), "length": Int32(1104)})
Document({"_id": ObjectId("..."), "name": String("Atlas Shrugged"), "author": String("Rand"), "length": Int32(1088)})

Additional Information

To learn more about the operations mentioned in this guide, see the following guides:

API Documentation

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

Back

Sort Results

Limit Results