Trait bonsaidb::core::schema::view::ViewSchema

pub trait ViewSchema: Send + Sync + 'static {
    type View: SerializedView;
    type MappedKey<'doc>: Key<'doc>;

    // Provided methods
    fn update_policy(&self) -> ViewUpdatePolicy { ... }
    fn version(&self) -> u64 { ... }
}
Expand description

Schema information for a View.

This trait controls several behaviors for a view:

  • MappedKey<'doc>: A Key type that is compatible with the associated View::Key type, but can borrow from the document by using the 'doc generic associated lifetime.
  • update_policy(): Controls when the view’s data is updated and any restrictions on the data contained in the view. The default policy for views is ViewUpdatePolicy
  • version(): An integer representing the view’s version. Changing this number will cause the view to be re-indexed. This is useful when there are fundamental changes in how the view is implemented.

Where is this trait used?

This trait is currently only used by bonsaidb-local, but is provided in bonsaidb-core to allow it to be used anywhere. It may be desireable to keep the implementation of ViewSchema in the “server” binary, while only exposing the View implementation to the “client”.

Deriving this Trait

This trait can be derived, and all attributes are optional. The available options are:

  • view: Sets the associated View type. If not provided, Self will be used.

  • version: Sets the version number of the view. If not provided, 0 will be used.

  • mapped_key: Sets the MappedKey<'doc> type to the provided type. The 'doc lifetime can be utilized to borrow data during the MapReduce::map() function.

    If not provided, the ViewSchema implementation uses View::Key.

  • policy: Sets the ViewUpdatePolicy. The accepted policies are:

    If not provided, the Lazy policy will be used.

Here is an example that showcases most of the options:

use std::borrow::Cow;

use bonsaidb_core::document::{BorrowedDocument, Emit};
use bonsaidb_core::schema::view::{ReduceResult, ViewMapResult};
use bonsaidb_core::schema::{MapReduce, View, ViewMappedValue, ViewSchema};

#[derive(View, ViewSchema)]
#[view(collection = MyCollection, key = String, value = u32)]
#[view_schema(mapped_key = Cow<'doc, str>, policy = Unique)]
struct UniqueByName;

impl MapReduce for UniqueByName {
    fn map<'doc>(&self, document: &'doc BorrowedDocument<'_>) -> ViewMapResult<'doc, Self> {
        let contents_as_str = std::str::from_utf8(&document.contents).expect("invalid utf-8");
        document
            .header
            .emit_key_and_value(Cow::Borrowed(contents_as_str), 1)
    }

    fn reduce(
        &self,
        mappings: &[ViewMappedValue<'_, Self::View>],
        _rereduce: bool,
    ) -> ReduceResult<Self::View> {
        Ok(mappings.iter().map(|mapping| mapping.value).sum())
    }
}

Views allow querying documents contained within Collections in an efficient manner.

The MapReduce::map() function is responsible for “mapping” data from the stored document into the Key type. In the example below, the field rank is being used as the View’s Key type, and the field score is being used as the View’s Value

The MapReduce::reduce() function is responsible for “reducing” a list of Values into a single value. The example below implements reduce() to return an average value.

This enables querying the view in many powerful ways:

All of the queries above can be filtered and customized by the methods available on connection::View.

For a more detailed walkthrough, see our user guide’s section on Views.

Required Associated Types§

type View: SerializedView

The view this schema is defined for.

type MappedKey<'doc>: Key<'doc>

The key type used during the map/reduce operation.

This can typically be specified as <Self::View as View>::Key. However, if the view can take advantage of utilizing borrowed data from the document in the map() and/or reduce() function calls, this type can utilize the generic associated lifetime 'doc. For example, Cow<'doc, str> can be used when the related View::Key type is String, and the map() function would be able to return a string slice that borrowed from the document.

Provided Methods§

fn update_policy(&self) -> ViewUpdatePolicy

Returns the update policy for this view, which controls when and how the view’s data is updated. The provided implementation returns ViewUpdatePolicy::Lazy.

fn version(&self) -> u64

The version of the view. Changing this value will cause indexes to be rebuilt.

Implementors§