Acceso a datos usando un cursor

Overview

En esta guía, puedes aprender cómo utilizar el controlador Rust para acceder a los datos devueltos de una operación de lectura o agregación mediante un cursor. Un cursor es un mecanismo que te permite iterar a través de varios documentos manteniendo solo un subconjunto de ellos en la memoria en un momento dado.

El conductor ofrece la Cursor tipo para recuperar documentos de un cursor. Por ejemplo, cuando ejecuta una operación de búsqueda que puede devolver varios documentos, el controlador retorna una instancia de Cursor desde la cual puedes acceder a los documentos coincidentes.

Después de ejecutar una operación de lectura o agregación, la instancia Cursor que se devuelve contiene el primer lote de resultados de la operación. A medida que se itera a través del cursor, el servidor devuelve más resultados individuales. Si hay más documentos coincidentes después de que llegues 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 usan los ejemplos de cursor.

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

• Recuperar documentos como un arreglo describe cómo acceder a todos los resultados como un solo arreglo recopilando los resultados del cursor devueltos

• Recuperar lotes de documentos sin procesar describe cómo usar la API del cursor de lotes sin procesar para el procesamiento de documentos sin copia con acceso directo a datos BSON

• 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 la API para los tipos y métodos mencionados en esta guía

Datos de muestra para ejemplos

Los ejemplos en 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 de Cursor:

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

• Patrón de implementación de Stream: iterar sobre el cursor y llamar 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 un arreglo

Debido a que el Cursor tipo implementa el rasgo Stream, puedes recolectar los resultados de un cursor en un arreglo.

Puedes usar los siguientes métodos para recuperar documentos como un arreglo:

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

• try_collect()recopila los 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" }]

Use el cursor de lote bruto

Puede llamar al método batch() en operaciones que devuelven cursor, como find(), para devolver un RawBatchCursor. Esto le permite iterar sobre lotes de documentos BSON sin procesar devueltos por el servidor, en lugar de valores deserializados individuales. Este módulo proporciona un método de alto rendimiento para procesar documentos cuando necesita acceso directo a los lotes de respuesta del servidor. Utilice el modo de lote sin procesar para aplicaciones de cursor sensibles al rendimiento con alto rendimiento.

let mut cursor = my_coll.find(doc! { "color": "red" }).batch().await?;
while let Some(batch) = cursor.next().await {
    let batch = batch?;
    let doc_slices = batch.doc_slices()?;
    let count = doc_slices.into_iter().count();
    println!("Processing batch with {} documents", count);
    for doc_result in batch.doc_slices()? {
        let doc = doc_result?;
        if let mongodb::bson::RawBsonRef::Document(raw_doc) = doc {
            println!("Raw document size: {} bytes", raw_doc.as_bytes().len());
        }
    }
}

Processing batch with 4 documents
Raw document size: 58 bytes
Raw document size: 59 bytes
Raw document size: 58 bytes
Raw document size: 59 bytes

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 puedes establecer llamando a su método generador correspondiente:

El siguiente código muestra cómo especificar la configuración relacionada con el cursor encadenando métodos de construcció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 query guía

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.