diff --git a/content/commands/bitop.md b/content/commands/bitop.md index 6a18d136d..7130568d4 100644 --- a/content/commands/bitop.md +++ b/content/commands/bitop.md @@ -21,6 +21,22 @@ arguments: name: not token: NOT type: pure-token + - display_text: diff + name: diff + token: DIFF + type: pure-token + - display_text: diff1 + name: diff1 + token: DIFF1 + type: pure-token + - display_text: andor + name: andor + token: ANDOR + type: pure-token + - display_text: one + name: one + token: ONE + type: pure-token name: operation type: oneof - display_text: destkey @@ -78,26 +94,45 @@ key_specs: linkTitle: BITOP since: 2.6.0 summary: Performs bitwise operations on multiple strings, and stores the result. -syntax_fmt: BITOP destkey key [key ...] +syntax_fmt: "BITOP destkey key [key ...]" syntax_str: destkey key [key ...] title: BITOP --- Perform a bitwise operation between multiple keys (containing string values) and store the result in the destination key. -The `BITOP` command supports four bitwise operations: **AND**, **OR**, **XOR** -and **NOT**, thus the valid forms to call the command are: +The `BITOP` command supports eight bitwise operations: `AND`, `OR`, `XOR`, +`NOT`, `DIFF`, `DIFF1`, `ANDOR`, and `ONE`. The valid forms to call the command are: * `BITOP AND destkey srckey1 srckey2 srckey3 ... srckeyN` + + A bit in `destkey` is set only if it is set in all source bitmaps. * `BITOP OR destkey srckey1 srckey2 srckey3 ... srckeyN` + + A bit in `destkey` is set only if it is set in at least one source bitmap. * `BITOP XOR destkey srckey1 srckey2 srckey3 ... srckeyN` + + Mostly used with two source bitmaps, a bit in `destkey` is set only if its value differs between the two source bitmaps. * `BITOP NOT destkey srckey` -As you can see **NOT** is special as it only takes an input key, because it -performs inversion of bits so it only makes sense as a unary operator. + `NOT` is a unary operator and only supports a single source bitmap; set the bit to the inverse of its value in the source bitmap. +* `BITOP DIFF destkey X [Y1 Y2 ...]` [1](#list-note-1) + + A bit in `destkey` is set if it is set in `X`, but not in any of `Y1, Y2, ...` . +* `BITOP DIFF1 destkey X [Y1 Y2 ...]` [1](#list-note-1) -The result of the operation is always stored at `destkey`. + A bit in `destkey` is set if it is set in one or more of `Y1, Y2, ...`, but not in `X`. +* `BITOP ANDOR destkey X [Y1 Y2 ...]` [1](#list-note-1) + + A bit in `destkey` is set if it is set in `X` and also in one or more of `Y1, Y2, ...`. +* `BITOP ONE destkey X1 [X2 X3 ...]` [1](#list-note-1) + + A bit in `destkey` is set if it is set in exactly one of `X1, X2, ...`. + +The result of each operation is always stored at `destkey`. + +1. Added in Redis 8.2. ## Handling of strings with different lengths @@ -110,13 +145,27 @@ zero bytes up to the length of the longest string. ## Examples +1. Basic usage example using the `AND` operator: + {{% redis-cli %}} -SET key1 "foobar" -SET key2 "abcdef" +BITFIELD key1 SET i8 #0 255 +BITFIELD key2 SET i8 #0 85 BITOP AND dest key1 key2 -GET dest +BITFIELD dest GET i8 #0 {{% /redis-cli %}} +2. Suppose you want to expose people to a book-related ad. The target audience is people who love to read books and are interested in fantasy, adventure, or science fiction. Assume you have the following bitmaps: + +* `LRB` - people who love to read books. +* `B:F` - people interested in fantasy. +* `B:A` - people interested in adventure. +* `B:SF` - people interested in science fiction. + +To create a bitmap representing the target audience, use the following command: + +``` +BITOP ANDOR TA LRB B:F B:A B:SF +``` ## Pattern: real time metrics using bitmaps diff --git a/content/commands/cluster-slot-stats.md b/content/commands/cluster-slot-stats.md new file mode 100644 index 000000000..973bfa53d --- /dev/null +++ b/content/commands/cluster-slot-stats.md @@ -0,0 +1,129 @@ +--- +arguments: +- arguments: + - arguments: + - name: start-slot + type: integer + - name: end-slot + type: integer + name: slotsrange + token: SLOTSRANGE + type: block + - arguments: + - name: metric + type: string + - name: limit + optional: true + token: LIMIT + type: integer + - arguments: + - name: asc + token: ASC + type: pure-token + - name: desc + token: DESC + type: pure-token + name: order + optional: true + type: oneof + name: orderby + token: ORDERBY + type: block + name: filter + type: oneof +arity: -4 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- STALE +- LOADING +command_tips: +- NONDETERMINISTIC_OUTPUT +- REQUEST_POLICY:ALL_SHARDS +complexity: O(N) where N is the total number of slots based on arguments. O(N*log(N)) + with ORDERBY subcommand. +container: CLUSTER +description: Return an array of slot usage statistics for slots assigned to the current + node. +function: clusterSlotStatsCommand +group: cluster +hidden: false +linkTitle: CLUSTER SLOT-STATS +reply_schema: + description: Array of nested arrays, where the inner array element represents a + slot and its respective usage statistics. + items: + description: Array of size 2, where 0th index represents (int) slot and 1st index + represents (map) usage statistics. + items: + - description: Slot Number. + type: integer + - additionalProperties: false + description: Map of slot usage statistics. + properties: + cpu-usec: + type: integer + key-count: + type: integer + network-bytes-in: + type: integer + network-bytes-out: + type: integer + type: object + maxItems: 2 + minItems: 2 + type: array + type: array +since: 8.2.0 +summary: Return an array of slot usage statistics for slots assigned to the current + node. +syntax_fmt: "CLUSTER SLOT-STATS " +syntax_str: '' +title: CLUSTER SLOT-STATS +--- + +Use this command to get an array of slot usage statistics for the slots assigned to the current shard. If you're working with a Redis cluster, this data helps you understand overall slot usage, spot hot or cold slots, plan slot migrations to balance load, or refine your application logic to better distribute keys. + +## Options + +`CLUSTER SLOT-STATS` has two mutually exclusive options: + +* `ORDERBY`: Sorts the slot statistics by the specified metric. Use ASC or DESC to sort in ascending or descending order. If multiple slots have the same value, the command uses the slot number as a tiebreaker, sorted in ascending order. + +* `SLOTSRANGE`: Limits the results to a specific, inclusive range of slots. Results are always sorted by slot number in ascending order. + +The command reports on the following statistics: + +* `KEY-COUNT`: Number of keys stored in the slot. +* `CPU-USEC`: CPU time (in microseconds) spent handling the slot. +* `NETWORK-BYTES-IN`: Total inbound network traffic (in bytes) received by the slot. +* `NETWORK-BYTES-OUT`: Total outbound network traffic (in bytes) sent from the slot. + +## Return information + +{{< multitabs id=“cmd-name-return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a nested list of slot usage statistics. +* [Simple error]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) otherwise. + +-tab-sep- + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a nested list of slot usage statistics. +* [Simple error]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) otherwise. + +{{< /multitabs >}} \ No newline at end of file diff --git a/content/commands/ft.aggregate.md b/content/commands/ft.aggregate.md index ca5b28ed6..8ea7f25e6 100644 --- a/content/commands/ft.aggregate.md +++ b/content/commands/ft.aggregate.md @@ -484,6 +484,27 @@ Next, count GitHub events by user (actor), to produce the most active users. +
+Use the case function for conditional logic +{{< highlight bash >}} +//Simple mapping +FT.AGGREGATE products "*" +APPLY case(@price > 100, "premium", "standard") AS category + +//Nested conditions where an error should be returned +FT.AGGREGATE orders "*" +APPLY case(@status == "pending", + case(@priority == "high", 1, 2), + case(@status == "completed", 3, 4)) AS status_code + +//Mapped approach +FT.AGGREGATE orders "*" +APPLY case(@status == "pending", 1, 0) AS is_pending +APPLY case(@is_pending == 1 && @priority == "high", 1,2) AS status_high +APPLY case(@is_pending == 0 && @priority == "high", 3,4) AS status_completed +{{< / highlight >}} + +
## Return information {{< multitabs id="ft-aggregate-return-info" diff --git a/content/commands/info.md b/content/commands/info.md index a25383659..3be798c1b 100644 --- a/content/commands/info.md +++ b/content/commands/info.md @@ -152,6 +152,7 @@ Here is the meaning of all fields in the **memory** section: * `used_memory_rss_human`: Human readable representation of previous value * `used_memory_peak`: Peak memory consumed by Redis (in bytes) * `used_memory_peak_human`: Human readable representation of previous value +* `used_memory_peak_time`: Time when peak memory was recorded * `used_memory_peak_perc`: The percentage of `used_memory` out of `used_memory_peak` * `used_memory_overhead`: The sum in bytes of all overheads that the server allocated for managing its internal data structures diff --git a/content/commands/vismember.md b/content/commands/vismember.md new file mode 100644 index 000000000..4093d1e32 --- /dev/null +++ b/content/commands/vismember.md @@ -0,0 +1,66 @@ +--- +arguments: +- name: key + type: key +- name: element + type: string +arity: 3 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- READONLY +complexity: O(1) +description: Check if an element exists in a vector set. +function: vismemberCommand +group: vector_set +hidden: false +linkTitle: VISMEMBER +since: 8.0.0 +summary: Check if an element exists in a vector set. +syntax_fmt: VISMEMBER key element +syntax_str: element +title: VISMEMBER +bannerText: Vector set is a new data type that is currently in preview and may be subject to change. +--- + +Check if an element exists in a vector set. + +## Required arguments + +
+key + +is the name of the key that holds the vector set. +
+ +
+element + +is the name of the element you want to check for membership. +
+ +## Related topics + +- [Vector sets]({{< relref "/develop/data-types/vector-sets" >}}) + +## Return information + +{{< multitabs id="vismember-return-info" + tab1="RESP2" + tab2="RESP3" >}} + +[Integer reply](../../develop/reference/protocol-spec#integers): `0` if the element does not exist in the vector set, or the key does not exist. `1` if the element exists in the vector set. + +-tab-sep- + +[Boolean reply](../../develop/reference/protocol-spec#booleans): `false` if the element does not exist in the vector set, or the key does not exist. `true` if the element exists in the vector set. + +{{< /multitabs >}} diff --git a/content/commands/vrem.md b/content/commands/vrem.md index 444692b05..227c1e65e 100644 --- a/content/commands/vrem.md +++ b/content/commands/vrem.md @@ -10,12 +10,12 @@ categories: - kubernetes - clients complexity: O(log(N)) for each element removed, where N is the number of elements in the vector set. -description: Remove one or more elements from a vector set. +description: Remove an element from a vector set. group: vector_set hidden: false linkTitle: VREM since: 8.0.0 -summary: Remove one or more elements from a vector set. +summary: Remove an element from a vector set. syntax_fmt: "VREM key element" title: VREM bannerText: Vector set is a new data type that is currently in preview and may be subject to change. @@ -26,14 +26,10 @@ Remove an element from a vector set. ```shell VADD vset VALUES 3 1 0 1 bar (integer) 1 -``` -```shell VREM vset bar (integer) 1 -``` -```shell VREM vset bar (integer) 0 ``` diff --git a/content/commands/vsim.md b/content/commands/vsim.md index 90326672a..78a568a3c 100644 --- a/content/commands/vsim.md +++ b/content/commands/vsim.md @@ -13,10 +13,13 @@ complexity: O(log(N)) where N is the number of elements in the vector set. description: Return elements by vector similarity. group: vector_set hidden: false +history: +- - 8.2.0 + - added the WITHATTRIBS option. linkTitle: VSIM since: 8.0.0 summary: Return elements by vector similarity. -syntax_fmt: "VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [COUNT num] [EF search-exploration-factor]\n [FILTER expression] [FILTER-EF max-filtering-effort] [TRUTH] [NOTHREAD]" +syntax_fmt: "VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [WITHATTRIBS] [COUNT num]\n [EPSILON delta] [EF search-exploration-factor] [FILTER expression] [FILTER-EF max-filtering-effort]\n [TRUTH] [NOTHREAD]" title: VSIM bannerText: Vector set is a new data type that is currently in preview and may be subject to change. --- @@ -39,16 +42,19 @@ VSIM word_embeddings ELE apple 10) "grape" ``` -You can include similarity scores and limit the number of results: +You can include similarity scores, attributes (if any), and limit the number of results: ```shell -VSIM word_embeddings ELE apple WITHSCORES COUNT 3 +VSIM word_embeddings ELE apple WITHSCORES WITHATTRIBS COUNT 3 1) "apple" 2) "0.9998867657923256" -3) "apples" -4) "0.8598527610301971" -5) "pear" -6) "0.8226882219314575" +3) "{\"len\": 5}" +4) "apples" +5) "0.859852746129036" +6) "{\"len\": 6}" +7) "pear" +8) "0.8226882070302963" +9) "{\"len\": 4}" ``` Set the `EF` (exploration factor) to improve recall at the cost of performance. Use the `TRUTH` option to perform an exact linear scan, useful for benchmarking. The `NOTHREAD` option runs the search in the main thread and may increase server latency. @@ -81,12 +87,24 @@ is either the vector data (for `FP32` or `VALUES`) or the name of the element (f returns the similarity score (from 1 to 0) alongside each result. A score of 1 is identical; 0 is the opposite. +
+WITHATTRIBS + +returns, for each element, the JSON attribute associated with the element or NULL when no attributes are present. +
+
COUNT num limits the number of returned results to `num`.
+
+EPSILON delta + +is a floating point number between 0 and 1. It is used to retrieve elements that have a distance that is no further than the specified `delta`. In vector sets, returned elements have a similarity score (when compared to the query vector) that is between 1 and 0, where 1 means identical and 0 means opposite vectors. For example, if the `EPSILON` option is specified with an argument of `0.2`, it means only elements that have a similarity of 0.8 or better (a distance < 0.2) are returned. This is useful when you specify a large `COUNT`, but you don't want elements that are too far away from the query vector. +
+
EF search-exploration-factor @@ -128,9 +146,11 @@ executes the search in the main thread instead of a background thread. Useful fo tab2="RESP3" >}} One of the following: -* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for unknown element. -* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for unknown key. -* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements; juxtaposed with scores when used with the WITHSCORES option. +* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for an unknown element. +* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for an unknown key. +* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements. +* With the `WITHSCORES` option, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements juxtaposed with [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) as floating-point scores. +* With the `WITHSCORES` and `WITHATTRIBS` options, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements, and two additional elements: (1) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) as floating-point score and (2) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the JSON attribute associated with the element or [nil (null bulk string)]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) for the elements missing an attribute. -tab-sep- @@ -138,6 +158,7 @@ One of the following: * [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for unknown element. * [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for unknown key. * [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements. -* [Map reply](../../develop/reference/protocol-spec#maps) with matching elements and [double](../../develop/reference/protocol-spec#doubles) scores when used with the WITHSCORES option. +* With the `WITHSCORES` option, a [map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements (keys) and [double](../../develop/reference/protocol-spec#doubles) scores (values). +* With the `WITHSCORES` and `WITHATTRIBS` options, a [Map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) elements (keys), and an additional array (values) with the following elements: (1) a [double reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) for the score and (2) a [bulk string]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the JSON attribute associated with the element or [null]({{< relref "/develop/reference/protocol-spec#nulls" >}}) for the elements missing an attribute. {{< /multitabs >}} diff --git a/content/commands/xackdel.md b/content/commands/xackdel.md new file mode 100644 index 000000000..bdbda003f --- /dev/null +++ b/content/commands/xackdel.md @@ -0,0 +1,163 @@ +--- +acl_categories: +- '@write' +- '@stream' +- '@fast' +arguments: +- display_text: key + key_spec_index: 0 + name: key + type: key +- display_text: group + name: group + type: string +- arguments: + - display_text: keepref + name: keepref + token: KEEPREF + type: pure-token + - display_text: delref + name: delref + token: DELREF + type: pure-token + - display_text: acked + name: acked + token: ACKED + type: pure-token + name: condition + optional: true + type: oneof +- arguments: + - display_text: numids + name: numids + type: integer + - display_text: id + multiple: true + name: id + type: string + name: ids + token: IDS + type: block +arity: -6 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- write +- fast +complexity: O(1) for each entry ID processed. +description: Acknowledges and conditionally deletes one or multiple entries for a stream consumer + group. +group: stream +hidden: false +key_specs: +- RW: true + begin_search: + spec: + index: 1 + type: index + delete: true + find_keys: + spec: + keystep: 1 + lastkey: 0 + limit: 0 + type: range + update: true +linkTitle: XACKDEL +since: 8.2.0 +summary: Acknowledges and conditionally deletes one or multiple entries for a stream consumer group. +syntax_fmt: "XACKDEL key group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]" +syntax_str: "group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]" +title: XACKDEL +--- + +Acknowledges and conditionally deletes one or multiple entries (messages) for a stream consumer group at the specified `key`. + +`XACKDEL` combines the functionality of [`XACK`]({{< relref "/commands/xack" >}}) and [`XDEL`]({{< relref "/commands/xdel" >}}) in Redis Streams. It acknowledges the specified entry IDs in the given consumer group and simultaneously attempts to delete the corresponding entries from the stream. + +## Required arguments + +
+key + +The name of the stream key. +
+ +
+group + +The name of the consumer group. +
+ +
+IDS numids id [id ...] + +The IDS block specifying which entries to acknowledge and delete: +- `numids`: The number of IDs that follow +- `id [id ...]`: One or more stream entry IDs to acknowledge and delete +
+ +## Optional arguments + +
+KEEPREF | DELREF | ACKED + +Specifies how to handle consumer group references when acknowledging and deleting entries. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default: + +- `KEEPREF` (default): Acknowledges the entries in the specified consumer group and deletes the entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). +- `DELREF`: Acknowledges the entries in the specified consumer group, deletes the entries from the stream, and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the entries. If an entry ID is not in the stream, but there are dangling references, `XACKDEL` with `DELREF` would still remove all those references. +- `ACKED`: Acknowledges the entries in the specified consumer group and only deletes entries that were read and acknowledged by all consumer groups. +
+ +This command is particularly useful when you want to both acknowledge entry processing and clean up the stream in a single atomic operation, providing fine-grained control over how entry references are handled. + +{{< note >}} +When using multiple consumer groups, users are encouraged to use `XACKDEL` with the `ACKED` option instead of `XACK` and `XDEL`, simplifying the application logic. +{{< /note >}} + +## Examples + +{{% redis-cli %}} +XADD mystream * field1 value1 +XADD mystream * field2 value2 +XGROUP CREATE mystream mygroup 0 +XREADGROUP GROUP mygroup consumer1 COUNT 2 STREAMS mystream > +XPENDING mystream mygroup +XACKDEL mystream mygroup KEEPREF IDS 2 1526919030474-55 1526919030474-56 +XPENDING mystream mygroup +XRANGE mystream - + +{{% /redis-cli %}} + +## Return information + +{{< multitabs id="xackdel-return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist. +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID: + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream. + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key. + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option). + +-tab-sep- + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist. +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID: + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream. + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key. + * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option). + +{{< /multitabs >}} diff --git a/content/commands/xadd.md b/content/commands/xadd.md index 363527f12..b45e2dd90 100644 --- a/content/commands/xadd.md +++ b/content/commands/xadd.md @@ -14,6 +14,22 @@ arguments: since: 6.2.0 token: NOMKSTREAM type: pure-token +- arguments: + - display_text: keepref + name: keepref + token: KEEPREF + type: pure-token + - display_text: delref + name: delref + token: DELREF + type: pure-token + - display_text: acked + name: acked + token: ACKED + type: pure-token + name: condition + optional: true + type: oneof - arguments: - arguments: - display_text: maxlen @@ -98,6 +114,8 @@ history: - Added the `NOMKSTREAM` option, `MINID` trimming strategy and the `LIMIT` option. - - 7.0.0 - Added support for the `-*` explicit ID form. +- - 8.2.0 + - Added the `KEEPREF`, `DELREF` and `ACKED` options. key_specs: - RW: true begin_search: @@ -115,44 +133,93 @@ key_specs: linkTitle: XADD since: 5.0.0 summary: Appends a new message to a stream. Creates the key if it doesn't exist. -syntax_fmt: "XADD key [NOMKSTREAM] [ [= | ~] threshold\n [LIMIT\_\ - count]] <* | id> field value [field value ...]" -syntax_str: "[NOMKSTREAM] [ [= | ~] threshold [LIMIT\_count]] <* |\ - \ id> field value [field value ...]" +syntax_fmt: "XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [\n\ + \ [= | ~] threshold [LIMIT\_count]] <* | id> field value [field value\n ...]" +syntax_str: "[NOMKSTREAM] [KEEPREF | DELREF | ACKED] [ [= | ~] threshold\ + \ [LIMIT\_count]] <* | id> field value [field value ...]" title: XADD --- -Appends the specified stream entry to the stream at the specified key. -If the key does not exist, as a side effect of running this command the -key is created with a stream value. The creation of stream's key can be -disabled with the `NOMKSTREAM` option. -An entry is composed of a list of field-value pairs. -The field-value pairs are stored in the same order they are given by the user. -Commands that read the stream, such as [`XRANGE`]({{< relref "/commands/xrange" >}}) or [`XREAD`]({{< relref "/commands/xread" >}}), are guaranteed to return the fields and values exactly in the same order they were added by `XADD`. +Appends the specified stream entry to the stream at the specified `key`. +If the key does not exist, `XADD` will create a new key with the given stream value as a side effect of running this command. +You can turn off key creation with the `NOMKSTREAM` option. + +## Required arguments + +
+key + +The name of the stream key. +
+ +
+id + +The stream entry ID. Use `*` to auto-generate a unique ID, or specify a well-formed ID in the format `-` (for example, `1526919030474-55`). +
+ +
+field value [field value ...] -`XADD` is the *only Redis command* that can add data to a stream, but -there are other commands, such as [`XDEL`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), that are able to +One or more field-value pairs that make up the stream entry. You must provide at least one field-value pair. +
+ +## Optional arguments + +
+NOMKSTREAM + +Prevents the creation of a new stream if the key does not exist. Available since Redis 6.2.0. +
+ +
+KEEPREF | DELREF | ACKED + +Specifies how to handle consumer group references when trimming. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and `XACKDEL` commands where one of these options is required, here they are optional to maintain backward compatibility: + +- `KEEPREF` (default): When trimming, removes entries from the stream according to the specified strategy (`MAXLEN` or `MINID`), regardless of whether they are referenced by any consumer groups, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). +- `DELREF`: When trimming, removes entries from the stream according to the specified strategy and also removes all references to these entries from all consumer groups' PEL. +- `ACKED`: When trimming, only removes entries that were read and acknowledged by all consumer groups. Note that if the number of referenced entries is larger than `MAXLEN`, trimming will still stop at the limit. +
+ +
+MAXLEN | MINID [= | ~] threshold [LIMIT count] + +Trims the stream to maintain a specific size or remove old entries: +- `MAXLEN`: Limits the stream to a maximum number of entries +- `MINID`: Removes entries with IDs lower than the specified threshold (available since Redis 6.2.0) +- `=`: Exact trimming (default) +- `~`: Approximate trimming (more efficient) +- `threshold`: The maximum number of entries (for MAXLEN) or minimum ID (for MINID) +- `LIMIT count`: Limits the number of entries to examine during trimming (available since Redis 6.2.0) +
+ +Each entry consists of a list of field-value pairs. +Redis stores the field-value pairs in the same order you provide them. +Commands that read the stream, such as [`XRANGE`]({{< relref "/commands/xrange" >}}) or [`XREAD`]({{< relref "/commands/xread" >}}), return the fields and values in exactly the same order you added them with `XADD`. + +{{< note >}} +`XADD` is the only Redis command that can add data to a stream. However, +other commands, such as [`XDEL`]({{< relref "/commands/xdel" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}), can remove data from a stream. +{{< /note >}} ## Specifying a Stream ID as an argument -A stream entry ID identifies a given entry inside a stream. +A stream entry ID identifies a specific entry inside a stream. -The `XADD` command will auto-generate a unique ID for you if the ID argument -specified is the `*` character (asterisk ASCII character). However, while -useful only in very rare cases, it is possible to specify a well-formed ID, so -that the new entry will be added exactly with the specified ID. +`XADD` auto-generates a unique ID for you if you specify the `*` character (asterisk) as the ID argument. However, you can also specify a well-formed ID to add the new entry with that exact ID, though this is useful only in rare cases. -IDs are specified by two numbers separated by a `-` character: +Specify IDs using two numbers separated by a `-` character: 1526919030474-55 -Both quantities are 64-bit numbers. When an ID is auto-generated, the +Both numbers are 64-bit integers. When Redis auto-generates an ID, the first part is the Unix time in milliseconds of the Redis instance generating -the ID. The second part is just a sequence number and is used in order to +the ID. The second part is a sequence number used to distinguish IDs generated in the same millisecond. -You can also specify an incomplete ID, that consists only of the milliseconds part, which is interpreted as a zero value for sequence part. +You can also specify an incomplete ID that consists only of the milliseconds part, which Redis interprets as a zero value for the sequence part. To have only the sequence part automatically generated, specify the milliseconds part followed by the `-` separator and the `*` character: ``` @@ -162,37 +229,25 @@ To have only the sequence part automatically generated, specify the milliseconds "1526919030474-56" ``` -IDs are guaranteed to be always incremental: If you compare the ID of the -entry just inserted it will be greater than any other past ID, so entries -are totally ordered inside a stream. In order to guarantee this property, -if the current top ID in the stream has a time greater than the current -local time of the instance, the top entry time will be used instead, and -the sequence part of the ID incremented. This may happen when, for instance, -the local clock jumps backward, or if after a failover the new master has -a different absolute time. - -When a user specified an explicit ID to `XADD`, the minimum valid ID is -`0-1`, and the user *must* specify an ID which is greater than any other -ID currently inside the stream, otherwise the command will fail and return an error. Usually -resorting to specific IDs is useful only if you have another system generating -unique IDs (for instance an SQL table) and you really want the Redis stream -IDs to match the one of this other system. +Redis guarantees that IDs are always incremental: the ID of any entry you insert will be greater than any previous ID, so entries are totally ordered inside a stream. To guarantee this property, if the current top ID in the stream has a time greater than the current local time of the instance, Redis uses the top entry time instead and increments the sequence part of the ID. This may happen when, for instance, the local clock jumps backward, or after a failover when the new master has a different absolute time. + +When you specify an explicit ID to `XADD`, the minimum valid ID is `0-1`, and you *must* specify an ID that is greater than any other ID currently inside the stream, otherwise the command fails and returns an error. Specifying explicit IDs is usually useful only if you have another system generating unique IDs (for instance an SQL table) and you want the Redis stream IDs to match those from your other system. ## Capped streams `XADD` incorporates the same semantics as the [`XTRIM`]({{< relref "/commands/xtrim" >}}) command - refer to its documentation page for more information. -This allows adding new entries and keeping the stream's size in check with a single call to `XADD`, effectively capping the stream with an arbitrary threshold. -Although exact trimming is possible and is the default, due to the internal representation of streams it is more efficient to add an entry and trim stream with `XADD` using **almost exact** trimming (the `~` argument). +This allows you to add new entries and keep the stream's size in check with a single call to `XADD`, effectively capping the stream with an arbitrary threshold. +Although exact trimming is possible and is the default, due to the internal representation of streams, it is more efficient to add an entry and trim the stream with `XADD` using **almost exact** trimming (the `~` argument). For example, calling `XADD` in the following form: XADD mystream MAXLEN ~ 1000 * ... entry fields here ... - -Will add a new entry but will also evict old entries so that the stream will contain only 1000 entries, or at most a few tens more. + +This adds a new entry but also evicts old entries so that the stream contains only 1000 entries, or at most a few tens more. ## Additional information about streams -For further information about Redis streams please check our +For more information about Redis streams, see the [introduction to Redis Streams document]({{< relref "/develop/data-types/streams" >}}). ## Examples diff --git a/content/commands/xdelex.md b/content/commands/xdelex.md new file mode 100644 index 000000000..35a2858d7 --- /dev/null +++ b/content/commands/xdelex.md @@ -0,0 +1,149 @@ +--- +acl_categories: +- '@write' +- '@stream' +- '@fast' +arguments: +- display_text: key + key_spec_index: 0 + name: key + type: key +- arguments: + - display_text: keepref + name: keepref + token: KEEPREF + type: pure-token + - display_text: delref + name: delref + token: DELREF + type: pure-token + - display_text: acked + name: acked + token: ACKED + type: pure-token + name: condition + optional: true + type: oneof +- arguments: + - display_text: numids + name: numids + type: integer + - display_text: id + multiple: true + name: id + type: string + name: ids + token: IDS + type: block +arity: -5 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- write +- fast +complexity: O(1) for each single item to delete in the stream, regardless of the stream + size. +description: Deletes one or multiple entries from the stream. +group: stream +hidden: false +key_specs: +- RW: true + begin_search: + spec: + index: 1 + type: index + delete: true + find_keys: + spec: + keystep: 1 + lastkey: 0 + limit: 0 + type: range +linkTitle: XDELEX +since: 8.2.0 +summary: Deletes one or multiple entries from the stream. +syntax_fmt: "XDELEX key [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]" +syntax_str: "[KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]" +title: XDELEX +--- + +Deletes one or multiple entries from the stream at the specified `key`. + +`XDELEX` is an extension of the Redis Streams [`XDEL`]({{< relref "/commands/xdel" >}}) command that provides more control over how message entries are deleted concerning consumer groups. + +## Required arguments + +
+key + +The name of the stream key. +
+ +
+IDS numids id [id ...] + +The IDS block specifying which entries to delete: +- `numids`: The number of IDs that follow +- `id [id ...]`: One or more stream entry IDs to delete + +Note: The IDS block can be at any position in the command, same as other commands. +
+ +## Optional arguments + +
+KEEPREF | DELREF | ACKED + +Specifies how to handle consumer group references when deleting entries. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default: + +- `KEEPREF` (default): Deletes the specified entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). This behavior is similar to [`XDEL`]({{< relref "/commands/xdel" >}}). +- `DELREF`: Deletes the specified entries from the stream and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages. If an entry ID is not in the stream, but there are dangling references, `XDELEX` with `DELREF` would still remove all those references. +- `ACKED`: Only deletes entries that were read and acknowledged by all consumer groups. +
+ +The command provides fine-grained control over stream entry deletion, particularly useful when working with consumer groups where you need to manage pending entry references carefully. + +## Examples + +{{% redis-cli %}} +XADD mystream * field1 value1 +XADD mystream * field2 value2 +XADD mystream * field3 value3 +XRANGE mystream - + +XDELEX mystream KEEPREF IDS 2 1526919030474-55 1526919030474-56 +XRANGE mystream - + +{{% /redis-cli %}} + +## Return information + +{{< multitabs id="xdelex-return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist. +* [Array reply](../../develop/reference/protocol-spec#arrays): For each ID: + * [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key. + * [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream. + * [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option). + +-tab-sep- + +One of the following: + +* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist. +* [Array reply](../../develop/reference/protocol-spec#arrays): For each ID: + * [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key. + * [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream. + * [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option). + +{{< /multitabs >}} diff --git a/content/commands/xtrim.md b/content/commands/xtrim.md index 9086919bd..fa40922f0 100644 --- a/content/commands/xtrim.md +++ b/content/commands/xtrim.md @@ -42,6 +42,22 @@ arguments: since: 6.2.0 token: LIMIT type: integer + - arguments: + - display_text: keepref + name: keepref + token: KEEPREF + type: pure-token + - display_text: delref + name: delref + token: DELREF + type: pure-token + - display_text: acked + name: acked + token: ACKED + type: pure-token + name: condition + optional: true + type: oneof name: trim type: block arity: -4 @@ -68,6 +84,8 @@ hints: history: - - 6.2.0 - Added the `MINID` trimming strategy and the `LIMIT` option. +- - 8.2.0 + - Added the `KEEPREF`, `DELREF` and `ACKED` options. key_specs: - RW: true begin_search: @@ -84,40 +102,91 @@ key_specs: linkTitle: XTRIM since: 5.0.0 summary: Deletes messages from the beginning of a stream. -syntax_fmt: "XTRIM key [= | ~] threshold [LIMIT\_count]" -syntax_str: " [= | ~] threshold [LIMIT\_count]" +syntax_fmt: "XTRIM key [= | ~] threshold [LIMIT\_count] [KEEPREF\n\ + \ | DELREF | ACKED]" +syntax_str: " [= | ~] threshold [LIMIT\_count] [KEEPREF | DELREF |\ + \ ACKED]" title: XTRIM --- + `XTRIM` trims the stream by evicting older entries (entries with lower IDs) if needed. -Trimming the stream can be done using one of these strategies: +## Required arguments + +
+key + +The name of the stream key. +
+ +
+MAXLEN | MINID + +The trimming strategy: +- `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified threshold +- `MINID`: Evicts entries with IDs lower than the specified threshold (available since Redis 6.2.0) +
+ +
+threshold + +The trimming threshold. For `MAXLEN`, this is a positive integer representing the maximum number of entries. For `MINID`, this is a stream ID. +
+ +## Optional arguments + +
+= | ~ + +The trimming operator: +- `=`: Exact trimming (default) - trims to the exact threshold +- `~`: Approximate trimming - more efficient, may leave slightly more entries than the threshold +
+ +
+LIMIT count + +Limits the number of entries to examine during trimming. Available since Redis 6.2.0. When not specified, Redis uses a default value of 100 * the number of entries in a macro node. Specifying 0 disables the limiting mechanism entirely. +
+ +
+KEEPREF | DELREF | ACKED + +Specifies how to handle consumer group references when trimming. If no option is specified, `KEEPREF` is used by default: + +- `KEEPREF` (default): When trimming, removes entries from the stream according to the specified strategy (`MAXLEN` or `MINID`), regardless of whether they are referenced by any consumer groups, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). +- `DELREF`: When trimming, removes entries from the stream according to the specified strategy and also removes all references to these entries from all consumer groups' PEL. +- `ACKED`: When trimming, only removes entries that were read and acknowledged by all consumer groups. Note that if the number of referenced entries is larger than `MAXLEN`, trimming will still stop at the limit. +
+ +You can trim the stream using one of these strategies: * `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified `threshold`, where `threshold` is a positive integer. * `MINID`: Evicts entries with IDs lower than `threshold`, where `threshold` is a stream ID. -For example, this will trim the stream to exactly the latest 1000 items: +For example, this trims the stream to exactly the latest 1000 items: ``` XTRIM mystream MAXLEN 1000 ``` -Whereas in this example, all entries that have an ID lower than 649085820-0 will be evicted: +In this example, Redis evicts all entries that have an ID lower than 649085820-0: ``` XTRIM mystream MINID 649085820 ``` -By default, or when provided with the optional `=` argument, the command performs exact trimming. +By default, or when you provide the optional `=` argument, the command performs exact trimming. Depending on the strategy, exact trimming means: -* `MAXLEN`: the trimmed stream's length will be exactly the minimum between its original length and the specified `threshold`. -* `MINID`: the oldest ID in the stream will be exactly the maximum between its original oldest ID and the specified `threshold`. +* `MAXLEN`: The trimmed stream's length will be exactly the minimum between its original length and the specified `threshold`. +* `MINID`: The oldest ID in the stream will be exactly the maximum between its original oldest ID and the specified `threshold`. Nearly exact trimming --- -Because exact trimming may require additional effort from the Redis server, the optional `~` argument can be provided to make it more efficient. +Because exact trimming may require additional effort from the Redis server, you can provide the optional `~` argument to make it more efficient. For example: @@ -125,13 +194,13 @@ For example: XTRIM mystream MAXLEN ~ 1000 ``` -The `~` argument between the `MAXLEN` strategy and the `threshold` means that the user is requesting to trim the stream so its length is **at least** the `threshold`, but possibly slightly more. -In this case, Redis will stop trimming early when performance can be gained (for example, when a whole macro node in the data structure can't be removed). -This makes trimming much more efficient, and it is usually what you want, although after trimming, the stream may have few tens of additional entries over the `threshold`. +The `~` argument between the `MAXLEN` strategy and the `threshold` means that you are requesting to trim the stream so its length is **at least** the `threshold`, but possibly slightly more. +In this case, Redis stops trimming early when performance can be gained (for example, when a whole macro node in the data structure can't be removed). +This makes trimming much more efficient, and it is usually what you want, although after trimming, the stream may have a few tens of additional entries over the `threshold`. -Another way to control the amount of work done by the command when using the `~`, is the `LIMIT` clause. -When used, it specifies the maximal `count` of entries that will be evicted. -When `LIMIT` and `count` aren't specified, the default value of 100 * the number of entries in a macro node will be implicitly used as the `count`. +Another way to control the amount of work done by the command when using `~` is the `LIMIT` clause. +When you use it, it specifies the maximum `count` of entries that will be evicted. +When you don't specify `LIMIT` and `count`, Redis implicitly uses the default value of 100 * the number of entries in a macro node as the `count`. Specifying the value 0 as `count` disables the limiting mechanism entirely. ## Examples diff --git a/content/develop/ai/search-and-query/advanced-concepts/aggregations.md b/content/develop/ai/search-and-query/advanced-concepts/aggregations.md index 3813995e7..d0a2e3f1b 100644 --- a/content/develop/ai/search-and-query/advanced-concepts/aggregations.md +++ b/content/develop/ai/search-and-query/advanced-concepts/aggregations.md @@ -379,6 +379,7 @@ Note that these operators apply only to numeric values and numeric sub-expressio | Function | Description | Example | | -------- | ------------------------------------------------------------ | ------------------ | | exists(s)| Checks whether a field exists in a document. | `exists(@field)` | +| case(condition, if_true, if_false) | If condition is non-zero, return if_true, otherwise return if_false. | `case(exists(@foo), @foo, "no foo")` | ### List of numeric APPLY functions diff --git a/content/develop/ai/search-and-query/indexing/field-and-type-options.md b/content/develop/ai/search-and-query/indexing/field-and-type-options.md index cb2033f2b..9941c7716 100644 --- a/content/develop/ai/search-and-query/indexing/field-and-type-options.md +++ b/content/develop/ai/search-and-query/indexing/field-and-type-options.md @@ -157,6 +157,7 @@ Where: - `FLAT`: brute force algorithm. - `HNSW`: hierarchical, navigable, small world algorithm. + - `SVS-VAMANA`: a graph-based nearest neighbor search algorithm, which is optimized for use with compression methods to reduce its memory footprint. The `{algorithm}` attribute specifies the algorithm to use when searching `k` most similar vectors in the index or filtering vectors by range. diff --git a/content/develop/ai/search-and-query/vectors.md b/content/develop/ai/search-and-query/vectors.md index 18ce729ab..b72153b61 100644 --- a/content/develop/ai/search-and-query/vectors.md +++ b/content/develop/ai/search-and-query/vectors.md @@ -25,7 +25,7 @@ To quickly get started, check out the [Redis vector quickstart guide]({{< relref ## Overview -1. [**Create a vector index**]({{< relref "develop/ai/search-and-query/vectors#create-a-vector-index" >}}): Redis maintains a secondary index over your data with a defined schema (including vector fields and metadata). Redis supports [`FLAT`]({{< relref "develop/ai/search-and-query/vectors#flat-index" >}}) and [`HNSW`]({{< relref "develop/ai/search-and-query/vectors#hnsw-index" >}}) vector index types. +1. [**Create a vector index**]({{< relref "develop/ai/search-and-query/vectors#create-a-vector-index" >}}): Redis maintains a secondary index over your data with a defined schema (including vector fields and metadata). Redis supports [`FLAT`]({{< relref "develop/ai/search-and-query/vectors#flat-index" >}}), [`HNSW`]({{< relref "develop/ai/search-and-query/vectors#hnsw-index" >}}) and [`SVS-VAMANA`]({{< relref "develop/ai/search-and-query/vectors#svs-vamana-index" >}}) vector index types. 1. [**Store and update vectors**]({{< relref "develop/ai/search-and-query/vectors#store-and-update-vectors" >}}): Redis stores vectors and metadata in hashes or JSON objects. 1. [**Search with vectors**]({{< relref "develop/ai/search-and-query/vectors#search-with-vectors" >}}): Redis supports several advanced querying strategies with vector fields including k-nearest neighbor ([KNN]({{< relref "develop/ai/search-and-query/vectors#knn-vector-search" >}})), [vector range queries]({{< relref "develop/ai/search-and-query/vectors#vector-range-queries" >}}), and [metadata filters]({{< relref "develop/ai/search-and-query/vectors#filters" >}}). 1. [**Configure vector queries at runtime**]({{< relref "develop/ai/search-and-query/vectors#runtime-query-params" >}}). @@ -106,12 +106,12 @@ Choose the `HNSW` index type when you have larger datasets (> 1M documents) or w [`HNSW`](https://arxiv.org/ftp/arxiv/papers/1603/1603.09320.pdf) supports a number of additional parameters to tune the accuracy of the queries, while trading off performance. -| Attribute | Description | -|:-------------------|:--------------------------------------------------------------------------------------------| -| `M` | Max number of outgoing edges (connections) for each node in a graph layer. On layer zero, the max number of connections will be `2 * M`. Higher values increase accuracy, but also increase memory usage and index build time. The default is 16. | -| `EF_CONSTRUCTION` | Max number of connected neighbors to consider during graph building. Higher values increase accuracy, but also increase index build time. The default is 200. | -| `EF_RUNTIME` | Max top candidates during KNN search. Higher values increase accuracy, but also increase search latency. The default is 10. | -| `EPSILON` | Relative factor that sets the boundaries in which a range query may search for candidates. That is, vector candidates whose distance from the query vector is `radius * (1 + EPSILON)` are potentially scanned, allowing more extensive search and more accurate results, at the expense of run time. The default is 0.01. | +| Attribute | Description | Default value | +|:-------------------|:-------------------------------------------------------------------|:-------------:| +| `M` | Max number of outgoing edges (connections) for each node in a graph layer. On layer zero, the max number of connections will be `2 * M`. Higher values increase accuracy, but also increase memory usage and index build time. | 16 | +| `EF_CONSTRUCTION` | Max number of connected neighbors to consider during graph building. Higher values increase accuracy, but also increase index build time. | 200 | +| `EF_RUNTIME` | Max top candidates during KNN search. Higher values increase accuracy, but also increase search latency. | 10 | +| `EPSILON` | Relative factor that sets the boundaries in which a range query may search for candidates. That is, vector candidates whose distance from the query vector is `radius * (1 + EPSILON)` are potentially scanned, allowing more extensive search and more accurate results, at the expense of run time. | 0.01 | **Example** @@ -129,6 +129,79 @@ FT.CREATE documents In the example above, an index named `documents` is created over hashes with the key prefix `docs:` and an `HNSW` vector field named `doc_embedding` with five index attributes: `TYPE`, `DIM`, `DISTANCE_METRIC`, `M`, and `EF_CONSTRUCTION`. +### SVS-VAMANA index + +Scalable Vector Search (SVS) is an Intel project featuring a graph-based vector search algorithm that is optimized to work with compression methods to reduce memory usage. You can read more about the project [here](https://intel.github.io/ScalableVectorSearch/intro.html). Support for SVS-VAMANA indexing was added in Redis 8.2. + +Choose the `SVS-VAMANA` index type when all of the following requirements apply: +- High search performance and scalability are more important than exact search accuracy (similar to HNSW) +- Reduced memory usage +- Performance optimizations for Intel hardware + +**Required attributes** + +| Attribute | Description | +|:-------------------|:-----------------------------------------| +| `TYPE` | Vector type (`FLOAT16` or `FLOAT32`). Note: `COMPRESSION` is supported with both types. | +| `DIM` | The width, or number of dimensions, of the vector embeddings stored in this field. In other words, the number of floating point elements comprising the vector. `DIM` must be a positive integer. The vector used to query this field must have the exact same dimensions as the field itself. | +| `DISTANCE_METRIC` | Distance metric (`L2`, `IP`, `COSINE`). | + +**Optional attributes** + +`SVS-VAMANA` supports a number of additional parameters to tune the accuracy of the queries. + +| Attribute | Description | Default value | +|:---------------------------|:-----------------------------------------|:-------------:| +| `COMPRESSION` | Compression algorithm; one of `LVQ8`, `LVQ4`, `LVQ4x4`, `LVQ4x8`, `LeanVec4x8`, or `LeanVec8x8`. Vectors will be compressed during indexing. See below for descriptions of each algorithm. Also, see these Intel pages for best practices on using these algorithms: [`COMPRESSION` settings](https://intel.github.io/ScalableVectorSearch/howtos.html#compression-setting) and [`LeanVec`](https://intel.github.io/ScalableVectorSearch/python/experimental/leanvec.html). | `LVQ4x4` | +| `CONSTRUCTION_WINDOW_SIZE` | The search window size to use during graph construction. A higher search window size will yield a higher quality graph since more overall vertexes are considered, but will increase construction time. | 200 | +| `GRAPH_MAX_DEGREE` | Sets the maximum number of edges per node; equivalent to `HNSW’s M*2`. A higher max degree may yield a higher quality graph in terms of recall for performance, but the memory footprint of the graph is directly proportional to the maximum degree. | 32 | +| `SEARCH_WINDOW_SIZE` | The size of the search window; the same as `HSNW's EF_RUNTIME`. Increasing the search window size and capacity generally yields more accurate but slower search results. | 10 | +| `EPSILON` | The range search approximation factor; the same as `HSNW's EPSILON`. | 0.01 | +| `TRAINING_THRESHOLD` | Number of vectors needed to learn compression parameters. Applicable only when used with `COMPRESSION`. Increase if recall is low. Note: setting this too high may slow down search.If a value is provided, it must be less than `100 * DEFAULT_BLOCK_SIZE`, where `DEFAULT_BLOCK_SIZE` is 1024. | `10 * DEFAULT_BLOCK_SIZE` | +| `LEANVEC_DIM` | The dimension used when using `LeanVec4x8` or `LeanVec8x8` compression for dimensionality reduction. If a value is provided, it should be less than `DIM`. Lowering it can speed up search and reduce memory use. | `DIM / 2` | + +{{< warning >}} +On non-Intel platforms, `SVS-VAMANA` with `COMPRESSION` will fall back to Intel’s basic scalar quantization implementation. +{{< /warning >}} + +**SVS_VAMANA vector compression algorithms** + +LVQ is a scalar quantization method that applies scaling constants for each vector. LeanVec builds on this by combining query-aware dimensionality reduction with LVQ-based scalar quantization for efficient vector compression. + +`LVQ4x4` (the default): Fast search with 4x vector compression relative to float32-encoded vectors (8 bits per dimension) and high accuracy. + +`LeanVec4x8`: Recommended for high-dimensional datasets. It offers the fastest search and ingestion. It's not the default because in rare cases it may reduce recall if the data does not compress well. + +`LeanVec` dimensional: For faster search and lower memory use, reduce the dimension further (default is input `dim / 2`; try `dim / 4` or even higher reduction). + +`LVQ8`: Faster ingestion than the default, but with slower search. + +| Compression algorithm | Best for | +|-----------------------|----------| +| `LVQ4x4` (default) | Fast search in most cases with low memory use. | +| `LeanVec4x8` | Fastest search and ingestion. | +| `LVQ4` | Maximum memory savings. | +| `LVQ8` | Faster ingestion than the default. | +| `LeanVec8x8` | Improved recall in cases where `LeanVec4x8` is not sufficient. | +| `LVQ4x8` | Improved recall in cases where the default is not sufficient. | + +**Example** + +``` +FT.CREATE documents + ON HASH + PREFIX 1 docs: + SCHEMA doc_embedding VECTOR SVS-VAMANA 12 + TYPE FLOAT32 + DIM 1536 + DISTANCE_METRIC COSINE + GRAPH_MAX_DEGREE 40 + CONSTRUCTION_WINDOW_SIZE 250 + COMPRESSION LVQ8 +``` + +In the example above, an index named `documents` is created over hashes with the key prefix `docs:` and an `SVS-VAMANA` vector field named `doc_embedding` with six index attributes: `TYPE`, `DIM`, `DISTANCE_METRIC`, `GRAPH_MAX_DEGREE`, `CONSTRUCTION_WINDOW_SIZE` and `COMPRESSION`. + ### Distance metrics Redis supports three popular distance metrics to measure the degree of similarity between two vectors $u$, $v$ $\in \mathbb{R}^n$, where $n$ is the length of the vectors: @@ -378,6 +451,17 @@ Optional runtime parameters for HNSW indexes are: | `EF_RUNTIME` | The maximum number of top candidates to hold during the KNN search. Higher values lead to more accurate results at the expense of a longer query runtime. | The value passed during index creation. The default is 10. | | `EPSILON` | The relative factor that sets the boundaries for a vector range query. Vector candidates whose distance from the query vector is `radius * (1 + EPSILON)` are potentially scanned, allowing a more extensive search and more accurate results at the expense of runtime. | The value passed during index creation. The default is 0.01. | +**SVS-VAMANA** + +Optional runtime parameters for SVS-VAMANA indexes are: + +| Parameter | Description | Default value | +|:----------|:------------|:--------------| +| `SEARCH_WINDOW_SIZE` | The size of the search window (applies only to KNN searches). | 10 or the value that was passed upon index creation. | +| `EPSILON` | The range search approximation factor. | 0.01 or the value that was passed upon index creation. | +| `USE_SEARCH_HISTORY` | When building an index, either the contents of the search buffer is used or the entire search history is used. The latter case may yield a slightly better graph at the cost of more search time. Boolean options are `OFF`, `ON`, and `AUTO`. `AUTO` is always evaluated internally as `ON`. | `AUTO` | +| `SEARCH_BUFFER_CAPACITY` | A tuning parameter used in compressed `SVS-VAMANA` indexes, which are using a two-level compression type (`LVQx` or one of the `LeanVec` types), that determines the number of vector candidates to collect in the first level of the search, before the re-ranking level (which is the second level). | `SEARCH_WINDOW_SIZE` | + ### Important notes diff --git a/content/develop/data-types/bitmaps.md b/content/develop/data-types/bitmaps.md index ecfec177a..1bbfa40f3 100644 --- a/content/develop/data-types/bitmaps.md +++ b/content/develop/data-types/bitmaps.md @@ -9,9 +9,7 @@ categories: - oss - kubernetes - clients -description: 'Introduction to Redis bitmaps - - ' +description: Introduction to Redis bitmaps linkTitle: Bitmaps title: Redis bitmaps weight: 120 @@ -79,7 +77,7 @@ stored into the target key) are always considered to be zero. There are three commands operating on group of bits: -1. [`BITOP`]({{< relref "/commands/bitop" >}}) performs bit-wise operations between different strings. The provided operations are AND, OR, XOR and NOT. +1. [`BITOP`]({{< relref "/commands/bitop" >}}) performs bit-wise operations between different strings. The provided operators are `AND`, `OR`, `XOR`, `NOT`, `DIFF`, `DIFF1`, `ANDOR`, and `ONE`. 2. [`BITCOUNT`]({{< relref "/commands/bitcount" >}}) performs population counting, reporting the number of bits set to 1. 3. [`BITPOS`]({{< relref "/commands/bitpos" >}}) finds the first bit having the specified value of 0 or 1. diff --git a/content/develop/data-types/streams.md b/content/develop/data-types/streams.md index 7f4b9dfd9..3a1434401 100644 --- a/content/develop/data-types/streams.md +++ b/content/develop/data-types/streams.md @@ -9,9 +9,7 @@ categories: - oss - kubernetes - clients -description: 'Introduction to Redis streams - - ' +description: Introduction to Redis streams linkTitle: Streams title: Redis Streams weight: 60 @@ -28,16 +26,18 @@ Examples of Redis stream use cases include: Redis generates a unique ID for each stream entry. You can use these IDs to retrieve their associated entries later or to read and process all subsequent entries in the stream. Note that because these IDs are related to time, the ones shown here may vary and will be different from the IDs you see in your own Redis instance. -Redis streams support several trimming strategies (to prevent streams from growing unbounded) and more than one consumption strategy (see [`XREAD`]({{< relref "/commands/xread" >}}), [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}), and [`XRANGE`]({{< relref "/commands/xrange" >}})). +Redis streams support several trimming strategies (to prevent streams from growing unbounded) and more than one consumption strategy (see [`XREAD`]({{< relref "/commands/xread" >}}), [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}), and [`XRANGE`]({{< relref "/commands/xrange" >}})). Starting with Redis 8.2, the `XACKDEL`, `XDELEX`, `XADD`, and `XTRIM` commands provide fine-grained control over how stream operations interact with multiple consumer groups, simplifying the coordination of message processing across different applications. ## Basic commands + * [`XADD`]({{< relref "/commands/xadd" >}}) adds a new entry to a stream. * [`XREAD`]({{< relref "/commands/xread" >}}) reads one or more entries, starting at a given position and moving forward in time. * [`XRANGE`]({{< relref "/commands/xrange" >}}) returns a range of entries between two supplied entry IDs. * [`XLEN`]({{< relref "/commands/xlen" >}}) returns the length of a stream. - -See the [complete list of stream commands]({{< relref "/commands/" >}}?group=stream). +* [`XDEL`]({{< relref "/commands/xdel" >}}) removes entries from a stream. +* [`XTRIM`]({{< relref "/commands/xtrim" >}}) trims a stream by removing older entries. +See the [complete list of stream commands]({{< relref "/commands/" >}}?group=stream). ## Examples @@ -90,7 +90,6 @@ For details on why, note that streams are implemented as [radix trees](https://e Simply put, Redis streams provide highly efficient inserts and reads. See each command's time complexity for the details. - ## Streams basics Streams are an append-only data structure. The fundamental write command, called [`XADD`]({{< relref "/commands/xadd" >}}), appends a new entry to the specified stream. @@ -393,6 +392,7 @@ Now it's time to zoom in to see the fundamental consumer group commands. They ar * [`XGROUP`]({{< relref "/commands/xgroup" >}}) is used in order to create, destroy and manage consumer groups. * [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}) is used to read from a stream via a consumer group. * [`XACK`]({{< relref "/commands/xack" >}}) is the command that allows a consumer to mark a pending message as correctly processed. +* [`XACKDEL`]({{< relref "/commands/xackdel" >}}) combines acknowledgment and deletion in a single atomic operation with enhanced control over consumer group references. ## Creating a consumer group @@ -681,6 +681,31 @@ The counter that you observe in the [`XPENDING`]({{< relref "/commands/xpending" When there are failures, it is normal that messages will be delivered multiple times, but eventually they usually get processed and acknowledged. However there might be a problem processing some specific message, because it is corrupted or crafted in a way that triggers a bug in the processing code. In such a case what happens is that consumers will continuously fail to process this particular message. Because we have the counter of the delivery attempts, we can use that counter to detect messages that for some reason are not processable. So once the deliveries counter reaches a given large number that you chose, it is probably wiser to put such messages in another stream and send a notification to the system administrator. This is basically the way that Redis Streams implements the *dead letter* concept. +## Working with multiple consumer groups + +Redis Streams can be associated with multiple consumer groups, where each entry is delivered to all the stream's consumer groups. Within each consumer group, consumers handle a portion of the entries collaboratively. This design enables different applications or services to process the same stream data independently. + +When a consumer processes a message, it acknowledges it using the [`XACK`]({{< relref "/commands/xack" >}}) command, which removes the entry reference from the Pending Entries List (PEL) of that specific consumer group. However, the entry remains in the stream and in the PELs of other consumer groups until they also acknowledge it. + +Traditionally, applications needed to implement complex logic to delete entries from the stream only after all consumer groups had acknowledged them. This coordination was challenging to implement correctly and efficiently. + +### Enhanced deletion control in Redis 8.2 + +Starting with Redis 8.2, several commands provide enhanced control over how entries are handled with respect to multiple consumer groups: + +* [`XADD`]({{< relref "/commands/xadd" >}}) with trimming options now supports `KEEPREF`, `DELREF`, and `ACKED` modes +* [`XTRIM`]({{< relref "/commands/xtrim" >}}) supports the same reference handling options +* [`XDELEX`]({{< relref "/commands/xdelex" >}}) provides fine-grained deletion control +* [`XACKDEL`]({{< relref "/commands/xackdel" >}}) combines acknowledgment and deletion atomically + +These options control how consumer group references are handled: + +- **KEEPREF** (default): Preserves existing references to entries in all consumer groups' PELs, maintaining backward compatibility +- **DELREF**: Removes all references to entries from all consumer groups' PELs, effectively cleaning up all traces of the messages +- **ACKED**: Only processes entries that have been acknowledged by all consumer groups + +The `ACKED` option is particularly useful as it automates the complex logic of coordinating deletion across multiple consumer groups, ensuring entries are only removed when all groups have finished processing them. + ## Streams observability Messaging systems that lack observability are very hard to work with. Not knowing who is consuming messages, what messages are pending, the set of consumer groups active in a given stream, makes everything opaque. For this reason, Redis Streams and consumer groups have different ways to observe what is happening. We already covered [`XPENDING`]({{< relref "/commands/xpending" >}}), which allows us to inspect the list of messages that are under processing at a given moment, together with their idle time and number of deliveries. @@ -832,6 +857,21 @@ However, [`XTRIM`]({{< relref "/commands/xtrim" >}}) is designed to accept diffe As [`XTRIM`]({{< relref "/commands/xtrim" >}}) is an explicit command, the user is expected to know about the possible shortcomings of different trimming strategies. +### Trimming with consumer group awareness + +Starting with Redis 8.2, both [`XADD`]({{< relref "/commands/xadd" >}}) with trimming options and [`XTRIM`]({{< relref "/commands/xtrim" >}}) support enhanced control over how trimming interacts with consumer groups through the `KEEPREF`, `DELREF`, and `ACKED` options: + +``` +XADD mystream KEEPREF MAXLEN 1000 * field value +XTRIM mystream ACKED MAXLEN 1000 +``` + +- **KEEPREF** (default): Trims entries according to the strategy but preserves references in consumer group PELs +- **DELREF**: Trims entries and removes all references from consumer group PELs +- **ACKED**: Only trims entries that have been acknowledged by all consumer groups + +The `ACKED` option is particularly useful for maintaining data integrity across multiple consumer groups, ensuring that entries are only removed when all groups have finished processing them. + Another useful eviction strategy that may be added to [`XTRIM`]({{< relref "/commands/xtrim" >}}) in the future, is to remove by a range of IDs to ease use of [`XRANGE`]({{< relref "/commands/xrange" >}}) and [`XTRIM`]({{< relref "/commands/xtrim" >}}) to move data from Redis to other storage systems if needed. ## Special IDs in the streams API @@ -882,7 +922,15 @@ Streams also have a special command for removing items from the middle of a stre 2) "Wood" {{< /clients-example >}} -However in the current implementation, memory is not really reclaimed until a macro node is completely empty, so you should not abuse this feature. +### Enhanced deletion with XDELEX + +Starting with Redis 8.2, the [`XDELEX`]({{< relref "/commands/xdelex" >}}) command provides enhanced control over entry deletion, particularly when working with consumer groups. Like other enhanced commands, it supports `KEEPREF`, `DELREF`, and `ACKED` options: + +``` +XDELEX mystream ACKED IDS 2 1692633198206-0 1692633208557-0 +``` + +This allows you to delete entries only when they have been acknowledged by all consumer groups (`ACKED`), remove all consumer group references (`DELREF`), or preserve existing references (`KEEPREF`). ## Zero length streams @@ -931,9 +979,6 @@ A few remarks: * Here we processed up to 10k messages per iteration, this means that the `COUNT` parameter of [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}) was set to 10000. This adds a lot of latency but is needed in order to allow the slow consumers to be able to keep with the message flow. So you can expect a real world latency that is a lot smaller. * The system used for this benchmark is very slow compared to today's standards. - - - ## Learn more * The [Redis Streams Tutorial]({{< relref "/develop/data-types/streams" >}}) explains Redis streams with many examples. diff --git a/content/develop/data-types/vector-sets/_index.md b/content/develop/data-types/vector-sets/_index.md index f654418ff..f730a52f6 100644 --- a/content/develop/data-types/vector-sets/_index.md +++ b/content/develop/data-types/vector-sets/_index.md @@ -33,6 +33,7 @@ The following commands are available for vector sets: - [VEMB]({{< relref "/commands/vemb" >}}) - retrieve the approximate vector associated with a vector set element. - [VGETATTR]({{< relref "/commands/vgetattr" >}}) - retrieve the attributes of a vector set element. - [VINFO]({{< relref "/commands/vinfo" >}}) - retrieve metadata and internal details about a vector set, including size, dimensions, quantization type, and graph structure. +- [VISMEMBER]({{< relref "/commands/vismember" >}}) - check if an element exists in a vector set. - [VLINKS]({{< relref "/commands/vlinks" >}}) - retrieve the neighbors of a specified element in a vector set; the connections for each layer of the HNSW graph. - [VRANDMEMBER]({{< relref "/commands/vrandmember" >}}) - retrieve random elements of a vector set. - [VREM]({{< relref "/commands/vrem" >}}) - remove an element from a vector set. diff --git a/content/develop/pubsub/keyspace-notifications.md b/content/develop/pubsub/keyspace-notifications.md index bac450d12..9b8ee50a1 100644 --- a/content/develop/pubsub/keyspace-notifications.md +++ b/content/develop/pubsub/keyspace-notifications.md @@ -82,9 +82,11 @@ following table: d Module key type events x Expired events (events generated every time a key expires) e Evicted events (events generated when a key is evicted for maxmemory) - m Key miss events (events generated when a key that doesn't exist is accessed) - n New key events (Note: not included in the 'A' class) - A Alias for "g$lshztxed", so that the "AKE" string means all the events except "m" and "n". + m Key miss events generated when a key that doesn't exist is accessed (Note: not included in the 'A' class) + n New key events generated whenever a new key is created (Note: not included in the 'A' class) + o Overwritten events generated every time a key is overwritten (Note: not included in the 'A' class) + c Type-changed events generated every time a key's type changes (Note: not included in the 'A' class) + A Alias for "g$lshztdxe", so that the "AKE" string means all the events except "m", "n", "o" and "c". At least `K` or `E` should be present in the string, otherwise no event will be delivered regardless of the rest of the string. @@ -151,6 +153,8 @@ Different commands generate different kind of events according to the following * Every time a key with a time to live associated is removed from the data set because it expired, an `expired` event is generated. * Every time a key is evicted from the data set in order to free memory as a result of the `maxmemory` policy, an `evicted` event is generated. * Every time a new key is added to the data set, a `new` event is generated. +* Every time a key is being overwritten, an `overwritten` event is generated. +* Every time a key's type changes, a `type_changed` event is generated. **IMPORTANT** all the commands generate events only if the target key is really modified. For instance an [`SREM`]({{< relref "/commands/srem" >}}) deleting a non-existing element from a Set will not actually change the value of the key, so no event will be generated. diff --git a/content/develop/reference/modules/modules-api-ref.md b/content/develop/reference/modules/modules-api-ref.md index 0bd64c308..c4aaf91cf 100644 --- a/content/develop/reference/modules/modules-api-ref.md +++ b/content/develop/reference/modules/modules-api-ref.md @@ -58,6 +58,7 @@ weight: 1 * [Server hooks implementation](#section-server-hooks-implementation) * [Module Configurations API](#section-module-configurations-api) * [RDB load/save API](#section-rdb-load-save-api) +* [Config access API](#section-config-access-api) * [Key eviction API](#section-key-eviction-api) * [Miscellaneous APIs](#section-miscellaneous-apis) * [Defrag API](#section-defrag-api) @@ -3166,7 +3167,7 @@ The returned `RedisModuleString` objects should be released with mstime_t RedisModule_HashFieldMinExpire(RedisModuleKey *key); -**Available since:** unreleased +**Available since:** 8.0.0 Retrieves the minimum expiration time of fields in a hash. @@ -5042,7 +5043,13 @@ is interested in. This can be an ORed mask of any of the following flags: this notification is wrong and discourage. It will cause the read command that trigger the event to be replicated to the AOF/Replica. - - `REDISMODULE_NOTIFY_ALL`: All events (Excluding `REDISMODULE_NOTIFY_KEYMISS`) + + - `REDISMODULE_NOTIFY_NEW`: New key notification + - `REDISMODULE_NOTIFY_OVERWRITTEN`: Overwritten events + - `REDISMODULE_NOTIFY_TYPE_CHANGED`: Type-changed events + - `REDISMODULE_NOTIFY_ALL`: All events (Excluding `REDISMODULE_NOTIFY_KEYMISS`, + REDISMODULE_NOTIFY_NEW, REDISMODULE_NOTIFY_OVERWRITTEN + and REDISMODULE_NOTIFY_TYPE_CHANGED) - `REDISMODULE_NOTIFY_LOADED`: A special notification available only for modules, indicates that the key was loaded from persistence. Notice, when this event fires, the given key @@ -5081,6 +5088,31 @@ write actions, please refer to [`RedisModule_AddPostNotificationJob`](#RedisModu See [https://redis.io/docs/latest/develop/use/keyspace-notifications/](https://redis.io/docs/latest/develop/use/keyspace-notifications/) for more information. + + +### `RedisModule_UnsubscribeFromKeyspaceEvents` + + int RedisModule_UnsubscribeFromKeyspaceEvents(RedisModuleCtx *ctx, + int types, + RedisModuleNotificationFunc callback); + +**Available since:** unreleased + + +[`RedisModule_UnsubscribeFromKeyspaceEvents`](#RedisModule_UnsubscribeFromKeyspaceEvents) - Unregister a module's callback from keyspace notifications for specific event types. + +This function removes a previously registered subscription identified by both the event mask and the callback function. +It is useful to reduce performance overhead when the module no longer requires notifications for certain events. + +Parameters: + - ctx: The `RedisModuleCtx` associated with the calling module. + - types: The event mask representing the keyspace notification types to unsubscribe from. + - callback: The callback function pointer that was originally registered for these events. + +Returns: + - `REDISMODULE_OK` on successful removal of the subscription. + - `REDISMODULE_ERR` if no matching subscription was found or if invalid parameters were provided. + ### `RedisModule_AddPostNotificationJob` @@ -5650,7 +5682,7 @@ If the user is able to access the key then `REDISMODULE_OK` is returned, otherwi RedisModuleString *prefix, int flags); -**Available since:** unreleased +**Available since:** 8.0.0 Check if the user can access keys matching the given key prefix according to the ACLs attached to the user and the flags representing key access. The flags are the same that @@ -7435,7 +7467,7 @@ Create an integer config that server clients can interact with via the int RedisModule_LoadDefaultConfigs(RedisModuleCtx *ctx); -**Available since:** unreleased +**Available since:** 8.0.0 Applies all default configurations for the parameters the module registered. Only call this function if the module would like to make changes to the @@ -7542,12 +7574,273 @@ Example: const char* RedisModule_GetInternalSecret(RedisModuleCtx *ctx, size_t *len); -**Available since:** unreleased +**Available since:** 8.0.0 Returns the internal secret of the cluster. Should be used to authenticate as an internal connection to a node in the cluster, and by that gain the permissions to execute internal commands. + + +## Config access API + + + +### `RedisModule_ConfigIteratorCreate` + + RedisModuleConfigIterator *RedisModule_ConfigIteratorCreate(RedisModuleCtx *ctx, + const char *pattern); + +**Available since:** unreleased + +Get an iterator to all configs. +Optional `ctx` can be provided if use of auto-memory is desired. +Optional `pattern` can be provided to filter configs by name. If `pattern` is +NULL all configs will be returned. + +The returned iterator can be used to iterate over all configs using +[`RedisModule_ConfigIteratorNext()`](#RedisModule_ConfigIteratorNext). + +Example usage: +``` +// Below is same as [`RedisModule_ConfigIteratorCreate`](#RedisModule_ConfigIteratorCreate)(ctx, NULL) +`RedisModuleConfigIterator` *iter = [`RedisModule_ConfigIteratorCreate`](#RedisModule_ConfigIteratorCreate)(ctx, "*"); +const char *config_name = NULL; +while ((`config_name` = [`RedisModule_ConfigIteratorNext`](#RedisModule_ConfigIteratorNext)(iter)) != NULL) { + RedisModuleString *value = NULL; + if (RedisModule_ConfigGet(ctx, config_name, &value) == REDISMODULE_OK) { + // Do something with `value`... + RedisModule_FreeString(ctx, value); + } +} +[`RedisModule_ConfigIteratorRelease`](#RedisModule_ConfigIteratorRelease)(ctx, iter); + +// Or optionally one can check the type to get the config value directly +// via the appropriate API in case performance is of consideration +iter = [`RedisModule_ConfigIteratorCreate`](#RedisModule_ConfigIteratorCreate)(ctx, "*"); +while ((`config_name` = [`RedisModule_ConfigIteratorNext`](#RedisModule_ConfigIteratorNext)(iter)) != NULL) { + RedisModuleConfigType type = RedisModule_ConfigGetType(config_name); + if (type == REDISMODULE_CONFIG_TYPE_STRING) { + RedisModuleString *value; + RedisModule_ConfigGet(ctx, config_name, &value); + // Do something with `value`... + RedisModule_FreeString(ctx, value); + } if (type == REDISMODULE_CONFIG_TYPE_NUMERIC) { + long long value; + RedisModule_ConfigGetNumeric(ctx, config_name, &value); + // Do something with `value`... + } else if (type == REDISMODULE_CONFIG_TYPE_BOOL) { + int value; + RedisModule_ConfigGetBool(ctx, config_name, &value); + // Do something with `value`... + } else if (type == REDISMODULE_CONFIG_TYPE_ENUM) { + RedisModuleString *value; + RedisModule_ConfigGetEnum(ctx, config_name, &value); + // Do something with `value`... + RedisModule_Free(value); + } +} +[`RedisModule_ConfigIteratorRelease`](#RedisModule_ConfigIteratorRelease)(ctx, iter); +``` + +Returns a pointer to `RedisModuleConfigIterator`. Unless auto-memory is enabled +the caller is responsible for freeing the iterator using +[`RedisModule_ConfigIteratorRelease()`](#RedisModule_ConfigIteratorRelease). + + + +### `RedisModule_ConfigIteratorRelease` + + void RedisModule_ConfigIteratorRelease(RedisModuleCtx *ctx, + RedisModuleConfigIterator *iter); + +**Available since:** unreleased + +Release the iterator returned by [`RedisModule_ConfigIteratorCreate()`](#RedisModule_ConfigIteratorCreate). If auto-memory +is enabled and manual release is needed one must pass the same `RedisModuleCtx` +that was used to create the iterator. + + + +### `RedisModule_ConfigGetType` + + int RedisModule_ConfigGetType(const char *name, RedisModuleConfigType *res); + +**Available since:** unreleased + +Get the type of a config as `RedisModuleConfigType`. One may use this in order +to get or set the values of the config with the appropriate function if the +generic [`RedisModule_ConfigGet`](#RedisModule_ConfigGet) and [`RedisModule_ConfigSet`](#RedisModule_ConfigSet) APIs are performing +poorly. + +Intended usage of this function is when iteration over the configs is +performed. See [`RedisModule_ConfigIteratorNext()`](#RedisModule_ConfigIteratorNext) for example usage. If setting +or getting individual configs one can check the config type by hand in +redis.conf (or via other sources if config is added by a module) and use the +appropriate function without the need to call this function. + +Explanation of config types: + - `REDISMODULE_CONFIG_TYPE_BOOL`: Config is a boolean. One can use `RedisModule_Config`(Get/Set)Bool + - `REDISMODULE_CONFIG_TYPE_NUMERIC`: Config is a numeric value. One can use `RedisModule_Config`(Get/Set)Numeric + - `REDISMODULE_CONFIG_TYPE_STRING`: Config is a string. One can use the generic `RedisModule_Config`(Get/Set) + - `REDISMODULE_CONFIG_TYPE_ENUM`: Config is an enum. One can use `RedisModule_Config`(Get/Set)Enum + +If a config with the given name exists `res` is populated with its type, else +`REDISMODULE_ERR` is returned. + + + +### `RedisModule_ConfigIteratorNext` + + const char *RedisModule_ConfigIteratorNext(RedisModuleConfigIterator *iter); + +**Available since:** unreleased + +Go to the next element of the config iterator. + +Returns the name of the next config, or NULL if there are no more configs. +Returned string is non-owning and thus should not be freed. +If a pattern was provided when creating the iterator, only configs matching +the pattern will be returned. + +See [`RedisModule_ConfigIteratorCreate()`](#RedisModule_ConfigIteratorCreate) for example usage. + + + +### `RedisModule_ConfigGet` + + int RedisModule_ConfigGet(RedisModuleCtx *ctx, + const char *name, + RedisModuleString **res); + +**Available since:** unreleased + +Get the value of a config as a string. This function can be used to get the +value of any config, regardless of its type. + +The string is allocated by the module and must be freed by the caller unless +auto memory is enabled. + +If the config does not exist, `REDISMODULE_ERR` is returned, else `REDISMODULE_OK` +is returned and `res` is populated with the value. + + + +### `RedisModule_ConfigGetBool` + + int RedisModule_ConfigGetBool(RedisModuleCtx *ctx, const char *name, int *res); + +**Available since:** unreleased + +Get the value of a bool config. + +If the config does not exist or is not a bool config, `REDISMODULE_ERR` is +returned, else `REDISMODULE_OK` is returned and `res` is populated with the +value. + + + +### `RedisModule_ConfigGetEnum` + + int RedisModule_ConfigGetEnum(RedisModuleCtx *ctx, + const char *name, + RedisModuleString **res); + +**Available since:** unreleased + +Get the value of an enum config. + +If the config does not exist or is not an enum config, `REDISMODULE_ERR` is +returned, else `REDISMODULE_OK` is returned and `res` is populated with the value. +If the config has multiple arguments they are returned as a space-separated +string. + + + +### `RedisModule_ConfigGetNumeric` + + int RedisModule_ConfigGetNumeric(RedisModuleCtx *ctx, + const char *name, + long long *res); + +**Available since:** unreleased + +Get the value of a numeric config. + +If the config does not exist or is not a numeric config, `REDISMODULE_ERR` is +returned, else `REDISMODULE_OK` is returned and `res` is populated with the +value. + + + +### `RedisModule_ConfigSet` + + int RedisModule_ConfigSet(RedisModuleCtx *ctx, + const char *name, + RedisModuleString *value, + RedisModuleString **err); + +**Available since:** unreleased + +Set the value of a config. + +This function can be used to set the value of any config, regardless of its +type. If the config is multi-argument, the value must be a space-separated +string. + +If the value failed to be set `REDISMODULE_ERR` will be returned and if `err` +is not NULL, it will be populated with an error message. + + + +### `RedisModule_ConfigSetBool` + + int RedisModule_ConfigSetBool(RedisModuleCtx *ctx, + const char *name, + int value, + RedisModuleString **err); + +**Available since:** unreleased + +Set the value of a bool config. + +See [`RedisModule_ConfigSet`](#RedisModule_ConfigSet) for return value. + + + +### `RedisModule_ConfigSetEnum` + + int RedisModule_ConfigSetEnum(RedisModuleCtx *ctx, + const char *name, + RedisModuleString *value, + RedisModuleString **err); + +**Available since:** unreleased + +Set the value of an enum config. + +If the config is multi-argument the value parameter must be a space-separated +string. + +See [`RedisModule_ConfigSet`](#RedisModule_ConfigSet) for return value. + + + +### `RedisModule_ConfigSetNumeric` + + int RedisModule_ConfigSetNumeric(RedisModuleCtx *ctx, + const char *name, + long long value, + RedisModuleString **err); + +**Available since:** unreleased + +Set the value of a numeric config. +If the value passed is meant to be a percentage, it should be passed as a +negative value. + +See [`RedisModule_ConfigSet`](#RedisModule_ConfigSet) for return value. + ## Key eviction API @@ -7801,7 +8094,7 @@ may allocate that is not tied to a specific data type. int RedisModule_RegisterDefragFunc2(RedisModuleCtx *ctx, RedisModuleDefragFunc2 cb); -**Available since:** unreleased +**Available since:** 8.0.0 Register a defrag callback for global data, i.e. anything that the module may allocate that is not tied to a specific data type. @@ -7817,7 +8110,7 @@ in and indicate that it should be called again later, or is it done (returned 0) RedisModuleDefragFunc start, RedisModuleDefragFunc end); -**Available since:** unreleased +**Available since:** 8.0.0 Register a defrag callbacks that will be called when defrag operation starts and ends. @@ -7914,7 +8207,7 @@ be used again. void *RedisModule_DefragAllocRaw(RedisModuleDefragCtx *ctx, size_t size); -**Available since:** unreleased +**Available since:** 8.0.0 Allocate memory for defrag purposes @@ -7934,7 +8227,7 @@ allow to support more complex defrag usecases. void RedisModule_DefragFreeRaw(RedisModuleDefragCtx *ctx, void *ptr); -**Available since:** unreleased +**Available since:** 8.0.0 Free memory for defrag purposes @@ -7968,7 +8261,7 @@ on the Redis side is dropped as soon as the command callback returns). RedisModuleDefragDictValueCallback valueCB, RedisModuleString **seekTo); -**Available since:** unreleased +**Available since:** 8.0.0 Defragment a Redis Module Dictionary by scanning its contents and calling a value callback for each value. @@ -8061,6 +8354,18 @@ There is no guarantee that this info is always available, so this may return -1. * [`RedisModule_CommandFilterArgReplace`](#RedisModule_CommandFilterArgReplace) * [`RedisModule_CommandFilterArgsCount`](#RedisModule_CommandFilterArgsCount) * [`RedisModule_CommandFilterGetClientId`](#RedisModule_CommandFilterGetClientId) +* [`RedisModule_ConfigGet`](#RedisModule_ConfigGet) +* [`RedisModule_ConfigGetBool`](#RedisModule_ConfigGetBool) +* [`RedisModule_ConfigGetEnum`](#RedisModule_ConfigGetEnum) +* [`RedisModule_ConfigGetNumeric`](#RedisModule_ConfigGetNumeric) +* [`RedisModule_ConfigGetType`](#RedisModule_ConfigGetType) +* [`RedisModule_ConfigIteratorCreate`](#RedisModule_ConfigIteratorCreate) +* [`RedisModule_ConfigIteratorNext`](#RedisModule_ConfigIteratorNext) +* [`RedisModule_ConfigIteratorRelease`](#RedisModule_ConfigIteratorRelease) +* [`RedisModule_ConfigSet`](#RedisModule_ConfigSet) +* [`RedisModule_ConfigSetBool`](#RedisModule_ConfigSetBool) +* [`RedisModule_ConfigSetEnum`](#RedisModule_ConfigSetEnum) +* [`RedisModule_ConfigSetNumeric`](#RedisModule_ConfigSetNumeric) * [`RedisModule_CreateCommand`](#RedisModule_CreateCommand) * [`RedisModule_CreateDataType`](#RedisModule_CreateDataType) * [`RedisModule_CreateDict`](#RedisModule_CreateDict) @@ -8356,6 +8661,7 @@ There is no guarantee that this info is always available, so this may return -1. * [`RedisModule_UnblockClient`](#RedisModule_UnblockClient) * [`RedisModule_UnlinkKey`](#RedisModule_UnlinkKey) * [`RedisModule_UnregisterCommandFilter`](#RedisModule_UnregisterCommandFilter) +* [`RedisModule_UnsubscribeFromKeyspaceEvents`](#RedisModule_UnsubscribeFromKeyspaceEvents) * [`RedisModule_ValueLength`](#RedisModule_ValueLength) * [`RedisModule_WrongArity`](#RedisModule_WrongArity) * [`RedisModule_Yield`](#RedisModule_Yield) @@ -8373,4 +8679,3 @@ There is no guarantee that this info is always available, so this may return -1. * [`RedisModule_ZsetRem`](#RedisModule_ZsetRem) * [`RedisModule_ZsetScore`](#RedisModule_ZsetScore) * [`RedisModule__Assert`](#RedisModule__Assert) - diff --git a/static/resources/redisuniversity.yaml b/static/resources/redisuniversity.yaml index d2ec3d78f..ebd578faf 100644 --- a/static/resources/redisuniversity.yaml +++ b/static/resources/redisuniversity.yaml @@ -63,6 +63,6 @@ links: text: See the [Get started with Redis Software learning path](https://university.redis.io/learningpath/an0mgw5bjpjfbe) for courses. # Redis Develop links - - page: /develop/interact/search-and-query/advanced-concepts/vectors + - page: /develop/ai/search-and-query/vectors text: See the [Introduction to vector search course](https://university.redis.io/course/yz1lretjfpdlew?tab=details) to learn more. - + \ No newline at end of file