[−][src]Crate mokuroku

Overview

This crate will build and maintain a secondary index within RocksDB, similar to what PouchDB does for LevelDB. The index keys and optional values are provided by your application. Once an index has been defined, queries for all entries, or those whose keys match a given prefix, can be performed. The index is kept up-to-date as data records, the data your application is storing in the database, are changed and/or deleted.

Usage

Create an instance of Database much like you would with rocksdb::DB. Provide the path to the database files, the set of indices to maintain (often referred to as views), and a ByteMapper that will assist in building indices from existing data.

Below is a very brief example. See the README and examples directory for additional examples.

fn mapper(key: &[u8], value: &[u8], view: &str, emitter: &Emitter) -> Result<(), Error> {
    // ... call emitter.emit() with index keys and optional values
    Ok(())
}
let db_path = "my_database";
let views = vec!["tags".to_owned()];
let dbase = Database::new(Path::new(db_path), views, Box::new(mapper)).unwrap();

Data Model

The secondary indices are built when Database.query() is called and the corresponding column family is missing. Knowing this, an application may want to open the database and subsequently call query() for every view. This will cause the index to be built based on the existing data. If for whatever reason the application deems it necessary to rebuild an index, that can be accomplished by calling the rebuild() function. When building an index, the library will invoke the application's ByteMapper function.

N.B. The index key emitted by the application is combined with the data record primary key, separated by a single null byte. Using a separator is necessary since the library does not know in advance how long either of these keys is expected to be, and the index query depends heavily on using the prefix iterator to speed up the search. If you want to specify a different separator, use the Database.separator() function when opening the database. If at some later time you decide to change the separator, you will need to rebuild the indices.

Structs

Database	An instance of the database for reading and writing records to disk. This wrapper manages the secondary indices defined by the application.
Emitter	The `Emitter` receives index key/value pairs from the application.
QueryIterator	`QueryIterator` returns the results from a database query as an instance of `QueryResult`.
QueryResult	`QueryResult` represents a single result from a query. The `key` is that which was emitted by the application, and similarly the `value` is whatever the application emitted along with the key (it will be an empty vector if the application emitted `None`). The `doc_id` is the primary key of the data record, a named borrowed from PouchDB.

Traits

Document

Document defines operations required for building the index.

Type Definitions

ByteMapper

Responsible for emitting index key/value pairs for any given data record.