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

• 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" }, None).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" }, None).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" }, None).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" }, None).await?;
println!("Output from collect():");
let v: Vec<Result<Fruit>> = cursor.collect().await;
println!("{:?}", v);
println!();
let cursor = my_coll.find(doc! { "color": "yellow" }, None).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 comportamento do cursor

Para modificar o cursor que uma operação retorna, passe opções para o método que retorna a instância Cursor . Por exemplo, você pode especificar opções relacionadas ao cursor em um tipo FindOptions que você passa para o método find() .

A tabela a seguir descreve as opções relacionadas ao cursor que você pode definir em uma instância de opções:

O seguinte código mostra como construir uma instância do FindOptions e especificar as configurações relacionadas ao cursor:

let opts: FindOptions = FindOptions::builder()
    .batch_size(5)
    .cursor_type(CursorType::Tailable)
    .no_cursor_timeout(true)
    .build();

Informações adicionais

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

• Guia Recuperar dados

• 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.