Struct Keyspace 

pub struct Keyspace(/* private fields */);

Handle to a keyspace

Each keyspace is backed by an LSM-tree to provide a disk-backed search tree, and can be configured individually.

A keyspace generally only takes a little bit of memory and disk space, but does not spawn its own background threads.

As long as a handle to a keyspace is held, its folder is not cleaned up from disk in case it is deleted from another thread.

Implementations

impl Keyspace

pub fn name(&self) -> &StrView

Returns the keyspace’s name.

pub fn clear(&self) -> Result<()>

Clears the entire keyspace in O(1) time.

Errors

Will return Err if an IO error occurs.

pub fn fragmented_blob_bytes(&self) -> u64

Returns the number of blob bytes on disk that are not referenced.

These will be reclaimed over time by blob garbage collection automatically.

pub fn start_ingestion(&self) -> Result<Ingestion<'_>>

Prepare ingestiom of a pre-sorted stream of key-value pairs into the keyspace.

Prefer this method over singular inserts or write batches/transactions for maximum bulk load speed.

Errors

Will return Err if an IO error occurs.

Panics

Panics if the input iterator is not sorted in ascending order.

pub fn path(&self) -> &Path

Returns the underlying LSM-tree’s path.

pub fn disk_space(&self) -> u64

Returns the disk space usage of this keyspace.

Examples

assert_eq!(0, tree.disk_space());

pub fn iter(&self) -> Iter

Returns an iterator that scans through the entire keyspace.

Avoid using this function, or limit it as otherwise it may scan a lot of items.

Examples

tree.insert("a", "abc")?;
tree.insert("f", "abc")?;
tree.insert("g", "abc")?;
assert_eq!(3, tree.iter().count());

pub fn range<K: AsRef<[u8]>, R: RangeBounds<K>>(&self, range: R) -> Iter

Returns an iterator over a range of items.

Avoid using full or unbounded ranges as they may scan a lot of items (unless limited).

Examples

tree.insert("a", "abc")?;
tree.insert("f", "abc")?;
tree.insert("g", "abc")?;
assert_eq!(2, tree.range("a"..="f").count());

pub fn prefix<K: AsRef<[u8]>>(&self, prefix: K) -> Iter

Returns an iterator over a prefixed set of items.

Avoid using an empty prefix as it may scan a lot of items (unless limited).

Examples

tree.insert("a", "abc")?;
tree.insert("ab", "abc")?;
tree.insert("abc", "abc")?;
assert_eq!(2, tree.prefix("ab").count());

pub fn approximate_len(&self) -> usize

Approximates the amount of items in the keyspace.

For update- or delete-heavy workloads, this value will diverge from the real value, but is a O(1) operation.

For insert-only workloads (e.g. logs, time series) this value is reliable.

Examples

assert_eq!(tree.approximate_len(), 0);

tree.insert("1", "abc")?;
assert_eq!(tree.approximate_len(), 1);

tree.remove("1")?;
// Oops! approximate_len will not be reliable here
assert_eq!(tree.approximate_len(), 2);

pub fn len(&self) -> Result<usize>

Scans the entire keyspace, returning the amount of items.

Caution

This operation scans the entire keyspace: O(n) complexity!

Never, under any circumstances, use .len() == 0 to check if the keyspace is empty, use Keyspace::is_empty instead.

If you want an estimate, use Keyspace::approximate_len instead.

Examples

assert_eq!(tree.len()?, 0);

tree.insert("1", "abc")?;
tree.insert("3", "abc")?;
tree.insert("5", "abc")?;
assert_eq!(tree.len()?, 3);

Errors

Will return Err if an IO error occurs.

pub fn is_empty(&self) -> Result<bool>

Returns true if the keyspace is empty.

This operation has O(log N) complexity.

Examples

assert!(tree.is_empty()?);

tree.insert("a", "abc")?;
assert!(!tree.is_empty()?);

Errors

Will return Err if an IO error occurs.

pub fn contains_key<K: AsRef<[u8]>>(&self, key: K) -> Result<bool>

Returns true if the keyspace contains the specified key.

Examples

assert!(!tree.contains_key("a")?);

tree.insert("a", "abc")?;
assert!(tree.contains_key("a")?);

Errors

Will return Err if an IO error occurs.

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

Retrieves an item from the keyspace.

Examples

tree.insert("a", "my_value")?;

let item = tree.get("a")?;
assert_eq!(Some("my_value".as_bytes().into()), item);

Errors

Will return Err if an IO error occurs.

pub fn size_of<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<u32>>

Retrieves the size of an item from the keyspace.

Examples

tree.insert("a", "my_value")?;

let len = tree.size_of("a")?.unwrap_or_default();
assert_eq!("my_value".len() as u32, len);

Errors

Will return Err if an IO error occurs.

pub fn first_key_value(&self) -> Option<Guard>

Returns the first key-value pair in the keyspace. The key in this pair is the minimum key in the keyspace.

Examples

tree.insert("1", "abc")?;
tree.insert("3", "abc")?;
tree.insert("5", "abc")?;

let key = tree.first_key_value().expect("item should exist").key()?;
assert_eq!(&*key, "1".as_bytes());

Errors

Will return Err if an IO error occurs.

pub fn last_key_value(&self) -> Option<Guard>

Returns the last key-value pair in the keyspace. The key in this pair is the maximum key in the keyspace.

Examples

tree.insert("1", "abc")?;
tree.insert("3", "abc")?;
tree.insert("5", "abc")?;

let key = tree.last_key_value().expect("item should exist").key()?;
assert_eq!(&*key, "5".as_bytes());

Errors

Will return Err if an IO error occurs.

pub fn is_kv_separated(&self) -> bool

Returns true if the underlying LSM-tree is key-value-separated.

pub fn insert<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, value: V, ) -> Result<()>

Inserts a key-value pair into the keyspace.

Keys may be up to 65536 bytes long, values up to 2^32 bytes. Shorter keys and values result in better performance.

If the key already exists, the item will be overwritten.

Examples

tree.insert("a", "abc")?;

assert!(!tree.is_empty()?);

Errors

Will return Err if an IO error occurs.

pub fn remove<K: Into<UserKey>>(&self, key: K) -> Result<()>

Removes an item from the keyspace.

The key may be up to 65536 bytes long. Shorter keys result in better performance.

Examples

tree.insert("a", "abc")?;

let item = tree.get("a")?.expect("should have item");
assert_eq!("abc".as_bytes(), &*item);

tree.remove("a")?;

let item = tree.get("a")?;
assert_eq!(None, item);

Errors

Will return Err if an IO error occurs.

Trait Implementations

impl AsRef<Keyspace> for &Keyspace

fn as_ref(&self) -> &Keyspace

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Keyspace> for OptimisticTxKeyspace

fn as_ref(&self) -> &Keyspace

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Keyspace> for SingleWriterTxKeyspace

fn as_ref(&self) -> &Keyspace

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Keyspace

fn clone(&self) -> Keyspace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Deref for Keyspace

type Target = KeyspaceInner

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for Keyspace

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Keyspace

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Keyspace