From a93e96850dd3f6104ab547d8593c169f9b60401c Mon Sep 17 00:00:00 2001 From: Volodymyr Yavdoshenko Date: Tue, 4 Aug 2026 15:50:47 +0300 Subject: [PATCH] docs: update command reference and compatibility for v1.40.0 --- docs/command-reference/acl/dryrun.md | 6 +- .../command-reference/bloom-filter/bf.info.md | 79 +++++++ .../dflycluster-slot-migration-status.md | 16 +- docs/command-reference/compatibility.md | 18 +- .../count-min-sketch/cms.incrby.md | 2 +- .../count-min-sketch/cms.initbydim.md | 2 +- .../count-min-sketch/cms.initbyprob.md | 2 +- .../count-min-sketch/cms.merge.md | 2 +- .../command-reference/cuckoo-filter/cf.add.md | 2 +- .../cuckoo-filter/cf.addnx.md | 2 +- .../cuckoo-filter/cf.compact.md | 17 +- .../cuckoo-filter/cf.count.md | 4 +- .../command-reference/cuckoo-filter/cf.del.md | 6 +- .../cuckoo-filter/cf.exists.md | 4 +- .../cuckoo-filter/cf.info.md | 18 +- .../cuckoo-filter/cf.insert.md | 4 +- .../cuckoo-filter/cf.insertnx.md | 4 +- .../cuckoo-filter/cf.mexists.md | 4 +- .../cuckoo-filter/cf.reserve.md | 10 +- docs/command-reference/generic/wait.md | 2 +- docs/command-reference/hashes/hgetex.md | 85 +++++++ docs/command-reference/hashes/hpexpiretime.md | 71 ++++++ docs/command-reference/search/ft.aggregate.md | 8 +- docs/command-reference/search/ft.create.md | 34 +-- docs/command-reference/search/ft.info.md | 52 +++-- docs/command-reference/search/ft.search.md | 26 ++- .../server-management/info.md | 12 +- .../server-management/reset.md | 79 +++++++ docs/managing-dragonfly/cluster-mode.md | 13 +- docs/managing-dragonfly/flags.md | 221 ++++++++++-------- docs/managing-dragonfly/monitoring.md | 4 +- docs/managing-dragonfly/replication.md | 34 ++- docs/managing-dragonfly/tiering.md | 4 +- 33 files changed, 623 insertions(+), 224 deletions(-) create mode 100644 docs/command-reference/bloom-filter/bf.info.md create mode 100644 docs/command-reference/hashes/hgetex.md create mode 100644 docs/command-reference/hashes/hpexpiretime.md create mode 100644 docs/command-reference/server-management/reset.md diff --git a/docs/command-reference/acl/dryrun.md b/docs/command-reference/acl/dryrun.md index f64e0892..7d005115 100644 --- a/docs/command-reference/acl/dryrun.md +++ b/docs/command-reference/acl/dryrun.md @@ -10,11 +10,11 @@ import PageTitle from '@site/src/components/PageTitle'; ## Syntax - ACL DRYRUN username command + ACL DRYRUN username command [arg [arg ...]] **ACL categories:** @admin, @slow, @dangerous -This command simulates the execution of a given command by a user. +This command simulates the execution of a given command and its arguments by a user. It can be used to test the permissions without having to enable the user or cause the side effects of running the actual command. ## Return @@ -32,5 +32,5 @@ dragonfly> ACL DRYRUN mike GET OK dragonfly> ACL DRYRUN mike SET -"This user has no permissions to run the 'set' command" +"This user has no permissions to run the 'SET' command" ``` diff --git a/docs/command-reference/bloom-filter/bf.info.md b/docs/command-reference/bloom-filter/bf.info.md new file mode 100644 index 00000000..52fa3fa3 --- /dev/null +++ b/docs/command-reference/bloom-filter/bf.info.md @@ -0,0 +1,79 @@ +--- +description: Learn how to use Redis BF.INFO to inspect a Bloom filter in Dragonfly. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# BF.INFO + + + +## Syntax + + BF.INFO key [CAPACITY | SIZE | FILTERS | ITEMS | EXPANSION] + +**Time complexity:** O(F), where F is the number of sub-filters. + +**ACL categories:** @bloom + +Returns usage information and properties of the Bloom filter stored at `key`. +Without a selector, the command returns all available properties. With a +selector, it returns only that property's value. + +## Selectors + +| Selector | Description | +|---|---| +| `CAPACITY` | Total design capacity across completed sub-filters and the current sub-filter. The value can be greater than the capacity requested with `BF.RESERVE` because Dragonfly rounds the underlying storage size. | +| `SIZE` | Number of bytes allocated by the filter. | +| `FILTERS` | Number of sub-filters. | +| `ITEMS` | Number of items successfully inserted across all sub-filters. | +| `EXPANSION` | Growth factor used when another sub-filter is created. | + +:::note Dragonfly compatibility + +Dragonfly v1.40.0 supports the five selectors listed above. The `ERROR`, +`TIGHTENING`, and `MAXSCALEDCAPACITY` selectors from the +[Valkey command](https://valkey.io/commands/bf.info/) are not supported. + +::: + +## Return + +- [Array reply](https://valkey.io/topics/protocol/#arrays): alternating property + names and integer values when no selector is provided. +- [Integer reply](https://valkey.io/topics/protocol/#integers): the requested + property value when a selector is provided. +- [Error reply](https://valkey.io/topics/protocol/#simple-errors): if `key` does + not exist, contains a different data type, or the selector is unsupported. + +## Examples + +```shell +dragonfly> BF.RESERVE visitors 0.01 1000 +OK + +dragonfly> BF.MADD visitors alice bob carol +1) (integer) 1 +2) (integer) 1 +3) (integer) 1 + +dragonfly> BF.INFO visitors + 1) "Capacity" + 2) (integer) 1485 + 3) "Size" + 4) (integer) 2136 + 5) "Number of filters" + 6) (integer) 1 + 7) "Number of items inserted" + 8) (integer) 3 + 9) "Expansion rate" +10) (integer) 2 + +dragonfly> BF.INFO visitors ITEMS +(integer) 3 +``` + +## See also + +[`BF.RESERVE`](./bf.reserve.md) | [`BF.ADD`](./bf.add.md) | [`BF.MADD`](./bf.madd.md) diff --git a/docs/command-reference/cluster-management/dflycluster-slot-migration-status.md b/docs/command-reference/cluster-management/dflycluster-slot-migration-status.md index edeed9a0..5bf6cdef 100644 --- a/docs/command-reference/cluster-management/dflycluster-slot-migration-status.md +++ b/docs/command-reference/cluster-management/dflycluster-slot-migration-status.md @@ -12,7 +12,8 @@ import PageTitle from '@site/src/components/PageTitle'; DFLYCLUSTER SLOT-MIGRATION-STATUS [node_id] -**Time complexity:** O(N), where N is the number of migrations on the node +**Time complexity:** O(M + R), where M is the number of migrations on the +node and R is the total number of their slot ranges. **ACL categories:** @admin, @slow @@ -28,17 +29,18 @@ For each migration, the following fields are returned: - The `node_id` of the migration. - The migration state, which can be `CONNECTING`, `SYNC`, `ERROR`, `FINISHED`, or `FATAL`. - The number of keys for selected slots on the current node. -- The error status, which is `0` if no error happens. Otherwise, it shows the last error description. +- The error status, which is `0` when no error occurred. Otherwise, it shows the last error description. +- The slot ranges included in the migration, formatted as a string. ## Examples ```shell -# The current node is migrating out to 'node_xfsef234fs'. -# It is currently syncing the data of 2250125 keys. +# The current node finished migrating four keys in slots 3000 through 9000. dragonfly> DFLYCLUSTER SLOT-MIGRATION-STATUS 1) 1) "out" - 2) "node_xfsef234fs" - 3) "SYNC" - 4) (integer) 2250125 + 2) "133807dea9b616400e22587b99abd87a1cbf6473" + 3) "FINISHED" + 4) (integer) 4 5) "0" + 6) "[3000, 9000]" ``` diff --git a/docs/command-reference/compatibility.md b/docs/command-reference/compatibility.md index 4909f2c5..cc706201 100644 --- a/docs/command-reference/compatibility.md +++ b/docs/command-reference/compatibility.md @@ -5,6 +5,11 @@ sidebar_position: 0 # Dragonfly API Compatibility +This table tracks command-surface compatibility: whether Dragonfly accepts a +command and its documented options or subcommands. "Fully supported" does not +imply byte-for-byte identical behavior. See each command page for +Dragonfly-specific precision, limits, and other behavioral differences. + | Command Family | Command | Dragonfly Support | Details | |:--|:--|:--|:--| | Bitmap | BITCOUNT | Fully supported | | @@ -37,7 +42,7 @@ sidebar_position: 0 | | HELLO | Fully supported | | | | PING | Fully supported | | | | QUIT | Fully supported | | -| | RESET | Unsupported | | +| | RESET | Fully supported | | | | SELECT | Fully supported | | | Generic | COPY | Partially supported | Missing: DB. | | | DEL | Fully supported | | @@ -76,12 +81,14 @@ sidebar_position: 0 | | HEXISTS | Fully supported | | | | HGET | Fully supported | | | | HGETALL | Fully supported | | +| | HGETEX | Fully supported | | | | HINCRBY | Fully supported | | | | HINCRBYFLOAT | Fully supported | | | | HKEYS | Fully supported | | | | HLEN | Fully supported | | | | HMGET | Fully supported | | | | HMSET | Fully supported | | +| | HPEXPIRETIME | Fully supported | | | | HRANDFIELD | Fully supported | | | | HSCAN | Fully supported | | | | HSET | Fully supported | | @@ -312,10 +319,9 @@ sidebar_position: 0 | | BF.INSERT | Unsupported | | | | BF.SCANDUMP | Fully supported | | | | BF.LOADCHUNK | Fully supported | | -| | BF.INFO | Unsupported | | +| | BF.INFO | Partially supported | Missing: ERROR, MAXSCALEDCAPACITY, TIGHTENING. | | | BF.CARD | Unsupported | | | | BF.DEBUG | Unsupported | | -| Cuckoo Filter | TBD | Unsupported | | | Count-Min Sketch | CMS.INCRBY | Fully supported | | | | CMS.INFO | Fully supported | | | | CMS.INITBYDIM | Fully supported | | @@ -350,7 +356,7 @@ sidebar_position: 0 | | JSON.TYPE | Fully supported | | | Search | FT.CREATE | Partially supported | Missing: DISABLE, ENABLE, INDEXALL, MAXTEXTFIELDS, NOFIELDS, NOFREQS, NOHL, PAYLOAD_FIELD, SCORE, SCORE_FIELD. | | | FT.SEARCH | Partially supported | Missing: EXPANDER, EXPLAINSCORE, FIELDS, FRAGS, GEOFILTER, HIGHLIGHT, INFIELDS, INKEYS, INORDER, LEN, NOSTOPWORDS, PAYLOAD, SLOP, SUMMARIZE, TAGS, TIMEOUT, VERBATIM, WITHPAYLOADS. | -| | FT.HYBRID | Partially supported | Missing: ADHOC, BATCHES, BATCH_SIZE, COUNT_DISTINCTISH, EF_RUNTIME, EPSILON, FIRST_VALUE, NOSORT, OFFSET, POLICY, QUANTILE, RADIUS, RANDOM_SAMPLE, STDDEV, TIMEOUT, TIMESHARING, TIMESTAMP, TOLIST. | +| | FT.HYBRID | Partially supported | Missing: ADHOC, BATCHES, BATCH_SIZE, COUNT_DISTINCTISH, FIRST_VALUE, NOSORT, OFFSET, POLICY, QUANTILE, RANDOM_SAMPLE, STDDEV, TIMEOUT, TIMESHARING, TIMESTAMP, TOLIST. | | | FT.ALTER | Fully supported | | | | FT.DROPINDEX | Fully supported | | | | FT.INFO | Fully supported | | @@ -371,7 +377,7 @@ sidebar_position: 0 | | TOPK.COUNT | Fully supported | | | | TOPK.LIST | Fully supported | | | | TOPK.INFO | Fully supported | | -| CF | CF.ADD | Fully supported | | +| Cuckoo Filter | CF.ADD | Fully supported | | | | CF.ADDNX | Fully supported | | | | CF.COMPACT | Fully supported | | | | CF.COUNT | Fully supported | | @@ -415,4 +421,4 @@ sidebar_position: 0 | | READONLY | Fully supported | | | | READWRITE | Fully supported | | -Verification: Dragonfly v1.39.0; Redis 8.6.4; modules: BF, CF, CMS, FT, JSON, TDIGEST, TOPK, TS. +Verification: Dragonfly v1.40.0; Redis 8.6.4; modules: BF, CF, CMS, FT, JSON, TDIGEST, TOPK, TS. diff --git a/docs/command-reference/count-min-sketch/cms.incrby.md b/docs/command-reference/count-min-sketch/cms.incrby.md index 51baf5a7..1784c509 100644 --- a/docs/command-reference/count-min-sketch/cms.incrby.md +++ b/docs/command-reference/count-min-sketch/cms.incrby.md @@ -14,7 +14,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(n) where n is the number of items -**ACL categories:** @cms, @fast +**ACL categories:** @cms, @fast, @write 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`. diff --git a/docs/command-reference/count-min-sketch/cms.initbydim.md b/docs/command-reference/count-min-sketch/cms.initbydim.md index 4abbc235..2408a681 100644 --- a/docs/command-reference/count-min-sketch/cms.initbydim.md +++ b/docs/command-reference/count-min-sketch/cms.initbydim.md @@ -14,7 +14,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(1) -**ACL categories:** @cms, @fast +**ACL categories:** @cms, @fast, @write Initializes a Count-Min Sketch filter at `key` with the given `width` and `depth` dimensions. diff --git a/docs/command-reference/count-min-sketch/cms.initbyprob.md b/docs/command-reference/count-min-sketch/cms.initbyprob.md index d6e12f6a..eed54e42 100644 --- a/docs/command-reference/count-min-sketch/cms.initbyprob.md +++ b/docs/command-reference/count-min-sketch/cms.initbyprob.md @@ -14,7 +14,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(1) -**ACL categories:** @cms, @fast +**ACL categories:** @cms, @fast, @write Initializes a Count-Min Sketch filter at `key` with dimensions automatically calculated from the desired `error` rate and `probability` of accuracy. diff --git a/docs/command-reference/count-min-sketch/cms.merge.md b/docs/command-reference/count-min-sketch/cms.merge.md index 9555241f..3e3af8d5 100644 --- a/docs/command-reference/count-min-sketch/cms.merge.md +++ b/docs/command-reference/count-min-sketch/cms.merge.md @@ -14,7 +14,7 @@ import PageTitle from '@site/src/components/PageTitle'; **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, @slow +**ACL categories:** @cms, @slow, @write 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. diff --git a/docs/command-reference/cuckoo-filter/cf.add.md b/docs/command-reference/cuckoo-filter/cf.add.md index 09fc5401..937b8eb2 100644 --- a/docs/command-reference/cuckoo-filter/cf.add.md +++ b/docs/command-reference/cuckoo-filter/cf.add.md @@ -13,7 +13,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k + i), where k is the number of sub-filters and i is `MAXITERATIONS` -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @slow, @write Adds a single `item` to the Cuckoo filter at `key`. If `key` does not exist, a new filter is created with default parameters. diff --git a/docs/command-reference/cuckoo-filter/cf.addnx.md b/docs/command-reference/cuckoo-filter/cf.addnx.md index 4acc7277..dfd9f58f 100644 --- a/docs/command-reference/cuckoo-filter/cf.addnx.md +++ b/docs/command-reference/cuckoo-filter/cf.addnx.md @@ -13,7 +13,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k + i), where k is the number of sub-filters and i is `MAXITERATIONS` -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @slow, @write Adds a single `item` to the Cuckoo filter at `key` only if it does not already exist. If `key` does not exist, a new filter is created with default parameters. diff --git a/docs/command-reference/cuckoo-filter/cf.compact.md b/docs/command-reference/cuckoo-filter/cf.compact.md index 564ce485..318e8b88 100644 --- a/docs/command-reference/cuckoo-filter/cf.compact.md +++ b/docs/command-reference/cuckoo-filter/cf.compact.md @@ -11,16 +11,19 @@ import PageTitle from '@site/src/components/PageTitle'; CF.COMPACT key -**Time complexity:** O(k), where k is the number of sub-filters +**Time complexity:** O(S × k) in the worst case, where S is the total number of fingerprint slots and k is the number of sub-filters. -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @slow, @write 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. +Compaction scans newer sub-filters and tries to move their fingerprints into +free slots in older sub-filters. It can remove a sub-filter only when the newest +one becomes completely empty. + +[`CF.DEL`](./cf.del.md) automatically runs a compaction pass when accumulated +deletions exceed one tenth of the remaining items. `CF.COMPACT` forces a full +pass on demand, for example after a batch of deletions. ## Return @@ -44,7 +47,7 @@ dragonfly> CF.COMPACT cf OK dragonfly> CF.COMPACT no_such_key -(error) no such key +(error) ERR no such key ``` ## See also diff --git a/docs/command-reference/cuckoo-filter/cf.count.md b/docs/command-reference/cuckoo-filter/cf.count.md index 7771461e..8b9705f5 100644 --- a/docs/command-reference/cuckoo-filter/cf.count.md +++ b/docs/command-reference/cuckoo-filter/cf.count.md @@ -13,14 +13,14 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k), where k is the number of sub-filters -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @read 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. +If `key` does not exist or holds a value of a different type, `0` is returned. ## Return diff --git a/docs/command-reference/cuckoo-filter/cf.del.md b/docs/command-reference/cuckoo-filter/cf.del.md index d1d6f4a5..3b5f86d2 100644 --- a/docs/command-reference/cuckoo-filter/cf.del.md +++ b/docs/command-reference/cuckoo-filter/cf.del.md @@ -11,9 +11,9 @@ import PageTitle from '@site/src/components/PageTitle'; CF.DEL key item -**Time complexity:** O(k), where k is the number of sub-filters +**Time complexity:** Normally O(k), where k is the number of sub-filters. If the deletion triggers automatic compaction, the worst case is O(S × k), where S is the total number of fingerprint slots. -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @write Removes a single occurrence of `item` from the Cuckoo filter at `key`. @@ -48,7 +48,7 @@ dragonfly> CF.DEL cf Hello (integer) 0 dragonfly> CF.DEL no_such_key Hello -(error) no such key +(error) ERR no such key ``` ## See also diff --git a/docs/command-reference/cuckoo-filter/cf.exists.md b/docs/command-reference/cuckoo-filter/cf.exists.md index 002b6994..50351a73 100644 --- a/docs/command-reference/cuckoo-filter/cf.exists.md +++ b/docs/command-reference/cuckoo-filter/cf.exists.md @@ -13,7 +13,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k), where k is the number of sub-filters -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @read Checks whether `item` exists in the Cuckoo filter at `key`. @@ -22,7 +22,7 @@ still be reported as present due to a fingerprint collision. False negatives are not possible: if an item was inserted and never deleted, `CF.EXISTS` will always return `1`. -If `key` does not exist, `0` is returned. +If `key` does not exist or holds a value of a different type, `0` is returned. ## Return diff --git a/docs/command-reference/cuckoo-filter/cf.info.md b/docs/command-reference/cuckoo-filter/cf.info.md index ef0ab9f8..1a91112e 100644 --- a/docs/command-reference/cuckoo-filter/cf.info.md +++ b/docs/command-reference/cuckoo-filter/cf.info.md @@ -11,9 +11,9 @@ import PageTitle from '@site/src/components/PageTitle'; CF.INFO key -**Time complexity:** O(1) +**Time complexity:** O(k), where k is the number of sub-filters. -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @read Returns information about the Cuckoo filter at `key`. @@ -22,12 +22,12 @@ Returns information about the Cuckoo filter at `key`. [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 buckets`: configured base number of buckets in the initial sub-filter. +- `Number of filters`: total number of sub-filters, including the initial one. - `Number of items inserted`: total number of items currently in the filter. -- `Number of items deleted`: total number of items deleted from the filter. +- `Number of items deleted`: number of deletions accumulated since the last compaction. - `Bucket size`: number of fingerprint slots per bucket. -- `Expansion rate`: the configured expansion rate. +- `Expansion rate`: effective expansion rate after rounding a nonzero configured value up to the next power of two. - `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. @@ -43,9 +43,9 @@ dragonfly> CF.ADD cf foo dragonfly> CF.INFO cf 1) "Size" - 2) (integer) 128 + 2) (integer) 1136 3) "Number of buckets" - 4) (integer) 512 + 4) (integer) 256 5) "Number of filters" 6) (integer) 1 7) "Number of items inserted" @@ -60,7 +60,7 @@ dragonfly> CF.INFO cf 16) (integer) 10 dragonfly> CF.INFO no_such_key -(error) no such key +(error) ERR no such key ``` ## See also diff --git a/docs/command-reference/cuckoo-filter/cf.insert.md b/docs/command-reference/cuckoo-filter/cf.insert.md index 7049df39..67821043 100644 --- a/docs/command-reference/cuckoo-filter/cf.insert.md +++ b/docs/command-reference/cuckoo-filter/cf.insert.md @@ -13,7 +13,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k * n), where k is the number of sub-filters and n is the number of items -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @slow, @write Adds one or more items to the Cuckoo filter at `key`, creating it first if it doesn't exist. @@ -51,7 +51,7 @@ dragonfly> CF.INSERT cf NOCREATE ITEMS bar 1) (integer) 1 dragonfly> CF.INSERT no_such_key NOCREATE ITEMS bar -(error) no such key +(error) ERR no such key ``` ## See also diff --git a/docs/command-reference/cuckoo-filter/cf.insertnx.md b/docs/command-reference/cuckoo-filter/cf.insertnx.md index cba37e45..a81e16d3 100644 --- a/docs/command-reference/cuckoo-filter/cf.insertnx.md +++ b/docs/command-reference/cuckoo-filter/cf.insertnx.md @@ -13,7 +13,7 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k * n), where k is the number of sub-filters and n is the number of items -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @slow, @write Adds one or more items to the Cuckoo filter at `key`, creating it first if it doesn't exist. @@ -50,7 +50,7 @@ dragonfly> CF.INSERTNX cf ITEMS Hello Again 2) (integer) 1 dragonfly> CF.INSERTNX no_such_key NOCREATE ITEMS bar -(error) no such key +(error) ERR no such key ``` ## See also diff --git a/docs/command-reference/cuckoo-filter/cf.mexists.md b/docs/command-reference/cuckoo-filter/cf.mexists.md index aba408b1..37c1b632 100644 --- a/docs/command-reference/cuckoo-filter/cf.mexists.md +++ b/docs/command-reference/cuckoo-filter/cf.mexists.md @@ -13,13 +13,13 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(k * n), where k is the number of sub-filters and n is the number of items -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @read Checks whether one or more items exist in the Cuckoo filter at `key`. Returns one reply per item in the same order as the input. Like [`CF.EXISTS`](./cf.exists.md), false positives are possible but false negatives are not. -If `key` does not exist, `0` is returned for every item. +If `key` does not exist or holds a value of a different type, `0` is returned for every item. ## Return diff --git a/docs/command-reference/cuckoo-filter/cf.reserve.md b/docs/command-reference/cuckoo-filter/cf.reserve.md index e6ff2f80..799b1159 100644 --- a/docs/command-reference/cuckoo-filter/cf.reserve.md +++ b/docs/command-reference/cuckoo-filter/cf.reserve.md @@ -13,9 +13,9 @@ import PageTitle from '@site/src/components/PageTitle'; **Time complexity:** O(1) -**ACL categories:** @cuckoo +**ACL categories:** @cuckoo_filter, @fast, @write -Creates a new Cuckoo filter at `key` with an initial capacity of at least `capacity` items. +Creates a new Cuckoo filter at `key` using `capacity` as the initial sizing estimate. If `key` already exists, an error is returned. Unlike Bloom filters, Cuckoo filters support deletion of individual items. @@ -25,10 +25,10 @@ Unlike Bloom filters, Cuckoo filters support deletion of individual items. | Parameter | Default | Description | |-----------------|---------|--------------------------------------------------------------------------------------------------------------------| | `key` | | The name of the filter. | -| `capacity` | | Estimated number of items the filter should hold. Actual capacity is rounded up to the next power of two. | +| `capacity` | | Initial sizing estimate. Dragonfly divides it by `BUCKETSIZE` and rounds the resulting base bucket count up to the next power of two, so the effective slot capacity can differ from this value. | | `BUCKETSIZE` | `2` | Number of fingerprint slots per bucket. Higher values improve fill rate but increase false positive probability. | | `MAXITERATIONS` | `20` | Maximum number of cuckoo-displacement attempts before declaring the filter full. Must be between 1 and 65535. | -| `EXPANSION` | `1` | When the filter is full, a new sub-filter of size `capacity * expansion` is created. `0` disables expansion. | +| `EXPANSION` | `1` | Growth factor for new sub-filters. `0` disables expansion; a nonzero value is rounded up to the next power of two. | ## Return @@ -43,7 +43,7 @@ dragonfly> CF.RESERVE cf 1000 OK dragonfly> CF.RESERVE cf 1000 -(error) item exists +(error) ERR item exists dragonfly> CF.RESERVE cf_custom 10000 BUCKETSIZE 4 MAXITERATIONS 50 EXPANSION 2 OK diff --git a/docs/command-reference/generic/wait.md b/docs/command-reference/generic/wait.md index f199c917..352971f9 100644 --- a/docs/command-reference/generic/wait.md +++ b/docs/command-reference/generic/wait.md @@ -12,7 +12,7 @@ import PageTitle from '@site/src/components/PageTitle'; WAIT numreplicas timeout -**Time complexity:** O(1) +**Time complexity:** Depends on the number of tracked replicas and shards, and on how long the command waits. **ACL categories:** @slow, @connection diff --git a/docs/command-reference/hashes/hgetex.md b/docs/command-reference/hashes/hgetex.md new file mode 100644 index 00000000..b2ffc266 --- /dev/null +++ b/docs/command-reference/hashes/hgetex.md @@ -0,0 +1,85 @@ +--- +description: Learn how to use Redis HGETEX to retrieve hash fields and update their expiration in Dragonfly. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# HGETEX + + + +## Syntax + + HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...] + +**Time complexity:** O(N) where N is the number of requested fields + +**ACL categories:** @write, @hash, @fast + +Returns the values of one or more hash fields and optionally changes their +expiration. Without an expiration option, `HGETEX` behaves like +[`HMGET`](./hmget.md) and leaves existing field expirations unchanged. + +## Options + +| Option | Description | +|---|---| +| `EX seconds` | Set a relative expiration in seconds. | +| `PX milliseconds` | Set a relative expiration in milliseconds. | +| `EXAT unix-time-seconds` | Set an absolute Unix expiration time in seconds. | +| `PXAT unix-time-milliseconds` | Set an absolute Unix expiration time in milliseconds. | +| `PERSIST` | Remove the expiration from the requested fields. | + +The options are mutually exclusive and must appear before `FIELDS`. An `EX` or +`PX` value of `0`, or an `EXAT` or `PXAT` value in the past, returns the current +field values and then deletes those fields. If the last field is deleted, the +hash key is also removed. + +:::note Dragonfly expiration precision + +Dragonfly stores hash-field expiration times with whole-second resolution. +`PX` and `PXAT` accept millisecond values, but the resulting expiration is +quantized to whole-second resolution. Positive values returned by +[`HPEXPIRETIME`](./hpexpiretime.md) are therefore multiples of 1000. +Expirations more than `2^28 - 1` seconds (about 8.5 years) in the future are +rejected. + +::: + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays): one value for each +requested field, in the same order. A missing field, or every field requested +from a missing key, is returned as `nil`. + +An [error reply](https://valkey.io/topics/protocol/#simple-errors) is returned +if `key` contains a non-hash value or the arguments are invalid. + +## Examples + +Set a TTL while retrieving fields. A missing field is returned as `nil`: + +```shell +dragonfly> HSET session:42 user alice token abc +(integer) 2 +dragonfly> HGETEX session:42 EX 600 FIELDS 2 token missing +1) "abc" +2) (nil) +``` + +Remove the field expiration with `PERSIST`: + +```shell +dragonfly> HSET session:42 token abc +(integer) 1 +dragonfly> HGETEX session:42 EX 600 FIELDS 1 token +1) "abc" +dragonfly> HGETEX session:42 PERSIST FIELDS 1 token +1) "abc" +dragonfly> HTTL session:42 FIELDS 1 token +1) (integer) -1 +``` + +## See also + +[`HMGET`](./hmget.md) | [`HSETEX`](./hsetex.md) | [`HEXPIRE`](./hexpire.md) | [`HTTL`](./httl.md) | [`HPEXPIRETIME`](./hpexpiretime.md) diff --git a/docs/command-reference/hashes/hpexpiretime.md b/docs/command-reference/hashes/hpexpiretime.md new file mode 100644 index 00000000..a3c0b4da --- /dev/null +++ b/docs/command-reference/hashes/hpexpiretime.md @@ -0,0 +1,71 @@ +--- +description: Learn how to use Redis HPEXPIRETIME to retrieve hash-field expiration timestamps in Dragonfly. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# HPEXPIRETIME + + + +## Syntax + + HPEXPIRETIME key FIELDS numfields field [field ...] + +**Time complexity:** O(N) where N is the number of requested fields + +**ACL categories:** @read, @hash, @fast + +Returns the absolute Unix timestamp, in milliseconds, at which each requested +hash field will expire. + +:::note Dragonfly expiration precision + +Dragonfly stores hash-field expiration times with whole-second resolution. +Positive `HPEXPIRETIME` results are therefore multiples of 1000, even when the +expiration was set with a millisecond-based option such as `HGETEX PXAT`. + +::: + +## Return + +[Array reply](https://valkey.io/topics/protocol/#arrays): one integer for each +requested field, in the same order: + +- `-2` if the field does not exist or the hash key does not exist. +- `-1` if the field exists but has no expiration. +- A positive integer representing the field's absolute Unix expiration time in + milliseconds. + +An [error reply](https://valkey.io/topics/protocol/#simple-errors) is returned +if `key` contains a non-hash value or the arguments are invalid. + +## Examples + +Set an expiration on one field, then inspect fields with and without an +expiration: + +```shell +dragonfly> HSET account:42 name Alice status active +(integer) 2 +dragonfly> HGETEX account:42 EX 3600 FIELDS 1 status +1) "active" +dragonfly> HPEXPIRETIME account:42 FIELDS 3 name status missing +1) (integer) -1 +2) (integer) 1785846880000 +3) (integer) -2 +``` + +The positive timestamp depends on the server time when the expiration is set. + +When the hash key does not exist, every requested field returns `-2`: + +```shell +dragonfly> HPEXPIRETIME no-such-key FIELDS 2 first second +1) (integer) -2 +2) (integer) -2 +``` + +## See also + +[`HGETEX`](./hgetex.md) | [`HEXPIRE`](./hexpire.md) | [`HTTL`](./httl.md) diff --git a/docs/command-reference/search/ft.aggregate.md b/docs/command-reference/search/ft.aggregate.md index 7dcefb08..c9d13fe8 100644 --- a/docs/command-reference/search/ft.aggregate.md +++ b/docs/command-reference/search/ft.aggregate.md @@ -16,6 +16,7 @@ description: Runs a search query and performs aggregate transformations [WITHSCORES] [ADDSCORES] [SCORER scorer] + [BM25STD_TANH_FACTOR factor] [PARAMS nargs name value [name value ...]] [DIALECT dialect] @@ -41,7 +42,8 @@ is index name. You must first create the index using [`FT.CREATE`](./ft.create.m query is text query to search. If it's more than a single word, put it in quotes. -Refer to [query syntax](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/) for more details. +Both `FLAT` and `HNSW` indexes support KNN and `VECTOR_RANGE` queries. HNSW queries can override `EF_RUNTIME` for KNN search and `EPSILON` for range search. A vector distance score alias defined by the query can be referenced by aggregation operations. +Refer to the [Valkey Search query syntax](https://valkey.io/topics/search-query/) for more details. ## Optional arguments @@ -132,7 +134,7 @@ adds the document score to each result as the `__score` field. When no `SCORER`
SCORER scorer -specifies the scoring function used to compute the score. Supported scorers are `BM25STD`, `TFIDF`, and `TFIDF.DOCNORM`. On its own `SCORER` only sets the scoring function — it does not add a visible score to the output; combine it with `ADDSCORES` to expose the computed score as `__score`. +specifies the scoring function used to compute the score. Supported scorers are `BM25STD`, `BM25STD.NORM`, `BM25STD.TANH`, `TFIDF`, and `TFIDF.DOCNORM`. On its own `SCORER` only sets the scoring function — it does not add a visible score to the output; combine it with `ADDSCORES` to expose the computed score as `__score`. With `BM25STD.TANH`, `BM25STD_TANH_FACTOR` optionally sets the positive integer scaling factor; its default is `4`.
@@ -183,4 +185,4 @@ dragonfly> FT.AGGREGATE products "*" GROUPBY 1 @category REDUCE AVG 1 @price AS ## Related topics -- [RediSearch](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/) +- [Valkey Search](https://valkey.io/topics/search/) diff --git a/docs/command-reference/search/ft.create.md b/docs/command-reference/search/ft.create.md index 9c2267b6..231e88a0 100644 --- a/docs/command-reference/search/ft.create.md +++ b/docs/command-reference/search/ft.create.md @@ -45,49 +45,49 @@ after the SCHEMA keyword, declares which fields to index: Field types are: - - `TEXT [WITHSUFFIXTRIE]` - Allows searching for words against the text value in this attribute. + - `TEXT [WEIGHT {weight}] [NOSTEM] [WITHSUFFIXTRIE]` - Allows searching for words against the text value in this attribute. + * `WEIGHT {weight}` - adjusts the field's contribution to relevance scores. The default is `1`. + * `NOSTEM` - disables stemming for this field. * `WITHSUFFIXTRIE` - builds a suffix trie for efficient suffix and infix queries. - `TAG [SEPARATOR {char}] [CASESENSITIVE] [WITHSUFFIXTRIE]` - Allows exact-match queries, such as categories or primary keys, against the value in this attribute. * `SEPARATOR {char}` - indicates how text is split into individual tags. Default is `,`. * `CASESENSITIVE` - preserve original case for tags. Default is case insensitive. * `WITHSUFFIXTRIE` - builds a suffix trie for efficient suffix and infix queries. - For more information, see [tag fields](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/tags/). + For more information, see [Valkey Search data formats](https://valkey.io/topics/search-data-formats/). - `NUMERIC [BLOCKSIZE {size}]` - Allows numeric range queries against the value in this attribute. * `BLOCKSIZE {size}` - block size for the range tree data structure. Default is optimized based on data size. - See [query syntax](https://redis.io/docs/latest/develop/interact/search-and-query/query/) for details on how to use numeric ranges. + See [Valkey Search query syntax](https://valkey.io/topics/search-query/) for details on how to use numeric ranges. - `VECTOR` - Allows vector similarity queries against the value in this attribute. - For more information, see [vector fields](https://redis.io/docs/latest/develop/ai/search-and-query/query/vector-search/). + For more information, see [Valkey Search query syntax](https://valkey.io/topics/search-query/). - `GEO` - Allows geographic range queries against the value in this attribute. :::note About `VECTOR` -- Full documentation on vector options is available [here](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/). +- Full documentation on vector options is available in the [Valkey FT.CREATE reference](https://valkey.io/commands/ft.create/). - Currently, Dragonfly has limited support for vector options. - You can specify either the `FLAT` or the `HNSW` index type. - - For both index types, `DIM`, `DISTANCE_METRIC`, and `INITIAL_CAP` options can be specified. - - For the `DISTANCE_METRIC` option, only `L2` and `COSINE` are supported. + - For both index types, `TYPE`, `DIM`, `DISTANCE_METRIC`, and `INITIAL_CAP` options can be specified. + - `TYPE` supports `FLOAT32`, `FLOAT64`, `FLOAT16`, `BFLOAT16`, `INT8`, and `UINT8`. + - `DISTANCE_METRIC` supports `L2`, `IP`, and `COSINE`. + - `HNSW` additionally supports `M`, `EF_CONSTRUCTION`, `EF_RUNTIME`, and `EPSILON`. ::: Field options are: - `SORTABLE` - `NUMERIC`, `TAG`, `TEXT` attributes can have an optional **SORTABLE** argument. - As the user [sorts the results by the value of this attribute](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/sorting/), the results are available with very low latency. - Note that his adds memory overhead, so consider not declaring it on large text attributes. - You can sort an attribute without the `SORTABLE` option, but the latency is not as good as with `SORTABLE`. - -:::note About `SORTABLE` -Dragonfly does **not** support sorting without the `SORTABLE` option. -::: + Dragonfly requires this option before the field can be used for sorting. + When the user [sorts results by this attribute](https://valkey.io/commands/ft.search/), the results are available with very low latency. + This adds memory overhead, so consider not declaring it on large text attributes. - `NOINDEX` - Attributes can have the `NOINDEX` option, which means they will not be indexed. This is useful in conjunction with `SORTABLE`, to create attributes whose update using PARTIAL will not cause full reindexing of the document. If an attribute has NOINDEX and doesn't have SORTABLE, it will just be ignored by the index. :::note About ignored field options The following field options are accepted but ignored for compatibility with Redis: -- `UNF`, `NOSTEM` - ignored without arguments -- `WEIGHT`, `PHONETIC` - ignored with their arguments +- `UNF` - ignored without arguments +- `PHONETIC` - ignored with its argument - `INDEXMISSING`, `INDEXEMPTY` - ignored without warning ::: @@ -188,6 +188,6 @@ dragonfly> FT.CREATE idx2 ON JSON SCHEMA title TEXT categories TAG ## Related topics -- [RediSearch](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/) +- [Valkey Search](https://valkey.io/topics/search/) - [Hash](../hashes/hset.md) - [JSON](../json/json.set.md) diff --git a/docs/command-reference/search/ft.info.md b/docs/command-reference/search/ft.info.md index a9f3ca60..0dff12e5 100644 --- a/docs/command-reference/search/ft.info.md +++ b/docs/command-reference/search/ft.info.md @@ -8,7 +8,7 @@ description: Returns information and statistics on the index FT.INFO index -**Time complexity:** O(1) +**Time complexity:** Proportional to the number of shards and the amount of index metadata returned. **ACL categories:** @ft_search @@ -26,23 +26,25 @@ is index name. You must first create the index using [`FT.CREATE`](./ft.create.m ## Return -`FT.INFO` returns an array reply with pairs of keys and values. +`FT.INFO` returns a flat array reply with pairs of keys and values under both RESP2 and RESP3. Returned values include: - `index_name`: name of the index upon creation by using [`FT.CREATE`](./ft.create.md). -- `index_definition`: contains information about the index configuration, including `key_type`, `prefixes`, and `default_score`. -- `index_options`: index-level options (may be empty). +- `index_definition`: contains information about the index configuration, including `key_type`, `prefixes`, `default_language`, optional `language_field`, and `default_score`. +- `index_options`: index-level options, including `NOOFFSETS` when configured (may be empty). - `attributes`: index schema - for each field contains: - `identifier`: the original field name or JSONPath - `attribute`: the field alias (or same as identifier if no alias provided) - `type`: field type (TEXT, TAG, NUMERIC, VECTOR, GEO) - - field-specific options such as `SORTABLE`, `NOINDEX`, `SEPARATOR` (for TAG fields), `algorithm`, `dim`, `distance_metric` (for VECTOR fields), and `blocksize` (for NUMERIC fields) + - field-specific options such as `SORTABLE`, `NOINDEX`, `WEIGHT` (for TEXT fields), `SEPARATOR` (for TAG fields), `algorithm`, `data_type`, `dim`, `distance_metric`, and algorithm-specific parameters (for VECTOR fields), and `blocksize` (for NUMERIC fields) - `num_docs`: Number of documents in the index. - `indexing`: whether the index is currently being built (`1`) or not (`0`). - `percent_indexed`: fraction of the data that has been indexed so far. - `stopwords_list`: custom stopwords list (only present when custom stopwords are configured). +The order of entries within `attributes` is not guaranteed and may differ between calls. + ## Examples
@@ -50,7 +52,7 @@ Returned values include: ```shell dragonfly> HSET blog:post:1 title "blog post 1" published_at 1701210030 category "default" description "this is a blog" -(error) ERR wrong number of arguments for 'hset' command +(integer) 4 dragonfly> FT.CREATE idx ON HASH PREFIX 1 blog:post: SCHEMA title TEXT SORTABLE published_at NUMERIC SORTABLE category TAG SORTABLE description TEXT NOINDEX OK dragonfly> FT.INFO idx @@ -61,27 +63,31 @@ dragonfly> FT.INFO idx 2) HASH 3) prefixes 4) 1) "blog:post:" - 5) default_score - 6) (integer) 1 + 5) default_language + 6) english + 7) default_score + 8) (integer) 1 5) index_options 6) (empty array) 7) attributes 8) 1) 1) identifier - 2) category + 2) title 3) attribute - 4) category + 4) title 5) type - 6) TAG + 6) TEXT 7) SORTABLE - 8) SEPARATOR - 9) , + 8) WEIGHT + 9) 1.000000 2) 1) identifier - 2) title + 2) description 3) attribute - 4) title + 4) description 5) type 6) TEXT - 7) SORTABLE + 7) NOINDEX + 8) WEIGHT + 9) 1.000000 3) 1) identifier 2) published_at 3) attribute @@ -92,14 +98,16 @@ dragonfly> FT.INFO idx 8) blocksize 9) 10000 4) 1) identifier - 2) description + 2) category 3) attribute - 4) description + 4) category 5) type - 6) TEXT - 7) NOINDEX + 6) TAG + 7) SORTABLE + 8) SEPARATOR + 9) , 9) num_docs -10) (integer) 0 +10) (integer) 1 11) indexing 12) (integer) 0 13) percent_indexed @@ -113,4 +121,4 @@ dragonfly> FT.INFO idx ## Related topics -- [RediSearch](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/) +- [Valkey Search](https://valkey.io/topics/search/) diff --git a/docs/command-reference/search/ft.search.md b/docs/command-reference/search/ft.search.md index 90a4c118..22eab6d0 100644 --- a/docs/command-reference/search/ft.search.md +++ b/docs/command-reference/search/ft.search.md @@ -10,6 +10,7 @@ description: Searches the index with a query, returning docs or just IDs [NOCONTENT] [WITHSCORES] [SCORER scorer_name] + [BM25STD_TANH_FACTOR factor] [LOAD count identifier [AS property] [ identifier [AS property] ...]] [RETURN count identifier [AS property] [ identifier [AS property] ...]] [SORTBY sortby [ ASC | DESC] [WITHCOUNT]] @@ -17,7 +18,7 @@ description: Searches the index with a query, returning docs or just IDs [PARAMS nargs name value [ name value ...]] [FILTER field min max] -**Time complexity:** O(N) +**Time complexity:** Varies with query structure, index type, scoring, sorting, and result set size. **ACL categories:** @ft_search ## Description @@ -25,7 +26,7 @@ description: Searches the index with a query, returning docs or just IDs Search the index with a textual query, returning either documents or just IDs. For usage, see [examples](#examples) below. -Dragonfly supports HNSW vector range search via the `VECTOR_RANGE` query operator. Use it in the query string as `@field:[VECTOR_RANGE radius $vec]` to find all vectors within a given distance. Optionally, append `=>{$YIELD_DISTANCE_AS: alias}` to include the distance score in results. HNSW vector range search is mutually exclusive with KNN vector search. +Dragonfly supports KNN and vector range searches with both `FLAT` and `HNSW` indexes. HNSW KNN queries can override `EF_RUNTIME` inline or in a query-attribute block. Use the `VECTOR_RANGE` query operator as `@field:[VECTOR_RANGE radius $vec]` to find all vectors within a given distance; HNSW range queries can override `EPSILON`. Optionally, append `=>{$YIELD_DISTANCE_AS: alias}` to include the distance score in results. A vector range search is mutually exclusive with KNN search. For HNSW, only one vector range clause is supported; it can be used by itself or combined with a filter using AND, while OR and NOT are not supported. ## Required arguments @@ -39,13 +40,17 @@ is index name. You must first create the index using [`FT.CREATE`](./ft.create.m query is text query to search. If it's more than a single word, put it in quotes. -Refer to [query syntax](https://redis.io/docs/latest/develop/interact/search-and-query/query/) for more details. +Refer to the [Valkey Search query syntax](https://valkey.io/topics/search-query/) for more details. The query language supports the following operators: - `~term` — optional match: documents matching the term are scored higher but the term is not required. - `w'glob*pattern'` — glob wildcard matching on TEXT and TAG fields (e.g., `w'py*'` matches `python`). - `"exact phrase"` — exact phrase search; use `"term1 term2"~N` (slop) to allow up to `N` word gaps between terms. +- `term=>{$weight: value}` — applies a query-time weight to a term. Term weights can also be used inside field groups. + +Configured stopwords are removed from textual query terms before search. +`FT.CREATE ... STOPWORDS 0` disables stopword removal.
## Optional arguments @@ -70,8 +75,12 @@ includes the relevance score of each result in the reply. When `WITHSCORES` is s uses the specified scoring function to rank results. Supported scorers: - `BM25STD` — BM25 with standard per-field TF tracking (default when `WITHSCORES` is used). +- `BM25STD.NORM` — a normalized BM25STD scoring variant. +- `BM25STD.TANH` — a BM25STD scoring variant using tanh normalization. - `TFIDF` — classic TF-IDF scoring. - `TFIDF.DOCNORM` — TF-IDF with document-length normalization. + +With `BM25STD.TANH`, the optional `BM25STD_TANH_FACTOR` argument sets the positive integer used to scale scores before tanh normalization. Its default is `4`.
@@ -157,12 +166,7 @@ When `WITHSCORES` is used, each result entry includes the relevance score betwee ## Complexity -`FT.SEARCH` complexity is O(N) for single word queries, where `N` is the number of the results in the result set. -Finding all the documents that have a specific term is O(1). -However, a scan on all those documents is needed to load the documents data from Hash or JSON values and return them. - -The time complexity for more complex queries varies, but in general it's proportional to the number of words, -the number of intersection points between them and the number of results in the result set. +For a single-term text query, locating the term's posting list is O(1), while loading and returning `N` matching documents is O(N). More complex text queries also depend on the number of terms and intersections. Vector search, scoring, and sorting costs depend on the selected index and query options. ## Examples @@ -263,5 +267,5 @@ dragonfly> FT.SEARCH books-idx "python" WITHSCORES SCORER TFIDF ## Related topics -- [RediSearch](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search/) -- [Query Syntax](https://redis.io/docs/latest/develop/interact/search-and-query/query/) +- [Valkey Search](https://valkey.io/topics/search/) +- [Query Syntax](https://valkey.io/topics/search-query/) diff --git a/docs/command-reference/server-management/info.md b/docs/command-reference/server-management/info.md index 613ce8e9..8757d116 100644 --- a/docs/command-reference/server-management/info.md +++ b/docs/command-reference/server-management/info.md @@ -12,14 +12,16 @@ import PageTitle from '@site/src/components/PageTitle'; INFO [section [section ...]] -**Time complexity:** O(1) +**Time complexity:** Depends on the requested sections and the metrics they collect. **ACL categories:** @slow, @dangerous The `INFO` command returns information and statistics about the server in a format that is simple to parse by computers and easy to read by humans. +When `INFO` is called through a TLS listener, the `server` section can also +include the subject, issuer, and validity period of the listener's certificate. -The optional parameter can be used to select a specific section of information: +The optional parameters can be used to select one or more sections of information: * `server`: General information about the Dragonfly server * `clients`: Client connections section @@ -29,6 +31,7 @@ The optional parameter can be used to select a specific section of information: * `replication`: Master/replica replication information * `cpu`: CPU consumption statistics * `commandstats`: Command statistics +* `latencystats`: Command latency statistics * `keyspace`: Database related statistics * `errorstats`: Error statistics @@ -36,7 +39,8 @@ It can also take the following values: * `all`: Return all sections (excluding module generated ones) -When no parameter is provided, the `default` option is assumed. +When no parameter is provided, the default output is returned. It includes the +`memory` and `latencystats` sections, but not the `commandstats` section. ## Return @@ -127,6 +131,8 @@ used_cpu_sys_children:0.0 used_cpu_user_children:0.0 used_cpu_sys_main_thread:0.32040 used_cpu_user_main_thread:4.681903 + +# Latencystats ``` ## Notes diff --git a/docs/command-reference/server-management/reset.md b/docs/command-reference/server-management/reset.md new file mode 100644 index 00000000..3a7f10ad --- /dev/null +++ b/docs/command-reference/server-management/reset.md @@ -0,0 +1,79 @@ +--- +description: Learn how to use Redis RESET to clear connection-scoped state in Dragonfly. +--- + +import PageTitle from '@site/src/components/PageTitle'; + +# RESET + + + +## Syntax + + RESET + +**Time complexity:** O(1) + +**ACL categories:** @fast, @connection + +Clears connection-scoped state without closing the connection. Dragonfly: + +- Aborts an active `MULTI` transaction and unwatches all keys. +- Removes channel and pattern Pub/Sub subscriptions. +- Exits `MONITOR` mode. +- Disables `CLIENT TRACKING`. +- Selects database 0. +- Switches the connection back to RESP2. +- Restores the default ACL identity and clears authentication. + +If authentication is required, the client must call `AUTH` again after +`RESET`. The command changes only connection state; it does not delete data. + +:::note Dragonfly v1.40 compatibility + +Dragonfly preserves the name set with `CLIENT SETNAME` when the connection is +reset. Valkey clears the client name. + +::: + +## Return + +[Simple string reply](https://valkey.io/topics/protocol/#simple-strings): +`RESET`. + +## Examples + +Abort a transaction without closing the connection: + +```shell +dragonfly> MULTI +OK +dragonfly> SET key value +QUEUED +dragonfly> RESET +RESET +dragonfly> EXEC +(error) ERR EXEC without MULTI +``` + +`RESET` selects database 0 but does not delete data from the previously +selected database: + +```shell +dragonfly> SELECT 1 +OK +dragonfly> SET reset:key value +OK +dragonfly> RESET +RESET +dragonfly> GET reset:key +(nil) +dragonfly> SELECT 1 +OK +dragonfly> GET reset:key +"value" +``` + +## See also + +[`AUTH`](./auth.md) | [`SELECT`](./select.md) | [`QUIT`](./quit.md) diff --git a/docs/managing-dragonfly/cluster-mode.md b/docs/managing-dragonfly/cluster-mode.md index 7102ea90..c846b8ce 100644 --- a/docs/managing-dragonfly/cluster-mode.md +++ b/docs/managing-dragonfly/cluster-mode.md @@ -23,7 +23,7 @@ $> dragonfly --cluster_mode=emulated $> redis-cli # See which cluster commands are supported -dragonfly$> CLUSTER HELP +dragonfly> CLUSTER HELP ``` Now you can connect to your Dragonfly instance with a Redis client that supports the Redis Cluster protocol, @@ -42,6 +42,8 @@ b'bar' - Your application code may be using a regular Redis client that does not require cluster commands as well. - By default, if the `--cluster_mode` server flag is not specified, Dragonfly runs in this emulated cluster mode. +- In emulated mode, `cluster_announce_ip` and `announce_port` can be changed at runtime with `CONFIG SET`. + Subsequent cluster topology replies use the new values. ## Multi-Shard Cluster @@ -54,8 +56,8 @@ A Dragonfly Cluster is similar to a Redis/Valkey Cluster: - Multiple Dragonfly servers participate in a single logical data store. - It provides all cluster-related commands required by Redis client libraries. -- It [distributes keys](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/) in the same way Redis Cluster does. -- It supports [hashtags](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags) in the same way Redis Cluster does. +- It [distributes keys](https://valkey.io/topics/cluster-spec/) in the same way as Valkey Cluster. +- It supports [hash tags](https://valkey.io/topics/cluster-spec/#hash-tags) in the same way as Valkey Cluster. **There is one important distinction regarding Dragonfly Cluster:** Dragonfly only provides a _data plane_ (which is the Dragonfly server), but it does **NOT** provide a @@ -193,13 +195,14 @@ such as adding/removing nodes, changing hostnames, etc. ### Notes +- Multi-shard cluster mode supports only database 0. - You could look at [`cluster_mgr.py`](https://github.com/dragonflydb/dragonfly/blob/main/tools/cluster_mgr.py) as a reference for how to set up and configure a cluster. This script starts a cluster locally, but much of its logic can be reused for nodes present on remote machines as well. -- If you're getting errors trying to issue the `DFLYCLUSTER CONFIG`, check Dragonfly's logs (you +- If you're getting errors trying to issue the `DFLYCLUSTER CONFIG`, check Dragonfly's logs (if you can pass `--logtostderr` temporarily) to see why the config was rejected. -- Dragonfly supports the migration of data slots between nodes as well. Detailed explaination can +- Dragonfly supports the migration of data slots between nodes as well. A detailed explanation can be found in one of our blog posts [here](https://www.dragonflydb.io/blog/redis-and-dragonfly-cluster-design-comparison). We will update the documentation to reflect these steps soon. diff --git a/docs/managing-dragonfly/flags.md b/docs/managing-dragonfly/flags.md index ed680159..aba281d4 100644 --- a/docs/managing-dragonfly/flags.md +++ b/docs/managing-dragonfly/flags.md @@ -19,7 +19,7 @@ flags which include specified substring in either in the name, description or pa ### `--port` Redis port. 0 disables the port, -1 will bind on a random available port. - `default: 6379` + `default: 6379` ### `--cache_mode` If true, the backend behaves like a cache, by evicting entries when getting close to maxmemory limit @@ -39,7 +39,7 @@ flags which include specified substring in either in the name, description or pa ### `--dbnum` Number of databases. - `default: 16` + `default: 16` ### `--bind` Bind address. If empty - binds on all interfaces. It's not advised due to security implications. @@ -49,7 +49,7 @@ flags which include specified substring in either in the name, description or pa ### `--requirepass` Password for AUTH authentication. - `default: ""` + `default: ""` ### `--dbfilename` The filename to save/load the DB. @@ -66,15 +66,20 @@ flags which include specified substring in either in the name, description or pa `default:` +### `--snapshot_egress_limit_bytes` + Per-shard-thread socket egress bandwidth budget in bytes per second. Each shard throttles its snapshot traversal loop to stay under this rate. Accepts human-readable sizes such as `100mb` and `1gb`. A value of 0 disables throttling. + + `default: 0B` + ### `--admin_bind` - If set, the admin console TCP connection would be bind to the given address. - This supports both HTTP and RESP protocols. + If set, the admin console TCP connection would be bind to the given address. + This supports both HTTP and RESP protocols. `default: ""` ### `--admin_port` - If set, would enable admin access to console on the assigned port. - This supports both HTTP and RESP protocols. + If set, would enable admin access to console on the assigned port. + This supports both HTTP and RESP protocols. `default: 0` @@ -86,7 +91,7 @@ flags which include specified substring in either in the name, description or pa ### `--max_multi_bulk_len` Maximum multi-bulk (array) length that is allowed to be accepted when parsing RESP protocol - `default: 65536` + `default: 65536` ### `--migrate_connections` When enabled, Dragonfly will try to migrate connections to the target thread on which they operate. Currently this is @@ -100,12 +105,17 @@ flags which include specified substring in either in the name, description or pa `default: false` ### `--publish_buffer_limit` - Amount of memory to use for storing pub commands in bytes - per IO thread. + Amount of memory to use for storing publish commands per IO thread. This is the soft Pub/Sub back-pressure limit; publishers are only parked once the per-thread subscriber memory reaches this value times the internal hard-limit multiplier. - `default: 128.00MiB` + `default: 196.00MiB` + +### `--pubsub_slow_subscriber_timeout_ms` + If a subscriber connection keeps a Pub/Sub socket write blocked for at least this many milliseconds, Dragonfly closes it when either its queued Pub/Sub memory reaches one-sixteenth of `publish_buffer_limit` or the per-IO-thread subscriber memory is above `publish_buffer_limit`. A value of 0 disables this slow-subscriber protection. This is a startup-only flag, like `publish_buffer_limit`. + + `default: 0` ### `--pipeline_squash` - Number of queued pipelined commands above which squashing is enabled, 0 means disabled. + Number of queued pipelined commands above which squashing is enabled, 0 means disabled. `default: 1` @@ -115,18 +125,18 @@ flags which include specified substring in either in the name, description or pa `default: true` ### `--request_cache_limit` - Amount of memory to use for request cache in bytes per IO thread. + Amount of memory to use for request cache in bytes per IO thread. `default: 64.00MiB` ### `--tcp_nodelay` - Configures dragonfly connections with socket option TCP_NODELAY. + Configures dragonfly connections with socket option TCP_NODELAY. `default: true` ### `--conn_io_thread_start` Starting thread id for handling server connections. - + `default: 0` ### `--conn_io_threads` @@ -142,7 +152,7 @@ flags which include specified substring in either in the name, description or pa ### `--container_iteration_yield_interval_usec` Yield the fiber every N microseconds during container iteration. 0 disables yielding. - `default: 0` + `default: 500` ### `--tcp_keepalive` The period in seconds of inactivity after which keep-alives are triggerred, @@ -171,7 +181,7 @@ flags which include specified substring in either in the name, description or pa `default: ""` ### `--tls_cert_file` - Cert file(public key) for tls connections. + Cert file(public key) for tls connections. `default: ""` @@ -180,11 +190,6 @@ flags which include specified substring in either in the name, description or pa `default: ""` -### `--rename_command` - Change the name of commands, format is: `=, =` - - `default:` - ### `--restricted_commands` Commands restricted to connections on the admin port. @@ -192,30 +197,28 @@ flags which include specified substring in either in the name, description or pa ### `--lock_on_hashtags` When true, locks are done in the \{hashtag\} level instead of key level. Only use this with `--cluster_mode=emulated|yes`. - + `default: false` ### `--enable_heartbeat_eviction` - Enable eviction during heartbeat when memory is under pressure. + Enable eviction during heartbeat when memory is under pressure. `default: true` ### `--max_eviction_per_heartbeat` + The maximum number of key-value pairs that will be deleted in each eviction when heartbeat based eviction is + triggered under memory pressure. - The maximum number of key-value pairs that will be deleted in each eviction when heartbeat based eviction is - triggered under memory pressure. - - `default: 100` + `default: 100` ### `--max_segment_to_consider` - The maximum number of dashtable segments to scan in each eviction when heartbeat based eviction is triggered under memory pressure. `default: 4` ### `--force_epoll` - If true - uses linux epoll engine underneath. Can fit for kernels older than 5.10. + If true - uses linux epoll engine underneath. Can fit for kernels older than 5.10. `default: false` @@ -225,18 +228,17 @@ flags which include specified substring in either in the name, description or pa `default: ""` ### `--unixsocket` - If not empty - specifies path for the Unix socket that will be used for listening for incoming connections. `default: ""` ### `--unixsocketperm` Set permissions for unixsocket, in octal value. - + `default: ""` ### `--version_check` - If true, Will monitor for new releases on Dragonfly servers once a day. + If true, Will monitor for new releases on Dragonfly servers once a day. `default: true` @@ -246,7 +248,7 @@ flags which include specified substring in either in the name, description or pa `default: 100` ### `--masterauth` - Password for authentication with master. + Password for authentication with master. `default: ""` @@ -258,24 +260,26 @@ flags which include specified substring in either in the name, description or pa ### `--mem_defrag_page_utilization_threshold` Memory page under utilization threshold. Ratio between used and committed size, below this, memory in - this page will defragmented. + this page will defragmented. `default: 0.8` ### `--mem_defrag_threshold` - Minimum percentage of used memory relative to maxmemory cap before running defragmentation. + Minimum percentage of used memory relative to maxmemory cap before running defragmentation. `default: 0.7` ### `--mem_defrag_waste_threshold` - The ratio of wasted/committed memory above which we run defragmentation. + The ratio of wasted/committed memory above which we run defragmentation. `default: 0.2` ### `--shard_round_robin_prefix` + Deprecated and will be removed. + When non-empty, keys which start with this prefix are not distributed across shards based on their value but instead - via round-robin. Use cautiously! This can efficiently support up to a few hundreds of prefixes. Note: prefix is - looked inside hashtags when cluster mode is enabled. + via round-robin. Use cautiously! This can efficiently support up to a few hundreds of prefixes. Note: the prefix is + inspected inside hashtags when cluster mode is enabled. `default: ""` @@ -291,7 +295,7 @@ flags which include specified substring in either in the name, description or pa `default: 0.5` ### `--tiered_upload_threshold` - Ratio of free memory (free/max memory) below which uploading stops. + Ratio of free memory (free/max memory) below which uploading stops. `default: 0.1` @@ -300,6 +304,11 @@ flags which include specified substring in either in the name, description or pa `default: 64` +### `--tiered_min_ttl_to_offload_ms` + Minimum remaining TTL in milliseconds for a value to be eligible for offloading. + + `default: 5000` + ### `--tiered_max_pending_stash_bytes` Maximum bytes in-flight to disk before rejecting new stashes or applying client backpressure. Allows batching writes to saturate disk I/O even with few clients. @@ -307,7 +316,7 @@ flags which include specified substring in either in the name, description or pa ### `--keys_output_limit` Maximum number of keys output by keys command. - + `default: 8192` ### `--backing_file_direct` @@ -315,14 +324,29 @@ flags which include specified substring in either in the name, description or pa `default: true` +### `--tiering_disk_storage_initial_size` + Initial disk storage size. + + `default: 256.00MiB` + ### `--list_compress_depth` - Compress depth of the list. Default is no compression. + Compress depth of the list. Default is no compression. `default: 0` +### `--list_compress_dict_threshold` + Minimum list malloc usage in bytes before attempting ZSTD dictionary compression. A value of 0 disables it. Compression is synchronous and may block the thread. + + `default: 0` + +### `--list_compress_level` + Compression level for QList ZSTD dictionaries. A value of -1 uses ZSTD's default tuning. + + `default: -1` + ### `--list_max_listpack_size` Maximum listpack size, default is 8kb. - + `default: -2` ### `--listpack_max_bytes` @@ -341,27 +365,27 @@ flags which include specified substring in either in the name, description or pa `default: false` ### `--memcached_port` - Memcached port: + Memcached port: `default: 0` ### `--multi_eval_squash_buffer` Max buffer for squashed commands per script: - `default: 4096` + `default: 8096` ### `--multi_exec_squash` - Whether multi exec will squash single shard commands to optimize performance. + Whether multi exec will squash single shard commands to optimize performance. `default: true` ### `--num_shards` Number of database shards, 0 - to choose automatically. - + `default: 0` ### `--tls_replication` - Enable TLS on replication. + Enable TLS on replication. `default: false` @@ -384,12 +408,12 @@ flags which include specified substring in either in the name, description or pa - `3` — `MULTI_ENTRY_LZ4` — multi entry lz4 compression on df snapshot and single entry on rdb snapshot. ### `--master_connect_timeout_ms` - Timeout for establishing connection to a replication master. + Timeout for establishing connection to a replication master. `default: 20000` ### `--master_reconnect_timeout_ms` - Timeout for re-establishing connection to a replication master. + Timeout for re-establishing connection to a replication master. `default: 1000` @@ -404,19 +428,17 @@ flags which include specified substring in either in the name, description or pa `default: 1000` ### `--default_lua_flags` - Configure default flags for running Lua scripts: - - Use `allow-undeclared-keys` to allow accessing undeclared keys, - - Use `disable-atomicity` to allow running scripts non-atomically. + - Use `allow-undeclared-keys` to allow accessing undeclared keys, + - Use `disable-atomicity` to allow running scripts non-atomically. - Specify multiple values separated by space, for example `allow-undeclared-keys disable-atomicity` - runs scripts non-atomically and allows accessing undeclared keys. + Specify multiple values separated by space, for example `allow-undeclared-keys disable-atomicity` + runs scripts non-atomically and allows accessing undeclared keys. `default: ""` ### `--lua_auto_async` - If enabled, call/pcall with discarded values are automatically replaced with acall/apcall. `default: false` @@ -427,32 +449,32 @@ flags which include specified substring in either in the name, description or pa `default: true` ### `--epoll_file_threads` - Thread size for file workers when running in epoll mode, default is hardware concurrent threads. + Thread size for file workers when running in epoll mode, default is hardware concurrent threads. `default: 0` ### `--maxclients` Maximum number of concurrent clients allowed. - + `default: 64000` ### `--s3_ec2_metadata` - Whether to load credentials and configuration from EC2 metadata. + Whether to load credentials and configuration from EC2 metadata. `default: false` ### `--s3_endpoint` - Endpoint for s3 snapshots, default uses aws regional endpoint. + Endpoint for s3 snapshots, default uses aws regional endpoint. `default: ""` ### `--s3_sign_payload` - Whether to sign the s3 request payload when uploading snapshots. + Whether to sign the s3 request payload when uploading snapshots. `default: true` ### `--s3_use_https` - Whether to use https for s3 endpoints. + Whether to use https for s3 endpoints. `default: true` @@ -462,7 +484,7 @@ flags which include specified substring in either in the name, description or pa `default: true` ### `--slowlog_log_slower_than` - Add commands slower than this threshold to slow log. The value is expressed in microseconds + Add commands slower than this threshold to slow log. The value is expressed in microseconds and if it's negative disables the slowlog. `default: 10000` @@ -479,15 +501,15 @@ flags which include specified substring in either in the name, description or pa ### `--serialization_max_chunk_size` Maximum size of a value that may be serialized at once during snapshotting or full sync. - Values bigger than this threshold will be serialized using streaming serialization. + Values bigger than this threshold will be serialized using streaming serialization. 0 - to disable streaming mode. - + `default: 65536` ### `--serialization_tagged_chunks` Allow serializer output to be split into tagged chunks and reassembled by receiver. - `default: false` + `default: true` ### `--aclfile` Path and name to aclfile. @@ -495,7 +517,7 @@ flags which include specified substring in either in the name, description or pa `default: ""` ### `--acllog_max_len` - Specify the number of log entries. Logs are kept locally for each thread and therefore + Specify the number of log entries. Logs are kept locally for each thread and therefore the total number of entries are `acllog_max_len * threads` `default: 32` @@ -521,7 +543,7 @@ flags which include specified substring in either in the name, description or pa `default: 8192` ### `--proactor_affinity_mode` - Can be on, off or auto. + Can be on, off or auto. `default: "on"` @@ -531,7 +553,7 @@ flags which include specified substring in either in the name, description or pa `default: 0` ### `--flagfile` - Comma-separated list of files to load flags from. + Comma-separated list of files to load flags from. `default:` @@ -561,18 +583,18 @@ flags which include specified substring in either in the name, description or pa `default: false` ### `--max_log_size` - Approx. maximum log file size (in MB). A value of 0 will be silently overridden to 1. + Approx. maximum log file size (in MB). A value of 0 will be silently overridden to 1. - `default: 200` + `default: 1800` ### `--minloglevel` - Messages logged at a lower level than this don't actually get logged anywhere. + Messages logged at a lower level than this don't actually get logged anywhere. `default: 0` ### `--stderrthreshold` Log messages at or above this level are copied to stderr in addition to logfiles. This flag obsoletes --alsologtostderr - + `default: 2` ### `--command_alias` @@ -660,6 +682,11 @@ flags which include specified substring in either in the name, description or pa `default: true` +### `--enable_pipeline_squashing_v2` + Enable vectorized pipeline squashing for the V2 dispatch loop. It groups consecutive single-shard pipeline commands by shard and executes them in parallel. + + `default: true` + ### `--enable_resp_io_loop_v2` Enable the event-driven IoLoopV2 for non-TLS RESP connections. @@ -675,6 +702,11 @@ flags which include specified substring in either in the name, description or pa `default: 0.1` +### `--experimental_cascaded_partial_sync` + Enable experimental cascaded partial synchronization. + + `default: false` + ### `--experimental_cluster_shard_by_slot` If true, cluster mode is enabled and sharding is done by slot. Otherwise, sharding is done by hash tag. @@ -685,11 +717,6 @@ flags which include specified substring in either in the name, description or pa `default: false` -### `--experimental_replicaof_v2` - Use ReplicaOfV2 algorithm for initiating replication. - - `default: true` - ### `--expose_http_api` If set, will expose a POST `/api` handler for sending redis commands as json array. @@ -715,6 +742,11 @@ flags which include specified substring in either in the name, description or pa `default: false` +### `--get_zero_copy` + If true, `GET` returns a borrowed view into the CompactObj raw payload for large raw strings. If false, it uses the materializing path. This flag can be used to compare the zero-copy and materializing `GET` paths. + + `default: true` + ### `--huffman_table` A comma separated map: `domain1:code1,domain2:code2,...` where domain can currently be only `KEYS` or `STRINGS`, code is a base64-encoded huffman table exported via `DEBUG COMPRESSION EXPORT`. If the flag is empty no huffman compression is applied. @@ -738,20 +770,20 @@ flags which include specified substring in either in the name, description or pa ### `--keep_legacy_memory_metrics` When true, keeps the legacy metrics format for memory-related info fields. - `default: true` + `default: false` ### `--latency_tracking` If true, track latency for commands. `default: false` -### `--list_experimental_zstd_dict_threshold` - Minimum list malloc usage in bytes before attempting ZSTD dictionary compression. 0 disables. Experimental: compression is synchronous and may block the thread. +### `--list_tiering_threshold` + Tiering threshold for lists. Default - no tiering. `default: 0` -### `--list_tiering_threshold` - Tiering threshold for lists. Default - no tiering. +### `--list_tiering_prefetch_depth` + Before loading a tiered list node, scan up to this many neighboring nodes and issue asynchronous load requests for any that are offloaded. A value of 0 disables prefetching. `default: 0` @@ -880,11 +912,6 @@ flags which include specified substring in either in the name, description or pa `default: false` -### `--oom_deny_commands` - Additional commands that will be marked as denyoom. - - `default:` - ### `--pause_wait_timeout` Timeout in seconds, to set up the pause for all connections for CLIENT PAUSE command and cluster slot migration finalization procedure. @@ -895,6 +922,16 @@ flags which include specified substring in either in the name, description or pa `default: 128.00MiB` +### `--pipeline_parse_in_proactor` + V2 only: parse newly arrived bytes from the proactor `OnRecv` callback while the fiber is parked waiting for parallel work, so the next batch has already grown when execution resumes. + + `default: true` + +### `--pipeline_prioritize_large_batches` + V2 only: in `ParseLoop`, defer executing a parsed pipeline batch and return to the read loop to accumulate more already-available input, so the squasher sees one large batch instead of many small ones. + + `default: true` + ### `--pipeline_queue_limit` Pipeline queue max length. The server will stop reading from the client socket once its pipeline queue crosses this limit, and will resume once it processes excessive requests. This is to prevent OOM states. Users of huge pipeline sizes may require increasing this limit to prevent the risk of deadlocking. See https://github.com/dragonflydb/dragonfly/discussions/3997 for details. @@ -1025,11 +1062,6 @@ flags which include specified substring in either in the name, description or pa `default: 0` -### `--squash_stats_latency_lower_limit` - If set, will not track latency stats below this threshold (usec). - - `default: 0` - ### `--squashed_reply_size_limit` Max bytes allowed for squashing_current_reply_size. If this limit is reached, connections dispatching pipelines won't squash them. @@ -1144,3 +1176,8 @@ flags which include specified substring in either in the name, description or pa If not empty - drop privileges to this user (and their primary group) after binding ports. Accepts username or numeric uid. If `--dir` is set, chowns the data directory to this user. `default: ""` + +### `--write_connection_throttling_sleep_usec` + Sleep period for a write connection in microseconds. A value of 0 disables yielding. + + `default: 0` diff --git a/docs/managing-dragonfly/monitoring.md b/docs/managing-dragonfly/monitoring.md index 48426a55..f1e8aef9 100644 --- a/docs/managing-dragonfly/monitoring.md +++ b/docs/managing-dragonfly/monitoring.md @@ -5,7 +5,7 @@ sidebar_position: 5 # Monitoring -By default, Dragonfly allows HTTP access via its main TCP port (i.e, `6379`) and it exposes Prometheus compatible metrics on `:6379/metrics`. +By default, Dragonfly allows HTTP access through its main TCP port (i.e., `6379`) and exposes Prometheus-compatible metrics at `:6379/metrics`. These include metrics for connection memory and pipelines. Batch I/O counters are available through `INFO stats`, but are not currently exported by the Prometheus endpoint. Check out this complete example of setting up a [Grafana Monitoring Stack with Dragonfly](https://github.com/dragonflydb/dragonfly/tree/main/tools/local/monitoring). @@ -22,4 +22,4 @@ curl: (1) Received HTTP/0.9 when not allowed ## Replication Metrics -The `/metrics` endpoint also exposes replication information. These metrics include details about the replication role of the instance, connected replicas, and replication lag, allowing you to monitor the health and status of your Dragonfly replication setup via Prometheus. +The `/metrics` endpoint also exposes replication information. These metrics include details about the replication role of the instance, connected replicas, replication backlog, and replication lag, allowing you to monitor the health and status of your Dragonfly replication setup via Prometheus. diff --git a/docs/managing-dragonfly/replication.md b/docs/managing-dragonfly/replication.md index ef1ef992..6e4e66e5 100644 --- a/docs/managing-dragonfly/replication.md +++ b/docs/managing-dragonfly/replication.md @@ -7,7 +7,7 @@ sidebar_position: 4 ## Managing Replication -Dragonfly supports a primary-replica high-availability model, similarly to Redis's [replication](https://redis.io/topics/replication). +Dragonfly supports a primary-replica high-availability model, similarly to [Valkey replication](https://valkey.io/topics/replication/). When using replication, Dragonfly creates exact copies of the primary instance. Once configured properly, replicas reconnect to the primary instance any time their connections break and will always aim to remain an exact copy of the primary. @@ -16,7 +16,7 @@ The Dragonfly replication management API is compatible with the Redis API and co If you're not sure whether the Dragonfly instance you're currently connected to is a primary instance or a replica, you can check by running the `ROLE` command: ```bash -dragonfly$> ROLE +dragonfly> ROLE 1) "master" 2) 1) 1) "172.19.0.4" 2) "6379" @@ -35,11 +35,25 @@ The instructions below apply to this type of replication as well, with the only This replication process internally is vastly different from the original Redis replication algorithm, but from the outside, the API is kept the same to make it compatible with the current ecosystem. +:::caution Experimental cascading replication + +Starting with Dragonfly v1.40.0, cascading replication is available behind the +`--experimental_cascaded_partial_sync=true` flag, which is disabled by default. +Start every node in the replication chain with this flag to let a replica serve +as the upstream instance for downstream replicas and support partial +synchronization across the chain. + +If an intermediate replica performs a full synchronization after its upstream +primary changes, it forces its downstream replicas to fully resynchronize so +that the entire chain converges to the new dataset. + +::: + To designate a Dragonfly instance as a replica of another instance on the fly, run the `REPLICAOF` command. This command takes the intended primary instance's hostname or IP address and port as arguments: ```bash -dragonfly$> REPLICAOF hostname_or_IP port +dragonfly> REPLICAOF hostname_or_IP port ``` If the server is already a replica of another primary, it will stop replicating the old primary and immediately start synchronizing with the new one. @@ -48,7 +62,7 @@ It will also discard the entire old dataset. To promote a replica back to being a primary, run the following `REPLICAOF` command: ```bash -dragonfly$> REPLICAOF NO ONE +dragonfly> REPLICAOF NO ONE ``` This will stop the instance from replicating the primary instance but will not discard the dataset it has already replicated. @@ -57,9 +71,9 @@ After running `REPLICAOF NO ONE` on a replica of the failed primary, the former ### Expired Key Deletion on Replicas -By default, replicas do not proactively delete expired keys — they wait for expiry propagation from the primary. -You can change this behavior by starting the replica with the `--replica_delete_expired=true` flag, which causes the replica to proactively delete expired keys on its own, without waiting for the primary to propagate the deletions. -This can reduce memory usage on replicas that have many keys with TTLs, at the cost of a small amount of additional work on the replica. +By default, replicas proactively delete expired keys when those keys are read. +Start a replica with `--replica_delete_expired=false` to disable this behavior and wait for the primary to propagate deletions instead. +Keeping the default can reduce memory usage on replicas that have many keys with TTLs, at the cost of a small amount of additional work on the replica. ## Secure Replication with TLS @@ -132,7 +146,7 @@ Finally, connect to the secondary Dragonfly instance and issue the `REPLICAOF` c ```bash redis-cli --tls --key ./client-key.pem --cert ./client-cert.pem --cacert ./ca-cert.pem -p 6380 -dragonfly$> REPLICAOF PRIMARY_HOST 6379 +dragonfly> REPLICAOF PRIMARY_HOST 6379 ``` Now, the replication works over TLS and is secure. @@ -169,7 +183,7 @@ Then, connect to the secondary Dragonfly instance and issue the `REPLICAOF` comm ```bash redis-cli -p 6382 -dragonfly$> REPLICAOF PRIMARY_HOST 6380 +dragonfly> REPLICAOF PRIMARY_HOST 6380 ``` From now on, the replica **does not** communicate with the primary instance over TLS. @@ -184,7 +198,7 @@ as well as in the `INFO REPLICATION` command output as the `lag` field. ```bash # On the primary instance: -dragonfly$> INFO REPLICATION +dragonfly> INFO REPLICATION # Replication role:master connected_slaves:1 diff --git a/docs/managing-dragonfly/tiering.md b/docs/managing-dragonfly/tiering.md index e049afaf..994b889f 100644 --- a/docs/managing-dragonfly/tiering.md +++ b/docs/managing-dragonfly/tiering.md @@ -27,7 +27,7 @@ entirely in-memory, leveraging disk-based keys for efficient operation. The feature can be enabled by passing the `--tiered_prefix /` flag. Dragonfly will automatically check the free disk space on the partition hosting the `` to determine the maximum capacity it can use. Finally, it creates one storage file for -each [proactor thread](http://localhost:3000/docs/managing-dragonfly/flags#--proactor_threads), +each [proactor thread](./flags.md#--proactor_threads), corresponding to the number of threads Dragonfly is running with. Here are the main server flags related to SSD data tiering: @@ -140,4 +140,4 @@ with locally attached SSDs is recommended. See below for specific cloud provider - Dragonfly v1.35 (release notes for [v1.35.0](https://github.com/dragonflydb/dragonfly/releases/tag/v1.35.0) and [v1.35.1](https://github.com/dragonflydb/dragonfly/releases/tag/v1.35.1)) is the first official release of SSD data tiering. - If you encounter any problems while using this feature, please report them by [filing a GitHub issue](https://github.com/dragonflydb/dragonfly/issues/). -- Data tiering is currently supported for string values and, experimentally, for list nodes and mutable hash commands. It is not supported for BitMap and HyperLogLog operations. +- Data tiering is currently supported for string values and, experimentally, for list nodes and mutable hash commands. List-node prefetching is disabled by default. If `--list_tiering_prefetch_depth` is set above `0`, loading a tiered list node asynchronously prefetches up to that many eligible neighboring nodes in each direction. Data tiering is not supported for BitMap and HyperLogLog operations.