Struct bonsaidb::core::connection::AsyncCollection [−][src]
pub struct AsyncCollection<'a, Cn, Cl> { /* fields omitted */ }
Expand description
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
pub async fn push(
&'_ self,
item: &'_ <Cl as SerializedCollection>::Contents
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
Cl: SerializedCollection,
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,
pub async fn push_bytes<B>(
&'_ self,
contents: B
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
B: Into<Bytes> + Send,
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: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
pub async fn insert<PrimaryKey>(
&'_ self,
id: PrimaryKey,
item: &'_ <Cl as SerializedCollection>::Contents
) -> Result<CollectionHeader<<Cl as Collection>::PrimaryKey>, Error> where
Cl: SerializedCollection,
PrimaryKey: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
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,
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,
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
);
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);
}
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: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
pub async fn get<PrimaryKey>(
&'_ self,
id: PrimaryKey
) -> Result<Option<OwnedDocument>, Error> where
PrimaryKey: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
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: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
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: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
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
) -> AsyncList<'a, Cn, Cl, PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
where
R: Into<Range<PrimaryKey>>,
PrimaryKey: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
pub fn list<PrimaryKey, R>(
&'a self,
ids: R
) -> AsyncList<'a, Cn, Cl, PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
where
R: Into<Range<PrimaryKey>>,
PrimaryKey: for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
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
) -> AsyncList<'a, Cn, Cl, <Cl as Collection>::PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
where
<Cl as Collection>::PrimaryKey: IntoPrefixRange,
pub fn list_with_prefix(
&'a self,
prefix: <Cl as Collection>::PrimaryKey
) -> AsyncList<'a, Cn, Cl, <Cl as Collection>::PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
where
<Cl as Collection>::PrimaryKey: IntoPrefixRange,
impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
Retrieves all documents with ids that start with prefix
.
use bonsaidb_core::{
connection::AsyncConnection,
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: AsyncConnection>(db: &C) -> Result<Vec<OwnedDocument>, Error> {
db.collection::<MyCollection>()
.list_with_prefix(String::from("a"))
.await
}
pub fn all(&'a self) -> AsyncList<'a, Cn, Cl, <Cl as Collection>::PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
pub fn all(&'a self) -> AsyncList<'a, Cn, Cl, <Cl as Collection>::PrimaryKey>ⓘNotable traits for AsyncList<'a, Cn, Cl, PrimaryKey>impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
impl<'a, Cn, Cl, PrimaryKey> Future for AsyncList<'a, Cn, Cl, PrimaryKey> where
Cn: AsyncConnection,
Cl: Collection + Unpin,
PrimaryKey: 'a + Unpin + for<'k> KeyEncoding<'k, <Cl as Collection>::PrimaryKey>,
<Cl as Collection>::PrimaryKey: Unpin, type Output = Result<Vec<OwnedDocument, Global>, Error>;
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);
}
Trait Implementations
Auto Trait Implementations
impl<'a, Cn, Cl> RefUnwindSafe for AsyncCollection<'a, Cn, Cl> where
Cl: RefUnwindSafe,
Cn: RefUnwindSafe,
impl<'a, Cn, Cl> Send for AsyncCollection<'a, Cn, Cl> where
Cl: Send,
Cn: Sync,
impl<'a, Cn, Cl> Sync for AsyncCollection<'a, Cn, Cl> where
Cl: Sync,
Cn: Sync,
impl<'a, Cn, Cl> Unpin for AsyncCollection<'a, Cn, Cl> where
Cl: Unpin,
impl<'a, Cn, Cl> UnwindSafe for AsyncCollection<'a, Cn, Cl> where
Cl: UnwindSafe,
Cn: RefUnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more