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 find() by passing a FindOptions instance as a parameter, and you can modify the behavior of find_one() by passing a FindOneOptions instance.

To use default values for each setting, specify the value None as the options parameter.

The following table describes commonly used settings that you can specify in FindOptions and FindOneOptions:

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 opts = FindOptions::builder()
    .sort(doc! { "unit_price": -1 })
    .build();
let mut cursor = my_coll.find(
    doc! { "$and": vec!
        [
            doc! { "unit_price": doc! { "$lt": 12.00 } },
            doc! { "category": doc! { "$ne": "kitchen" } }
        ] },
    opts
).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 opts = FindOneOptions::builder().skip(2).build();
let result = my_coll.find_one(
    doc! { "unit_price":
        doc! { "$lte": 20.00 } },
    opts
).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 aggregate() by passing an AggregateOptions instance as an optional parameter.

To use default values for each setting, specify the value None as the options parameter.

The following table describes commonly used settings that you can specify in AggregateOptions:

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:

• A $group stage to group documents by the category field and calculate the average of the unit_price field by category

• A $sort stage to 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, None).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