Struct mokuroku::Database

pub struct Database { /* private fields */ }

An instance of the database for reading and writing records to disk. This wrapper manages the secondary indices defined by the application.

The secondary indices, often referred to as views, will be stored in RocksDB column families whose names are based on the names given in the constructor, with a prefix of mrview- to avoid conflicting with any column families managed by the application. The library will manage these column families as needed when (re)building the indices.

In addition to the names of the views, the application must provide a mapping function that works with key/value pairs as slices of bytes. This is called when building an index by reading every record in the default column family, in which the library does not have an inferred Document implementation to deserialize the record.

Implementations

impl Database

pub fn open_default<I, N>(
    db_path: &Path,
    views: I,
    mapper: ByteMapper
) -> Result<Self, Error> where
    I: IntoIterator<Item = N>,
    N: ToString, 

Open a database with default options.

The set of view names are passed to Document.map() whenever a document is put() into the database. That is, these are the names of the indices that will be updated whenever a document is stored.

The ByteMapper is responsible for deserializing any type of record and emitting index key/value pairs appropriately. It will be invoked when (re)building an index from existing data.

pub fn open<I, N>(
    db_path: &Path,
    views: I,
    mapper: ByteMapper,
    opts: Options
) -> Result<Self, Error> where
    I: IntoIterator<Item = N>,
    N: ToString, 

Open the database with the specified database options.

pub fn separator(self, sep: &[u8]) -> Self

Set the byte sequence used to separate index key from primary key.

This sets the separator byte sequence used to separate the index key from the primary data record key in the index. The default is a single null byte. Note that changing the separator sequence will likely invalidate any previously built indices, and thus the application should call rebuild() for every defined view.

pub fn db(&self) -> &DB

Return a reference to the RocksDB instance.

This is an escape hatch in the event that you need to call a function that is not exposed via this wrapper. Beware that interfacing directly with RocksDB means that the index is not being updated with respect to those operations.

pub fn mut_db(&mut self) -> &mut DB

Return a mutable reference to the RocksDB instance.

The mutable version of the db() function.

pub fn put<D, K>(&mut self, key: K, value: &D) -> Result<(), Error> where
    D: Document,
    K: AsRef<[u8]>, 

Put the data record key/value pair into the database, ensuring all indices are updated, if they have been built.

pub fn get<D, K>(&self, key: K) -> Result<Option<D>, Error> where
    D: Document,
    K: AsRef<[u8]>, 

Retrieve the data record with the given key.

pub fn delete<K: AsRef<[u8]>>(&mut self, key: K) -> Result<(), Error>

Delete the data record associated with the given key.

pub fn query(&mut self, view: &str) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning all results.

If the index has not yet been built, it will be built prior to returning any results.

pub fn query_by_key<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning those results whose key prefix matches the value given, with the keys in ascending order.

Only those index keys with a matching prefix will be returned.

As with query(), if the index has not yet been built, it will be.

pub fn query_all_keys<I, N>(
    &mut self,
    view: &str,
    keys: I
) -> Result<Vec<QueryResult>, Error> where
    I: IntoIterator<Item = N>,
    N: AsRef<[u8]>, 

Query the index for documents that have all of the given keys.

Unlike the other query functions, this one returns a single result per document for which it emitted all of the specified keys.

This function is potentially memory intensive as it will query the index for each given key, combining all of the results in memory, and then filtering out the documents that lack all of the keys. As such this returns a vector versus an iterator.

pub fn query_exact<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning those results whose key matches exactly the value given.

Only those index entries with matching keys will be returned.

As with query(), if the index has not yet been built, it will be.

pub fn query_range<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key_a: K,
    key_b: K
) -> Result<QueryIterator<'_>, Error>

Query an index by range of key values, returning those results whose key is equal to or greater than the first key, and less than the second key.

See also query_greater_than() and query_less_than() for querying with only the lower or upper bound.

As with query(), if the index has not yet been built, it will be.

pub fn query_greater_than<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning those results whose key is equal to or greater than the key.

See also query_range() and query_less_than().

As with query(), if the index has not yet been built, it will be.

pub fn query_less_than<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning those results whose key strictly less than the key.

See also query_range() and query_greater_than().

As with query(), if the index has not yet been built, it will be.

pub fn query_desc<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<QueryIterator<'_>, Error>

Query on the given index, returning those results whose key is less than the given value, with the keys in descending order.

As with query(), if the index has not yet been built, it will be.

pub fn count_by_key<K: AsRef<[u8]>>(
    &mut self,
    view: &str,
    key: K
) -> Result<usize, Error>

Query on the given index, returning the number of rows whose key prefix matches the value given.

As with query(), if the index has not yet been built, it will be.

pub fn count_all_keys(
    &mut self,
    view: &str
) -> Result<HashMap<Box<[u8]>, usize>, Error>

Query the index and return the number of occurrences of all keys.

The map keys are the index keys, and the map values are the number of times each key was encountered in the index.

As with query(), if the index has not yet been built, it will be.

pub fn rebuild(&mut self, view: &str) -> Result<(), Error>

Build the named index, replacing the index if it already exists.

To simply ensure that an index has been built, call query(), which will not delete the existing index.

pub fn delete_index(&mut self, view: &str) -> Result<(), Error>

Delete the named index from the database.

If the column family for the named view exists, it will be dropped. Likewise, the entry will be removed from the set of view names defined in this instance, such that it will no longer be passed to the Document.map() functions.

pub fn index_cleanup(&mut self) -> Result<(), Error>

Scan for column families that are not associated with this database instance, and yet have the “mrview-” prefix, removing any that are found.