Skip Returned Results

On this page

Overview

Sample Data for Examples
Skip Documents
skip() Method Example
Options Example
Aggregation Example
Additional Information
API Documentation

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 {
        id: 1,
        name: "The Brothers Karamazov".to_string(),
        author: "Dostoyevsky".to_string(),
        length: 824,
    },
    Book {
        id: 2,
        name: "Atlas Shrugged".to_string(),
        author: "Rand".to_string(),
        length: 1088,
    },
    Book {
        id: 3,
        name: "Les Misérables".to_string(),
        author: "Hugo".to_string(),
        length: 1462,
    },
    Book {
        id: 4,
        name: "A Dance with Dragons".to_string(),
        author: "Martin".to_string(),
        length: 1104,
    },
];
my_coll.insert_many(books).await?;

Skip Documents

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

This section describes how to skip results in the following ways:

skip() method: Chain the skip() method to the find() method
FindOptions struct: Use the skip() option builder method to configure a FindOptions struct
Aggregation pipleline: Create a pipeline that uses the $skip stage

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.

skip() Method Example

To skip documents, you can chain the skip() method to the find() method. The skip() method takes an integer that specifies the number of documents to omit from the beginning of the result set.

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 mut cursor = my_coll
    .find(doc! {})
    .sort(doc! { "author": 1 })
    .skip(2).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 }

Options Example

Alternatively, if you are setting and reusing options for your query, you can use FindOptions. Set the skip field of the FindOptions struct by using the skip() option builder method. Then, chain the with_options() method to the find() method and pass your FindOptions struct as a parameter to the with_options() method.

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

Sorts the results in descending order of their name field values
Skips the first document
Returns the remaining documents

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

Book { name: "Les Misérables", author: "Hugo", length: 1462 }
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).await?;
while let Some(result) = cursor.try_next().await? {
    println!("{:?}", result);
}

Document({"_id": Int32(3), "name": String("Les Misérables"), "author": String("Hugo"), "length": Int32(1462)})
Document({"_id": Int32(4), "name": String("A Dance with Dragons"), "author": String("Martin"), "length": Int32(1104)})
Document({"_id": Int32(2), "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 the Number of Returned Results