DEV: (feat/cmds) docs for blessed keys in 8.12

content/commands/bless-clear.md

@@ -0,0 +1,120 @@
+---
+acl_categories:
+- '@keyspace'
+- '@write'
+- '@fast'
+arguments:
+- display_text: key
+  key_spec_index: 0
+  name: key
+  type: key
+- display_text: no-evict
+  name: no-evict
+  token: NO-EVICT
+  type: pure-token
+arity: 4
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- write
+- fast
+complexity: O(1)
+description: Removes protection flags from a key.
+group: generic
+hidden: false
+key_specs:
+- RW: true
+  begin_search:
+    spec:
+      index: 2
+    type: index
+  find_keys:
+    spec:
+      keystep: 1
+      lastkey: 0
+      limit: 0
+    type: range
+linkTitle: BLESS CLEAR
+railroad_diagram: /images/railroad/bless-clear.svg
+since: 8.12.0
+summary: Removes protection flags from a key.
+syntax_fmt: BLESS CLEAR key NO-EVICT
+title: BLESS CLEAR
+---
+`BLESS CLEAR` removes a protection flag from a key, making it eligible again for eviction. The key must already exist.
+
+## Required arguments
+
+<details open><summary><code>key</code></summary>
+
+The name of the key to unprotect. The key must already exist, or the command returns an error.
+
+</details>
+
+<details open><summary><code>NO-EVICT</code></summary>
+
+The protection flag to remove. `NO-EVICT` is currently the only supported flag.
+
+</details>
+
+## Details
+
+### Behavior
+
+- `BLESS CLEAR` is idempotent: it returns `1` the first time the flag is removed from a key, and `0` on later calls if the key didn't carry that flag.
+- Unlike [`BLESS SET`]({{< relref "/commands/bless-set" >}}), `BLESS CLEAR` isn't blocked when the server is out of memory, so protection can always be removed to free up eviction candidates.
+- `BLESS CLEAR` generates an `unbless` [keyspace notification]({{< relref "/develop/pubsub/keyspace-notifications" >}}) event.
+- Clearing the flag persists across restarts and replicates like any other write.
+
+## Examples
+
+{{% redis-cli %}}
+redis> BLESS SET session:42 NO-EVICT
+(integer) 1
+redis> BLESS CLEAR session:42 NO-EVICT
+(integer) 1
+redis> BLESS CLEAR session:42 NO-EVICT
+(integer) 0
+redis> BLESS CLEAR missing-key NO-EVICT
+(error) ERR no such key
+{{% /redis-cli %}}
+
+## Redis Software and Redis Cloud compatibility
+
+| Redis<br />Software | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
+|:----------------------|:-----------------|:------|
+| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> |  |
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+One of the following:
+* [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): `1` if the flag was removed, `0` if the key didn't have it.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key doesn't exist.
+
+-tab-sep-
+
+One of the following:
+* [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): `1` if the flag was removed, `0` if the key didn't have it.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key doesn't exist.
+
+{{< /multitabs >}}
+
+## See also
+
+[`BLESS SET`]({{< relref "/commands/bless-set" >}}) | [`BLESS GET`]({{< relref "/commands/bless-get" >}}) | [`BLESS SCAN`]({{< relref "/commands/bless-scan" >}})
+
+## Related topics
+
+- [Key eviction]({{< relref "/develop/reference/eviction" >}})

content/commands/bless-get.md

@@ -0,0 +1,105 @@
+---
+acl_categories:
+- '@keyspace'
+- '@fast'
+arguments:
+- display_text: key
+  key_spec_index: 0
+  name: key
+  type: key
+arity: 3
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- fast
+complexity: O(1).
+description: Returns the active protection flags of a key.
+group: generic
+hidden: false
+key_specs:
+- RO: true
+  begin_search:
+    spec:
+      index: 2
+    type: index
+  find_keys:
+    spec:
+      keystep: 1
+      lastkey: 0
+      limit: 0
+    type: range
+linkTitle: BLESS GET
+railroad_diagram: /images/railroad/bless-get.svg
+since: 8.12.0
+summary: Returns the active protection flags of a key.
+syntax_fmt: BLESS GET key
+title: BLESS GET
+---
+`BLESS GET` returns the eviction-protection flags currently set on a key. The key must already exist.
+
+## Required arguments
+
+<details open><summary><code>key</code></summary>
+
+The name of the key to inspect. The key must already exist, or the command returns an error.
+
+</details>
+
+## Details
+
+`BLESS GET` returns an empty array if the key exists but has no protection flags. `NO-EVICT` is currently the only flag `BLESS` defines.
+
+## Examples
+
+{{% redis-cli %}}
+redis> SET session:42 "some value"
+OK
+redis> BLESS GET session:42
+(empty array)
+redis> BLESS SET session:42 NO-EVICT
+(integer) 1
+redis> BLESS GET session:42
+1) "NO-EVICT"
+redis> BLESS GET missing-key
+(error) ERR no such key
+{{% /redis-cli %}}
+
+## Redis Software and Redis Cloud compatibility
+
+| Redis<br />Software | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
+|:----------------------|:-----------------|:------|
+| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> |  |
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+One of the following:
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of the key's active protection flags, empty if none are set.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key doesn't exist.
+
+-tab-sep-
+
+One of the following:
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of the key's active protection flags, empty if none are set.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) if the key doesn't exist.
+
+{{< /multitabs >}}
+
+## See also
+
+[`BLESS SET`]({{< relref "/commands/bless-set" >}}) | [`BLESS CLEAR`]({{< relref "/commands/bless-clear" >}}) | [`BLESS SCAN`]({{< relref "/commands/bless-scan" >}})
+
+## Related topics
+
+- [Key eviction]({{< relref "/develop/reference/eviction" >}})

content/commands/bless-scan.md

@@ -0,0 +1,122 @@
+---
+acl_categories:
+- '@keyspace'
+- '@slow'
+arguments:
+- display_text: cursor
+  name: cursor
+  type: integer
+- display_text: no-evict
+  name: no-evict
+  token: NO-EVICT
+  type: pure-token
+- display_text: count
+  name: count
+  optional: true
+  token: COUNT
+  type: integer
+arity: -4
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+complexity: O(1) for every call. O(N) for a complete iteration, where N is the number
+  of blessed keys.
+description: Incrementally iterates the blessed keys of the current database that
+  carry the given flag.
+group: generic
+hidden: false
+hints:
+- nondeterministic_output
+- request_policy:special
+- response_policy:special
+linkTitle: BLESS SCAN
+railroad_diagram: /images/railroad/bless-scan.svg
+since: 8.12.0
+summary: Incrementally iterates the blessed keys of the current database that carry
+  the given flag.
+syntax_fmt: "BLESS SCAN cursor NO-EVICT [COUNT\_count]"
+title: BLESS SCAN
+---
+`BLESS SCAN` incrementally iterates the blessed keys of the current database that carry the given protection flag, using the same cursor-based protocol as [`SCAN`]({{< relref "/commands/scan" >}}).
+
+## Required arguments
+
+<details open><summary><code>cursor</code></summary>
+
+The cursor value. Start an iteration with `0`, then use the cursor returned by each call as the argument to the next call.
+
+</details>
+
+<details open><summary><code>NO-EVICT</code></summary>
+
+The protection flag to filter by. `NO-EVICT` is currently the only supported flag, and this argument is required.
+
+</details>
+
+## Optional arguments
+
+<details open><summary><code>COUNT count</code></summary>
+
+A hint for the number of keys to visit per iteration. The default is 1024.
+
+</details>
+
+## Details
+
+`BLESS SCAN` follows the same cursor semantics and iteration guarantees as [`SCAN`]({{< relref "/commands/scan" >}}): a full iteration, from cursor `0` until the returned cursor is `0` again, is guaranteed to return every key that carried the given flag for the entire duration of the iteration. `COUNT` is only a hint, and a key may be returned more than once during a full iteration.
+
+## Examples
+
+{{% redis-cli %}}
+redis> SET session:42 "some value"
+OK
+redis> SET cache:100 "some value"
+OK
+redis> BLESS SET session:42 NO-EVICT
+(integer) 1
+redis> BLESS SET cache:100 NO-EVICT
+(integer) 1
+redis> BLESS SCAN 0 NO-EVICT
+1) "0"
+2) 1) "cache:100"
+   2) "session:42"
+{{% /redis-cli %}}
+
+## Redis Software and Redis Cloud compatibility
+
+| Redis<br />Software | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
+|:----------------------|:-----------------|:------|
+| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> |  |
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): specifically, an array with two elements.
+* The first element is a [Bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) that represents an unsigned 64-bit number, the cursor.
+* The second element is an [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with the names of the scanned keys.
+
+-tab-sep-
+
+[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): specifically, an array with two elements.
+* The first element is a [Bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) that represents an unsigned 64-bit number, the cursor.
+* The second element is an [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with the names of the scanned keys.
+
+{{< /multitabs >}}
+
+## See also
+
+[`BLESS SET`]({{< relref "/commands/bless-set" >}}) | [`BLESS CLEAR`]({{< relref "/commands/bless-clear" >}}) | [`BLESS GET`]({{< relref "/commands/bless-get" >}})
+
+## Related topics
+
+- [Key eviction]({{< relref "/develop/reference/eviction" >}})