Struct qm_mongodb::SessionCursor

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

A SessionCursor is a cursor that was created with a ClientSession that must be iterated using one. To iterate, use SessionCursor::next or retrieve a SessionCursorStream using SessionCursor::stream:

// iterate using next()
let mut cursor = coll.find(doc! {}).session(&mut session).await?;
while let Some(doc) = cursor.next(&mut session).await.transpose()? {
    println!("{}", doc)
}

// iterate using `Stream`:
use futures::stream::TryStreamExt;

let mut cursor = coll.find(doc! {}).session(&mut session).await?;
let results: Vec<_> = cursor.stream(&mut session).try_collect().await?;

If a SessionCursor 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> SessionCursor<T>

where T: DeserializeOwned,

pub fn stream<'session>( &mut self, session: &'session mut ClientSession, ) -> SessionCursorStream<'_, 'session, T>

Retrieves a SessionCursorStream to iterate this cursor. The session provided must be the same session used to create the cursor.

Note that the borrow checker will not allow the session to be reused in between iterations of this stream. In order to do that, either use SessionCursor::next instead or drop the stream before using the session.

use futures::stream::TryStreamExt;

// iterate over the results
let mut cursor = coll.find(doc! { "x": 1 }).session(&mut session).await?;
while let Some(doc) = cursor.stream(&mut session).try_next().await? {
    println!("{}", doc);
}

// collect the results
let mut cursor1 = coll.find(doc! { "x": 1 }).session(&mut session).await?;
let v: Vec<Document> = cursor1.stream(&mut session).try_collect().await?;

// use session between iterations
let mut cursor2 = coll.find(doc! { "x": 1 }).session(&mut session).await?;
loop {
    let doc = match cursor2.stream(&mut session).try_next().await? {
        Some(d) => d,
        None => break,
    };
    other_coll.insert_one(doc).session(&mut session).await?;
}

pub async fn next( &mut self, session: &mut ClientSession, ) -> Option<Result<T, Error>>

Retrieve the next result from the cursor. The session provided must be the same session used to create the cursor.

Use this method when the session needs to be used again between iterations or when the added functionality of Stream is not needed.

let mut cursor = coll.find(doc! { "x": 1 }).session(&mut session).await?;
while let Some(doc) = cursor.next(&mut session).await.transpose()? {
    other_coll.insert_one(doc).session(&mut session).await?;
}

impl<T> SessionCursor<T>

pub async fn advance( &mut self, session: &mut ClientSession, ) -> Result<bool, Error>

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: SessionCursor::current and SessionCursor::deserialize_current must only be called after SessionCursor::advance returned Ok(true). It is an error to call either of them without calling SessionCursor::advance first or after SessionCursor::advance returns an error / false.

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

pub fn current(&self) -> &RawDocument

Returns a reference to the current result in the cursor.

Panics

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

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

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

where T: Deserialize<'a>,

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

Panics

SessionCursor::advance must return Ok(true) before SessionCursor::deserialize_current can be invoked. Calling SessionCursor::deserialize_current after SessionCursor::advance does not return true or without calling SessionCursor::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(doc! {}).session(&mut session).await?;
while cursor.advance(&mut session).await? {
    println!("{:?}", cursor.deserialize_current()?);
}

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

where D: Deserialize<'a>,

Update the type streamed values will be parsed as.

Trait Implementations

impl<T> Debug for SessionCursor<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Drop for SessionCursor<T>

fn drop(&mut self)

Executes the destructor for this type.