diff --git a/docs/command-reference/compatibility.md b/docs/command-reference/compatibility.md index 3b836a4a..5046cd6e 100644 --- a/docs/command-reference/compatibility.md +++ b/docs/command-reference/compatibility.md @@ -372,12 +372,13 @@ sidebar_position: 0 | | TOPK.INFO | Fully supported | | Cuckoo Filter | CF.ADD | Fully supported | | | CF.ADDNX | Fully supported | +| | CF.COMPACT | Fully supported | | | CF.COUNT | Fully supported | | | CF.DEL | Fully supported | | | CF.EXISTS | Fully supported | | | CF.INFO | Fully supported | -| | CF.INSERT | Unsupported | -| | CF.INSERTNX | Unsupported | +| | CF.INSERT | Fully supported | +| | CF.INSERTNX | Fully supported | | | CF.LOADCHUNK | Unsupported | | | CF.MEXISTS | Fully supported | | | CF.RESERVE | Fully supported | diff --git a/docs/command-reference/cuckoo-filter/cf.add.md b/docs/command-reference/cuckoo-filter/cf.add.md index ae4165b5..923b7f89 100644 --- a/docs/command-reference/cuckoo-filter/cf.add.md +++ b/docs/command-reference/cuckoo-filter/cf.add.md @@ -45,4 +45,4 @@ dragonfly> CF.COUNT cf Hello ## See also -[`CF.ADDNX`](./cf.addnx.md) | [`CF.EXISTS`](./cf.exists.md) | [`CF.RESERVE`](./cf.reserve.md) +[`CF.ADDNX`](./cf.addnx.md) | [`CF.INSERT`](./cf.insert.md) | [`CF.EXISTS`](./cf.exists.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.addnx.md b/docs/command-reference/cuckoo-filter/cf.addnx.md index 90a9e927..0b8d6c33 100644 --- a/docs/command-reference/cuckoo-filter/cf.addnx.md +++ b/docs/command-reference/cuckoo-filter/cf.addnx.md @@ -46,4 +46,4 @@ dragonfly> CF.ADDNX cf World ## See also -[`CF.ADD`](./cf.add.md) | [`CF.EXISTS`](./cf.exists.md) | [`CF.RESERVE`](./cf.reserve.md) +[`CF.ADD`](./cf.add.md) | [`CF.INSERTNX`](./cf.insertnx.md) | [`CF.EXISTS`](./cf.exists.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.compact.md b/docs/command-reference/cuckoo-filter/cf.compact.md new file mode 100644 index 00000000..19477576 --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.compact.md @@ -0,0 +1,52 @@ +--- +description: Learn how to use the CF.COMPACT command to compact a Cuckoo filter in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.COMPACT + + + +## Syntax + + CF.COMPACT key + +**Time complexity:** O(k), where k is the number of sub-filters + +**ACL categories:** @cuckoo + +Attempts to compact the Cuckoo filter at `key` by consolidating its sub-filters. + +When a filter expands, older sub-filters are kept around until [`CF.DEL`](./cf.del.md) empties +them out. `CF.DEL` already triggers this automatically once deletions exceed 10% of the items in +the filter, so `CF.COMPACT` mainly exists to force the pass on demand, for example after a batch +of deletions. + +## Return + +[Simple string reply](https://valkey.io/topics/protocol/#simple-strings): `OK`. + +[Error reply](https://valkey.io/topics/protocol/#simple-errors): if `key` does not exist or is not a Cuckoo filter. + +## Examples + +```shell +dragonfly> CF.RESERVE cf 4 +OK + +dragonfly> CF.ADD cf Hello +(integer) 1 + +dragonfly> CF.DEL cf Hello +(integer) 1 + +dragonfly> CF.COMPACT cf +OK + +dragonfly> CF.COMPACT no_such_key +(error) no such key +``` + +## See also + +[`CF.DEL`](./cf.del.md) | [`CF.RESERVE`](./cf.reserve.md) | [`CF.INFO`](./cf.info.md) diff --git a/docs/command-reference/cuckoo-filter/cf.count.md b/docs/command-reference/cuckoo-filter/cf.count.md new file mode 100644 index 00000000..d8414f4a --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.count.md @@ -0,0 +1,50 @@ +--- +description: Learn how to use the CF.COUNT command to count occurrences of an item in a Cuckoo filter in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.COUNT + + + +## Syntax + + CF.COUNT key item + +**Time complexity:** O(k), where k is the number of sub-filters + +**ACL categories:** @cuckoo + +Returns the number of times `item` occurs in the Cuckoo filter at `key`. + +Since [`CF.ADD`](./cf.add.md) allows duplicate insertions, the same item can occupy more than one +slot. `CF.COUNT` reports how many slots currently match `item`, which may include false positives. + +If `key` does not exist, `0` is returned. + +## Return + +[Integer reply](https://valkey.io/topics/protocol/#integers): the number of occurrences of `item` in the filter. + +## Examples + +```shell +dragonfly> CF.ADD cf foo +(integer) 1 + +dragonfly> CF.ADD cf foo +(integer) 1 + +dragonfly> CF.COUNT cf foo +(integer) 2 + +dragonfly> CF.COUNT cf bar +(integer) 0 + +dragonfly> CF.COUNT no_such_key foo +(integer) 0 +``` + +## See also + +[`CF.ADD`](./cf.add.md) | [`CF.EXISTS`](./cf.exists.md) | [`CF.DEL`](./cf.del.md) diff --git a/docs/command-reference/cuckoo-filter/cf.del.md b/docs/command-reference/cuckoo-filter/cf.del.md new file mode 100644 index 00000000..0652474f --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.del.md @@ -0,0 +1,56 @@ +--- +description: Learn how to use the CF.DEL command to remove an item from a Cuckoo filter in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.DEL + + + +## Syntax + + CF.DEL key item + +**Time complexity:** O(k), where k is the number of sub-filters + +**ACL categories:** @cuckoo + +Removes a single occurrence of `item` from the Cuckoo filter at `key`. + +Unlike Bloom filters, Cuckoo filters support deletion. Only one occurrence is removed per call, +so if `item` was added multiple times, `CF.DEL` must be called once per insertion to fully remove it. + +Deleting an item that was never added, or deleting more times than it was added, can introduce +false negatives for that item. Only delete items that are known to have been added. + +## Return + +[Integer reply](https://valkey.io/topics/protocol/#integers): + +- `1` if the item was found and removed. +- `0` if the item was not found. + +[Error reply](https://valkey.io/topics/protocol/#simple-errors): if `key` does not exist or is not a Cuckoo filter. + +## Examples + +```shell +dragonfly> CF.ADD cf Hello +(integer) 1 + +dragonfly> CF.DEL cf Hello +(integer) 1 + +dragonfly> CF.EXISTS cf Hello +(integer) 0 + +dragonfly> CF.DEL cf Hello +(integer) 0 + +dragonfly> CF.DEL no_such_key Hello +(error) no such key +``` + +## See also + +[`CF.ADD`](./cf.add.md) | [`CF.COUNT`](./cf.count.md) | [`CF.COMPACT`](./cf.compact.md) diff --git a/docs/command-reference/cuckoo-filter/cf.exists.md b/docs/command-reference/cuckoo-filter/cf.exists.md index 87a1305f..88994815 100644 --- a/docs/command-reference/cuckoo-filter/cf.exists.md +++ b/docs/command-reference/cuckoo-filter/cf.exists.md @@ -49,4 +49,4 @@ dragonfly> CF.EXISTS no_such_key item ## See also -[`CF.MEXISTS`](./cf.mexists.md) | [`CF.ADD`](./cf.add.md) | [`CF.RESERVE`](./cf.reserve.md) +[`CF.MEXISTS`](./cf.mexists.md) | [`CF.COUNT`](./cf.count.md) | [`CF.ADD`](./cf.add.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.info.md b/docs/command-reference/cuckoo-filter/cf.info.md new file mode 100644 index 00000000..67df56b9 --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.info.md @@ -0,0 +1,68 @@ +--- +description: Learn how to use the CF.INFO command to get information about a Cuckoo filter in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.INFO + + + +## Syntax + + CF.INFO key + +**Time complexity:** O(1) + +**ACL categories:** @cuckoo + +Returns information about the Cuckoo filter at `key`. + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays) of alternating field names and values: + +- `Size`: memory used by the filter, in bytes. +- `Number of buckets`: total number of buckets across all sub-filters. +- `Number of filters`: number of sub-filters created due to expansion. +- `Number of items inserted`: total number of items currently in the filter. +- `Number of items deleted`: total number of items deleted from the filter. +- `Bucket size`: number of fingerprint slots per bucket. +- `Expansion rate`: the configured expansion rate. +- `Max iterations`: the configured maximum number of cuckoo-displacement attempts. + +[Error reply](https://valkey.io/topics/protocol/#simple-errors): if `key` does not exist or is not a Cuckoo filter. + +## Examples + +```shell +dragonfly> CF.RESERVE cf 1000 BUCKETSIZE 4 MAXITERATIONS 10 EXPANSION 2 +OK + +dragonfly> CF.ADD cf foo +(integer) 1 + +dragonfly> CF.INFO cf + 1) "Size" + 2) (integer) 128 + 3) "Number of buckets" + 4) (integer) 512 + 5) "Number of filters" + 6) (integer) 1 + 7) "Number of items inserted" + 8) (integer) 1 + 9) "Number of items deleted" +10) (integer) 0 +11) "Bucket size" +12) (integer) 4 +13) "Expansion rate" +14) (integer) 2 +15) "Max iterations" +16) (integer) 10 + +dragonfly> CF.INFO no_such_key +(error) no such key +``` + +## See also + +[`CF.RESERVE`](./cf.reserve.md) | [`CF.COUNT`](./cf.count.md) diff --git a/docs/command-reference/cuckoo-filter/cf.insert.md b/docs/command-reference/cuckoo-filter/cf.insert.md new file mode 100644 index 00000000..b1cb2e6e --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.insert.md @@ -0,0 +1,59 @@ +--- +description: Learn how to use the CF.INSERT command to add multiple items to a Cuckoo filter in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.INSERT + + + +## Syntax + + CF.INSERT key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...] + +**Time complexity:** O(k * n), where k is the number of sub-filters and n is the number of items + +**ACL categories:** @cuckoo + +Adds one or more items to the Cuckoo filter at `key`, creating it first if it doesn't exist. + +Like [`CF.ADD`](./cf.add.md), duplicate insertions are allowed. + +## Parameters + +| Parameter | Default | Description | +|--------------|---------|-------------------------------------------------------------------------------------------------| +| `key` | | The name of the filter. | +| `CAPACITY` | `1024` | Initial capacity to use if the filter is created by this command. Ignored if `key` already exists. | +| `NOCREATE` | | If set, the filter must already exist; otherwise an error is returned instead of creating it. | +| `ITEMS` | | One or more items to add. Required. | + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays) of [Integer replies](https://valkey.io/topics/protocol/#integers), one per item, in the same order as the input: + +- `1` if the item was successfully added. +- `-1` if the filter is full and the item could not be added. + +[Error reply](https://valkey.io/topics/protocol/#simple-errors): if `NOCREATE` is set and `key` does not exist, or `CAPACITY` is `0`. + +## Examples + +```shell +dragonfly> CF.INSERT cf ITEMS Hello World +1) (integer) 1 +2) (integer) 1 + +dragonfly> CF.INSERT cf CAPACITY 500 ITEMS foo +1) (integer) 1 + +dragonfly> CF.INSERT cf NOCREATE ITEMS bar +1) (integer) 1 + +dragonfly> CF.INSERT no_such_key NOCREATE ITEMS bar +(error) no such key +``` + +## See also + +[`CF.INSERTNX`](./cf.insertnx.md) | [`CF.ADD`](./cf.add.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.insertnx.md b/docs/command-reference/cuckoo-filter/cf.insertnx.md new file mode 100644 index 00000000..dd8ebf5d --- /dev/null +++ b/docs/command-reference/cuckoo-filter/cf.insertnx.md @@ -0,0 +1,58 @@ +--- +description: Learn how to use the CF.INSERTNX command to add multiple items to a Cuckoo filter without duplicates in Dragonfly. +--- +import PageTitle from '@site/src/components/PageTitle'; + +# CF.INSERTNX + + + +## Syntax + + CF.INSERTNX key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...] + +**Time complexity:** O(k * n), where k is the number of sub-filters and n is the number of items + +**ACL categories:** @cuckoo + +Adds one or more items to the Cuckoo filter at `key`, creating it first if it doesn't exist. + +Unlike [`CF.INSERT`](./cf.insert.md), an item is only added if it doesn't already exist in the filter. + +## Parameters + +| Parameter | Default | Description | +|--------------|---------|-------------------------------------------------------------------------------------------------| +| `key` | | The name of the filter. | +| `CAPACITY` | `1024` | Initial capacity to use if the filter is created by this command. Ignored if `key` already exists. | +| `NOCREATE` | | If set, the filter must already exist; otherwise an error is returned instead of creating it. | +| `ITEMS` | | One or more items to add. Required. | + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays) of [Integer replies](https://valkey.io/topics/protocol/#integers), one per item, in the same order as the input: + +- `1` if the item was successfully added. +- `0` if the item already exists in the filter. +- `-1` if the filter is full and the item could not be added. + +[Error reply](https://valkey.io/topics/protocol/#simple-errors): if `NOCREATE` is set and `key` does not exist, or `CAPACITY` is `0`. + +## Examples + +```shell +dragonfly> CF.INSERTNX cf ITEMS Hello World +1) (integer) 1 +2) (integer) 1 + +dragonfly> CF.INSERTNX cf ITEMS Hello Again +1) (integer) 0 +2) (integer) 1 + +dragonfly> CF.INSERTNX no_such_key NOCREATE ITEMS bar +(error) no such key +``` + +## See also + +[`CF.INSERT`](./cf.insert.md) | [`CF.ADDNX`](./cf.addnx.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.mexists.md b/docs/command-reference/cuckoo-filter/cf.mexists.md index 34c773df..8f7b5250 100644 --- a/docs/command-reference/cuckoo-filter/cf.mexists.md +++ b/docs/command-reference/cuckoo-filter/cf.mexists.md @@ -50,4 +50,4 @@ dragonfly> CF.MEXISTS no_such_key a b c ## See also -[`CF.EXISTS`](./cf.exists.md) | [`CF.ADD`](./cf.add.md) | [`CF.RESERVE`](./cf.reserve.md) +[`CF.EXISTS`](./cf.exists.md) | [`CF.INSERT`](./cf.insert.md) | [`CF.ADD`](./cf.add.md) | [`CF.RESERVE`](./cf.reserve.md) diff --git a/docs/command-reference/cuckoo-filter/cf.reserve.md b/docs/command-reference/cuckoo-filter/cf.reserve.md index 204d244e..ad847984 100644 --- a/docs/command-reference/cuckoo-filter/cf.reserve.md +++ b/docs/command-reference/cuckoo-filter/cf.reserve.md @@ -51,4 +51,4 @@ OK ## See also -[`CF.ADD`](./cf.add.md) | [`CF.ADDNX`](./cf.addnx.md) +[`CF.ADD`](./cf.add.md) | [`CF.ADDNX`](./cf.addnx.md) | [`CF.INSERT`](./cf.insert.md) | [`CF.INFO`](./cf.info.md)