Struct mongodb::Cursor

pub struct Cursor<T> { /* private fields */ }

A Cursor streams the result of a query. When a query is made, the returned Cursor will contain the first batch of results from the server; the individual results will then be returned as the Cursor is iterated. When the batch is exhausted and if there are more results, the Cursor will fetch the next batch of documents, and so forth until the results are exhausted. Note that because of this batching, additional network I/O may occur on any given call to next. Because of this, a Cursor iterates over Result<T> items rather than simply T items.

The batch size of the Cursor can be configured using the options to the method that returns it. For example, setting the batch_size field of FindOptions will set the batch size of the Cursor returned by Collection::find.

Note that the batch size determines both the number of documents stored in memory by the Cursor at a given time as well as the total number of network round-trips needed to fetch all results from the server; both of these factors should be taken into account when choosing the optimal batch size.

Cursor implements Stream, which means it can be iterated over much in the same way that an Iterator can be in synchronous Rust. In order to do so, the StreamExt trait must be imported. Because a Cursor iterates over a Result<T>, it also has access to the potentially more ergonomic functionality provided by TryStreamExt, which can be imported instead of or in addition to StreamExt. The methods from TryStreamExt are especially useful when used in conjunction with the ? operator.

use futures::stream::{StreamExt, TryStreamExt};

let mut cursor = coll.find(None, None).await?;
// regular Stream uses next() and iterates over Option<Result<T>>
while let Some(doc) = cursor.next().await {
  println!("{}", doc?)
}
// regular Stream uses collect() and collects into a Vec<Result<T>>
let v: Vec<Result<_>> = cursor.collect().await;

let mut cursor = coll.find(None, None).await?;
// TryStream uses try_next() and iterates over Result<Option<T>>
while let Some(doc) = cursor.try_next().await? {
  println!("{}", doc)
}
// TryStream uses try_collect() and collects into a Result<Vec<T>>
let v: Vec<_> = cursor.try_collect().await?;

If a Cursor is still open when it goes out of scope, it will automatically be closed via an asynchronous killCursors command executed from its Drop implementation.

Implementations

impl<T> Cursor<T>

pub async fn advance(&mut self) -> Result<bool>

Move the cursor forward, potentially triggering requests to the database for more results if the local buffer has been exhausted.

This will keep requesting data from the server until either the cursor is exhausted or batch with results in it has been received.

The return value indicates whether new results were successfully returned (true) or if the cursor has been closed (false).

Note: Cursor::current and Cursor::deserialize_current must only be called after Cursor::advance returned Ok(true). It is an error to call either of them without calling Cursor::advance first or after Cursor::advance returns an error / false.

let mut cursor = coll.find(None, None).await?;
while cursor.advance().await? {
    println!("{:?}", cursor.current());
}

pub fn current(&self) -> &RawDocument

Returns a reference to the current result in the cursor.

Panics

Cursor::advance must return Ok(true) before Cursor::current can be invoked. Calling Cursor::current after Cursor::advance does not return true or without calling Cursor::advance at all may result in a panic.

let mut cursor = coll.find(None, None).await?;
while cursor.advance().await? {
    println!("{:?}", cursor.current());
}

pub fn deserialize_current<'a>(&'a self) -> Result<T>

where T: Deserialize<'a>,

Deserialize the current result to the generic type associated with this cursor.

Panics

Cursor::advance must return Ok(true) before Cursor::deserialize_current can be invoked. Calling Cursor::deserialize_current after Cursor::advance does not return true or without calling Cursor::advance at all may result in a panic.

use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Cat<'a> {
    #[serde(borrow)]
    name: &'a str
}

let coll = db.collection::<Cat>("cat");
let mut cursor = coll.find(None, None).await?;
while cursor.advance().await? {
    println!("{:?}", cursor.deserialize_current()?);
}

pub fn with_type<'a, D>(self) -> Cursor<D>

where D: Deserialize<'a>,

Update the type streamed values will be parsed as.

Trait Implementations

impl<T: Debug> Debug for Cursor<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for Cursor<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Stream for Cursor<T>

where T: DeserializeOwned,

type Item = Result<T, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.