Add documentation for Hash Fields Expiration

commands/hexpire.md

@@ -0,0 +1,26 @@
+The `HEXPIRE` command allows manipulating the expiration time for existing hash fields.
+When set, the expiration time of a hash field will determine when the field will be automatically deleted.
+Note, that providing a millisecond time of '0' will cause immediate expiration and deletion of the field(s).
+
+## Options
+
+The `HEXPIRE` command supports a set of options that modify its behavior:
+
+* NX — For each specified field, set expiration only when the field has no expiration.
+* XX — For each specified field, set expiration only when the field has an existing expiration.
+* GT — For each specified field, set expiration only when the new expiration is greater than current one.
+* LT — For each specified field, set expiration only when the new expiration is less than current one.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HEXPIRE myhash 10 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 8
+3) (integer) 8
+```

commands/hexpireat.md

@@ -0,0 +1,30 @@
+`HEXPIREAT` has the same effect and semantic as [`HEXPIRE`](hexpire.md), but instead of
+specifying the number of seconds representing the TTL (time to live), it takes
+an absolute Unix timestamp (seconds since January 1, 1970). A
+timestamp in the past will delete the key immediately.
+
+For the specific semantics of the command refer to the documentation of
+[`HEXPIRE`](hexpire.md).
+
+## Options
+
+The `HEXPIREAT` command supports a set of options that modify its behavior:
+
+* NX — For each specified field, set expiration only when the field has no expiration.
+* XX — For each specified field, set expiration only when the field has an existing expiration.
+* GT — For each specified field, set expiration only when the new expiration is greater than current one.
+* LT — For each specified field, set expiration only when the new expiration is less than current one.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HEXPIREAT myhash 1754846600 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HEXPIRETIME myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 1754846600
+3) (integer) 1754846600
+```

commands/hexpiretime.md

@@ -0,0 +1,18 @@
+The `HEXPIRETIME` command returns the absolute Unix timestamp (since January 1, 1970) in seconds at which the given hash field(s) will expire or -1 if the hash field doesn't have expiration time.
+
+See also the [`HPEXPIRETIME`](hpexpiretime.md) command that returns the same information with milliseconds resolution.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HEXPIREAT myhash 1754846600 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HEXPIRETIME myhash FIELDS 4 f1 f2 f3 non-exist
+1) (integer) -1
+2) (integer) 1754846600
+3) (integer) 1754846600
+4) (integer) -2
+```

commands/hgetex.md

@@ -0,0 +1,41 @@
+The `HGETEX` command returns the value of one or more fields of a given hash key, and optionally manipulates their expiration time.
+The command will return an array in the size of the number of requested fields.
+Without providing any optional flags, this command behaves exactly like a normal [`HMGET`](hmget.md) command.
+
+## Options
+
+The `HGETEX` command supports a set of options that modify its behavior:
+
+* 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 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 expiration time associated with the fields.
+
+Note for the following:
+
+1. The EX, PX, EXAT, PXAT, and PERSIST options are mutually exclusive.
+2. Providing '0' expiration TTL via `EX` or `PX` optional arguments will cause the specified fields to expire immediately and be removed from the hash.
+3. Providing past expiration time via `EXAT` or `PXAT` optional arguments will cause the specified fields to expire immediately and be removed from the hash.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HGETEX myhash EX 10 FIELDS 2 f2 f3
+1) "v2"
+2) "v3"
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 8
+3) (integer) 8
+127.0.0.1:6379> HGETEX myhash EX 0 FIELDS 3 f1 f2 f3 
+1) "v1"
+2) "v2"
+3) "v3"
+127.0.0.1:6379> HGETEX myhash FIELDS 3 f1 f2 f3 
+1) (nil)
+2) (nil)
+3) (nil)
+```

commands/hpersist.md

@@ -0,0 +1,24 @@
+The `HPERSIST` remove the existing expiration on a hash key's field(s), turning the field(s) from volatile (a field with expiration set) 
+to persistent (a field that will never expire as no TTL (time to live) is associated).
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HEXPIRE myhash 1000 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 998
+3) (integer) 998
+127.0.0.1:6379> HPERSIST myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 1
+3) (integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) -1
+3) (integer) -1
+```

commands/hpexpire.md

@@ -0,0 +1,26 @@
+This command works exactly like [`HEXPIRE`](hexpire.md) but the time to live of the key is
+specified in milliseconds instead of seconds.
+Note, that providing a millisecond time of '0' will cause immediate expiration and reclamation of the field(s).
+
+## Options
+
+The `HPXPIRE` command supports a set of options that modify its behavior:
+
+* NX — For each specified field, set expiration only when the field has no expiration.
+* XX — For each specified field, set expiration only when the field has an existing expiration.
+* GT — For each specified field, set expiration only when the new expiration is greater than current one.
+* LT — For each specified field, set expiration only when the new expiration is less than current one.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HPEXPIRE myhash 10000 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HPTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 9597
+3) (integer) 9597
+```

commands/hpexpireat.md

@@ -0,0 +1,30 @@
+`HEXPIREAT` has the same effect and semantic as [`HPEXPIRE`](hpexpire.md), but instead of
+specifying the number of milliseconds representing the TTL (time to live), it takes
+an absolute Unix timestamp (milliseconds since January 1, 1970). A
+timestamp in the past will delete the key immediately.
+
+For the specific semantics of the command refer to the documentation of
+[`HPEXPIRE`](hpexpire.md).
+
+## Options
+
+The `HPEXPIREAT` command supports a set of options that modify its behavior:
+
+* NX — For each specified field, set expiration only when the field has no expiration.
+* XX — For each specified field, set expiration only when the field has an existing expiration.
+* GT — For each specified field, set expiration only when the new expiration is greater than current one.
+* LT — For each specified field, set expiration only when the new expiration is less than current one.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HPEXPIREAT myhash 1754847944000 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HPEXPIRETIME myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 1754847944000
+3) (integer) 1754847944000
+```

commands/hpexpiretime.md

@@ -0,0 +1,18 @@
+The `HPEXPIRETIME` command returns the absolute Unix timestamp (since January 1, 1970) in milliseconds at which the given hash field(s) will expire.
+
+See also the [`HEXPIRETIME`](hexpiretime.md) command which returns the same information with seconds resolution.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HPEXPIREAT myhash 1754847944000 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HPEXPIRETIME myhash FIELDS 4 f1 f2 f3 non-exist
+1) (integer) -1
+2) (integer) 1754847944000
+3) (integer) 1754847944000
+4) (integer) -2
+```

commands/hpttl.md

@@ -0,0 +1,19 @@
+Like [`HTTL`](httl.md) this command returns the remaining time to live of hash field(s) that has an associated expiration time,
+with the sole difference that `HTTL` returns the amount of remaining
+time in seconds while `HPTTL` returns it in milliseconds.
+
+See also the [`HTTL`](httl.md) command that returns the same information with seconds resolution.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HPEXPIRE myhash 10000 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HPTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 9597
+3) (integer) 9597
+```

commands/hsetex.md

@@ -0,0 +1,74 @@
+The `HSETEX` command allows setting the value of one or more fields of a given hash key, and optionally manipulating their expiration time.
+The command will return 1 in case all provided fields have been set or 0 in case `FNX` or `FXX` were provided and non of the specified fields were set.
+Without providing any optional flags, this command behaves exactly like a normal [`HSET`](hset.md) command.
+
+## Options
+
+The `HSETEX` command supports a set of options that modify its behavior:
+
+* 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 for when 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.
+
+Note for the following:
+
+1. The EX, PX, EXAT, PXAT, and KEEPTTL options are mutually exclusive.
+2. Setting a value on a volatile hash field (A field which has an assigned expiration time) will remove the expiration for that field.
+3. Providing '0' expiration TTL via `EX` or `PX` optional arguments will result in the specified fields immediately expiring and being removed from the hash.
+4. Providing past expiration time via `EXAT` or `PXAT` optional arguments will result in the specified fields immediately expiring and being removed from the hash.
+
+## Examples
+
+Add 3 new items without expiration time to a 'myhash'
+```
+127.0.0.1:6379> HSETEX myhash FIELDS 3 f1 v1 f2 v2 f3 v3
+(integer) 1
+```
+
+Unsuccessful attempt setting expiration time on EXISTING fields
+```
+127.0.0.1:6379> HSETEX myhash FNX EX 10 FIELDS 2 f2 v2 f3 v3
+(integer) 0
+```
+
+Successful attempt setting expiration time on EXISTING fields
+```
+127.0.0.1:6379> HSETEX myhash FXX EX 10 FIELDS 2 f2 v2 f3 v3
+(integer) 1
+```
+
+Verify hash fields expiration time:
+```
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) 8
+3) (integer) 8
+```
+
+Override all hash items will also persist the fields
+```
+127.0.0.1:6379> HSETEX myhash FIELDS 3 f1 v1 f2 v2 f3 v3
+(integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -1
+2) (integer) -1
+3) (integer) -1
+```
+
+Setting expiration time in the past will remove all the elements in the hash:
+```
+127.0.0.1:6379> HSETEX EX 0 myhash FIELDS 3 f1 v1 f2 v2 f3 v3
+(integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 3 f1 f2 f3
+1) (integer) -2
+2) (integer) -2
+3) (integer) -2
+127.0.0.1:6379> HLEN myhash
+(integer) 0
+127.0.0.1:6379> EXISTS myhash
+(integer) 0
+```

commands/httl.md

@@ -0,0 +1,20 @@
+The `HTTL` command returns the remaining time to live of hash field(s) with associated expiration time(s).
+This introspection capability allows a Valkey client to check how many seconds a
+given hash field will continue to be part of the hash object.
+
+See also the [`HPTTL`](hpttl.md) command that returns the same information with milliseconds resolution.
+
+## Examples
+
+```
+127.0.0.1:6379> HSET myhash f1 v1 f2 v2 f3 v3
+(integer) 3
+27.0.0.1:6379> HEXPIRE myhash 10 FIELDS 2 f2 f3
+1) (integer) 1
+2) (integer) 1
+127.0.0.1:6379> HTTL myhash FIELDS 4 f1 f2 f3 non-exist
+1) (integer) -1
+2) (integer) 8
+3) (integer) 8
+4) (integer) -2
+```