Command 键规格

什么是命令键规范以及如何在客户端中使用它们

Redis 中的许多命令都接受键名称作为输入参数。回复中的第 9 个元素COMMAND（以及COMMAND INFO）是一个数组，其中包含命令的关键规范。

键规范描述用于从给定命令的参数中提取一个或多个键的名称的规则。与 Redis 7.0 之前采用的第一个密钥、最后一个密钥和步骤方案相比，密钥规范提供了一种强大而灵活的机制。在引入这些规范之前，Redis 客户端没有简单的编程方法来提取所有命令的键名称。

集群感知型 Redis 客户端必须对键的提取逻辑进行硬编码，以使用以下命令：EVAL和ZUNIONSTORE依赖于 numkeys 参数或SORT及其许多子句。或者，COMMAND GETKEYS可以用于实现类似的提取效果，但延迟更高。

Redis 客户端没有义务支持关键规范。它可以继续使用旧版 first key、last key 和 step 方案以及保持不变的 movablekeys 标志。

但是，实现密钥规范支持的 Redis 客户端可以整合其大部分密钥的提取逻辑。即使客户端遇到不熟悉的密钥规范类型，它也始终可以恢复到COMMAND GETKEYS命令。

也就是说，大多数集群感知 Client 端只需要一个键名来执行正确的命令路由，因此尽管命令具有一个不熟悉的规范，但其另一个规范可能仍可供 Client 端使用。

关键规范是具有以下键的 map：

begin_search：：键提取的起始索引。
find_keys：标识相对于 BS 的 key 的规则。
备注：关于此关键规范的注意事项（如果有）。
flags：数据访问的类型。

begin_search

规范的 begin_search 值通知客户端提取的开始。值为 map。有三种类型的begin_search:

index：键名称参数从 constant 索引开始。
关键字：键名称在特定关键字（token）之后开始。
unknown：未知类型的规范 - 有关更多详细信息，请参阅 Incomplete Flag 部分。

指数

索引类型begin_search指示输入键显示在常量索引处。它是 spec key 下的一个 map，只有一个 key：

index：从 0 开始的索引，客户端应从该索引开始提取键名称。

关键词

关键字类型begin_search表示 Literals Token（文本标记）位于 Key Name 参数之前。它是规范下的一张地图，有两个键：

keyword：标记键名称参数开头的关键字（token）。
startFrom：客户端应从中开始搜索的 arguments 数组的索引。这可以是负值，这意味着搜索应从参数数组的末尾开始，顺序相反。例如，-2 的含义是从倒数第二个参数中搜索 reverse。

关键字搜索类型的更多示例包括：

SET具有begin_searchindex 类型的 specification 值为 1。
XREAD具有begin_searchkeyword 类型的规范，其中值分别为 “STREAMS” 和 1 作为 keyword 和 startfrom。
MIGRATE具有 keyword 类型的 start_search 规范，其值为 “KEYS” 和 -2。

find_keys

这find_keys值告诉客户端如何继续搜索键名称。find_keys有三种可能的类型：

range：键在特定索引或相对于最后一个参数停止。
keynum：一个附加参数指定 input key 的数量。
unknown：未知类型的规范 - 有关更多详细信息，请参阅 Incomplete Flag 部分。

范围

的范围类型find_keys是 spec 键下的 map，具有三个键：

lastKey：索引，相对于begin_search，最后一个键参数。这可以是负值，在这种情况下，它不是相对的。例如，-1 表示继续提取键直到最后一个参数，-2 表示直到最后一个参数之前的 1 个，依此类推。
keystep：找到一个 key 后，为了找到下一个 key，应该跳过的 arguments 个数。
limit：如果 lastKey is 的值为 -1，我们使用 limit 来停止按一个因子进行搜索。0 和 1 表示没有限制。2 表示剩余参数的一半，3 表示第三个参数，依此类推。

密钥

的 keynum 类型find_keys是 spec 键下的 map，具有三个键：

keynumidx：索引，相对于begin_search，其中包含键数的参数。
firstKey：索引，相对于begin_search，则表示第一个键的这通常是 keynumidx 之后的下一个参数，在这种情况下，它的值大于 1。
键步：T找到 key 后，为了找到下一个 key 而应该跳过的参数的数量。

例子：

这SETcommand 的范围为 0、1 和 0。
这MSETcommand 的范围为 -1、2 和 0。
这XREADcommand 的范围为 -1、1 和 2。
这ZUNIONcommand 具有值为 1 的 start_search 类型索引，并且find_keys类型 keynum ，值为 0、 1 和 1。

注意：这不是一个完美的解决方案，因为模块编写者可以想出任何东西。但是，此机制应允许提取绝大多数命令的键名称参数。

笔记

有关非明显关键规格注意事项的说明（如果适用）。

标志

密钥规范可以包含其他标志，这些标志提供有关密钥的更多详细信息。这些标志分为三组，如下所述。

访问类型标志

以下标志声明命令用于键值或其元数据的访问类型。键的元数据包括 LRU/LFU 计数器、类型和基数。这些标志与发送回客户端的回复无关。

每个密钥规范都恰好具有以下标志之一：

RW：读写标志。该命令修改存储在键值或其元数据中的数据。此标志标记不是明确删除、覆盖或只读的每个作。
RO：只读标志。该命令仅读取键的值（尽管它不一定返回它）。
OW：overwrite 标志。该命令将覆盖 key 值中存储的数据。
RM：remove 标志。该命令将删除密钥。

逻辑作标志

以下标志声明对存储为键值及其 TTL（如果有）的数据执行的作类型，而不是元数据。这些标志描述命令对数据执行的逻辑作，由输入参数驱动。这些标志与修改或返回元数据（例如键的类型、基数或存在性）无关。

每个密钥规范都可以包含以下标志：

access：访问标志。此标志指示命令返回、复制或以某种方式使用存储在密钥中的用户数据。

此外，说明书可能恰好包括以下其中一项：

update：更新标志。该命令将更新存储在 key 值中的数据。新值可能取决于旧值。此标志标记不是明确插入或删除的每个作。
insert：插入标志。该命令仅向值添加数据;不会修改或删除现有数据。
delete：删除标志。该命令从存储在 key 的值中显式删除数据。

其他标志

关键规范可能具有以下标志：

not_key：此标志指示指定的参数不是键。在计算应为 Redis 集群分配命令的插槽时，此参数被视为与键相同。对于所有其他目的，不应将此参数视为键。
incomplete：此标志将在下面说明。
variable_flags：此标志解释如下。

不完全的

一些命令在指定键时采用奇特的方法，这使得提取变得困难。例如，考虑一下调用MIGRATE其中包括文本字符串 “KEYS” 作为其 AUTH 子句的参数。我们的关键规范会错过标记，并且提取将从错误的索引开始。

因此，我们认识到 key 规范不完整，并且可能无法提取所有 key。但是，我们保证，只要命令在语法上正确，即使不完整的规范也永远不会产生错误的键名称。

在MIGRATE，则搜索从末尾开始（startFrom 的值为 -1）。如果我们遇到一个名为 “KEYS” 的键，我们只会提取它后面的键名称参数的子集。这就是为什么MIGRATE在其密钥规范中具有 incomplete 标志。

不完全性的另一种情况是SORT命令。在这里，begin_search和find_keys的类型为 unknown。客户端应恢复为调用COMMAND GETKEYS命令从参数中提取键名称，而不是在本地实现它。例如，困难在于字符串 “STORE” 既是关键字（标记）又是SORT.

注意：唯一具有不完整密钥规范的命令是SORT和MIGRATE. 我们预计将来不会添加此类命令。

variable_flags

在某些命令中，相同 key name 参数的标志可能依赖于其他参数。例如，考虑SET命令及其可选的 GET 参数。如果没有 GET 参数，SET是 write only，但它会成为 read and write 命令。当存在此标志时，这意味着键规范标志涵盖了所有可能的选项，但有效标志取决于其他参数。

例子

SET 关键规格

  1) 1) "flags"
     2) 1) RW
        2) access
        3) update
     3) "begin_search"
     4) 1) "type"
        2) "index"
        3) "spec"
        4) 1) "index"
           2) (integer) 1
     5) "find_keys"
     6) 1) "type"
        2) "range"
        3) "spec"
        4) 1) "lastkey"
           2) (integer) 0
           3) "keystep"
           4) (integer) 1
           5) "limit"
           6) (integer) 0

ZUNION 关键规格

  1) 1) "flags"
     2) 1) RO
        2) access
     3) "begin_search"
     4) 1) "type"
        2) "index"
        3) "spec"
        4) 1) "index"
           2) (integer) 1
     5) "find_keys"
     6) 1) "type"
        2) "keynum"
        3) "spec"
        4) 1) "keynumidx"
           2) (integer) 0
           3) "firstkey"
           4) (integer) 1
           5) "keystep"
           6) (integer) 1