diff --git a/docs/command-reference/compatibility.md b/docs/command-reference/compatibility.md index 86d5a300..b65a6327 100644 --- a/docs/command-reference/compatibility.md +++ b/docs/command-reference/compatibility.md @@ -314,12 +314,12 @@ sidebar_position: 0 | | BF.LOADCHUNK | Unsupported | | | BF.INFO | Unsupported | | Cuckoo Filter | TBD | Unsupported | -| Count-Min Sketch | CMS.INCRBY | Unsupported | -| | CMS.INFO | Unsupported | -| | CMS.INITBYDIM | Unsupported | -| | CMS.INITBYPROB | Unsupported | -| | CMS.MERGE | Unsupported | -| | CMS.QUERY | Unsupported | +| Count-Min Sketch | CMS.INCRBY | Fully supported | +| | CMS.INFO | Fully supported | +| | CMS.INITBYDIM | Fully supported | +| | CMS.INITBYPROB | Fully supported | +| | CMS.MERGE | Fully supported | +| | CMS.QUERY | Fully supported | | Graph | Not supported | Unsupported | | JSON | JSON.ARRAPPEND | Fully supported | | | JSON.ARRINDEX | Fully supported | diff --git a/docs/command-reference/count-min-sketch/_category_.yml b/docs/command-reference/count-min-sketch/_category_.yml new file mode 100644 index 00000000..1af571b1 --- /dev/null +++ b/docs/command-reference/count-min-sketch/_category_.yml @@ -0,0 +1,4 @@ +position: 1 +label: Count-Min Sketch +link: + type: generated-index diff --git a/docs/command-reference/count-min-sketch/cms.incrby.md b/docs/command-reference/count-min-sketch/cms.incrby.md new file mode 100644 index 00000000..70b8de01 --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.incrby.md @@ -0,0 +1,43 @@ +--- +description: Learn how to use the CMS.INCRBY command to increment the count of one or more items in a Count-Min Sketch. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.INCRBY + + + +## Syntax + + CMS.INCRBY key item increment [item increment ...] + +**Time complexity:** O(n) where n is the number of items + +**ACL categories:** @cms + +Increments the count of one or more `item`s in the Count-Min Sketch stored at `key` by the given `increment` values. +The `increment` value must be a positive integer greater than `0`. +If `key` does not exist, an error is returned. + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays): An array of integers, one per item, representing the estimated count of each item after the increment. + +## Examples + +```shell +dragonfly> CMS.INITBYDIM cms_key 2000 5 +OK + +dragonfly> CMS.INCRBY cms_key item1 1 item2 5 +1) (integer) 1 +2) (integer) 5 + +dragonfly> CMS.INCRBY cms_key item1 10 +1) (integer) 11 +``` + +## See also + +[`CMS.INITBYDIM`](./cms.initbydim.md) | [`CMS.INITBYPROB`](./cms.initbyprob.md) | [`CMS.QUERY`](./cms.query.md) | [`CMS.MERGE`](./cms.merge.md) diff --git a/docs/command-reference/count-min-sketch/cms.info.md b/docs/command-reference/count-min-sketch/cms.info.md new file mode 100644 index 00000000..8f2c65ed --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.info.md @@ -0,0 +1,50 @@ +--- +description: Learn how to use the CMS.INFO command to retrieve information about a Count-Min Sketch. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.INFO + + + +## Syntax + + CMS.INFO key + +**Time complexity:** O(1) + +**ACL categories:** @cms + +Returns metadata about the Count-Min Sketch stored at `key`, including its dimensions and the total number of counted events. + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays): A flat array of field-value pairs with the following fields: + +- `width`: The number of counters in each row. +- `depth`: The number of hash functions / rows. +- `count`: The total sum of all increments applied to the sketch. + +## Examples + +```shell +dragonfly> CMS.INITBYDIM cms_key 2000 5 +OK + +dragonfly> CMS.INCRBY cms_key item1 10 item2 3 +1) (integer) 10 +2) (integer) 3 + +dragonfly> CMS.INFO cms_key +1) width +2) (integer) 2000 +3) depth +4) (integer) 5 +5) count +6) (integer) 13 +``` + +## See also + +[`CMS.INITBYDIM`](./cms.initbydim.md) | [`CMS.INITBYPROB`](./cms.initbyprob.md) | [`CMS.QUERY`](./cms.query.md) | [`CMS.MERGE`](./cms.merge.md) diff --git a/docs/command-reference/count-min-sketch/cms.initbydim.md b/docs/command-reference/count-min-sketch/cms.initbydim.md new file mode 100644 index 00000000..635a9262 --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.initbydim.md @@ -0,0 +1,39 @@ +--- +description: Learn how to use the CMS.INITBYDIM command to initialize a Count-Min Sketch with given width and depth dimensions. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.INITBYDIM + + + +## Syntax + + CMS.INITBYDIM key width depth + +**Time complexity:** O(1) + +**ACL categories:** @cms + +Initializes a Count-Min Sketch filter at `key` with the given `width` and `depth` dimensions. + +- `width`: The number of counters in each row (affects accuracy — a larger width reduces the error rate). +- `depth`: The number of hash functions / rows (affects confidence — a larger depth reduces the probability of error). + +If `key` already exists, an error is returned. + +## Return + +[Simple string reply](https://valkey.io/topics/protocol/#simple-strings): `OK` if the sketch was created successfully. + +## Examples + +```shell +dragonfly> CMS.INITBYDIM cms_key 2000 5 +OK +``` + +## See also + +[`CMS.INITBYPROB`](./cms.initbyprob.md) | [`CMS.INCRBY`](./cms.incrby.md) | [`CMS.QUERY`](./cms.query.md) | [`CMS.INFO`](./cms.info.md) diff --git a/docs/command-reference/count-min-sketch/cms.initbyprob.md b/docs/command-reference/count-min-sketch/cms.initbyprob.md new file mode 100644 index 00000000..e688ba41 --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.initbyprob.md @@ -0,0 +1,42 @@ +--- +description: Learn how to use the CMS.INITBYPROB command to initialize a Count-Min Sketch with a given error rate and probability. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.INITBYPROB + + + +## Syntax + + CMS.INITBYPROB key error probability + +**Time complexity:** O(1) + +**ACL categories:** @cms + +Initializes a Count-Min Sketch filter at `key` with dimensions automatically calculated from +the desired `error` rate and `probability` of accuracy. + +- `error`: The desired error rate as a fraction of the total count. Must be a positive number between `0` and `1`. + For example, `0.01` means the estimated count will be within `1%` of the true count. +- `probability`: The desired failure probability — the probability that an estimate will exceed the error bounds. Must be a positive number between `0` and `1`. + For example, `0.01` means there is a `1%` chance the estimate exceeds the error bounds. Lower values produce a deeper sketch with fewer errors but higher memory and CPU usage. + +If `key` already exists, an error is returned. + +## Return + +[Simple string reply](https://valkey.io/topics/protocol/#simple-strings): `OK` if the sketch was created successfully. + +## Examples + +```shell +dragonfly> CMS.INITBYPROB cms_key 0.01 0.01 +OK +``` + +## See also + +[`CMS.INITBYDIM`](./cms.initbydim.md) | [`CMS.INCRBY`](./cms.incrby.md) | [`CMS.QUERY`](./cms.query.md) | [`CMS.INFO`](./cms.info.md) diff --git a/docs/command-reference/count-min-sketch/cms.merge.md b/docs/command-reference/count-min-sketch/cms.merge.md new file mode 100644 index 00000000..b9c2c2bc --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.merge.md @@ -0,0 +1,77 @@ +--- +description: Learn how to use the CMS.MERGE command to merge multiple Count-Min Sketches into a destination sketch. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.MERGE + + + +## Syntax + + CMS.MERGE destination numkeys source [source ...] [WEIGHTS weight [weight ...]] + +**Time complexity:** O(n·w·d) where n is the number of source sketches, w is the width, and d is the depth + +**ACL categories:** @cms + +Merges multiple source Count-Min Sketches into `destination`. +The `destination` key must be pre-initialized via [`CMS.INITBYDIM`](./cms.initbydim.md) or [`CMS.INITBYPROB`](./cms.initbyprob.md) before calling this command — if it does not exist, an error is returned. +All sketches (sources and destination) must have identical `width` and `depth` dimensions. The destination's existing counts are overwritten. + +- `numkeys`: The number of source sketch keys to merge. +- `source`: One or more source sketch keys. +- `WEIGHTS`: Optional integer multipliers applied to each source sketch before merging. Each source's counters are multiplied by its corresponding weight prior to being summed into the destination. Defaults to `1` for all sources if omitted. + +## Return + +[Simple string reply](https://valkey.io/topics/protocol/#simple-strings): `OK` if the merge was successful. + +## Examples + +```shell +dragonfly> CMS.INITBYDIM cms1 2000 5 +OK + +dragonfly> CMS.INITBYDIM cms2 2000 5 +OK + +dragonfly> CMS.INCRBY cms1 item1 10 item2 3 +1) (integer) 10 +2) (integer) 3 + +dragonfly> CMS.INCRBY cms2 item1 5 item3 7 +1) (integer) 5 +2) (integer) 7 + +dragonfly> CMS.INITBYDIM cms_merged 2000 5 +OK + +dragonfly> CMS.MERGE cms_merged 2 cms1 cms2 +OK + +dragonfly> CMS.QUERY cms_merged item1 item2 item3 +1) (integer) 15 +2) (integer) 3 +3) (integer) 7 +``` + +Using `WEIGHTS` to scale contributions before merging: + +```shell +dragonfly> CMS.INITBYDIM cms_weighted 2000 5 +OK + +dragonfly> CMS.MERGE cms_weighted 2 cms1 cms2 WEIGHTS 2 1 +OK + +dragonfly> CMS.QUERY cms_weighted item1 item2 item3 +1) (integer) 25 +2) (integer) 6 +3) (integer) 7 +``` + +## See also + +[`CMS.INITBYDIM`](./cms.initbydim.md) | [`CMS.INITBYPROB`](./cms.initbyprob.md) | [`CMS.INCRBY`](./cms.incrby.md) | [`CMS.INFO`](./cms.info.md) diff --git a/docs/command-reference/count-min-sketch/cms.query.md b/docs/command-reference/count-min-sketch/cms.query.md new file mode 100644 index 00000000..7b6e5461 --- /dev/null +++ b/docs/command-reference/count-min-sketch/cms.query.md @@ -0,0 +1,46 @@ +--- +description: Learn how to use the CMS.QUERY command to retrieve the estimated count of one or more items from a Count-Min Sketch. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# CMS.QUERY + + + +## Syntax + + CMS.QUERY key item [item ...] + +**Time complexity:** O(n) where n is the number of items + +**ACL categories:** @cms + +Returns the estimated count of one or more `item`s from the Count-Min Sketch stored at `key`. + +The returned counts are estimates and may be higher than the true count (over-counting) due to hash collisions, +but will never be lower than the true count. + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays): An array of integers, one per item, representing the estimated count of each queried item. + +## Examples + +```shell +dragonfly> CMS.INITBYDIM cms_key 2000 5 +OK + +dragonfly> CMS.INCRBY cms_key item1 10 item2 3 +1) (integer) 10 +2) (integer) 3 + +dragonfly> CMS.QUERY cms_key item1 item2 item3 +1) (integer) 10 +2) (integer) 3 +3) (integer) 0 +``` + +## See also + +[`CMS.INCRBY`](./cms.incrby.md) | [`CMS.INITBYDIM`](./cms.initbydim.md) | [`CMS.INITBYPROB`](./cms.initbyprob.md) | [`CMS.INFO`](./cms.info.md)