Struct fuzzy_rocks::Table

pub struct Table<ConfigT: TableConfig, const UTF8_KEYS: bool> { /* private fields */ }

A collection containing records that may be searched using Keys

IMPLEMENTATION NOTE: Currently Rust doesn’t let us bound an impl by an associated constant. In other words the bound ConfigT : TableConfig<UTF8_KEYS = true> won’t work, and we need to reflect the UTF8_KEYS associated constant as a const generic parameter on Table. This is tracked by https://github.com/rust-lang/rust/issues/70256

When the following Rust language issues are resolved, I will remove the UTF8_KEYS generic constant from Table

• https://github.com/rust-lang/rust/issues/44580
• https://github.com/rust-lang/rust/issues/70256
• https://github.com/rust-lang/rust/issues/76560

In the meantime, the UTF8_KEYS generic constant set for the table must match the value in the config parameter.

Implementations

impl<OwnedKeyT, ConfigT: TableConfig, const UTF8_KEYS: bool> Table<ConfigT, UTF8_KEYS>

where ConfigT::KeyCharT: 'static + Copy + PartialEq + Serialize + DeserializeOwned, ConfigT::DistanceT: 'static + Copy + Zero + PartialOrd + PartialEq + From<u8>, ConfigT::ValueT: 'static + Serialize + DeserializeOwned, OwnedKeyT: OwnedKey<KeyCharT = ConfigT::KeyCharT>, Self: TableKeyEncoding<OwnedKeyT = OwnedKeyT>,

The implementation of the shared parts of Table, that are the same regardless of UTF8_KEYS

pub fn new(path: &str, config: ConfigT) -> Result<Self, String>

Creates a new Table, backed by the database at the path provided

WARNING: No sanity checks are performed to ensure the database being opened matches the parameters of the table being created. Therefore you may see bugs if you are opening a table that was created using a different set of parameters.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn reset(&mut self) -> Result<(), String>

Resets a Table, dropping every record in the table and restoring it to an empty state.

(Dropping in a database sense, not a Rust sense)

pub fn delete(&mut self, record_id: RecordID) -> Result<(), String>

Deletes a record from the Table.

A deleted record cannot be accessed or otherwise found. All of the record’s associated keys and the associated value may be purged from the database.

pub fn replace_value( &mut self, record_id: RecordID, value: &ConfigT::ValueT ) -> Result<ConfigT::ValueT, String>

Replaces a record’s value with the supplied value. Returns the value that was replaced

The supplied record_id must references an existing record that has not been deleted.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get_value(&self, record_id: RecordID) -> Result<ConfigT::ValueT, String>

Returns the value associated with the specified record

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn keys_count(&self, record_id: RecordID) -> Result<usize, String>

Returns the number of keys associated with a specified record

pub fn reset_perf_counters(&self)

Resets all values in the performance counters, so the information returned by get_perf_counters only reflects activity since the last call to reset_perf_counters

pub fn get_perf_counters(&self) -> PerfCounterFields

Returns the values in the performance counters, which should reflect all activity since the previous call to reset_perf_counters

impl<ConfigT: TableConfig<KeyCharT = char>> Table<ConfigT, true>

pub fn insert<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = char>>( &mut self, key: K, value: &ConfigT::ValueT ) -> Result<RecordID, String>

Inserts a new key-value pair into the table and returns the RecordID of the new record

This is a high-level interface to be used if multiple keys are not needed, but is functions the same as create

NOTE: Inserting the same key into a Table multiple times will result in multiple distinct records, and all of the records will be found by lookups of that key.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get( &self, record_id: RecordID ) -> Result<(String, ConfigT::ValueT), String>

Retrieves a key-value pair using a RecordID

This is a high-level interface to be used if multiple keys are not needed, but is functions the same as get_one_key / get_value

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn create<K: Key<KeyCharT = char>>( &mut self, keys: &[K], value: &ConfigT::ValueT ) -> Result<RecordID, String>

Creates a new record in the table and returns the RecordID of the new record

This function will always create a new record, regardless of whether an identical key exists. It is permissible to have two distinct records with identical keys.

NOTE: This function takes an &T for value rather than an owned T because it must make an internal copy regardless of passed ownership, so requiring an owned object would ofter result in a redundant copy. However this is different from most containers, and makes things feel awkward when using String types for values.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn add_keys<K: Key<KeyCharT = char>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Adds the supplied keys to the record’s keys

The supplied record_id must references an existing record that has not been deleted.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn remove_keys<K: Key<KeyCharT = char>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Removes the supplied keys from the keys associated with a record

If one of the specified keys is not associated with the record then that specified key will be ignored.

If removing the keys would result in a record with no keys, this operation will return an error and no keys will be removed, because all records must have at least one key.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn replace_keys<K: Key<KeyCharT = char>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Replaces a record’s keys with the supplied keys

The supplied record_id must references an existing record that has not been deleted.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get_keys( &self, record_id: RecordID ) -> Result<impl Iterator<Item = String> + '_, String>

Returns an iterator over all of the key associated with the specified record

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get_one_key(&self, record_id: RecordID) -> Result<String, String>

Returns one key associated with the specified record. If the record has more than one key then which key is unspecified

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_exact<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = char>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates all records in the table with keys that precisely match the key supplied

BUG!!: In some cases, this function will return records that have keys that contain the key searched. For example, the search key “london” may return a record associated with the key “londonia”. We may opt to keep this functionality as a separate function as its performance is better than as loading the exact keys for all records is significant overhead.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_fuzzy_raw<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = char>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates all records in the table with a key that is within a deletion distance of [config.max_deletes] of the key supplied, based on the SymSpell algorithm.

This function underlies all fuzzy lookups, and does no further filtering based on any distance function.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_fuzzy<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = char>>( &self, key: K, threshold: Option<ConfigT::DistanceT> ) -> Result<impl Iterator<Item = (RecordID, ConfigT::DistanceT)>, String>

Locates all records in the table for which the Table’s DISTANCE_FUNCTION(TableConfig::DISTANCE_FUNCTION) evaluates to a result smaller than the supplied threshold when comparing the record’s key with the supplied key

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_best<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = char>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates the record in the table for which the Table’s DISTANCE_FUNCTION(TableConfig::DISTANCE_FUNCTION) evaluates to the lowest value when comparing the record’s key with the supplied key.

If no matching record is found within the table’s config.max_deletes, this method will return an error.

NOTE: If two or more results have the same returned distance value and that is the smallest value, the implementation does not specify which result will be returned.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

impl<ConfigT: TableConfig> Table<ConfigT, false>

pub fn insert<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = ConfigT::KeyCharT>>( &mut self, key: K, value: &ConfigT::ValueT ) -> Result<RecordID, String>

Inserts a new key-value pair into the table and returns the RecordID of the new record

This is a high-level interface to be used if multiple keys are not needed, but is functions the same as create

NOTE: Inserting the same key into a Table multiple times will result in multiple distinct records, and all of the records will be found by lookups of that key.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get( &self, record_id: RecordID ) -> Result<(Vec<ConfigT::KeyCharT>, ConfigT::ValueT), String>

Retrieves a key-value pair using a RecordID

This is a high-level interface to be used if multiple keys are not needed, but is functions the same as get_one_key / get_value

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn create<K: Key<KeyCharT = ConfigT::KeyCharT>>( &mut self, keys: &[K], value: &ConfigT::ValueT ) -> Result<RecordID, String>

Creates a new record in the table and returns the RecordID of the new record

This function will always create a new record, regardless of whether an identical key exists. It is permissible to have two distinct records with identical keys.

NOTE: This function takes an &T for value rather than an owned T because it must make an internal copy regardless of passed ownership, so requiring an owned object would ofter result in a redundant copy. However this is different from most containers, and makes things feel awkward when using String types for values.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn add_keys<K: Key<KeyCharT = ConfigT::KeyCharT>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Adds the supplied keys to the record’s keys

The supplied record_id must references an existing record that has not been deleted.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn remove_keys<K: Key<KeyCharT = ConfigT::KeyCharT>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Removes the supplied keys from the keys associated with a record

If one of the specified keys is not associated with the record then that specified key will be ignored.

If removing the keys would result in a record with no keys, this operation will return an error and no keys will be removed, because all records must have at least one key.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn replace_keys<K: Key<KeyCharT = ConfigT::KeyCharT>>( &mut self, record_id: RecordID, keys: &[K] ) -> Result<(), String>

Replaces a record’s keys with the supplied keys

The supplied record_id must references an existing record that has not been deleted.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get_keys( &self, record_id: RecordID ) -> Result<impl Iterator<Item = Vec<ConfigT::KeyCharT>> + '_, String>

Returns an iterator over all of the key associated with the specified record

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn get_one_key( &self, record_id: RecordID ) -> Result<Vec<ConfigT::KeyCharT>, String>

Returns one key associated with the specified record. If the record has more than one key then which key is unspecified

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_exact<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = ConfigT::KeyCharT>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates all records in the table with keys that precisely match the key supplied

BUG!!: In some cases, this function will return records that have keys that contain the key searched. For example, the search key “london” may return a record associated with the key “londonia”. We may opt to keep this functionality as a separate function as its performance is better than as loading the exact keys for all records is significant overhead.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_fuzzy_raw<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = ConfigT::KeyCharT>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates all records in the table with a key that is within a deletion distance of config.max_deletes of the key supplied, based on the SymSpell algorithm.

This function underlies all fuzzy lookups, and does no further filtering based on any distance function.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_fuzzy<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = ConfigT::KeyCharT>>( &self, key: K, threshold: Option<ConfigT::DistanceT> ) -> Result<impl Iterator<Item = (RecordID, ConfigT::DistanceT)>, String>

Locates all records in the table for which the Table’s DISTANCE_FUNCTION(TableConfig::DISTANCE_FUNCTION) evaluates to a result smaller than the supplied threshold when comparing the record’s key with the supplied key

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.

pub fn lookup_best<K: IntoKey<Key = KeyT>, KeyT: Key<KeyCharT = ConfigT::KeyCharT>>( &self, key: K ) -> Result<impl Iterator<Item = RecordID>, String>

Locates the record in the table for which the Table’s DISTANCE_FUNCTION(TableConfig::DISTANCE_FUNCTION) evaluates to the lowest value when comparing the record’s key with the supplied key.

If no matching record is found within the table’s config.max_deletes, this method will return an error.

NOTE: If two or more results have the same returned distance value and that is the smallest value, the implementation does not specify which result will be returned.

NOTE: rocksdb::Error is a wrapper around a string, so if an error occurs it will be the unwrapped RocksDB error.