Trait bonsaidb_core::schema::Collection

source ·

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

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

    // Provided method
    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(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(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, ViewSchema};
use serde::{Deserialize, Serialize};

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

#[derive(Clone, View, ViewSchema)]
#[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(Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", primary_key = u128)]
pub struct MyCollection;

If the data being stored has a “natural key”, the field can be annotated with #[natural_id] to use the field’s contents as the primary key when doing a push operation:

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

#[derive(Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
pub struct MyCollection {
    #[natural_id]
    pub external_id: u64,
}

Alternatively, this can be accomplished with an expression using the natural_id attribute:

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

#[derive(Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", natural_id = Some(self.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(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(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(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(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(Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(serialization = None)]
pub struct MyCollection;

If the collection type implements or derives the Key trait, serialization = Key can be passed to serialize using the key format.