pub trait Collection: Debug + Send + Sync {
    type PrimaryKey: for<'k> Key<'k> + Eq + Ord;

    fn collection_name() -> CollectionName;
    fn define_views(schema: &mut Schematic) -> Result<(), Error>;

    fn encryption_key() -> Option<KeyId> { ... }
}
Expand description

A namespaced collection of Document<Self> items and views.

Deriving this trait

This trait can be derived instead of manually implemented:

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

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

If you’re publishing a collection for use in multiple projects, consider giving the collection an authority, which gives your collection a namespace:

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

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

The list of views can be specified using the views parameter:

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

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

#[derive(Debug, Clone, View)]
#[view(collection = MyCollection, key = u32, value = f32, name = "scores-by-rank")]
pub struct ScoresByRank;

Selecting a Primary Key type

By default, the #[collection] macro will use u64 for the Self::PrimaryKey type. Collections can use any type that implements the Key trait:

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

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

If the data being stored has a “natural key”, a closure or a function can be provided to extract the value during a push operation:

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

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", natural_id = |item: &Self| Some(item.external_id))]
pub struct MyCollection {
    pub external_id: u64,
}

Primary keys are not able to be updated. To update a document’s primary key, the contents must be inserted at the new id and deleted from the previous id.

Specifying a Collection Encryption Key

By default, encryption will be required if an encryption_key is provided:

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

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", encryption_key = Some(KeyId::Master))]
pub struct MyCollection;

The encryption_required parameter can be provided if you wish to be explicit:

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

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(encryption_key = Some(KeyId::Master), encryption_required)]
pub struct MyCollection;

Or, if you wish your collection to be encrypted if its available, but not cause errors when being stored without encryption, you can provide the encryption_optional parameter:

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

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(encryption_key = Some(KeyId::Master), encryption_optional)]
pub struct MyCollection;

Changing the serialization strategy

BonsaiDb uses transmog to allow customizing serialization formats. To use one of the formats Transmog already supports, add its crate to your Cargo.toml and use it like this example using transmog_bincode:

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

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(serialization = transmog_bincode::Bincode)]
pub struct MyCollection;

To manually implement SerializedCollection you can pass None to serialization:

use bonsaidb_core::schema::Collection;

#[derive(Debug, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(serialization = None)]
pub struct MyCollection;

Required Associated Types§

The unique id type. Each document stored in a collection will be uniquely identified by this type.

Primary Key Limits

The result of KeyEncoding::as_ord_bytes() must be less than or equal to DocumentId::MAX_LENGTH.

Required Methods§

The unique name of this collection. Each collection must be uniquely named within the Schema it is registered within.

Defines all Views in this collection in schema.

Provided Methods§

If a KeyId is returned, this collection will be stored encrypted at-rest using the key specified.

Implementors§