Trait bonsaidb::core::schema::Collection

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.

Required Associated Types§

type PrimaryKey: for<'k> Key<'k> + Eq + Ord

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§

fn collection_name() -> CollectionName

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

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

Defines all Views in this collection in schema.

Provided Methods§

fn encryption_key() -> Option<KeyId>

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

Implementors§