From 8ec5cbc54891b4b85608abb333d5ce0052c97719 Mon Sep 17 00:00:00 2001
From: Kyle Kim <kimkyle@amazon.com>
Date: Tue, 25 Jun 2024 22:02:25 +0000
Subject: [PATCH] Add CLUSTER SLOT-STATS document. - Valkey PR link;
 https://github.com/valkey-io/valkey/pull/351.

Signed-off-by: Kyle Kim <kimkyle@amazon.com>
---
 commands.json                                 |  81 ++++++++++++++++++
 commands/cluster-slot-stats.md                |  42 +++++++++
 .../__pycache__/command_syntax.cpython-38.pyc | Bin 0 -> 7089 bytes
 3 files changed, 123 insertions(+)
 create mode 100644 commands/cluster-slot-stats.md
 create mode 100644 utils/__pycache__/command_syntax.cpython-38.pyc

diff --git a/commands.json b/commands.json
index c95dc374..881c4e71 100644
--- a/commands.json
+++ b/commands.json
@@ -3095,6 +3095,87 @@
             "nondeterministic_output"
         ]
     },
+    "CLUSTER SLOT-STATS": {
+        "summary": "Returns an array of slot usage statistics for slots assigned to the current shard.",
+        "since": "8.0.0",
+        "group": "cluster",
+        "complexity": "O(N) where N is the total number of slots based on arguments. O(N log N) with ORDERBY subcommand.",
+        "history": [
+            [
+                "8.0.0",
+                "Initial release with key-count metric support."
+            ]
+        ],
+        "acl_categories": [
+            "@slow"
+        ],
+        "arity": -4,
+        "command_flags": [
+            "stale",
+            "loading"
+        ],
+        "hints": [
+            "nondeterministic_output",
+            "request_policy:all_shards"
+        ],
+        "arguments": [
+            {
+                "name": "filter",
+                "type": "oneof",
+                "arguments": [
+                    {
+                        "token": "SLOTSRANGE",
+                        "name": "slotsrange",
+                        "type": "block",
+                        "arguments": [
+                            {
+                                "name": "start-slot",
+                                "type": "integer"
+                            },
+                            {
+                                "name": "end-slot",
+                                "type": "integer"
+                            }
+                        ]
+                    },
+                    {
+                        "token": "ORDERBY",
+                        "name": "orderby",
+                        "type": "block",
+                        "arguments": [
+                            {
+                                "name": "metric",
+                                "type": "string"
+                            },
+                            {
+                                "token": "LIMIT",
+                                "name": "limit",
+                                "type": "integer",
+                                "optional": true
+                            },
+                            {
+                                "name": "order",
+                                "type": "oneof",
+                                "optional": true,
+                                "arguments": [
+                                    {
+                                        "name": "asc",
+                                        "type": "pure-token",
+                                        "token": "ASC"
+                                    },
+                                    {
+                                        "name": "desc",
+                                        "type": "pure-token",
+                                        "token": "DESC"
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    },
     "COMMAND": {
         "summary": "Returns detailed information about all commands.",
         "since": "2.8.13",
diff --git a/commands/cluster-slot-stats.md b/commands/cluster-slot-stats.md
new file mode 100644
index 00000000..4b667814
--- /dev/null
+++ b/commands/cluster-slot-stats.md
@@ -0,0 +1,42 @@
+`CLUSTER SLOT-STATS` returns an array of slot usage statistics for slots assigned to the current shard.
+The command is suitable for Valkey Cluster users aiming to assess general slot usage trends, identify hot / cold slots, migrate slots for a balanced cluster workload, and / or re-write application logic to better utilize slots.
+
+As of now, the following metrics are supported:
+* key-count
+
+## Supported arguments
+There exist two mutually exclusive arguments, namely;
+
+### SLOTSRANGE
+Returns slot statistics based on the slots range provided.
+The `SLOTSRANGE` argument allows for request pagination.
+
+```
+> CLUSTER SLOT-STATS SLOTSRANGE 0 2
+> 1) (integer) 0
+> 2) 1) "key-count"
+>    2) (integer) 0
+> 3) (integer) 1
+> 4) 1) "key-count"
+>    2) (integer) 0
+> 5) (integer) 2
+> 6) 1) "key-count"
+>    2) (integer) 0
+```
+
+### ORDERBY
+Orders slot statistics based on the provided metric. Right now, only `key-count` is available.
+The `ORDERBY` argument allows for the user to identify hot / cold slots across the cluster.
+
+```
+> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 3 DESC
+> 1) (integer) 12426
+> 2) 1) "key-count"
+>    2) (integer) 45
+> 3) (integer) 13902
+> 4) 1) "key-count"
+>    2) (integer) 20
+> 5) (integer) 2704
+> 6) 1) "key-count"
+>    2) (integer) 11
+```
diff --git a/utils/__pycache__/command_syntax.cpython-38.pyc b/utils/__pycache__/command_syntax.cpython-38.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..398dc08e09088dc9ea949663a22589fbccce172a
GIT binary patch
literal 7089
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

literal 0
HcmV?d00001