命令键规范

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

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

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

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

Redis 客户端不需要支持键规范。它可以继续使用传统的第一个键、最后一个键和步长方案以及movablekeys 标志，这些标志保持不变。

然而，实现了键规范支持的 Redis 客户端可以合并大多数键的提取逻辑。即使客户端遇到不熟悉的键规范类型，它也可以始终回退到 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

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

1. index: 客户端应该从哪个基于 0 的索引开始提取键名。

keyword

begin_search 的 keyword 类型表示一个文字标记位于键名参数之前。它是在 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

find_keys 的 range 类型是在 spec 键下的一个映射，有三个键

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

keynum

find_keys 的 keynum 类型是在 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。
• AI.DAGRUN 命令的 start_search 类型为 keyword，其值为 "LOAD" 和 1，find_keys 的类型为 keynum，其值为 0、1 和 1。

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

notes

关于非显而易见的键规范考虑因素的说明（如果有）。

flags

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

访问类型标志

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

每个键规范都具有以下标志中的一个

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

逻辑操作标志

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

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

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

此外，规范可能包含以下标志中的一个

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

杂项标志

键规范可能具有以下标志

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

incomplete

某些命令在指定键时采用奇特的策略，这使得提取变得很困难。例如，考虑对 MIGRATE 的调用，它将文字字符串 "KEYS" 作为其 AUTH 子句的参数。我们的键规范将无法满足要求，提取将从错误的索引开始。

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

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

不完整性的另一个情况是 SORT 命令。在这里，begin_search 和 find_keys 的类型为 unknown。客户端应该回退到调用 COMMAND GETKEYS 命令以从参数中提取键名，除非本地实现它。例如，困难之处在于字符串 "STORE" 既是关键字（标记），又是 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