rustis::commands

Trait CuckooCommands

Source 
pub trait CuckooCommands<'a> {
    // Provided methods
    fn cf_add(
        self,
        key: impl SingleArg,
        item: impl SingleArg,
    ) -> PreparedCommand<'a, Self, ()>
       where Self: Sized { ... }
    fn cf_addnx(
        self,
        key: impl SingleArg,
        item: impl SingleArg,
    ) -> PreparedCommand<'a, Self, bool>
       where Self: Sized { ... }
    fn cf_count(
        self,
        key: impl SingleArg,
        item: impl SingleArg,
    ) -> PreparedCommand<'a, Self, usize>
       where Self: Sized { ... }
    fn cf_del(
        self,
        key: impl SingleArg,
        item: impl SingleArg,
    ) -> PreparedCommand<'a, Self, bool>
       where Self: Sized { ... }
    fn cf_exists(
        self,
        key: impl SingleArg,
        item: impl SingleArg,
    ) -> PreparedCommand<'a, Self, bool>
       where Self: Sized { ... }
    fn cf_info(
        self,
        key: impl SingleArg,
    ) -> PreparedCommand<'a, Self, CfInfoResult>
       where Self: Sized { ... }
    fn cf_insert<I: SingleArg>(
        self,
        key: impl SingleArg,
        options: CfInsertOptions,
        item: impl SingleArgCollection<I>,
    ) -> PreparedCommand<'a, Self, Vec<usize>>
       where Self: Sized { ... }
    fn cf_insertnx<I: SingleArg, R: CollectionResponse<i64>>(
        self,
        key: impl SingleArg,
        options: CfInsertOptions,
        item: impl SingleArgCollection<I>,
    ) -> PreparedCommand<'a, Self, R>
       where Self: Sized { ... }
    fn cf_loadchunk(
        self,
        key: impl SingleArg,
        iterator: i64,
        data: impl SingleArg,
    ) -> PreparedCommand<'a, Self, ()>
       where Self: Sized { ... }
    fn cf_mexists<I: SingleArg, R: CollectionResponse<bool>>(
        self,
        key: impl SingleArg,
        items: impl SingleArgCollection<I>,
    ) -> PreparedCommand<'a, Self, R>
       where Self: Sized { ... }
    fn cf_reserve(
        self,
        key: impl SingleArg,
        capacity: usize,
        options: CfReserveOptions,
    ) -> PreparedCommand<'a, Self, ()>
       where Self: Sized { ... }
    fn cf_scandump(
        self,
        key: impl SingleArg,
        iterator: i64,
    ) -> PreparedCommand<'a, Self, CfScanDumpResult>
       where Self: Sized { ... }
}
Available on crate feature redis-bloom only.
Expand description

A group of Redis commands related to Cuckoo filters

§See Also

Cuckoo Filter Commands

Provided Methods§

Source

fn cf_add( self, key: impl SingleArg, item: impl SingleArg, ) -> PreparedCommand<'a, Self, ()>
where Self: Sized,

Adds an item to the cuckoo filter, creating the filter if it does not exist.

Cuckoo filters can contain the same item multiple times, and consider each insert as separate. You can use cf_addnx to only add the item if it does not exist yet. Keep in mind that deleting an element inserted using cf_addnx may cause false-negative errors.

§Arguments
  • key - The name of the filter
  • item - The item to add
§See Also
Source

fn cf_addnx( self, key: impl SingleArg, item: impl SingleArg, ) -> PreparedCommand<'a, Self, bool>
where Self: Sized,

Adds an item to a cuckoo filter if the item did not exist previously.

See documentation on cf_add for more information on this command.

This command is equivalent to a cf_exists + cf_add command. It does not insert an element into the filter if its fingerprint already exists in order to use the available capacity more efficiently. However, deleting elements can introduce false negative error rate!

Note that this command is slower than cf_add because it first checks whether the item exists.

§Arguments
  • key - The name of the filter
  • item - The item to add
§Return
  • true - if the item did not exist in the filter.
  • false - if the item already existed.
§See Also
Source

fn cf_count( self, key: impl SingleArg, item: impl SingleArg, ) -> PreparedCommand<'a, Self, usize>
where Self: Sized,

Returns the number of times an item may be in the filter.

Because this is a probabilistic data structure, this may not necessarily be accurate.

If you just want to know if an item exists in the filter, use cf_exists because it is more efficient for that purpose.

§Arguments
  • key - The name of the filter
  • item - The item to count
§Return

the count of possible matching copies of the item in the filter.

§See Also
Source

fn cf_del( self, key: impl SingleArg, item: impl SingleArg, ) -> PreparedCommand<'a, Self, bool>
where Self: Sized,

Deletes an item once from the filter.

If the item exists only once, it will be removed from the filter. If the item was added multiple times, it will still be present.

§Danger !

Deleting elements that are not in the filter may delete a different item, resulting in false negatives!

§Arguments
  • key - The name of the filter
  • item - The item to delete from the filter
§Complexity

O(n), where n is the number of sub-filters. Both alternative locations are checked on all sub-filters.

§Return
  • true - the item has been deleted from the filter.
  • false - if the item was not found.
§See Also
Source

fn cf_exists( self, key: impl SingleArg, item: impl SingleArg, ) -> PreparedCommand<'a, Self, bool>
where Self: Sized,

Check if an item exists in a Cuckoo Filter key

§Arguments
  • key - The name of the filter
  • item - The item to check for
§Return
  • true - the item may exist in the filter
  • false - if the item does not exist in the filter.
§See Also
Source

fn cf_info(self, key: impl SingleArg) -> PreparedCommand<'a, Self, CfInfoResult>
where Self: Sized,

Return information about key

§Arguments
  • key - Name of the key to get info about
§Return

An instance of CfInfoResult

§See Also
Source

fn cf_insert<I: SingleArg>( self, key: impl SingleArg, options: CfInsertOptions, item: impl SingleArgCollection<I>, ) -> PreparedCommand<'a, Self, Vec<usize>>
where Self: Sized,

Adds one or more items to a cuckoo filter, allowing the filter to be created with a custom capacity if it does not exist yet.

These commands offers more flexibility over the cf_add command, at the cost of more verbosity.

§Arguments
  • key - The name of the filter
  • options - see CfInsertOptions
  • items - One or more items to add.
§See Also
Source

fn cf_insertnx<I: SingleArg, R: CollectionResponse<i64>>( self, key: impl SingleArg, options: CfInsertOptions, item: impl SingleArgCollection<I>, ) -> PreparedCommand<'a, Self, R>
where Self: Sized,

Adds one or more items to a cuckoo filter, allowing the filter to be created with a custom capacity if it does not exist yet.

This command is equivalent to a cf_exists + cf_add command. It does not insert an element into the filter if its fingerprint already exists and therefore better utilizes the available capacity. However, if you delete elements it might introduce false negative error rate!

These commands offers more flexibility over the cf_add and cf_addnx commands, at the cost of more verbosity.

§Complexity

O(n + i), where n is the number of sub-filters and i is maxIterations. Adding items requires up to 2 memory accesses per sub-filter. But as the filter fills up, both locations for an item might be full. The filter attempts to Cuckoo swap items up to maxIterations times.

§Arguments
  • key - The name of the filter
  • options - see CfInsertOptions
  • items - One or more items to add.
§Return

A collection of integers corresponding to the items specified. Possible values for each element are:

  • >0 - if the item was successfully inserted
  • 0 - if the item already existed and cf_insertnx is used.
  • <0 - if an error occurred
§See Also
Source

fn cf_loadchunk( self, key: impl SingleArg, iterator: i64, data: impl SingleArg, ) -> PreparedCommand<'a, Self, ()>
where Self: Sized,

Restores a filter previously saved using cf_scandump.

See the cf_scandump command for example usage.

This command overwrites any bloom filter stored under key. Make sure that the bloom filter is not be changed between invocations.

§Arguments
  • key - Name of the key to restore
  • iterator - Iterator value associated with data (returned by cf_scandump)
  • data - Current data chunk (returned by cf_scandump)
§See Also

https://redis.io/commands/cf.loadchunk/

Source

fn cf_mexists<I: SingleArg, R: CollectionResponse<bool>>( self, key: impl SingleArg, items: impl SingleArgCollection<I>, ) -> PreparedCommand<'a, Self, R>
where Self: Sized,

Check if one or more items exists in a Cuckoo Filter key

§Arguments
  • key - The name of the filter
  • items - One or more items to check for
§Return

Collection reply of boolean - for each item where true value means the corresponding item may exist in the filter, and a false value means it does not exist in the filter.

§See Also

https://redis.io/commands/cf.mexists/

Source

fn cf_reserve( self, key: impl SingleArg, capacity: usize, options: CfReserveOptions, ) -> PreparedCommand<'a, Self, ()>
where Self: Sized,

Create a Cuckoo Filter as key with a single sub-filter for the initial amount of capacity for items. Because of how Cuckoo Filters work, the filter is likely to declare itself full before capacity is reached and therefore fill rate will likely never reach 100%. The fill rate can be improved by using a larger bucketsize at the cost of a higher error rate. When the filter self-declare itself full, it will auto-expand by generating additional sub-filters at the cost of reduced performance and increased error rate. The new sub-filter is created with size of the previous sub-filter multiplied by expansion. Like bucket size, additional sub-filters grow the error rate linearly. The size of the new sub-filter is the size of the last sub-filter multiplied by expansion.

The minimal false positive error rate is 2/255 ≈ 0.78% when bucket size of 1 is used. Larger buckets increase the error rate linearly (for example, a bucket size of 3 yields a 2.35% error rate) but improve the fill rate of the filter.

maxiterations dictates the number of attempts to find a slot for the incoming fingerprint. Once the filter gets full, high maxIterations value will slow down insertions.

Unused capacity in prior sub-filters is automatically used when possible. The filter can grow up to 32 times.

§Arguments
  • key - The key under which the filter is found
  • capacity - Estimated capacity for the filter. Capacity is rounded to the next 2^n number. The filter will likely not fill up to 100% of it’s capacity. Make sure to reserve extra capacity if you want to avoid expansions.
  • options - See CfReserveOptions
§See Also

https://redis.io/commands/cf.reserve/

Source

fn cf_scandump( self, key: impl SingleArg, iterator: i64, ) -> PreparedCommand<'a, Self, CfScanDumpResult>
where Self: Sized,

Begins an incremental save of the cuckoo filter. This is useful for large cuckoo filters which cannot fit into the normal dump and restore model.

§Arguments
  • key - Name of the filter
  • iterator - Iterator value; either 0 or the iterator from a previous invocation of this command.
    The first time this command is called, the value of iterator should be 0.
§Return

This command returns successive (iterator, data) pairs until (0, vec![]) to indicate completion.

§See Also

https://redis.io/commands/cf.scandump/

Implementors§

Source§

impl<'a> CuckooCommands<'a> for &'a Client

Source§

impl<'a> CuckooCommands<'a> for &'a mut Transaction

Source§

impl<'a, 'b> CuckooCommands<'a> for &'a mut Pipeline<'b>