Encontrar documentos

Encontre todos os documentos correspondentes

Para encontrar todos os documentos que correspondem aos seus critérios, use o método find() . Este método utiliza um filtro de query como parâmetro. Um filtro de query consiste nos campos e valores que formam critérios para a correspondência de documentos.

O método retorna um tipo de Cursor que você pode iterar para recuperar quaisquer documentos que correspondam aos critérios do filtro.

Para ver um exemplo que usa esse método para recuperar dados, consulte o exemplo find().

Para saber mais sobre como especificar uma query, consulte o guia Especificar uma Consulta .

Encontrar um documento

Para encontrar o primeiro documento que corresponda aos seus critérios, use o método find_one() . Este método utiliza um filtro de query como parâmetro. Um filtro de query consiste nos campos e valores que formam critérios para a correspondência de documentos.

Se um documento corresponder aos critérios de filtro, o método retornará um tipo de Result<Option<T>> com um valor de Some. Se nenhum documento corresponder aos critérios de filtro, find_one() retornará um tipo Result<Option<T>> com um valor de None.

Para ver um exemplo que usa esse método para recuperar dados, consulte o exemplo find_one().

Modificar comportamento de localização

Você pode modificar o comportamento do método find() encadeando FindOptions métodos de construtor de opção a find() e pode modificar o comportamento do método find_one() encadeando FindOneOptions métodos de construtor de opção a find_one().

A tabela a seguir descreve os campos FindOptions e FindOneOptions comumente usados que você pode definir chamando seus métodos construtores correspondentes:

Para obter uma lista completa de configurações que você pode especificar para cada tipo, consulte a documentação da API para FindOptions e FindOneOptions.

Exemplo de encontrar()

Este exemplo executa as seguintes ações:

• Chama o método find()

• Passa um filtro de query para find() que corresponde a documentos em que o valor de unit_price é menor que 12.00 e o valor de category não é "kitchen"

• Encadeia o método sort() a find() para classificar documentos correspondentes por unit_price em ordem decrescente

let mut cursor = my_coll
    .find(doc! { "$and": vec!
    [
        doc! { "unit_price": doc! { "$lt": 12.00 } },
        doc! { "category": doc! { "$ne": "kitchen" } }
    ] })
    .sort(doc! { "unit_price": -1 })
    .await?;
while let Some(result) = cursor.try_next().await? {
    println!("{:?}", result);
}

Inventory { item: "watering can", category: "garden", unit_price: 11.99 }
Inventory { item: "candle", category: "decor", unit_price: 2.89 }

Exemplo de arquivo completo: encontrar documentos

Este exemplo recupera documentos que correspondem a um filtro de query da coleção restaurants no banco de dados sample_restaurants . O método find() retorna todos os documentos em que o valor do campo cuisine é "French".

Você pode modelar cada documento recuperado como um tipo Document ou um tipo de dados personalizado. Para especificar qual tipo de dados representa os dados da coleção, substitua o parâmetro de tipo <T> na linha realçada por um dos seguintes valores:

• <Document>: Recupera e imprime documentos de coleção como documentos BSON

• <Restaurant>: recupera e imprime documentos de coleção como instâncias da estrutura Restaurant, definida na parte superior do código

Selecione a guia Asynchronous ou Synchronous para ver o código correspondente para cada tempo de execução:

use mongodb::{ 
    bson::doc,
    Client,
    Collection
};
use futures::TryStreamExt;
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    cuisine: String,
}
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri).await?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let mut cursor = my_coll.find(
        doc! { "cuisine": "French" }
    ).await?;
    while let Some(doc) = cursor.try_next().await? {
        println!("{:#?}", doc);
    }
    Ok(())
}

use mongodb::{
    bson::doc,
    sync::{Client, Collection}
};
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    cuisine: String,
}
fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri)?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let mut cursor = my_coll.find(
        doc! { "cuisine": "French" }
    ).run()?;
    
    for result in cursor {
        println!("{:#?}", result?);
      }
    Ok(())
}

...
Some(
   Document({
      "_id": ObjectId(
            "...",
      ),
      ...
      "name": String(
            "Cafe Un Deux Trois",
      ),
      ...
   }),
),
Some(
   Document({
      "_id": ObjectId(
            "...",
      ),
      ...
      "name": String(
            "Calliope",
      ),
      ...
   }),
)
...

...
Restaurant {
   name: "Cafe Un Deux Trois",
   cuisine: "French",
}
Restaurant {
   name: "Calliope",
   cuisine: "French",
}
...

Exemplo de carregar uma query de um arquivo

Você pode armazenar um filtro de queries em um arquivo JSON e carregá-lo no tempo de execução. Essa abordagem permite compartilhar definições de query entre o aplicativo Rust e ferramentas externas, como o MongoDB Shell (mongosh).

cargo add serde_json

Primeiro, crie um arquivo JSON que contenha seu filtro de queries. O seguinte arquivo de amostra query.json contém um filtro de queries de comparação que corresponde a documentos nos quais o valor de campo category é "kitchen":

{ "category": "kitchen" }

Para carregar esse arquivo em seu aplicativo Rust, leia o arquivo usando o método std::fs::read_to_string(). Em seguida, chamar serde_json::from_str() para analisar a string JSON em uma instância do Document. Como o Document implementa a traça serde::Deserialize, você pode desserializá-lo diretamente de uma string JSON.

O exemplo a seguir lê um filtro de queries do arquivo query.json e o passa para o método find():

let json = std::fs::read_to_string("query.json")
    .expect("failed to read query.json");
let filter: Document = serde_json::from_str(&json)
    .expect("query.json contains invalid JSON");
let mut cursor = my_coll.find(filter).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Inventory { item: "blender", category: "kitchen", unit_price: 38.49 }
Inventory { item: "placemat", category: "kitchen", unit_price: 3.19 }

Exemplo de find_one()

Este exemplo executa as seguintes ações:

• Chama o método find_one()

• Passa um filtro de query para find_one() que corresponde a documentos em que o valor de unit_price é menor ou igual a 20.00

• Encadeia o método skip() para find_one() para ignorar os dois primeiros documentos correspondentes

let result = my_coll
    .find_one(doc! { "unit_price": doc! { "$lte": 20.00 } })
    .skip(2)
    .await?;
println!("{:#?}", result);

Some(
    Inventory {
        item: "watering can",
        category: "garden",
        unit_price: 11.99,
    },
)

Exemplo de arquivo completo: encontrar um documento

Este exemplo recupera um documento que corresponde a um filtro de query da coleção restaurants no banco de dados sample_restaurants. O método find_one() retorna o primeiro documento no qual o valor do campo name é "Tompkins Square Bagels".

Você pode modelar o documento recuperado como um tipo Document ou um tipo de dados personalizado. Para especificar qual tipo de dados representa os dados da coleção, substitua o parâmetro de tipo <T> na linha realçada por um dos seguintes valores:

• <Document>: Recupera e imprime documentos de coleção como documentos BSON

• <Restaurant>: recupera e imprime documentos de coleção como instâncias da estrutura Restaurant, definida na parte superior do código

Selecione a guia Asynchronous ou Synchronous para ver o código correspondente para cada tempo de execução:

use mongodb::{ 
    bson::doc,
    Client,
    Collection
};
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    cuisine: String,
}
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri).await?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let result = my_coll.find_one(
        doc! { "name": "Tompkins Square Bagels" }
    ).await?;
    println!("{:#?}", result);
    Ok(())
}

use mongodb::{
    bson::doc,
    sync::{Client, Collection}
};
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    cuisine: String,
}
fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri)?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let result = my_coll.find_one(
        doc! { "name": "Tompkins Square Bagels" }
    ).run()?;
    println!("{:#?}", result);
    Ok(())
}

Some(
   Document({
      "_id": ObjectId(
            "...",
      ),
      ...
      "name": String(
            "Tompkins Square Bagels",
      ),
      ...
   }),
)

Some(
   Restaurant {
      name: "Tompkins Square Bagels",
      cuisine: "American",
   },
)

Dados agregados do documento

O método aggregate() usa um aggregation pipeline como parâmetro. Um pipeline de agregação inclui um ou mais estágios que especificam como transformar dados. Um estágio inclui um operador de agregação (prefixado com um $) e quaisquer parâmetros exigidos para este operador.

Para saber mais sobre agregações e ver exemplos de agregação, consulte o Guia de agregação .

O método retorna os documentos resultantes em um tipo Cursor . Se o pipeline de agregação não contiver um estágio $match , o pipeline processará todos os documentos na coleção.

Modificar comportamento de agregação

Você pode modificar o comportamento do método aggregate() encadeando os métodos de construtor de opção AggregateOptions para aggregate().

A tabela a seguir descreve os campos AggregateOptions comumente usados que você pode definir chamando seus métodos construtores correspondentes:

Para obter uma lista completa das configurações, consulte a documentação da API para AggregateOptions.

Exemplo

Este exemplo mostra como chamar o método aggregate() com um pipeline que contém os seguintes estágios:

• $group estágio para calcular a média do campo unit_price para cada valor do campo category

• $sort estágio para ordenar resultados por avg_price em ordem crescente

let pipeline = vec![
    doc! { "$group": doc! { "_id" : doc! {"category": "$category"} ,
    "avg_price" : doc! { "$avg" : "$unit_price" } } },
    doc! { "$sort": { "_id.avg_price" : 1 } },
];
let mut cursor = my_coll.aggregate(pipeline).await?;
while let Some(result) = cursor.try_next().await? {
    println!("{:?}", result);
}

Document({"_id": Document({"category": String("decor")}), "avg_price": Double(2.890000104904175)})
Document({"_id": Document({"category": String("kitchen")}), "avg_price": Double(20.840000867843628)})
Document({"_id": Document({"category": String("garden")}), "avg_price": Double(11.989999771118164)})

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

• find_one()

• find()

• Encontre opções

• FindOneOptions

• Cursor

• Aggregate()

• AggregateOptions