Struct bonsaidb::core::connection::Collection

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

Interacts with a collection over a Connection.

These examples in this type use this basic collection definition:

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

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

Implementations

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

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

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())
    .await?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);

pub async fn push_bytes<B>(
    &'_ self,
    contents: B
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
    B: Into<Bytes> + Send,
    Cl: SerializedCollection, 

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![]).await?;
println!(
    "Inserted id {} with revision {}",
    inserted_header.id, inserted_header.revision
);

pub async fn insert<PrimaryKey>(
    &'_ self,
    id: PrimaryKey,
    item: &'_ <Cl as SerializedCollection>::Contents
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
    Cl: SerializedCollection,
    PrimaryKey: Into<AnyDocumentId<<Cl as Collection>::PrimaryKey>> + Send + Sync, 

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

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

pub async fn insert_bytes<B>(
    &'_ self,
    id: <Cl as Collection>::PrimaryKey,
    contents: B
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
    B: Into<Bytes> + Send,
    Cl: SerializedCollection, 

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

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

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

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).await? {
    // modify the document
    db.collection::<MyCollection>().update(&mut document);
    println!("Updated revision: {:?}", document.header.revision);
}

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

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).await? {
    // modify the document
    db.collection::<MyCollection>().overwrite(&mut document);
    println!("Updated revision: {:?}", document.header.revision);
}

pub async fn get<PrimaryKey>(
    &'_ self,
    id: PrimaryKey
) -> Result<Option<OwnedDocument>, Error> where
    PrimaryKey: Into<AnyDocumentId<<Cl as Collection>::PrimaryKey>> + Send, 

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

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

pub async fn get_multiple<DocumentIds, PrimaryKey, I>(
    &'_ self,
    ids: DocumentIds
) -> Result<Vec<OwnedDocument, Global>, Error> where
    DocumentIds: IntoIterator<Item = PrimaryKey, IntoIter = I> + Send + Sync,
    I: Iterator<Item = PrimaryKey> + Send + Sync,
    PrimaryKey: Into<AnyDocumentId<<Cl as Collection>::PrimaryKey>> + Send + Sync, 

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])
    .await?
{
    println!("Retrieved #{} with bytes {:?}", doc.header.id, doc.contents);
    let deserialized = MyCollection::document_contents(&doc)?;
    println!("Deserialized contents: {:?}", deserialized);
}

pub fn list<PrimaryKey, R>(&'a self, ids: R) -> List<'a, Cn, Cl> where
    R: Into<Range<PrimaryKey>>,
    PrimaryKey: Into<AnyDocumentId<<Cl as Collection>::PrimaryKey>>, 

Retrieves all documents matching the range of ids.

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

pub fn list_with_prefix(
    &'a self,
    prefix: <Cl as Collection>::PrimaryKey
) -> List<'a, Cn, Cl> where
    <Cl as Collection>::PrimaryKey: IntoPrefixRange, 

Retrieves all documents with ids that start with prefix.

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

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

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

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

Retrieves all documents.

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

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

Removes a Document from the database.

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

Trait Implementations

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

fn clone(&self) -> Collection<'a, Cn, Cl>

Returns a copy of the value.

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

Performs copy-assignment from source.