Skip Returned Results

On this page

Overview

Sample Data for Examples
Skip Documents
Query Results 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 {
        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 Data

Limit Results