Struct ReadTransaction

pub struct ReadTransaction { /* private fields */ }

A cross-partition, read-only transaction (snapshot)

Implementations

impl ReadTransaction

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

Retrieves an item from the transaction’s state.

Examples

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

let tx = keyspace.read_tx();
let item = tx.get(&partition, "a")?;
assert_eq!(Some("my_value".as_bytes().into()), item);

partition.insert("b", "my_updated_value")?;

// Repeatable read
let item = tx.get(&partition, "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, partition: &TxPartitionHandle, key: K, ) -> Result<Option<u32>>

Retrieves the size of an item from the transaction’s state.

Examples

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

let tx = keyspace.read_tx();
let item = tx.size_of(&partition, "a")?.unwrap_or_default();
assert_eq!("my_value".len() as u32, item);

partition.insert("b", "my_updated_value")?;

// Repeatable read
let item = tx.size_of(&partition, "a")?.unwrap_or_default();
assert_eq!("my_value".len() as u32, item);

Errors

Will return Err if an IO error occurs.

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

Returns true if the transaction’s state contains the specified key.

Examples

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

let tx = keyspace.read_tx();
assert!(tx.contains_key(&partition, "a")?);

Errors

Will return Err if an IO error occurs.

pub fn first_key_value( &self, partition: &TxPartitionHandle, ) -> Result<Option<KvPair>>

Returns the first key-value pair in the transaction’s state. The key in this pair is the minimum key in the transaction’s state.

Examples

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

let (key, _) = keyspace.read_tx().first_key_value(&partition)?.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, partition: &TxPartitionHandle, ) -> Result<Option<KvPair>>

Returns the last key-value pair in the transaction’s state. The key in this pair is the maximum key in the transaction’s state.

Examples

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

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

Errors

Will return Err if an IO error occurs.

pub fn len(&self, partition: &TxPartitionHandle) -> 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 ReadTransaction::is_empty instead.

Examples

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

let tx = keyspace.read_tx();
assert_eq!(2, tx.len(&partition)?);

partition.insert("c", "my_value3")?;

// Repeatable read
assert_eq!(2, tx.len(&partition)?);

// Start new snapshot
let tx = keyspace.read_tx();
assert_eq!(3, tx.len(&partition)?);

Errors

Will return Err if an IO error occurs.

pub fn is_empty(&self, partition: &TxPartitionHandle) -> Result<bool>

Returns true if the partition is empty.

This operation has O(1) complexity.

Examples

assert!(keyspace.read_tx().is_empty(&partition)?);

partition.insert("a", "abc")?;
assert!(!keyspace.read_tx().is_empty(&partition)?);

Errors

Will return Err if an IO error occurs.

pub fn iter<'a>( &'a self, partition: &'a TxPartitionHandle, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

Iterates over the transaction’s state.

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, keyspace.read_tx().iter(&partition).count());

pub fn keys<'a>( &'a self, partition: &'a TxPartitionHandle, ) -> impl DoubleEndedIterator<Item = Result<UserKey>> + 'static

Iterates over the transaction’s state, returning keys only.

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

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

Iterates over the transaction’s state, returning values only.

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, partition: &'a TxPartitionHandle, range: R, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

Iterates over a range of the transaction’s state.

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, keyspace.read_tx().range(&partition, "a"..="f").count());

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

Iterates over a prefixed set of the transaction’s state.

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, keyspace.read_tx().prefix(&partition, "ab").count());