Acceder a los datos mediante un cursor

Overview

En esta guía, aprenderá a usar el controlador de Rust para acceder a los datos devueltos por una operación de lectura o agregación mediante un cursor. Un cursor es un mecanismo que permite iterar a través de múltiples documentos manteniendo solo un subconjunto de ellos en memoria en un momento dado.

El conductor ofrece la Cursor Tipo para recuperar documentos de un cursor. Por ejemplo, al ejecutar una operación de búsqueda que puede devolver varios documentos, el controlador devuelve una instancia Cursor desde la que se puede acceder a los documentos coincidentes.

Tras ejecutar una operación de lectura o agregación, la instancia Cursor devuelta contiene el primer lote de resultados de la operación. A medida que se itera sobre el cursor, el servidor devuelve más resultados individuales. Si hay más documentos coincidentes después de llegar al final de un lote de resultados, la instancia Cursor recupera el siguiente lote de documentos hasta que se devuelvan todos los resultados.

Esta guía incluye las siguientes secciones:

• Datos de muestra para ejemplos presenta los datos de muestra que se utilizan en los ejemplos del cursor

• Recuperar documentos individualmente describe cómo usar la iteración o un flujo para acceder a los resultados de uno en uno

• Recuperar documentos como una matriz describe cómo acceder a todos los resultados como una única matriz recopilando los resultados del cursor devueltos

• Especificar el comportamiento del cursor describe cómo configurar el cursor que un método devuelve

• Información adicional proporciona enlaces a recursos y documentación de API para los tipos y métodos mencionados en esta guía.

Datos de muestra para ejemplos

Los ejemplos de esta guía utilizan los siguientes datos almacenados en una estructura:

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() 
    }
];

Recuperar documentos individualmente

El controlador proporciona los siguientes patrones de acceso para iterar a través de los documentos devueltos por una instancia Cursor:

• Patrón incorporado: avanza el cursor, luego recupera y deserializa el documento actual

• Patrón de implementación de flujo: itera sobre el cursor y llama a los métodos proporcionados por Stream para procesar uno o varios documentos

Las siguientes secciones describen estos patrones de acceso y los métodos correspondientes con más detalle.

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" }

Recuperar documentos como una matriz

Debido a que el tipo Cursor implementa el rasgo Stream, puede recopilar los resultados de un cursor en una matriz.

Puede utilizar los siguientes métodos para recuperar documentos como una matriz:

• collect(): recopila resultados de un cursor en un tipo Vec<Result<T>>

• try_collect(): recopila resultados de un cursor en un tipo Result<Vec<T>>

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" }]

Especificar el comportamiento del cursor

Para modificar el cursor que devuelve una operación, encadene los métodos del generador de opciones al método que devuelve la instancia Cursor. Por ejemplo, puede encadenar los métodos del generador de opciones relacionados con el cursor al método find().

La siguiente tabla describe las opciones relacionadas con el cursor que puede configurar llamando a su método de generación correspondiente:

El siguiente código muestra cómo especificar configuraciones relacionadas con el cursor encadenando métodos de generación de opciones al método find():

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

Información Adicional

Para obtener más información sobre las operaciones de esta guía, consulte la siguiente documentación:

• Retrieve Data guide

• Especificar una guía de consulta

Para obtener más información sobre la conversión entre tipos de Rust y BSON, consulte la guía sobre modelado y serialización de datos.