Access Data by Using a Cursor

Overview

In this guide, you can learn how to use the Rust driver to access data returned from a read operation or aggregation by using a cursor. A cursor is a mechanism that enables you to iterate through multiple documents while holding only a subset of them in memory at a given time.

The driver offers the Cursor type to retrieve documents from a cursor. For example, when you run a find operation that can return multiple documents, the driver returns a Cursor instance from which you can access the matched documents.

After you run a read operation or aggregation, the returned Cursor instance contains the first batch of results from the operation. As you iterate through the cursor, the server returns more individual results. If there are more matching documents after you reach the end of a batch of results, the Cursor instance fetches the next batch of documents until all the results are returned.

This guide includes the following sections:

• Sample Data for Examples presents the sample data that is used by the cursor examples

• Retrieve Documents Individually describes how to use iteration or a stream to access results one at a time

• Retrieve Documents as an Array describes how to access all results as a single array by collecting the returned cursor results

• Specify Cursor Behavior describes how to configure the cursor that a method returns

• Additional Information provides links to resources and API documentation for types and methods mentioned in this guide

Sample Data for Examples

The examples in this guide use the following data stored in a struct:

let docs = vec! [
    Fruit { 
        name: "strawberry".to_string(), 
        color: "red".to_string() 
    },
    Fruit { 
        name: "banana".to_string(), 
        color: "yellow".to_string() 
    },
    Fruit { 
        name: "pomegranate".to_string(), 
        color: "red".to_string() 
    },
    Fruit { 
        name: "pineapple".to_string(), 
        color: "yellow".to_string() 
    }
];

Retrieve Documents Individually

The driver provides the following access patterns to iterate through documents returned by a Cursor instance:

• Built-in Pattern: advance the cursor, then retrieve and deserialize the current document

• Stream Implementation Pattern: iterate over the cursor and call methods provided by Stream to process single or multiple documents

The following sections describe these access patterns and corresponding methods in more detail.

let mut cursor = my_coll.find(doc! { "color": "red" }).await?;
while cursor.advance().await? {
    println!("{:?}", cursor.deserialize_current()?);
}

Fruit { name: "strawberry", color: "red" }
Fruit { name: "pomegranate", color: "red" }

let mut cursor = my_coll.find(doc! { "color": "red" }).await?;
println!("Output from next() iteration:");
while let Some(doc) = cursor.next().await {
    println!("{:?}", doc?);
}
println!();
let mut cursor = my_coll.find(doc! { "color": "yellow" }).await?;
println!("Output from try_next() iteration:");
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Output from next() iteration:
Fruit { name: "strawberry", color: "red" }
Fruit { name: "pomegranate", color: "red" }
Output from try_next() iteration:
Fruit { name: "banana", color: "yellow" }
Fruit { name: "pineapple", color: "yellow" }

Retrieve Documents as an Array

Because the Cursor type implements the Stream trait, you can collect the results from a cursor into an array.

You can use the following methods to retrieve documents as an array:

• collect(): collects results from a cursor into a Vec<Result<T>> type

• try_collect(): collects results from a cursor into a Result<Vec<T>> type

let cursor = my_coll.find(doc! { "color": "red" }).await?;
println!("Output from collect():");
let v: Vec<Result<Fruit>> = cursor.collect().await;
println!("{:?}", v);
println!();
let cursor = my_coll.find(doc! { "color": "yellow" }).await?;
println!("Output from try_collect():");
let v: Vec<Fruit> = cursor.try_collect().await?;
println!("{:?}", v);

Output from collect():
[Ok(Fruit { name: "strawberry", color: "red" }), Ok(Fruit { name: "pomegranate", color: "red" })]
Output from try_collect():
[Fruit { name: "banana", color: "yellow" }, Fruit { name: "pineapple", color: "yellow" }]

Specify Cursor Behavior

To modify the cursor that an operation returns, chain option builder methods to the method that returns the Cursor instance. For example, you can chain cursor-related option builder methods to the find() method.

The following table describes cursor-related options that you can set by calling their corresponding builder method:

The following code shows how to specify cursor-related settings by chaining option builder methods to the find() method:

let mut cursor = my_coll.find(doc! { "color": "red" })
    .batch_size(5)
    .cursor_type(CursorType::Tailable)
    .no_cursor_timeout(true)
    .await?;

Additional Information

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

• Retrieve Data guide

• Specify a Query guide

To learn more about converting between Rust types and BSON, see the guide on Data Modeling and Serialization.