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 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.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 copy 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