文档：命令键规范

Valkey 中的许多命令都接受键名作为输入参数。COMMAND（和 COMMAND INFO）回复中的第 9 个元素是一个数组，由命令的键规范组成。

键规范描述了一个从给定命令的参数中提取一个或多个键名的规则。与 Redis OSS 7.0 之前采用的首键、尾键和步长方案相比，键规范提供了一种健壮且灵活的机制。在引入这些规范之前，Valkey 客户端没有简单编程方法来提取所有命令的键名。

集群感知的 Valkey 客户端必须在 EVAL 和 ZUNIONSTORE 等依赖 numkeys 参数的命令，或者 SORT 及其多个子句的情况下，将键提取逻辑硬编码。或者，可以使用 COMMAND GETKEYS 来实现类似的提取效果，但延迟更高。

Valkey 客户端不必支持键规范。它可以继续使用旧的首键、尾键和步长方案以及保持不变的movablekeys 标志。

然而，实现了键规范支持的 Valkey 客户端可以整合其大部分键提取逻辑。即使客户端遇到不熟悉的键规范类型，它也始终可以回退到 COMMAND GETKEYS 命令。

话虽如此，大多数集群感知客户端只需要一个键名来执行正确的命令路由，因此即使某个命令具有不熟悉的规范，其其他规范可能仍然可被客户端使用。

键规范是带有以下键的映射

1. begin_search:：键提取的起始索引。
2. find_keys: 相对于 BS 识别键的规则。
3. notes: 有关此键规范的注释（如果有）。
4. flags: 指示数据访问类型。

begin_search

规范的 begin_search 值告知客户端提取的开始。该值是一个映射。begin_search 有三种类型

1. index: 键名参数从一个常量索引开始。
2. keyword: 键名在特定关键字（标记）之后开始。
3. unknown: 未知类型的规范 - 详情请参阅不完整标志部分。

index

index 类型的 begin_search 表示输入键出现在一个常量索引处。它是 spec 键下的一个映射，只包含一个键

1. index: 客户端应从中开始提取键名的 0-based 索引。

keyword

keyword 类型的 begin_search 意味着一个文字标记在键名参数之前。它是 spec 下的一个映射，包含两个键

1. keyword: 标记键名参数开始的关键字（标记）。
2. startfrom: 参数数组的索引，客户端应从该索引开始搜索。这可以是一个负值，表示搜索应从参数数组的末尾开始，按逆序进行。例如，-2 的意思是反向搜索，从倒数第二个参数开始。

keyword 搜索类型的更多示例包括

• SET 的 begin_search 规范类型为 index，值为 1。
• XREAD 的 begin_search 规范类型为 keyword，其 keyword 和 startfrom 值分别为 "STREAMS" 和 1。
• MIGRATE 的 start_search 规范类型为 keyword，值为 "KEYS" 和 -2。

find_keys

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

1. range: 键在特定索引处停止或相对于最后一个参数。
2. keynum: 附加参数指定输入键的数量。
3. unknown: 未知类型的规范 - 详情请参阅不完整标志部分。

range

range 类型的 find_keys 是 spec 键下的一个映射，包含三个键

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

keynum

keynum 类型的 find_keys 是 spec 键下的一个映射，包含三个键

• keynumidx: 相对于 begin_search 的包含键数量的参数索引。
• firstkey: 相对于 begin_search 的第一个键的索引。这通常是 keynumidx 之后的下一个参数，在这种情况下，其值会增加一。
• keystep: 找到一个键后，为找到下一个键而应跳过的参数数量。

示例

• SET 命令的 range 值为 0, 1 和 0。
• MSET 命令的 range 值为 -1, 2 和 0。
• XREAD 命令的 range 值为 -1, 1 和 2。
• ZUNION 命令的 start_search 类型为 index，值为 1；find_keys 类型为 keynum，值为 0, 1 和 1。

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

notes

有关不明显的键规范考虑事项的说明（如果适用）。

flags

键规范可以有额外的标志，提供关于键的更多详细信息。这些标志分为三组，如下所述。

访问类型标志

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

每个键规范都精确地包含以下标志之一

• RW: 读写标志。命令修改存储在键值或其元数据中的数据。此标志标记所有不明确为删除、覆盖或只读的操作。
• RO: 只读标志。命令只读取键的值（尽管不一定返回它）。
• OW: 覆盖标志。命令覆盖存储在键值中的数据。
• RM: 移除标志。命令删除键。

逻辑操作标志

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

每个键规范可能包含以下标志

• access: 访问标志。此标志表示命令返回、复制或以某种方式使用存储在键中的用户数据。

此外，规范可能精确地包含以下之一

• update: 更新标志。命令更新存储在键值中的数据。新值可能取决于旧值。此标志标记所有不明确为插入或删除的操作。
• insert: 插入标志。命令只向值添加数据；现有数据不被修改或删除。
• delete: 删除标志。命令明确删除存储在键值中的数据。

杂项标志

键规范可能具有以下标志

• not_key: 此标志表示指定的参数不是键。在计算命令应分配到 Valkey 集群的哪个槽时，此参数被视为与键相同。对于所有其他目的，此参数不应被视为键。
• incomplete: 此标志在下面解释。
• variable_flags: 此标志在下面解释。

incomplete

有些命令在指定其键时采用异乎寻常的方法，这使得提取变得困难。例如，考虑在 MIGRATE 调用中，如果其 AUTH 子句包含文字字符串 "KEYS" 作为参数，会发生什么。我们的键规范将失误，提取将从错误的索引开始。

因此，我们认识到键规范是不完整的，可能无法提取所有键。然而，我们保证，即使是不完整的规范也绝不会产生错误的键名，前提是命令在语法上是正确的。

在 MIGRATE 的情况下，搜索从末尾开始（startfrom 的值为 -1）。如果我们遇到一个名为 "KEYS" 的键，我们将只提取其后的键名参数子集。这就是为什么 MIGRATE 的键规范中带有 incomplete 标志。

另一个不完整的情况是 SORT 命令。在这里，begin_search 和 find_keys 的类型都是 unknown。客户端应回退到调用 COMMAND GETKEYS 命令来从参数中提取键名，而不是原生实现它。困难 arises, for example, because the string "STORE" is both a keyword (token) and a valid literal argument for SORT.

注意： 唯一带有 incomplete 键规范的命令是 SORT 和 MIGRATE。我们不期望将来增加此类命令。

variable_flags

在某些命令中，相同键名参数的标志可能取决于其他参数。例如，考虑 SET 命令及其可选的 GET 参数。如果没有 GET 参数，SET 是只写命令，但有了它，它就变成了读写命令。当此标志存在时，表示键规范标志涵盖所有可能的选项，但实际标志取决于其他参数。

示例

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