pub struct Collection<'a, Cn, Cl> { /* private fields */ }
Expand description

Interacts with a collection over a Connection.

These examples in this type use this basic collection definition:

use bonsaidb_core::schema::Collection;
use bonsaidb_core::Error;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
pub struct MyCollection {
    pub rank: u32,
    pub score: f32,
}

Implementations§

source§

impl<'a, Cn, Cl> Collection<'a, Cn, Cl>
where Cn: Connection, Cl: Collection,

source

pub fn push( &self, item: &<Cl as SerializedCollection>::Contents ) -> Result<CollectionHeader<Cl::PrimaryKey>, Error>

Adds a new Document<Cl> with the contents item.

Automatic ID Assignment

This function calls SerializedCollection::natural_id() to try to retrieve a primary key value from item. If an id is returned, the item is inserted with that id. If an id is not returned, an id will be automatically assigned, if possible, by the storage backend, which uses the Key trait to assign ids.

let inserted_header = db
    .collection::<MyCollection>()
    .push(&MyCollection::default())?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);
source

pub fn push_bytes<B: Into<Bytes> + Send>( &self, contents: B ) -> Result<CollectionHeader<Cl::PrimaryKey>, Error>

Adds a new Document<Cl> with the contents.

Automatic ID Assignment

An id will be automatically assigned, if possible, by the storage backend, which uses the Key trait to assign ids.

let inserted_header = db.collection::<MyCollection>().push_bytes(vec![])?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);
source

pub fn insert<PrimaryKey>( &self, id: &PrimaryKey, item: &<Cl as SerializedCollection>::Contents ) -> Result<CollectionHeader<Cl::PrimaryKey>, Error>
where Cl: SerializedCollection, PrimaryKey: KeyEncoding<Cl::PrimaryKey> + ?Sized,

Adds a new Document<Cl> with the given id and contents item.

let inserted_header = db
    .collection::<MyCollection>()
    .insert(&42, &MyCollection::default())?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);
source

pub fn insert_bytes<PrimaryKey, B: Into<Bytes> + Send>( &self, id: &PrimaryKey, contents: B ) -> Result<CollectionHeader<Cl::PrimaryKey>, Error>
where PrimaryKey: KeyEncoding<Cl::PrimaryKey> + ?Sized,

Adds a new Document<Cl> with the the given id and contents.

let inserted_header = db.collection::<MyCollection>().insert_bytes(&42, vec![])?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);
source

pub fn update<D: Document<Cl> + Send + Sync>( &self, doc: &mut D ) -> Result<(), Error>

Updates an existing document. Upon success, doc.revision will be updated with the new revision.

if let Some(mut document) = db.collection::<MyCollection>().get(&42)? {
    // modify the document
    db.collection::<MyCollection>().update(&mut document);
    println!("Updated revision: {:?}", document.header.revision);
}
source

pub fn overwrite<D: Document<Cl> + Send + Sync>( &self, doc: &mut D ) -> Result<(), Error>

Overwrites an existing document, or inserts a new document. Upon success, doc.revision will be updated with the new revision information.

if let Some(mut document) = db.collection::<MyCollection>().get(&42)? {
    // modify the document
    db.collection::<MyCollection>().overwrite(&mut document);
    println!("Updated revision: {:?}", document.header.revision);
}
source

pub fn get<PrimaryKey>( &self, id: &PrimaryKey ) -> Result<Option<OwnedDocument>, Error>
where PrimaryKey: KeyEncoding<Cl::PrimaryKey> + ?Sized,

Retrieves a Document<Cl> with id from the connection.

if let Some(doc) = db.collection::<MyCollection>().get(&42)? {
    println!(
        "Retrieved bytes {:?} with revision {}",
        doc.contents, doc.header.revision
    );
    let deserialized = MyCollection::document_contents(&doc)?;
    println!("Deserialized contents: {:?}", deserialized);
}
source

pub fn get_multiple<'id, DocumentIds, PrimaryKey, I>( &self, ids: DocumentIds ) -> Result<Vec<OwnedDocument>, Error>
where DocumentIds: IntoIterator<Item = &'id PrimaryKey, IntoIter = I> + Send + Sync, I: Iterator<Item = &'id PrimaryKey> + Send + Sync, PrimaryKey: KeyEncoding<Cl::PrimaryKey> + 'id + ?Sized,

Retrieves all documents matching ids. Documents that are not found are not returned, but no error will be generated.

for doc in db.collection::<MyCollection>().get_multiple(&[42, 43])? {
    println!("Retrieved #{} with bytes {:?}", doc.header.id, doc.contents);
    let deserialized = MyCollection::document_contents(&doc)?;
    println!("Deserialized contents: {:?}", deserialized);
}
source

pub fn list<PrimaryKey, R>(&'a self, ids: R) -> List<'a, Cn, Cl, PrimaryKey>
where R: Into<Range<&'a PrimaryKey>>, PrimaryKey: KeyEncoding<Cl::PrimaryKey> + PartialEq + 'a + ?Sized, Cl::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Retrieves all documents matching the range of ids.

for doc in db
    .collection::<MyCollection>()
    .list(&42..)
    .descending()
    .limit(20)
    .query()?
{
    println!("Retrieved #{} with bytes {:?}", doc.header.id, doc.contents);
    let deserialized = MyCollection::document_contents(&doc)?;
    println!("Deserialized contents: {:?}", deserialized);
}
source

pub fn list_with_prefix<PrimaryKey>( &'a self, prefix: &'a PrimaryKey ) -> List<'a, Cn, Cl, PrimaryKey>
where PrimaryKey: IntoPrefixRange<'a, Cl::PrimaryKey> + KeyEncoding<Cl::PrimaryKey> + PartialEq + ?Sized, Cl::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Retrieves all documents with ids that start with prefix.

use bonsaidb_core::connection::Connection;
use bonsaidb_core::document::OwnedDocument;
use bonsaidb_core::schema::{Collection, Schematic, SerializedCollection};
use bonsaidb_core::Error;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", primary_key = String)]
pub struct MyCollection;

fn starts_with_a<C: Connection>(db: &C) -> Result<Vec<OwnedDocument>, Error> {
    db.collection::<MyCollection>()
        .list_with_prefix("a")
        .query()
}
source

pub fn all(&'a self) -> List<'a, Cn, Cl, Cl::PrimaryKey>

Retrieves all documents.

for doc in db.collection::<MyCollection>().all().query()? {
    println!("Retrieved #{} with bytes {:?}", doc.header.id, doc.contents);
    let deserialized = MyCollection::document_contents(&doc)?;
    println!("Deserialized contents: {:?}", deserialized);
}
source

pub fn delete<H: HasHeader + Send + Sync>(&self, doc: &H) -> Result<(), Error>

Removes a Document from the database.

if let Some(doc) = db.collection::<MyCollection>().get(&42)? {
    db.collection::<MyCollection>().delete(&doc)?;
}

Trait Implementations§

source§

impl<'a, Cn, Cl> Clone for Collection<'a, Cn, Cl>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<'a, Cn, Cl> RefUnwindSafe for Collection<'a, Cn, Cl>

§

impl<'a, Cn, Cl> Send for Collection<'a, Cn, Cl>
where Cl: Send, Cn: Sync,

§

impl<'a, Cn, Cl> Sync for Collection<'a, Cn, Cl>
where Cl: Sync, Cn: Sync,

§

impl<'a, Cn, Cl> Unpin for Collection<'a, Cn, Cl>
where Cl: Unpin,

§

impl<'a, Cn, Cl> UnwindSafe for Collection<'a, Cn, Cl>
where Cl: UnwindSafe, Cn: RefUnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more