Struct Repository

pub struct Repository<M: Model> { /* private fields */ }

Associate a mongodb::Collection and a specific Model.

This type can safely be copied and passed around because std::sync::Arc is used internally. Underlying mongodb::Collection can be retrieved at anytime with Repository::get_underlying.

Implementations

impl<M: Model> Repository<M>

pub fn new(db: Database) -> Self

Create a new repository from the given mongo client.

pub fn new_with_options(db: Database, options: CollectionOptions) -> Self

Create a new repository with associated collection options (override Model::coll_options).

pub fn collection_name(&self) -> &'static str

Returns associated M::collection_name.

pub fn get_underlying(&self) -> Collection<M>

Returns underlying mongodb::Collection.

pub fn cast_model<OtherModel>(self) -> Repository<OtherModel>

where OtherModel: Model<CollConf = M::CollConf>,

Convert this repository to use another Model. Only compiles if both Model::CollConf are identicals.

Example

use mongodm::{ToRepository, Model, CollectionConfig};
use mongodm::mongo::bson::doc;
use mongodm::f;
use serde::{Serialize, Deserialize};

struct UserCollConf;

impl CollectionConfig for UserCollConf {
    fn collection_name() -> &'static str {
        "cast_model"
    }
}

// Latest schema currently in use
#[derive(Serialize, Deserialize)]
struct User {
    username: String,
    last_seen: i64,
}

impl Model for User {
    type CollConf = UserCollConf;
}

// Old schema
#[derive(Serialize, Deserialize)]
struct UserV1 {
    name: String,
    ls: i64,
}

// Versionned version of our `User`
#[derive(Serialize, Deserialize)]
#[serde(untagged)]
enum UserVersionned {
    Last(User),
    V1(UserV1),
}

impl Model for UserVersionned {
    type CollConf = UserCollConf; // same as the non-versionned version
}

// We have some repository for `User`
let repo = db.repository::<User>();

// Assume the following document is stored: { "name": "Bernard", "ls": 1500 }

// Following query should fails because the schema doesn't match
let err = repo.find_one(doc!{ f!(name in UserV1): "Bernard" }, None).await.err().unwrap();
assert_eq!(err.to_string(), "missing field `username`"); // serde deserialization error

// We can get a repository for `UserVersionned` from our `Repository<User>`
// because `User::CollConf` == `UserVersionned::CollConf`
let repo_versionned = repo.cast_model::<UserVersionned>();

// Our versionned model should match with the document
let ret = repo_versionned.find_one(doc!{ f!(name in UserV1): "Bernard" }, None).await?;
match ret {
    Some(UserVersionned::V1(UserV1 { name, ls: 1500 })) if name == "Bernard" => { /* success */ }
    _ => panic!("Expected document was missing"),
}

Following code will fail to compile because CollectionConfig doesn’t match.

use mongodm::{ToRepository, Model, CollectionConfig};
use serde::{Serialize, Deserialize};

struct ACollConf;

impl CollectionConfig for ACollConf {
    fn collection_name() -> &'static str { "a" }
}

#[derive(Serialize, Deserialize)]
struct A;

impl Model for A {
    type CollConf = ACollConf;
}

struct BCollConf;

impl CollectionConfig for BCollConf {
    fn collection_name() -> &'static str { "B" }
}

#[derive(Serialize, Deserialize)]
struct B;

impl Model for B {
    type CollConf = BCollConf;
}

// Doesn't compile because `A` and `B` doesn't share the same `CollectionConfig`.
db.repository::<A>().cast_model::<B>();

pub async fn bulk_update<V, U>(&self, updates: V) -> Result<BulkUpdateResult>

where V: Borrow<Vec<U>> + Send + Sync, U: Borrow<BulkUpdate> + Send + Sync,

Apply multiple update operations in bulk.

This will be removed once support for bulk update is added to the official driver. see for tracking progress on this feature in the official driver.

Example

use mongodm::prelude::*;
/* ... */
let db: mongodb::Database; /* exists */
let repository = db.repository::<User>();
/* ... */
let bulk_update_res = repository
    .bulk_update(&vec![
        &BulkUpdate {
            query: doc! { f!(name in User): "Dane" },
            update: doc! { Set: { f!(age in User): 12 } },
            options: None,
        },
        &BulkUpdate {
            query: doc! { f!(name in User): "David" },
            update: doc! { Set: { f!(age in User): 30 } },
            options: None,
        },
    ])
    .await
    .unwrap();
assert_eq!(bulk_update_res.nb_affected, 2);
assert_eq!(bulk_update_res.nb_modified, 2);

Methods from Deref<Target = Collection<M>>

pub fn aggregate( &self, pipeline: impl IntoIterator<Item = Document>, ) -> Aggregate<'_>

Runs an aggregation operation.

See the documentation here for more information on aggregations.

await will return Result<Cursor<Document>>. If a ClientSession was provided, the returned cursor will be a SessionCursor. If with_type was called, the returned cursor will be generic over the T specified.

These methods can be chained before .await to set options:

• with_type
• with_options
• allow_disk_use
• batch_size
• bypass_document_validation
• collation
• comment
• hint
• max_await_time
• max_time
• read_concern
• selection_criteria
• write_concern
• let_vars
• session

pub fn estimated_document_count(&self) -> EstimatedDocumentCount<'_>

Estimates the number of documents in the collection using collection metadata.

Due to an oversight in versions 5.0.0 - 5.0.7 of MongoDB, the count server command, which estimatedDocumentCount uses in its implementation, was not included in v1 of the Stable API. Users of the Stable API with estimatedDocumentCount are recommended to upgrade their cluster to 5.0.8+ or set ServerApi::strict to false to avoid encountering errors.

For more information on the behavior of the count server command, see Count: Behavior.

await will return Result<u64>.

These methods can be chained before .await to set options:

• with_options
• max_time
• selection_criteria
• read_concern
• comment

pub fn count_documents(&self, filter: Document) -> CountDocuments<'_>

Gets the number of documents.

Note that this method returns an accurate count.

await will return Result<u64>.

These methods can be chained before .await to set options:

• session
• with_options
• hint
• limit
• max_time
• skip
• collation
• selection_criteria
• read_concern
• comment

pub fn create_index(&self, index: IndexModel) -> CreateIndex<'_>

Creates the given index on this collection.

await will return Result<CreateIndexResult>.

These methods can be chained before .await to set options:

• session
• with_options
• commit_quorum
• max_time
• write_concern
• comment

pub fn create_indexes( &self, indexes: impl IntoIterator<Item = IndexModel>, ) -> CreateIndex<'_, Multiple>

Creates the given indexes on this collection.

await will return Result<CreateIndexesResult>.

These methods can be chained before .await to set options:

• session
• with_options
• commit_quorum
• max_time
• write_concern
• comment

pub fn delete_one(&self, query: Document) -> Delete<'_>

Deletes up to one document found matching query.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<DeleteResult>.

These methods can be chained before .await to set options:

• session
• with_options
• collation
• write_concern
• hint
• let_vars
• comment

pub fn delete_many(&self, query: Document) -> Delete<'_>

Deletes all documents stored in the collection matching query.

await will return Result<DeleteResult>.

These methods can be chained before .await to set options:

• session
• with_options
• collation
• write_concern
• hint
• let_vars
• comment

pub fn distinct( &self, field_name: impl AsRef<str>, filter: Document, ) -> Distinct<'_>

Finds the distinct values of the field specified by field_name across the collection.

await will return Result<Vec<Bson>>.

These methods can be chained before .await to set options:

• session
• with_options
• max_time
• selection_criteria
• read_concern
• collation
• comment

pub fn drop(&self) -> DropCollection<'_>

Drops the collection, deleting all data and indexes stored in it.

await will return Result<()>.

These methods can be chained before .await to set options:

• session
• with_options
• write_concern
• encrypted_fields

pub fn drop_index(&self, name: impl AsRef<str>) -> DropIndex<'_>

Drops the index specified by name from this collection.

await will return Result<()>.

These methods can be chained before .await to set options:

• session
• with_options
• max_time
• write_concern
• comment

pub fn drop_indexes(&self) -> DropIndex<'_>

Drops all indexes associated with this collection.

await will return Result<()>.

These methods can be chained before .await to set options:

• session
• with_options
• max_time
• write_concern
• comment

pub fn find(&self, filter: Document) -> Find<'_, T>

Finds the documents in the collection matching filter.

await will return Result<Cursor<T>> (or Result<SessionCursor<T>> if a session is provided).

These methods can be chained before .await to set options:

• session
• with_options
• allow_disk_use
• allow_partial_results
• batch_size
• comment
• cursor_type
• hint
• limit
• max
• max_await_time
• max_scan
• max_time
• min
• no_cursor_timeout
• projection
• read_concern
• return_key
• selection_criteria
• show_record_id
• skip
• sort
• collation
• let_vars

pub fn find_one(&self, filter: Document) -> FindOne<'_, T>

Finds a single document in the collection matching filter.

await will return Result<Option<T>>.

These methods can be chained before .await to set options:

• session
• with_options
• allow_partial_results
• collation
• comment
• hint
• max
• max_scan
• max_time
• min
• projection
• read_concern
• return_key
• selection_criteria
• show_record_id
• skip
• sort
• let_vars

pub fn find_one_and_delete(&self, filter: Document) -> FindOneAndDelete<'_, T>

Atomically finds up to one document in the collection matching filter and deletes it.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<Option<T>>.

These methods can be chained before .await to set options:

• session
• with_options
• max_time
• projection
• sort
• write_concern
• collation
• hint
• let_vars
• comment

pub fn find_one_and_update( &self, filter: Document, update: impl Into<UpdateModifications>, ) -> FindOneAndUpdate<'_, T>

Atomically finds up to one document in the collection matching filter and updates it. Both Document and Vec<Document> implement Into<UpdateModifications>, so either can be passed in place of constructing the enum case. Note: pipeline updates are only supported in MongoDB 4.2+.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<Option<T>>.

These methods can be chained before .await to set options:

• session
• with_options
• array_filters
• bypass_document_validation
• max_time
• projection
• return_document
• sort
• upsert
• write_concern
• collation
• hint
• let_vars
• comment

pub fn find_one_and_replace( &self, filter: Document, replacement: impl Borrow<T>, ) -> FindOneAndReplace<'_, T>

Atomically finds up to one document in the collection matching filter and replaces it with replacement.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<Option<T>>.

These methods can be chained before .await to set options:

• session
• with_options
• bypass_document_validation
• max_time
• projection
• return_document
• sort
• upsert
• write_concern
• collation
• hint
• let_vars
• comment

pub fn insert_many( &self, docs: impl IntoIterator<Item = impl Borrow<T>>, ) -> InsertMany<'_>

Inserts the data in docs into the collection.

Note that this method accepts both owned and borrowed values, so the input documents do not need to be cloned in order to be passed in.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<InsertManyResult>.

These methods can be chained before .await to set options:

• session
• with_options
• bypass_document_validation
• ordered
• write_concern
• comment

pub fn insert_one(&self, doc: impl Borrow<T>) -> InsertOne<'_>

Inserts doc into the collection.

Note that either an owned or borrowed value can be inserted here, so the input document does not need to be cloned to be passed in.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<InsertOneResult>.

These methods can be chained before .await to set options:

• session
• with_options
• bypass_document_validation
• write_concern
• comment

pub fn list_indexes(&self) -> ListIndexes<'_>

Lists all indexes on this collection.

await will return Result<Cursor<IndexModel>> (or Result<SessionCursor<IndexModel>> if a ClientSession is provided).

These methods can be chained before .await to set options:

• with_options
• max_time
• batch_size
• comment
• session

pub fn list_index_names(&self) -> ListIndexes<'_, ListNames>

Gets the names of all indexes on the collection.

await will return Result<Vec<String>>.

These methods can be chained before .await to set options:

• with_options
• max_time
• batch_size
• comment
• session

pub fn replace_one( &self, query: Document, replacement: impl Borrow<T>, ) -> ReplaceOne<'_>

Replaces up to one document matching query in the collection with replacement.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<UpdateResult>.

These methods can be chained before .await to set options:

• session
• with_options
• bypass_document_validation
• upsert
• collation
• hint
• write_concern
• let_vars
• comment
• sort

pub fn create_search_indexes( &self, models: impl IntoIterator<Item = SearchIndexModel>, ) -> CreateSearchIndex<'_, Multiple>

Creates multiple search indexes on the collection.

await will return Result<Vec<String>>.

These methods can be chained before .await to set options:

• with_options

pub fn create_search_index( &self, model: SearchIndexModel, ) -> CreateSearchIndex<'_, Single>

Convenience method for creating a single search index.

await will return Result<String>.

These methods can be chained before .await to set options:

• with_options

pub fn update_search_index( &self, name: impl Into<String>, definition: Document, ) -> UpdateSearchIndex<'_>

Updates the search index with the given name to use the provided definition.

await will return [Result<()>].

These methods can be chained before .await to set options:

• with_options

pub fn drop_search_index(&self, name: impl Into<String>) -> DropSearchIndex<'_>

Drops the search index with the given name.

await will return [Result<()>].

These methods can be chained before .await to set options:

• with_options

pub fn list_search_indexes(&self) -> ListSearchIndexes<'_>

Gets index information for one or more search indexes in the collection.

If name is not specified, information for all indexes on the specified collection will be returned.

await will return Result<Cursor<Document>>.

These methods can be chained before .await to set options:

• name
• aggregate_options
• with_options

pub fn update_many( &self, query: Document, update: impl Into<UpdateModifications>, ) -> Update<'_>

Updates all documents matching query in the collection.

Both Document and Vec<Document> implement Into<UpdateModifications>, so either can be passed in place of constructing the enum case. Note: pipeline updates are only supported in MongoDB 4.2+. See the official MongoDB documentation for more information on specifying updates.

await will return Result<UpdateResult>.

These methods can be chained before .await to set options:

• session
• with_options
• array_filters
• bypass_document_validation
• upsert
• collation
• hint
• write_concern
• let_vars
• comment
• sort

pub fn update_one( &self, query: Document, update: impl Into<UpdateModifications>, ) -> Update<'_>

Updates up to one document matching query in the collection.

Both Document and Vec<Document> implement Into<UpdateModifications>, so either can be passed in place of constructing the enum case. Note: pipeline updates are only supported in MongoDB 4.2+. See the official MongoDB documentation for more information on specifying updates.

This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.

await will return Result<UpdateResult>.

These methods can be chained before .await to set options:

• session
• with_options
• array_filters
• bypass_document_validation
• upsert
• collation
• hint
• write_concern
• let_vars
• comment
• sort

pub fn watch(&self) -> Watch<'_, T>

Starts a new ChangeStream that receives events for all changes in this collection. A ChangeStream cannot be started on system collections.

See the documentation here on change streams.

Change streams require either a “majority” read concern or no read concern. Anything else will cause a server error.

await will return Result<ChangeStream<ChangeStreamEvent<T>>> or Result<SessionChangeStream<ChangeStreamEvent<T>>> if a ClientSession has been provided.

These methods can be chained before .await to set options:

• pipeline
• resume_after
• with_options
• full_document
• full_document_before_change
• start_at_operation_time
• start_after
• max_await_time
• batch_size
• collation
• read_concern
• selection_criteria
• show_expanded_events
• comment
• session

pub fn insert_one_model( &self, document: impl Borrow<T>, ) -> Result<InsertOneModel, Error>

Constructs an InsertOneModel with this collection’s namespace by serializing the provided value into a Document. Returns an error if serialization fails.

Note that the returned value must be provided to bulk_write for the insert to be performed.

pub fn replace_one_model( &self, filter: Document, replacement: impl Borrow<T>, ) -> Result<ReplaceOneModel, Error>

Constructs a ReplaceOneModel with this collection’s namespace by serializing the provided value into a Document. Returns an error if serialization fails.

Note that the returned value must be provided to bulk_write for the replace to be performed.

pub fn clone_with_type<U>(&self) -> Collection<U>

where U: Send + Sync,

Gets a clone of the Collection with a different type U.

pub fn client(&self) -> &Client

Get the Client that this collection descended from.

pub fn name(&self) -> &str

Gets the name of the Collection.

pub fn namespace(&self) -> Namespace

Gets the namespace of the Collection.

The namespace of a MongoDB collection is the concatenation of the name of the database containing it, the ‘.’ character, and the name of the collection itself. For example, if a collection named “bar” is created in a database named “foo”, the namespace of the collection is “foo.bar”.

pub fn selection_criteria(&self) -> Option<&SelectionCriteria>

Gets the selection criteria of the Collection.

pub fn read_concern(&self) -> Option<&ReadConcern>

Gets the read concern of the Collection.

pub fn write_concern(&self) -> Option<&WriteConcern>

Gets the write concern of the Collection.

Trait Implementations

impl<M: Model> Clone for Repository<M>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: Debug + Model> Debug for Repository<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M: Model> Deref for Repository<M>

type Target = Collection<M>

The resulting type after dereferencing.

fn deref(&self) -> &Collection<M>

Dereferences the value.