Skip to main content

redis_tower_commands/
sketch.rs

1//! Count-Min Sketch and Top-K probabilistic data structures.
2//!
3//! Available with the `sketch` feature (included by `stack`) and requiring the
4//! RedisBloom module on the server. Count-Min Sketch updates and queries return
5//! count vectors. Top-K add/increment operations return optional evicted items,
6//! membership queries return booleans, and list/info commands retain raw
7//! [`Frame`] reply shapes.
8//!
9//! ```
10//! use redis_tower_commands::CmsInitByDim;
11//! use redis_tower_core::Command;
12//!
13//! let command = CmsInitByDim::new("frequency", 1000, 5);
14//! assert_eq!(command.name(), "CMS.INITBYDIM");
15//! ```
16//!
17//! See the [command cookbook] for feature and server prerequisites.
18//!
19//! [command cookbook]: https://github.com/joshrotenberg/redis-tower/blob/main/docs/COMMAND-COOKBOOK.md#feature-gated-and-versioned-families
20
21use crate::CommandArg;
22use bytes::Bytes;
23use redis_tower_core::{Command, Frame, RedisError};
24use redis_tower_protocol::helpers::{array, bulk};
25
26// ---------------------------------------------------------------------------
27// Helpers
28// ---------------------------------------------------------------------------
29
30fn parse_i64_array(frame: Frame) -> Result<Vec<i64>, RedisError> {
31    match frame {
32        Frame::Array(Some(frames)) => frames
33            .into_iter()
34            .map(|f| match f {
35                Frame::Integer(n) => Ok(n),
36                other => Err(RedisError::UnexpectedResponse {
37                    expected: "integer",
38                    actual: format!("{other:?}"),
39                }),
40            })
41            .collect(),
42        other => Err(RedisError::UnexpectedResponse {
43            expected: "array",
44            actual: format!("{other:?}"),
45        }),
46    }
47}
48
49fn parse_bool_array(frame: Frame) -> Result<Vec<bool>, RedisError> {
50    match frame {
51        Frame::Array(Some(frames)) => frames
52            .into_iter()
53            .map(|f| match f {
54                Frame::Integer(n) => Ok(n != 0),
55                Frame::Boolean(b) => Ok(b),
56                other => Err(RedisError::UnexpectedResponse {
57                    expected: "integer or boolean",
58                    actual: format!("{other:?}"),
59                }),
60            })
61            .collect(),
62        other => Err(RedisError::UnexpectedResponse {
63            expected: "array",
64            actual: format!("{other:?}"),
65        }),
66    }
67}
68
69fn parse_optional_bytes_array(frame: Frame) -> Result<Vec<Option<Bytes>>, RedisError> {
70    match frame {
71        Frame::Array(Some(frames)) => frames
72            .into_iter()
73            .map(|f| match f {
74                Frame::BulkString(data) => Ok(data),
75                Frame::Null => Ok(None),
76                other => Err(RedisError::UnexpectedResponse {
77                    expected: "bulk string or null",
78                    actual: format!("{other:?}"),
79                }),
80            })
81            .collect(),
82        other => Err(RedisError::UnexpectedResponse {
83            expected: "array",
84            actual: format!("{other:?}"),
85        }),
86    }
87}
88
89// ===========================================================================
90// Count-Min Sketch commands
91// ===========================================================================
92
93/// CMS.INITBYDIM key width depth
94///
95/// Initializes a Count-Min Sketch with the given width and depth.
96#[derive(Clone)]
97pub struct CmsInitByDim {
98    key: CommandArg,
99    width: i64,
100    depth: i64,
101}
102
103impl CmsInitByDim {
104    /// Create a new [`CmsInitByDim`] command.
105    pub fn new(key: impl Into<CommandArg>, width: i64, depth: i64) -> Self {
106        Self {
107            key: key.into(),
108            width,
109            depth,
110        }
111    }
112}
113
114impl Command for CmsInitByDim {
115    type Response = ();
116
117    fn to_frame(&self) -> Frame {
118        array(vec![
119            bulk("CMS.INITBYDIM"),
120            bulk(&self.key),
121            bulk(self.width.to_string()),
122            bulk(self.depth.to_string()),
123        ])
124    }
125
126    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
127        match frame {
128            Frame::SimpleString(s) if &s[..] == b"OK" => Ok(()),
129            other => Err(RedisError::UnexpectedResponse {
130                expected: "OK",
131                actual: format!("{other:?}"),
132            }),
133        }
134    }
135
136    fn name(&self) -> &str {
137        "CMS.INITBYDIM"
138    }
139}
140
141/// CMS.INITBYPROB key error probability
142///
143/// Initializes a Count-Min Sketch with the given error rate and probability.
144#[derive(Clone)]
145pub struct CmsInitByProb {
146    key: CommandArg,
147    error: f64,
148    probability: f64,
149}
150
151impl CmsInitByProb {
152    /// Create a new [`CmsInitByProb`] command.
153    pub fn new(key: impl Into<CommandArg>, error: f64, probability: f64) -> Self {
154        Self {
155            key: key.into(),
156            error,
157            probability,
158        }
159    }
160}
161
162impl Command for CmsInitByProb {
163    type Response = ();
164
165    fn to_frame(&self) -> Frame {
166        array(vec![
167            bulk("CMS.INITBYPROB"),
168            bulk(&self.key),
169            bulk(self.error.to_string()),
170            bulk(self.probability.to_string()),
171        ])
172    }
173
174    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
175        match frame {
176            Frame::SimpleString(s) if &s[..] == b"OK" => Ok(()),
177            other => Err(RedisError::UnexpectedResponse {
178                expected: "OK",
179                actual: format!("{other:?}"),
180            }),
181        }
182    }
183
184    fn name(&self) -> &str {
185        "CMS.INITBYPROB"
186    }
187}
188
189/// CMS.INCRBY key item increment \[item increment ...\]
190///
191/// Increments one or more items in the Count-Min Sketch. Returns the
192/// estimated count for each item after incrementing.
193#[derive(Clone)]
194pub struct CmsIncrBy {
195    key: CommandArg,
196    items: Vec<(CommandArg, i64)>,
197}
198
199impl CmsIncrBy {
200    /// Create a new [`CmsIncrBy`] command.
201    pub fn new(
202        key: impl Into<CommandArg>,
203        items: impl IntoIterator<Item = (impl Into<CommandArg>, i64)>,
204    ) -> Self {
205        Self {
206            key: key.into(),
207            items: items.into_iter().map(|(s, n)| (s.into(), n)).collect(),
208        }
209    }
210}
211
212impl Command for CmsIncrBy {
213    type Response = Vec<i64>;
214
215    fn to_frame(&self) -> Frame {
216        let mut args = vec![bulk("CMS.INCRBY"), bulk(&self.key)];
217        for (item, incr) in &self.items {
218            args.push(bulk(item));
219            args.push(bulk(incr.to_string()));
220        }
221        array(args)
222    }
223
224    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
225        parse_i64_array(frame)
226    }
227
228    fn name(&self) -> &str {
229        "CMS.INCRBY"
230    }
231}
232
233/// CMS.QUERY key item \[item ...\]
234///
235/// Returns the estimated count for one or more items in the Count-Min Sketch.
236#[derive(Clone)]
237pub struct CmsQuery {
238    key: CommandArg,
239    items: Vec<CommandArg>,
240}
241
242impl CmsQuery {
243    /// Create a new [`CmsQuery`] command.
244    pub fn new(
245        key: impl Into<CommandArg>,
246        items: impl IntoIterator<Item = impl Into<CommandArg>>,
247    ) -> Self {
248        Self {
249            key: key.into(),
250            items: items.into_iter().map(Into::into).collect(),
251        }
252    }
253}
254
255impl Command for CmsQuery {
256    type Response = Vec<i64>;
257
258    fn to_frame(&self) -> Frame {
259        let mut args = vec![bulk("CMS.QUERY"), bulk(&self.key)];
260        for item in &self.items {
261            args.push(bulk(item));
262        }
263        array(args)
264    }
265
266    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
267        parse_i64_array(frame)
268    }
269
270    fn name(&self) -> &str {
271        "CMS.QUERY"
272    }
273
274    fn idempotent(&self) -> bool {
275        true
276    }
277}
278
279/// CMS.MERGE destination numkeys source \[source ...\] \[WEIGHTS weight ...\]
280///
281/// Merges several Count-Min Sketches into a destination sketch.
282#[derive(Clone)]
283pub struct CmsMerge {
284    destination: CommandArg,
285    sources: Vec<CommandArg>,
286    weights: Vec<i64>,
287}
288
289impl CmsMerge {
290    /// Create a new [`CmsMerge`] command.
291    pub fn new(
292        destination: impl Into<CommandArg>,
293        sources: impl IntoIterator<Item = impl Into<CommandArg>>,
294    ) -> Self {
295        Self {
296            destination: destination.into(),
297            sources: sources.into_iter().map(Into::into).collect(),
298            weights: Vec::new(),
299        }
300    }
301
302    /// Set weights for the source sketches.
303    pub fn weights(mut self, weights: impl IntoIterator<Item = i64>) -> Self {
304        self.weights = weights.into_iter().collect();
305        self
306    }
307}
308
309impl Command for CmsMerge {
310    type Response = ();
311
312    fn to_frame(&self) -> Frame {
313        let mut args = vec![
314            bulk("CMS.MERGE"),
315            bulk(&self.destination),
316            bulk(self.sources.len().to_string()),
317        ];
318        for src in &self.sources {
319            args.push(bulk(src));
320        }
321        if !self.weights.is_empty() {
322            args.push(bulk("WEIGHTS"));
323            for w in &self.weights {
324                args.push(bulk(w.to_string()));
325            }
326        }
327        array(args)
328    }
329
330    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
331        match frame {
332            Frame::SimpleString(s) if &s[..] == b"OK" => Ok(()),
333            other => Err(RedisError::UnexpectedResponse {
334                expected: "OK",
335                actual: format!("{other:?}"),
336            }),
337        }
338    }
339
340    fn name(&self) -> &str {
341        "CMS.MERGE"
342    }
343}
344
345/// CMS.INFO key
346///
347/// Returns information about the Count-Min Sketch at `key` as a raw Frame.
348#[derive(Clone)]
349pub struct CmsInfo {
350    key: CommandArg,
351}
352
353impl CmsInfo {
354    /// Create a new [`CmsInfo`] command.
355    pub fn new(key: impl Into<CommandArg>) -> Self {
356        Self { key: key.into() }
357    }
358}
359
360impl Command for CmsInfo {
361    type Response = Frame;
362
363    fn to_frame(&self) -> Frame {
364        array(vec![bulk("CMS.INFO"), bulk(&self.key)])
365    }
366
367    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
368        Ok(frame)
369    }
370
371    fn name(&self) -> &str {
372        "CMS.INFO"
373    }
374
375    fn idempotent(&self) -> bool {
376        true
377    }
378}
379
380// ===========================================================================
381// Top-K commands
382// ===========================================================================
383
384/// TOPK.RESERVE key topk \[width depth decay\]
385///
386/// Initializes a Top-K data structure with the given parameters.
387#[derive(Clone)]
388pub struct TopkReserve {
389    key: CommandArg,
390    topk: i64,
391    width: Option<i64>,
392    depth: Option<i64>,
393    decay: Option<f64>,
394}
395
396impl TopkReserve {
397    /// Create a new [`TopkReserve`] command.
398    pub fn new(key: impl Into<CommandArg>, topk: i64) -> Self {
399        Self {
400            key: key.into(),
401            topk,
402            width: None,
403            depth: None,
404            decay: None,
405        }
406    }
407
408    /// Set the width, depth, and decay parameters.
409    pub fn params(mut self, width: i64, depth: i64, decay: f64) -> Self {
410        self.width = Some(width);
411        self.depth = Some(depth);
412        self.decay = Some(decay);
413        self
414    }
415}
416
417impl Command for TopkReserve {
418    type Response = ();
419
420    fn to_frame(&self) -> Frame {
421        let mut args = vec![
422            bulk("TOPK.RESERVE"),
423            bulk(&self.key),
424            bulk(self.topk.to_string()),
425        ];
426        if let (Some(w), Some(d), Some(decay)) = (self.width, self.depth, self.decay) {
427            args.push(bulk(w.to_string()));
428            args.push(bulk(d.to_string()));
429            args.push(bulk(decay.to_string()));
430        }
431        array(args)
432    }
433
434    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
435        match frame {
436            Frame::SimpleString(s) if &s[..] == b"OK" => Ok(()),
437            other => Err(RedisError::UnexpectedResponse {
438                expected: "OK",
439                actual: format!("{other:?}"),
440            }),
441        }
442    }
443
444    fn name(&self) -> &str {
445        "TOPK.RESERVE"
446    }
447}
448
449/// TOPK.ADD key item \[item ...\]
450///
451/// Adds one or more items to the Top-K. Returns a vector of evicted items
452/// (or None for items that did not cause an eviction).
453#[derive(Clone)]
454pub struct TopkAdd {
455    key: CommandArg,
456    items: Vec<CommandArg>,
457}
458
459impl TopkAdd {
460    /// Create a new [`TopkAdd`] command.
461    pub fn new(
462        key: impl Into<CommandArg>,
463        items: impl IntoIterator<Item = impl Into<CommandArg>>,
464    ) -> Self {
465        Self {
466            key: key.into(),
467            items: items.into_iter().map(Into::into).collect(),
468        }
469    }
470}
471
472impl Command for TopkAdd {
473    type Response = Vec<Option<Bytes>>;
474
475    fn to_frame(&self) -> Frame {
476        let mut args = vec![bulk("TOPK.ADD"), bulk(&self.key)];
477        for item in &self.items {
478            args.push(bulk(item));
479        }
480        array(args)
481    }
482
483    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
484        parse_optional_bytes_array(frame)
485    }
486
487    fn name(&self) -> &str {
488        "TOPK.ADD"
489    }
490}
491
492/// TOPK.INCRBY key item increment \[item increment ...\]
493///
494/// Increments the score of one or more items in the Top-K. Returns a vector
495/// of evicted items (or None for items that did not cause an eviction).
496#[derive(Clone)]
497pub struct TopkIncrBy {
498    key: CommandArg,
499    items: Vec<(CommandArg, i64)>,
500}
501
502impl TopkIncrBy {
503    /// Create a new [`TopkIncrBy`] command.
504    pub fn new(
505        key: impl Into<CommandArg>,
506        items: impl IntoIterator<Item = (impl Into<CommandArg>, i64)>,
507    ) -> Self {
508        Self {
509            key: key.into(),
510            items: items.into_iter().map(|(s, n)| (s.into(), n)).collect(),
511        }
512    }
513}
514
515impl Command for TopkIncrBy {
516    type Response = Vec<Option<Bytes>>;
517
518    fn to_frame(&self) -> Frame {
519        let mut args = vec![bulk("TOPK.INCRBY"), bulk(&self.key)];
520        for (item, incr) in &self.items {
521            args.push(bulk(item));
522            args.push(bulk(incr.to_string()));
523        }
524        array(args)
525    }
526
527    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
528        parse_optional_bytes_array(frame)
529    }
530
531    fn name(&self) -> &str {
532        "TOPK.INCRBY"
533    }
534}
535
536/// TOPK.QUERY key item \[item ...\]
537///
538/// Checks whether one or more items are in the Top-K.
539#[derive(Clone)]
540pub struct TopkQuery {
541    key: CommandArg,
542    items: Vec<CommandArg>,
543}
544
545impl TopkQuery {
546    /// Create a new [`TopkQuery`] command.
547    pub fn new(
548        key: impl Into<CommandArg>,
549        items: impl IntoIterator<Item = impl Into<CommandArg>>,
550    ) -> Self {
551        Self {
552            key: key.into(),
553            items: items.into_iter().map(Into::into).collect(),
554        }
555    }
556}
557
558impl Command for TopkQuery {
559    type Response = Vec<bool>;
560
561    fn to_frame(&self) -> Frame {
562        let mut args = vec![bulk("TOPK.QUERY"), bulk(&self.key)];
563        for item in &self.items {
564            args.push(bulk(item));
565        }
566        array(args)
567    }
568
569    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
570        parse_bool_array(frame)
571    }
572
573    fn name(&self) -> &str {
574        "TOPK.QUERY"
575    }
576
577    fn idempotent(&self) -> bool {
578        true
579    }
580}
581
582/// TOPK.COUNT key item \[item ...\]
583///
584/// Returns the approximate count for one or more items in the Top-K.
585#[derive(Clone)]
586pub struct TopkCount {
587    key: CommandArg,
588    items: Vec<CommandArg>,
589}
590
591impl TopkCount {
592    /// Create a new [`TopkCount`] command.
593    pub fn new(
594        key: impl Into<CommandArg>,
595        items: impl IntoIterator<Item = impl Into<CommandArg>>,
596    ) -> Self {
597        Self {
598            key: key.into(),
599            items: items.into_iter().map(Into::into).collect(),
600        }
601    }
602}
603
604impl Command for TopkCount {
605    type Response = Vec<i64>;
606
607    fn to_frame(&self) -> Frame {
608        let mut args = vec![bulk("TOPK.COUNT"), bulk(&self.key)];
609        for item in &self.items {
610            args.push(bulk(item));
611        }
612        array(args)
613    }
614
615    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
616        parse_i64_array(frame)
617    }
618
619    fn name(&self) -> &str {
620        "TOPK.COUNT"
621    }
622
623    fn idempotent(&self) -> bool {
624        true
625    }
626}
627
628/// TOPK.LIST key \[WITHCOUNT\]
629///
630/// Returns the list of top-k items. When called with WITHCOUNT, the response
631/// includes counts interleaved with items, returned as a raw Frame.
632#[derive(Clone)]
633pub struct TopkList {
634    key: CommandArg,
635    withcount: bool,
636}
637
638impl TopkList {
639    /// Create a new [`TopkList`] command.
640    pub fn new(key: impl Into<CommandArg>) -> Self {
641        Self {
642            key: key.into(),
643            withcount: false,
644        }
645    }
646
647    /// Include counts in the response.
648    pub fn withcount(mut self) -> Self {
649        self.withcount = true;
650        self
651    }
652}
653
654impl Command for TopkList {
655    type Response = Frame;
656
657    fn to_frame(&self) -> Frame {
658        let mut args = vec![bulk("TOPK.LIST"), bulk(&self.key)];
659        if self.withcount {
660            args.push(bulk("WITHCOUNT"));
661        }
662        array(args)
663    }
664
665    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
666        Ok(frame)
667    }
668
669    fn name(&self) -> &str {
670        "TOPK.LIST"
671    }
672
673    fn idempotent(&self) -> bool {
674        true
675    }
676}
677
678/// TOPK.INFO key
679///
680/// Returns information about the Top-K at `key` as a raw Frame.
681#[derive(Clone)]
682pub struct TopkInfo {
683    key: CommandArg,
684}
685
686impl TopkInfo {
687    /// Create a new [`TopkInfo`] command.
688    pub fn new(key: impl Into<CommandArg>) -> Self {
689        Self { key: key.into() }
690    }
691}
692
693impl Command for TopkInfo {
694    type Response = Frame;
695
696    fn to_frame(&self) -> Frame {
697        array(vec![bulk("TOPK.INFO"), bulk(&self.key)])
698    }
699
700    fn parse_response(&self, frame: Frame) -> Result<Self::Response, RedisError> {
701        Ok(frame)
702    }
703
704    fn name(&self) -> &str {
705        "TOPK.INFO"
706    }
707
708    fn idempotent(&self) -> bool {
709        true
710    }
711}
712
713#[cfg(test)]
714mod tests {
715    use super::*;
716    use redis_tower_core::Command;
717
718    #[test]
719    fn idempotency_flags() {
720        // Read-only commands are safe to retry.
721        assert!(CmsQuery::new("k", ["i"]).idempotent());
722        // Mutating commands keep the default (false).
723        assert!(!CmsIncrBy::new("k", [("i", 1)]).idempotent());
724    }
725}