Struct bonsaidb::core::connection::View

pub struct View<'a, Cn, V, Key>
where
    V: SerializedView,
    <V as View>::Key: Borrow<Key> + PartialEq<Key>,
    Key: PartialEq + ?Sized,
{
    pub key: Option<QueryKey<'a, <V as View>::Key, Key>>,
    pub access_policy: AccessPolicy,
    pub sort: Sort,
    pub limit: Option<u32>,
    /* private fields */
}

Parameters to query a schema::View.

The examples for this type use this view definition:

use bonsaidb_core::define_basic_unique_mapped_view;
use bonsaidb_core::document::{CollectionDocument, Emit};
use bonsaidb_core::schema::{
    CollectionMapReduce, DefaultViewSerialization, Name, ReduceResult, View, ViewMapResult,
    ViewMappedValue, ViewSchema,
};

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

impl CollectionMapReduce for ScoresByRank {
    fn map<'doc>(
        &self,
        document: CollectionDocument<<Self::View as View>::Collection>,
    ) -> ViewMapResult<'doc, Self::View> {
        document
            .header
            .emit_key_and_value(document.contents.rank, document.contents.score)
    }

    fn reduce(
        &self,
        mappings: &[ViewMappedValue<'_, Self::View>],
        rereduce: bool,
    ) -> ReduceResult<Self::View> {
        if mappings.is_empty() {
            Ok(0.)
        } else {
            Ok(mappings.iter().map(|map| map.value).sum::<f32>() / mappings.len() as f32)
        }
    }
}

Fields

key: Option<QueryKey<'a, <V as View>::Key, Key>>

Key filtering criteria.

access_policy: AccessPolicy

The view’s data access policy. The default value is AccessPolicy::UpdateBefore.

sort: Sort

The sort order of the query.

limit: Option<u32>

The maximum number of results to return.

Implementations

impl<'a, Cn, V, Key> View<'a, Cn, V, Key>

where <V as View>::Key: Borrow<Key> + PartialEq<Key>, V: SerializedView, Cn: Connection, Key: KeyEncoding<<V as View>::Key> + PartialEq + ?Sized,

pub fn with_key<K>(self, key: &'a K) -> View<'a, Cn, V, K>

where K: KeyEncoding<<V as View>::Key> + PartialEq + ?Sized, <V as View>::Key: Borrow<K> + PartialEq<K>,

Filters for entries in the view with key.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).with_key(&42).query()? {
    assert_eq!(mapping.key, 42);
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub fn with_keys<K, IntoIter>(self, keys: IntoIter) -> View<'a, Cn, V, K>

where IntoIter: IntoIterator<Item = &'a K>, <V as View>::Key: Borrow<K> + PartialEq<K>, K: PartialEq + ?Sized,

Filters for entries in the view with keys.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).with_keys(&[42, 43]).query()? {
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub fn with_key_range<K, R>(self, range: R) -> View<'a, Cn, V, K>

where R: Into<RangeRef<'a, <V as View>::Key, K>>, K: PartialEq, <V as View>::Key: Borrow<K> + PartialEq<K>,

Filters for entries in the view with the range keys.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).with_key_range(42..).query()? {
    assert!(mapping.key >= 42);
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub fn with_key_prefix<K>(self, prefix: &'a K) -> View<'a, Cn, V, K>

where K: KeyEncoding<<V as View>::Key> + IntoPrefixRange<'a, <V as View>::Key> + PartialEq + ?Sized, <V as View>::Key: Borrow<K> + PartialEq<K>,

Filters for entries in the view with keys that begin with prefix.

#[derive(View, Debug, Clone)]
#[view(name = "by-name", key = String, collection = MyCollection)]
struct ByName;

// score is an f32 in this example
for mapping in ByName::entries(&db).with_key_prefix("a").query()? {
    assert!(mapping.key.starts_with("a"));
    println!("{} in document {:?}", mapping.key, mapping.source);
}

pub const fn with_access_policy( self, policy: AccessPolicy ) -> View<'a, Cn, V, Key>

Sets the access policy for queries.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db)
    .with_access_policy(AccessPolicy::UpdateAfter)
    .query()?
{
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub const fn ascending(self) -> View<'a, Cn, V, Key>

Returns the matching mappings in ascending key order. This is the default sorting behavior.

When more than one mapping exists for a single key, all matching mappings are returned as a unique entry. The resulting mappings are sorted only by the key, and as such, the order of mappings with the same key is undefined.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).ascending().query()? {
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub const fn descending(self) -> View<'a, Cn, V, Key>

Returns the matching mappings in descending key order.

When more than one mapping exists for a single key, all matching mappings are returned as a unique entry. The resulting mappings are sorted only by the key, and as such, the order of mappings with the same key is undefined.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).descending().query()? {
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub const fn limit(self, maximum_results: u32) -> View<'a, Cn, V, Key>

Sets the maximum number of results to return.

// score is an f32 in this example
let mappings = ScoresByRank::entries(&db).limit(10).query()?;
assert!(mappings.len() <= 10);

pub fn query( self ) -> Result<Vec<CollectionMap<<<V as View>::Collection as Collection>::PrimaryKey, <V as View>::Key, <V as View>::Value>>, Error>

Executes the query and retrieves the results.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).query()? {
    println!("Rank {} has a score of {:3}", mapping.key, mapping.value);
}

pub fn query_with_docs(self) -> Result<MappedDocuments<OwnedDocument, V>, Error>

Executes the query and retrieves the results with the associated Documents.

for mapping in &ScoresByRank::entries(&db)
    .with_key_range(42..=44)
    .query_with_docs()?
{
    println!(
        "Mapping from #{} with rank: {} and score: {}. Document bytes: {:?}",
        mapping.document.header.id, mapping.key, mapping.value, mapping.document.contents
    );
}

pub fn query_with_collection_docs( self ) -> Result<MappedDocuments<CollectionDocument<<V as View>::Collection>, V>, Error>

where <V as View>::Collection: SerializedCollection, <<V as View>::Collection as SerializedCollection>::Contents: Debug,

Executes the query and retrieves the results with the associated CollectionDocuments.

for mapping in &ScoresByRank::entries(&db)
    .with_key_range(42..=44)
    .query_with_collection_docs()?
{
    println!(
        "Mapping from #{} with rank: {} and score: {}. Deserialized Contents: {:?}",
        mapping.document.header.id, mapping.key, mapping.value, mapping.document.contents
    );
}

pub fn reduce(self) -> Result<<V as View>::Value, Error>

Executes a reduce over the results of the query

// score is an f32 in this example
let score = ScoresByRank::entries(&db).reduce()?;
println!("Average score: {:3}", score);

pub fn reduce_grouped( self ) -> Result<Vec<MappedValue<<V as View>::Key, <V as View>::Value>>, Error>

Executes a reduce over the results of the query, grouping by key.

// score is an f32 in this example
for mapping in ScoresByRank::entries(&db).reduce_grouped()? {
    println!(
        "Rank {} has an average score of {:3}",
        mapping.key, mapping.value
    );
}

pub fn delete_docs(self) -> Result<u64, Error>

Deletes all of the associated documents that match this view query.

ScoresByRank::entries(&db).delete_docs()?;