From a89f02adfc3a5ea3c2461c6fb2d961b3b51ee0d3 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Mon, 24 Feb 2025 08:59:26 -0800 Subject: [PATCH 1/2] DEV: add new HFE commands --- content/commands/hgetdel/index.md | 88 +++++++++++++++++ content/commands/hgetdel/syntax.svg | 20 ++++ content/commands/hgetex/index.md | 127 ++++++++++++++++++++++++ content/commands/hgetex/syntax.svg | 20 ++++ content/commands/hsetex/index.md | 143 ++++++++++++++++++++++++++++ content/commands/hsetex/syntax.svg | 20 ++++ data/resp2_replies.json | 13 +++ data/resp3_replies.json | 13 +++ 8 files changed, 444 insertions(+) create mode 100644 content/commands/hgetdel/index.md create mode 100644 content/commands/hgetdel/syntax.svg create mode 100644 content/commands/hgetex/index.md create mode 100644 content/commands/hgetex/syntax.svg create mode 100644 content/commands/hsetex/index.md create mode 100644 content/commands/hsetex/syntax.svg diff --git a/content/commands/hgetdel/index.md b/content/commands/hgetdel/index.md new file mode 100644 index 000000000..93cadb98b --- /dev/null +++ b/content/commands/hgetdel/index.md @@ -0,0 +1,88 @@ +--- +acl_categories: +- '@write' +- '@hash' +- '@fast' +arguments: +- display_text: key + key_spec_index: 0 + name: key + type: key +- arguments: + - display_text: numfields + name: numfields + type: integer + - display_text: field + multiple: true + name: field + type: string + name: fields + token: FIELDS + type: block +arity: -5 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- write +- fast +complexity: O(N) where N is the number of specified fields +description: Returns the value of a field and deletes it from the hash. +group: hash +hidden: false +key_specs: +- RW: true + access: true + begin_search: + spec: + index: 1 + type: index + delete: true + find_keys: + spec: + keystep: 1 + lastkey: 0 + limit: 0 + type: range +linkTitle: HGETDEL +since: 8.0.0 +summary: Returns the value of a field and deletes it from the hash. +syntax_fmt: "HGETDEL key FIELDS\_numfields field [field ...]" +syntax_str: "FIELDS\_numfields field [field ...]" +title: HGETDEL +--- +Get and delete the value of one or more fields of a given hash key. When the last field is deleted, the key will also be deleted. + +## Example + +``` +redis> HSET mykey field1 "Hello" field2 "World" field3 "!" +(integer) 3 +redis> HGETALL mykey +1) "field1" +2) "Hello" +3) "field2" +4) "World" +5) "field3" +6) "!" +redis> HGETDEL mykey FIELDS 2 field3 field4 +1) "!" +2) (nil) +redis> HGETALL mykey +1) "field1" +2) "Hello" +3) "field2" +4) "World" +redis> HGETDEL mykey FIELDS 2 field1 field2 +1) "Hello" +2) "World" +redis> KEYS * +(empty array) +``` diff --git a/content/commands/hgetdel/syntax.svg b/content/commands/hgetdel/syntax.svg new file mode 100644 index 000000000..5687b8db0 --- /dev/null +++ b/content/commands/hgetdel/syntax.svg @@ -0,0 +1,20 @@ + + + + + + +HEXPIRE +keykey +secondsinteger + + + +XX +NX +GT +LT +numfieldsinteger + +fieldstring + \ No newline at end of file diff --git a/content/commands/hgetex/index.md b/content/commands/hgetex/index.md new file mode 100644 index 000000000..c4d75a03e --- /dev/null +++ b/content/commands/hgetex/index.md @@ -0,0 +1,127 @@ +--- +acl_categories: +- '@write' +- '@hash' +- '@fast' +arguments: +- display_text: key + key_spec_index: 0 + name: key + type: key +- arguments: + - display_text: seconds + name: seconds + token: EX + type: integer + - display_text: milliseconds + name: milliseconds + token: PX + type: integer + - display_text: unix-time-seconds + name: unix-time-seconds + token: EXAT + type: unix-time + - display_text: unix-time-milliseconds + name: unix-time-milliseconds + token: PXAT + type: unix-time + - display_text: persist + name: persist + token: PERSIST + type: pure-token + name: expiration + optional: true + type: oneof +- arguments: + - display_text: numfields + name: numfields + type: integer + - display_text: field + multiple: true + name: field + type: string + name: fields + token: FIELDS + type: block +arity: -5 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- write +- fast +complexity: O(N) where N is the number of specified fields +description: Get the value of one or more fields of a given hash key, and optionally + set their expiration. +group: hash +hidden: false +key_specs: +- RW: true + access: true + begin_search: + spec: + index: 1 + type: index + find_keys: + spec: + keystep: 1 + lastkey: 0 + limit: 0 + type: range + notes: RW and UPDATE because it changes the TTL + update: true +linkTitle: HGETEX +since: 8.0.0 +summary: Get the value of one or more fields of a given hash key, and optionally set + their expiration. +syntax_fmt: "HGETEX key [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds\ + \ |\n PXAT\_unix-time-milliseconds | PERSIST] FIELDS\_numfields field\n [field\ + \ ...]" +syntax_str: "[EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds | PXAT\_unix-time-milliseconds\ + \ | PERSIST] FIELDS\_numfields field [field ...]" +title: HGETEX +--- +Get the value of one or more fields of a given hash key and optionally set their expirations (time-to-live or TTL). + +## Options + +The `HGETEX` command supports a set of options: + +* `EX seconds` -- Set the specified expiration time, in seconds. +* `PX milliseconds` -- Set the specified expiration time, in milliseconds. +* `EXAT unix-time-seconds` -- Set the specified Unix time at which the field will expire, in seconds. +* `PXAT unix-time-milliseconds` -- Set the specified Unix time at which the field will expire, in milliseconds. +* `PERSIST` -- Remove the TTL associated with the field. + +The `EX`, `PX`, `EXAT`, `PXAT`, and `PERSIST` options are mutually exclusive. + +## Example + +``` +redis> HSET mykey field1 "Hello" field2 "World" +(integer) 2 +redis> HGETEX mykey EX 120 FIELDS 1 field1 +1) "Hello" +redis> HGETEX mykey EX 100 FIELDS 1 field2 +1) "World" +redis> HTTL mykey FIELDS 2 field1 field2 +1) (integer) 91 +2) (integer) 85 +redis> HTTL mykey FIELDS 3 field1 field2 field3 +1) (integer) 75 +2) (integer) 68 +3) (integer) -2 +... +redis> HTTL mykey FIELDS 3 field1 field2 +1) (integer) -2 +2) (integer) -2 +redis> HGETALL mykey +(empty array) +``` diff --git a/content/commands/hgetex/syntax.svg b/content/commands/hgetex/syntax.svg new file mode 100644 index 000000000..5687b8db0 --- /dev/null +++ b/content/commands/hgetex/syntax.svg @@ -0,0 +1,20 @@ + + + + + + +HEXPIRE +keykey +secondsinteger + + + +XX +NX +GT +LT +numfieldsinteger + +fieldstring + \ No newline at end of file diff --git a/content/commands/hsetex/index.md b/content/commands/hsetex/index.md new file mode 100644 index 000000000..5b3b1d739 --- /dev/null +++ b/content/commands/hsetex/index.md @@ -0,0 +1,143 @@ +--- +acl_categories: +- '@write' +- '@hash' +- '@fast' +arguments: +- display_text: key + key_spec_index: 0 + name: key + type: key +- arguments: + - display_text: fnx + name: fnx + token: FNX + type: pure-token + - display_text: fxx + name: fxx + token: FXX + type: pure-token + name: condition + optional: true + type: oneof +- arguments: + - display_text: seconds + name: seconds + token: EX + type: integer + - display_text: milliseconds + name: milliseconds + token: PX + type: integer + - display_text: unix-time-seconds + name: unix-time-seconds + token: EXAT + type: unix-time + - display_text: unix-time-milliseconds + name: unix-time-milliseconds + token: PXAT + type: unix-time + - display_text: keepttl + name: keepttl + token: KEEPTTL + type: pure-token + name: expiration + optional: true + type: oneof +- arguments: + - display_text: numfields + name: numfields + type: integer + - arguments: + - display_text: field + name: field + type: string + - display_text: value + name: value + type: string + multiple: true + name: data + type: block + name: fields + token: FIELDS + type: block +arity: -6 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- write +- denyoom +- fast +complexity: O(N) where N is the number of fields being set. +description: Set the value of one or more fields of a given hash key, and optionally + set their expiration. +group: hash +hidden: false +key_specs: +- RW: true + begin_search: + spec: + index: 1 + type: index + find_keys: + spec: + keystep: 1 + lastkey: 0 + limit: 0 + type: range + update: true +linkTitle: HSETEX +since: 8.0.0 +summary: Set the value of one or more fields of a given hash key, and optionally set + their expiration. +syntax_fmt: "HSETEX key [FNX | FXX] [EX\_seconds | PX\_milliseconds |\n EXAT\_unix-time-seconds\ + \ | PXAT\_unix-time-milliseconds | KEEPTTL]\n FIELDS\_numfields field value [field\ + \ value ...]" +syntax_str: "[FNX | FXX] [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds\ + \ | PXAT\_unix-time-milliseconds | KEEPTTL] FIELDS\_numfields field value [field\ + \ value ...]" +title: HSETEX +--- +Set the value of one or more fields of a given hash key, and optionally set their expirations (time-to-live or TTL). + +## Options + +The `HGETEX` command supports a set of options: + +* `FNX` -- Only set the fields if none of them already exist. +* `FXX` -- Only set the fields if all of them already exist. +* `EX seconds` -- Set the specified expiration time in seconds. +* `PX milliseconds` -- Set the specified expiration time in milliseconds. +* `EXAT unix-time-seconds` -- Set the specified Unix time in seconds at which the field will expire. +* `PXAT unix-time-milliseconds` -- Set the specified Unix time in milliseconds at which the field will expire. +* `KEEPTTL` -- Retain the TTL associated with the field. + +The `EX`, `PX`, `EXAT`, `PXAT`, and `KEEPTTL` options are mutually exclusive. + +## Example + +``` +redis> HSETEX mykey EXAT 1740470400 FIELDS 2 field1 "Hello" field2 "World" +(integer) 1 +redis> HTTL mykey FIELDS 2 field1 field2 +1) (integer) 55627 +2) (integer) 55627 +redis> HSETEX mykey FNX EX 60 FIELDS 2 field1 "Hello" field2 "World" +(integer) 0 +redis> HSETEX mykey FXX EX 60 KEEPTTL FIELDS 2 field1 "hello" field2 "world" +(error) ERR Only one of EX, PX, EXAT, PXAT or KEEPTTL arguments can be specified +redis> HSETEX mykey FXX KEEPTTL FIELDS 2 field1 "hello" field2 "world" +(integer) 1 +redis> HTTL mykey FIELDS 2 field1 field2 +1) (integer) 55481 +2) (integer) 55481 +``` + diff --git a/content/commands/hsetex/syntax.svg b/content/commands/hsetex/syntax.svg new file mode 100644 index 000000000..5687b8db0 --- /dev/null +++ b/content/commands/hsetex/syntax.svg @@ -0,0 +1,20 @@ + + + + + + +HEXPIRE +keykey +secondsinteger + + + +XX +NX +GT +LT +numfieldsinteger + +fieldstring + \ No newline at end of file diff --git a/data/resp2_replies.json b/data/resp2_replies.json index 07a7cc52e..a20316525 100644 --- a/data/resp2_replies.json +++ b/data/resp2_replies.json @@ -575,6 +575,14 @@ "HGETALL": [ "[Array reply](../../develop/reference/protocol-spec#arrays): a list of fields and their values stored in the hash, or an empty list when key does not exist." ], + "HGETDEL": [ + "[Array reply](../../develop/reference/protocol-spec#arrays): a list of deleted fields and their values or `nil` for fields that do not exist." + ], + "HGETEX": [ + "* [Array reply](../../develop/reference/protocol-spec#arrays). For each field:", + " - [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if no such field exists in the provided hash key, or the provided key does not exist, or if the field exists but has no associated expiration set.", + " - [Integer reply](../../develop/reference/protocol-spec#integers): the expiration in seconds." + ], "HINCRBY": [ "[Integer reply](../../develop/reference/protocol-spec#integers): the value of the field after the increment operation." ], @@ -648,6 +656,11 @@ "HSET": [ "[Integer reply](../../develop/reference/protocol-spec#integers): the number of fields that were added." ], + "HSETEX": [ + "One of the following:", + "* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if no fields were set.", + "* [Integer reply](../../develop/reference/protocol-spec#integers): `1` if all the fields wereset." + ], "HSETNX": [ "One of the following:", "* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the field already exists in the hash and no operation was performed.", diff --git a/data/resp3_replies.json b/data/resp3_replies.json index 0a3692e4f..b39f3e79c 100644 --- a/data/resp3_replies.json +++ b/data/resp3_replies.json @@ -575,6 +575,14 @@ "HGETALL": [ "[Map reply](../../develop/reference/protocol-spec#maps): a map of fields and their values stored in the hash, or an empty list when key does not exist." ], + "HGETDEL": [ + "[Array reply](../../develop/reference/protocol-spec#arrays): a list of deleted fields and their values or `nil` for fields that do not exist." + ], + "HGETEX": [ + "* [Array reply](../../develop/reference/protocol-spec#arrays). For each field:", + " - [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if no such field exists in the provided hash key, or the provided key does not exist, or if the field exists but has no associated expiration set.", + " - [Integer reply](../../develop/reference/protocol-spec#integers): the expiration in seconds." + ], "HINCRBY": [ "[Integer reply](../../develop/reference/protocol-spec#integers): the value of the field after the increment operation." ], @@ -648,6 +656,11 @@ "HSET": [ "[Integer reply](../../develop/reference/protocol-spec#integers): the number of fields that were added." ], + "HSETEX": [ + "One of the following:", + "* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if no fields were set.", + "* [Integer reply](../../develop/reference/protocol-spec#integers): `1` if all the fields wereset." + ], "HSETNX": [ "One of the following:", "* [Integer reply](../../develop/reference/protocol-spec#integers): `0` if the field already exists in the hash and no operation was performed.", From df7258b1c99a6334c48592630c188e095c793a45 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Tue, 25 Feb 2025 07:11:45 -0800 Subject: [PATCH 2/2] DEV: correct previous merge --- content/commands/hgetex/index.md | 8 ++++---- content/commands/hsetex/index.md | 9 ++++----- data/resp2_replies.json | 2 +- data/resp3_replies.json | 2 +- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/content/commands/hgetex/index.md b/content/commands/hgetex/index.md index c4d75a03e..92ab1248a 100644 --- a/content/commands/hgetex/index.md +++ b/content/commands/hgetex/index.md @@ -88,7 +88,7 @@ syntax_str: "[EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds | PXAT\_u \ | PERSIST] FIELDS\_numfields field [field ...]" title: HGETEX --- -Get the value of one or more fields of a given hash key and optionally set their expirations (time-to-live or TTL). +Get the value of one or more fields of a given hash key and optionally set their expiration time or time-to-live (TTL). ## Options @@ -96,9 +96,9 @@ The `HGETEX` command supports a set of options: * `EX seconds` -- Set the specified expiration time, in seconds. * `PX milliseconds` -- Set the specified expiration time, in milliseconds. -* `EXAT unix-time-seconds` -- Set the specified Unix time at which the field will expire, in seconds. -* `PXAT unix-time-milliseconds` -- Set the specified Unix time at which the field will expire, in milliseconds. -* `PERSIST` -- Remove the TTL associated with the field. +* `EXAT unix-time-seconds` -- Set the specified Unix time at which the fields will expire, in seconds. +* `PXAT unix-time-milliseconds` -- Set the specified Unix time at which the fields will expire, in milliseconds. +* `PERSIST` -- Remove the TTL associated with the fields. The `EX`, `PX`, `EXAT`, `PXAT`, and `PERSIST` options are mutually exclusive. diff --git a/content/commands/hsetex/index.md b/content/commands/hsetex/index.md index 5b3b1d739..19b825a6d 100644 --- a/content/commands/hsetex/index.md +++ b/content/commands/hsetex/index.md @@ -106,7 +106,7 @@ syntax_str: "[FNX | FXX] [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-secon \ value ...]" title: HSETEX --- -Set the value of one or more fields of a given hash key, and optionally set their expirations (time-to-live or TTL). +Set the value of one or more fields of a given hash key, and optionally set their expiration time or time-to-live (TTL). ## Options @@ -116,9 +116,9 @@ The `HGETEX` command supports a set of options: * `FXX` -- Only set the fields if all of them already exist. * `EX seconds` -- Set the specified expiration time in seconds. * `PX milliseconds` -- Set the specified expiration time in milliseconds. -* `EXAT unix-time-seconds` -- Set the specified Unix time in seconds at which the field will expire. -* `PXAT unix-time-milliseconds` -- Set the specified Unix time in milliseconds at which the field will expire. -* `KEEPTTL` -- Retain the TTL associated with the field. +* `EXAT unix-time-seconds` -- Set the specified Unix time in seconds at which the fields will expire. +* `PXAT unix-time-milliseconds` -- Set the specified Unix time in milliseconds at which the fields will expire. +* `KEEPTTL` -- Retain the TTL associated with the fields. The `EX`, `PX`, `EXAT`, `PXAT`, and `KEEPTTL` options are mutually exclusive. @@ -140,4 +140,3 @@ redis> HTTL mykey FIELDS 2 field1 field2 1) (integer) 55481 2) (integer) 55481 ``` - diff --git a/data/resp2_replies.json b/data/resp2_replies.json index a20316525..1b639e5cf 100644 --- a/data/resp2_replies.json +++ b/data/resp2_replies.json @@ -573,7 +573,7 @@ "* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): If the field is not present in the hash or key does not exist." ], "HGETALL": [ - "[Array reply](../../develop/reference/protocol-spec#arrays): a list of fields and their values stored in the hash, or an empty list when key does not exist." + "[Array reply](../../develop/reference/protocol-spec#arrays): a list of fields and their values, or an empty list when key does not exist." ], "HGETDEL": [ "[Array reply](../../develop/reference/protocol-spec#arrays): a list of deleted fields and their values or `nil` for fields that do not exist." diff --git a/data/resp3_replies.json b/data/resp3_replies.json index b39f3e79c..e465fa393 100644 --- a/data/resp3_replies.json +++ b/data/resp3_replies.json @@ -573,7 +573,7 @@ "* [Null reply](../../develop/reference/protocol-spec#nulls): If the field is not present in the hash or key does not exist." ], "HGETALL": [ - "[Map reply](../../develop/reference/protocol-spec#maps): a map of fields and their values stored in the hash, or an empty list when key does not exist." + "[Map reply](../../develop/reference/protocol-spec#maps): a map of fields and their values, or an empty list when key does not exist." ], "HGETDEL": [ "[Array reply](../../develop/reference/protocol-spec#arrays): a list of deleted fields and their values or `nil` for fields that do not exist."