Struct ejdb::Collection

pub struct Collection<'db> { /* fields omitted */ }

A handle to an EJDB collection.

This structure is connected via a lifetime to the corresponding database object, so it is not possible for collections to outlive their database.

Most of the work with EJDB databases goes through this structure. This includes the following operations:

• Executing queries.
• Creating transactions.
• Saving and loading objects by their identifier.

Dropping and creating collections is performed through Database object.

Collection instances can be created with Database::get_collection(), Database::collection(), Database::collection_with_options() or CollectionOptions::get_or_create() methods.

Methods

impl<'db> Collection<'db>

pub fn index<S: Into<String>>(&self, key: S) -> Index

Returns an index builder for the provided field in this collection.

The index builder may be used to create, modify or delete various indices on collection fields. A field may have more than one index of different types. This may be useful if this field is heterogeneous, i.e. if it may hold different types of data.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();

// create a case sensitive string index on "name" field in this collection
coll.index("name").string(true).set().unwrap();

See builder methods for more examples.

impl<'db> Collection<'db>

pub fn begin_transaction(&self) -> Result<Transaction>

Starts a transaction, returning a guard object for it.

This method can be used to start transactions over an EJDB collection. Transactions are controlled with their guard objects, which rely on the RAII pattern to abort or commit transactions when appropriate.

Failures

Returns an error if the corresponding EJDB operation can't be completed successfully.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let tx = coll.begin_transaction().unwrap();
// transaction is now active until `tx` goes out of scope or otherwise consumed

pub fn transaction_active(&self) -> Result<bool>

Checks whether there is an active transaction on this collection.

Failures

Returns an error if the corresponding EJDB operation can't be completed successfully.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let tx = coll.begin_transaction().unwrap();
assert!(coll.transaction_active().unwrap());

impl<'db> Collection<'db>

pub fn name(&self) -> &str

Returns the name of the collection.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
assert_eq!("some_collection", coll.name());

pub fn save<D: Borrow<Document>>(&self, doc: D) -> Result<ObjectId>

Saves the given BSON document to this collection, assigning it a fresh id, if needed.

This is a convenient way to store a single object into the database. If the document contains an _id field of type bson::oid::ObjectId, then it will be used as an identifier for the new record; otherwise, a fresh identifier is generated. The actual identifier of the record, be it the provided one or the generated one, is returned if this call completed successfully.

If a document with such id is already present in the collection, it will be replaced with the provided one entirely.

Failures

Returns an error if the provided document can't be converted to the EJDB one or if some error occurs which prevents the corresponding EJDB operation from successful completion.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
coll.save(bson! {
    "name" => "FooBar",
    "count" => 12345
}).unwrap();

pub fn load(&self, id: &ObjectId) -> Result<Option<Document>>

Attempts to load a BSON document from this collection by its id.

This is a convenient way to find a single object by its identifier without resorting to queries. If the object with the specified id is present in the collection, returns it, otherwise returns None.

Failures

Returns an error if there are problems in converting the document from EJDB BSON representation or if the corresponding EJDB operation can't be completed successfully.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let value = coll.load(&ObjectId::with_string("1234567890abcdef0987feab").unwrap()).unwrap();
// value is ejdb::bson::Document

pub fn save_all<I>(&self, docs: I) -> Result<Vec<ObjectId>> where
    I: IntoIterator,
    I::Item: Borrow<Document>, 

Saves all BSON documents in the provided iterable to this collection.

Every BSON document from the provided iterable will be saved to this collection as if they all have been passed one by one to Collection::save(). Returns a vector of identifiers of each created record. Any BSON document may contain an _id field of bson::oid::ObjectId type, it will then be used as a record id; otherwise, a fresh identifier will be generated.

Failures

Returns an error if saving of any of the provided documents has failed. As documents are processed one by one, none of the documents after the failed one will be saved. The error will contain a vector of identifiers of documents which has been saved successfully.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
coll.save_all(&[
    bson!{ "name" => "Foo", "count" => 123 },
    bson!{ "name" => "Bar", "items" => [4, 5, 6] }
]).unwrap();

pub fn query<Q, H>(&self, query: Q, hints: H) -> PreparedQuery<Q, H> where
    Q: Borrow<Query>,
    H: Borrow<QueryHints>, 

Prepares the provided query for execution.

This method accepts a query object and returns a prepared query object which can then be used to execute the query in various ways.

The query argument may be of any type which can be borrowed into a Query, which means that query::Query instances may be passed by value and by reference.

Examples

Using the query API:

use ejdb::query::{Q, QH};

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let query = coll.query(Q.field("name").eq("Foo"), QH.empty());
// work with the query object