Retrieve Data

Find All Matching Documents

To find all the documents that match your criteria, use the find() method. This method takes a query filter as a parameter. A query filter consists of the fields and values that form criteria for documents to match.

The method returns a Cursor type that you can iterate through to retrieve any documents that match the filter criteria.

To see an example that uses this method to retrieve data, see the find() example.

To learn more about specifying a query, see the Specify a Query guide.

Find One Document

To find the first document that matches your criteria, use the find_one() method. This method takes a query filter as a parameter. A query filter consists of the fields and values that form criteria for documents to match.

If a document matches the filter criteria, the method returns a Result<Option<T>> type with a value of Some. If no documents match the filter criteria, find_one() returns a Result<Option<T>> type with a value of None.

To see an example that uses this method to retrieve data, see the find_one() example.

Modify Find Behavior

You can modify the behavior of the find() method by chaining FindOptions option builder methods to find(), and you can modify the behavior of the find_one() method by chaining FindOneOptions option builder methods to find_one().

The following table describes commonly used FindOptions and FindOneOptions fields that you can set by calling their corresponding builder methods:

For a full list of settings you can specify for each type, see the API documentation for FindOptions and FindOneOptions.

Examples

The following sections contain examples that use the find() and findOne() methods to retrieve sample documents that match filter criteria.

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 }

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,
    },
)

Aggregate Document Data

The aggregate() method takes an aggregation pipeline as a parameter. An aggregation pipeline includes one or more stages that specify how to transform data. A stage includes an aggregation operator (prefixed with a $) and any required parameters for that operator.

To learn more about aggregations and view aggregation examples, see the Aggregation guide.

The method returns the resulting documents in a Cursor type. If your aggregation pipeline does not contain a $match stage, the pipeline processes all the documents in the collection.

Modify Aggregation Behavior

You can modify the behavior of the aggregate() method by chaining AggregateOptions option builder methods to aggregate().

The following table describes commonly used AggregateOptions fields that you can set by calling their corresponding builder methods:

For a full list of settings, see the API documentation for AggregateOptions.

Example

This example shows how to call the aggregate() method with a pipeline that contains the following stages:

• $group stage to calculate the average of the unit_price field for each value of the category field

• $sort stage to order results by avg_price in ascending order

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

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

• find_one()

• find()

• FindOptions

• FindOneOptions

• Cursor

• aggregate()

• AggregateOptions