Acessar dados usando um cursor

Visão geral

Neste guia, você aprenderá a usar o driver Rust para acessar os dados retornados de uma operação de leitura ou agregação usando um cursor . Um cursor é um mecanismo que permite iterar vários documentos enquanto mantém apenas um subconjunto deles na memória em determinado momento.

O driver oferece o tipo Cursor para recuperar documentos de um cursor. Por exemplo, quando você executa uma operação de busca que pode retornar vários documentos, o driver retorna uma instância do Cursor da qual você pode acessar os documentos correspondentes.

Após executar uma operação de leitura ou agregação, a instância do Cursor retornada contém o primeiro lote de resultados da operação. À medida que você itera pelo cursor, o servidor retorna mais resultados individuais. Se houver mais documentos correspondentes depois que você chegar ao final de um lote de resultados, a instância Cursor buscará o próximo lote de documentos até que todos os resultados sejam retornados.

Este guia inclui as seguintes seções:

• Amostra de dados para exemplos apresenta os dados de amostra que são usados pelos exemplos do cursor

• Recuperar documentos Descreve individualmente como usar a iteração ou um fluxo para acessar os resultados um de cada vez

• Recuperar documentos como array descreve como acessar todos os resultados como um único array coletando os resultados do cursor retornado

• recuperar lotes de documentos brutos descreve como usar a API do cursor de lote bruto para em processamento de documento cópia zero e acesso direto aos dados BSON

• Especificar o Comportamento do Cursor descreve como configurar o cursor que um método retorna

• Informações adicionais fornecem links para recursos e documentação da API para os tipos e métodos mencionados neste guia

Dados de amostra para exemplos

Os exemplos deste guia usam os seguintes dados armazenados em uma estrutura:

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

O driver fornece os seguintes padrões de acesso para iterar por meio de documentos retornados por uma instância Cursor :

• Padrão integrado: avance o cursor, depois recupere e desserialize o documento atual

• Padrão de implementação de fluxo: iterar sobre o cursor e chamar os métodos fornecidos pelo Stream para processar um ou vários documentos

As seções a seguir descrevem esses padrões de acesso e métodos correspondentes em mais detalhes.

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 um array

Como o tipo Cursor implementa a Stream , você pode coletar os resultados de um cursor em uma array.

Você pode usar os seguintes métodos para recuperar documentos como um array:

• collect(): coleta resultados de um cursor em um tipo Vec<Result<T>>

• try_collect(): coleta resultados de um cursor em um 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 o cursor de lote bruto

Você pode chamar o método batch() em operações de retorno de cursor, como find() para retornar um RawBatchCursor. Isso permite que você itere sobre lotes de documento BSON brutos retornados pelo servidor em vez de valores desserializados individuais. Este módulo oferece uma maneira de alto desempenho de processar documentos quando você precisa de acesso direto aos lotes de resposta do servidor . Use o modo de lote bruto para aplicativos de cursor sensíveis ao desempenho com alta taxa de transferência.

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 comportamento do cursor

Para modificar o cursor que uma operação retorna, encadeie os métodos do construtor de opções ao método que retorna a instância Cursor . Por exemplo, é possível encadear métodos de construtor de opção relacionados ao cursor ao método find() .

A tabela a seguir descreve as opções relacionadas ao cursor que você pode definir chamando o método de construtor correspondente:

O código a seguir mostra como especificar configurações relacionadas ao cursor encadeando métodos de construtor de opção ao método find() :

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

Informações adicionais

Para saber mais sobre as operações neste guia, consulte a seguinte documentação:

• Guia para encontrar documentos

• Especificar uma guia de query

Para saber mais sobre a conversão entre tipos de Rust e BSON, consulte o guia sobre modelagem de dados e serialização.