Struct PartitionHandle 

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

Access to a keyspace partition

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

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

Implementations

impl PartitionHandle

pub fn ingest<K: Into<UserKey>, V: Into<UserValue>>( &self, iter: impl Iterator<Item = (K, V)>, ) -> Result<()>

Ingests a sorted stream of key-value pairs into the partition.

Can only be called on a new fresh, empty partition.

Errors

Will return Err if an IO error occurs.

Panics

Panics if the partition is not initially empty.

Will panic 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 partition.

Examples

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

pub fn iter(&self) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

Returns an iterator that scans through the entire partition.

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

Examples

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

pub fn keys(&self) -> impl DoubleEndedIterator<Item = Result<UserKey>> + 'static

Returns an iterator that scans through the entire partition, returning only keys.

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

pub fn values( &self, ) -> impl DoubleEndedIterator<Item = Result<UserValue>> + 'static

Returns an iterator that scans through the entire partition, returning only values.

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

pub fn range<'a, K: AsRef<[u8]> + 'a, R: RangeBounds<K> + 'a>( &'a self, range: R, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

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

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

pub fn prefix<'a, K: AsRef<[u8]> + 'a>( &'a self, prefix: K, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

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

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

pub fn approximate_len(&self) -> usize

Approximates the amount of items in the partition.

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!(partition.approximate_len(), 0);

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

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

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

Scans the entire partition, returning the amount of items.

Caution

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

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

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

Examples

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

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

Errors

Will return Err if an IO error occurs.

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

Returns true if the partition is empty.

This operation has O(1) complexity.

Examples

assert!(partition.is_empty()?);

partition.insert("a", "abc")?;
assert!(!partition.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 partition contains the specified key.

Examples

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

partition.insert("a", "abc")?;
assert!(partition.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 partition.

Examples

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

let item = partition.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 partition.

Examples

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

let len = partition.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) -> Result<Option<KvPair>>

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

Examples

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

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

Errors

Will return Err if an IO error occurs.

pub fn last_key_value(&self) -> Result<Option<KvPair>>

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

Examples

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

let (key, _) = partition.last_key_value()?.expect("item should exist");
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.

See CreateOptions::with_kv_separation for more information.

Examples

let tree1 = keyspace.open_partition("default", PartitionCreateOptions::default())?;
assert!(!tree1.is_kv_separated());

let blob_cfg = PartitionCreateOptions::default().with_kv_separation(Default::default());
let tree2 = keyspace.open_partition("blobs", blob_cfg)?;
assert!(tree2.is_kv_separated());

pub fn snapshot(&self) -> Snapshot

Opens a snapshot of this partition.

pub fn snapshot_at(&self, seqno: Instant) -> Snapshot

Opens a snapshot of this partition with a given sequence number.

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

Inserts a key-value pair into the partition.

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

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

assert!(!partition.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 partition.

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

Examples

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

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

partition.remove("a")?;

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

Errors

Will return Err if an IO error occurs.

Trait Implementations

impl Clone for PartitionHandle

fn clone(&self) -> PartitionHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for PartitionHandle

type Target = PartitionHandleInner

The resulting type after dereferencing.

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

Dereferences the value.

impl GarbageCollection for PartitionHandle

fn gc_scan(&self) -> Result<GcReport>

Collects statistics about blob fragmentation inside the partition.

fn gc_with_space_amp_target(&self, factor: f32) -> Result<u64>

Rewrites blobs in order to achieve the given space amplification factor.

fn gc_with_staleness_threshold(&self, threshold: f32) -> Result<u64>

Rewrites blobs that have reached a given staleness threshold.

fn gc_drop_stale_segments(&self) -> Result<u64>

Drops fully stale segments.

impl Hash for PartitionHandle

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 PartitionHandle

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 PartitionHandle