Keybyte命令十分丰富，包括的命令组有Bitmaps、Cluster、Connection、Geo、Hashes、HyperLogLog、Keys、Lists、Pub/Sub、Scripting、Server、Sets、Sorted Sets、Streams、Strings、Transactions一共16个keybyte命令组两百多个keybyte命令。本文将通过分组的方式分别介绍Keybyte中的命令。

Bitmaps

BITCOUNT

计算字符串中设置的位数（人口计数）。

默认情况下，检查字符串中包含的所有字节。可以仅在传递附加参数start和end的间隔中指定计数操作。

像GETRANGE命令一样，start 和 end 可以包含负值，以便从字符串的末尾开始索引字节，其中 -1 是最后一个字节，-2 是倒数第二个，依此类推。

不存在的键被视为空字符串，因此该命令将返回零。
返回值

整数回复：位数设置为 1。

例子

redis> **SET mykey "foobar"**

"OK"

redis> **BITCOUNT mykey**

(integer) 26

redis> **BITCOUNT mykey 0 0**

(integer) 4

redis> **BITCOUNT mykey 1 1**

(integer) 6

redis>

模式：使用位图的实时指标

位图是某些类型信息的非常节省空间的表示。一个例子是一个需要用户访问历史的 Web 应用程序，例如，它可以确定哪些用户是 beta 功能的良好目标。

使用SETBIT命令实现这一点很简单，用一个小的渐进整数标识每一天。例如，第 0 天是应用程序上线的第一天，第二天是第 1 天，依此类推。

每次用户执行页面查看时，应用程序可以使用设置与当天对应的位的SETBIT命令来注册用户在当天访问了网站。

稍后，只需针对位图调用BITCOUNT命令即可知道用户访问网站的单日天数。

使用用户 ID 而不是天数的类似模式在名为“使用 Keybyte 位图的快速简单实时指标”的文章中有所描述。

性能注意事项

在上面计算天数的例子中，即使应用程序上线 10 年后，我们365*10每个用户仍然只有比特数据，即每个用户只有 456 字节。有了这么大的数据量，BITCOUNT仍然与任何其他O(1) Keybyte 命令（如GET或INCR ）一样快。

当位图很大时，有两种选择：

每次修改位图时都会增加一个单独的键。使用一个小的 Keybyte Lua 脚本可以非常高效和原子化。
使用BITCOUNT start和end 可选参数以增量方式运行位图，在客户端累积结果，并可选择将结果缓存到一个键中。

BITFIELD

该命令将 Keybyte 字符串视为位数组，并且能够寻址不同位宽和任意非（必要）对齐偏移量的特定整数字段。实际上，您可以使用此命令将位偏移量 1234 处的有符号 5 位整数设置为特定值，从偏移量 4567 检索 31 位无符号整数。类似地，该命令处理指定整数的递增和递减，提供用户可以配置的保证和明确指定的上溢和下溢行为。

BITFIELD能够在同一个命令调用中使用多个位字段进行操作。它需要一个要执行的操作列表，并返回一个回复数组，其中每个数组都与参数列表中的相应操作相匹配。

例如，以下命令在位偏移 100 处递增一个 5 位有符号整数，并在位偏移 0 处获取 4 位无符号整数的值：

> BITFIELD mykey INCRBY i5 100 1 GET u4 0

1) (integer) 1

2) (integer) 0

注意：

使用GET当前字符串长度之外的位寻址（包括key根本不存在的情况），会导致要执行的操作就像丢失的部分全部由设置为 0 的位组成。
使用SET或INCRBY当前字符串长度之外的位寻址将扩大字符串，根据需要根据最远位触及的最小长度对其进行零填充。
- 用法:

支持的子命令和整数类型

以下是支持的命令列表。

GET—— <type> <offset>返回指定的位域。
SET <type> <offset> <value> -- 设置指定的位域并返回其旧值。
INCRBY—— <type> <offset> <increment>递增或递减（如果给出负递增）指定的位域并返回新值。

还有另一个子命令，它只通过设置溢出行为来改变连续 INCRBY和SET子命令调用的行为：

溢出 [WRAP|SAT|FAIL]

在需要整数类型的地方，它可以通过i为有符号整数和u无符号整数加上我们的整数类型的位数作为前缀来组成。因此，例如u8是一个 8 位的无符号整数和i16一个 16 位的有符号整数。

支持的类型有符号整数最多 64 位，无符号整数最多 63 位。无符号整数的这种限制是由于当前 Keybyte 协议无法返回 64 位无符号整数作为回复。

位和位置偏移

有两种方法可以在位域命令中指定偏移量。如果指定了没有任何前缀的数字，则它仅用作字符串内基于零的位偏移量。

但是，如果偏移量以#字符为前缀，则指定的偏移量将乘以整数类型的宽度，例如：

BITFIELD mystring SET i8 #0 100 SET i8 #1 200

将在偏移量 0 处设置第一个 i8 整数，在偏移量 8 处设置第二个整数。这样，如果您想要的是给定大小的普通整数数组，则不必在客户端内部进行数学计算。

溢出控制

使用该OVERFLOW命令，用户可以通过指定以下行为之一来微调递增或递减溢出（或下溢）的行为：

WRAP：环绕，包括有符号和无符号整数。在无符号整数的情况下，换行就像对整数可以包含的最大值进行模运算（C 标准行为）。使用有符号整数代替包装意味着溢出重新开始朝向最负值并下溢朝向最正值，因此例如，如果i8整数设置为值 127，则将其增加 1 将产生-128。
SAT：使用饱和算法，即下溢时设置为最小整数值，溢出时设置为最大整数值。例如，i8从值 120 开始以 10 的增量递增一个整数，将导致值 127，并且进一步递增将始终将该值保持在 127。下溢时也会发生同样的情况，但该值在最大负值处被阻塞.
FAIL：在此模式下，不会对检测到的上溢或下溢执行任何操作。相应的返回值设置为 NULL 以向调用者发出条件信号。

请注意，每个OVERFLOW语句只影响子命令列表中跟在它后面的INCRBY和SET命令，直到下一个OVERFLOW 语句。

默认情况下，如果没有另外指定，则使用WRAP。

> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102
1

1) (integer) 1

2) (integer) 1

> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102
1

1) (integer) 2

2) (integer) 2

> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102
1

1) (integer) 3

2) (integer) 3

> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102
1

1) (integer) 0

2) (integer) 3

返回值

该命令返回一个数组，每个条目是在相同位置给出的子命令的相应结果。OVERFLOW子命令不算作生成回复。

以下是OVERFLOW FAIL返回 NULL的示例。

> BITFIELD mykey OVERFLOW FAIL incrby u2 102 1

1) (nil)

动机

此命令的动机是将许多小整数存储为单个大位图（或分割成几个键以避免使用大键）的能力非常有效，并为 Keybyte 应用开辟了新的用例，特别是在实时分析领域。以受控方式指定溢出的能力支持此用例。

有趣的示例：Reddit 的 2017 年愚人节项目r/place是使用 Keybyte BITFIELD 命令构建的，以便在内存中表示协作画布。

性能注意事项

通常BITFIELD是一个快速命令，但是请注意，寻址当前短字符串的远位将触发分配，这可能比在已经存在的位上执行命令的成本更高。

位的顺序

BITFIELD使用的表示将位图视为第一个字节的最高有效位的位数为 0，依此类推，例如，将偏移 7 处的 5 位无符号整数设置为值 23 到先前设置为的位图中全为零，将产生以下表示：

+--------+--------+

|00000001|01110000|

+--------+--------+

当偏移量和整数大小与字节边界对齐时，这与大端对齐相同，但是当这种对齐不存在时，理解字节内的位是如何排列的也很重要。

BITOP

在多个键（包含字符串值）之间执行按位运算并将结果存储在目标键中。

该BITOP命令支持四个位运算：AND，OR，XOR 和NOT，从而有效形式调用命令是：

BITOP AND destkey srckey1 srckey2 srckey3 … srckeyN
BITOP OR destkey srckey1 srckey2 srckey3 … srckeyN
BITOP XOR destkey srckey1 srckey2 srckey3 … srckeyN
BITOP NOT destkey srckey

正如您所看到的，NOT很特殊，因为它只需要一个输入键，因为它执行位反转，因此它仅作为一元运算符才有意义。

操作的结果总是存储在destkey。

处理不同长度的字符串

当在具有不同长度的字符串之间执行操作时，所有比集合中最长字符串短的字符串都被视为零填充直到最长字符串的长度。

对于不存在的键也是如此，它们被认为是最长字符串长度的零字节流。

返回值

整数回复：存储在目标键中的字符串的大小，即等于最长输入字符串的大小。

例子

redis> SET key1 "foobar"

"OK"

redis> SET key2 "abcdef"

"OK"

redis> BITOP AND dest key1 key2

(integer) 6

redis> GET dest

"`bc`ab"



redis>

模式：使用位图的实时指标

BITOP是对BITCOUNT命令文档中记录的模式的一个很好的补充。可以组合不同的位图以获得执行人口计数操作的目标位图。

性能注意事项

BITOP是一个潜在的慢命令，因为它在O(N)时间内运行。对长输入字符串运行它时应该小心。

对于涉及大量输入的实时指标和统计数据，一个好的方法是使用副本（禁用只读选项），其中执行按位操作以避免阻塞主实例。

BITPOS

返回字符串中设置为 1 或 0 的第一位的位置。

返回位置，将字符串视为从左到右的位数组，其中第一个字节的最高有效位位于位置 0，第二个字节的最高有效位位于位置 8，依此类推。

GETBIT和SETBIT遵循相同的位位置约定。

默认情况下，检查字符串中包含的所有字节。可以仅在指定的时间间隔内通过附加参数start和end查找位（可以只传递start，该操作将假定结尾是字符串的最后一个字节。但是，如解释的那样存在语义差异之后）。该范围被解释为字节范围而不是位范围，因此start=0andend=2意味着查看前三个字节。

请注意，即使使用start和end来指定范围，位位置也始终作为从位 0 开始的绝对值返回。

像GETRANGE命令一样，start 和 end 可以包含负值，以便从字符串的末尾开始索引字节，其中 -1 是最后一个字节，-2 是倒数第二个，依此类推。

不存在的键被视为空字符串。

返回值

整数回复

该命令根据请求返回设置为 1 或 0 的第一位的位置。

如果我们查找设置位（位参数为 1）并且字符串为空或仅由零字节组成，则返回 -1。

如果我们寻找清除位（位参数为 0）并且字符串仅包含设置为 1 的位，则该函数返回第一个位，而不是右侧字符串的一部分。因此，如果字符串是设置为值0xff的三个字节，则命令BITPOS key 0将返回 24，因为直到第 23 位，所有位都是 1。

基本上，如果您查找清除位并且未指定范围或仅指定起始参数，则该函数会将字符串的右侧视为用零填充。

但是，如果您正在寻找清除位并使用start和end指定范围，则此行为会发生变化。如果在指定范围内未找到清除位，则该函数返回 -1，因为用户指定了清除范围并且该范围内没有 0 位。

例子

redis> **SET mykey "\xff\xf0\x00"**

"OK"

redis> **BITPOS mykey 0**

(integer) 12

redis> **SET mykey "\x00\xff\xf0"**

"OK"

redis> **BITPOS mykey 1 0**

(integer) 8

redis> **BITPOS mykey 1 2**

(integer) 16

redis> **set mykey "\x00\x00\x00"**

"OK"

redis> **BITPOS mykey 1**

(integer) -1



redis>

GETBIT

返回位的值存储在关键的字符串值的偏移量。

返回存储在key的字符串值中offset处的位值。

当偏移量超过字符串长度时，字符串被假定为一个连续的空间，有 0 位。当key不存在时，它被假定为一个空字符串，因此偏移量总是超出范围，并且该值也被假定为一个具有 0 位的连续空间。

返回值
整数回复:存储在offset处的位值。

SETBIT

设置或清除存储在key的字符串值中offset处的位。

该位根据value设置或清除，value可以是 0 或 1。

当键不存在时，会创建一个新的字符串值。字符串被增长以确保它可以在offset处保持一点。所述偏移参数是必需的，以大于或等于0，且小于2 ³²（这限制位图（BIGMAP）512MB）。当key处的字符串增长时，添加的位设置为 0。

警告：当设置最后一个可能的位（offset等于 2 ³² -1）并且存储在key的字符串值还没有保存字符串值，或者保存了一个很小的字符串值时，Keybyte 需要分配所有可以阻塞的中间内存服务器一段时间。在 2010 款 MacBook Pro 上，设置位数 2 ³² -1（512MB 分配）需要约 300 毫秒，设置位数 2 ³⁰ -1（128MB 分配）需要约 80毫秒，设置位数2 ²⁸ -1（32MB 分配）需要约 30 毫秒并设置位数 2 ²⁶-1（8MB 分配）大约需要 8 毫秒。请注意，一旦第一次分配完成，后续对相同键的SETBIT调用将不会有分配开销。

返回值

整数回复：存储在offset处的原始位值。

例子

redis> **SETBIT mykey 7 1**

(integer) 0

redis> **SETBIT mykey 7 0**

(integer) 1

redis> **GET mykey**

"\u0000"


redis>

模式：访问整个位图（BIGMAP）

在某些情况下，您需要一次设置单个位图的所有位，例如将其初始化为默认的非零值时。可以通过多次调用SETBIT命令来做到这一点，每个需要设置的位调用一次。但是，作为优化，您可以使用单个SET命令来设置整个位图。

位图不是实际的数据类型，而是在 String 类型上定义的一组面向位的操作。这意味着位图可以与字符串命令一起使用，最重要的是与SET和 GET 一起使用。

因为 Keybyte 的字符串是二进制安全的，位图被简单地编码为字节流。字符串的第一个字节对应于位图的偏移量 0..7，第二个字节对应于 8..15 范围，依此类推。

例如，设置几位后，获取位图的字符串值将如下所示：

> SETBIT bitmapsarestrings 2 1

> SETBIT bitmapsarestrings 3 1

> SETBIT bitmapsarestrings 5 1

> SETBIT bitmapsarestrings 10 1

> SETBIT bitmapsarestrings 11 1

> SETBIT bitmapsarestrings 14 1

> GET bitmapsarestrings

"42"

通过获取位图（BIGMAP）的字符串表示，客户端可以通过在其本地编程语言中使用本地位操作提取位值来解析响应的字节。对称地，也可以通过在客户端执行位到字节编码并使用结果字符串调用SET来设置整个位图。

模式：设置多个位

SETBIT擅长设置单个位，需要设置多个位时可以多次调用。要优化此操作，您可以将多个SETBIT调用替换为对可变参数BITFIELD命令的单个调用和 type 字段的使用u1。

例如，上面的示例可以替换为：

> BITFIELD bitsinabitmap SET u1 2 1 SET u1 3 1 SET u1 5 1 SET u1
10 1 SET u1 11 1 SET u1 14 1

高级模式：访问位图范围

也可以使用GETRANGE和SETRANGE字符串命令来有效地访问位图中的位偏移范围。以下是可使用EVAL 命令运行的惯用 Keybyte Lua 脚本中的示例实现：

--[[

Sets a bitmap range

Bitmaps are stored as Strings in Redis. A range spans one or more
bytes,

so we can call [SETRANGE](/commands/setrange) when entire bytes
need to be set instead of flipping

individual bits. Also, to avoid multiple internal memory
allocations in

Redis, we traverse in reverse.

Expected input:

  KEYS[1] - bitfield key

  ARGV[1] - start offset (0-based, inclusive)

  ARGV[2] - end offset (same, should be bigger than start, no
error checking)

  ARGV[3] - value (should be 0 or 1, no error
checking)

]]--

-- A helper function to stringify a binary string to semi-binary
format

local function tobits(str)

  local r = ''

  for i = 1, string.len(str) do

    local c = string.byte(str, i)

    local b = ' '

    for j = 0, 7 do

      b = tostring(bit.band(c, 1)) .. b

      c = bit.rshift(c, 1)

    end

    r = r .. b

  end

  return r

end

-- Main

local k = KEYS[1]

local s, e, v = tonumber(ARGV[1]), tonumber(ARGV[2]),
tonumber(ARGV[3])

-- First treat the dangling bits in the last byte

local ms, me = s % 8, (e + 1) % 8

if me > 0 then

  local t = math.max(e - me + 1, s)

  for i = e, t, -1 do

    redis.call('SETBIT', k, i, v)

  end

  e = t

end

-- Then the danglings in the first byte

if ms > 0 then

  local t = math.min(s - ms + 7, e)

  for i = s, t, 1 do

    redis.call('SETBIT', k, i, v)

  end

  s = t + 1

end

-- Set a range accordingly, if at all

local rs, re = s / 8, (e + 1) / 8

local rl = re - rs

if rl > 0 then

  local b = '\255'

  if 0 == v then

    b = '\0'

  end

  redis.call('SETRANGE', k, rs, string.rep(b, rl))

end

Cluster

CLUSTER ADDSLOTS

此命令可用于修改节点的集群配置视图。具体来说，它为接收命令的节点分配一组哈希槽（hash slots）。如果命令成功，节点会将指定的哈希槽（hash slots）映射到自身，并开始广播新配置。

但请注意：

从接收命令的节点的角度来看，该命令仅在所有指定的插槽（slots）当前未分配时才起作用。一个节点将拒绝对已经属于某个其他节点（包括它自己）的插槽（slots）取得所有权。
如果多次指定同一插槽，则该命令将失败。
作为命令执行的副作用，如果指定为参数的插槽（slots）中的插槽（slots）设置为importing，则一旦节点将（以前未绑定的）插槽分配给自身，此状态就会清除。

例子

例如，以下命令将插槽（slots） 1 2 3 分配给接收命令的节点：

> CLUSTER ADDSLOTS 1 2 3

OK

但是，由于插槽（slots）已经分配，因此尝试再次执行它会导致错误：

> CLUSTER ADDSLOTS 1 2 3

ERR Slot 1 is already busy

在Keybyte集群中的使用

此命令仅在集群模式下有效，在以下 Keybyte 集群操作中很有用：

创建新集群 ADDSLOTS 用于初始设置主节点，在它们之间拆分可用的哈希槽。
为了修复某些插槽未分配的损坏集群。

有关插槽传播和警告的信息

请注意，一旦节点为自己分配了一组时隙，它将开始在心跳包的头中传播此信息。然而，只有当其他节点的插槽尚未与另一个节点绑定时，或者如果通告新哈希插槽的节点的配置纪元(epoch)大于表中当前列出的节点，其他节点才会接受该信息。

这意味着此命令仅应由编排 Keybyte 集群的应用程序谨慎使用，例如redis-cli，如果在正确的上下文之外使用该命令可能会使集群处于错误状态或导致数据丢失。

返回值

简单的字符串回复：如果命令成功返回OK，否则返回错误信息。

CLUSTER BUMPEPOCH

推进集群配置纪元(epoch)。
CLUSTER BUMPEPOCH命令触发从连接节点到集群配置epoch的增量。如果节点的配置epoch为0，或者小于集群的最大epoch，则epoch将增加。
注意:配置epoch管理是由集群内部执行的，依赖于获得节点的一致意见。CLUSTER BUMPEPOCH试图在没有获得一致意见的情况下增加配置时间，因此使用它可能违反“最后一次故障转移获胜”规则。小心使用。
返回值
简单的字符串回复：如果epoch增加，则为bumped;如果节点已经拥有集群中最大的配置epoch，则为STILL。

CLUSTER COUNT-FAILURE-REPORTS

该命令返回指定节点的故障报告数。故障报告是 Keybyte 集群用来提升 PFAIL状态的方式，这意味着节点不可达，到FAIL状态，这意味着集群中的大多数主节点在节点不可达的时间窗口内达成一致。

更多细节：

PFAIL当节点无法访问的时间超过配置的节点 timeout 时，节点会标记另一个节点，这是 Keybyte 集群的基本配置参数。
PFAIL状态节点在心跳包的八卦部分中提供。
每次节点处理来自其他节点的八卦数据包时，它都会创建（并在需要时刷新 TTL）故障报告，记住给定节点表示另一个给定节点处于PFAIL状况。
每个故障报告的生存时间是节点超时时间的两倍。
如果在给定时间一个节点已经另一节点与标记PFAIL，并在同一时间所收集的大多数的其他主节点的故障报告关于该节点（包括自身如果是主设备），然后将其提升从节点的故障状态PFAIL到FAIL，并广播一条消息，强制所有可以到达的节点将该节点标记为FAIL。

此命令返回当前节点的故障报告数量，这些报告当前未过期（因此在节点超时时间的两倍内收到）。该计数不包括我们询问该计数的节点对我们作为参数传递的节点 ID 的看法，该计数仅包括该节点从其他节点收到的故障报告。

此命令主要用于调试，当 Keybyte Cluster 的故障检测器未按我们认为应有的方式运行时。

返回值

整数回复：节点的活动故障报告数量。

CLUSTER COUNTKEYSINSLOT

返回指定 Keybyte Cluster 哈希槽中的键数。该命令仅查询本地数据集，因此联系不为指定哈希槽提供服务的节点将始终导致返回计数为零。

> CLUSTER COUNTKEYSINSLOT 7000

(integer) 50341

返回值

整数回复：指定哈希槽中的键数，如果哈希槽无效则报错。

CLUSTER DELSLOTS

在 Keybyte 集群中，每个节点都会跟踪哪个主节点正在为特定的哈希槽提供服务。

该DELSLOTS命令要求特定的 Keybyte 集群节点忘记哪个主服务器正在为指定为参数的哈希槽提供服务。

在收到DELSLOTS命令并因此删除传递的散列槽的关联的节点的上下文中，我们说这些散列槽是未绑定的。请注意，当节点尚未配置为处理它们（可以通过ADDSLOTS命令完成）并且没有收到有关谁拥有这些哈希槽的任何信息（它可以学习的东西）时，未绑定哈希槽的存在自然会发生从心跳或更新消息）。

如果具有未绑定散列槽的节点从声称是其中一些散列槽的所有者的另一个节点收到心跳数据包，则立即建立关联。此外，如果收到心跳或更新消息的配置纪元(epoch)大于节点自己的配置纪元(epoch)，则重新建立关联。

但是，请注意：

该命令仅在所有指定的插槽都已与某个节点关联时才有效。
如果多次指定同一插槽，则该命令将失败。
作为命令执行的副作用，节点可能会进入关闭状态，因为并非所有哈希槽都被覆盖。

例子

以下命令从接收命令的节点中删除插槽 5000 和 5001 的关联：

> CLUSTER DELSLOTS 5000 5001

OK

在Keybyte集群中的使用

此命令仅适用于集群模式，可用于调试以及在创建新集群时手动编排集群配置。它目前没有被使用redis-cli，主要是为了 API 完整性而存在。

返回值

简单字符串回复：如果命令成功执行返回OK，否则返回一个错误。

CLUSTER FAILOVER

此命令只能发送到 Keybyte Cluster 副本节点，强制副本启动其主实例的手动故障转移。

手动故障转移是一种特殊的故障转移，通常在没有实际故障时执行，但我们希望以安全的方式将当前主节点与其副本之一（即我们发送命令的节点）交换，没有任何数据丢失窗口。它的工作方式如下：

副本告诉主服务器停止处理来自客户端的查询。
主用当前复制偏移量回复副本。
副本等待复制偏移量在其一侧匹配，以确保它在继续之前处理了来自主服务器的所有数据。
副本开始故障转移，从大多数主节点获取新的配置纪元(epoch)，并广播新配置。
旧的 master 收到配置更新：取消阻止其客户端并开始回复重定向消息，以便他们继续与新 master 聊天。

通过这种方式，客户端以原子方式从旧主服务器移至新主服务器，并且仅当正在变成新主服务器的副本已处理来自旧主服务器的所有复制流时。

FORCE 选项：当主服务器关闭时手动故障转移

命令行为可以通过两个选项修改：FORCE和TAKEOVER。

如果给定FORCE选项，则副本不会与主服务器执行任何握手，这可能无法访问，而是从第 4 点开始尽快启动故障转移。当我们想要在主服务器的同时启动手动故障转移时，这很有用不再可达。

然而，使用FORCE，我们仍然需要大多数 masters 可用，以便授权故障转移并为将成为 master 的副本生成新的配置纪元(epoch)。

TAKEOVER 选项：没有集群共识的手动故障转移

在某些情况下，这还不够，我们希望副本在不与集群的其余部分达成任何协议的情况下进行故障转移。一个真实世界的用例是将不同数据中心的副本批量提升到主节点以执行数据中心切换，同时所有主节点都关闭或分区。

该TAKEOVER选项意味着一切FORCE意味着，但也没有任何使用授权集群，以故障转移。接收副本 CLUSTER FAILOVER TAKEOVER将改为：

configEpoch单方面生成一个新的，只取当前可用的最大 epoch，如果其本地配置 epoch 还不是最大的，则增加它。
将其主节点的所有哈希槽分配给自己，并将新配置尽快传播到每个可访问的节点，并最终传播到每个其他节点。

注意TAKEOVER违反了Keybyte Cluster的last-failover-wins原则，因为replica生成的配置epoch在几个方面违反了正常的配置epoch生成：

不能保证它实际上是更高的配置纪元(epoch)，因为例如，我们可以在少数情况下使用TAKEOVER选项，也不会执行任何消息交换来生成新的配置纪元(epoch)。
如果我们生成的配置纪元(epoch)碰巧与另一个实例发生冲突，最终我们的配置纪元(epoch)或具有相同纪元(epoch)的另一个实例将使用配置纪元(epoch)碰撞解决算法移开。

因此，应谨慎使用TAKEOVER选项。

实施细节和注意事项

CLUSTER FAILOVER，除非指定了TAKEOVER选项，否则不会同步执行故障转移。它只安排手动故障转移，绕过故障检测阶段。
的OK回答是不能保证故障转移会成功。
如果副本被集群中的大多数主节点称为副本，则它只能被提升为主节点。如果副本是刚刚添加到集群中的新节点（例如在升级之后），则集群中的所有主节点可能都不知道它。要检查主节点是否知道新副本，您可以将CLUSTER NODES或CLUSTER REPLICAS发送到每个主节点并检查它是否显示为副本，然后再将CLUSTER FAILOVER发送到副本。
要检查故障已实际发生，你可以使用角色，INFO REPLICATION（这表明“角色：主”成功的故障转移后），或群集节点来验证集群的状态已经改变某个命令发出后。
要检查故障转移是否失败，请检查副本的日志中是否有“手动故障转移超时”，如果副本在几秒钟后放弃，则会记录该日志。

返回值

简单的字符串回复：OK如果命令被接受并且将尝试手动故障转移。如果操作无法执行，则会出现错误，例如，如果我们正在与已经是主节点的节点进行对话。

CLUSTER FLUSHSLOTS

从节点中删除所有插槽。

所述CLUSTER FLUSHSLOTS删除关于从所连接的节点槽的所有信息。只能在数据库为空时调用。

返回值

简单的字符串回复：OK

CLUSTER FORGET

该命令可以从收到命令的keybyte群集节点的节点信息列表中移除指定ID的节点。换句话说，从收到命令的keybyte群集节点的nodes table中删除指定节点。

该命令不是将待删除节点的信息简单从内部配置中简单删除，它同时实现了禁止列表功能：不允许已删除的节点再次被添加进来，否则已删除节点会因为处理其他节点心跳包中的gossip section时被再次添加。

命令执行详细

假设我们有四个节点:A,B,C,D。为了得到一个三节点群集A,B,C，我们可以做如下操作：

将D上的哈希槽重分配到节点A,B,C。
节点D现在已经空了，但是节点A,B,C的节点信息表中仍然有D的信息。
我们连接节点A，发送命令CLUSTER FORGET D。
节点B发送心跳包给节点A，包含节点D的信息。
节点A无节点D信息，无法识别节点D(参见步骤3)，因此开始与节点D握手。
节点D最终再次添加进节点A的节点信息表中。

上述的移除方法很不稳定，因此我们需要尽快发送命令CLUSTER FORGET 给所有节点，以期没有gossip sections在同时处理。因为这个原因，命令CLUSTER FORGET为每个节点实现了包含超时时间的禁止列表

因此我们命令实际的执行情况如下：

从收到命令节点的节点信息列表中删除待删除节点的节点信息。
已删除的节点的节点ID被加入禁止列表，保留1分钟
收到命令的节点，在处理从其他节点发送过来的gossip sections 会跳过所有在禁止列表中的节点。

这样，想要删除某个节点，我们就有60秒的时间窗口来通知群集中的所有节点。该命令无法执行的特殊情况

在如下情况下，该命令无法成功执行并返回错误

节点信息表中无法找到指定删除节点的节点信息
收到命令的节点是slave 节点，指定要删除的节点被识别出是它的当前master节点。
收到命令的节点和待删除的节点是同一节点

返回值

simple-string-reply：命令成功执行返回OK，否则返回错误

CLUSTER GETKEYSINSLOT

该命令返回存储在联系节点中的键名数组，并散列到指定的散列槽。通过count参数指定要返回的最大键数，以便此 API 的用户可以批处理键。

此命令的主要用途是将集群插槽从一个节点重新散列到另一个节点期间。重新散列的执行方式在 Keybyte Cluster 规范中公开，或者以更简单易懂的形式公开，作为CLUSTER SETSLOT命令文档的附录。

> CLUSTER GETKEYSINSLOT 7000 3

"47344|273766|70329104160040|key_39015"

"47344|273766|70329104160040|key_89793"

"47344|273766|70329104160040|key_92937"

CLUSTER INFO

INFO提供有关 Keybyte Cluster 重要参数的INFO 样式信息。以下是示例输出，后跟报告的每个字段的说明。

cluster_state:ok

cluster_slots_assigned:16384

cluster_slots_ok:16384

cluster_slots_pfail:0

cluster_slots_fail:0

cluster_known_nodes:6

cluster_size:3

cluster_current_epoch:6

cluster_my_epoch:2

cluster_stats_messages_sent:1483972

cluster_stats_messages_received:1483968

cluster_state：状态是ok节点是否能够接收查询。fail如果至少有一个哈希槽未绑定（没有关联节点）、处于错误状态（为其提供服务的节点被标记为 FAIL 标志），或者该节点无法访问大多数主节点。
cluster_slots_assigned：与某个节点相关联的插槽数（未绑定）。这个数字应该是 16384 节点才能正常工作，这意味着每个哈希槽都应该映射到一个节点。
cluster_slots_ok：映射到未处于FAIL或未PFAIL处于状态的节点的哈希槽数。
cluster_slots_pfail：映射到PFAIL状态节点的哈希槽数。请注意，只要故障检测算法PFAIL不提升状态，这些哈希槽仍然可以正常工作FAIL。PFAIL仅表示我们目前无法与节点对话，但可能只是暂时性错误。
cluster_slots_fail：映射到FAIL状态节点的哈希槽数。如果此数字不为零，则节点无法提供查询服务，除非在配置中cluster-require-full-coverage设置为no。
cluster_known_nodes：集群中已知节点的总数，包括HANDSHAKE当前可能不是集群适当成员的状态节点。
cluster_size：集群中至少服务于一个哈希槽的主节点数。
cluster_current_epoch: 局部Current Epoch变量。这用于在故障转移期间创建唯一的递增版本号。
cluster_my_epoch：Config Epoch我们正在与之交谈的节点的。这是分配给该节点的当前配置版本。
cluster_stats_messages_sent：通过集群节点到节点二进制总线发送的消息数。
cluster_stats_messages_received：通过集群节点到节点二进制总线接收的消息数。

CLUSTER KEYSLOT

返回一个整数，标识指定键散列到的散列槽。此命令主要用于调试和测试，因为它通过 API 公开散列算法的底层 Keybyte 实现。此命令的示例用例：

客户端库可能会使用 Keybyte 来测试他们自己的散列算法，生成随机key并使用本地实现和使用 Keybyte CLUSTER KEYSLOT命令对它们进行散列，然后检查结果是否相同。
人类可以使用这个命令来检查哈希槽是什么，然后是关联的 Keybyte 集群节点，负责给定的键。

例子

> CLUSTER KEYSLOT somekey

11058

> CLUSTER KEYSLOT foo\{hash_tag}

(integer) 2515

> CLUSTER KEYSLOT bar\{hash_tag}

(integer) 2515

请注意，该命令实现了完整的散列算法，包括对散列标签的支持，这是 Keybyte Cluster 键散列算法的特殊属性，如果在键名中发现这样的模式\{，}则对它们之间的内容进行散列，以强制由同一个节点处理的多个键。

CLUSTER MEET

CLUSTER MEET用于将启用了集群支持的不同 Keybyte 节点连接到一个工作集群中。

基本思想是默认情况下节点不相互信任，并且被认为是未知的，因此不太可能由于系统管理错误或网络地址修改而将不同的集群节点混合为一个。

因此，为了让给定节点接受另一个节点进入组成 Keybyte 集群的节点列表，只有两种方法：

系统管理员发送一个CLUSTER MEET命令来强制一个节点与另一个节点相遇。
一个已知的节点在八卦部分发送一个我们不知道的节点列表。如果接收节点信任发送节点为已知节点，它将处理八卦部分并向仍然未知的节点发送握手。

注意Keybyte Cluster需要形成全网状网络（每个节点与其他节点相连），但是为了创建集群，不需要发送所有形成全网状网络所需的CLUSTER MEET命令。重要的是发送足够多的CLUSTER MEET消息，以便每个节点可以通过已知节点的链到达彼此的节点。由于心跳包中的八卦信息交换，丢失的链接将被创建。

因此，如果我们通过CLUSTER MEET将节点 A 与节点 B以及 B 与 C 链接起来，A 和 C 将找到握手并创建链接的方法。

另一个例子：如果我们想象一个集群由以下四个节点组成，称为 A、B、C 和 D，我们可能只向 A 发送以下命令集：

CLUSTER MEET B-ip B-port
CLUSTER MEET C-ip C-port
CLUSTER MEET D-ip D-port

作为A知道和被所有其他节点知道的副作用，它会在心跳包中发送八卦部分，这将允许其他节点相互创建链接，在几秒钟内形成一个完整的网格，甚至如果集群很大。

此外，CLUSTER MEET不需要相互执行。如果我将命令发送给 A 以加入 B，我不需要也将它发送给 B 以加入 A。

实现细节：MEET和PING包

当给定节点收到CLUSTER MEET消息时，命令中指定的节点仍然不知道我们发送命令的节点。所以为了让节点强制接收方接受它作为受信节点，它发送一个 MEET数据包而不是PING数据包。这两个数据包具有完全相同的格式，但前者强制接收方确认该节点是可信的。

CLUSTER MYID

返回节点的 id。

CLUSTER MYID 返回与连接的集群节点关联的唯一、自动生成的标识符。

CLUSTER NODES

Keybyte 集群中的每个节点都有其当前集群配置的视图，由一组已知节点、我们与这些节点的连接状态、它们的标志、属性和分配的插槽等给出。

CLUSTER NODES以序列化格式提供所有这些信息，即我们正在联系的节点的当前集群配置，该格式恰好与 Keybyte Cluster 本身使用的格式完全相同，以便将集群状态存储在磁盘上（但是磁盘集群状态在末尾附加了一些附加信息）。

请注意，通常愿意获取集群哈希槽和节点地址之间映射的客户端应该使用CLUSTER SLOTS代替。 CLUSTER NODES提供更多信息，应该用于管理任务、调试和配置检查。它也用于redis-cli管理集群。

用法

序列化格式

命令的输出只是一个以空格分隔的 CSV 字符串，其中每一行代表集群中的一个节点。以下是输出示例：

07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:30004@31004
slave e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 0 1426238317239 4
connected

67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 127.0.0.1:30002@31002
master - 0 1426238316232 2 connected 5461-10922

292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 127.0.0.1:30003@31003
master - 0 1426238318243 3 connected 10923-16383

6ec23923021cf3ffec47632106199cb7f496ce01 127.0.0.1:30005@31005
slave 67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 0 1426238316232 5
connected

824fe116063bc5fcf9f4ffd895bc17aee7731ac3 127.0.0.1:30006@31006
slave 292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 0 1426238317741 6
connected

e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 127.0.0.1:30001@31001
myself,master - 0 0 1 connected 0-5460

每行由以下字段组成：

<id> <ip:port@cport> <flags> <master> <ping-sent> <pong-recv>
<config-epoch> <link-state> <slot> <slot> ... <slot>

每个字段的含义如下：

id: 节点 ID，一个 40 个字符的随机字符串，在节点创建时生成，不再更改（除非CLUSTER RESET HARD使用）。
ip:port@cport：客户端应联系节点以运行查询的节点地址。
flags: 逗号分隔标志的列表：myself, master, slave, fail?, fail, handshake, noaddr, nofailover, noflags. 下一节将详细解释标志。
master：如果节点是副本，并且master已知，则为master节点ID，否则为“-”字符。
ping-sent：发送当前活动 ping 的毫秒 unix 时间，如果没有挂起的 ping，则为零。
pong-recv: 毫秒 unix 时间收到最后一个乒乓。
config-epoch：当前节点（或当前主节点，如果节点是副本）的配置纪元(epoch)（或版本）。每次发生故障转移时，都会创建一个新的、独特的、单调递增的配置纪元(epoch)。如果多个节点声称为相同的哈希槽提供服务，则具有更高配置 epoch 的节点将获胜。
link-state：用于节点到节点集群总线的链路状态。我们使用此链接与节点进行通信。可以connected或disconnected。
slot: 一个哈希槽号或范围。从参数编号 9 开始，但总共可能有多达 16384 个条目（从未达到限制）。这是该节点服务的哈希槽列表。如果条目只是一个数字，则按此解析。如果是范围，则采用 , 形式start-end，表示该节点负责从start到end包括开始和结束值的所有哈希槽。

标志的含义（字段编号 3）：

myself：您正在联系的节点。
master: 节点是大师。
slave: 节点是一个副本。
fail?: 节点处于PFAIL状态。您正在联系的节点无法访问，但在逻辑上仍然可以访问（未处于FAIL状态）。
fail: 节点处于FAIL状态。将PFAIL状态提升为的多个节点无法访问它FAIL。
handshake: 不受信任的节点，我们正在握手。
noaddr: 此节点没有已知地址。
nofailover: 副本不会尝试故障转移。
noflags: 根本没有标志。

关于已发布配置纪元(epoch)的说明

副本广播其主节点的配置纪元(epoch)（以便UPDATE 在发现它们陈旧时获得消息），因此副本的真实配置纪元(epoch)（或多或少毫无意义，因为它们不提供哈希槽）只能是获得检查标记为的节点myself，这是我们要求生成CLUSTER NODES输出的节点的条目。其他副本纪元(epoch)反映了它们在心跳包中发布的内容，即它们当前正在复制的主节点的配置纪元(epoch)。

特殊插槽条目

通常与给定节点关联的哈希槽采用以下格式之一，如上文所述：

单号：3894
范围：3900-4000

但是，节点哈希槽可以处于特殊状态，用于在节点重新启动（AOF/KDB 文件中的键与节点哈希槽配置之间不匹配）或正在进行重新分片操作后传达错误信息. 这两个状态是输入和迁移。

Keybyte 规范中解释了这两种状态的含义，但是这两种状态的要点如下：

导入槽还不是节点哈希槽的一部分，正在进行迁移。仅当使用该ASK命令时，节点才会接受有关这些插槽的查询。
迁移槽已分配给该节点，但正在迁移到某个其他节点。如果命令中的所有键都已经存在，节点将接受查询，否则它将发出所谓的ASK 重定向，以强制直接在导入节点中创建新键。
导入和迁移插槽在CLUSTER NODES输出中发出，如下所示：
导入槽： [slot_number-←importing_from_node_id]
迁移槽： [slot_number→-migrating_to_node_id]
以下是导入和迁移槽的几个示例：
[93-←292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]
[1002-←67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1]
[77→-e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca]
[16311→-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]

请注意，该格式没有任何空格，因此CLUSTER NODES输出格式是纯 CSV 格式，即使发出此特殊插槽也有空格作为分隔符。然而，格式的完整解析器应该能够处理它们。

注意：

迁移和导入槽仅添加到标记为的节点myself。相对于节点的哈希槽，这是哈希槽所属节点的本地局部变量。
导入和迁移插槽作为附加信息提供。如果节点分配了给定的哈希槽，它也将是哈希槽列表中的一个普通数字，因此对哈希槽迁移一无所知的客户端可以跳过这个特殊字段。

返回值

批量字符串回复：序列化的集群配置。

CLUSTER REPLICAS

该命令提供从指定主节点复制的副本节点列表。该列表以CLUSTER NODES使用的相同格式提供（有关格式规范，请参阅其文档）。

根据接收命令的节点的节点表，如果指定节点未知或不是主节点，则该命令将失败。

请注意，如果从给定的主节点添加、移动或删除副本，并且我们向尚未收到配置更新的节点询问CLUSTER REPLICAS，它可能会显示陈旧信息。然而最终（如果没有网络分区，在几秒钟内）所有节点都会就与给定主节点关联的节点集达成一致。

CLUSTER REPLICATE

该命令将节点重新配置为指定主节点的副本。如果接收命令的节点是一个空的 master，作为命令的副作用，节点角色从 master 更改为 replica 。

一旦一个节点变成另一个主节点的副本，就不需要通知其他集群节点这个变化：节点之间交换的心跳包会自动传播新的配置。

副本将始终接受该命令，假设：

指定的节点 ID 存在于其节点表中。
指定的节点 ID 不标识我们将命令发送到的实例。
指定的节点 ID 是主节点。

如果接收命令的节点还不是副本，而是主节点，则命令只会成功，节点将转换为副本，前提是满足以下附加条件：

该节点不提供任何哈希槽。
节点为空，键空间中根本没有存储任何键。

如果命令成功，新副本将立即尝试联系其主节点以从中复制。

CLUSTER RESET

根据重置类型（可以是hard或soft ）以或多或少激烈的方式重置 Keybyte Cluster 节点。请注意，如果主节点持有一个或多个，则此命令不适用于主节点，在这种情况下，必须先删除主节点的key才能完全重置，例如首先使用FLUSHALL，然后使用CLUSTER RESET。

对节点的影响：

集群中的所有其他节点都被遗忘了。
所有分配的/开放的插槽都被重置，因此插槽到节点的映射被完全清除。
如果节点是副本，则它会变成（空）主节点。它的数据集被刷新，所以最后节点将是一个空的主节点。
仅硬重置：生成新的节点 ID。
仅硬重置：currentEpoch并且configEpoch变量设置为 0。
新配置将保留在节点集群配置文件中的磁盘上。

此命令主要用于重新配置 Keybyte 集群节点，以便在新的不同集群的上下文中使用。该命令还被 Keybyte 集群测试框架广泛使用，以便在每次执行新的测试单元时重置集群的状态。

如果未指定复位类型，则默认为soft。

CLUSTER SAVECONFIG

强制节点将nodes.conf配置保存在磁盘上。在返回命令调用之前，fsync(2)以确保配置已刷新到计算机磁盘上。

该命令主要用于nodes.conf节点状态文件由于某种原因丢失/删除的情况，我们想从头开始重新生成它。在通过CLUSTER命令对节点集群配置进行普通更改的情况下，它也很有用，以确保新配置保留在磁盘上，但是所有命令通常应该能够自动调度以在磁盘上保留配置时这样做对于系统在重新启动时的正确性很重要。

CLUSTER SET-CONFIG-EPOCH

此命令在新节点中设置特定的配置config epoch。它仅在以下情况下有效：

节点的节点表为空。
节点当前配置纪元(epoch)为零。

这些先决条件是必需的，因为通常手动更改节点的配置纪元(epoch)是不安全的，我们希望确保具有较高配置纪元(epoch)值的节点（即最后一个故障转移的节点）在声明哈希槽时胜过其他节点所有权。

但是，此规则有一个例外，即从头开始创建新集群时。Keybyte Cluster config epoch 冲突解决算法可以在启动时处理所有配置相同配置的新节点，但是这个过程很慢，应该是例外，只是为了确保无论发生什么，最终总是有两个节点远离状态具有相同的配置纪元(epoch)。

因此，使用CONFIG SET-CONFIG-EPOCH，当创建新集群时，我们可以在将集群加入到一起之前为每个节点分配不同的渐进式配置epoch。

CLUSTER SETSLOT

CLUSTER SETSLOT负责以不同的方式改变接收节点中哈希槽的状态。它可以，取决于使用的子命令：

MIGRATING子命令：设置一个处于迁移状态的哈希槽。
IMPORTING子命令：设置一个处于导入状态的哈希槽。
STABLE 子命令：清除哈希槽中的任何导入/迁移状态。
NODE 子命令：将哈希槽绑定到不同的节点。

该命令及其子命令集对于启动和结束集群实时重新分片操作非常有用，这些操作是通过在源节点中设置处于迁移状态的哈希槽并在目标节点中导入状态来完成的。

下面记录了每个子命令。最后，您将找到有关如何使用此命令和其他相关命令执行实时重新分片的说明。

用法

CLUSTER SETSLOT<slot>迁移<destination-node-id>

此子命令将插槽设置为迁移状态。为了在这种状态下设置一个槽，接收命令的节点必须是哈希槽的所有者，否则返回错误。

当插槽设置为迁移状态时，节点以下列方式改变行为：

如果收到有关现有key的命令，则照常处理该命令。
如果接收到有关不存在的键的命令ASK，节点将发出重定向，要求客户端仅重试该特定查询到destination-node. 在这种情况下，客户端不应更新其哈希槽到节点映射。
如果命令包含多个键，如果不存在，则行为与第 2 点相同，如果全部存在，则与第 1 点相同，但是如果只有部分键存在，则命令TRYAGAIN按顺序发出错误将感兴趣的key迁移到目标节点，以便执行multikeys命令。

集群SETSLOT<slot>导入<source-node-id>

此子命令是MIGRATING的反向操作，并准备目标节点从指定的源节点导入key。该命令仅在节点还不是指定哈希槽的所有者时才有效。

当插槽设置为导入状态时，节点以下列方式改变行为：

与此哈希槽有关的命令将被拒绝，并像MOVED往常一样生成重定向，但在命令跟随ASKING命令的情况下，在这种情况下执行命令。

这样，当处于迁移状态的节点产生ASK重定向时，客户端联系目标节点，发送ASKING，然后立即发送命令。这样，旧节点中不存在的key或者已经迁移到目标节点的key的命令在目标节点中执行，这样：

key总是在目标节点中创建。在哈希槽迁移期间，我们只需要移动key，而不是key。
在作为迁移目标的节点（即新的哈希槽所有者）的上下文中正确处理有关已迁移key的命令，以保证一致性。
没有ASKING行为与往常一样。这保证了具有损坏的哈希槽映射的客户端不会在目标节点中写入错误，从而创建尚未迁移的key的新版本。

集群SETSLOT<slot>稳定

此子命令只是从插槽清除迁移/导入状态。它主要用于修复陷入错误状态的集群redis-cli --cluster fix。通常，这两种状态会在迁移结束时使用SETSLOT … NODE …下一节中说明的子命令自动清除。

集群SETSLOT<slot>节点<node-id>

NODE子命令是具有最复杂语义的命令。它将哈希槽与指定节点相关联，但是该命令仅在特定情况下起作用，并且根据槽状态具有不同的副作用。以下是该命令的一组先决条件和副作用：

如果当前哈希槽的所有者是接收命令的节点，但为了命令的作用，槽将被分配给不同的节点，如果在接收命令的节点中仍然存在该哈希槽的键，则该命令将返回错误.
如果插槽处于迁移状态，则当插槽分配给另一个节点时，状态会被清除。
如果插槽在接收命令的节点中处于导入状态，并且命令将插槽分配给该节点（这发生在从一个节点到另一个节点的哈希插槽重新分片结束时的目标节点中），则该命令具有以下副作用： A)导入状态被清除。B) 如果节点配置纪元(epoch)还不是集群中最大的，它会生成一个新的配置纪元(epoch)并将新的配置纪元(epoch)分配给它自己。这样，它的新哈希槽所有权将胜过由以前的故障转移或槽迁移创建的任何过去的配置。

需要注意的是，第 3 步是 Keybyte 集群节点在没有其他节点同意的情况下创建新配置纪元(epoch)的唯一时间。这仅在操作手动配置时发生。然而，这不可能创建两个节点具有相同配置纪元(epoch)的非瞬态设置，因为 Keybyte 集群使用配置纪元(epoch)冲突解决算法。

CLUSTER SLAVES

如果不是为了向后兼容，Keybyte 项目不再使用 slave。请使用新命令CLUSTER REPLICAS。命令SLAVEOF将继续工作以实现向后兼容性。

该命令提供从指定主节点复制的副本节点列表。该列表以CLUSTER NODES使用的相同格式提供（有关格式规范，请参阅其文档）。

根据接收命令的节点的节点表，如果指定节点未知或不是主节点，则该命令将失败。

请注意，如果从给定的主节点添加、移动或删除副本，并且我们向尚未收到配置更新的节点询问CLUSTER SLAVES，它可能会显示陈旧信息。然而最终（如果没有网络分区，在几秒钟内）所有节点都会就与给定主节点关联的节点集达成一致。

返回值
该命令以与CLUSTER NODES相同的格式返回数据。

CLUSTER SLOTS

CLUSTER SLOTS返回有关哪些集群插槽映射到哪些 Keybyte 实例的详细信息。该命令适合由 Keybyte 集群客户端库实现使用，以便检索（或在收到重定向时更新）将集群哈希槽与实际节点网络坐标（由 IP 地址和 TCP 端口组成）相关联的映射，因此当收到命令时，它可以发送到命令中指定的键的可能正确实例。

嵌套结果数组

每个嵌套结果是：

起始槽范围
结束槽范围
插槽范围的主节点表示为嵌套的 IP/端口数组
插槽范围的主副本的第一个副本
第二个副本
…继续，直到返回此主服务器的所有副本。

每个结果都包括列出的插槽范围内主实例的所有活动副本。不返回失败的副本。

第三个嵌套回复保证是插槽范围的主实例的 IP/端口对。第三个嵌套回复之后的所有 IP/端口对都是主服务器的副本。

如果集群实例具有不连续的插槽（例如 1-400,900,1800-6000），那么对于每个顶级插槽范围回复，主和副本 IP/端口结果将被复制。

警告：对于每个 Keybyte 实例，较新版本的 Keybyte Cluster 不仅会输出 IP 和端口，还会输出节点 ID 作为数组的第三个元素。在未来的版本中，可能会有更多元素更好地描述节点。通常，客户端实现应仅依赖于某些参数位于指定的固定位置这一事实，但可能会跟随更多参数并应忽略。同样，如果可能，客户端库应该尝试处理旧版本可能只有 IP 和端口参数的事实。

返回值
Array reply:有IP/端口映射的槽位范围的嵌套列表。

READONLY

启用读取查询以连接到 Keybyte 集群副本节点。

通常副本节点会将客户端重定向到给定命令中涉及的哈希槽的权威主节点，但是客户端可以使用副本来使用READONLY命令扩展读取。

READONLY告诉 Keybyte Cluster 副本节点客户端愿意读取可能过时的数据并且对运行写入查询不感兴趣。

当连接处于只读模式时，仅当操作涉及副本的主节点未提供的key时，集群才会向客户端发送重定向。这可能是因为：

客户端发送了一个关于这个副本的主节点从未服务过的哈希槽的命令。
集群被重新配置（例如重新分片），副本不再能够为给定的哈希槽提供命令。

READWRITE

禁用读取查询的到的Keybyte集群从属节点的连接。

阅读对一个集群的Keybyte从节点查询默认被禁用，但是你可以使用READONLY命令改变以每个连接的基础上此行为。的READWRITE命令重置的连接回为读写的只读模式标志

Connection

AUTH

AUTH 命令在两种情况下对当前连接进行身份验证：

如果 Keybyte 服务器通过该requirepass选项受密码保护。
实例使用Keybyte ACL 系统。

AUTH <password>

此表单仅根据设置的密码进行身份验证requirepass。在此配置中，Keybyte 将拒绝刚刚连接的客户端执行的任何命令，除非连接通过AUTH进行身份验证。

如果通过 AUTH 提供的密码与配置文件中的密码匹配，则服务器回复OK状态码并开始接受命令。否则，返回错误并且客户端需要尝试新密码。

使用 Keybyte ACL 时，应以扩展方式给出命令：

AUTH <username> <password>

为了使用 ACL 列表中定义的连接之一来验证当前连接（请参阅ACL SETUSER）和官方ACL 指南以获取更多信息。

使用 ACL 时，命令的单参数形式（仅指定密码）假定隐式用户名是“default”。

安全须知

由于Keybyte的高性能特性，可以在很短的时间内并行尝试大量密码，因此请确保生成一个强大且很长的密码，这样这种攻击是不可行的。生成强密码的一个好方法是通过ACL GENPASS命令。

CLIENT CACHING

当在OPTIN或OPTOUT模式下启用跟踪时，此命令控制连接执行的下一个命令中的键的跟踪。

当启用跟踪 Keybyte 时，使用CLIENT TRACKING命令，可以指定OPTIN或OPTOUT选项，以便服务器不会自动记住只读命令中的键以便稍后失效。当我们处于OPTIN模式时，我们可以通过在下一个命令CLIENT CACHING yes 之前立即调用来启用对下一个命令中的键的跟踪。类似地，当我们处于OPTOUTmode 并且键被正常跟踪时，我们可以避免使用下一个命令中的键被跟踪CLIENT CACHING no。

基本上，该命令在连接中设置一个状态，该状态仅对下一个命令执行有效，这将修改客户端跟踪的行为。

CLIENT GETNAME

返回当前连接作为集的名称CLIENT SETNAME。由于每个新连接开始时都没有关联的名称，如果没有分配名称，则返回空批量回复。

返回值
批量字符串应答:连接名称，如果没有设置名称，则为空批量应答。

CLIENT GETREDIR

此命令返回我们将跟踪通知重定向到的客户端 ID 。当使用CLIENT TRACKING启用跟踪时，我们设置了一个要重定向到的客户端。然而，为了避免强制客户端库实现记住 ID 通知被重定向到，此命令存在是为了改进自省并允许客户端稍后检查重定向是否处于活动状态以及重定向到哪个客户端 ID。

返回值
整数应答:我们将通知重定向到的客户端的ID。如果没有启用客户端跟踪，该命令返回-1，如果启用客户端跟踪，但我们没有将通知重定向到任何客户端，则返回0。

CLIENT ID

该命令仅返回当前连接的 ID。每个连接 ID 都有一定的保证：

它永远不会重复，所以如果CLIENT ID返回相同的数字，调用者可以确定底层客户端没有断开并重新连接连接，但它仍然是相同的连接。
ID 是单调递增的。如果一个连接的 ID 大于另一个连接的 ID，则保证稍后与服务器建立第二个连接。

此命令与CLIENT UNBLOCK一起使用特别有用。检查CLIENT UNBLOCK命令页面以获取涉及这两个命令的模式。

返回值

整数回复

客户端的 ID。

CLIENT INFO

该命令以大多数人类可读的格式返回有关当前客户端连接的信息和统计信息。

回复格式与CLIENT LIST相同，内容仅包含当前客户端的信息。

返回值

批量字符串回复：当前客户端的唯一字符串，如CLIENT LIST页面所述。

CLIENT KILL

该命令关闭一个给定的客户端连接。该命令支持两种格式，旧格式：

CLIENT KILL addr: port

在ip:port应该与由所述返回的线客户端列表命令（addr字段）。

新格式：

CLIENT KILL <filter> <value> … … <filter> <value>

使用新形式，可以通过不同的属性来关闭客户端，而不是仅仅通过地址来关闭客户端。以下过滤器可用：

CLIENT KILL ADDR ip: port. 这与旧的三参数行为完全相同。
CLIENT KILL LADDR ip: port. 关闭所有连接到指定本地（绑定）地址的客户端。
CLIENT KILL ID client-id. 允许通过其独特的ID字段关闭客户端。客户端ID的使用所检索的客户端列表命令。
CLIENT KILL TYPE type，其中类型是之一normal，master，replica和pubsub。这将关闭指定类中所有客户端的连接。请注意，阻止进入MONITOR命令的客户端被视为属于normal类。
CLIENT KILL USER username. 关闭所有使用指定ACL用户名进行身份验证的连接，但如果用户名未映射到现有 ACL 用户，则返回错误。
CLIENT KILL SKIPME yes/no. 默认情况下，此选项设置为yes，即调用命令的客户端不会被关闭，但设置此选项no将具有同时关闭调用命令的客户端的效果。

可以同时提供多个过滤器。该命令将通过逻辑 AND 处理多个过滤器。例如：

CLIENT KILL addr 127.0.0.1:12345 type pubsub

是有效的，并且只会关闭具有指定地址的 pubsub 客户端。这种包含多个过滤器的格式目前很少有用。

当使用新表单时，该命令不再返回OK或返回错误，而是返回被关闭客户端的数量，这可能为零。

CLIENT KILL 和 Keybyte Sentinel

Keybyte Sentinel 的最新版本使用 CLIENT KILL 以在重新配置实例时终止客户端，以强制客户端再次与一个 Sentinel 执行握手并更新其配置。

笔记

由于 Keybyte 的单线程特性，在执行命令时无法终止客户端连接。从客户端的角度来看，连接永远不会在命令执行过程中关闭。但是，只有在发送下一个命令（并导致网络错误）时，客户端才会注意到连接已关闭。

返回值

当使用三个参数格式调用时：

简单字符串回复：返回OK如果连接存在且已关闭

当使用过滤器/值格式调用时：

整数回复：被关闭的客户端数量。

CLIENT LIST

该命令返回的信息和统计信息的大多是人类可读的格式的客户端连接服务器。

您可以使用可选子命令之一来过滤列表。该TYPE type子滤波器由客户的类型，其中该列表类型是一个normal，master，replica，和pubsub。请注意，被MONITOR命令阻止的客户端属于normal该类。

该ID过滤器只返回匹配的ID为客户输入client-id的参数。

CLIENT PAUSE

CLIENT PAUSE是一个连接控制命令，能够在指定的时间量（以毫秒为单位）暂停所有 Keybyte 客户端。

该命令执行以下操作：

它停止处理给定模式下来自普通客户端和发布/订阅客户端的所有待处理命令。但是，与副本的交互将继续正常进行。请注意，客户端在尝试执行命令时会正式暂停，因此服务器端不会对非活动客户端进行任何工作。
但是它会尽快向调用者返回 OK，因此CLIENT PAUSE命令的执行不会自行暂停。
当指定的时间段过去后，所有客户端都将被解除阻塞：这将触发暂停期间每个客户端的查询缓冲区中累积的所有命令的处理。
客户端暂停目前支持两种模式：
ALL: 这是默认模式。所有客户端命令都被阻止。
WRITE: 客户端只有在尝试执行写入命令时才会被阻止。

对于WRITE模式，一些命令有特殊行为：

EVA* / EVALSHA：将阻止所有脚本的客户端。
PUBLISH：将阻止客户端。
PFCOUNT：将阻止客户端。
WAIT：确认将被延迟，因此该命令将被阻止。
此命令很有用，因为它可以以受控方式将客户端从 Keybyte 实例切换到另一个实例。例如，在实例升级期间，系统管理员可以执行以下操作：
使用CLIENT PAUSE暂停
等待几秒钟以确保副本处理了来自主服务器的最新复制流。
将其中一个副本变成主副本。
重新配置客户端以连接新的主节点。

推荐的客户端暂停模式是WRITE. 此模式将停止所有复制流量，可以使用CLIENT UNPAUSE命令中止，并允许重新配置旧主服务器而不会冒故障转移后接受写入的风险。这也是集群故障转移期间使用的模式。

可以在 MULTI/EXEC 块中与命令一起发送CLIENT PAUSEINFO replication，以便在客户端被阻塞时获取当前主偏移量。这样就可以在副本端等待一个特定的偏移量，以确保所有的复制流都被处理。

此命令还可以防止在客户端暂停期间key被逐出或过期。这样，不仅从客户端无法写入的角度来看，而且从内部操作的角度来看，数据集都可以保证是静态的。

返回值

简单字符串回复：如果超时无效，该命令返回 OK 或错误。

CLIENT REPLY

有时，客户端完全禁用来自 Keybyte 服务器的回复可能很有用。例如，当客户端发送即发即弃命令或执行大量数据加载时，或在不断流式传输新数据的缓存上下文中。在这种情况下，使用服务器时间和带宽来向客户端发回将被忽略的回复被认为是浪费。

该命令控制服务器是否会回复客户端的命令。可以使用以下模式：

ON. 这是服务器对每个命令返回回复的默认模式。
OFF. 在这种模式下，服务器不会回复客户端命令。
SKIP. 此模式会立即跳过命令的回复。

返回值

当用OFF或SKIP子命令调用时，不会作出应答。当调用ON时:
简单的字符串回答:好的。

CLIENT SETNAME

该命令指定一个名称为当前连接。

分配的名称显示在CLIENT LIST的输出中，以便可以识别执行给定连接的客户端。

例如，当使用 Keybyte 来实现队列时，消息的生产者和消费者可能希望根据他们的角色设置连接的名称。

如果不是 Keybyte 字符串类型的通常限制 (512 MB)，则可以分配的名称长度没有限制。但是，不能在连接名称中使用空格，因为这会违反CLIENT LIST回复的格式。

可以完全删除连接名称，将其设置为空字符串，这不是有效的连接名称，因为它用于此特定目的。

可以使用CLIENT GETNAME检查连接名称。

每个新连接都在没有指定名称的情况下启动。

提示：为连接设置名称是调试由于使用 Keybyte 的应用程序中的错误导致的连接泄漏的好方法。
返回值

简单字符串回复：如果连接名称设置成功返回值为OK。

CLIENT TRACKING

此命令启用 Keybyte 服务器的跟踪功能，用于服务器辅助客户端缓存。

启用跟踪后，Keybyte 会记住连接请求的键，以便在修改这些键时发送失效消息。无效消息在同一连接中发送（仅在使用 RESP3 协议时可用）或在不同连接中重定向（也可用于 RESP2 和 Pub/Sub）。一种特殊的广播模式是可用的，在这种模式下，参与此协议的客户端会收到每个订阅给定key前缀的通知，而不管他们请求的是什么key。

要启用跟踪，请使用：

CLIENT TRACKING on … options …

该功能将在其整个生命周期中在当前连接中保持活动状态，除非CLIENT TRACKING off在某个时刻打开跟踪。

以下是在启用跟踪时修改命令行为的选项列表：

REDIRECT <id>: 向具有指定 ID 的连接发送失效消息。连接必须存在。您可以使用CLIENT ID获取连接的ID。如果我们重定向到的连接被终止，当处于 RESP3 模式时，启用跟踪的连接将接收tracking-redir-broken推送消息，以便通知条件。
BCAST: 在广播模式下启用跟踪。在此模式下，会针对所有指定的前缀报告失效消息，而不管连接请求的key如何。相反，当广播模式未启用时，Keybyte 将使用只读命令跟踪获取了哪些键，并且只会报告此类键的失效消息。
PREFIX <prefix>: 对于广播，注册一个给定的键前缀，以便只为以该字符串开头的键提供通知。可以多次给出此选项以注册多个前缀。如果在没有此选项的情况下启用广播，Keybyte 将为每个键发送通知。您不能删除单个前缀，但可以通过禁用和重新启用跟踪来删除所有前缀。使用此选项会增加O(N ²⁾的额外时间复杂度^，其中 N 是跟踪的前缀总数。
OPTIN：当广播未激活时，通常不跟踪只读命令中的键，除非在CLIENT CACHING yes命令后立即调用它们。
OPTOUT：当广播未激活时，通常在只读命令中跟踪键，除非在CLIENT CACHING no命令后立即调用它们。
NOLOOP：不要发送有关此连接本身修改的key的通知。

返回值
简单字符串回复:如果连接被成功地放入跟踪模式或如果跟踪模式被成功地禁用，则OK。否则返回一个错误。

CLIENT TRACKINGINFO

该命令返回有关当前客户端连接使用服务器辅助客户端缓存功能的信息。

返回值

数组回复：跟踪信息部分及其各自值的列表，具体为：

flags：连接使用的跟踪标志列表。标志及其含义如下：
- off：连接未使用服务器辅助客户端缓存。
- on：为连接启用服务器辅助客户端缓存。
- bcast: 客户端使用广播模式。
- optin: 默认情况下，客户端不缓存key。
- optout：客户端默认缓存key。
- caching-yes:下一个命令将缓存key（仅与optin一起存在）。
- caching-no：下一个命令不会缓存key（仅与optout一起存在）。
- noloop：客户端不会收到自己修改的key的通知。
- broken_redirect：用于重定向的客户端 ID 不再有效。
redirect：用于通知重定向的客户端 ID，如果没有，则为 -1。
prefixes：向客户端发送通知的键前缀列表。

CLIENT UNBLOCK

此命令可以从不同的连接解除阻止在阻塞操作中阻塞的客户端，例如BRPOP或XREAD或WAIT。

默认情况下，客户端会像达到命令的超时时间一样解除阻塞，但是如果传递了附加（和可选）参数，则可以指定解除阻塞行为，可以是TIMEOUT（默认值）或ERROR。如果指定了ERROR，则行为是解除对客户端的阻止，将客户端被强制解除阻止的事实作为错误返回。具体客户端会收到如下错误：

-UNBLOCKED client unblocked via CLIENT UNBLOCK

注意：当然，通常不保证错误文本保持不变，但错误代码将保持不变-UNBLOCKED。

这个命令，在仅能使用较少连接但要监控大量keys的时候特别有用。例如，我们可能希望在不使用超过 N 个连接的情况下使用XREAD监视多个流。然而，在某一时刻，消费者进程被告知还有一个流key需要监控。为了避免使用更多连接，最好的行为是停止来自池中一个连接的阻塞命令，添加key，然后再次发出阻塞命令。

要获得此行为，请使用以下模式。该进程使用额外的控制连接，以便在需要时发送CLIENT UNBLOCK命令。同时，在对其他连接运行阻塞操作之前，该进程会运行CLIENT ID以获取与该连接关联的 ID。当应添加key或不再监视key时，通过在控制连接中发送CLIENT UNBLOCK来中止相关的连接阻止命令。阻塞命令将返回并最终可以重新发出。

此示例显示了 Keybyte streams上下文中的应用程序，但该模式是通用模式，可以应用于其他情况。

Connection A (blocking connection):

> CLIENT ID

2934

> BRPOP key1 key2 key3 0

(client is blocked)

... Now we want to add a new key ...

Connection B (control connection):

> CLIENT UNBLOCK 2934

1

Connection A (blocking connection):

... BRPOP reply with timeout ...

NULL

> BRPOP key1 key2 key3 key4 0

(client is blocked again)

返回值

整数回复：

回复1，则客户端成功解锁。
回复0，则客户端没有被解锁。

CLIENT UNPAUSE

CLIENT UNPAUSE用于恢复所有被CLIENT PAUSE暂停的客户端的命令处理。

返回值

简单字符串回复：命令返回OK

ECHO

返回消息。

返回值

批量字符串回复

例子

redis> ECHO "Hello World!"

"Hello World!"



redis>

HELLO

切换到不同的协议，可选择验证和设置连接的名称，或提供上下文客户端报告。

Keybyte 支持两种协议：旧协议 RESP2 和引入的新协议 RESP3。RESP3 有一定的优势，因为当连接处于这种模式时，Keybyte 能够回复更多的语义回复：例如，HGETALL将返回一个映射类型，因此客户端库实现不再需要提前知道将数组转换为将其返回给调用者之前的哈希值。

在 Keybyte 中，连接以 RESP2 模式启动，因此实现 RESP2 的客户端不需要更新或更改。虽然未来版本可能默认为 RESP3，但短期内没有放弃对 RESP2 的支持的计划。

HELLO总是回复当前服务器和连接属性的列表，例如：版本、加载的模块、客户端 ID、复制角色等。在 Keybyte 中不带任何参数调用并且默认使用 RESP2 协议时，回复如下所示：

> HELLO

 1) "server"

 2) "redis"

 3) "version"

 4) "255.255.255"

 5) "proto"

 6) (integer) 2

 7) "id"

 8) (integer) 5

 9) "mode"

10) "standalone"

11) "role"

12) "master"

13) "modules"

14) (empty array)

想要使用 RESP3 模式握手的客户端需要调用HELLO 命令并指定值“3”作为protover参数，如下所示：

> HELLO 3

1# "server" => "redis"

2# "version" => "6.0.0"

3# "proto" => (integer) 3

4# "id" => (integer) 10

5# "mode" => "standalone"

6# "role" => "master"

7# "modules" => (empty array)

因为HELLO回复了有用的信息，并且考虑到它protover是可选的或可以设置为“2”，客户端库作者可能会在设置连接时考虑使用此命令而不是规范的PING。

当使用可选protover参数调用时，此命令将协议切换到指定版本并接受以下选项：

AUTH <username> <password>: 除了切换到指定的协议版本外，还直接验证连接。这使得在建立新连接时不需要在HELLO之前调用AUTH。请注意，可以将username设置为“defult”以针对不使用 ACL 的服务器进行身份验证，而是使用更简单的 Keybyte 之前的机制。
SETNAME <clientname>：这相当于调用CLIENT SETNAME。

返回值

数组回复：服务器属性列表。选择 RESP3 时，回复是map而不是array。如果protover请求的请求不存在，该命令将返回错误。

PING

如果没有提供参数，那么返回值为pong，否则返回参数的副本作为一个块。此命令通常用于测试连接是否仍然有效，或测量延迟。

如果客户端订阅了频道或模式，它将改为返回第一个位置为“pong”而第二个位置为空(empty bulk)，除非提供了实参（argument），在这种情况下它返回一个副本实参(argument)。

返回值

简单的字符串回复

例子

redis> **PING**

"PONG"

redis> **PING "hello world"**

"hello world"



redis>

QUIT

要求服务器关闭连接。一旦所有待处理的回复都写入客户端，连接就会关闭。

返回值

简单的字符串回复：always OK.

RESET

此命令执行连接的服务器端上下文的完全重置，模拟断开连接并再次重新连接的效果。

当从常规客户端连接调用该命令时，它会执行以下操作：

如果存在，则丢弃当前的MULTI事务块。
取消监视WATCH连接的所有键。
禁用CLIENT TRACKING，如果正在使用。
将连接设置为READWRITE模式。
取消连接的ASKING模式（如果之前设置）。
将客户端回复设置为ON.
将协议版本设置为 RESP2。
SELECTs 数据库 0。
适用时退出MONITOR模式。
在适当的时候中止 Pub/Sub 的订阅状态（SUBSCRIBE和PSUBSCRIBE）。
取消验证连接，当启用验证时需要调用AUTH重新验证。

返回值

简单的字符串回复：总是“RESET”。

SELECT

选择具有指定的从零开始的数字索引的 Keybyte 逻辑数据库。新连接始终使用数据库 0。

可选的 Keybyte 数据库是一种命名空间形式：所有数据库仍然保存在同一个 KDB/AOF 文件中。但是，不同的数据库可以具有相同名称的键，并且诸如FLUSHDB、SWAPDB或RANDOMKEY 之类的命令适用于特定数据库。

实际上，Keybyte 数据库应该用于分隔属于同一应用程序的不同键（如果需要），而不是将单个 Keybyte 实例用于多个不相关的应用程序。

使用Keybyte Cluster时，不能使用SELECT命令，因为Keybyte Cluster只支持零数据库。在 Keybyte 集群的情况下，拥有多个数据库将毫无用处，并且是不必要的复杂性来源。对于 Keybyte 集群设计和目标，在单个数据库上原子操作的命令是不可能的。

由于当前选择的数据库是连接的一个属性，客户端应该跟踪当前选择的数据库并在重新连接时重新选择它。虽然没有命令可以查询当前连接中选定的数据库，但CLIENT LIST输出显示每个客户端当前选定的数据库。

返回值

简单的字符串回复

Geo

GEOADD

将指定的地理空间项（经度、纬度、名称）添加到指定的键。数据作为排序集存储在键中，这样就可以使用GEOSEARCH命令查询项目。

该命令采用标准格式 x,y 的参数，因此必须在纬度之前指定经度。可编入索引的坐标有限制：非常靠近极点的区域不可编入索引。

EPSG: 900913 / EPSG: 3785 / OSGEO: 41001 指定的确切限制如下：

有效经度为 -180 到 180 度。
有效纬度是从 -85.05112878 到 85.05112878 度。

当用户尝试索引指定范围之外的坐标时，该命令将报告错误。

注意：没有GEODEL命令，因为您可以使用ZREM删除元素。地理索引结构只是一个排序集。

GEOADD 用法

GEOADD 选项

GEOADD还提供以下选项：

XX : 只更新已经存在的元素。永远不要添加元素。
NX：不要更新已经存在的元素。始终添加新元素。
CH：修改返回值，从新增元素的数量，到变化的元素总数（CH是changed的缩写）。更改的元素是添加的新元素和已更新坐标的现有元素。因此，命令行中指定的具有与过去相同分数的元素不计算在内。注意：通常情况下，GEOADD的返回值只计算新增元素的数量。

注意：XX和NX选项是互斥的。

它是如何工作的？

填充排序集的方式是使用一种称为Geohash的技术。纬度和经度位交错以形成唯一的 52 位整数。我们知道一个有序集合双分可以表示一个 52 位的整数而不会损失精度。

这种格式允许通过检查覆盖整个形状所需的 1+8 区域并丢弃其外部的元素来查询边界框和半径。通过计算所覆盖的框的范围，从排序集分数的不太重要的部分中去除足够的位，并计算每个区域在排序集中查询的分数范围来检查区域。

它使用什么地球模型？

该模型假设地球是一个球体，因为它使用Haversine 公式来计算距离。当应用于地球时，这个公式只是一个近似值，地球不是一个完美的球体。例如，当使用社交网络和需要此类查询的类似应用程序时，引入的错误不是问题。但是，在最坏的情况下，错误可能高达 0.5%，因此对于错误关键应用程序，您可能需要考虑其他系统。

返回值

整数回复，特别是：

在不带可选参数的情况下使用时，添加到排序集中的元素数（不包括分数更新）。
如果CH指定了该选项，则更改（添加或更新）的元素数。

例子

redis> **GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"**

(integer) 2

redis> GEODIST Sicily Palermo Catania

"166274.1516"

redis> GEORADIUS Sicily 15 37 100 km

{empty}1) "Catania"

redis> GEORADIUS Sicily 15 37 200 km

{empty}1) "Palermo"

{empty}2) "Catania"



redis>

GEODIST

返回由排序集表示的地理空间索引中两个成员之间的距离。

给定一个表示地理空间索引的排序集，使用GEOADD命令填充，该命令返回指定单位中两个指定成员之间的距离。

如果缺少一个或两个成员，则该命令返回 NULL。

单位必须是以下之一，默认为米：

m为米。
km为公里。
mi数英里。
ft为英尺。

假设地球是一个完美的球体来计算距离，因此在边缘情况下可能会出现高达 0.5% 的误差。

返回值

批量字符串回复，特别是：

该命令以指定单位的双精度值（表示为字符串）形式返回距离，如果缺少一个或两个元素，则返回 NULL。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEODIST Sicily Palermo Catania

"166274.1516"

redis> GEODIST Sicily Palermo Catania km

"166.2742"

redis> GEODIST Sicily Palermo Catania mi

"103.3182"

redis> GEODIST Sicily Foo Bar

(nil)



redis>

GEOHASH

返回有效的Geohash字符串，表示一个或多个元素在表示地理空间索引的排序集合值中的位置（其中元素是使用GEOADD添加的）。

通常 Keybyte 使用 Geohash 技术的变体表示元素的位置，其中位置使用 52 位整数进行编码。与标准相比，编码也不同，因为在编码和解码过程中使用的初始最小和最大坐标不同。但是，此命令以Wikipedia 文章中所述的字符串形式返回标准 Geohash，并与geohash.org网站兼容。

Geohash 字符串属性

该命令返回 11 个字符的 Geohash 字符串，因此与 Keybyte 内部 52 位表示相比没有精度损失。返回的 Geohashes 具有以下属性：

它们可以缩短从右边删除字符。它会失去精度，但仍会指向同一区域。
可以在geohash.orgURL 中使用它们，例如http://geohash.org/<geohash-string>. 这是此类 URL的示例。
具有相似前缀的字符串在附近，但反之则不然，具有不同前缀的字符串也可能在附近。

返回值

数组回复，具体如下：

该命令返回一个数组，其中每个元素是与作为参数传递给命令的每个成员名称相对应的 Geohash。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEOHASH Sicily Palermo Catania

{empty}1) "sqc8b49rny0"

{empty}2) "sqdtr74hyu0"



redis>

GEOPOS

返回由key处的排序集表示的地理空间索引的所有指定成员的位置（经度、纬度）。

给定一个表示地理空间索引的排序集合，使用GEOADD命令填充，获取指定成员的坐标通常很有用。当通过GEOADD填充地理空间索引时，坐标被转换为 52 位 geohash，因此返回的坐标可能不完全是用于添加元素的坐标，但可能会引入小错误。

该命令可以接受可变数量的参数，因此即使指定了单个元素，它也始终返回一个位置数组。

返回值

数组回复，具体如下：

该命令返回一个数组，其中每个元素都是一个两元素数组，表示作为参数传递给命令的每个成员名称的经度和纬度 (x,y)。

不存在的元素被报告为数组的 NULL 元素。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEOPOS Sicily Palermo Catania NonExisting

{empty}1) 1) "13.36138933897018433"

   2) "38.11555639549629859"

{empty}2) 1) "15.08726745843887329"

   2) "37.50266842333162032"

{empty}3) (nil)



redis>

GEORADIUS

使用GEOADD返回填充了地理空间信息的排序集合的成员，这些成员位于由中心位置和距中心的最大距离（半径）指定的区域的边界内。

GEORADIUS 命令系列被视为已弃用。请在新代码中选择GEOSEARCH和GEOSEARCHSTORE。

用法

此命令的常见用例是检索指定点附近不超过给定米数（或其他单位）的地理空间项目。例如，这允许向移动用户推荐附近地点的应用程序。

半径以下列单位之一指定：

m为米。
km为公里。
mi数英里。
ft为英尺。

该命令可选地使用以下选项返回附加信息：

WITHDIST: 同时返回返回的物品与指定中心的距离。距离以与命令的半径参数指定的单位相同的单位返回。
WITHCOORD: 同时返回匹配项的经纬度坐标。
WITHHASH: 还以 52 位无符号整数的形式返回项目的原始 geohash 编码的排序集分数。这仅对低级黑客或调试有用，否则一般用户几乎没有兴趣。
命令默认是返回未排序的项目。可以使用以下两个选项调用两种不同的排序方法：
ASC：相对于中心，从最近到最远对返回的项目进行排序。
DESC：相对于中心，从最远到最近对返回的项目进行排序。

默认情况下，返回所有匹配项。可以使用[.16]COUNT<count>选项将结果限制为前 N 个匹配项。当ANY提供时，一旦找到足够的匹配项，命令就会返回，因此结果可能不是最接近指定点的结果，但另一方面，服务器投入的工作量显着降低。如果ANY没有提供，该命令将执行的努力是成正比的匹配指定区域和整理他们的项目数量，所以查询非常大的领域，以非常小的COUNT选项可能会很慢，即使返回短短结果。

默认情况下，该命令将项目返回给客户端。可以使用以下选项之一存储结果：

STORE：将项目存储在填充了其地理空间信息的排序集中。
STOKeybyteT：将项目存储在一个排序的集合中，以它们到中心的距离作为浮点数，以半径中指定的相同单位填充。

返回值

数组回复，具体如下：

没有WITH指定任何选项，该命令只返回一个线性数组，如 ["New York","Milan","Paris"]。
如果指定WITHCOORD,WITHDIST或WITHHASHoptions ，则该命令返回一个数组(array)，其中每个子数组代表一个项目。

当附加信息作为每个项目的数组返回时，子数组中的第一个项目始终是返回项目的名称。其他信息按以下顺序作为子数组的连续元素返回。

与中心的距离作为浮点数，与半径中指定的单位相同。
geohash 整数。
坐标作为两个项目 x,y 数组（经度，纬度）。

例如，该命令GEORADIUS Sicily 15 37 200 km WITHCOORD WITHDIST将以以下方式返回每个项目：

["Palermo","190.4424",["13.361389338970184","38.115556395496299"]]

只读变体

由于GEORADIUS和GEORADIUSBYMEMBER有一个STOREandSTOREDIST选项，它们在技术上被标记为 Keybyte 命令表中的写入命令。因此，只读副本会标记它们，即使连接处于只读模式，Keybyte 集群副本也会将它们重定向到主实例。它们与原始命令完全相同，但拒绝STORE和STOREDIST选项。这两个变体称为GEORADIUS_RO和GEORADIUSBYMEMBER_RO，可以安全地用于副本中。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEORADIUS Sicily 15 37 200 km WITHDIST

{empty}1) 1) "Palermo"

   2) "190.4424"

{empty}2) 1) "Catania"

   2) "56.4413"

redis> GEORADIUS Sicily 15 37 200 km WITHCOORD

{empty}1) 1) "Palermo"

   2) 1) "13.36138933897018433"

      2) "38.11555639549629859"

{empty}2) 1) "Catania"

   2) 1) "15.08726745843887329"

      2) "37.50266842333162032"

redis> GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD

{empty}1) 1) "Palermo"

   2) "190.4424"

   3) 1) "13.36138933897018433"

      2) "38.11555639549629859"

{empty}2) 1) "Catania"

   2) "56.4413"

   3) 1) "15.08726745843887329"

      2) "37.50266842333162032"



redis>

GEOREAIUSBYMEMBER

该命令与GEORADIUS完全相同，唯一不同的是，它不以经纬度值作为要查询的区域的中心，而是以排序集表示的地理空间索引中已经存在的成员的名称。

由于目前GEORADIUS 命令系列被视为已弃用。请在新代码中选择GEOSEARCH和GEOSEARCHSTORE。

指定成员的位置用作查询的中心。

请查看下面的示例和GEORADIUS文档以获取有关该命令及其选项的更多信息。

例子

redis> GEOADD Sicily 13.583333 37.316667 "Agrigento"

(integer) 1

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEORADIUSBYMEMBER Sicily Agrigento 100 km

{empty}1) "Agrigento"

{empty}2) "Palermo"



redis>

GEOSEARCH

使用GEOADD返回填充了地理空间信息的排序集合的成员，这些成员位于给定形状指定的区域的边界内。该命令扩展了GEORADIUS命令，因此除了在圆形区域内搜索外，它还支持在矩形区域内搜索。

应使用此命令代替已弃用的GEORADIUS和GEORADIUSBYMEMBER命令。

查询的中心点由以下强制性选项之一提供：

FROMMEMBER: 使用给定存<member>在于排序集中的位置。
FROMLONLAT: 使用给定的<longitude>和<latitude>位置。
查询的形状由以下强制性选项之一提供：
BYRADIUS: 类似于GEORADIUS，根据给定的在圆形区域内搜索<radius>。
BYBOX：在轴对齐的矩形内搜索，由<height>和确定<width>。
该命令可选地使用以下选项返回附加信息：
WITHDIST: 同时返回返回的物品到指定中心点的距离。距离以与为半径或高度和宽度参数指定的相同单位返回。
WITHCOORD: 同时返回匹配项的经纬度。
WITHHASH: 还以 52 位无符号整数的形式返回项目的原始 geohash 编码的排序集分数。这仅对低级黑客或调试有用，否则一般用户几乎没有兴趣。
匹配项默认返回未排序。要对它们进行排序，请使用以下两个选项之一：
ASC：相对于中心点，从最近到最远对返回的项目进行排序。
DESC：相对于中心点，从最远到最近对返回的项目进行排序。

默认返回所有匹配项。要将结果限制为前 N 个匹配项，请使用COUNT<count>选项。使用该ANY选项时，一旦找到足够的匹配项，该命令就会返回。这意味着返回的结果可能不是最接近指定点的结果，但服务器为生成它们所投入的努力要少得多。如果ANY没有提供，该命令将执行的努力是成正比的匹配指定区域和整理他们的项目数量，所以查询非常大的领域，以非常小的COUNT选项可能会很慢，即使返回短短结果。

返回值

数组回复，具体如下：

没有WITH指定任何选项，该命令只返回一个线性数组，如 ["New York","Milan","Paris"]。
如果指定WITHCOORD,WITHDIST或WITHHASHoptions ，则该命令返回一个数组数组，其中每个子数组代表一个项目。

当附加信息作为每个项目的数组返回时，子数组中的第一个项目始终是返回项目的名称。其他信息按以下顺序作为子数组的连续元素返回。

与中心的距离作为浮点数，与形状中指定的单位相同。
geohash 整数。
坐标作为两个项目 x,y 数组（经度，纬度）。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269
37.502669 "Catania"

(integer) 2

redis> GEOADD Sicily 12.758489 38.788135 "edge1" 17.241510 38.788135
"edge2"

(integer) 2

redis> GEOSEARCH Sicily FROMLONLAT 15 37 BYRADIUS 200 km ASC

{empty}1) "Catania"

{empty}2) "Palermo"

redis> GEOSEARCH Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC
WITHCOORD WITHDIST

{empty}1) 1) "Catania"

   2) "56.4413"

   3) 1) "15.08726745843887329"

      2) "37.50266842333162032"

{empty}2) 1) "Palermo"

   2) "190.4424"

   3) 1) "13.36138933897018433"

      2) "38.11555639549629859"

{empty}3) 1) "edge2"

   2) "279.7403"

   3) 1) "17.24151045083999634"

      2) "38.78813451624225195"

{empty}4) 1) "edge1"

   2) "279.7405"

   3) 1) "12.7584877610206604"

      2) "38.78813451624225195"



redis>

GEOSEARCHSTORE

此命令类似于GEOSEARCH，但将结果存储在目标键中。

此命令代替了现已弃用的GEORADIUS和GEORADIUSBYMEMBER。

默认情况下，它将结果destination与其地理空间信息一起存储在排序集中。

使用该STOREDIST选项时，该命令将项目存储在一个排序集中，其中填充了它们与圆或框中心的距离，作为浮点数，以为该形状指定的相同单位。

返回值

整数回复：结果集中的元素数。

例子

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669
"Catania"

(integer) 2

redis> GEOADD Sicily 12.758489 38.788135 "edge1" 17.241510 38.788135
"edge2"

(integer) 2

redis> GEOSEARCHSTORE key1 Sicily FROMLONLAT 15 37 BYBOX 400 400 km
ASC COUNT 3

(integer) 3

redis> GEOSEARCH key1 FROMLONLAT 15 37 BYBOX 400 400 km ASC WITHCOORD
WITHDIST WITHHASH

{empty}1) 1) "Catania"

   2) "56.4413"

   3) (integer) 3479447370796909

   4) 1) "15.08726745843887329"

      2) "37.50266842333162032"

{empty}2) 1) "Palermo"

   2) "190.4424"

   3) (integer) 3479099956230698

   4) 1) "13.36138933897018433"

      2) "38.11555639549629859"

{empty}3) 1) "edge2"

   2) "279.7403"

   3) (integer) 3481342659049484

   4) 1) "17.24151045083999634"

      2) "38.78813451624225195"

redis> GEOSEARCHSTORE key2 Sicily FROMLONLAT 15 37 BYBOX 400 400 km
ASC COUNT 3 STOREDIST

(integer) 3

redis> ZRANGE key2 0 -1 WITHSCORES

{empty}1) "Catania"

{empty}2) "56.441257870158204"

{empty}3) "Palermo"

{empty}4) "190.44242984775784"

{empty}5) "edge2"

{empty}6) "279.7403417843143"



redis>

Hashes

HDEL

从key的哈希中删除指定的字段（field）。在此散列中不存在的指定字段(field)将被忽略。如果key不存在，则将其视为空散列，此命令返回 0。

返回值

整数回复：从散列中删除的字段数，不包括指定但不存在的字段。

例子

redis> HSET myhash field1 "foo"

(integer) 1

redis> HDEL myhash field1

(integer) 1

redis> HDEL myhash field2

(integer) 0



redis>

HEXISTS

如果字段(field)是按键(key)存储的散列中的现有字段(field)，则返回。

返回值

整数回复，特别是：

如果哈希包含field，则返回1.
如果散列不包含field，或key不存在，则返回0。

例子

redis> HSET myhash field1 "foo"

(integer) 1

redis> HEXISTS myhash field1

(integer) 1

redis> HEXISTS myhash field2

(integer) 0



redis>

HGET

返回以键(key)存储的散列中与字段(field)关联的值。

返回值

批量字符串回复：与field, or nilwhen相关联的值field不存在于散列中或key不存在。

例子

redis> HSET myhash field1 "foo"

(integer) 1

redis> HGET myhash field1

"foo"

redis> HGET myhash field2

(nil)



redis>

HGETALL

返回按键(key)存储的散列(hash)的所有字段(field)和值(value)。在返回的值中，每个字段名后跟其值，因此回复的长度是散列大小的两倍。

返回值

数组回复：存储在哈希中的字段及其值的列表，或者当key不存在时为空列表。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HSET myhash field2 "World"

(integer) 1

redis> HGETALL myhash

{empty}1) "field1"

{empty}2) "Hello"

{empty}3) "field2"

{empty}4) "World"



redis>

HINCRBY

将按键(key)存储的散列(hash)中存储在字段(field)中的数字递增(increment)。如果key不存在，则创建一个包含散列的key。如果field不存在，则0在执行操作之前将该值设置为。

HINCRBY支持的值范围仅限于 64 位有符号整数。

返回值

整数回复：field递增操作后的值。

例子

由于increment参数是有符号的，因此可以执行递增和递减操作：

redis> HSET myhash field 5

(integer) 1

redis> HINCRBY myhash field 1

(integer) 6

redis> HINCRBY myhash field -1

(integer) 5

redis> HINCRBY myhash field -10

(integer) -5



redis>

HINCRBYFLOAT

将field存储在key并表示浮点数的散列的指定值增加指定的increment。如果增量值为负，则结果是哈希字段值递减而不是递增。如果该字段不存在，则0在执行操作之前将其设置为。如果发生以下情况之一，则返回错误：

该字段包含错误类型的值（不是字符串）。
当前字段内容或指定的增量不能解析为双精度浮点数。

此命令的确切行为与INCRBYFLOAT 命令之一相同，有关详细信息，请参阅INCRBYFLOAT的文档。

返回值

批量字符串回复：field增量后的值。

例子

redis> HSET mykey field 10.50

(integer) 1

redis> HINCRBYFLOAT mykey field 0.1

"10.6"

redis> HINCRBYFLOAT mykey field -5

"5.6"

redis> HSET mykey field 5.0e3

(integer) 0

redis> HINCRBYFLOAT mykey field 2.0e2

"5200"



redis>

HKEYS

返回key指定的的散列中所有字段(field)名称。

返回值

数组回复：哈希中的字段列表，key不存在时为空列表。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HSET myhash field2 "World"

(integer) 1

redis> HKEYS myhash

{empty}1) "field1"

{empty}2) "field2"



redis>

HLEN

返回key指定的散列中包含的字段(field)数。

返回值

整数回复：哈希中的字段数，或0何时key不存在。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HSET myhash field2 "World"

(integer) 1

redis> HLEN myhash

(integer) 2



redis>

HMGET

返回key指定的hash中指定的字段(field)。

对于field散列中不存在的每一个，返回一个nil值。因为不存在的键被视为空哈希，所以对不存在的键(key)运行HMGET命令，将返回一个nil值列表。

返回值

数组回复：与给定字段关联的值列表，按请求顺序排列。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HSET myhash field2 "World"

(integer) 1

redis> HMGET myhash field1 field2 nofield

{empty}1) "Hello"

{empty}2) "World"

{empty}3) (nil)



redis>

HMSET

设置key指定的hash中指定字段(field)的值。此命令会覆盖哈希中已存在的任何指定字段(field)。如果key不存在，则创建一个包含散列的key。

根据 Keybyte，HMSET 被认为已弃用。请在新代码中首选HSET。

返回值

简单的字符串回复

例子

redis> HMSET myhash field1 "Hello" field2 "World"

"OK"

redis> HGET myhash field1

"Hello"

redis> HGET myhash field2

"World"



redis>

HRANDFIELD

当仅使用key参数调用时，从存储在key上的散列值返回一个随机字段(field)。

如果提供的count参数为正数，则返回不同字段的数组。数组的长度是count或哈希的字段数 ( HLEN )，以较低者为准。

如果使用负数调用count，则行为会发生变化，并且该命令可以多次返回相同的字段。在这种情况下，返回字段的数量是指定的绝对值count。

可选WITHVALUES修饰符更改回复，使其包括随机选择的哈希字段的相应值。

返回值

批量字符串回复：如果没有附加count参数，该命令将返回一个随机选择的字段的批量回复，或者nil当key不存在时。

数组回复：当count传递附加参数时，命令返回一个字段数组，或者当key不存在时返回一个空数组。如果使用WITHVALUES修饰符，则回复是一个列表字段及其哈希值。

例子

redis> HMSET coin heads obverse tails reverse edge null

"OK"

redis> HRANDFIELD coin

"edge"

redis> HRANDFIELD coin

"tails"

redis> HRANDFIELD coin -5 WITHVALUES

{empty}1) "heads"

 2) "obverse"

 3) "heads"

 4) "obverse"

 5) "heads"

 6) "obverse"

 7) "edge"

 8) "null"

 9) "heads"

{empty}10) "obverse"



redis>

传递计数时的行为规范

当count参数为正值时，此命令的行为如下：

不返回重复的字段。
如果count大于散列中的字段数，则该命令将仅返回整个散列，而没有其他字段。
回复中字段的顺序并不是真正随机的，因此如果需要，由客户端来调整它们。
当count为负值时，行为变化如下：
重复字段是可能的。
count如果散列为空（不存在的键），则始终返回确切的字段或空数组。
回复中字段的顺序是真正随机的。

HSCAN

关于HSCAN的用法请看SCAN相关文档。

HSET

设置field在存储在的散列key中value。如果key不存在，则创建一个包含散列的key。如果field散列中已存在，则将其覆盖。

从 Keybyte 开始，HSET 是可变参数并允许多个field/value对。

返回值

整数回复：添加的字段数。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HGET myhash field1

"Hello"



redis>

HSETNX

只在 key 指定的哈希集中不存在指定的字段时，设置字段的值。如果key不存在，则创建一个包含散列的key。如果field已经存在，则此操作无效。

返回值

整数回复，特别是：

1：如果field是散列中的一个新字段并value已设置。
0：如果field散列中已存在且未执行任何操作。

例子

redis> HSETNX myhash field "Hello"

(integer) 1

redis> HSETNX myhash field "World"

(integer) 0

redis> HGET myhash field

"Hello"



redis>

HSTRLEN

返回hash指定field的value的字符串长度，如果hash或者field不存在，返回0。

返回值

整数回复：返回hash指定field的value的字符串长度，如果hash或者field不存在，返回0。

例子

redis> HMSET myhash f1 HelloWorld f2 99 f3 -256

"OK"

redis> HSTRLEN myhash f1

(integer) 10

redis> HSTRLEN myhash f2

(integer) 2

redis> HSTRLEN myhash f3

(integer) 4



redis>

HVALS

返回 key 指定的哈希集中所有字段的值。

返回值

数组回复：散列中的值列表，或者key不存在时为空列表。

例子

redis> HSET myhash field1 "Hello"

(integer) 1

redis> HSET myhash field2 "World"

(integer) 1

redis> HVALS myhash

{empty}1) "Hello"

{empty}2) "World"



redis>

HyperLogLog

PFADD

将所有元素参数添加到存储在指定为第一个参数的变量名称的 HyperLogLog 数据结构中。

作为此命令的副作用，HyperLogLog 内部结构可能会更新，以反映迄今为止添加的唯一项目数量（集合的基数）的不同估计。

如果执行命令后HyperLogLog估计的近似基数发生变化，则PFADD返回1，否则返回0。如果指定的键不存在，该命令会自动创建一个空的 HyperLogLog 结构（即指定长度和给定编码的 Keybyte String）。

要调用没有元素但只有变量名有效的命令，如果变量已经存在，这将导致不执行任何操作，或者如果键不存在则只创建数据结构（在后一种情况下返回 1） .

有关 HyperLogLog 数据结构的介绍，请查看PFCOUNT命令页面。

返回值

整数回复，特别是：

如果至少 1 个 HyperLogLog 内部寄存器被更改，则为 1；否则为0。

例子

redis> PFADD hll a b c d e f g

(integer) 1

redis> PFCOUNT hll

(integer) 7



redis>

PFCOUNT

当使用单个键调用时，返回由存储在指定变量中的 HyperLogLog 数据结构计算的近似基数，如果该变量不存在，则为 0。

当使用多个键调用时，通过内部将存储在提供的键中的 HyperLogLog 合并到临时 HyperLogLog 中，返回传递的 HyperLogLog 联合的近似基数。

HyperLogLog 数据结构可用于仅使用少量恒定内存来计算集合中的唯一元素，特别是每个 HyperLogLog 需要 12k 字节（加上key本身的几个字节）。

返回的观察集的基数并不准确，但近似标准误差为 0.81%。

例如，为了计算一天内执行的所有唯一搜索查询的计数，程序需要在每次处理查询时调用PFADD。可以随时使用PFCOUNT检索估计的唯一查询数。

注意：作为调用此函数的副作用，HyperLogLog 可能被修改，因为最后 8 个字节编码了用于缓存目的的最新计算基数。所以PFCOUNT从技术上来说是一个写命令。

返回值

整数回复，特别是：

通过PFADD观察到的唯一元素的近似数量。

例子

redis> PFADD hll foo bar zap

(integer) 1

redis> PFADD hll zap zap zap

(integer) 0

redis> PFADD hll foo bar

(integer) 0

redis> PFCOUNT hll

(integer) 3

redis> PFADD some-other-hll 1 2 3

(integer) 1

redis> PFCOUNT hll some-other-hll

(integer) 6



redis>

表现

当使用单个键调用PFCOUNT时，即使理论上处理密集 HyperLogLog 的恒定时间很高，性能也非常出色。这是可能的，因为PFCOUNT使用缓存来记住先前计算的基数，这很少改变，因为大多数PFADD操作不会更新任何寄存器。每秒可以进行数百次操作。

当PFCOUNT被称为有多个按键，HyperLogLogs的上即时合并进行，这是缓慢的，而且联盟的基数不能被缓存，所以有多个按键使用时PFCOUNT可能需要的时间在毫秒的数量级，不应滥用。

用户应该记住，此命令的单键和多键执行在语义上是不同的，并且具有不同的性能。

HyperLogLog 表示

Keybyte HyperLogLogs 使用双重表示来表示：稀疏表示适用于计数少量元素（导致少量寄存器设置为非零值）的稀疏表示，以及适用于更高基数的密集表示。Keybyte 会在需要时自动从稀疏表示切换到密集表示。

稀疏表示使用经过优化的运行长度编码，以有效地存储大量设置为零的寄存器。密集表示是一个 12288 字节的 Keybyte 字符串，以存储 16384 个 6 位计数器。对双重表示的需要来自这样一个事实，即使用 12k（这是密集表示内存要求）仅编码几个寄存器以获得较小的基数是非常次优的。

两种表示都有一个 16 字节的头作为前缀，其中包括一个魔法、一个编码/版本字段，以及计算出的缓存基数估计，以小端格式存储（如果自 HyperLogLog 更新以来估计无效，则最高有效位为 1因为计算了基数）。

HyperLogLog 是一个 Keybyte 字符串，可以使用GET检索并使用SET恢复。使用损坏的 HyperLogLog调用PFADD、PFCOUNT或PFMERGE命令从来都不是问题，它可能会返回随机值但不会影响服务器的稳定性。大多数情况下，在损坏稀疏表示时，服务器会识别损坏并返回错误。

从处理器字长和字节序的角度来看，该表示是中性的，因此 32 位和 64 位处理器，大端或小端使用相同的表示。

PFMERGE

将多个 HyperLogLog 值合并为一个唯一值，该值将近似于观察到的源 HyperLogLog 结构集合的并集的基数。

计算出的合并后的 HyperLogLog 设置为目标变量，如果不存在则创建该变量（默认为空的 HyperLogLog）。

如果目标变量存在，则将其视为源集之一，其基数将包含在计算的 HyperLogLog 的基数中。

返回值

简单的字符串回复：命令只是返回OK。

例子

redis> PFADD hll1 foo bar zap a

(integer) 1

redis> PFADD hll2 a b c foo

(integer) 1

redis> PFMERGE hll3 hll1 hll2

"OK"

redis> PFCOUNT hll3

(integer) 6



redis>

Keys

COPY

此命令将存储在source键中的值复制到destination 键。

默认情况下，destination键是在连接使用的逻辑数据库中创建的。该DB选项允许为目标键指定替代逻辑数据库索引。

当destinationkey已经存在时，该命令会返回错误。该 REPLACE选项destination在将值复制到键之前删除键。

返回值

整数回复，特别是：

如果source被复制,返回1。
如果source没有被复制，返回0。

例子

SET dolly "sheep"

COPY dolly clone

GET clone

DEL

删除指定的键。如果键不存在，则忽略该键。

返回值

整数回复：删除的键数。

例子

redis> SET key1 "Hello"

"OK"

redis> SET key2 "World"

"OK"

redis> DEL key1 key2 key3

(integer) 2



redis>

DUMP

以特定于 Keybyte 的格式序列化存储在 key 中的值并将其返回给用户。可以使用RESTORE 命令将返回的值合成回 Keybyte 键。

序列化格式是不透明和非标准的，但它有一些语义特征：

它包含一个 64 位校验和，用于确保检测到错误。在RESTORE命令可以确保使用合成序列化价值的关键前检查校验。
值以 KDB 使用的相同格式编码。
KDB 版本被编码在序列化值中，因此具有不兼容 KDB 格式的不同 Keybyte 版本将拒绝处理序列化值。
序列化值不包含过期信息。为了捕获当前值的生存时间，应该使用PTTL命令。
如果key不存在，则返回 nil 批量回复。

返回值

批量字符串回复：序列化值。

例子

redis> SET mykey 10

"OK"

redis> DUMP mykey

"\u0000\xC0\n\t\u0000\xBEm\u0006\x89Z(\u0000\n"



redis>

EXISTS

如果key存在则返回。

可以指定多个键而不是单个键。在这种情况下，它返回现有键的总数。请注意，为单个键返回 1 或 0 只是可变参数用法的一种特殊情况，因此该命令完全向后兼容。

用户应该知道，如果在参数中多次提到相同的现有键，它将被多次计算。所以如果somekey存在，EXISTS somekey somekey将返回 2。

返回值

整数回复，特别是：

如果key存在，返回1。
如果key不存在，返回0。
指定为参数的键中存在的键数。多次提及和现有的键被多次计数。

例子

redis> SET key1 "Hello"

"OK"

redis> EXISTS key1

(integer) 1

redis> EXISTS nosuchkey

(integer) 0

redis> SET key2 "World"

"OK"

redis> EXISTS key1 key2 nosuchkey

(integer) 2



redis>

EXPIRE

设置超时key。超时到期后，key将被自动删除。在 keybyte 术语中，具有关联超时的键通常被称为易变的。

超时只会被删除或覆盖key内容的命令清除，包括DEL、SET、GETSET和所有*STORE 命令。这意味着所有在概念上更改存储在键中的值而不用新值替换它的操作将保持超时不变。举例来说，增加一键的值INCR，推新值的列表，包括LPUSH，或改变了哈希的字段值HSET是将离开超时不变的所有操作。

也可以使用PERSIST命令清除超时，将key恢复为永久key。

如果使用RENAME重命名key，则关联的生存时间将转移到新的key名称。

如果key被RENAME覆盖，就像现有keyKey_A 被类似调用覆盖的情况一样RENAME Key_B Key_A，原始Key_Akey是否具有关联的超时无关紧要，keyKey_A将继承的所有特征Key_B。

请注意，使用非正超时调用EXPIRE / PEXPIRE或使用过去时间调用 EXPIREAT / PEXPIREAT将导致键被删除而不是过期（因此，发出的键事件将是del，不是expired）。

选项

EXPIRE命令支持一组选项：

NX -- 仅当key没有过期时才设置过期
XX -- 仅当key已存在过期时才设置过期
GT -- 仅当新的到期时间大于当前的到期时间时才设置到期时间
LT -- 仅当新的到期时间小于当前的到期时间时才设置到期时间

对于GT和LT而言，非易失性密钥被视为无限TTL。GT、LT和NX选项是互斥的。

刷新过期

可以使用已经具有现有过期集的键作为参数来调用EXPIRE。在这种情况下，键的生存时间更新为新值。有许多有用的应用程序，下面的导航会话模式部分中记录了一个示例。

模式：导航会话

假设您有一个 Web 服务，并且您对用户最近访问的最新 N 个页面感兴趣，这样每个相邻的页面视图都不会在前一次执行后超过 60 秒。从概念上讲，您可以将这组页面视图视为用户的导航会话，其中可能包含有关他或她当前正在寻找的产品类型的有趣信息，以便您可以推荐相关产品。

您可以使用以下策略在 Keybyte 中轻松建模此模式：每次用户进行页面查看时，您都调用以下命令：

MULTI

RPUSH pagewviews.user: <userid> http://.....

EXPIRE pagewviews.user: <userid> 60

EXEC

如果用户闲置超过 60 秒，则该键将被删除，仅记录相差小于 60 秒的后续页面访问。

这种模式很容易修改为使用INCR的计数器而不是使用RPUSH的列表。

返回值

整数回复，特别是：

1：如果设置了超时。
0：如果未设置超时。例如，键不存在，或由于提供的参数而跳过操作。

例子

redis> SET mykey "Hello"

"OK"

redis> EXPIRE mykey 10

(integer) 1

redis> TTL mykey

(integer) 10

redis> SET mykey "Hello World"

"OK"

redis> TTL mykey

(integer) -1

redis> EXPIRE mykey 10 XX

ERR ERR wrong number of arguments for 'expire' command

redis> TTL mykey

(integer) -1

redis> EXPIRE mykey 10 NX

ERR ERR wrong number of arguments for 'expire' command

redis> TTL mykey

(integer) -1



redis>  +

附录：keybyte 过期

过期的键

通常 keybyte key是在没有关联的生存时间的情况下创建的。key将永远存在，除非用户以明确的方式将其删除，例如使用DEL命令。

该EXPIRE命令的家庭能够联想到的到期给定的关键，在通过按键使用了一些额外的内存成本。当一个键设置了过期时间时，Keybyte 将确保在指定的时间段过去后删除该键。

可以使用EXPIRE和 PERSIST命令（或其他严格相关的命令）更新或完全删除关键生存时间。

过期精度

expire 错误是从 0 到 1 毫秒。

过期和持久性

key过期信息存储为绝对 Unix 时间戳。这意味着即使 Keybyte 实例不活动，时间也在流动。

为了使到期工作正常，计算机时间必须保持稳定。如果您从两台计算机中移动一个 KDB 文件，它们的时钟有很大的不同步，可能会发生有趣的事情（例如所有加载的key在加载时都会过期）。

即使正在运行的实例也会始终检查计算机时钟，因此例如如果您设置一个生存时间为 1000 秒的key，然后将您的计算机时间设置为 2000 秒后，该key将立即过期，而不是持续1000 秒。

Keybyte 如何使key过期

Keybyte key以两种方式过期：被动方式和主动方式。

当某个客户端尝试访问它时，key就会被动地过期，并且发现该key已超时。

当然，这还不够，因为存在永远不会再次访问的过期key。这些键无论如何都应该过期，因此 Keybyte 会定期在具有过期设置的键中随机测试一些键。所有已经过期的键都从键空间中删除。

具体来说，Keybyte 每秒执行 10 次：

从具有关联过期的key集中测试 20 个随机key。
删除所有发现过期的key。
如果超过 25% 的key已过期，请从步骤 1 重新开始。

这是一个平凡的概率算法，基本上假设是我们的样本代表整个key空间，我们继续过期直到可能过期的key百分比低于25％

这意味着在任何给定时刻，使用内存的已过期键的最大数量最大等于每秒最大写入操作数量除以4。

在复制链接和 AOF 文件中如何处理过期

为了在不牺牲一致性的情况下获得正确的行为，当key过期时，在 AOF 文件中合成一个DEL操作并获得所有附加的副本节点。这样过期过程集中在主实例中，不会出现一致性错误。

然而，虽然连接到 master 的副本不会独立地使key过期（但会等待来自 master的DEL），但它们仍将获取数据集中存在的过期的完整状态，因此当副本被选为 master 时它将能够独立地使key过期，完全充当master。

EXPIREAT

EXPIREAT与EXPIRE具有相同的效果和语义，但它不是指定代表 TTL（生存时间）的秒数，而是采用绝对Unix 时间戳（自 1970 年 1 月 1 日以来的秒数）。过去的时间戳将立即删除key。

命令的具体语义请参考EXPIRE的文档。

背景

引入EXPIREAT是为了将相对超时转换为 AOF 持久模式的绝对超时。当然，它可以直接用于指定给定的key应该在未来的给定时间到期。

选项

该EXPIREAT命令支持一组：

NX -- 仅当key没有过期时才设置过期
XX -- 仅当key已存在过期时才设置过期
GT -- 仅当新的到期时间大于当前的到期时间时才设置到期时间
LT -- 仅当新的到期时间小于当前的到期时间时才设置到期时间

一种非易失性键被当作目的的无限TTLGT和LT。的GT，LT而NX选项是互斥的。

返回值

整数回复，特别是：

1：如果设置了超时。
0：如果未设置超时。例如，键不存在，或由于提供的参数而跳过操作。

例子

redis> SET mykey "Hello"

"OK"

redis> EXISTS mykey

(integer) 1

redis> EXPIREAT mykey 1293840000

(integer) 1

redis> EXISTS mykey

(integer) 0



redis>

EXPIRETIME

返回给定key到期的绝对 Unix 时间戳（自 1970 年 1 月 1 日以来），以秒为单位。

另请参阅PEXPIRETIME命令，它以毫秒分辨率返回相同的信息。

返回值

整数回复：以秒为单位的过期 Unix 时间戳，或一个负值以表示错误（请参阅下面的描述）。如果key存在但没有关联的过期时间，则该命令返回-1。如果key不存在，则该命令返回-2。

例子

redis> SET mykey "Hello"

"OK"

redis> EXPIREAT mykey 33177117420

(integer) 1

redis> EXPIRETIME mykey

ERR ERR unknown command `EXPIRETIME`, with args beginning with:
`173146a2f1a230e972c700bf241548c0:mykey`,



redis>

KEYS

返回所有匹配的键pattern。

虽然此操作的时间复杂度为O(N)，但常数时间相当低。例如，运行在入门级笔记本电脑上的 Keybyte 可以在 40 毫秒内扫描 100 万个key数据库。

警告：将KEYS视为仅应在生产环境中极其小心地使用的命令。当它针对大型数据库执行时，它可能会破坏性能。此命令用于调试和特殊操作，例如更改键空间布局。不要在常规应用程序代码中使用KEYS。如果您正在寻找一种在键空间子集中查找键的方法，请考虑使用SCAN或sets。

支持的全局样式模式：

h?llo匹配hello，hallo和hxllo
h*llo匹配hllo和heeeello
h[ae]llo匹配hello和hallo,，但不hillo
h[^e]llo匹配hallo, hbllo, … 但不匹配hello
h[a-b]llo匹配hallo和hbllo

如果要逐字匹配特殊字符，请使用转义字符。

返回值

数组回复：匹配的键列表pattern。

例子

redis> MSET firstname Jack lastname Stuntman age 35**

"OK"

redis> KEYS *name***

{empty}1) "firstname"

{empty}2) "lastname"

redis> KEYS a??**

{empty}1) "age"

redis> KEYS ***

{empty}1) "firstname"

{empty}2) "age"

{empty}3) "lastname"



redis>

MIGRATE

以原子方式将key从源 Keybyte 实例传输到目标 Keybyte 实例。成功后，key将从原始实例中删除，并保证存在于目标实例中。

该命令是原子的，并在传输key所需的时间内阻塞两个实例，在任何给定时间，除非发生超时错误，否则key将出现在给定实例或另一个实例中。通过将空字符串 ("") 作为键并添加KEYS子句，可以在对MIGRATE的单个调用中管道（pipeline）化多个键。

该命令在内部使用DUMP生成键值的序列化版本，并使用RESTORE来合成目标实例中的键。源实例充当目标实例的客户端。如果目标实例对RESTORE命令返回 OK ，则源实例使用DEL删除键。

超时指定与目标实例通信的任何时刻的最大空闲时间（以毫秒为单位）。这意味着操作不需要在指定的毫秒数内完成，但传输应该在不超过指定的毫秒数的情况下进行。

MIGRATE需要执行 I/O 操作并遵守指定的超时。当传输过程中出现 I/O 错误或达到超时时，操作将中止并IOERR返回特殊错误。发生这种情况时，可能会出现以下两种情况：

· key可能在两个实例上。

· key可能仅在源实例中。

在超时的情况下key不可能丢失，但是调用MIGRATE的客户端在超时错误的情况下应该检查key是否也存在于目标实例中并采取相应的行动。

当返回任何其他错误（以开头ERR）时，MIGRATE保证key仍然只存在于原始实例中（除非目标实例上也已经存在同名的key）。

如果源实例中没有要迁移的key，NOKEY则返回。因为在正常情况下丢失key是可能的，例如过期， NOKEY这不是错误。

使用单个命令调用迁移多个键

MIGRATE支持新的批量迁移模式，该模式使用管道（pipeline）以便在实例之间迁移多个键，而不会产生往返时间延迟和其他开销，而这些开销是通过单个MIGRATE调用移动每个键时产生的。

为了启用这种形式，使用了KEYS选项，并将普通的key 参数设置为空字符串。实际的键名将在KEYS参数本身之后提供，如下例所示：

MIGRATE 192.168.1.34 6379 "" 0 5000 KEYS key1 key2 key3

使用这种形式NOKEY时，仅当实例中不存在任何键时才返回状态代码，否则执行命令，即使只存在一个键。

选项

COPY -- 不要从本地实例中删除key。
REPLACE -- 替换远程实例上的现有key。
KEYS -- 如果 key 参数是空字符串，则该命令将迁移所有跟在KEYS选项之后的键（有关更多信息，请参阅上一节）。
AUTH -- 使用给定的密码对远程实例进行身份验证。
AUTH2 -- 使用给定的用户名和密码对进行身份验证。

返回值

简单字符串回复：该命令在成功时返回 OK，或者NOKEY如果在源实例中未找到任何键。

MOVE

移动key从当前选择的数据库（参见SELECT）到指定的目标数据库。当key目标数据库中已经存在，或者源数据库中不存在时，它什么都不做。因此，可以使用MOVE作为锁定原语。

返回值

整数回复，特别是：

1：如果key被移动。
0：如果key移动失败。

OBJECT

OBJECT命令允许检查与key相关联的Keybyte对象的内部结构。这对于调试或了解您的key是否使用特殊编码的数据类型以节省空间很有用。当使用 Keybyte 作为缓存时，您的应用程序还可以使用OBJECT命令报告的信息来实现应用程序级key驱逐策略。

OBJECT命令支持的多个子命令：

OBJECT REFCOUNT <key>返回与指定键关联的值的引用数。此命令主要用于调试。
OBJECT ENCODING <key> 返回用于存储与键关联的值的内部表示类型。
OBJECT IDLETIME <key>返回自存储在指定键的对象空闲（未由读取或写入操作请求）以来的秒数。虽然该值以秒为单位返回，但此计时器的实际分辨率为 10 秒，但在未来的实现中可能会有所不同。当此子命令可maxmemory-policy被设置为LRU策略noeviction 和maxmemory设置。
OBJECT FREQ <key>返回存储在指定键上的对象的对数访问频率计数器。此子命令在maxmemory-policy设置为 LFU 策略时可用。
OBJECT HELP 返回一个简洁的帮助文本。
对象可以用不同的方式编码：
字符串可以编码为raw（正常字符串编码）或int（以这种方式编码表示 64 位有符号间隔中的整数的字符串以节省空间）。
列表可以编码为ziplist或linkedlist。本ziplist是用来节省空间的小型列出特定表示。
集合可以编码为intset或hashtable。该intset是用于单纯的整数组成的小集的特殊编码。
哈希可以编码为ziplist或hashtable。该ziplist是用于小型哈希一个特殊的编码。
排序集可以编码为ziplist或skiplist格式。对于 List 类型的小排序集，可以使用进行特殊编码 ziplist，而skiplist编码则适用于任何大小的排序集。

一旦您执行了使 Keybyte 无法保留节省空间的编码的操作，所有特殊编码的类型都会自动转换为通用类型。

返回值

不同的返回值用于不同的子命令。

· 子命令refcount并idletime返回整数。

· 子命令encoding返回批量回复。

如果您尝试检查的对象丢失，则返回空批量回复。

例子

redis> lpush mylist "Hello World"

(integer) 4

redis> object refcount mylist

(integer) 1

redis> object encoding mylist

"ziplist"

redis> object idletime mylist

(integer) 10

在下面的示例中，您可以看到一旦 Keybyte 不再能够使用节省空间的编码，编码会如何变化。

redis> set foo 1000

OK

redis> object encoding foo

"int"

redis> append foo bar

(integer) 7

redis> get foo

"1000bar"

redis> object encoding foo

"raw"

PERSIST

删除上的现有超时key，将key从volatile（设置了过期时间的key）变为持久性（一个永不过期的key，因为没有关联超时）。

返回值

整数回复，特别是：

1：如果超时被删除。
0：如果key不存在或没有关联的超时。

例子

redis> SET mykey "Hello"

"OK"

redis> EXPIRE mykey 10

(integer) 1

redis> TTL mykey

(integer) 10

redis> PERSIST mykey

(integer) 1

redis> TTL mykey

(integer) -1



redis>

PEXPIRE

此命令的工作方式与EXPIRE完全相同，但key的生存时间以毫秒而不是秒为单位指定。

选项

该PEXPIRE命令支持一组：

NX -- 仅当key没有过期时才设置过期
XX -- 仅当key已存在过期时才设置过期
GT -- 仅当新的到期时间大于当前的到期时间时才设置到期时间
LT -- 仅当新的到期时间小于当前的到期时间时才设置到期时间

一种非易失性键被当作目的的无限TTLGT和LT。的GT，LT而NX选项是互斥的。

返回值

整数回复，特别是：

1：如果设置了超时。
0：如果未设置超时。例如，键不存在，或由于提供的参数而跳过操作。

例子

redis> SET mykey "Hello"

"OK"

redis> PEXPIRE mykey 1500

(integer) 1

redis> TTL mykey

(integer) 2

redis> PTTL mykey

(integer) 1500

redis> PEXPIRE mykey 1000 XX**

ERR ERR wrong number of arguments for 'pexpire' command

redis> TTL mykey

(integer) 1

redis> PEXPIRE mykey 1000 NX**

ERR ERR wrong number of arguments for 'pexpire' command

redis> TTL mykey

(integer) 1



redis>

PEXPIREAT

PEXPIREAT具有相同的效果和语义为EXPIREAT，但Unix时间，在这毫秒，而不是秒指定的键将到期。

选项

PEXPIREAT命令支持一组选项：

NX -- 仅当key没有过期时才设置过期
XX -- 仅当key已存在过期时才设置过期
GT -- 仅当新的到期时间大于当前的到期时间时才设置到期时间
LT -- 仅当新的到期时间小于当前的到期时间时才设置到期时间

一种非易失性键被当作目的的无限TTLGT和LT。的GT，LT而NX选项是互斥的。

返回值

整数回复，特别是：

1：如果设置了超时。
0：如果未设置超时。例如，键不存在，或由于提供的参数而跳过操作。

例子

redis> SET mykey "Hello"

"OK"

redis> PEXPIREAT mykey 1555555555005

(integer) 1

redis> TTL mykey

(integer) -2

redis> PTTL mykey

(integer) -2



redis>

PEXPIRETIME

PEXPIRETIME具有语义为同一EXPIRETIME，但返回以毫秒为单位，而不是秒的绝对Unix的到期时间戳。

返回值

整数回复：以毫秒为单位的过期 Unix 时间戳，或一个负值以发出错误信号（请参阅下面的描述）。如果key存在但没有关联的过期时间，则该命令返回-1。-2如果key不存在，则该命令返回-2。

例子

redis> SET mykey "Hello"

"OK"

redis> PEXPIREAT mykey 33177117420000

(integer) 1

redis> PEXPIRETIME mykey

ERR ERR unknown command `PEXPIRETIME`, with args beginning with:
`adc28fe9c724889304c7cd25f19d6bd9:mykey`,



redis>

PTTL

与TTL一样，此命令返回设置了过期时间的key的剩余生存时间，唯一的区别是TTL以秒为单位返回剩余时间量，而PTTL以毫秒为单位返回剩余时间。

发生错误时的返回值：

如果key不存在，该命令将返回-2。
如果key存在但没有关联的过期，则该命令返回-1。

返回值

整数回复：以毫秒为单位的 TTL，或一个负值以发出错误信号（请参阅上面的描述）。

例子

redis> SET mykey "Hello"

"OK"

redis> EXPIRE mykey 1

(integer) 1

redis> PTTL mykey

(integer) 999



redis>

RANDOMKEY

从当前选择的数据库中返回一个随机key。

返回值

批量字符串回复：随机key，或nil当数据库为空时。

RENAME

重命名key为newkey. key不存在时返回错误。如果newkey已经存在它会被覆盖，当发生这种情况时，RENAME 会执行一个隐式DEL操作，所以如果删除的键包含一个非常大的值，即使RENAME本身通常是一个恒定时间操作，它也可能导致高延迟。

在集群模式下，key和newkey必须在同一个哈希槽中，这意味着实际上只有具有相同哈希标签的键才能在集群中可靠地重命名。

返回值

简单的字符串回复

例子

redis> SET mykey "Hello"

"OK"

redis> RENAME mykey myotherkey

"OK"

redis> GET myotherkey

"Hello"



redis>

RENAMENX

重命名key为newkeyifnewkey尚不存在。key不存在时返回错误。

在集群模式下，key和newkey必须在同一个哈希槽中，这意味着实际上只有具有相同哈希标签的键才能在集群中可靠地重命名。

返回值

整数回复，特别是：

1：如果key被重命名为newkey.
0：如果newkey已经存在。

例子

redis> SET mykey "Hello"

"OK"

redis> SET myotherkey "World"

"OK"

redis> RENAMENX mykey myotherkey

(integer) 0

redis> GET myotherkey

"World"



redis>

RESTORE

创建与通过反序列化提供的序列化值（通过DUMP获得）获得的值关联的键。

如果ttl为 0，则创建的key没有任何过期，否则设置指定的过期时间（以毫秒为单位）。

如果使用了ABSTTL修饰符，ttl则应表示key将过期的绝对 Unix 时间戳（以毫秒为单位）。出于驱逐目的，您可以使用IDLETIME或FREQ修饰符。除非您使用REPLACE修饰符，否则RESTORE将在已存在时返回“目标键名称正忙”错误。

RESTORE检查 KDB 版本和数据校验和。如果它们不匹配，则返回错误。

返回值

简单字符串回复：该命令在成功时返回 OK。

例子

redis> DEL mykey

0

redis> RESTORE mykey 0
"\n\x17\x17\x00\x00\x00\x12\x00\x00\x00\x03\x00\x00\xc0\x01\x00\x04\xc0\x02\x00\x04\xc0\x03\x00\xff\x04\x00u#<\xc0;.\xe9\xdd"

OK

redis> TYPE mykey

list

redis> LRANGE mykey 0 -1

1) "1"

2) "2"

3) "3"

SCAN

在SCAN命令和紧密相关的命令SSCAN，HSCAN和ZSCAN，以便用来递增迭代所有元素的集合。

SCAN迭代当前选定的 Keybyte 数据库中的一组键。
SSCAN迭代 Sets 类型的元素。
HSCAN迭代哈希类型的字段及其关联的值。
ZSCAN迭代 Sorted Set 类型的元素及其相关的分数。

由于这些命令允许增量迭代，每次调用仅返回少量元素，因此它们可以在生产中使用，而不会产生诸如KEYS或SMEMBERS 之类的命令的缺点，这些命令在调用时可能会阻塞服务器很长时间（甚至几秒钟）键或元素的大集合。

然而，虽然像SMEMBERS这样的阻塞命令能够在给定时刻提供属于 Set 的所有元素，但 SCAN 命令系列仅对返回的元素提供有限的保证，因为我们增量迭代的集合可能会在迭代过程中发生变化.

请注意，SCAN、SSCAN、HSCAN和ZSCAN的工作方式都非常相似，因此本文档涵盖了所有四个命令。然而，一个明显的区别是在SSCAN、HSCAN和ZSCAN的情况下，第一个参数是保存 Set、Hash 或 Sorted Set 值的键的名称。该SCAN命令不需要任何按键名称参数，因为它遍历当前数据库的key，所以迭代对象是数据库本身。

SCAN基本用法

SCAN 是一个基于游标的迭代器。这意味着在每次调用命令时，服务器都会返回一个更新的游标，用户需要将其用作下一次调用中的游标参数。

一次迭代在游标设置为0时开始，当服务器返回的游标为0时终止。下面是一个SCAN迭代的例子：

redis 127.0.0.1:6379> scan 0

1) "17"

2)  1) "key:12"

    2) "key:8"

    3) "key:4"

    4) "key:14"

    5) "key:16"

    6) "key:17"

    7) "key:15"

    8) "key:10"

    9) "key:3"

   10) "key:7"

   11) "key:1"

redis 127.0.0.1:6379> scan 17

1) "0"

2) 1) "key:5"

   2) "key:18"

   3) "key:0"

   4) "key:2"

   5) "key:19"

   6) "key:13"

   7) "key:6"

   8) "key:9"

   9) "key:11"

在上面的例子中，第一次调用使用零作为游标，开始迭代。第二次调用使用前一次调用返回的游标作为回复的第一个元素，即 17。

如您所见，SCAN 返回值是一个包含两个值的数组：第一个值是在下一次调用中使用的新游标，第二个值是一个元素数组。

由于在第二次调用中返回的游标为 0，服务器向调用者发出信号，表示迭代已完成，并完全探索了集合。以游标值为 0 开始迭代，并调用SCAN直到返回的游标再次为 0 称为完整迭代。

扫描保证

在SCAN命令，并在其他命令SCAN家庭，能够提供给用户的一组相关联的全迭代保证。

完整迭代始终检索从完整迭代开始到结束的集合中存在的所有元素。这意味着如果给定元素在迭代开始时在集合内，并且在迭代终止时仍然存在，那么在某个时刻SCAN将其返回给用户。
完整迭代永远不会返回从完整迭代开始到结束的集合中不存在的任何元素。因此，如果一个元素在迭代开始之前被删除，并且在迭代持续的所有时间里都不会被添加回集合，SCAN确保永远不会返回该元素。
然而，因为SCAN关联的状态很少（只有光标），所以它有以下缺点：
一个给定的元素可能会被多次返回。由应用程序来处理重复元素的情况，例如，仅使用返回的元素来执行多次重新应用时安全的操作。
在完整迭代期间不经常出现在集合中的元素可能会返回或不返回：它是未定义的。

每次 SCAN 调用返回的元素数

SCAN系列函数不保证每次调用返回的元素数在给定范围内。这些命令也允许返回零个元素，只要返回的游标不为零，客户端就不应认为迭代完成。

但是返回元素的数量是合理的，即在实际操作中SCAN在迭代一个大集合时可能会返回最多几十个元素的数量级的元素，也可能一次返回集合中的所有元素当迭代集合足够小以在内部表示为编码数据结构时调用（这发生在小集合、散列和排序集合中）。

但是，用户可以使用COUNT选项调整每次调用返回的元素数量的数量级。

计数选项

虽然SCAN不保证每次迭代返回的元素数量，但可以使用COUNT选项凭经验调整SCAN的行为。基本上，使用 COUNT 用户指定每次调用时应该完成的工作量，以便从集合中检索元素。这只是对实现的一个提示，但一般来说，这是您在大多数情况下可以从实现中期望的。

默认 COUNT 值为 10。
当迭代键空间，或者一个足够大的可以用哈希表表示的 Set、Hash 或 Sorted Set 时，假设没有使用MATCH选项，服务器通常会在每次调用时返回count或比count多一点的元素。请检查为什么 SCAN 可能会在本文档后面的部分中一次返回所有元素。
当迭代编码为 intsets 的 Sets（仅由整数组成的小集）或编码为 ziplists 的散列和排序集（小散列和由小的单个值组成的集）时，通常所有元素都在第一个SCAN调用中返回，而不管 COUNT价值。

重要提示：不需要每次迭代都使用相同的 COUNT 值。调用者可以根据需要自由地将计数从一次迭代更改为另一次迭代，只要在下一次调用中传递的游标是在上一次调用该命令时获得的游标。

匹配选项

可以只迭代匹配给定 glob 样式模式的元素，类似于将模式作为唯一参数的KEYS命令的行为。

为此，只需MATCH <pattern>在SCAN命令的末尾附加参数（它适用于所有 SCAN 系列命令）。

这是使用MATCH进行迭代的示例：

redis 127.0.0.1:6379> sadd myset 1 2 3 foo foobar
feelsgood

(integer) 6

redis 127.0.0.1:6379> sscan myset 0 match f*

1) "0"

2) 1) "foo"

   2) "feelsgood"

   3) "foobar"

redis 127.0.0.1:6379>

重要的是要注意MATCH过滤器在从集合中检索元素之后应用，就在将数据返回给客户端之前。这意味着如果模式匹配集合中的元素很少，则SCAN在大多数迭代中可能不会返回任何元素。一个例子如下所示：

redis 127.0.0.1:6379> scan 0 MATCH *11*

1) "288"

2) 1) "key:911"

redis 127.0.0.1:6379> scan 288 MATCH *11*

1) "224"

2) (empty list or set)

redis 127.0.0.1:6379> scan 224 MATCH *11*

1) "80"

2) (empty list or set)

redis 127.0.0.1:6379> scan 80 MATCH *11*

1) "176"

2) (empty list or set)

redis 127.0.0.1:6379> scan 176 MATCH *11* COUNT 1000

1) "0"

2)  1) "key:611"

    2) "key:711"

    3) "key:118"

    4) "key:117"

    5) "key:311"

    6) "key:112"

    7) "key:111"

    8) "key:110"

    9) "key:113"

   10) "key:211"

   11) "key:411"

   12) "key:115"

   13) "key:116"

   14) "key:114"

   15) "key:119"

   16) "key:811"

   17) "key:511"

   18) "key:11"

redis 127.0.0.1:6379>

正如您所看到的，大多数调用都返回了零个元素，但最后一次调用使用了 1000 的 COUNT 以强制命令对该迭代进行更多扫描。

类型选项

您可以使用此选项要求SCAN仅返回与给定匹配的对象type，从而允许您遍历数据库以查找特定类型的键。该类型选项只是整个数据库上可用SCAN，HSCAN或ZSCAN等。

type参数与type命令返回的字符串名称相同。注意一个奇怪的地方，一些Redis类型，如geohash, HyperLogLogs, Bitmaps，和Bitfields，可能在内部实现使用其他Redis类型，如字符串或zset，所以不能区分其他键的相同类型的SCAN。例如，ZSET和GEOHASH：

redis 127.0.0.1:6379> GEOADD geokey 0 0 value

(integer) 1

redis 127.0.0.1:6379> ZADD zkey 1000 value

(integer) 1

redis 127.0.0.1:6379> TYPE geokey

zset

redis 127.0.0.1:6379> TYPE zkey

zset

redis 127.0.0.1:6379> SCAN 0 TYPE zset

1) "0"

2) 1) "geokey"

   2) "zkey"

需要注意的是，TYPE过滤器也会在从数据库中检索元素后应用，因此该选项不会减少服务器完成完整迭代所需的工作量，对于稀有类型，您可能不会收到任何元素在多次迭代中。

多次并行迭代

无限数量的客户端可以同时迭代同一个集合，因为迭代器的完整状态在游标中，每次调用都会获取并返回给客户端。根本不采用服务器端状态。

在中间终止迭代

由于没有状态服务器端，但是完整的状态被游标捕获，调用者可以自由地中途终止迭代，而无需以任何方式向服务器发出信号。可以开始无限次迭代并且永远不会终止而不会出现任何问题。

使用损坏的游标调用 SCAN

使用损坏的、负的、超出范围或其他无效的光标调用SCAN将导致未定义的行为，但永远不会导致崩溃。未定义的是SCAN实现不再能确保对返回元素的保证。

唯一可以使用的有效游标是：

开始迭代时光标值为 0。
前一次调用 SCAN 返回的游标以继续迭代。

终止保证

该SCAN算法是保证终止仅在迭代集合保持一定到给定的最大尺寸的大小，否则迭代的集合，总是增长可能导致到SCAN永远不会终止一个完整的迭代。

这很容易直观地看出：如果集合增长，则需要做越来越多的工作来访问所有可能的元素，并且终止迭代的能力取决于对SCAN的调用次数及其 COUNT 选项值与集合增长的速度。

为什么 SCAN 可以在一次调用中返回聚合数据类型的所有项目？

在COUNT选项文档中，我们声明有时这一系列命令可能会在一次调用中一次返回 Set、Hash 或 Sorted Set 的所有元素，而不管COUNT选项值如何。发生这种情况的原因是基于游标的迭代器可以实现，并且只有当我们正在扫描的聚合数据类型表示为哈希表时才有用。然而，Keybyte 使用内存优化，其中小的聚合数据类型，直到它们达到给定的项目数量或单个元素的给定最大大小，使用紧凑的单分配打包编码表示。在这种情况下，SCAN 没有有意义的游标要返回，并且必须一次迭代整个数据结构，因此它唯一合理的行为是在调用中返回所有内容。

然而，一旦数据结构更大并被提升为使用真正的哈希表，SCAN命令系列将诉诸正常行为。请注意，由于这种返回所有元素的特殊行为仅适用于小型聚合，因此它对命令复杂性或延迟没有影响。然而，转换为真实哈希表的确切限制是用户可配置的，因此您可以在单个调用中看到的最大元素数取决于聚合数据类型可以有多大并且仍然使用打包表示。

另请注意，此行为特定于SSCAN、HSCAN和ZSCAN。SCAN本身从不显示此行为，因为键空间始终由哈希表表示。

返回值

SCAN、SSCAN、HSCAN和ZSCAN返回两个元素的多批量回复，其中第一个元素是表示无符号 64 位数字（光标）的字符串，第二个元素是具有元素数组的多批量回复。

SCAN元素数组是一个键列表。
SSCAN元素数组是 Set 成员的列表。
HSCAN元素数组包含两个元素，一个字段和一个值，用于哈希的每个返回元素。
ZSCAN元素数组包含两个元素，一个成员及其关联的分数，用于排序集合的每个返回元素。

其他示例

哈希值的迭代。

redis 127.0.0.1:6379> hmset hash name Jack age 33

OK

redis 127.0.0.1:6379> hscan hash 0

1) "0"

2) 1) "name"

   2) "Jack"

   3) "age"

   4) "33"

SORT

返回或存储包含在列表、集合或排序集合中的元素key。

默认情况下，排序是数字，元素通过它们的值进行比较，解释为双精度浮点数。这是最简单形式的排序：

SORT mylist

假设mylist是一个数字列表，此命令将返回相同的列表，其中元素从小到大排序。为了将数字从大到小排序，请使用DESC修饰符：

SORT mylist DESC

当mylist包含字符串值并且您想按字典顺序对它们进行排序时，请使用ALPHA修饰符：

SORT mylist ALPHA

Keybyte 支持 UTF-8，前提是您正确设置了!LC_COLLATE环境变量。

可以使用LIMIT修饰符限制返回元素的数量。此修饰符采用offset参数，指定要跳过的元素数和count参数，指定从开始返回的元素数offset。以下示例将返回的排序版本的 10 个元素mylist，从元素 0 开始（offset从零开始）：

SORT mylist LIMIT 0 10

几乎所有的修饰符都可以一起使用。下面的例子将返回前 5 个元素，按字典顺序降序排列：

SORT mylist LIMIT 0 5 ALPHA DESC

按外部键排序

有时您想使用外部键作为权重对元素进行排序，而不是比较列表、集合或排序集合中的实际元素。假设列表mylist包含元素1，2并3表示存储在object_1、object_2和中的对象的唯一 ID object_3。当这些对象都有关联的存储的权重weight_1，weight_2，weight_3，SORT可以使用这些权重对mylist排序：

SORT mylist BY weight_*

该BY选项采用一个模式（weight_*在本例中等于），用于生成用于排序的键。获得这些键名称代的第一次出现*在列表中的元件的实际值（1，2并且3在这个例子中）。

跳过元素排序

该BY选项还可以采用不存在的键，这会导致SORT跳过排序操作。如果您想在GET没有排序开销的情况下检索外部键（请参阅下面的选项），这非常有用。

SORT mylist BY nosort

检索外部key

我们前面的例子只返回排序后的 ID。在某些情况下，获取实际对象而不是它们的 ID（object_1、object_2和object_3）更有用。可以使用以下命令根据列表、集合或排序集合中的元素检索外部键：

SORT mylist BY weight_* GET object_*

该GET选项可以多次使用，以便为原始列表、集合或排序集合的每个元素获取更多键。

GET元素本身也可以使用特殊模式#：

SORT mylist BY weight_* GET object_* GET #

存储 SORT 操作的结果

默认情况下，SORT将排序后的元素返回给客户端。使用该STORE选项，结果将存储为指定键的列表，而不是返回给客户端。

SORT mylist BY weight_* STORE resultkey

一个有趣的使用模式SORT … STORE包括将EXPIRE超时与结果键相关联，以便在SORT操作的结果可以缓存一段时间的应用程序中。其他客户端将使用缓存列表，而不是为每个请求调用SORT。当键超时时，可以通过SORT … STORE再次调用来创建缓存的更新版本。

请注意，为了正确实现此模式，避免多个客户端同时重建缓存非常重要。这里需要某种锁定（例如使用SETNX）。

在BY和GET中用哈希

可以使用以下语法对哈希字段使用BY和GET选项：

SORT mylist BY weight_*->fieldname GET object_*->fieldname

该字符串→用于将键名与哈希字段名分开。该键被替换为上述记录，并访问存储在结果键中的散列以检索指定的散列字段。

返回值

数组回复：不传递store选项，命令返回已排序元素的列表。整数回复：当store指定该选项时，该命令返回目标列表中已排序元素的数量。

SORT_RO

SORT命令的只读变体。它与原始SORT完全相同，但拒绝该STORE选项并且可以安全地用于只读副本。

由于原始SORT有一个STORE选项，它在技术上被标记为 Keybyte 命令表中的写入命令。因此，即使连接处于只读模式，Keybyte 集群中的只读副本也会将其重定向到主实例（请参阅Keybyte 集群的READONLY命令）。

返回值

数组回复：已排序元素的列表。

例子

SORT_RO mylist BY weight_*->fieldname GET object_*->fieldname

TOUCH

更改key的最后访问时间。如果键不存在，则忽略该键。

返回值

整数回复：被触摸的键数。

例子

redis> SET key1 "Hello"

"OK"

redis> SET key2 "World"

"OK"

redis> TOUCH key1 key2**

(integer) 2



redis>

TTL

返回具有超时的键的剩余生存时间。这种内省功能允许 Keybyte 客户端检查给定键将继续成为数据集一部分的秒数。

-2如果key不存在，该命令将返回-2。
如果key存在但没有关联的过期，则该命令返回-1。

另请参阅以毫秒分辨率返回相同信息的PTTL命令。

返回值

整数回复：以秒为单位的 TTL，或一个负值以发出错误信号（请参阅上面的描述）。

例子

redis> SET mykey "Hello"

"OK"

redis> EXPIRE mykey 10

(integer) 1

redis> TTL mykey

(integer) 10



redis>

TYPE

返回key所存储的value的数据结构类型。可以返回不同的类型有：string，list，set，zset， hash和stream。

返回值

简单字符串回复：返回当前key的数据类型，如果key不存在时返回none。

例子

redis> SET key1 "value"

"OK"

redis> LPUSH key2 "value"

(integer) 1

redis> SADD key3 "value"

(integer) 1

redis> TYPE key1

"string"

redis> TYPE key2**

"list"

redis> TYPE key3

"set"



redis>

UNLINK

此命令与DEL非常相似：它删除指定的键。就像DEL一样，如果键不存在，则会被忽略。然而，该命令在不同的线程中执行实际的内存回收，因此它不会阻塞，而DEL会阻塞。这就是命令名称的来源：该命令只是从键空间中取消键的链接。实际的删除将在稍后异步进行。

返回值

整数回复：未链接的键数。

例子

redis> SET key1 "Hello"

"OK"

redis> SET key2 "World"

"OK"

redis> UNLINK key1 key2 key3

(integer) 2



redis>

WAIT

此命令会阻塞当前客户端，直到所有先前的写入命令成功传输并被至少指定数量的副本确认。如果达到以毫秒为单位指定的超时，即使尚未达到指定的副本数，该命令也会返回。

该命令将始终返回确认在WAIT命令之前发送的写入命令的副本数，无论是在达到指定的副本数的情况下，还是在达到超时时。

几点说明：

当WAIT返回时，在当前连接的上下文中发送的所有先前写入命令都保证被WAIT返回的副本数接收。
如果该命令作为MULTI事务的一部分发送，则该命令不会阻塞，而是会尽快返回确认先前写入命令的副本数。
超时为 0 意味着永远阻塞。
由于WAIT返回在失败和成功的情况下达到的副本数，客户端应该检查返回的值是否等于或大于它要求的复制级别。

一致性和等待

请注意，WAIT不会使 Keybyte 成为强一致性存储：虽然同步复制是复制状态机的一部分，但它并不是唯一需要的东西。然而，在 Sentinel 或 Keybyte 集群故障转移的背景下，WAIT提高了现实世界的数据安全性。

具体来说，如果给定的写入传输到一个或多个副本，则更有可能（但不能保证）如果主节点发生故障，我们将能够在故障转移期间提升接收写入的副本：Sentinel 和Keybyte Cluster 将尽最大努力在可用副本集中提升最佳副本。

然而，这只是尽力而为的尝试，因此仍有可能丢失同步复制到多个副本的写入。

实施细则

由于引入了与副本的部分重新同步（PSYNC 功能），Keybyte 副本使用它们已在复制流中处理的偏移量异步 ping 其主节点。这以多种方式使用：

检测超时的副本。
断开连接后执行部分重新同步。
实施WAIT。

在WAIT实现的特定情况下，Keybyte 会记住，对于每个客户端，当在给定客户端的上下文中执行给定写入命令时，生成的复制流的复制偏移量。当调用WAIT时，Keybyte 检查指定数量的副本是否已经确认了此偏移量或更大的偏移量。

返回值

整数回复：该命令返回在当前连接上下文中执行的所有写入所达到的副本数。

例子

> SET foo bar

OK

> WAIT 1 0

(integer) 1

> WAIT 2 1000

(integer) 1

在以下示例中，对WAIT的第一次调用不使用超时并要求写入达到 1 个副本。它成功返回。在第二次尝试中，我们设置了超时，并要求将写入复制到两个副本。由于只有一个副本可用，一秒钟后WAIT解除阻塞并返回 1，即达到副本数。

Lists

BLMOVE

BLMOVE是的阻挡变体LMOVE。当source包含元素时，此命令的行为与LMOVE完全相同。在MULTI / EXEC块中使用时，此命令的行为与LMOVE完全相同。当source为空时，Keybyte 将阻止连接，直到另一个客户端推送到它或直到timeout（指定要阻止的最大秒数的双精度值）达到为止。A timeoutof zero 可用于无限期阻止。

此命令代替现在已弃用的BRPOPLPUSH。它的效果与BLMOVE RIGHT LEFT是一样的。

有关详细信息，请参阅LMOVE。

返回值

批量字符串回复：要从中弹出source并推送到的元素destination。如果timeout达到，则返回空回复。

模式：可靠队列

请参阅LMOVE文档中的模式描述。

图案：圆形列表

请参阅LMOVE文档中的模式描述。

BLPOP

BLPOP是一个阻止列表弹出原语。它是LPOP的阻塞版本，因为当没有要从任何给定列表中弹出的元素时，它会阻塞连接。从第一个非空列表的头部弹出一个元素，并按照给定的顺序检查给定的键。

非阻塞行为

当BLPOP被调用时，如果至少有一个指定的键包含一个非空列表，则从列表的头部弹出一个元素，并与从中弹出的元素一起返回给调用者key。

键按照它们被给出的顺序进行检查。假设keylist1不存在list2并且list3持有非空列表。考虑以下命令：

BLPOP list1 list2 list3 0

BLPOP保证从存储在的列表中返回一个元素list2（因为它是检查时的第一个非空列表list1，list2并按list3该顺序）。

阻塞行为

如果指定的键都不存在，BLPOP将阻止连接，直到另一个客户端对其中一个键执行LPUSH或RPUSH操作。

一旦新数据出现在其中一个列表中，客户端就会返回解除阻塞的键名和弹出值。

当BLPOP导致客户端阻塞并且指定了非零超时nil时，当指定的超时到期且没有对至少一个指定键执行推送操作时，客户端将取消阻止返回多批量值。

timeout 参数被解释为一个 double 值，指定要阻止的最大秒数。零超时可用于无限期阻塞。

首先提供什么key？什么客户？什么元素？优先订购详情。

如果客户端尝试阻塞多个键，但至少一个键包含元素，则返回的键/元素对是从左到右具有一个或多个元素的第一个键。在这种情况下，客户端不会被阻止。因此，例如BLPOP key1 key2 key3 key4 0，假设key2和key4都是非空的，将始终返回key2中的一个元素。
如果多个客户端被同一个key阻塞，第一个被服务的客户端是等待更多时间的客户端（第一个被key阻塞的客户端）。一旦一个客户端被解除阻塞，它就不会保留任何优先级，当它在下一次调用BLPOP时再次阻塞时，它将根据已经为同一个key阻塞的客户端数量提供相应的服务，所有这些都将在它之前提供服务（从第一个到最后那个阻塞）。
当一个客户端同时阻塞多个键，并且元素在多个键中同时可用时（因为一个事务或 Lua 脚本将元素添加到多个列表中），客户端将使用第一个键解除阻塞收到一个推送操作（假设它有足够的元素来为我们的客户服务，因为可能还有其他客户在等待这个key）。基本上，在执行每个命令后，Keybyte 将运行一个包含所有接收数据且至少有一个客户端被阻止的键的列表。该列表按新元素到达时间排序，从接收数据的第一个键到最后一个。对于处理的每个键，Keybyte 将以 FIFO 方式为所有等待该键的客户端提供服务，只要该键中存在元素。当key为空或不再有客户端等待此key时，将处理前一个命令/事务/脚本中接收到新数据的下一个key，以此循环。

BLPOP当多个元素被推入列表时的行为。

有时列表可以在同一个概念命令的上下文中接收多个元素：

可变参数推送操作，例如LPUSH mylist a b c.
在对同一个列表执行多次推送操作的MULTI块之后。
更新版本执行 Lua 脚本。

请注意，出于同样的原因，Lua 脚本或MULTI/EXEC块可能会将元素推入列表，然后删除列表。在这种情况下，被阻止的客户端根本不会得到服务，只要在执行单个命令、事务或脚本后列表中没有数据，就会继续被阻止。

BLPOP在MULTI/EXEC交易中

BLPOP可以与管道（pipeline）一起使用（发送多个命令并批量读取回复），但是这种设置几乎只有当它是管道（pipeline）的最后一个命令时才有意义。

在MULTI / EXEC块中使用BLPOP没有多大意义，因为它需要阻塞整个服务器才能以原子方式执行块，这反过来又不允许其他客户端执行推送操作。为此行为BLPOP内MULTI / EXEC当列表为空是返回一个多批量回复，这是达到超时值时会发生同样的事情。

如果你喜欢科幻小说，想想时间在MULTI / EXEC块中以无限的速度流动 ……

返回值

数组回复：特别是：

nil无法弹出元素且超时到期时的多批量。
一个双元素多块，第一个元素是弹出元素的键名，第二个元素是弹出元素的值。

例子

redis> DEL list1 list2

(integer) 0

redis> RPUSH list1 a b c

(integer) 3

redis> BLPOP list1 list2 0

1) "list1"

2) "a"

可靠的队列

当BLPOP向客户端返回一个元素时，它也会从列表中删除该元素。这意味着该元素仅存在于客户端的上下文中：如果客户端在处理返回的元素时崩溃，它将永远丢失。

对于某些我们想要更可靠的消息传递系统的应用程序，这可能是一个问题。在这种情况下，请检查BRPOPLPUSH命令，它是BLPOP的变体，它在将返回的元素返回给客户端之前将其添加到目标列表中。

模式：事件通知

使用阻塞列表操作可以挂载不同的阻塞原语。例如，对于某些应用程序，您可能需要阻止等待元素进入 Keybyte 集合，以便只要将新元素添加到集合中，就可以在不依靠轮询的情况下检索它。这将需要一个不可用的阻止版本的SPOP，但使用阻止列表操作我们可以轻松完成此任务。

消费者会做：

LOOP forever

    WHILE SPOP(key) returns elements

        ... process elements ...

    END

    BRPOP helper_key

END

在生产者方面，我们将简单地使用：

MULTI

SADD key element

LPUSH helper_key x

EXEC

BRPOP

BRPOP是一个阻止列表弹出原语。它是RPOP的阻塞版本，因为当没有要从任何给定列表中弹出的元素时，它会阻塞连接。从第一个非空列表的尾部弹出一个元素，并按照给定的顺序检查给定的键。

参见BLPOP文档的确切语义，因为BRPOP相同BLPOP与唯一的区别是它弹出从列表，而不是从头部弹出的尾部元件。

返回值

数组回复：特别是：

当不能弹出任何元素且超时已过时，回复A ni* multi-bulk 。
一个双元素多块，第一个元素是弹出元素的键名，第二个元素是弹出元素的值。

例子

redis> DEL list1 list2

(integer) 0

redis> RPUSH list1 a b c

(integer) 3

redis> BRPOP list1 list2 0

1) "list1"

2) "c"

BRPOPLPUSH

BRPOPLPUSH是RPOPLPUSH的变种。当source包含元素时，此命令的行为与RPOPLPUSH完全相同。在MULTI / EXEC块中使用时，此命令的行为与RPOPLPUSH完全相同。当source为空时，Keybyte 将阻塞连接，直到另一个客户端推送到它或直到timeout到达。A timeoutof zero 可用于无限期阻止。

BRPOPLPUSH 被认为已弃用。请在新代码中更喜欢BLMOVE。

有关详细信息，请参阅RPOPLPUSH。

返回值

批量字符串回复：要从中弹出source并推送到的元素destination。如果timeout达到，则返回空回复。

模式：可靠队列

请参阅RPOPLPUSH文档中的模式描述。

图案：圆形列表

请参阅RPOPLPUSH文档中的模式描述。

LINDEX

返回存储在键的列表中index index处的元素。索引从零开始，因此0表示第一个元素、1第二个元素等。负索引可用于指定从列表尾部开始的元素。在这里，-1表示最后一个元素，-2表示倒数第二个等等。

当key处的value不是list时，返回错误。

返回值

批量字符串回复：请求的元素，或nil何时index超出范围。

例子

redis> LPUSH mylist "World"

(integer) 1

redis> LPUSH mylist "Hello"

(integer) 2

redis> LINDEX mylist 0

"Hello"

redis> LINDEX mylist -1

"World"

redis> LINDEX mylist 3

(nil)



redis>

LINSERT

在引用值pivot之前或之后以键key存储的列表中插入元素。

当key不存在时，它被认为是一个空列表，不执行任何操作。

当key存在但不包含列表值时返回错误。

返回值

整数回复：当pivot的值没有被找到时，回复插入操作后列表的长度或-1

例子

redis> RPUSH mylist "Hello"

(integer) 1

redis> RPUSH mylist "World"

(integer) 2

redis> LINSERT mylist BEFORE "World" "There"

(integer) 3

redis> LRANGE mylist 0 -1

{empty}1) "Hello"

{empty}2) "There"

{empty}3) "World"



redis>

LLEN

返回存储在key的list的长度。如果key不存在，则将其解释为空list并0返回。当存储的值key不是列表时返回错误。

返回值

整数回复：在key（键）处的列表长度。

例子

redis> LPUSH mylist "World"

(integer) 1

redis> LPUSH mylist "Hello"

(integer) 2

redis> LLEN mylist**

(integer) 2



redis>

LMOVE

原子地(atomically)返回并删除存储在源列表的第一个/最后一个元素(head/tail取决于wherefrom参数)，并将元素推入存储在目标列表的第一个/最后一个元素(head/tail取决于whereto参数)。

例如：考虑source持有 list a,b,c，并destination 持有 list x,y,z。执行LMOVE source destination RIGHT LEFT结果是source持有 a,b和destination持有c,x,y,z。

如果source不存在，nil则返回该值并且不执行任何操作。如果source和destination相同，则该操作相当于从列表中移除第一个/最后一个元素并将其作为列表的第一个/最后一个元素推送，因此可以认为它是一个列表旋转命令（如果wherefrom是，则为无操作）一样whereto）。

此命令代替现在已弃用的RPOPLPUSH。做 LMOVE RIGHT LEFT是等价的。

返回值

批量字符串回复：被弹出和推送的元素。

例子

redis> RPUSH mylist "one"

(integer) 1

redis> RPUSH mylist "two"

(integer) 2

redis> RPUSH mylist "three"

(integer) 3

redis> LMOVE mylist myotherlist RIGHT LEFT

"three"

redis> LMOVE mylist myotherlist LEFT RIGHT

"one"

redis> LRANGE mylist 0 -1

{empty}1) "two"

redis> LRANGE myotherlist 0 -1

{empty}1) "three"

{empty}2) "one"



redis>

模式：可靠队列

Keybyte 通常用作消息服务器来实现后台作业或其他类型的消息任务的处理。往往获得队列的简单形式推值代入在生产者侧的列表，并使用等待在消费侧此值RPOP （使用轮询），或BRPOP如果客户端更好通过阻塞操作提供服务。

然而，在这种情况下，获得的队列是不可靠的，因为消息可能会丢失，例如在存在网络问题的情况下，或者如果消费者在收到消息后立即崩溃但仍在处理中。

LMOVE（或用于阻塞变体的BLMOVE）提供了一种避免此问题的方法：消费者获取消息并同时将其推送到处理列表中。一旦消息被处理，它将使用LREM命令从处理列表中删除该消息。

额外的客户端可能会监视处理列表中停留时间过长的项目，并在需要时将这些超时的项目再次推送到队列中。

图案：圆形列表

使用具有相同源和目标键的LMOVE，客户端可以在O(N) 中一个接一个地访问 N 元素列表的所有元素，而无需使用单个LRANGE 操作将完整列表从服务器传输到客户端.

即使满足以下两个条件，上述模式也能正常工作：

· 有多个客户端轮换列表：它们将获取不同的元素，直到访问了列表的所有元素，然后进程重新启动。

· 即使其他客户正在积极推动列表末尾的新项目。

以上使得实现一个系统变得非常简单，其中一组项目必须由 N 个工人尽可能快地连续处理。一个例子是一个监控系统，它必须检查一组网站是否可以访问，延迟尽可能小，使用多个并行工作器。

请注意，worker 的这种实现具有简单的可扩展性和可靠性，因为即使消息丢失，该项目仍然在队列中，并将在下一次迭代中进行处理。

LPOP

删除并返回存储在key的list的第一个元素(element)。

默认情况下，该命令从列表的开头弹出单个元素。当提供可选count参数时，回复将最多包含count元素，具体取决于列表的长度。

返回值

当不带count参数调用时：

批量字符串回复：第一个元素的值，或者nil什么key时候不存在。

当使用count参数调用时：

数组回复：弹出元素列表，或nil何时key不存在。

例子

redis> RPUSH mylist "one" "two" "three" "four" "five"

(integer) 5

redis> LPOP mylist**

"one"

redis> LPOP mylist 2**

{empty}1) "two"

{empty}2) "three"

redis> LRANGE mylist 0 -1

{empty}1) "four"

{empty}2) "five"



redis>

LPOS

该命令返回 Keybyte 列表中匹配元素的索引。默认情况下，当没有给出选项时，它将从头到尾扫描列表，寻找“元素”的第一个匹配项。如果找到该元素，则返回其索引（列表中从零开始的位置）。否则，如果未找到匹配项，nil则返回。

> RPUSH mylist a b c 1 2 3 c c

> LPOS mylist c
2

可选参数和选项可以修改命令的行为。该RANK选项指定要返回的第一个元素的“等级”，以防有多个匹配项。等级 1 表示返回第一个匹配项，2 表示返回第二个匹配项，依此类推。

例如，在上面的例子中，元素“c”多次出现，如果我想要第二个匹配的索引，我会写：

> LPOS mylist c RANK 2

6

也就是说，“c”的第二次出现在位置 6。作为RANK参数的负“等级”告诉LPOS反转搜索方向，从尾部开始到头部。

所以，我们想说，给我从列表尾部开始的第一个元素：

> LPOS mylist c RANK -1

7

请注意，索引仍以“自然”方式报告，即考虑从索引 0 处的列表头部开始的第一个元素，索引 1 处的下一个元素，依此类推。这基本上意味着无论排名是正还是负，返回的索引都是稳定的。

有时我们不仅要返回第 N 个匹配元素，还要返回所有前 N 个匹配元素的位置。这可以使用COUNT选项来实现。

> LPOS mylist c COUNT 2

[2,6]

我们可以组合COUNTand RANK，这样COUNT将尝试返回指定数量的匹配项，但从RANK选项指定的第 N 个匹配项开始。

> LPOS mylist c RANK -1 COUNT 2

[7,6]

当COUNT使用时，可以指定0作为匹配的数量，以此来告诉我们希望所有的比赛，发现返回指标阵列的命令。这比给出一个非常大的COUNT选项要好，因为它更通用。

> LPOS mylist c COUNT 0

[2,6,7]

当COUNT使用并且没有找到匹配时，返回一个空数组。但是，当COUNT未使用且没有匹配项时，该命令返回nil。

最后，该MAXLEN选项告诉命令仅将提供的元素与给定的最大列表项数进行比较。因此，例如指定MAXLEN 1000将确保该命令仅执行 1000 次比较，有效地在列表的一个子集上运行算法（第一部分或最后一部分取决于我们使用正排名或负排名的事实）。这有助于限制命令的最大复杂性。当我们希望很早就找到匹配项时，它也很有用，但要确保万一这不是真的，命令不会花费太多时间来运行。

当MAXLEN使用时，可以指定0作为比较的最大数量，以此来告诉我们要无限攀比的命令。这比给出一个非常大的MAXLEN选项要好，因为它更通用。

返回值

该命令返回表示匹配元素的整数，或者nil如果没有匹配。但是，如果COUNT给出该选项，该命令将返回一个数组（如果没有匹配项，则为空）。

例子

redis> RPUSH mylist a b c d 1 2 3 4 3 3 3

(integer) 11

redis> LPOS mylist 3

(integer) 6

redis> LPOS mylist 3 COUNT 0 RANK 2

{empty}1) (integer) 8

{empty}2) (integer) 9

{empty}3) (integer) 10



redis>

LPUSH

将所有指定的值插入到存于 key 的列表的头部。如果key不存在，则在执行推送操作之前将其创建为空列表。当key保存的值不是列表时，将返回错误。

可以使用单个命令调用推送多个元素，只需在命令末尾指定多个参数。元素一个接一个地插入到列表的头部，从最左边的元素到最右边的元素。例如，该命令LPUSH mylist a b c将生成一个包含c第一个元素、b第二个元素和a第三个元素的列表。

返回值

整数回复：推送操作后列表的长度。

例子

redis> LPUSH mylist "world"

(integer) 1

redis> LPUSH mylist "hello"

(integer) 2

redis> LRANGE mylist 0 -1

{empty}1) "hello"

{empty}2) "world"



redis>

LPUSHX

只有当 key 已经存在并且存着一个 list 的时候，在这个 key 下面的 list 的头部插入 value。与LPUSH相反，当key不存在时不会执行任何操作。

返回值

整数回复：推送操作后列表的长度。

例子

redis> LPUSH mylist "World"

(integer) 1

redis> LPUSHX mylist "Hello"

(integer) 2

redis> LPUSHX myotherlist "Hello"

(integer) 0

redis> LRANGE mylist 0 -1

{empty}1) "Hello"

{empty}2) "World"

redis> LRANGE myotherlist 0 -1

(empty list or set)



redis>

LRANGE

返回存储在 key 的列表里指定范围内的元素。偏移量start和stop是从零开始的索引，0是列表的第一个元素（列表的头部），1是下一个元素等等。

这些偏移量也可以是负数，表示从列表末尾开始的偏移量。例如，-1是列表的最后一个元素，-2倒数第二个，等等。

与各种编程语言中的范围函数的一致性

请注意，如果您有一个从 0 到 100 的数字列表，LRANGE list 0 10将返回 11 个元素，即包含最右边的项目。这可能会或可能不会与在您选择的编程语言范围相关的功能行为是一致的（认为Ruby的Range.new，Array#slice 或Python的range()功能）。

超出范围的索引

超出范围的索引不会产生错误。如果start大于列表末尾，则返回一个空列表。如果stop大于列表的实际末尾，Keybyte 会将其视为列表的最后一个元素。

返回值

数组回复：指定范围内的元素列表。

例子

redis> RPUSH mylist "one"

(integer) 1

redis> RPUSH mylist "two"

(integer) 2

redis> RPUSH mylist "three"

(integer) 3

redis> LRANGE mylist 0 0

{empty}1) "one"

redis> LRANGE mylist -3 2**

{empty}1) "one"

{empty}2) "two"

{empty}3) "three"

redis> LRANGE mylist -100 100

{empty}1) "one"

{empty}2) "two"

{empty}3) "three"

redis> LRANGE mylist 5 10

(empty list or set)



redis>

LREM

从存于 key 的列表里移除前 count 次出现的值为 value 的元素。该参数影响在以下几个方面的工作：elementkeycount

count > 0: 删除元素等于element从头到尾移动。
count < 0: 删除元素等于element从尾部移动到头部。
count = 0: 删除所有等于的元素element。

比如， LREM list -2 “hello” 会从存于 list 的列表里移除最后两个出现的 “hello”。请注意，不存在的键被视为空列表，因此当key不存在时，该命令将始终返回0。

返回值

整数回复：删除元素的数量。

例子

redis> RPUSH mylist "hello"

(integer) 1

redis> RPUSH mylist "hello"

(integer) 2

redis> RPUSH mylist "foo"

(integer) 3

redis> RPUSH mylist "hello"

(integer) 4

redis> LREM mylist -2 "hello"

(integer) 2

redis> LRANGE mylist 0 -1

{empty}1) "hello"

{empty}2) "foo"



redis>

LSET

将列表元素设置index为element。有关index参数的更多信息，请参阅LINDEX。

超出范围的索引会返回错误。

返回值

简单的字符串回复

例子

redis> RPUSH mylist "one"

(integer) 1

redis> RPUSH mylist "two"

(integer) 2

redis> RPUSH mylist "three"

(integer) 3

redis> LSET mylist 0 "four"

"OK"

redis> LSET mylist -2 "five"

"OK"

redis> LRANGE mylist 0 -1

{empty}1) "four"

{empty}2) "five"

{empty}3) "three"



redis>

LTRIM

修剪（trim）现有列表，使其仅包含指定范围的指定元素。两者start和stop是基于0的索引，其中，0是列表（头），的第一个元素1的下一个元素等。

例如：LTRIM foobar 0 2将修改存储在的列表，foobar以便仅保留列表的前三个元素。

start并且end也可以是指示从列表中，其中的端部的偏移量的负数-1是列表的最后一个元素，-2倒数第二个元件等。

超出范围的索引不会产生错误：如果start大于列表的末尾，或者start > end，结果将是一个空列表（这会导致key被删除）。如果end大于列表的末尾，Keybyte 会将其视为列表的最后一个元素。

LTRIM 的一个常见用途是与LPUSH / RPUSH一起使用。例如：

LPUSH mylist someelement

LTRIM mylist 0 99

这对命令将在列表上推送一个新元素，同时确保列表不会增长到超过 100 个元素。例如，这在使用 Keybyte 存储日志时非常有用。重要的是要注意，当以这种方式使用时，LTRIM是一个O(1)操作，因为在一般情况下，只从列表的尾部删除一个元素。

返回值

简单的字符串回复

例子

redis> RPUSH mylist "one"

(integer) 1

redis> RPUSH mylist "two"

(integer) 2

redis> RPUSH mylist "three"

(integer) 3

redis> LTRIM mylist 1 -1

"OK"

redis> LRANGE mylist 0 -1

{empty}1) "two"

{empty}2) "three"



redis>

RPOP

删除并返回存储在key中list的最后一个元素。

默认情况下，该命令从列表末尾弹出单个元素。当提供可选count参数时，回复将最多包含count元素，具体取决于列表的长度。

返回值

当不带count参数调用时：

批量字符串回复：最后一个元素的值，或者nil什么key时候不存在。

当使用count参数调用时：

数组回复：弹出元素列表，或nil何时key不存在。

例子

redis> RPUSH mylist "one" "two" "three" "four" "five"

(integer) 5

redis> RPOP mylist**

"five"

redis> RPOP mylist 2**

{empty}1) "four"

{empty}2) "three"

redis> LRANGE mylist 0 -1

{empty}1) "one"

{empty}2) "two"



redis>

RPOPLPUSH

原子地（atomically）返回并移除存储在 source 的列表的最后一个元素（列表尾部元素），并把该元素放入存储在 destination 的列表的第一个元素位置（列表头部）。

例如：考虑source持有 list a,b,c，并destination 持有 list x,y,z。执行RPOPLPUSH导致source持有a,b和destination 持有c,x,y,z。

如果source不存在，nil则返回该值并且不执行任何操作。如果source和destination相同，则该操作相当于从列表中移除最后一个元素并将其作为列表的第一个元素推送，因此可以认为它是一个列表旋转命令。

RPOPLPUSH 被认为已弃用。请在新代码中使用LMOVE。

返回值

批量字符串回复：被弹出和推送的元素。

例子

redis> RPUSH mylist "one"

(integer) 1

redis> RPUSH mylist "two"

(integer) 2

redis> RPUSH mylist "three"

(integer) 3

redis> RPOPLPUSH mylist myotherlist

"three"

redis> LRANGE mylist 0 -1

{empty}1) "one"

{empty}2) "two"

redis> LRANGE myotherlist 0 -1

{empty}1) "three"



redis>

模式：可靠队列

Keybyte 通常用作消息服务器来实现后台作业或其他类型的消息任务的处理。一种简单的队列形式通常是在生产者端将值压入列表，然后在消费者端使用RPOP(使用轮询)或BRPOP(如果阻塞操作更好地服务客户端)等待该值。

例如，当接收到消息后，出现了网络问题或者消费者端崩溃了，那么这个消息就丢失了。RPOPLPUSH（或BRPOPLPUSH用于阻塞变体）提供了一种避免此问题的方法：消费者获取消息，同时将其推送到处理列表中。一旦消息被处理，它将使用LREM命令从处理列表中删除该消息。

额外的客户端可能会监视处理列表中停留时间过长的项目，如果需要，将超时的项目再次推送到队列中。

图案：圆形列表

使用具有相同源和目标键的RPOPLPUSH，客户端可以在O(N) 中一个接一个地访问 N 元素列表的所有元素，而无需使用单个LRANGE 操作将完整列表从服务器传输到客户端.

即使出现以下一种或两种情况，上述模式仍然有效：

有多个客户端轮换列表：它们将获取不同的元素，直到访问了列表的所有元素，然后进程重新启动。
其他客户正在积极推动列表末尾的新项目。

请注意，worker 的这种实现具有简单的可扩展性和可靠性，因为即使消息丢失，该项目仍然在队列中，并将在下一次迭代中进行处理。

RPUSH

向存于 key 的列表的尾部插入所有指定的值。如果key不存在，则在执行推送操作之前将其创建为空列表。当key保存的值不是列表时，将返回错误。

可以使用单个命令调用推送多个元素，只需在命令末尾指定多个参数。元素一个接一个地插入到列表的尾部，从最左边的元素到最右边的元素。例如，该命令RPUSH mylist a b c将生成一个包含a第一个元素、b第二个元素和c第三个元素的列表。

返回值

整数回复：推送操作后列表的长度。

例子

redis> RPUSH mylist "hello"

(integer) 1

redis> RPUSH mylist "world"

(integer) 2

redis> LRANGE mylist 0 -1

{empty}1) "hello"

{empty}2) "world"



redis>

RPUSHX

仅当key已经存在并保存列表时，在存储于key的列表尾部插入指定的值。与RPUSH相反，当key不存在时不会执行任何操作。

返回值

整数回复：推送操作后列表的长度。

例子

redis> RPUSH mylist "Hello"

(integer) 1

redis> RPUSHX mylist "World"

(integer) 2

redis> RPUSHX myotherlist "World"

(integer) 0

redis> LRANGE mylist 0 -1

{empty}1) "Hello"

{empty}2) "World"

redis> LRANGE myotherlist 0 -1

(empty list or set)



redis>

Pub/Sub

PSUBSCRIBE

将客户端订阅到给定的模式。

支持的全局样式模式：

h?llo订阅hello,hallo和hxllo
h*llo订阅hllo和heeeello
h[ae]llo订阅hello和hallo,，但不能是hillo

如果你想逐字匹配的话，请用\分开特殊字符。

PUBLISH

向指定频道发布消息。

在 Keybyte 集群中，客户端可以发布到每个节点。集群确保根据需要转发已发布的消息，因此客户端可以通过连接到任何一个节点来订阅任何通道。

返回值

整数回复：收到消息的客户端数量。请注意，在 Keybyte Cluster 中，仅将与发布客户端连接到同一节点的客户端计入计数。

PUBSUB

PUBSUB 命令是一个内省命令，允许检查 Pub/Sub 子系统的状态。它由单独记录的子命令组成。一般形式为：

PUBSUB <subcommand> … args …

集群注意：在 Keybyte 集群中，客户端可以订阅每个节点，也可以发布到其他每个节点。集群将确保根据需要转发已发布的消息。也就是说，PUBSUB在集群中的回复仅报告来自节点的 Pub/Sub 上下文的信息，而不是整个集群。

PUBSUB 频道 [模式]

列出当前活动的频道。活动频道是具有一个或多个订阅者（不包括订阅模式的客户端）的 Pub/Sub 频道。

如果没有pattern指定，则列出所有通道，否则如果指定了模式，则仅列出与指定的全局样式模式匹配的通道。

返回值

数组回复：活动频道列表，可选择匹配指定的模式。

PUBSUB NUMSUB [channel-1 … channel-N]

返回指定频道的订阅者数量（不包括订阅模式的客户端）。

返回值

数组回复：频道列表和每个频道的订阅者数量。格式是 channel, count, channel, count, …，所以列表是扁平的。列出通道的顺序与命令调用中指定的通道顺序相同。

需要注意的是，在没有通道的情况下调用该命令是有效的。在这种情况下，它只会返回一个空列表。

PUBSUB NUMPAT

返回对模式的订阅数（使用 PSUBSCRIBE命令执行）。请注意，这不仅仅是订阅模式的客户端数量，而是所有客户端订阅的模式总数。

返回值

整数回复：所有客户端订阅的模式数。

PUNSUBSCRIBE

从给定的模式中取消订阅客户端，如果没有给出，则从所有模式中取消订阅。

如果未指定任何模式，则客户端将取消订阅所有先前订阅的模式。在这种情况下，每个未订阅模式的消息将发送到客户端。

将客户端订阅到指定的频道。

一旦客户端进入订阅状态，它不应该发出任何其他命令，除了额外的SUBSCRIBE、PSUBSCRIBE、UNSUBSCRIBE、 PUNSUBSCRIBE、PING、RESET和QUIT命令。

UNSUBSCRIBE

从给定的频道取消订阅客户端，如果没有给定频道，则从所有频道取消订阅。

当未指定频道时，客户端将取消订阅所有先前订阅的频道。在这种情况下，每个未订阅频道的消息将发送到客户端。

Scripting

EVAL

EVAL的第一个参数是 Lua 5.1 脚本。该脚本不需要定义 Lua 函数（也不应该）。它只是一个将在 Keybyte 服务器的上下文中运行的 Lua 程序。

EVAL的第二个参数是脚本后面的参数数量（从第三个参数开始），代表 Keybyte 键名。Lua 可以使用KEYS全局变量以基于一个的数组（so KEYS[1], KEYS[2], …）的形式访问这些参数。

所有额外的参数不应该代表键名并且可以被 Lua 使用ARGV全局变量访问，非常类似于键（so ARGV[1], ARGV[2], …）发生的情况。

以下示例应阐明上述内容：

> eval "return \{KEYS[1],KEYS[2],ARGV[1],ARGV[2]}" 2 key1 key2
first second

1) "key1"

2) "key2"

3) "first"

4) "second"

注意：正如您所看到的，Lua 数组作为 Keybyte 多批量回复返回，这是一种 Keybyte 返回类型，您的客户端库可能会将其转换为您的编程语言中的 Array 类型。

可以使用两个不同的 Lua 函数从 Lua 脚本调用 Keybyte 命令：

redis.call()
redis.pcall()

redis.call()与类似redis.pcall()，唯一的区别是，如果 Keybyte 命令调用会导致错误，redis.call()则会引发 Lua 错误，进而强制EVAL向命令调用者返回错误，同时redis.pcall会捕获错误并返回 Lua 表表示错误。

的自变量redis.call()和redis.pcall()函数都是形成的阱Keybyte的命令的参数：

> eval "return redis.call('set','foo','bar')" 0

OK

上面的脚本将键foo设置为 string bar。然而，它违反了EVAL命令语义，因为脚本使用的所有键都应该使用KEYS数组传递：

> eval "return redis.call('set',KEYS[1],'bar')" 1 foo

OK

在执行之前必须分析所有 Keybyte 命令，以确定该命令将操作哪些键。为了使EVAL为真(true)，必须显式传递键。这在很多方面都很有用，但特别是要确保 Keybyte 集群可以将您的请求转发到适当的集群节点。

请注意，此规则不是为了让用户有机会滥用 Keybyte 单实例配置而强制执行的，代价是编写与 Keybyte 集群不兼容的脚本。

Lua 脚本可以使用一组转换规则返回一个从 Lua 类型转换为 Keybyte 协议的值。

Lua和Keybyte数据类型之间的转换

当 Lua 使用call()或调用Keybyte 命令时，Keybyte 返回值会转换为Lua 数据类型pcall()。类似地，在调用Keybyte命令和Lua脚本返回值时，Lua数据类型被转换为Keybyte协议，以便脚本可以控制EVAL返回给客户端的内容。

这种数据类型之间的转换是这样设计的，如果将Keybyte类型转换为Lua类型，然后将结果转换回Keybyte类型，则结果与初始值相同。

换句话说，Lua 和 Keybyte 类型之间存在一对一的转换。下表显示了所有转换规则：

[.16]Keybyte[.16] 到 Lua 的转换表。

Keybyte整数回复→ Lua数
Keybyte 批量回复 → Lua 字符串
Keybyte 多批量回复 → Lua 表（可能嵌套了其他 Keybyte 数据类型）
Keybyte 状态回复 → Lua 表，包含一个ok包含状态的字段
Keybyte 错误回复 → Lua 表，包含一个err包含错误的字段
Keybyte Nil 批量回复和 Nil 多批量回复 → Lua false 布尔类型

Lua 到 Keybyte的转换表

Lua number → Keybyte 整数回复（将数字转换为整数）
Lua 字符串 → Keybyte 批量回复
Lua 表（数组）→ Keybyte 多批量回复（如果有的话，截断到 Lua 数组中的第一个 nil）
带有单个ok字段的Lua 表→ Keybyte 状态回复
带有单个err字段的Lua 表→ Keybyte 错误回复
Lua boolean false → Keybyte Nil 批量回复。
还有一个额外的 Lua-to-Redis 转换规则，没有对应的 Keybyte 到 Lua 转换规则：
Lua boolean true → Keybyte 整数回复，值为 1。
最后，需要注意三个重要规则：
Lua 有一个单一的数字类型，Lua numbers。整数和浮点数之间没有区别。所以我们总是把 Lua 数字转换成整数回复，如果有的话，去掉数字的小数部分。如果你想从 Lua 返回一个浮点数，你应该将它作为一个 string 返回，就像 Keybyte 本身一样（参见例如ZSCORE命令）。
有没有简单的方法有lua阵内尼尔斯，这是的Lua表语义的结果，所以当Keybyte的一个Lua阵列转换成Keybyte的协议如果遇到零的转换停止。
当 Lua 表包含键（及其值）时，转换后的 Keybyte 回复将不包含它们。

RESP3 模式转换规则：注意 Lua 引擎可以使用新的 Keybyte 6 协议在 RESP3 模式下工作。在这种情况下，有额外的转换规则，并且与 RESP2 模式相比，某些转换也进行了修改。有关更多信息，请参阅本文档的 RESP3 部分。

以下是一些转换示例：

> eval "return 10" 0

(integer) 10

> eval "return \{1,2,\{3,'Hello World!'}}" 0

1) (integer) 1

2) (integer) 2

3) 1) (integer) 3

   2) "Hello World!"

> eval "return redis.call('get','foo')" 0

"bar"

最后一个例子展示了如何接收Lua的redis.call()或redis.pcall()来自 Lua的准确返回值，如果直接调用该命令将返回该值。

在以下示例中，我们可以看到如何处理包含 nils 和键的浮点数和数组：

> eval "return \{1,2,3.3333,somekey='somevalue','foo',nil,'bar'}"
0

1) (integer) 1

2) (integer) 2

3) (integer) 3

4) "foo"

如您所见，3.333 被转换为 3，排除了somekey，并且因为之前有一个 nil，所以不会返回bar字符串。

返回 Keybyte 类型的辅助函数

有两个辅助函数可以从 Lua 返回 Keybyte 类型。

redis.error_reply(error_string)返回错误回复。此函数仅返回一个字段表，其中err字段为您设置为指定的字符串。
redis.status_reply(status_string)返回状态回复。此函数仅返回一个字段表，其中ok字段为您设置为指定的字符串。

使用辅助函数和直接返回指定格式的表格没有区别，所以下面两种形式是等价的：

return \{err="My Error"}

return redis.error_reply("My Error")

脚本的原子性

Keybyte 使用相同的 Lua 解释器来运行所有命令。Keybyte 还保证以原子方式执行脚本：在执行脚本时不会执行其他脚本或 Keybyte 命令。这种语义类似于MULTI / EXEC 之一。从所有其他客户端的角度来看，脚本的效果要么仍然不可见，要么已经完成。

然而，这也意味着执行慢速脚本不是一个好主意。创建快速脚本并不难，因为脚本开销非常低，但是如果您打算使用慢速脚本，您应该意识到在脚本运行时没有其他客户端可以执行命令。

错误处理

如前所述，redis.call()导致 Keybyte 命令错误的调用将停止脚本的执行并返回一个错误，在某种程度上，该错误是由脚本生成的：

> del foo

(integer) 1

> lpush foo a

(integer) 1

> eval "return redis.call('get','foo')" 0

(error) ERR Error running script (call to
f_6b1bf486c81ceb7edf3c093f4c48582e38c0e791): ERR Operation against a key
holding the wrong kind of value

Usingredis.pcall()不会引发错误，但会以上面指定的格式返回错误对象（作为带有err字段的 Lua 表）。脚本可以通过返回redis.pcall()返回的error对象，将准确的错误传递给用户。

在低内存条件下运行 Lua

当Keybyte中的内存使用超过maxmemory限制时，Lua脚本中遇到的第一个使用额外内存的写命令会导致脚本中止（除非redis.pcall被使用）。但是，这里需要注意的一点是，如果第一个写入命令没有使用额外的内存，例如 DEL、LREM 或 SREM 等，Keybyte 将允许它运行，并且 Lua 脚本中的所有后续命令都将执行到完成以实现原子性. 如果后续的脚本写入产生了额外的内存，Keybyte 的内存使用量可以超过maxmemory。

Lua 脚本导致 Keybyte 内存使用量超过的另一种可能方式maxmemory发生在脚本执行开始时，Keybyte 略低于此值，maxmemory因此允许脚本中的第一个写入命令。随着脚本的执行，后续的写入命令会继续生成内存并导致 Keybyte 服务器超过maxmemory.

在这些场景中，建议将maxmemory-policy配置为不使用noeviction。此外，Lua脚本应该很短，这样就可以在Lua脚本之间进行项的移除。

带宽和EVALSHA

该EVAL命令迫使你一次又一次地发送脚本主体。Keybyte 不需要每次都重新编译脚本，因为它使用内部缓存机制，但是在许多情况下，支付额外带宽的成本可能不是最优的。

另一方面，redis.conf 由于以下几个原因，使用特殊命令或 via 定义命令将是一个问题：

不同的实例可能有不同的命令实现。
如果我们必须确保所有实例都包含一个给定的命令，那么部署是很困难的，尤其是在分布式环境中。
阅读应用程序代码，完整的语义可能不清楚，因为应用程序调用服务器端定义的命令。
为了在避免带宽损失的同时避免这些问题，Keybyte 实现了EVALSHA命令。
EVALSHA 的工作方式与EVAL完全一样，但它不是将脚本作为第一个参数，而是具有脚本的 SHA1 摘要。行为如下：
如果服务器仍然记住具有匹配 SHA1 摘要的脚本，则执行该脚本。
如果服务器不记得带有此 SHA1 摘要的脚本，则会返回一个特殊错误，告诉客户端改用EVAL。

示例：

> set foo bar

OK

> eval "return redis.call('get','foo')" 0

"bar"

> evalsha 6b1bf486c81ceb7edf3c093f4c48582e38c0e791 0

"bar"

> evalsha ffffffffffffffffffffffffffffffffffffffff 0

(error) NOSCRIPT No matching script. Please use EVAL.

客户端库实现总是能够在底层乐观地发送EVALSHA，即使在客户端实际调用EVAL时也是如此，希望服务器已经看到了脚本。如果返回NOSCRIPT错误，则将使用EVAL。

在这种情况下，将键和参数作为附加的EVAL参数传递也非常有用，因为脚本字符串保持不变并且可以被 Keybyte 有效地缓存。

脚本缓存语义

执行的脚本保证永远在 Keybyte 实例的给定执行的脚本缓存中。这意味着如果对 Keybyte 实例执行EVAL，则所有后续EVALSHA调用都会成功。

脚本可以被长时间缓存的原因是，编写好的应用程序不太可能有足够多的不同脚本来导致内存问题。每个脚本在概念上就像一个新命令的实现，甚至一个大型应用程序也可能只有几百个。即使应用程序被多次修改，脚本会发生变化，使用的内存也可以忽略不计。

刷新脚本缓存的唯一方法是显式调用SCRIPT FLUSH命令，该命令将完全刷新脚本缓存，删除目前执行的所有脚本。

这通常仅在要为云环境中的其他客户或应用程序实例化实例时才需要。

此外，如前所述，重新启动 Keybyte 实例会刷新脚本缓存，这不是持久的。然而，从客户端的角度来看，只有两种方法可以确保 Keybyte 实例不会在两个不同的命令之间重新启动。

我们与服务器的连接是持久的，到目前为止从未关闭。
客户端显式检查INFO命令中的runid字段，以确保服务器没有重新启动并且仍然是相同的进程。

实际上，对于客户端来说，最好简单地假设在给定连接的上下文中，除非管理员明确调用SCRIPT FLUSH命令，否则保证缓存脚本存在。

用户可以指望 Keybyte 不删除脚本这一事实在管道（pipeline）上下文中在语义上很有用。

例如，具有到 Keybyte 的持久连接的应用程序可以确保如果脚本仍在内存中被发送，那么 EVALSHA 可以用于管道（pipeline）中的那些脚本，而不会因未知脚本而产生错误（我们稍后会详细介绍这个问题）。

一种常见的模式是调用SCRIPT LOAD来加载将出现在管道（pipeline）中的所有脚本，然后直接在管道（pipeline）内使用EVALSHA，而无需检查因无法识别脚本哈希而导致的错误。

脚本命令

Keybyte 提供了一个 SCRIPT 命令，可用于控制脚本子系统。SCRIPT 目前接受三种不同的命令：

SCRIPT FLUSH

此命令是强制 Keybyte 刷新脚本缓存的唯一方法。它在可以将同一实例重新分配给不同用户的云环境中最为有用。它也可用于测试客户端库的脚本功能实现。

SCRIPT EXISTS sha1 sha2 … shaN

给定一个 SHA1 摘要列表作为参数，此命令返回一个 1 或 0 的数组，其中 1 表示特定 SHA1 被识别为脚本缓存中已存在的脚本，而 0 表示以前从未见过具有此 SHA1 的脚本（或者至少在最新的 SCRIPT FLUSH 命令之后从未见过）。

SCRIPT LOAD script

该命令在Keybyte脚本缓存中注册指定的脚本。该命令在我们想要确保EVALSHA不会失败的所有上下文中都很有用（例如在管道（pipeline）或 MULTI/EXEC 操作期间），而无需实际执行脚本。

SCRIPT KILL

此命令是中断长时间运行的脚本的唯一方法，该脚本达到为脚本配置的最大执行时间。SCRIPT KILL 命令只能用于在执行期间未修改数据集的脚本（因为停止只读脚本不会违反脚本引擎保证的原子性）。有关长时间运行的脚本的更多信息，请参阅下一节。

具有确定性写入的脚本

脚本编写的一个非常重要的部分是编写仅以确定性方式更改数据库的脚本。默认情况下，在 Keybyte 实例中执行的脚本通过发送脚本本身而不是结果命令传播到副本和 AOF 文件。由于脚本将在远程主机上重新运行（或在重新加载 AOF 文件时），因此它对数据库所做的更改必须是可重现的。

发送脚本的原因是它通常比发送脚本生成的多个命令要快得多。如果客户端向主服务器发送许多脚本，将脚本转换为副本/AOF 的单个命令将导致复制链接或仅追加文件的带宽过多（并且由于调度通过网络接收到的命令，因此 CPU 也过多与调度由 Lua 脚本调用的命令相比，Keybyte 需要做更多的工作）。

通常复制脚本而不是脚本的效果是有意义的，但并非在所有情况下。因此，脚本引擎能够复制脚本执行产生的写入命令序列，而不是复制脚本本身。有关更多信息，请参阅下一节。

在本节中，我们假设通过发送整个脚本来复制脚本。我们将此复制模式称为整个脚本复制。

整个脚本复制方法的主要缺点是脚本需要具有以下属性：

给定相同的输入数据集，脚本必须始终使用相同的参数执行相同的 Keybyte写入命令。脚本执行的操作不能依赖于任何隐藏（非显式）信息或状态，这些信息或状态可能随着脚本执行的进行或在脚本的不同执行之间而改变，也不能依赖于来自 I/O 设备的任何外部输入。
诸如使用系统时间、调用 Keybyte 随机命令（如 RANDOMKEY）或使用 Lua 的随机数生成器之类的事情可能会导致脚本不会总是以相同的方式进行评估。
为了在脚本中强制执行此行为，Keybyte 执行以下操作：
Lua 不导出访问系统时间或其他外部状态的命令。
如果脚本调用能够在Keybyte随机命令（如RANDOMKEY、SRANDMEMBER、TIME ）之后更改数据集的 Keybyte命令，Keybyte 将阻止脚本并显示错误。这意味着如果脚本是只读的并且不修改数据集，则可以自由调用这些命令。请注意，随机命令不一定意味着使用随机数的命令：任何非确定性命令都被视为随机命令（这方面的最佳示例是TIME命令）。
在 Keybyte 中，可能会以随机顺序返回元素的命令，例如 SMEMBERS（因为 Keybyte 集合是无序的）在从 Lua 调用时具有不同的行为，并且在将数据返回到 Lua 脚本之前会经历一个无声的字典排序过滤器。所以redis.call("smembers",KEYS[1]) 将始终以相同的顺序返回 Set 元素，而从普通客户端调用的相同命令可能会返回不同的结果，即使键包含完全相同的元素。一般来说，不要假设 Lua 中的某些命令会被排序，而是依赖于你调用的原始命令的文档来查看它提供的属性。
Lua 的伪随机数生成函数math.random被修改为每次执行新脚本时总是使用相同的种子。这意味着math.random每次执行脚本时，如果math.randomseed不使用，调用将始终生成相同的数字序列。

然而，用户仍然可以使用以下简单的技巧编写具有随机行为的命令。想象一下，我想编写一个 Keybyte 脚本，用 N 个随机整数填充一个列表。

我可以从这个小 Ruby 程序开始：

require 'rubygems'

require 'redis'

r = Redis.new

RandomPushScript = <<EOF

    local i = tonumber(ARGV[1])

    local res

    while (i > 0) do

        res =
redis.call('lpush',KEYS[1],math.random())

        i = i-1

    end

    return res

EOF

r.del(:mylist)

puts r.eval(RandomPushScript,[:mylist],[10,rand(2**32)])

每次执行此脚本时，结果列表都将包含以下元素：

> lrange mylist 0 -1

 1) "0.74509509873814"

 2) "0.87390407681181"

 3) "0.36876626981831"

 4) "0.6921941534114"

 5) "0.7857992587545"

 6) "0.57730350670279"

 7) "0.87046522734243"

 8) "0.09637165539729"

 9) "0.74990198051087"

10) "0.17082803611217"

为了使其具有确定性，但仍要确保脚本的每次调用都会产生不同的随机元素，我们可以简单地向脚本添加一个额外的参数，该参数将用于为 Lua 伪随机数生成器提供种子。新脚本如下：

RandomPushScript = <<EOF

    local i = tonumber(ARGV[1])

    local res

    math.randomseed(tonumber(ARGV[2]))

    while (i > 0) do

        res =
redis.call('lpush',KEYS[1],math.random())

        i = i-1

    end

    return res

EOF

r.del(:mylist)

puts r.eval(RandomPushScript,1,:mylist,10,rand(2**32))

我们在这里所做的是发送 PRNG 的种子(seed)作为参数之一。给定相同的参数（我们的要求），脚本输出将始终相同，但我们在每次调用时更改其中一个参数，生成随机种子(seed)客户端。种子(seed)将作为复制链接和仅附加文件中的参数之一传播，确保在重新加载 AOF 或副本处理脚本时将生成相同的更改。

注：此行为的一个重要部分是，这Keybyte的工具作为PRNGmath.random和math.randomseed保证具有相同的输出，无论运行Keybyte的系统的架构。32 位、64 位、大端和小端系统都将产生相同的输出。

复制命令而不是脚本

可以选择替代复制方法。我们可以只复制脚本生成的单个写入命令，而不是复制整个脚本。我们称之为脚本效果复制。

在这种复制模式下，在执行 Lua 脚本的同时，Keybyte 会收集 Lua 脚本引擎执行的所有实际修改数据集的命令。当脚本执行完成时，脚本生成的命令序列被包装到一个 MULTI / EXEC 事务中并发送到副本和 AOF。

根据用例，这在多种方面都很有用：

当脚本计算速度慢，但可以通过几个写命令总结效果时，在副本上或重新加载AOF时重新计算脚本是一种耻辱。在这种情况下，最好只复制脚本的效果。
启用脚本效果复制后，将取消对非确定性函数的限制。例如，您可以在脚本中的任何地方自由使用TIME或SRANDMEMBER命令。
这种模式下的 Lua PRNG 在每次调用时随机播种。

要启用脚本效果复制，您需要在脚本执行写入之前发出以下 Lua 命令：

redis.replicate_commands()

如果启用了脚本效果复制，则该函数返回 true；否则，如果在脚本已经调用了写入命令之后调用该函数，则返回 false，并使用正常的整个脚本复制。

命令的选择性复制

选择脚本效果复制（参见上一节），可以更好地对命令传播到副本和AOF的方式。这是一项非常高级的功能，因为误用可能会破坏主、副本和 AOF 必须都包含相同逻辑内容的约定，从而造成损害。

然而，这是一个有用的功能，因为有时我们需要仅在主服务器中执行某些命令才能创建，例如，中间值。

想想我们在两个集合之间执行交集的 Lua 脚本。然后我们从交集中挑选五个随机元素并创建一个包含它们的新集合。最后，我们删除代表两个原始集合之间交集的临时键。我们想要复制的只是具有五个元素的新集合的创建。复制创建临时key的命令也没有用。

为此，Keybyte 引入了一个新命令，该命令仅在启用脚本效果复制时有效，并且能够控制脚本复制引擎。redis.set_repl()如果在禁用脚本效果复制时调用该命令，则会失败并引发错误。

可以使用四个不同的参数调用该命令：

redis.set_repl(redis.REPL_ALL) -- Replicate to the AOF and
replicas.

redis.set_repl(redis.REPL_AOF) -- Replicate only to the
AOF.

redis.set_repl(redis.REPL_REPLICA) -- Replicate only to replicas
(Redis >= 5)

redis.set_repl(redis.REPL_SLAVE) -- Used for backward
compatibility, the same as REPL_REPLICA.

redis.set_repl(redis.REPL_NONE) -- Don't replicate at all.

默认情况下，脚本引擎设置为REPL_ALL. 通过调用此函数，用户可以随时打开或关闭复制模式。

一个简单的例子如下：

redis.replicate_commands() -- Enable effects
replication.

redis.call('set','A','1')

redis.set_repl(redis.REPL_NONE)

redis.call('set','B','2')

redis.set_repl(redis.REPL_ALL)

redis.call('set','C','3')

运行上述脚本后，结果是在副本和AOF上只会创建键A和C。

全局变量保护

Keybyte 脚本不允许创建全局变量，以避免将数据泄漏到 Lua 状态。如果脚本需要在调用之间维护状态（一种非常不常见的需求），则应改用 Keybyte 键。

当尝试访问全局变量时，脚本终止并且 EVAL 返回错误：

redis 127.0.0.1:6379> eval 'a=10' 0

(error) ERR Error running script (call to
f_933044db579a2f8fd45d8065f04a8d0249383e57): user_script:1: Script
attempted to create global variable 'a'

访问不存在的全局变量会产生类似的错误。

使用 Lua 调试功能或其他方法（例如更改用于实现全局保护的元表以规避全局保护）并不难。然而，很难意外地做到这一点。如果用户弄乱了 Lua 全局状态，则无法保证 AOF 和复制的一致性：不要这样做。

Lua 新手请注意：为了避免在脚本中使用全局变量，只需使用local关键字声明要使用的每个变量。

在脚本中使用 SELECT

可以像使用普通客户端一样在 Lua 脚本中调用SELECT，Lua脚本选择的数据库只影响脚本本身的执行，不会修改调用脚本的客户端选择的数据库。

补丁级别版本之间的语义更改是必需的，因为旧行为本质上与 Keybyte 复制层不兼容，并且是错误的原因。

在 RESP3 模式下使用 Lua 脚本

Keybyte服务器支持两种不同的协议。一种称为 RESP2，是旧协议：到服务器的所有新连接都以这种模式启动。然而，客户端可以使用HELLO命令协商新协议：这样连接就被置于 RESP3 模式。在这种模式下，某些命令（例如HGETALL）使用新数据类型（在此特定情况下为 Map 数据类型）进行回复。RESP3 协议在语义上更强大，但是大多数脚本只使用 RESP2 就可以了。

Lua 引擎在与 Keybyte 通信时总是假定以 RESP2 模式运行，因此无论调用EVAL或EVALSHA命令的连接处于 RESP2 或 RESP3 模式，Lua 脚本在默认情况下仍会看到它们使用的相同类型的回复从Keybyte看过去，当使用redis.call()内置函数调用命令时。

在 Keybyte 中运行的 Lua 脚本能够切换到 RESP3 模式，并使用新的可用类型获取回复。类似地，Lua 脚本能够使用新类型回复客户端。在继续阅读本节之前，请确保了解 RESP3 的功能。

为了切换到 RESP3，脚本应该调用这个函数：

redis.setresp(3)

请注意，通过使用参数“3”或“2”调用函数，脚本可以在 RESP3 和 RESP2 之间来回切换。

此时，新的转换可用，特别是：

RESP3特有的Keybyte到Lua转换表：

Keybyte 映射回复 → Lua 表，map其中包含一个表示映射字段和值的Lua 表的单个字段。
Keybyte 设置回复 → Lua 表，set其中包含一个 Lua 表，该表将集合的元素表示为字段，其值仅为true。
Keybyte 新的 RESP3 单空值 → Lua nil。
Keybyte 真(True)回复 → Lua 真布尔值。
Keybyte 错误(False)回复 → Lua 错误布尔值。
Keybyte 双重回复 → Lua 表，其中一个score字段包含一个表示双重值的 Lua 数字。
所有 RESP2 旧转换仍然适用。

特定于 RESP3 的Lua 到 Keybyte转换表。

Lua boolean → Redis boolean true 或 false。请注意，与 RESP2 模式相比，这是一个变化，其中从 Lua 返回 true 将数字 1 返回给 Keybyte 客户端，而返回 false 用于返回 NULL。
将单个map字段设置为字段值 Lua 表 → Keybyte 映射回复的 Lua 表。
单个set字段设置为字段值的 Lua 表 Lua 表 → Keybyte 设置回复，值被丢弃并且可以是任何值。
单个double字段设置为字段值的 Lua 表 Lua 表 → Keybyte 双重回复。
Lua null → Keybyte RESP3 新的空回复（协议"_\r\n"）。
除非以上指定，否则所有 RESP2 旧转换仍然适用。

有一点需要理解：如果 Lua 回复 RESP3 类型，但调用 Lua 的连接处于 RESP2 模式，Keybyte 会自动将 RESP3 协议转换为 RESP2 兼容协议，就像正常命令发生的那样。例如，在 RESP2 模式下将映射类型返回到连接将具有返回字段和值的平面数组的效果。

可用库

Keybyte Lua 解释器加载以下 Lua 库：

base 库。
table 库。
string 库。
math 库。
struct 库。
cjson 库。
cmsgpack 库。
bitop 库。
redis.sha1hex 功能。
redis.breakpoint and redis.debugRedis Lua 调试器上下文中的函数。

每个 Keybyte 实例都保证具有上述所有库，因此您可以确保 Keybyte 脚本的环境始终相同。

struct、CJSON 和 cmsgpack 是外部库，所有其他库都是标准 Lua 库。

结构

struct 是一个用于在 Lua 中打包/解包结构的库。

Valid formats:

> - big endian

< - little endian

![num] - alignment

x - pading

b/B - signed/unsigned byte

h/H - signed/unsigned short

l/L - signed/unsigned long

T   - size_t

i/In - signed/unsigned integer with size `n' (default is size of
int)

cn - sequence of `n' chars (from/to a string); when packing, n==0
means

     the whole string; when unpacking, n==0 means use the
previous

     read number as the string length

s - zero-terminated string

f - float

d - double

' ' - ignored

示例：

127.0.0.1:6379> eval 'return struct.pack("HH", 1, 2)'
0

"\x01\x00\x02\x00"

127.0.0.1:6379> eval 'return \{struct.unpack("HH", ARGV[1])}' 0
"\x01\x00\x02\x00"

1) (integer) 1

2) (integer) 2

3) (integer) 5

127.0.0.1:6379> eval 'return struct.size("HH")' 0

(integer) 4

JSON格式

CJSON 库在 Lua 中提供了极快的 JSON 操作。

示例：

redis 127.0.0.1:6379> eval 'return cjson.encode(\{["foo"]=
"bar"})' 0

"\{\"foo\":\"bar\"}"

redis 127.0.0.1:6379> eval 'return cjson.decode(ARGV[1])["foo"]'
0 "\{\"foo\":\"bar\"}"

"bar"

消息包

cmsgpack 库在 Lua 中提供了简单快速的 MessagePack 操作。

示例：

127.0.0.1:6379> eval 'return cmsgpack.pack(\{"foo", "bar",
"baz"})' 0

"\x93\xa3foo\xa3bar\xa3baz"

127.0.0.1:6379> eval 'return cmsgpack.unpack(ARGV[1])' 0
"\x93\xa3foo\xa3bar\xa3baz"

1) "foo"

2) "bar"

3) "baz"

BITOP

Lua 位运算模块添加了对数字的位运算。它可用于在 Keybyte 中编写脚本。

示例：

127.0.0.1:6379> eval 'return bit.tobit(1)' 0

(integer) 1

127.0.0.1:6379> eval 'return bit.bor(1,2,4,8,16,32,64,128)'
0

(integer) 255

127.0.0.1:6379> eval 'return bit.tohex(422342)' 0

"000671c6"

它支持其他几个功能： bit.tobit、bit.tohex、bit.bnot、bit.band、bit.bor、bit.bxor、 bit.lshift、bit.rshift、bit.arshift、bit.rol、bit.ror、bit.bswap。Lua BitOp 文档中记录了所有可用的函数

redis.sha1hex

对输入字符串执行 SHA1。

示例：

127.0.0.1:6379> eval 'return redis.sha1hex(ARGV[1])' 0
"foo"

"0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"

从脚本中发出 Keybyte 日志

可以使用该redis.log函数从 Lua 脚本写入 Keybyte 日志文件。

redis.log(loglevel,message)

loglevel 是以下之一：

redis.LOG_DEBUG
redis.LOG_VERBOSE
redis.LOG_NOTICE
redis.LOG_WARNING

它们直接对应于普通的 Keybyte 日志级别。只有使用等于或大于当前配置的 Keybyte 实例日志级别的日志级别的脚本生成的日志才会被发出。

该message参数是一个简单的字符串。示例：

redis.log(redis.LOG_WARNING,"Something is wrong with this script.")

将生成以下内容：

[32343] 22 Mar 15:21:39 # Something is wrong with this script.

沙盒和最长执行时间

脚本永远不应该尝试访问外部系统，如文件系统或任何其他系统调用。脚本应该只对 Keybyte 数据和传递的参数进行操作。

脚本也受最大执行时间限制（默认为 5 秒）。这个默认超时时间很大，因为脚本通常应该在一毫秒内运行。限制主要是为了处理开发过程中创建的意外无限循环。

可以通过redis.conf或使用 CONFIG GET / CONFIG SET 命令以毫秒精度修改脚本的最大执行时间。影响最大执行时间的配置参数称为 lua-time-limit。

当脚本达到超时时，它不会被 Keybyte 自动终止，因为这违反了 Keybyte 与脚本引擎之间的约定，以确保脚本是原子的。中断脚本意味着可能会留下写入一半的数据的数据集。出于这个原因，当脚本执行时间超过指定时间时，会发生以下情况：

Keybyte 记录脚本运行时间过长。
它再次开始接受来自其他客户端的命令，但会以 BUSY 错误回复所有发送正常命令的客户端。此状态下唯一允许的命令是SCRIPT KILL和SHUTDOWN NOSAVE.
可以使用SCRIPT KILL命令终止只执行只读命令的脚本。这不会违反脚本语义，因为脚本尚未将数据写入数据集。
如果脚本已经调用了写入命令，则唯一允许的命令将 SHUTDOWN NOSAVE停止服务器而不将当前数据集保存在磁盘上（基本上服务器已中止）。

管道（pipeline）上下文中的EVALSHA

在管道（pipeline）请求的上下文中执行EVALSHA时应该小心，因为即使在管道（pipeline）中，也必须保证命令的执行顺序。如果EVALSHA将返回NOSCRIPT错误，则该命令不能在以后重新发出，否则将违反执行顺序。

客户端库实现应采用以下方法之一：

在管道（pipeline）上下文中始终使用普通EVAL。
累积要发送到管道（pipeline）中的所有命令，然后检查EVA* 命令并使用SCRIPT EXISTS命令检查是否已定义所有脚本。如果没有，请根据需要在管道（pipeline）顶部添加SCRIPT LOAD命令，并对所有EVAL调用使用EVALSHA。

调试 Lua 脚本

Keybyte 支持本地 Lua 调试。Keybyte Lua 调试器是一个远程调试器，由服务器（Keybyte 本身）和客户端（默认为）组成redis-cli。

EVALSHA

通过其 SHA1 摘要评估缓存在服务器端的脚本。脚本使用SCRIPT LOAD命令缓存在服务器端。该命令在其他方面与EVAL相同。

EVALSHA_RO

这是EVALSHA命令的只读变体，不允许执行修改数据的命令。

与EVALSHA不同，使用此命令执行的脚本始终可以被终止并且永远不会影响复制流。因为它只能读取数据，所以这个命令总是可以在 master 或 replica 上执行。

EVAL_RO

这是EVAL命令的只读变体，不允许执行修改数据的命令。

与EVAL不同，使用此命令执行的脚本始终可以被终止并且永远不会影响复制流。因为它只能读取数据，所以这个命令总是可以在 master 或 replica 上执行。

例子

> SET mykey "Hello"

OK

> EVAL_RO "return redis.call('GET', KEYS[1])" 1 mykey

"Hello"

> EVAL_RO "return redis.call('DEL', KEYS[1])" 1 mykey

(error) ERR Error running script (call to
f_359f69785f876b7f3f60597d81534f3d6c403284): @user_script:1:
@user_script: 1: Write commands are not allowed from read-only scripts

SCRIPT DEBUG

为使用EVAL执行的后续脚本设置调试模式。Keybyte 包含一个完整的 Lua 调试器，代号 LDB，可用于使编写复杂脚本的任务变得更加简单。在调试模式下，Keybyte 充当远程调试服务器和客户端，例如redis-cli，可以逐步执行脚本、设置断点、检查变量等.

重要提示：避免使用 Keybyte 生产服务器调试 Lua 脚本。改用开发服务器。

LDB 可以在两种模式之一中启用：异步或同步。在异步模式下，服务器创建一个不会阻塞的分叉调试会话，会话完成后对数据的所有更改都会回滚，因此可以使用相同的初始状态重新启动调试。备用同步调试模式在调试会话处于活动状态时阻止服务器，并在结束后保留对数据集的所有更改。

YES. 启用 Lua 脚本的非阻塞异步调试（更改被丢弃）。
SYNC. 启用 Lua 脚本的阻塞同步调试（保存对数据的更改）。
NO. 禁用脚本调试模式。

返回值

简单的字符串回复：OK。

SCRIPT EXISTS

返回有关脚本缓存中脚本存在的信息。

此命令接受一个或多个 SHA1 摘要并返回一列 1 或 0 以指示脚本是否已在脚本缓存中定义。这在管道（pipeline）操作之前很有用，以确保加载脚本（如果没有，则使用SCRIPT LOAD加载它们）以便可以单独使用EVALSHA而不是EVAL来执行管道（pipeline）操作以节省带宽。

有关 Keybyte Lua 脚本的详细信息，请参阅EVAL文档。

返回值

数组回复该命令返回与指定的 SHA1 摘要参数相对应的整数数组。对于脚本缓存中实际存在的脚本的每个对应 SHA1 摘要，返回 1，否则返回 0。

SCRIPT FLUSH

刷新 Lua 脚本缓存。

有关 Keybyte Lua 脚本的详细信息，请参阅EVAL文档。

默认情况下，SCRIPT FLUSH将同步刷新缓存。Keybyte将lazyfree-lazy-user-flush配置指令设置为“yes”会将默认刷新模式更改为异步。

可以使用以下修饰符之一来明确指定刷新模式：

ASYNC: 异步刷新缓存
SYNC: 同步刷新缓存

返回值

简单的字符串回复

SCRIPT KILL

关闭当前正在执行的 Lua 脚本，假设脚本尚未执行写入操作。

此命令主要用于关闭运行时间过长的脚本（例如，由于错误而进入无限循环）。该脚本将被终止，当前被阻止进入 EVAL 的客户端将看到命令返回并显示错误。

如果脚本已经执行了写操作，则不能以这种方式关闭它，因为这会违反 Lua 脚本原子性契约。在这种情况下，只能SHUTDOWN NOSAVE关闭脚本，以一种艰难的方式关闭 Keybyte 进程，以防止它保留写了一半的信息。

有关 Keybyte Lua 脚本的详细信息，请参阅EVAL文档。

返回值

简单的字符串回复

SCRIPT LOAD

将脚本加载到脚本缓存中，但不执行它。将指定的命令加载到脚本缓存中后，它将可以使用EVALSHA和脚本的正确 SHA1 摘要进行调用，就像第一次成功调用EVAL 之后一样。

脚本保证永远留在脚本缓存中（除非SCRIPT FLUSH被调用）。

即使脚本已经存在于脚本缓存中，该命令也会以相同的方式工作。

有关 Keybyte Lua 脚本的详细信息，请参阅EVAL文档。

返回值

Bulk字符串回复：此命令返回的SHA1摘要添加到脚本缓存脚本。

Server

ACL CAT

如果不带参数调用，该命令将显示可用的 ACL 类别。如果给出了类别名称，该命令将显示指定类别中的所有 Keybyte 命令。

ACL 类别对于创建一次包含或排除大量命令的 ACL 规则非常有用，而无需指定每个命令。例如，以下规则将让用户karin执行除可能影响服务器稳定性的最危险操作之外的所有操作：

ACL SETUSER karin on +@all -@dangerous

我们首先将所有命令添加到karin能够执行的命令集中，然后我们删除所有危险命令。

检查所有可用类别非常简单：

> ACL CAT

 1) "keyspace"

 2) "read"

 3) "write"

 4) "set"

 5) "sortedset"

 6) "list"

 7) "hash"

 8) "string"

 9) "bitmap"

10) "hyperloglog"

11) "geo"

12) "stream"

13) "pubsub"

14) "admin"

15) "fast"

16) "slow"

17) "blocking"

18) "dangerous"

19) "connection"

20) "transaction"

21) "scripting"

然后我们可能想知道哪些命令属于给定类别的一部分：

> ACL CAT dangerous

 1) "flushdb"

 2) "acl"

 3) "slowlog"

 4) "debug"

 5) "role"

 6) "keys"

 7) "pfselftest"

 8) "client"

 9) "bgrewriteaof"

10) "replicaof"

11) "monitor"

12) "restore-asking"

13) "latency"

14) "replconf"

15) "pfdebug"

16) "bgsave"

17) "sync"

18) "config"

19) "flushall"

20) "cluster"

21) "info"

22) "lastsave"

23) "slaveof"

24) "swapdb"

25) "module"

26) "restore"

27) "migrate"

28) "save"

29) "shutdown"

30) "psync"

31) "sort"

返回值

数组回复：ACL 类别列表或给定类别内的命令列表。如果将无效的类别名称作为参数给出，该命令可能会返回错误。

ACL DELUSER

删除所有指定的 ACL 用户并终止所有与这些用户进行身份验证的连接。注意：特殊default用户不能从系统中删除，这是每个新连接都经过身份验证的默认用户。用户列表可能包含不存在的用户名，在这种情况下，不对不存在的用户执行任何操作。

返回值

整数回复：被删除的用户数。由于某些用户可能不存在，因此该数字并不总是与参数的数量相匹配。

例子

> ACL DELUSER antirez

1

==== ACL GENPASS

ACL 用户需要一个可靠的密码才能在没有安全风险的情况下对服务器进行身份验证。这样的密码不需要人为记住，只需要计算机记住，因此它可以非常长和强大（外部攻击者无法猜测）。该ACL GENPASS命令生成从/ dev / urandom的，如有，否则启动密码（系统没有的/ dev / urandom的），它使用了一个较弱的系统很可能仍然比手工采摘弱密码更好。

默认情况下（如果 /dev/urandom 可用）密码很强，可以在 Keybyte 应用程序的上下文中用于其他用途，例如为了创建唯一的会话标识符或其他类型的不可猜测且不冲突的 ID。密码生成也非常便宜，因为我们实际上并没有在每次执行时询问 /dev/urandom 的位。Keybyte 启动时使用 /dev/urandom 创建一个种子，然后它将在计数器模式下使用 SHA256，以 HMAC-SHA256(seed,counter) 作为原语，以便根据需要创建更多随机字节。这意味着应用程序开发人员应该可以随意滥用ACL GENPASS来根据需要创建尽可能多的安全伪随机字符串。

命令输出是二进制字符串的十六进制表示。默认情况下，它发出 256 位（即 64 个十六进制字符）。用户可以提供从 1 到 1024 的比特数形式的参数，以改变输出长度。请注意，所提供的位数始终四舍五入为下一个 4 的倍数。因此，例如，仅要求 1 位密码将导致以单个十六进制字符的形式发出 4 位。

返回值

批量字符串回复：默认情况下，代表 256 位伪随机数据的 64 字节字符串。否则，如果需要参数，则输出字符串长度是指定位数（四舍五入为 4 的下一个倍数）除以 4。

例子

> ACL GENPASS

"dd721260bfe1b3d9601e7fbab36de6d04e2e67b0ef1c53de59d45950db0dd3cc"

> ACL GENPASS 32

"355ef3dd"

> ACL GENPASS 5

"90"

ACL GETUSER

该命令返回为现有 ACL 用户定义的所有规则。

具体来说，它列出了用户的 ACL 标志、密码哈希和key名称模式。请注意，命令规则作为字符串返回，格式与ACL SETUSER命令使用的格式相同。命令规则的这种描述反映了用户的有效权限，因此虽然它可能与用于配置用户的规则集不同，但在功能上仍然相同。

数组回复：用户的 ACL 规则定义列表。

例子

这是默认用户的默认配置：

> ACL GETUSER default

1) "flags"

2) 1) "on"

   2) "allkeys"

   3) "allcommands"

   4) "nopass"

3) "passwords"

4) (empty array)

5) "commands"

6) "+@all"

7) "keys"

8) 1) "*"

9) "channels"

10) 1) "*"

ACL HELP

该ACL HELP命令返回描述不同子一个有用的文本。

返回值

数组回复：子命令列表及其描述

ACL LIST

该命令显示 Keybyte 服务器中当前活动的 ACL 规则。返回数组中的每一行定义了不同的用户，格式与redis.conf文件或外部ACL文件中使用的格式相同，因此您可以将ACL LIST命令返回的内容直接剪切粘贴到配置文件中，如果你愿意（但一定要检查ACL SAVE）。

返回值

字符串数组。

例子

> ACL LIST

1) "user antirez on
#9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
~objects:* &* +@all -@admin -@dangerous"

2) "user default on nopass ~* &* +@all"

ACL LOAD

当 Keybyte 配置为使用 ACL 文件（带有aclfile配置选项）时，此命令将从文件中重新加载 ACL，将所有当前 ACL 规则替换为文件中定义的规则。该命令确保具有全有或全无行为，即：

如果文件中的每一行都有效，则加载所有 ACL。
如果文件中的一行或多行无效，则不会加载任何内容，并继续使用服务器内存中定义的旧 ACL 规则。

返回值

简单的字符串回复：OK成功。

该命令可能会因多种原因失败并出现错误：如果文件不可读，如果文件内部有错误，在这种情况下，错误将在错误中报告给用户。最后，如果服务器未配置为使用外部 ACL 文件，该命令将失败。

例子

> ACL LOAD

+OK

> ACL LOAD

-ERR /tmp/foo:1: Unknown command or category name in ACL...

ACL LOG

该命令显示最近的 ACL 安全事件列表：

无法通过AUTH或HELLO验证他们的连接。
命令被拒绝，因为违反当前 ACL 规则。
命令被拒绝，因为当前 ACL 规则中不允许访问key。

可选参数指定要显示的条目数。默认情况下，最多返回十个失败。特殊的RESET参数清除日志。从最近的条目开始显示。

返回值

当被调用以显示安全事件时：

数组回复：ACL 安全事件列表。

当用RESET调用时：

简单的字符串回复：OK如果安全日志被清除。

例子

> AUTH someuser wrongpassword

(error) WRONGPASS invalid username-password pair

> ACL LOG 1

1)  1) "count"

    2) (integer) 1

    3) "reason"

    4) "auth"

    5) "context"

    6) "toplevel"

    7) "object"

    8) "AUTH"

    9) "username"

   10) "someuser"

   11) "age-seconds"

   12) "4.0960000000000001"

   13) "client-info"

   14) "id=6 addr=127.0.0.1:63026 fd=8 name= age=9 idle=0 flags=N
db=0 sub=0 psub=0 multi=-1 qbuf=48 qbuf-free=32720 obl=0 oll=0 omem=0
events=r cmd=auth user=default"

ACL SAVE

当Keybyte 配置为使用ACL 文件（带有aclfile配置选项）时，此命令会将当前定义的ACL 从服务器内存保存到ACL 文件中。

返回值

简单的字符串回复：OK成功。

由于多种原因，该命令可能会失败并出现错误：如果无法写入文件或服务器未配置为使用外部 ACL 文件。

例子

> ACL SAVE

+OK

> ACL SAVE

-ERR There was an error trying to save the ACLs. Please check the
server logs for more information

ACL SETUSER

创建具有指定规则的 ACL 用户或修改现有用户的规则。这是交互操作Keybyte ACL用户的主界面：如果用户名不存在，则该命令创建没有任何权限的用户名，然后从左到右读取作为连续参数提供的所有规则，将用户ACL规则设置为指定。

如果用户已存在，则除了已设置的规则之外，还简单地应用提供的 ACL 规则。例如：

ACL SETUSER virginia on allkeys +set

上面的命令将创建一个名为virginiaactive的用户（on 规则），可以访问任何键（allkeys 规则），并且可以调用 set 命令（+set 规则）。然后另一个 SETUSER 调用可以修改用户规则：

ACL SETUSER virginia +get

上述规则不会将新规则应用于用户 virginia，因此除了SET 之外，用户 virginia 现在也可以使用GET命令。

当我们想确保从头开始定义一个用户，而不关心它之前是否有关联的规则时，我们可以使用特殊规则 reset作为第一条规则，以便刷新所有其他现有规则：

ACL SETUSER antirez reset [… other rules …]

重置用户后，返回到刚创建时的状态：非活动（关闭规则），不能执行任何命令，不能访问任何键：

> ACL SETUSER antirez reset

+OK

> ACL LIST

1) "user antirez off -@all"

ACL 规则要么是诸如“on”、“off”、“reset”、“allkeys”之类的词，要么是以特殊字符开头并后跟另一个字符串（中间没有任何空格）的特殊规则，例如“+设置”。

以下文档是有关此命令功能的参考手册，但是我们的ACL 教程可能更温和地介绍了 ACL 系统的一般工作方式。

规则列表

这是所有支持的 Keybyte ACL 规则的列表：

on：将用户设置为活动用户，可以使用AUTH <username> <password>.
off: 将用户设置为非活动状态，将无法以该用户身份登录。请注意，如果用户在连接已通过此类用户进行身份验证后被禁用（设置为关闭），则连接将继续按预期工作。要同时终止旧连接，您可以使用带有用户选项的CLIENT KILL。另一种方法是使用ACL DELUSER删除用户，这将导致所有被认证为已删除用户的连接被断开。
~<pattern>：将指定的键模式（glob 样式模式，就像在KEYS命令中一样）添加到用户可访问的键模式列表中。您可以向同一用户添加多个key模式。示例：~objects:*
allkeys: alias for ~*，它允许用户访问所有key。
resetkeys：从用户可以访问的键模式列表中删除所有键模式。
&<pattern>：将指定的 glob 样式模式添加到用户可访问的 Pub/Sub 频道模式列表中。您可以向同一用户添加多个频道模式。示例：&chatroom:*
allchannels: 别名&*，它允许用户访问所有发布/订阅频道。
resetchannels：从用户可以访问的 Pub/Sub 频道模式列表中删除所有频道模式。
+<command>: 将此命令添加到用户可以调用的命令列表中。例子：+zadd。
@<category>：将指定类别中的所有命令添加到用户能够执行的命令列表中。示例：（@string添加所有字符串命令）。有关类别列表，请检查ACL CAT命令。
+<command>|<subcommand>: 将指定的命令添加到用户可以执行的命令列表中，但仅限于指定的子命令。例子：+config|get。如果指定命令的完整版本已被允许用于指定用户，则生成错误。注意：没有删除子命令的对称命令，您需要删除整个命令并重新添加您要允许的子命令。这比去掉子命令安全得多，以后Keybyte可能会增加新的危险子命令，所以减法配置不好。
allcommands: 的别名+@all。添加服务器中存在的所有命令，包括由该用户执行的未来通过模块加载的命令。
-<command>. 喜欢+<command>但删除命令而不是添加它。
-@<category>: 喜欢+@<category>但删除类别中的所有命令而不是添加它们。
nocommands: 别名-@all。删除所有命令，用户将无法再执行任何操作。
nopass：用户被设置为“无密码”用户。这意味着可以使用任何密码对此类用户进行身份验证。默认情况下，default特殊用户设置为“nopass”。该nopass规则还将为用户重置所有配置的密码。
>password：在用户密码列表中添加指定的明文密码作为散列密码。每个用户都可以有多个活动密码，这样密码轮换会更简单。指定的密码不会以明文形式存储在服务器中。例子：>mypassword。
#<hashedpassword>：将指定的散列密码添加到用户密码列表中。Keybyte 散列密码使用 SHA256 散列并转换为十六进制字符串。例子：#c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2。
<password: 喜欢>password但删除密码而不是添加密码。
!<hashedpassword>: 喜欢#<hashedpassword>但删除密码而不是添加密码。
重置：删除用户的任何能力。设置为关闭，没有密码，无法执行任何命令，无法访问任何key。

返回值

简单的字符串回复：OK成功。

如果规则包含错误，则返回error。

例子

> ACL SETUSER alan allkeys +@string +@set -SADD
>alanpassword

+OK



 

> ACL SETUSER antirez heeyyyy

(error) ERR Error in ACL SETUSER modifier 'heeyyyy': Syntax
error

ACL USERS

该命令显示了 Keybyte ACL 系统中当前配置用户的所有用户名的列表。

返回值

字符串数组。

例子

> ACL USERS

1) "anna"

2) "antirez"

3) "default"

ACL WHOAMI

返回当前连接进行身份验证的用户名。新连接使用“Defult”用户进行身份验证。他们可以使用AUTH更改用户。

返回值

批量字符串回复：当前连接的用户名。

例子

> ACL WHOAMI

"default"

BGREWRITEAOF

指示 Keybyte 启动Append Only File重写过程。重写将创建当前仅附加文件的小型优化版本。

如果BGREWRITEAOF失败，则不会丢失任何数据，因为旧的 AOF 将保持不变。

如果还没有后台进程进行持久化，则重写只会由 Keybyte 触发。

具体来说：

如果 Keybyte 子进程正在磁盘上创建快照，则会安排AOF 重写，但在生成 KDB 文件的保存子进程终止之前不会开始。在这种情况下，BGREWRITEAOF仍将返回一个肯定的状态回复，但带有适当的消息。您可以通过查看INFO命令来检查是否安排了 AOF 重写。
如果 AOF 重写已经在进行中，该命令会返回一个错误，并且以后不会安排 AOF 重写。
如果 AOF 重写可以启动，但启动它的尝试失败（例如，由于创建子进程时出错），则会向调用者返回错误。

AOF 重写是由 Keybyte 自动触发的，但是可以随时使用BGREWRITEAOF命令来触发重写。

有关详细信息，请参阅持久性文档。

返回值

简单字符串回复：简单的字符串回复，表示在调用成功执行后，重写开始或即将开始尽快。

在某些情况下，该命令可能会回复错误，如上文所述。

BGSAVE

在后台保存数据库。

通常立即返回 OK 代码。Keybyte fork，父进程继续为客户端服务，子进程将数据库保存在磁盘上然后退出。

如果已经有后台保存在运行，或者如果有另一个非后台保存进程在运行，特别是正在进行的 AOF 重写，则会返回错误。

如果BGSAVE SCHEDULE使用，该命令将OK在 AOF 重写正在进行时立即返回并安排后台保存在下一次机会运行。

客户端可以使用LASTSAVE 命令检查操作是否成功。

有关详细信息，请参阅持久性文档。

返回值

简单字符串回复：Background saving started如果BGSAVE正确启动或Background saving scheduled与SCHEDULE子命令一起使用。

COMMAND

返回有关所有 Keybyte 命令的详细信息的Array 回复。

集群客户端必须知道命令中的键位置，以便命令可以转到匹配的实例，但是 Keybyte 命令在接受一个键、多个键甚至多个由其他数据分隔的键之间有所不同。

您可以使用COMMAND来缓存命令和每个命令的关键位置之间的映射，以便将命令准确路由到集群实例。

嵌套结果数组

每个顶级结果都包含六个嵌套结果。每个嵌套结果是：

命令名
命令数量规范
命令标志的嵌套数组回复
参数列表中第一个键的位置
参数列表中最后一个键的位置
用于定位重复键的步数

命令名称

命令名称是作为小写字符串返回的命令。

命令数量

1) 1) "get"

2) (integer) 2

3) 1) readonly

4) (integer) 1

5) (integer) 1

6) (integer) 1

1) 1) "mget"

2) (integer) -2

3) 1) readonly

4) (integer) 1

5) (integer) -1

6) (integer) 1

命令参数遵循一个简单的模式：

如果命令具有固定数量的必需参数，则为正。
如果命令具有最少数量的必需参数，但可能有更多参数，则为负。
命令数量包括计算命令名称本身。
例子：
GET arity 为 2，因为该命令只接受一个参数并且始终具有格式GET _ key _.
MGET arity 为 -2，因为该命令至少接受一个参数，但最多接受一个参数：MGET _ key1 _ [key2] [key3] …。

还要注意MGET，“最后一个键位置”的 -1 值意味着键列表的长度可能不受限制。

标志（Flag）

命令标志是包含一个或多个状态回复的数组回复：

write - 命令可能会导致修改
readonly - 命令永远不会修改key
denyoom - 如果当前内存不足，则拒绝命令
admin - 服务器管理命令
pubsub - 与 pubsub 相关的命令
noscript - 从脚本中拒绝此命令
random - 命令有随机结果，对脚本很危险
sort_for_script - 如果从脚本调用，排序输出
loading- 在加载数据库时允许命令
stale - 当副本有陈旧数据时允许命令
skip_monitor - 不要在 MONITOR 中显示此命令
asking- 集群相关 - 即使导入也接受
fast- 命令以常数或 log(N) 时间运行。用于延迟监控。
movablekeys - 键没有预先确定的位置。您必须自己发现key。

Movable Keys

1) 1) "sort"

   2) (integer) -2

   3) 1) write

      2) denyoom

      3) movablekeys

   4) (integer) 1

   5) (integer) 1

   6) (integer) 1

某些 Keybyte 命令没有预先确定的键位置。对于这些命令， flagmovablekeys被添加到命令 flags Array reply 中。您的 Keybyte Cluster 客户端需要解析标记的命令movablekeys以定位所有相关的关键位置。

当前需要关键位置解析的命令的完整列表：

SORT - 可选STORE键、可选BY权重、可选GET键
ZUNION - 键在WEIGHT或AGGREGATE开始时停止
ZUNIONSTORE - 键在WEIGHT或AGGREGATE开始时停止
ZINTER - 键停止时WEIGHT或AGGREGATE开始
ZINTERSTORE - 键在WEIGHT或AGGREGATE开始时停止
ZDIFF - 键在numkeys计数参数后停止
ZDIFFSTORE - 键在numkeys计数参数后停止
EVAL - 键在numkeys计数参数后停止
EVALSHA - 键在numkeys计数参数后停止

另请参阅COMMAND GETKEYS以让您的 Keybyte 服务器告诉您键在任何给定命令中的位置。

参数列表中的第一个键

对于大多数命令，第一个键是位置 1。位置 0 始终是命令名称本身。

参数列表中的最后一个键

Keybyte 命令通常接受一个key、两个key或无限数量的key。

如果命令接受一个键，则第一个键和最后一个键的位置为 1。

如果命令接受两个键（例如BRPOPLPUSH、SMOVE、RENAME，…），则最后一个键位置是参数列表中最后一个键的位置。

如果命令接受无限数量的键，则最后一个键位置为 -1。

步数

1) 1) "mset"

2) (integer) -3

3) 1) write

2) denyoom

4) (integer) 1

5) (integer) -1

6) (integer) 2

1) 1) "mget"

2) (integer) -2

3) 1) readonly

4) (integer) 1

5) (integer) -1

6) (integer) 1

关键步数允许我们在MSET 等命令中找到关键位置，格式为MSET _ key1 _ _ val1 _ [key2] [val2] [key3] [val3]….

在MSET的情况下，键是每隔一个位置，因此步长值为 2。与上面的MGET比较，步长值为 1。

返回值

数组回复：命令详细信息的嵌套列表。命令以随机顺序返回。

COMMAND COUNT

返回此 Keybyte 服务器中总命令数的整数回复。

返回值

整数回复：COMMAND返回的命令数

例子

redis> COMMAND COUNT

(integer) 224


redis>

COMMAND GETKEYS

从完整的 Keybyte 命令返回键的数组回复。

COMMAND GETKEYS是一个帮助命令，可让您从完整的 Keybyte 命令中找到key。

COMMAND 将某些命令显示为具有可移动键，这意味着必须解析整个命令才能发现存储或检索键。您可以使用COMMAND GETKEYS直接从 Keybyte 解析命令的方式中发现关键位置。

返回值

数组回复：来自您的命令的键列表。

例子

redis> COMMAND GETKEYS MSET a b c d e f

{empty}1) "a"

{empty}2) "c"

{empty}3) "e"

redis> COMMAND GETKEYS EVAL "not consulted" 3 key1 key2 key3 arg1 arg2
arg3 argN

{empty}1) "key1"

{empty}2) "key2"

{empty}3) "key3"

redis> COMMAND GETKEYS SORT mylist ALPHA STORE outlist

{empty}1) "mylist"

{empty}2) "outlist"



redis>

COMMAND INFO

返回有关多个 Keybyte 命令的详细信息的Array 回复。

与COMMAND相同的结果格式，但您可以指定返回哪些命令。

如果您请求有关不存在的命令的详细信息，它们的返回位置将为 nil。

返回值

数组回复：命令详细信息的嵌套列表。

CONFIG GET

在CONFIG GET命令用于读取一个运行Keybyte的服务器的配置参数。

用于在运行时更改配置的对称命令是CONFIG SET.

CONFIG GET接受一个参数，这是一个全局样式的模式。与此参数匹配的所有配置参数都报告为键值对列表。示例：

redis> config get *max-*-entries*

1) "hash-max-zipmap-entries"

2) "512"

3) "list-max-ziplist-entries"

4) "512"

5) "set-max-intset-entries"

6) "512"

您可以通过CONFIG GET *在打开的redis-cli提示中键入来获取所有支持的配置参数的列表。

所有支持的参数与redis.conf文件中使用的等效配置参数含义相同，重要区别如下：

在指定字节或其他数量的情况下，不能使用redis.conf缩写形式（10k, 2gb… 等等），所有内容都应在配置指令的基本单位中指定为格式正确的 64 位整数。
save 参数是一个由空格分隔的整数组成的字符串。每对整数代表一个秒/修改阈值。

例如redis.conf看起来像：

save 900 1

save 300 10

这意味着，如果数据集至少有 1 次更改，则在 900 秒后保存，如果数据集至少有 10 次更改，则在 300 秒后保存，CONFIG GET将报告为“900 1 300 10”。

返回值

命令的返回类型是Array 回复。

CONFIG RESETSTAT

复位统计使用报告Keybyte的INFO命令。

这些是重置的计数器：

键空间命中
键空间未命中
处理的命令数
收到的连接数
过期key数
被拒绝的连接数
最新叉（2）时间
该aof_delayed_fsync计数器

返回值

简单的字符串回复：始终OK。

CONFIG REWRITE

该CONFIG REWRITE命令重写redis.conf，服务器启动时使用的文件，应用，使其反映当前使用的服务器相比，由于使用的原来这可能是不同的配置所需要的最小的变化CONFIG SET命令。

重写以非常保守的方式执行：

尽量保留原 redis.conf 的注释和整体结构。
如果旧的 redis.conf 文件中已经存在一个选项，它将在相同的位置（行号）被重写。
如果选项尚未存在，但已设置为其默认值，则重写过程不会添加该选项。
如果选项尚不存在，但已设置为非默认值，则将其附加到文件末尾。
未使用的行被消隐。例如，如果您曾经有多个save指令，但是当您禁用 KDB 持久性时，当前配置有更少或没有，所有行都将被空白。

如果原始配置文件由于某种原因不再存在，CONFIG REWRITE 还可以从头开始重写配置文件。然而，如果服务器在没有配置文件的情况下启动，CONFIG REWRITE 只会返回一个错误。

原子重写过程

为了确保 redis.conf 文件始终一致，也就是说，在出现错误或崩溃时，您总是以旧文件或新文件结尾，重写是通过单个write(2)调用执行的，该调用具有足够的内容至少和旧文件一样大。有时以注释的形式添加额外的填充以确保生成的文件足够大，然后文件被截断以删除末尾的填充。

返回值

简单字符串回复：OK正确重写配置时。否则返回错误。

CONFIG SET

该CONFIG SET命令，以重新配置在运行时服务器，而不需要重启Keybyte的使用。您可以使用此命令更改两个微不足道的参数或从一个持久性选项切换到另一个持久性选项。

CONFIG SET支持的配置参数列表可以通过下发CONFIG GET *命令获取，即对称命令，用于获取正在运行的Keybyte实例的配置信息。

使用CONFIG SET设置的所有配置参数都会立即被 Keybyte 加载，并会从执行的下一个命令开始生效。

所有支持的参数与redis.conf文件中使用的等效配置参数含义相同，重要区别如下：

在指定字节或其他数量的选项中，不能使用redis.conf缩写形式 ( 10k, 2gb… 等等)，所有内容都应指定为格式正确的 64 位整数，以配置的基本单位指令。可以将CONFIG SET与内存单元 maxmemory、客户端输出缓冲区和复制积压大小一起使用。
save 参数是一个由空格分隔的整数组成的字符串。每对整数代表一个秒/修改阈值。

例如redis.conf看起来像：

save 900 1

save 300 10

这意味着，如果数据集至少有 1 次更改，则在 900 秒后保存，如果数据集至少有 10 次更改，则在 300 秒后保存，应使用CONFIG SET SAVE "900 1 300 10".

可以使用CONFIG SET命令将持久性从 KDB 快照切换到仅附加文件（反之亦然）。有关如何执行此操作的更多信息，请查看持久性页面。

一般来说，你应该知道的是，将appendonly参数设置为 yes将启动一个后台进程来保存初始的 append-only 文件（从内存数据集中获得），并将所有后续命令附加到 append-only 文件上，因此获得与从一开始就开启 AOF 的 Keybyte 服务器完全相同的效果。

如果需要，您可以同时启用 AOF 和 KDB 快照，这两个选项并不相互排斥。

返回值

简单字符串回复：OK正确设置配置时。否则返回错误。

DBSIZE

返回当前选择的数据库中的键数。

返回值

整数回复

DEBUG OBJECT

DEBUG OBJECT是客户端不应使用的调试命令。改为检查OBJECT命令。

返回值

简单的字符串回复

DEBUG SEGFAULT

DEBUG SEGFAULT执行导致 Keybyte 崩溃的无效内存访问。它用于模拟开发过程中的错误。

返回值

简单的字符串回复

FAILOVER

此命令将在当前连接的主节点与其副本之一之间启动协调故障转移。故障转移不是同步的，而是由后台任务来协调故障转移。它旨在限制故障转移期间集群的数据丢失和不可用。此命令类似于非集群 Keybyte的CLUSTER FAILOVER命令，类似于 sentinel 提供的故障转移支持。

默认故障转移流程的具体细节如下：

master 将在内部启动一个CLIENT PAUSE WRITE，这将暂停传入的写入并防止在复制流中积累新数据。
主节点将监视其副本，等待副本表明它已完全消耗了复制流。如果 master 有多个副本，它只会等待第一个副本赶上。
然后主服务器将自己降级为副本。这样做是为了防止任何双主场景。注意：master 不会丢弃它的数据，因此如果副本在下一步中拒绝故障转移请求，它将能够回滚。
之前的master会向目标副本发送一个特殊的PSYNC请求PSYNC FAILOVER，指示目标副本成为master。
一旦前一个主机收到确认PSYNC FAILOVER并被接受，它将取消暂停其客户端。如果 PSYNC 请求被拒绝，master 将中止故障转移并恢复正常。

字段master_failover_stateinINFO replication可用于跟踪故障转移的当前状态，它具有以下值：

no-failover：没有正在进行的协调故障转移。
waiting-for-sync：master 正在等待副本赶上其复制偏移量。
failover-in-progress: master 已经降级了，并试图将所有权移交给目标副本。

如果之前的 master 附加了额外的副本，它们将继续从它作为链式副本进行复制。您将需要在这些副本上手动执行REPLICAOF以直接从新主服务器开始复制。

可选参数

存在以下可选参数来修改故障转移流的行为：

TIMEOUT 毫秒- 此选项允许指定主waiting-for-sync服务器在中止故障转移尝试和回滚之前将在该状态下等待的最长时间。这旨在为 Keybyte 集群可能遇到的写中断设置上限。故障转移通常会在不到一秒的时间内发生，但如果存在大量写入流量或副本已经落后于使用复制流，则可能需要更长时间。如果未指定此值，则超时可被视为“无限”。
TO 主机端口——此选项允许通过主机和端口指定要故障转移到的特定副本。master 将专门等待此副本赶上其复制偏移量，然后故障转移到它。
FORCE-- 如果同时设置了TIMEOUT和TO选项，则强制标志也可用于指定一旦超时过去，主服务器应故障转移到目标副本而不是回滚。这可用于在不丢失数据的情况下进行故障转移时的最大努力尝试，但可以限制写入中断。

注意：如果PSYNC FAILOVER请求被目标副本拒绝，主节点将始终回滚。

故障转移中止

故障转移命令旨在避免数据丢失和损坏，但可能会遇到一些无法自动修复并可能卡住的情况。为此，FAILOVER ABORT存在该命令，它将中止正在进行的故障转移并将主服务器返回到其正常状态。该命令在waiting-for-sync状态下发出没有副作用，但可以在状态下引入多主场景failover-in-progress。如果遇到多主的场景，你需要手动识别哪个主拥有最新的数据，并将其指定为主并拥有其他副本。

注意：在进行故障转移时禁用REPLICAOF，这是为了防止可能导致数据丢失的与故障转移的意外交互。

返回值

简单字符串回复：OK如果命令被接受并且协调故障转移正在进行中。如果操作无法执行，则会出现错误。

FLUSHALL

删除所有现有数据库的所有键，而不仅仅是当前选择的键。这个命令永远不会失败。

默认情况下，FLUSHALL将同步刷新所有数据库。Keybyte将lazyfree-lazy-user-flush配置指令设置为“yes”会将默认刷新模式更改为异步。

可以使用以下修饰符之一来明确指定刷新模式：

ASYNC: 异步刷新数据库
SYNC: 同步刷新数据库

注意：异步FLUSHALL命令仅删除调用该命令时存在的键。在异步刷新期间创建的键将不受影响。

返回值

简单的字符串回复

FLUSHDB

删除当前选定数据库的所有键。这个命令永远不会失败。

默认情况下，FLUSHDB将同步刷新数据库中的所有键。Keybyte将lazyfree-lazy-user-flush配置指令设置为“yes”会将默认刷新模式更改为异步。

可以使用以下修饰符之一来明确指定刷新模式：

ASYNC: 异步刷新数据库
SYNC: 同步刷新数据库

注意：异步FLUSHDB命令仅删除调用该命令时存在的键。在异步刷新期间创建的键将不受影响。

返回值

简单的字符串回复

INFO

该INFO命令返回的信息和统计信息的格式很简单通过计算机来分析和容易被人读取服务器。

可选参数可用于选择特定信息部分：

server: Keybyte 服务器的一般信息
clients: 客户端连接部分
memory: 内存消耗相关信息
persistence：KDB和AOF相关信息
stats: 一般统计
replication: 主/副本复制信息
cpu：CPU消耗统计
commandstats: Keybyte 命令统计
cluster：Keybyte集群部分
modules: 模块部分
keyspace: 数据库相关统计
modules: 模块相关部分
errorstats: Keybyte 错误统计
它还可以采用以下值：
all: 返回所有部分（不包括模块生成的部分）
default: 仅返回默认的部分集
everything: 包括all和modules

如果未提供参数，default则假定该选项。

返回值

批量字符串回复：作为文本行的集合。

行可以包含节名称（以 # 字符开头）或属性。所有的属性都是以field:value结尾的形式\r\n。

LASTSAVE

返回上次成功执行的 DB 保存的 UNIX TIME。客户端可以检查BGSAVE命令是否成功读取LASTSAVE值，然后发出BGSAVE命令并每隔 N 秒定期检查LASTSAVE 是否更改。

返回值

整数回复：一个 UNIX 时间戳。

LATENCY DOCTOR

该命令是延迟监控框架中最强大的分析工具，能够提供额外的统计数据，例如延迟峰值之间的平均周期、中值偏差和人类可读的事件分析。对于某些事件，例如fork，提供了附加信息，例如系统分叉进程的速率。

如果您正在寻找有关延迟相关问题的帮助，则应在 Keybyte 邮件列表中发布此输出。

127.0.0.1:6379> latency doctor



 

Dave, I have observed latency spikes in this Redis
instance.

You don't mind talking about it, do you Dave?



 

1. command: 5 latency spikes (average 300ms, mean deviation
120ms,

    period 73.40 sec). Worst all time event 500ms.



 

I have a few advices for you:



 

- Your current Slow Log configuration only logs events that
are

    slower than your configured latency monitor threshold.
Please

    use 'CONFIG SET slowlog-log-slower-than 1000'.

- Check your Slow Log to understand what are the commands you
are

    running which are too slow to execute. Please
check

    http://redis.io/commands/slowlog for more
information.

- Deleting, expiring or evicting (because of maxmemory
policy)

    large objects is a blocking operation. If you have very
large

    objects that are often deleted, expired, or evicted, try
to

    fragment those objects into multiple smaller objects.

返回值

批量字符串回复

LATENCY GRAPH

为指定的事件生成 ASCII 艺术风格的图形。

LATENCY GRAPHevent通过最先进的可视化让您直观地了解延迟趋势。它可用于在求助于解析来自LATENCY HISTORY或外部工具的原始数据等手段之前快速掌握情况。

有效值为event： active-defrag-cycle aof-fsync-always aof-stat aof-rewrite-diff-write aof-rename aof-write aof-write-active-child aof-write-alone aof-write-pending-fsync command expire-cycle eviction-cycle eviction-del fast-command * fork *KDB-unlink-temp-file

127.0.0.1:6379> latency reset command

(integer) 0

127.0.0.1:6379> debug sleep .1

OK

127.0.0.1:6379> debug sleep .2

OK

127.0.0.1:6379> debug sleep .3

OK

127.0.0.1:6379> debug sleep .5

OK

127.0.0.1:6379> debug sleep .4

OK

127.0.0.1:6379> latency graph command

command - high 500 ms, low 101 ms (all time high 500
ms)

--------------------------------------------------------------------------------

   #_

  _||

 _|||

_||||

11186

542ss

sss

每个图表列下的垂直标签代表事件发生前的秒、分钟、小时或天数。例如，“15s”表示第一个图形事件发生在 15 秒前。

该图在 min-max 范围内标准化，因此零（下一行中的下划线）是最小值，而较高行中的 # 是最大值。

返回值

批量字符串回复

LATENCY HELP

该命令返回描述不同子命令的有用文本。
返回值

数组回复：子命令列表及其描述

LATENCY HISTORY

返回的原始数据event的延迟高峰的时间序列。

这对于想要获取原始数据以执行监视、显示图形等的应用程序很有用。

该命令将最多返回 160 个时间戳-延迟对event。

127.0.0.1:6379> latency history command

1) 1) (integer) 1405067822

   2) (integer) 251

2) 1) (integer) 1405067941

   2) (integer) 1001

返回值

数组回复：特别是：

该命令返回一个数组，其中每个元素都是一个由两个元素组成的数组，表示事件的时间戳和延迟。

LATENCY LATEST

该命令会报告记录的最新延迟事件。每个报告的事件有以下字段:

事件名称。
事件的最新延迟峰值的 Unix 时间戳。
以毫秒为单位的最新事件延迟。
此事件的历史最大延迟。

“所有时间”表示自 Keybyte 实例启动以来的最大延迟，或事件重置的时间LATENCY RESET。

例子：

127.0.0.1:6379> debug sleep 1

OK

(1.00s)

127.0.0.1:6379> debug sleep .25

OK

127.0.0.1:6379> latency latest

1) 1) "command"

   2) (integer) 1405067976

   3) (integer) 251

   4) (integer) 1001

返回值

数组回复：特别是：

该命令返回一个数组，其中每个元素都是一个四元素数组，表示事件的名称、时间戳、最新和所有时间延迟测量。

LATENCY RESET

该命令重置等待时间尖峰时间序列的全部或仅一些事件。

当不带参数调用该命令时，它会重置所有事件，丢弃当前记录的延迟尖峰事件，并重置最大事件时间寄存器。

通过提供event名称作为参数，可以仅重置特定事件。

返回值

整数回复：被重置的事件时间序列的数量。

LOLWUT

LOLWUT 想提醒大家，编程不仅仅是为了创建一些有用的东西而将一些代码放在一起。每个 LOLWUT 版本都应具有以下属性：

它应该显示一些计算机艺术。只要输出在正常终端显示中运行良好，就没有限制。然而，输出不应仅限于图形（就像 LOLWUT 5 和 6 实际所做的那样），还可以是生成诗歌和其他非图形的东西。
LOLWUT 输出应该完全没用。显示一些有用的 Keybyte 内部指标不算作有效的 LOLWUT。
LOLWUT 输出应该快速生成，以便可以在生产实例中调用该命令而不会出现问题。即使用户使用奇数参数进行实验，它也应该保持快速。
LOLWUT 实现应该是安全的，并仔细检查安全性，并在接受参数时抵制不受信任的输入。
LOLWUT 必须始终在最后显示 Keybyte 版本。

返回值

批量字符串回复：包含生成计算机艺术的字符串，以及带有 Keybyte 版本的文本。

MEMORY DOCTOR

该命令报告Keybyte服务器遇到的不同内存相关问题，并提出可能的补救措施。

返回值

大部分字符串回复

MEMORY HELP

MEMORY HELP命令返回描述不同子命令的有用文本。

返回值

数组回复：子命令列表及其描述

MEMORY MALLOC-STATS

提供了一个内部统计从存储器分配器报告。

此命令目前仅在使用jemalloc作为分配器时实现，并且对所有其他命令评估为良性 NOOP。

返回值

批量字符串回复：内存分配器的内部统计报告

MEMORY PURGE

命令尝试清除脏页，以便分配器可以回收这些脏页。
该命令目前仅在使用jemalloc作为分配器时执行，并且对所有其他分配器计算为良性NOOP。

返回值

简单的字符串的回复

MEMORY STATS

命令返回一个阵列答复有关服务器的存储器使用量。

有关内存使用情况的信息作为指标及其各自的值提供。报告了以下指标：

peak.allocated：Keybyte 消耗的峰值内存（以字节为单位）（参见INFO的 used_memory_peak）
total.allocated：Keybyte 使用其分配器分配的总字节数（请参阅INFO的used_memory）
startup.allocated：Keybyte 在启动时消耗的初始内存量（以字节为单位）（参见INFO的used_memory_startup）
replication.backlog：在复制积压字节大小（见 INFO的repl_backlog_active）
clients.slaves：所有副本开销（输出和查询缓冲区、连接上下文）的总大小（以字节为单位）
clients.normal：所有客户端开销（输出和查询缓冲区、连接上下文）的总大小（以字节为单位）
aof.buffer：在当前和重写AOF缓冲器的字节大小求和（参见INFO的aof_buffer_length和aof_rewrite_buffer_length，分别地）
lua.caches：Lua 脚本缓存开销的总和大小（以字节为单位）
dbXXX：对于每个服务器的数据库，主字典和过期字典（分别为overhead.hashtable.main和 overhead.hashtable.expires）的开销以字节为单位报告
overhead.total：所有开销总和,例如startup.allocated， replication.backlog，clients.slaves，clients.normal，aof.buffer和那些在管理Keybyte的key空间中使用的内部数据结构（参见INFO的used_memory_overhead）
keys.count：服务器中所有数据库中存储的key总数
keys.bytes-per-key：净内存使用量（total.allocated 减startup.allocated）和keys.count
dataset.bytes：数据集的字节大小，即overhead.total 减去total.allocated（参见INFO的used_memory_dataset）
dataset.percentage:dataset.bytes出净内存使用的百分比
peak.percentage：百分比peak.allocated出来的 total.allocated
fragmentation: 见INFO的mem_fragmentation_ratio

返回值

数组回复：内存使用指标及其值的嵌套列表

关于本手册页中使用的 slave 一词的说明：如果不是为了向后兼容，Keybyte 项目不再使用 slave 一词。不幸的是，在这个命令中，slave 这个词是协议的一部分，所以只有当这个 API 自然被弃用时，我们才能删除此类事件。

MEMORY USAGE

命令报告键及其值需要存储在RAM中的字节数。

报告的使用情况是键值所需的数据和管理开销的内存分配总数。

对于嵌套数据类型，SAMPLES可以提供可选选项，其中 count是采样嵌套值的数量。默认情况下，此选项设置为5。要对所有嵌套值进行采样，请使用SAMPLES 0.

例子

使用 Keybyte v4.0.1 64 位和jemalloc，空字符串测量如下：

> SET "" ""

OK

> MEMORY USAGE ""

(integer) 51

由于没有存储实际数据，这些字节目前是纯粹的开销，用于维护服务器的内部数据结构。更长的键和值显示渐近线性用法。

> SET foo bar

OK

> MEMORY USAGE foo

(integer) 54

> SET cento
01234567890123456789012345678901234567890123

45678901234567890123456789012345678901234567890123456789

OK

127.0.0.1:6379> MEMORY USAGE cento

(integer) 153

返回值

整数回复：以字节为单位的内存使用情况，或者nil当key不存在时。

MODULE LIST

返回有关加载到服务器的模块的信息。

返回值

数组回复：已加载模块的列表。列表中的每个元素都代表一个模块，并且本身就是一个属性名称及其值的列表。为每个加载的模块报告以下属性：

name: 模块名称
ver: 模块版本

MODULE LOAD

在运行时从动态库加载模块。

此命令从path参数指定的动态库加载并初始化 Keybyte 模块。此path应该是图书馆的绝对路径，包括完整的文件名。任何附加参数都未经修改地传递给模块。

注：模块也可以在服务器启动时加载loadmodule 的配置指令redis.conf。

返回值

简单的字符串回复：OK如果模块已加载。

MODULE UNLOAD

卸载模块。

此命令卸载由指定的模块name。请注意，模块的名称由MODULE LIST命令报告，并且可能与动态库的文件名不同。

已知限制：

无法卸载注册自定义数据类型的模块。

返回值

简单的字符串回复：OK如果模块已卸载。

MONITOR

流回 Keybyte 服务器处理的每个命令。它可以帮助了解数据库发生了什么。该命令可以通过 viaredis-cli和 via 使用telnet。

在将 Keybyte 用作数据库和分布式缓存系统时，查看服务器处理的所有请求的能力对于发现应用程序中的错误非常有用。

$ redis-cli monitor

1339518083.107412 [0 127.0.0.1:60866] "keys" "*"

1339518087.877697 [0 127.0.0.1:60866] "dbsize"

1339518090.420270 [0 127.0.0.1:60866] "set" "x" "6"

1339518096.506257 [0 127.0.0.1:60866] "get" "x"

1339518099.363765 [0 127.0.0.1:60866] "del" "x"

1339518100.544926 [0 127.0.0.1:60866] "get" "x"

使用SIGINT（按Ctrl-C）停止MONITOR通过运行流redis-cli。

$ telnet localhost 6379

Trying 127.0.0.1...

Connected to localhost.

Escape character is '^]'.

MONITOR

+OK

+1339518083.107412 [0 127.0.0.1:60866] "keys" "*"

+1339518087.877697 [0 127.0.0.1:60866] "dbsize"

+1339518090.420270 [0 127.0.0.1:60866] "set" "x" "6"

+1339518096.506257 [0 127.0.0.1:60866] "get" "x"

+1339518099.363765 [0 127.0.0.1:60866] "del" "x"

+1339518100.544926 [0 127.0.0.1:60866] "get" "x"

QUIT

+OK

Connection closed by foreign host.

手动发出QUIT或RESET命令停止MONITOR通过运行流telnet。

MONITOR 未记录的命令

出于安全考虑，MONITOR的输出不会记录所有管理命令。

此外，以下命令也不会被记录：

AUTH
EXEC
HELLO
QUIT

运行 MONITOR 的成本

因为MONITOR 会流回所有命令，所以它的使用是有代价的。以下（完全不科学的）基准数据说明了运行MONITOR的成本。

没有运行MONITOR 的基准测试结果：

$ src/redis-benchmark -c 10 -n 100000 -q

PING_INLINE: 101936.80 requests per second

PING_BULK: 102880.66 requests per second

SET: 95419.85 requests per second

GET: 104275.29 requests per second

INCR: 93283.58 requests per second

基准测试结果与 MONITOR运行（redis-cli monitor > /dev/null）：

$ src/redis-benchmark -c 10 -n 100000 -q

PING_INLINE: 58479.53 requests per second

PING_BULK: 59136.61 requests per second

SET: 41823.50 requests per second

GET: 45330.91 requests per second

INCR: 41771.09 requests per second

在这种特殊情况下，运行单个MONITOR客户端可以将吞吐量降低 50% 以上。运行更多MONITOR客户端将进一步降低吞吐量。

返回值

非标准返回值，只是在无限流中转储接收到的命令。

PSYNC

从主服务器启动复制流。

该PSYNC命令由Keybyte的副本调用，用于从主复制流发起[#OLE_LINK13]复制流。

返回值

非标准返回值，用PING对数据进行批量传输，并写入来自master的请求。

REPLICAOF

该REPLICAOF命令可以动态改变一个副本的复制设置。

如果 Keybyte 服务器已经充当副本，则命令REPLICAOF NO ONE 将关闭复制，将 Keybyte 服务器变为 MASTER。以正确的形式REPLICAOF主机名端口将使服务器成为在指定主机名和端口上侦听的另一台服务器的副本。

如果服务器已经是某个主服务器的副本，REPLICAOF主机名端口将停止针对旧服务器的复制并开始针对新服务器的同步，丢弃旧数据集。

REPLICAOF NO ONE形式将停止复制，将服务器变成 MASTER，但不会丢弃复制。因此，如果旧的 master 停止工作，则可以将副本变成 master 并将应用程序设置为在读/写中使用这个新的 master。稍后当其他 Keybyte 服务器修复后，可以将其重新配置为副本。

返回值

简单的字符串回复

ROLE

通过返回实例当前是 master、slave 或是 sentinel 节点，提供关于 Keybyte 实例在复制上下文中的角色的信息。该命令还返回有关复制状态的附加信息（如果角色是 master 或 slave）或受监控的 master 名称列表（如果角色是 sentinel）。slavesentinel

输出格式

该命令返回一个元素数组。第一个元素是实例的角色，作为以下三个字符串之一：

"master"
"slave"
"sentinel"

数组的附加元素取决于角色。

主输出

在主实例中调用ROLE时的输出示例：

1) "master"

2) (integer) 3129659

3) 1) 1) "127.0.0.1"

      2) "9001"

      3) "3129242"

   2) 1) "127.0.0.1"

      2) "9002"

      3) "3129543"

主输出由以下部分组成：

字符串master。
当前 master 复制偏移量，这是 masters 和 replicas 共享的偏移量，以了解在部分重新同步中，副本需要获取的复制流部分才能继续。
由三个元素组成的数组，表示连接的副本。每个子阵列都包含副本 IP、端口和最后确认的复制偏移量。

命令在副本上的输出

在副本实例中调用ROLE时的输出示例：

1) "slave"

2) "127.0.0.1"

3) (integer) 9000

4) "connected"

5) (integer) 3167038

副本输出由以下部分组成：

字符串slave，因为向后兼容（请参阅本页末尾的注释）。
主人的IP。
主站的端口号。
从 master 的角度来看复制的状态，可以是connect（实例需要连接到它的 master），connecting（master-replica 连接正在进行），sync（master 和 replica 正在尝试执行同步), connected（副本在线）。
到目前为止从副本接收到的数据量，就主复制偏移而言。

Sentinel输出

Sentinel 输出示例：

1) "sentinel"

2) 1) "resque-master"

   2) "html-fragments-master"

   3) "stats-master"

   4) "metadata-master"

Sentinel输出由以下部分组成：

字符串sentinel。
此 Sentinel 实例监视的主名称数组。

返回值

阵列答复：其中所述第一元件是一个master，slave，sentinel和如上所示的附加元件是角色的特定。

SAVE

执行数据集的同步保存，生成Keybyte实例中所有数据的时间点快照，以KDB文件的形式。

您几乎不想在生产环境中调用SAVE，因为它会阻止所有其他客户端。相反，通常使BGSAVE。但是，如果出现阻止 Keybyte 创建后台保存子项的问题（例如 fork(2) 系统调用中的错误），则SAVE命令可能是执行最新数据集转储的最后手段。

有关详细信息，请参阅持久性文档。

返回值

简单字符串回复：命令在成功时返回 OK。

SHUTDOWN

命令行为如下：

停止所有客户端。
如果至少配置了一个保存点，则执行阻塞保存。
如果启用了 AOF，则刷新仅附加文件。
退出服务器。

如果启用持久性，此命令可确保 Keybyte 关闭而不会丢失任何数据。如果客户端仅使用SAVE然后QUIT，则无法保证这一点，因为其他客户端可能会更改这两个命令之间的 DB 数据。

注意：配置为不在磁盘上持久化的 Keybyte 实例（未配置 AOF 或“保存”指令）不会在SHUTDOWN上转储 KDB 文件，因为通常您不希望仅用于缓存的 Keybyte 实例在以下情况下阻塞关闭。

SAVE 和 NOSAVE 修饰符

可以指定一个可选的修饰符来改变命令的行为。具体来说：

即使没有配置保存点，SHUTDOWN SAVE也会强制执行数据库保存操作。
即使配置了一个或多个保存点，SHUTDOWN NOSAVE也会阻止数据库保存操作。（您可以将此变体视为只是停止服务器的假设ABORT命令）。

SHUTDOWN 失败的情况

启用仅附加文件后，关闭可能会失败，因为系统处于不允许立即安全地保留在磁盘上的状态。

通常如果有一个 AOF 子进程执行 AOF 重写，Keybyte 会简单地关闭它并退出。然而，在两种情况下这样做是不安全的，并且SHUTDOWN命令将被拒绝并出现错误。这发生在：

用户刚开启AOF，服务器触发了第一次AOF重写，以创建初始AOF文件。在这种情况下，停止将导致数据集完全丢失：一旦重新启动，服务器可能会启用 AOF，而根本没有任何 AOF 文件。
启用了 AOF 的副本，重新与其主服务器连接，执行完全重新同步，并重新启动 AOF 文件，触发初始 AOF 创建过程。在这种情况下，不完成 AOF 重写是危险的，因为从 master 收到的最新数据集将丢失。新的 master 实际上甚至可以是一个不同的实例（如果使用REPLICAOF或SLAVEOF命令来重新配置副本），因此完成 AOF 重写并从代表内存中数据集的正确数据集开始很重要服务器被终止。

在某些情况下，我们只想尽快终止 Keybyte 实例，而不管其内容是什么。在这种情况下，正确的命令组合是发送CONFIG appendonly no后跟SHUTDOWN NOSAVE。如果需要，第一个命令将关闭 AOF，如果有一个活动，将终止 AOF 重写子进程。由于不再启用 AOF，因此第二个命令执行起来不会有任何问题。

返回值

简单的字符串回复错误。成功后，由于服务器退出并关闭连接，因此不会返回任何内容。

SLAVEOF

关于本手册页中使用的单词 slave 和命令名称的说明：如果不是为了向后兼容，Keybyte 项目不再使用单词 slave。请使用新命令REPLICAOF。命令SLAVEOF将继续工作以实现向后兼容性。

该SLAVEOF命令可以动态改变一个副本的复制设置。如果 Keybyte 服务器已经充当副本，则命令SLAVEOF NO ONE 将关闭复制，将 Keybyte 服务器变为 MASTER。以正确的形式SLAVEOF主机名端口将使服务器成为在指定主机名和端口上侦听的另一台服务器的副本。

如果服务器已经是某个主服务器的副本，则SLAVEOF主机名端口将停止针对旧服务器的复制并开始针对新服务器的同步，丢弃旧数据集。

形式SLAVEOF NO ONE 将停止复制，将服务器变成 MASTER，但不会丢弃复制。因此，如果旧的 master 停止工作，则可以将副本变成 master 并将应用程序设置为在读/写中使用这个新的 master。稍后当其他 Keybyte 服务器修复后，可以将其重新配置为副本。

返回值

简单的字符串回复

SLOWLOG

此命令用于读取和重置 Keybyte 慢查询日志。

Keybyte 慢日志概述

Keybyte 慢日志是一种记录超过指定执行时间的查询的系统。执行时间不包括与客户端通话、发送回复等 I/O 操作，而只是实际执行命令所需的时间（这是命令执行的唯一阶段，线程被阻塞且无法执行）同时处理其他请求）。

您可以使用两个参数配置慢日志：slowlog-log-slower-than 告诉 Keybyte 执行时间是多少，以微秒为单位，以便记录命令。请注意，负数会禁用慢速日志，而零值会强制记录每个命令。 slowlog-max-len是慢日志的长度。最小值为零。当记录新命令并且慢速日志已达到其最大长度时，最旧的命令将从记录的命令队列中删除以腾出空间。

可以通过编辑redis.conf或在服务器运行时使用CONFIG GET和CONFIG SET命令来完成配置。

读取慢日志

慢日志在内存中累积，因此不会写入包含慢命令执行信息的文件。这使得慢日志非常快，因为您可以启用所有命令的日志记录（将slowlog-log-slower-than配置参数设置为零），但性能受到轻微影响。

要读取慢日志，使用SLOWLOG GET命令，该命令返回慢日志中的每个条目。可以只返回 N 个最近的条目，并将附加参数传递给命令（例如SLOWLOG GET 10）。默认请求长度为 10（省略参数时）。可以通过 -1 来获取整个慢日志。

请注意，您需要最新版本的 redis-cli 才能读取慢速日志输出，因为它使用了以前未在 redis-cli 中实现的协议的某些功能（深度嵌套的多批量回复）。

输出格式

redis 127.0.0.1:6379> slowlog get 2

1) 1) (integer) 14

   2) (integer) 1309448221

   3) (integer) 15

   4) 1) "ping"

2) 1) (integer) 13

   2) (integer) 1309448128

   3) (integer) 30

   4) 1) "slowlog"

      2) "get"

      3) "100"

5) "127.0.0.1:58217"

6) "worker-123"

每个条目由四个或六个字段组成：

每个慢速日志条目的唯一累进标识符。
处理记录命令的 Unix 时间戳。
执行所需的时间量，以微秒为单位。
组成命令参数的数组。
客户端 IP 地址和端口（仅限 4.0）。
客户端名称，如果通过CLIENT SETNAME命令设置（仅限 4.0）。

可以使用条目的唯一 ID 以避免多次处理慢速日志条目（例如，您可能有一个脚本，为每个新的慢速日志条目向您发送电子邮件警报）。

ID在Keybyte服务器执行过程中不会重置，只有服务器重启才会重置。

获取慢日志的当前长度

可以使用命令SLOWLOG LEN仅获取慢日志的长度。

重置慢日志

您可以使用SLOWLOG RESET命令重置慢速日志。一旦删除，信息将永远丢失。

SWAPDB

此命令交换两个 Keybyte 数据库，以便连接到给定数据库的所有客户端立即看到另一个数据库的数据，反之亦然。示例：

SWAPDB 0 1

这会将数据库 0 与数据库 1 交换。所有与数据库 0 连接的客户端将立即看到新数据，就像所有与数据库 1 连接的客户端将看到以前来自数据库 0 的数据一样。

返回值

简单字符串回复：OK如果SWAPDB执行正确。

例子

SWAPDB 0 1

SYNC

从主服务器启动复制流。

的SYNC命令由Keybyte的称为复制品，用于从主发起复制流。它已在较新版本的 Keybyte 中被PSYNC取代。

有关 Keybyte 中复制的更多信息，请查看复制页面。

返回值

非标准返回值，数据的批量传输，然后是PING和来自主机的写请求。

TIME

TIME命令以两项列表的形式返回当前服务器时间:Unix时间戳和当前秒内已经经过的微秒数。基本上接口非常类似于gettimeofday系统调用之一。

返回值

数组回复，具体如下：

包含两个元素的多批量回复：

以秒为单位的 unix 时间。
微秒。

Sets

SADD

将指定的成员添加到key存储的集合中。已经是此集合成员的指定成员将被忽略。如果key不存在，则在添加指定成员之前创建一个新集。

当存储的值key不是集合时返回错误。

返回值

整数回复：添加到集合中的元素数，不包括集合中已经存在的所有元素。

SCARD

返回存储在key上的集合的基数(元素的数量)。

返回值

整数回复：集合的基数（元素数），0如果key 不存在。

SDIFF

返回由第一个集合和所有后续集合之间的差异产生的集合成员。

例如：

key1 = \{a,b,c,d}

key2 = \{c}

key3 = \{a,c,e}

SDIFF key1 key2 key3 = \{b,d}

不存在的键被认为是空集。

返回值

数组回复：包含结果集成员的列表。

SDIFFSTORE

此命令等于SDIFF，但不是返回结果集，而是存储在destination.

如果destination已经存在，则将其覆盖。

返回值

整数回复：结果集中的元素数。

SINTER

返回由所有给定集合的交集产生的集合成员。

例如：

key1 = \{a,b,c,d}

key2 = \{c}

key3 = \{a,c,e}

SINTER key1 key2 key3 = \{c}

不存在的键被认为是空集。由于其中一个键是空集，结果集也是空的（因为集与空集的交集总是导致空集）。

返回值

数组回复：包含结果集成员的列表。

SINTERCARD

返回由所有给定集合的交集产生的集合的基数。

不存在的键被认为是空集。由于其中一个键是空集，结果集也是空的（因为集与空集的交集总是导致空集）。

返回值

整数回复：结果交集中的元素数。

SINTERSTORE

此命令等于SINTER，但不是返回结果集，而是存储在destination.

如果destination已经存在，则将其覆盖。

返回值

整数回复：结果集中的元素数。

SISMEMBER

如果member是存储在key上的集合的成员，则返回。

返回值

整数回复，特别是：

如果元素是集合的成员,则返回1。
如果元素不是集合的成员，或者key不存在，返回0。

SMEMBERS

返回存储在key的设置值的所有成员。

这与使用一个参数运行SINTER 的效果相同key。

返回值

数组回复：集合的所有元素。

SMISMEMBER

返回每个是否member是存储在的集合的成员key。

对于 each member，1如果值是集合的成员，或者0元素不是集合的成员或key不存在，则返回。

返回值

数组回复：表示给定元素的成员资格的列表，其顺序与请求的顺序相同。

SMOVE

member从集合处移动source到集合处destination。这个操作是原子的。在每个给定的时刻，该元素似乎是其他客户的成员source 或 destination为其他客户服务。

如果源集不存在或不包含指定元素，则不执行任何操作并0返回。否则，元素将从源集中删除并添加到目标集中。当指定的元素已经存在于目标集中时，它只会从源集中移除。

如果source或destination不保存设置值，则返回错误。

返回值

整数回复，特别是：

1：如果元素被移动。
0：如果元素不是source的成员并且未执行任何操作。

SPOP

从设置值存储中删除并返回一个或多个随机成员key。

此操作类似于SRANDMEMBER，它从集合中返回一个或多个随机元素但不删除它。

默认情况下，该命令从集合中弹出一个成员。当提供可选count参数时，回复将最多包含count成员，具体取决于集合的基数。

返回值

当不带count参数调用时：

批量字符串回复：被移除的成员，或nil何时key不存在。

当使用count参数调用时：

数组回复：删除的成员，或者key不存在时为空数组。

SRANDMEMBER

当仅使用key参数调用时，从存储在key的设置值中返回一个随机元素。

如果提供的count参数为正数，则返回不同元素的数组。数组的长度是count或集合的基数 ( SCARD )，以较低者为准。

如果使用负数调用count，则行为会发生变化，并且该命令可以多次返回相同的元素。在这种情况下，返回元素的数量是指定的绝对值count。

返回值

批量字符串回复：如果没有附加count参数，该命令将返回带有随机选择元素的批量回复，或者nil当key不存在时返回。

数组回复：当count传递附加参数时，命令返回一个元素数组，或者当key不存在时返回一个空数组。

SREM

从存储在key的集合中删除指定的成员。不属于此集合的指定成员将被忽略。如果key不存在，则将其视为空集，此命令返回 0。

当存储的值key不是集合时返回错误。

返回值

整数回复：从集合中删除的成员数，不包括不存在的成员。

SSCAN

见SCAN为SSCAN文档。

SUNION

返回由所有给定集合的并集产生的集合成员。

例如：

key1 = \{a,b,c,d}

key2 = \{c}

key3 = \{a,c,e}

SUNION key1 key2 key3 = \{a,b,c,d,e}

不存在的键被认为是空集。

返回值

数组回复：包含结果集成员的列表。

SUNIONSTORE

此命令等于SUNION，但不是返回结果集，而是存储在destination.

如果destination已经存在，则将其覆盖。

返回值

整数回复：结果集中的元素数。

Sorted Sets

BZPOPMAX

BZPOPMAX是有序集ZPOPMAX原语的阻塞变体。

它是阻塞版本，因为当没有成员可以从任何给定的排序集中弹出时，它会阻塞连接。从第一个非空的已排序集合中弹出得分最高的成员，并按照给定的顺序检查给定的键。

该timeout参数被解释为一个 double 值，指定要阻止的最大秒数。零超时可用于无限期阻塞。

见BZPOPMIN文档的确切语义，因为BZPOPMAX 是相同的BZPOPMIN唯一的区别是它弹出得分最高的，而不是弹出得分最低的那些成员。

返回值

数组回复：特别是：

当没有元素可以弹出和超时过期时，回复ni* multi-bulk。
一个三元素多块，第一个元素是弹出成员的键的名称，第二个元素是弹出成员本身，第三个元素是弹出元素的分数。

例子

redis> DEL zset1 zset2

(integer) 0

redis> ZADD zset1 0 a 1 b 2 c

(integer) 3

redis> BZPOPMAX zset1 zset2 0

1) "zset1"

2) "c"

3) "2"

BZPOPMIN

BZPOPMIN是有序集ZPOPMIN原语的阻塞变体。

它是阻塞版本，因为当没有成员可以从任何给定的排序集中弹出时，它会阻塞连接。从第一个非空的有序集合中弹出得分最低的成员，并按照给定的顺序检查给定的键。

该timeout参数被解释为一个 double 值，指定要阻止的最大秒数。零超时可用于无限期阻塞。

有关确切语义，请参阅BLPOP 文档，因为BZPOPMIN与BLPOP相同，唯一的区别是从中弹出的数据结构。

返回值

数组回复：特别是：

当没有元素可以弹出和超时过期时，回复ni* multi-bulk。
一个三元素多块，第一个元素是弹出成员的键的名称，第二个元素是弹出成员本身，第三个元素是弹出元素的分数。

例子

redis> DEL zset1 zset2

(integer) 0

redis> ZADD zset1 0 a 1 b 2 c

(integer) 3

redis> BZPOPMIN zset1 zset2 0

1) "zset1"

2) "a"

3) "0"

ZADD

将具有指定分数的所有指定成员添加到按键存储的排序集。可以指定多个分数/成员对。如果指定的成员已经是排序集的成员，则更新分数并在正确的位置重新插入元素以确保正确排序。

如果key不存在，则创建一个以指定成员作为唯一成员的新排序集，就像排序集为空一样。如果键存在但不包含排序集，则返回错误。

分数值应该是双精度浮点数的字符串表示形式。+inf和-inf值也是有效值。

ZADD 选项

ZADD 支持选项列表，在键名之后和第一个 score 参数之前指定。选项是：

XX : 只更新已经存在的元素。不要添加新元素。
NX：仅添加新元素。不要更新已经存在的元素。
LT：仅当新分数小于当前分数时才更新现有元素。此标志不会阻止添加新元素。
GT：仅当新分数大于当前分数时才更新现有元素。此标志不会阻止添加新元素。
CH：修改返回值，从新增元素的个数，到变化的元素总数（CH是changed的缩写）。更改的元素是添加的新元素和已更新分数的现有元素。因此，命令行中指定的具有与过去相同分数的元素不计算在内。注意：通常ZADD的返回值只计算添加的新元素的数量。
INCR：指定此选项时，ZADD 的作用类似于ZINCRBY。在这种模式下只能指定一个分数元素对。

注意：GT、LT和NX选项是互斥的。

可以精确表达的整数分数范围

Keybyte 排序集使用一个双 64 位浮点数来表示分数。在我们支持的所有架构中，这表示为IEEE 754 浮点数，能够精确表示介于-(2^53)和+(253)包含之间的整数。在更实际的术语中，-9007199254740992 和 9007199254740992 之间的所有整数都可以完美表示。较大的整数或分数在内部以指数形式表示，因此您可能只得到十进制数或设置为分数的非常大整数的近似值。

排序集 101

已排序的集合按其分数升序排序。同一个元素只存在一次，不允许重复元素。分数可以通过更新元素分数的ZADD修改，作为副作用，它在排序集中的位置，以及可以使用ZINCRBY修改分数，以便相对于其先前的值更新分数。

可以使用ZSCORE命令检索元素的当前分数，该命令还可用于验证元素是否已存在。

对于介绍的有序集合，请参阅数据类型页排序集。

分数相同的元素

虽然同一元素不能在排序集中重复，因为每个元素都是唯一的，但可以添加多个具有相同 score 的不同元素。当多个元素的score相同时，按字典序排列（仍然以score作为第一个key排序，但在本地，所有score相同的元素按字典序相对排序）。

使用的字典顺序是二进制的，它将字符串作为字节数组进行比较。

如果用户将排序集中的所有元素插入分数相同（例如 0），则排序集中的所有元素按字典顺序排序，并且可以使用命令ZRANGEBYLEX对元素进行范围查询（注：也可以使用ZRANGEBYSCORE按分数范围查询排序集）。

返回值

整数回复，特别是：

在不带可选参数的情况下使用时，添加到排序集中的元素数（不包括分数更新）。
如果CH指定了该选项，则更改（添加或更新）的元素数。
如果指定了INCR选项，则返回值将是Bulk string reply：
member（双精度浮点数）的新分数表示为字符串，或者nil操作是否中止（使用 theXX或NX选项调用时）。

ZCARD

返回存储在key的排序集的排序集基数（元素数）。

返回值

整数回复：排序集合的基数（元素数），0 如果key不存在。

ZCOUNT

返回排序集中的元素数，key分数介于min和之间 max。

该min和max作为描述参数具有相同的语义 ZRANGEBYSCORE。

注意：该命令的复杂度仅为O(log(N))，因为它使用元素等级（请参阅ZRANK）来了解范围。因此，不需要做与范围大小成比例的工作。

返回值

整数回复：指定分数范围内的元素数。

ZDIFF

此命令类似于ZDIFFSTORE，但不是存储结果排序集，而是将其返回给客户端。

返回值

数组回复：差异的结果（如果WITHSCORES给出了选项，可以选择使用他们的分数）。

ZDIFFSTORE

计算第一个和所有连续输入排序集之间的差值，并将结果存储在目标中。输入键的总数由numkeys指定。
不存在的键被认为是空集。
如果目的地已经存在，它将被覆盖。

返回值

在目标处得到的已排序集合中的元素数。

ZINCRBY

按increment递增存储在key处的已排序集合中成员的分数。如果成员在排序集中不存在，它将以递增值作为其分数(就像它之前的分数是0.0)。如果key不存在，则创建一个新的以指定成员作为唯一成员的排序集。
当key存在但没有保存已排序的集合时返回错误。
分数值应该是数字值的字符串表示形式，并接受双精度浮点数。可以提供一个负值来降低分数。

返回值
大容量字符串回复:成员(双精度浮点数)的新分数，表示为字符串。

ZINTER

此命令类似于ZINTERSTORE，但不是存储结果排序集，而是将其返回给客户端。

有关WEIGHTS和AGGREGATE选项的说明，请参阅ZUNIONSTORE。

返回值

数组回复：交集的结果（如果WITHSCORES给出了选项，可以选择他们的分数）。

ZINTERCARD

这个命令类似于ZINTER，但它不返回结果集，它只返回结果的基数。

不存在的键被认为是空集。由于其中一个键是空集，结果集也是空的（因为集与空集的交集总是导致空集）。

返回值

整数回复：结果交集中的元素数。

ZINTERSTORE

计算由指定键给出的numkeys排序集的交集，并将结果存储在目标。在传递输入键和其他(可选)参数之前，必须提供输入键(numkeys)的数量。
默认情况下，元素的最终分数是其在其存在的排序集合中的分数之和。因为交集要求一个元素是每个给定排序集的成员，这将导致结果排序集中每个元素的得分等于输入排序集的个数。

返回值

整数回复:结果排序集在目标的元素数。

ZLEXCOUNT

当排序集中的所有元素都以相同的分数插入时，为了强制按字典顺序排列，此命令将排序集中的元素数返回到键，并且值介于min和之间max。

该min和max参数具有作为描述的意思相同 ZRANGEBYLEX。

注意：该命令的复杂度仅为O(log(N))，因为它使用元素等级（请参阅ZRANK）来了解范围。因此，不需要做与范围大小成比例的工作。

返回值

整数回复：指定分数范围内的元素数。

ZMSCORE

返回与按键存储的已排序集合中指定成员关联的分数。
对于排序集合中不存在的每个成员，返回一个nil值。

返回值
数组回复:与指定的成员值(双精度浮点数)相关联的分数或空的列表，表示为字符串。

ZPOPMAX

删除并返回按键存储的排序集合中分数最高的成员数。
当不指定时，count的默认值是1。指定高于排序集基数的计数值不会产生错误。当返回多个元素时，得分最高的元素将排在第一位，后面是得分较低的元素。

返回值
数组回复:弹出元素和分数的列表。

ZPOPMIN

删除并返回按键存储的排序集合中分数最低的成员数。
当不指定时，count的默认值是1。指定高于排序集基数的计数值不会产生错误。当返回多个元素时，得分最低的元素将排在第一个，后面是得分较高的元素。

返回值
数组回复:弹出元素和分数的列表。

ZRANDMEMBER

当仅使用 key 参数调用时，从存储在 key 的排序集合值中返回一个随机元素。

如果提供的 count 参数为正数，则返回不同元素的数组。数组的长度是计数或排序集的基数 (ZCARD)，以较低者为准。

如果以负计数调用，则行为会发生变化，并且该命令可以多次返回相同的元素。在这种情况下，返回元素的数量是指定计数的绝对值。

可选的 WITHSCORES 修饰符更改回复，使其包括从排序集中随机选择的元素的相应分数。

返回值

批量字符串回复：没有额外的 count 参数，该命令返回一个随机选择的元素的批量回复，或者当 key 不存在时返回 nil。

数组回复：当传入额外的 count 参数时，该命令返回一个元素数组，或者当 key 不存在时返回一个空数组。如果使用 WITHSCORES 修饰符，则回复是一个列表元素及其排序集中的分数。

ZRANGE

返回存储在<键>处的已排序集合中指定的元素范围。

ZRANGE可以执行不同类型的范围查询：按索引（排名）、按分数或按字典顺序。

此命令可以替换以下命令：ZREVRANGE、ZRANGEBYSCORE、ZREVRANGEBYSCORE、ZRANGEBYLEX和ZREVRANGEBYLEX。

常见行为和选项

元素的顺序是从最低分到最高分。具有相同分数的元素按字典顺序排列。

可选REV参数颠倒顺序，因此元素从最高分到最低分排序，并且分数关系通过反向词典排序来解决。

可选LIMIT参数可用于从匹配元素中获取子范围（类似于SQL 中的SELECT LIMIT 偏移量、计数）。负数<count>返回中的所有元素<offset>。请记住，如果<offset>很大，则<offset>在到达要返回的元素之前需要遍历已排序的集合中的元素，这可能加起来为O(N)时间复杂度。

可选WITHSCORES参数用返回的元素分数补充命令的回复。返回的列表包含value1,score1,…,valueN,scoreN而不是value1,…,valueN。客户端库可以自由返回更合适的数据类型（建议：带有（值，分数）数组/元组的数组）。

索引范围

默认情况下，该命令执行索引范围查询。的<min>和<max>参数表示基于零的索引，其中0是第一要素，1是下一个元素，依此类推。这些参数指定一个包含范围，例如，ZRANGE myzset 0 1将返回排序集合的第一个和第二个元素。

索引也可以是负数，表示从排序集的末尾开始的偏移量，是排序集-1的最后一个元素、-2倒数第二个元素，依此类推。

超出范围的索引不会产生错误。

如果<min>大于排序集的结束索引或<max>，则返回一个空列表。

如果<max>大于排序集的结束索引，Keybyte 将使用排序集的最后一个元素。

分数范围

当BYSCORE提供该选项时，该命令的行为类似于ZRANGEBYSCORE并返回排序集中的元素范围，其分数等于或介于<min>和之间<max>。

<min>和<max>可以-inf和+inf，分别表示负无穷大和正无穷大。这意味着您不需要知道排序集中的最高或最低分数来获取从某个分数开始或达到某个分数的所有元素。

默认情况下，由<min>和指定的分数区间<max>是封闭的（包括）。可以通过在分数前加上字符来指定一个开放区间（独占）。

例如：

ZRANGE zset (1 5 BYSCORE

将使用1 < score ⇐ 5while返回所有元素：

ZRANGE zset (5 (10 BYSCORE

将返回带有5 < score < 10（5 和 10 除外）的所有元素。

字典范围

使用该BYLEX选项时，该命令的行为类似于ZRANGEBYLEX，并返回排序集中的元素范围<min>和<max>字典序闭区间区间。

请注意，字典顺序依赖于具有相同分数的所有元素。当元素具有不同的分数时，回复是未指定的。

有效<min>且<max>必须以(或开头[，以分别指定范围间隔是不包含还是包含。

+or- <min>和的特殊值<max>分别表示正和负无限字符串，因此例如命令ZRANGEBYLEX myzset - +保证返回排序集中的所有元素，前提是所有元素具有相同的分数。

字符串的字典序比较

字符串作为二进制字节数组进行比较。由于 ASCII 字符集的指定方式，这意味着通常这也具有以明显的字典方式比较普通 ASCII 字符的效果。但是，如果使用非纯 ASCII 字符串（例如 utf8 字符串），则情况并非如此。

但是，用户可以对编码字符串应用转换，以便插入到排序集中的元素的第一部分将按照用户对特定应用程序的要求进行比较。例如，如果我想添加会以不区分大小写的方式进行比较的字符串，但查询时仍然想检索真实的大小写，我可以通过以下方式添加字符串：

ZADD autocomplete 0 foo: Foo 0 bar: BAR 0 zap: zap

由于每个元素中的第一个标准化部分（在冒号字符之前），我们强制进行给定的比较。但是，在使用查询范围后ZRANGE … BYLEX，应用程序可以向用户显示字符串的第二部分，在冒号之后。

比较的二进制特性允许使用排序集作为通用索引，例如，元素的第一部分可以是 64 位大端数。由于 big-endian 数字在初始位置具有最高有效字节，因此二进制比较将匹配数字的数字比较。这可用于对 64 位值实施范围查询。如下例所示，在前 8 个字节之后，我们可以存储我们正在索引的元素的值。

返回值

数组回复：指定范围内的元素列表（如果WITHSCORES给出了选项，则可以选择带有它们的分数）。

ZRANGEBYLEX

当排序集中的所有元素都以相同的分数插入时，为了强制按字典顺序排列，此命令返回排序集中的所有元素 at key，其值介于min和之间max。

如果排序集中的元素具有不同的分数，则返回的元素是未指定的。

使用memcmp()C 函数逐字节比较时，元素被认为是从低到高的字符串排序。如果公共部分相同，则较长的字符串被认为大于较短的字符串。

目前此命令被视为已弃用。请更喜欢在新代码中使用带有参数的ZRANGE命令BYLEX。

可选LIMIT参数可用于仅获取匹配元素的范围（类似于SQL 中的SELECT LIMIT offset、count）。负数count 返回中的所有元素offset。请记住，如果offset很大，则offset在到达要返回的元素之前需要遍历已排序的集合中的元素，这可能加起来为 O(N)时间复杂度。

如何指定间隔

有效的启动和停止必须开始(或以指定该范围的项目分别是排他性或包容性。用于start和stop的特殊值+or具有特殊含义或正无限和负无限字符串，因此例如命令ZRANGEBYLEX myzset - +保证返回排序集中的所有元素，如果所有元素具有相同的分数.-

字符串比较的详细信息

然而，用户可以对编码字符串应用转换，以便插入到排序集中的元素的第一部分将按照用户对特定应用程序的要求进行比较。例如，如果我想添加将以不区分大小写的方式进行比较的字符串，但我在查询时仍然想检索真实的大小写，我可以通过以下方式添加字符串：

ZADD autocomplete 0 foo: Foo 0 bar: BAR 0 zap: zap

由于每个元素中的第一个规范化部分（在冒号字符之前），我们强制进行给定的比较，但是在使用ZRANGEBYLEX查询范围之后，应用程序可以向用户显示字符串的第二部分，在冒号之后。

比较的二进制性质允许使用排序集作为通用索引，例如元素的第一部分可以是 64 位大端数：由于大端数在初始位置具有最高有效字节，二进制比较将匹配数字的数字比较。这可用于对 64 位值实施范围查询。如下例所示，在前 8 个字节之后，我们可以存储我们实际索引的元素的值。

返回值

数组回复：指定分数范围内的元素列表。

ZRANGEBYSCORE

返回按键排序的集合中分数在min和max之间的所有元素(包括分数等于min或max的元素)。元素被认为是从低到高的顺序。

具有相同分数的元素按字典顺序返回（这是从 Keybyte 中排序集实现的一个属性得出的，不涉及进一步的计算）。

可选WITHSCORES参数使命令返回元素及其分数，而不是单独返回元素。

独占区间和无穷大

minandmax可以是-infand +inf，这样你就不需要知道排序集中的最高或最低分数来获取来自或达到某个分数的所有元素。

默认情况下，由min和指定的间隔max是封闭的（包括）。可以通过在分数前加上字符来指定一个开放区间（独占）。例如：

ZRANGEBYSCORE zset (1 5

将使用1 < score ⇐ 5while返回所有元素：

ZRANGEBYSCORE zset (5 (10

将返回带有5 < score < 10（5 和 10 除外）的所有元素。

返回值

数组回复：指定分数范围内的元素列表（可选及其分数）。

ZRANGESTORE

此命令类似于ZRANGE，但将结果存储在<dst>目标键中。

返回值

整数回复：结果排序集中的元素数。

ZRANK

返回按键存储的已排序集合中成员的排名，分数按从低到高的顺序排列。排名(或索引)是基于0的，这意味着得分最低的成员排名为0。
使用ZREVRANK可以得到分数从高到低排序的元素的排名。

返回值
如果在已排序的集合中存在成员，则整数回答:成员的等级。
如果成员在排序集中不存在或键不存在，则批量字符串应答:nil。

ZREM

从按键存储的已排序集合中删除指定的成员。不存在的成员将被忽略。当key存在且不保存已排序的集合时返回错误。

返回值

整数的答复,具体地说: 从已排序集合中删除的成员数，不包括不存在的成员。

ZREMRANGEBYLEX

当排序集中的所有元素都以相同的分数插入时，为了强制按字典顺序排列，此命令删除存储在和key指定的字典范围之间的排序集中的所有元素。minmax

和的含义min与ZRANGEBYLEX命令max相同。类似地，此命令实际上删除了ZRANGEBYLEX如果使用相同的and参数调用将返回的相同元素。

返回值

整数回复：删除的元素数。

ZREMRANGEBYRANK

删除已排序集合中存储在键上的所有元素，并在开始和停止之间设置秩。start和stop都是基于0的索引，其中0是得分最低的元素。这些索引可以是负数，表示从得分最高的元素开始的偏移量。例如:-1是得分最高的元素，-2是得分第二的元素，以此类推。

返回值

整数回复:删除的元素个数。

ZREMRANGEBYSCORE

删除按键存储的已排序集合中的所有元素，其分数在min和max之间(包括)。 min和max可以按照ZRANGEBYSCORE的语法互斥。

返回值

整数回复:删除的元素个数。

ZREVRANGE

返回按键存储的已排序集合中指定的元素范围。元素被认为是按照从高到低的顺序排列的。对分数相等的元素使用降序字典顺序。除了顺序相反外，ZREVRANGE与ZRANGE相似。这个命令被认为是不推荐的的。请在新代码中使用带有REV参数的ZRANGE命令。

返回值

数组回复:指定范围内的元素列表(可选带有它们的分数)。

ZREVRANGEBYLEX

当以相同的分数插入一个排序集合中的所有元素时，为了强制按字典顺序排序，该命令返回排序集合中的所有元素，其值在max和min之间。
除了顺序相反外，ZREVRANGEBYLEX与ZRANGEBYLEX相似。
这个命令被认为是不推荐的。请在新代码中使用带有BYLEX和REV参数的ZRANGE命令。

返回值

数组回复:指定分数范围内的元素列表。

ZREVRANGEBYSCORE

返回键值在max和min之间的已排序集合中的所有元素(包括score等于max或min的元素)。与排序集的默认顺序相反，对于该命令，元素被认为是按照从高到低的顺序排列的。
具有相同分数的元素将按照字典顺序的倒序返回。
除了顺序相反外，ZREVRANGEBYSCORE与ZRANGEBYSCORE类似。
这个命令被认为是不推荐的。请在新代码中使用带有BYSCORE和REV参数的ZRANGE命令。

返回值

数组回复:指定分数范围内的元素列表(可选带有它们的分数)。

ZREVRANK

返回按key存储的已排序集合中成员的排名，分数按从高到低排序。排名(或索引)是基于0的，这意味着得分最高的成员排名为0。
使用ZRANK可以得到分数从低到高排序的元素的排名。

返回值

如果在已排序的集合中存在成员，则整数回答:成员的等级。如果成员在排序集中不存在或键不存在，则批量字符串应答:nil。

ZSCAN

见SCAN为ZSCAN文档。

ZSCORE

返回排序集中的成员在 key 处的分数。

如果有序集合中不存在成员，或者键不存在，则返回 nil。

返回值

批量字符串回复：成员的分数（双精度浮点数），用字符串表示。

ZUNION

此命令类似于ZUNIONSTORE，但不是存储结果排序集，而是将其返回给客户端。

有关WEIGHTS和AGGREGATE选项的说明，请参阅ZUNIONSTORE。

返回值

数组回复：联合的结果（如果WITHSCORES给出了选项，可以选择带有他们的分数）。

ZUNIONSTORE

计算由指定键给定的 numkeys 排序集的并集，并将结果存储在目标中。在传递输入键和其他（可选）参数之前，必须提供输入键 (numkeys) 的数量。

默认情况下，一个元素的结果分数是它在它存在的排序集中的分数的总和。

使用 WEIGHTS 选项，可以为每个输入排序集指定乘法因子。这意味着在传递给聚合函数之前，每个输入排序集中的每个元素的分数都乘以这个因子。当未给出 WEIGHTS 时，乘法因子默认为 1。

使用 AGGREGATE 选项，可以指定如何聚合联合的结果。此选项默认为 SUM，其中元素的分数在它存在的输入中求和。当此选项设置为 MIN 或 MAX 时，结果集将包含元素在其存在的输入中的最小或最大分数。

如果目的地已经存在，它会被覆盖。

返回值

整数回复：在目的地结果排序集中的元素数。

Streams

XACK

从流消费者组的Pending Entries List (PEL)中删除一条或多条消息。当消息被传递给某个消费者时，通常作为调用XREADGROUP 的副作用，或者当消费者获得调用XCLAIM的消息的所有权时，消息处于挂起状态，因此存储在 PEL 中。待处理的消息已传递给某个消费者，但服务器还不确定它是否至少被处理过一次。所以对XREADGROUP 的新调用获取消费者的消息历史记录（例如使用 ID 0），将返回此类消息。类似地，待处理消息将由检查 PEL的XPENDING命令列出。

一旦消费者成功处理了一条消息，它就应该调用XACK，这样这条消息就不会被再次处理，作为副作用，关于这条消息的 PEL 条目也被清除，从 Keybyte 服务器释放内存。

返回值

整数回复，特别是：

该命令返回成功确认的消息数。某些消息 ID 可能不再是 PEL 的一部分（例如因为它们已经被确认），并且 XACK 不会将它们算作成功确认。

例子

redis> XACK mystream mygroup 1526569495631-0

(integer) 1

XADD

将指定的流条目附加到指定键的流中。如果键不存在，作为运行此命令的副作用，键是使用流值创建的。可以使用该NOMKSTREAM选项禁用流key的创建。

一个条目由一组字段值对组成，它基本上是一个小字典。字段-值对按照用户给定的顺序存储，读取流的命令（如 XRANGE或XREAD）保证以与XADD添加的顺序完全相同的顺序返回字段和值。

XADD是唯一可以向流中添加数据的Keybyte 命令，但还有其他命令，例如XDEL和XTRIM，可以从流中删除数据。

将流 ID 指定为参数

流条目 ID 标识流内的给定条目。

如果指定的 ID 参数是字符（星号 ASCII 字符），则XADD命令将为您自动生成唯一 ID *。然而，虽然仅在极少数情况下有用，但可以指定格式正确的 ID，以便新条目将与指定的 ID 完全一致地添加。

ID 由两个由一个-字符分隔的数字指定：

1526919030474-55

这两个数量都是 64 位数字。自动生成 ID 时，第一部分是生成 ID 的 Keybyte 实例的 Unix 时间（以毫秒为单位）。第二部分只是一个序列号，用于区分同一毫秒内生成的 ID。

ID 保证始终是增量的：如果比较刚刚插入的条目的 ID，它将大于任何其他过去的 ID，因此条目在流中完全排序。为了保证这个属性，如果流中当前top ID的时间大于实例的当前本地时间，则将使用top entry时间代替，并且ID的序列部分递增。例如，当本地时钟向后跳时，或者在故障转移后新主设备具有不同的绝对时间时，可能会发生这种情况。

当用户向XADD指定显式 ID 时，最小有效 ID 为 0-1，并且用户必须指定一个大于当前流中的任何其他 ID 的 ID，否则命令将失败并返回错误。通常，仅当您有另一个系统生成唯一 ID（例如 SQL 表）并且您确实希望 Keybyte 流 ID 与其他系统中的一个相匹配时，诉诸特定 ID 才有用。

限制流

XADD包含与XTRIM命令相同的语义- 有关更多信息，请参阅其文档页面。这允许添加新条目并通过对XADD的单个调用来检查流的大小，从而有效地使用任意阈值限制流。尽管精确修剪（trim）是可能的并且是默认设置，但由于流的内部表示，使用几乎精确的修剪（trim）（参数）使用XADD添加条目和修剪（trim）流更有效。

例如，以下列形式调用XADD：

XADD mystream MAXLEN ~ 1000 * ... entry fields here ...

将添加一个新条目，但也会驱逐旧条目，以便流将仅包含 1000 个条目，或最多几十个条目。

关于流的附加信息

有关 Keybyte 流的更多信息，请查看我们对 streams文档的介绍。

返回值

批量字符串回复，特别是：

该命令返回添加的条目的 ID。如果*作为 ID 参数传递，则 ID 是自动生成的，否则该命令仅返回用户在插入期间指定的相同 ID。

当与选项一起使用且key不存在时，该命令将返回Null 回复NOMKSTREAM。

XAUTOCLAIM

此命令转移与指定条件匹配的挂起流条目的所有权。从概念上讲，XAUTOCLAIM 相当于调用XPENDING然后XCLAIM，但提供了一个更直接的方式来处理通过消息传递失败SCAN般的语义。

与XCLAIM一样，该命令<key>在提供的<group>. 它将所有权转移到<consumer>的挂起时间超过<min-idle-time>毫秒且 ID 等于或大于的消息<start>。

可选<count>参数默认为 100，是命令尝试声明的条目数的上限。在内部，该命令开始扫描消费者组的待处理条目列表 (PEL)，<start>并过滤掉空闲时间小于或等于的条目<min-idle-time>。命令扫描的最大挂起条目数是<count>的值乘以10（硬编码）的乘积。因此，声明的条目数可能会少于指定值。

可选JUSTID参数将回复更改为仅返回成功声明的消息 ID 数组，而不返回实际消息。使用此选项意味着重试计数器不会增加。

该命令将声明的条目作为数组返回。它还返回一个流 ID，用于类似游标的用途，作为<start>其后续调用的参数。当没有剩余的 PEL 条目时，该命令返回特殊0-0ID 以表示完成。但是，请注意，即使在使用as ID完成扫描后，您也可能希望继续调用XAUTOCLAIM，因为经过了足够的时间，因此较旧的待处理条目现在可能有资格进行声明。0-0<start>

请注意，只有空闲时间长于<min-idle-time>声明的消息，并且声明消息会重置其空闲时间。这确保了只有一个消费者可以在特定的时刻成功声明给定的待处理消息，并且微不足道地降低了多次处理同一消息的可能性。

最后，使用XAUTOCLAIM声明消息还会增加该消息的尝试传递计数，除非JUSTID已指定该选项（仅传递消息 ID，而不传递消息本身）。由于某种原因无法处理的消息 - 例如，因为消费者在处理它们时系统性地崩溃 - 将表现出可以通过监控检测到的高尝试传递计数。

返回值

数组回复，具体如下：

包含两个元素的数组：

第一个元素是一个流 ID，用作<start>下一次调用XAUTOCLAIM的参数
第二个元素是一个数组，包含所有成功声明的消息，格式与XRANGE相同。

例子

> XAUTOCLAIM mystream mygroup Alice 3600000 0-0 COUNT
25

1) "0-0"

2) 1) 1) "1609338752495-0"

      2) 1) "field"

         2) "value"

在上面的示例中，我们尝试声明多达 25 个挂起和空闲（未确认或声明）至少一个小时的条目，从流的开头开始。来自“mygroup”组的消费者“Alice”获得了这些消息的所有权。请注意，示例中返回的流 ID 为0-0，表示扫描了整个流。

XCLAIM

在流消费者组的上下文中，此命令更改挂起消息的所有权，因此新所有者是指定为命令参数的消费者。通常是这样的：

有一个带有关联消费者组的流。
某些消费者 A在该消费者组的上下文中通过XREADGROUP从流中读取消息。
作为副作用，在消费者组的待处理条目列表 (PEL) 中创建了待处理消息条目：这意味着消息已传递给给定消费者，但尚未通过XACK确认。
然后突然那个消费者永远失败了。
其他消费者可能会使用XPENDING命令检查挂起消息的列表，这些消息已经陈旧了一段时间。为了继续处理此类消息，他们使用XCLAIM获取消息的所有权并继续。消费者可以使用XAUTOCLAIM命令自动扫描和声明陈旧的待处理消息。

Stream清楚地解释了这种动态。

请注意，仅当消息的空闲时间大于我们在调用XCLAIM时指定的最小空闲时间时才会声明该消息。因为作为副作用，XCLAIM也会重置空闲时间（因为这是处理消息的新尝试），所以两个尝试同时声明消息的消费者永远不会成功：只有一个消费者会成功声明该消息。这避免了我们以微不足道的方式多次处理给定消息（但在一般情况下，多次处理是可能且不可避免的）。

此外，作为副作用，除非已指定选项（仅传递消息 ID，而不是消息本身），否则XCLAIM将增加尝试传递消息的计数JUSTID。通过这种方式，由于某种原因无法处理的消息，例如因为消费者在尝试处理它们时崩溃，将开始有一个更大的计数器，并且可以在系统内部检测到。

命令选项

该命令有多个选项，但大多数主要供内部使用，以便将XCLAIM或其他命令的效果传输到 AOF 文件并将相同的效果传播到从站，对普通用户不太可能有用：

IDLE <ms>: 设置消息的空闲时间（最后一次传递）。如果未指定 IDLE，则假定 IDLE 为 0，即重置时间计数，因为消息现在有一个新的所有者尝试处理它。
TIME <ms-unix-time>: 这与 IDLE 相同，但它不是相对的毫秒数，而是将空闲时间设置为特定的 Unix 时间（以毫秒为单位）。这对于重写生成XCLAIM命令的 AOF 文件很有用。
RETRYCOUNT <count>: 将重试计数器设置为指定值。每次再次传递消息时，此计数器都会增加。通常XCLAIM不会改变这个计数器，它只是在调用 XPENDING 命令时提供给客户端：这样客户端可以检测异常，比如在大量传递尝试后由于某种原因从未处理过的消息。
FORCE：即使某些指定的 ID 不在分配给不同客户端的 PEL 中，也会在 PEL 中创建挂起的消息条目。但是消息必须存在于流中，否则不存在的消息的 ID 将被忽略。
JUSTID：仅返回成功声明的消息 ID 数组，而不返回实际消息。使用此选项意味着重试计数器不会增加。

返回值

数组回复，具体如下：

该命令以与XRANGE相同的格式返回所有成功声明的消息。但是，如果JUSTID指定了该选项，则仅报告消息 ID，而不包括实际消息。

例子

> XCLAIM mystream mygroup Alice 3600000
1526569498055-0

1) 1) 1526569498055-0

   2) 1) "message"

      2) "orange"

在上面的例子中，我们使用 ID 声明消息1526569498055-0，只有当消息空闲至少一小时没有原始消费者或其他一些消费者取得进展（确认或声明）时，才会将所有权分配给消费者Alice。

XDEL

从流中删除指定的条目，并返回删除的条目数，如果某些 ID 不存在，则该数可能与传递给命令的 ID 数不同。

通常，您可能会将 Keybyte 流视为仅附加数据结构，但是 Keybyte 流在内存中表示，因此我们也可以删除条目。这可能很有用，例如，为了遵守某些隐私政策。

了解条目删除的底层细节

Keybyte 流以一种使它们的内存高效的方式表示：使用基数树来索引线性打包数十个流条目的宏节点。通常，当您从流中删除条目时，该条目并未真正被驱逐，只是被标记为已删除。

最终，如果宏节点中的所有条目都被标记为已删除，则整个节点将被销毁并回收内存。这意味着如果您从流中删除大量条目，例如超过 50% 的附加到流的条目，每个条目的内存使用量可能会增加，因为会发生流将开始碎片化的情况。但是，流性能将保持不变。

在 Keybyte 的未来版本中，如果给定的宏节点达到给定数量的已删除条目，我们可能会触发节点垃圾收集。目前，根据我们对这种数据结构的预期用途，增加这种复杂性并不是一个好主意。

返回值

整数回复：实际删除的条目数。

例子

> XADD mystream * a 1

1538561698944-0

> XADD mystream * b 2

1538561700640-0

> XADD mystream * c 3

1538561701744-0

> XDEL mystream 1538561700640-0

(integer) 1

127.0.0.1:6379> XRANGE mystream - +

1) 1) 1538561698944-0

   2) 1) "a"

      2) "1"

2) 1) 1538561701744-0

   2) 1) "c"

      2) "3"

XGROUP

此命令用于管理与流数据结构关联的消费者组。使用XGROUP，您可以：

创建与流关联的新消费者组。
销毁一个消费者组。
从消费者组中删除特定消费者。
将消费者组上次交付的 ID 设置为其他内容。

要创建新的消费者组，请使用以下形式：

XGROUP CREATE mystream consumer-group-name $

最后一个参数是流中要考虑已交付的最后一项的 ID。在上面的例子中，我们使用了特殊的 ID '$'（这意味着：流中最后一个项目的 ID）。在这种情况下，从该消费者组获取数据的消费者只会看到到达流中的新元素。

相反，如果您希望消费者获取整个流历史记录，请使用零作为消费者组的起始 ID：

XGROUP CREATE mystream consumer-group-name 0

当然，也可以使用任何其他有效 ID。如果指定的消费者组已经存在，则该命令返回-BUSYGROUP错误。否则，执行操作并返回简单字符串回复 OK。您可以与给定流关联的消费者组的数量没有硬性限制。

如果创建组时指定的流不存在，则会返回错误。如果流不存在，您可以使用可选的MKSTREAM子命令作为ID自动创建流之后的最后一个参数。请注意，如果以这种方式创建流，它的长度将为 0：

XGROUP CREATE mystream consumer-group-name $ MKSTREAM

可以使用以下形式完全销毁消费者组：

XGROUP DESTROY mystream consumer-group-name

即使有活动的消费者和待处理的消息，消费者组也会被销毁，因此请确保仅在真正需要时才调用此命令。此表单返回一个带有销毁的消费者组数（0 或 1）的整数回复。

每当某个命令提到新的消费者名称时，都会自动创建消费者组中的消费者。它们也可以使用以下形式显式创建：

XGROUP CREATECONSUMER mystream consumer-group-name myconsumer123

此表单返回一个带有创建的消费者数量（0 或 1）的整数回复。

要从消费者组中删除给定的消费者，请使用以下形式：

XGROUP DELCONSUMER mystream consumer-group-name myconsumer123

有时删除旧消费者可能很有用，因为它们不再使用。此表单返回一个整数回复，其中包含消费者在删除之前拥有的待处理消息的数量。

最后，可以使用SETID子命令设置要传递的下一条消息。通常在创建消费者时设置下一个 ID，作为XGROUP CREATE. 但是，使用此表单可以稍后修改下一个 ID，而无需再次删除和创建消费者组。例如，如果您希望消费者组中的消费者重新处理流中的所有消息，您可能希望将其下一个 ID 设置为 0：

XGROUP SETID mystream consumer-group-name 0

此表单返回简单字符串回复 OK或错误。

最后，如果您不记得语法，要获得一些帮助，请使用 HELP 子命令：

XGROUP HELP

XINFO

这是一个内省命令，用于检索有关流和相关消费者组的不同信息。三种形式是可能的：

XINFO STREAM <key>

在这种形式中，该命令返回有关存储在指定键中的流的一般信息。

> XINFO STREAM mystream

 1) length

 2) (integer) 2

 3) radix-tree-keys

 4) (integer) 1

 5) radix-tree-nodes

 6) (integer) 2

 7) groups

 8) (integer) 2

 9) last-generated-id

10) 1538385846314-0

11) first-entry

12) 1) 1538385820729-0

    2) 1) "foo"

       2) "bar"

13) last-entry

14) 1) 1538385846314-0

    2) 1) "field"

       2) "value"

在上面的例子中，你可以看到报告的信息是流的元素数量，关于表示流的基数树的详细信息，对优化和调试任务最有用，与流关联的消费者组的数量，最后生成的 ID如果某些条目被删除，它可能与最后一个条目 ID 不同。最后显示了流中完整的第一个和最后一个条目，以便对流的内容有一些了解。

XINFO STREAM <key> FULL [COUNT <count>]

在这种形式中，该命令返回流的整个状态，包括条目、组、消费者和待处理条目列表 (PEL)。

> XADD mystream * foo bar

"1588152471065-0"

> XADD mystream * foo bar2

"1588152473531-0"

> XGROUP CREATE mystream mygroup 0-0

OK

> XREADGROUP GROUP mygroup Alice COUNT 1 STREAMS mystream
>

1) 1) "mystream"

   2) 1) 1) "1588152471065-0"

         2) 1) "foo"

            2) "bar"

> XINFO STREAM mystream FULL

 1) "length"

 2) (integer) 2

 3) "radix-tree-keys"

 4) (integer) 1

 5) "radix-tree-nodes"

 6) (integer) 2

 7) "last-generated-id"

 8) "1588152473531-0"

 9) "entries"

10) 1) 1) "1588152471065-0"

       2) 1) "foo"

          2) "bar"

    2) 1) "1588152473531-0"

       2) 1) "foo"

          2) "bar2"

11) "groups"

12) 1)  1) "name"

        2) "mygroup"

        3) "last-delivered-id"

        4) "1588152471065-0"

        5) "pel-count"

        6) (integer) 1

        7) "pending"

        8) 1) 1) "1588152471065-0"

              2) "Alice"

              3) (integer) 1588152520299

              4) (integer) 1

        9) "consumers"

       10) 1) 1) "name"

              2) "Alice"

              3) "seen-time"

              4) (integer) 1588152520299

              5) "pel-count"

              6) (integer) 1

              7) "pending"

              8) 1) 1) "1588152471065-0"

                    2) (integer) 1588152520299

                    3) (integer) 1

报告的信息包含由的简单形式报告的所有字段XINFO STREAM，以及一些附加信息：

返回流条目，包括字段和值。
返回组、消费者和 PEL。

该COUNT选项用于限制返回的流/PEL 条目的数量（返回第一个<count>条目）。默认COUNT为 10，a COUNTof 0 表示将返回所有条目（如果流中有很多条目，则执行时间可能会很长）

XINFO GROUPS <key>

在这种形式中，我们只获得与流关联的所有消费者组作为输出：

> XINFO GROUPS mystream

1) 1) name

   2) "mygroup"

   3) consumers

   4) (integer) 2

   5) pending

   6) (integer) 2

   7) last-delivered-id

   8) "1588152489012-0"

2) 1) name

   2) "some-other-group"

   3) consumers

   4) (integer) 1

   5) pending

   6) (integer) 0

   7) last-delivered-id

   8) "1588152498034-0"

对于列出的每个消费者组，该命令还显示该组中已知的消费者数量以及该组中的待处理消息（已传递但尚未确认）。

XINFO CONSUMERS <key> <group>

最后，可以获取特定消费者组中每个消费者的列表：

> XINFO CONSUMERS mystream mygroup

1) 1) name

   2) "Alice"

   3) pending

   4) (integer) 1

   5) idle

   6) (integer) 9104628

2) 1) name

   2) "Bob"

   3) pending

   4) (integer) 1

   5) idle

   6) (integer) 83841983

我们可以看到以毫秒为单位的空闲时间（最后一个字段）以及该特定消费者的消费者名称和待处理消息的数量。

请注意，您不应依赖于字段的确切位置，也不应依赖于字段的数量，将来可能会添加新的字段。因此，行为良好的客户端应该获取整个列表，并将其报告给用户，例如，作为字典数据结构。低级客户端，例如 C 客户端，其中的项目可能会以线性数组的形式返回，应记录订单未定义。

最后，可以从命令中获取帮助，以防用户不记得确切的语法，通过使用HELP子命令：

> XINFO HELP

1) XINFO <subcommand> arg arg ... arg. Subcommands
are:

2) CONSUMERS <key> <groupname>  -- Show consumer groups of group
<groupname>.

3) GROUPS <key>                 -- Show the stream consumer
groups.

4) STREAM <key>                 -- Show information about the
stream.

5) HELP

XLEN

返回流中的条目数。如果指定的键不存在，则命令返回零，就好像流是空的一样。但是请注意，与其他 Keybyte 类型不同，零长度流是可能的，因此您应该调用TYPE或EXISTS以检查键是否存在。

一旦流内部没有条目（例如在XDEL调用之后），流就不会自动删除，因为流可能有与之关联的消费者组。

返回值

整数回复：流在处的条目数key。

XPENDING

通过消费者组从流中获取数据，但不确认此类数据，具有创建挂起条目的效果。这在XREADGROUP命令中有很好的解释，在我们对 Keybyte Streams的介绍中甚至更好。该XACK命令将立即删除从待定条目列表（PEL）的等待条目，因为一旦消息被成功处理，没有用于消费群体不再需要跟踪它，并记住消息的当前所有者。

该XPENDING命令检查待处理的邮件列表界面，并且是作为这样一个非常重要的命令，以观察和了解与流的消费群体发生了：什么客户是主动的，有什么消息待被消耗，或查看是否有空闲消息。此外，此命令与XCLAIM一起用于实现对长期失败的消费者的恢复，因此某些消息未被处理：不同的消费者可以声明该消息并继续。

XPENDING汇总表

当仅使用键名和消费者组名称调用XPENDING 时，它只会输出有关给定消费者组中待处理消息的摘要。在下面的示例中，我们创建了一个消费者组，并通过使用XREADGROUP从组中读取来立即创建一条挂起的消息。

> XGROUP CREATE mystream group55 0-0

OK

> XREADGROUP GROUP group55 consumer-123 COUNT 1 STREAMS mystream
>

1) 1) "mystream"

   2) 1) 1) 1526984818136-0

         2) 1) "duration"

            2) "1532"

            3) "event-id"

            4) "5"

            5) "user-id"

            6) "7782813"

我们希望消费者组的待处理条目列表group55现在有一条消息：名为消费者的消费者consumer-123在不确认其处理的情况下获取了该消息。简单的XPENDING 表单将为我们提供以下信息：

> XPENDING mystream group55

1) (integer) 1

2) 1526984818136-0

3) 1526984818136-0

4) 1) 1) "consumer-123"

      2) "1"

在这种形式中，命令输出这个消费者组的待处理消息总数，为1，然后是待处理消息中最小和最大的ID，然后列出消费者组中每个消费者至少有一个待处理消息，以及它拥有的待处理消息的数量。

XPENDING的扩展形式

摘要提供了很好的概述，但有时我们对细节感兴趣。为了查看具有更多关联信息的所有待处理消息，我们还需要传递一系列 ID，以类似的方式使用 XRANGE和一个非可选的count参数来限制每次调用返回的消息数量：

> XPENDING mystream group55 - + 10

1) 1) 1526984818136-0

   2) "consumer-123"

   3) (integer) 196415

   4) (integer) 1

在扩展形式中，我们不再看到摘要信息，而是在待处理条目列表中显示每条消息的详细信息。对于每条消息，返回四个属性：

消息的 ID。
获取消息并仍需确认的消费者的名称。我们称其为消息的当前所有者。
自上次将此消息传递给此使用者以来经过的毫秒数。
此消息的传递次数。

传递计数器是数组中的第四个元素，当其他消费者使用XCLAIM声明消息时，或者当消息通过XREADGROUP再次传递时，当访问消费者组中消费者的历史记录时，它会增加（请参阅XREADGROUP页面了解更多信息）。

可以向命令传递一个额外的参数，以便查看具有特定所有者的消息：

XPENDING mystream group55 - + 10 consumer-123

但在上述情况下，输出将是相同的，因为我们只有一个消费者的待处理消息。然而，重要的是要记住，即使有来自许多消费者的许多挂起消息，这种由特定消费者过滤的操作也不是低效的：我们在全局和每个消费者都有一个挂起条目列表数据结构，所以我们可以非常有效地只显示单个消费者的待处理消息。

空闲时间过滤器

从 6.2 版开始，可以通过空闲时间过滤条目，以毫秒为单位（XCLAIM对于一段时间未处理的条目很有用）：

XPENDING mystream group55 IDLE 9000 - + 10

XPENDING mystream group55 IDLE 9000 - + 10 consumer-123

第一种情况将返回整个组中空闲超过 9 秒的前 10 个（或更少）PEL 条目，而在第二种情况下仅返回 consumer-123.

独占范围和迭代 PEL

该XPENDING命令允许遍历待定参赛就像 XRANGE和XREVRANGE允许流的条目。您可以通过在最后读取的挂起条目的 ID 前面加上(表示开放（独占）范围的字符作为前缀，并将其证明给对命令的后续调用来实现。

返回值

数组回复，具体如下：

该命令根据调用方式返回不同格式的数据，如本页前面所述。但是，回复始终是一组项目。

XRANGE

该命令返回匹配给定 ID 范围的流条目。范围由最小和最大 ID 指定。返回 ID 介于指定的两个 ID 或恰好指定的两个 ID 之一（闭区间）的所有条目。

该XRANGE命令有许多应用程序：

返回特定时间范围内的项目。这是可能的，因为 Stream ID与 time 相关。
增量迭代流，每次迭代只返回几个项目。然而，它在语义上比SCAN系列函数更健壮。
从流中获取单个条目，提供要获取两次的条目 ID：作为查询间隔的开始和结束。

该命令还有一个交互命令，以相反的顺序返回项目，称为XREVRANGE，在其他方面是相同的。

-和+特殊IDs

该-和+特殊的ID分别指最低ID可能和流内的最高ID可能的，因此下面的命令将只返回流中的每个条目：

> XRANGE somestream - +

1) 1) 1526985054069-0

   2) 1) "duration"

      2) "72"

      3) "event-id"

      4) "9"

      5) "user-id"

      6) "839248"

2) 1) 1526985069902-0

   2) 1) "duration"

      2) "415"

      3) "event-id"

      4) "2"

      5) "user-id"

      6) "772213"

... other entries here ...

的-ID是有效地只是完全一样指定0-0，而 +等同于18446744073709551615-18446744073709551615，但它们是更好键入。

不完整的 ID

流 ID 由两部分组成，Unix 毫秒时间戳和在同一毫秒内插入的条目的序列号。可以使用XRANGE仅指定 ID 的第一部分，即毫秒时间，如下例所示：

> XRANGE somestream 1526985054069 1526985055069

在这种情况下，XRANGE将使用自动完成开始间隔-0 和结束间隔-18446744073709551615，以返回在给定毫秒和另一个指定毫秒结束之间生成的所有条目。这也意味着重复相同的毫秒两次，我们会得到该毫秒内的所有条目，因为序列号范围将从零到最大值。

以这种方式使用XRANGE作为范围查询命令来获取指定时间的条目。这对于访问流中过去事件的历史非常方便。

独家范围

默认情况下，范围接近（包括），这意味着回复可以包含 ID 与查询的开始和结束间隔匹配的条目。可以通过在 ID 前面加上字符来指定一个开放区间（独占）(。这对于迭代流很有用，如下所述。

返回最大条目数

使用COUNT选项可以减少报告的条目数。这是一个非常重要的特性，即使它可能看起来微不足道，因为它允许，例如，建模操作，例如给我大于或等于以下的条目：

> XRANGE somestream 1526985054069-0 + COUNT 1

1) 1) 1526985054069-0

   2) 1) "duration"

      2) "72"

      3) "event-id"

      4) "9"

      5) "user-id"

      6) "839248"

在上述情况下，条目1526985054069-0存在，否则服务器会向我们发送下一个条目。UsingCOUNT也是将XRANGE用作迭代器的基础。

迭代流

为了迭代一个流，我们可以进行如下操作。让我们假设每次迭代需要两个元素。我们开始获取前两个元素，这是微不足道的：

> XRANGE writers - + COUNT 2

1) 1) 1526985676425-0

   2) 1) "name"

      2) "Virginia"

      3) "surname"

      4) "Woolf"

2) 1) 1526985685298-0

   2) 1) "name"

      2) "Jane"

      3) "surname"

      4) "Austen"

然后，不是从-再次开始迭代，作为范围的开始，我们使用前一个XRANGE调用返回的最后一个条目的条目 ID作为独占间隔。

最后一个条目的 ID 是1526985685298-0，所以我们只需在它前面加上一个 '('，然后继续我们的迭代：

> XRANGE writers (1526985685298-0 + COUNT 2

1) 1) 1526985691746-0

   2) 1) "name"

      2) "Toni"

      3) "surname"

      4) "Morrison"

2) 1) 1526985712947-0

   2) 1) "name"

      2) "Agatha"

      3) "surname"

      4) "Christie"

最终这将允许访问流中的所有条目。显然，通过提供给定的不完整起始 ID，我们可以从任何 ID，甚至从特定时间开始迭代。此外，我们可以通过提供结束 ID 或不完整的 ID 而不是，将迭代限制为给定的 ID 或时间+。

命令XREAD也能够迭代流。命令XREVRANGE可以反向迭代流，从较高的 ID（或时间）到较低的 ID（或时间）。

使用早期版本的 Keybyte 进行迭代

您开始以与上述相同的方式从流中获取以获取第一个条目。

对于后续调用，您需要以编程方式提前返回最后一个条目的 ID。大多数 Keybyte 客户端应该抽象这个细节，但如果需要，实现也可以在应用程序中。在上面的示例中，在上面的示例中，这意味着将序列1526985685298-0从0增加1。因此，第二项调用是:

> XRANGE writers 1526985685298-1 + COUNT 2

1) 1) 1526985691746-0

   2) 1) "name"

      2) "Toni"

...

另请注意，一旦最后一个 ID 的序列部分等于 18446744073709551615，您将需要增加时间戳并将序列部分重置为 0。例如，增加 ID 1526985685298-18446744073709551615应该导致1526985685299-0.

对称模式适用于使用XREVRANGE迭代流。唯一的区别是客户端需要为后续调用递减 ID。递减序列部分为0的ID时，时间戳需要递减1，序列设置为18446744073709551615。

获取单个项目

如果您查找XGET命令，您会感到失望，因为XRANGE 是从流中获取单个条目的有效方法。您所要做的就是在 XRANGE 的参数中指定 ID 两次：

> XRANGE mystream 1526984818136-0 1526984818136-0

1) 1) 1526984818136-0

   2) 1) "duration"

      2) "1532"

      3) "event-id"

      4) "5"

      5) "user-id"

      6) "7782813"

关于流的附加信息

有关 Keybyte 流的更多信息，请查看Streams的介绍。

返回值

数组回复，具体如下：

该命令返回 ID 与指定范围匹配的条目。返回的条目是完整的，这意味着返回 ID 和它们组成的所有字段。此外，条目及其字段和值的返回顺序与XADD添加它们的顺序完全相同。

XREAD

从一个或多个流中读取数据，仅返回 ID 大于调用者报告的最后接收到的 ID 的条目。如果项目不可用，此命令有一个选项来阻止，与BRPOP或BZPOPMIN等类似。

请注意，在阅读本页之前，如果您不熟悉流，我们建议您阅读Streams的介绍。

非阻塞使用

如果不使用BLOCK选项，则该命令是同步的，可以认为与XRANGE有点相关：它将返回流内的一系列项目，但是即使我们只考虑同步用法，它与XRANGE相比也有两个根本区别：

如果我们想同时从多个键中读取，可以使用多个流调用此命令。这是XREAD 的一个关键特性，因为特别是在使用BLOCK阻塞时，能够通过单个连接侦听多个键是一个重要特性。
虽然XRANGE返回一系列 ID 中的项目，但XREAD更适合使用从第一个条目开始的流，该条目比我们目前看到的任何其他条目都大。所以我们传递给XREAD 的是，对于每个流，我们从该流接收到的最后一个元素的 ID。

例如，如果我有两个流mystreamand writers，并且我想从它们包含的第一个元素开始从两个流中读取数据，我可以像下面的例子一样调用XREAD。

注意：我们在示例中使用了COUNT选项，因此对于每个流，调用将最多返回每个流两个元素。

> XREAD COUNT 2 STREAMS mystream writers 0-0 0-0

1) 1) "mystream"

   2) 1) 1) 1526984818136-0

         2) 1) "duration"

            2) "1532"

            3) "event-id"

            4) "5"

            5) "user-id"

            6) "7782813"

      2) 1) 1526999352406-0

         2) 1) "duration"

            2) "812"

            3) "event-id"

            4) "9"

            5) "user-id"

            6) "388234"

2) 1) "writers"

   2) 1) 1) 1526985676425-0

         2) 1) "name"

            2) "Virginia"

            3) "surname"

            4) "Woolf"

      2) 1) 1526985685298-0

         2) 1) "name"

            2) "Jane"

            3) "surname"

            4) "Austen"

STREAMS选项是强制性的，因为这样的选项得到以下面的格式参数的可变长度必须是最后一个选项：

STREAMS key_1 key_2 key_3 … key_N ID_1 ID_2 ID_3 … ID_N

所以我们从一个键列表开始，然后继续所有关联的 ID，代表_我们为该流收到的最后一个 ID，这样调用将只为我们提供来自同一流的更大的 ID。

例如在上面的例子中，我们为流接收的最后一个项目mystream有 ID 1526999352406-0，而对于流writers有 ID 1526985685298-0。

要继续迭代这两个流，我将调用：

> XREAD COUNT 2 STREAMS mystream writers 1526999352406-0
1526985685298-0

1) 1) "mystream"

   2) 1) 1) 1526999626221-0

         2) 1) "duration"

            2) "911"

            3) "event-id"

            4) "7"

            5) "user-id"

            6) "9488232"

2) 1) "writers"

   2) 1) 1) 1526985691746-0

         2) 1) "name"

            2) "Toni"

            3) "surname"

            4) "Morrison"

      2) 1) 1526985712947-0

         2) 1) "name"

            2) "Agatha"

            3) "surname"

            4) "Christie"

等等。最终，调用不会返回任何项目，而只是一个空数组，然后我们知道没有什么可以从我们的流中获取（并且我们必须重试该操作，因此该命令也支持阻塞模式）。

不完整的 ID

使用不完整的 ID 是有效的，就像它对XRANGE有效一样。但是这里 ID 的序列部分，如果丢失，总是被解释为零，所以命令：

> XREAD COUNT 2 STREAMS mystream writers 0 0

完全等同于

> XREAD COUNT 2 STREAMS mystream writers 0-0 0-0

数据阻塞

在其同步形式中，只要有更多可用项，该命令就可以获取新数据。但是，在某些时候，我们将不得不等待数据的生产者使用XADD将新条目推送到我们正在使用的流中。为了避免以固定或自适应间隔进行轮询，如果无法返回任何数据，该命令能够根据指定的流和 ID 进行阻塞，并在请求的key之一接受数据后自动解除阻塞。

重要的是要了解此命令会扇出所有等待相同 ID 范围的客户端，因此每个消费者都将获得一份数据副本，这与使用阻止列表弹出操作时发生的情况不同。

为了阻止，使用了BLOCK选项，以及我们想要在超时之前阻止的毫秒数。通常 Keybyte 阻塞命令以秒为单位超时，但是此命令需要毫秒超时，即使通常服务器的超时分辨率接近 0.1 秒。这一次在某些用例中可能会阻塞更短的时间，如果服务器内部会随着时间的推移而改进，则超时的分辨率可能会提高。

当传递了BLOCK命令，但至少在传递的流之一中有数据要返回时，该命令将同步执行，就像缺少 BLOCK 选项一样。

这是一个阻塞调用的例子，该命令稍后返回一个空回复，因为超时已经过去而没有新数据到达：

> XREAD BLOCK 1000 STREAMS mystream 1526999626221-0

(nil)

特殊$标识

当阻塞时，有时我们只想接收从阻塞那一刻开始通过XADD添加到流中的条目。在这种情况下，我们对已添加条目的历史记录不感兴趣。对于此用例，我们必须检查流顶部元素 ID，并在XREAD命令行中使用此类 ID 。这并不干净，需要调用其他命令，因此可以使用特殊$ ID 向流发出信号，表明我们只需要新事物。

这是非常重要的，要明白，你应该使用$ ID仅在第一次调用XREAD。稍后，ID 应该是流中最后报告的项目之一，否则您可能会错过在其间添加的所有条目。

这是一个典型的XREAD调用在愿意只使用新条目的消费者的第一次迭代中的样子：

> XREAD BLOCK 5000 COUNT 100 STREAMS mystream $

一旦我们得到一些回复，下一次调用将是这样的：

> XREAD BLOCK 5000 COUNT 100 STREAMS mystream 1526999644174-3

如何为单个流上阻塞的多个客户端提供服务

列表或排序集上的阻止列表操作具有弹出行为。基本上，元素从列表或排序集中删除，以便返回给客户端。在这种情况下，您希望项目以公平的方式被消费，这取决于被给定键阻塞的客户端到达的时刻。通常 Keybyte 在这个用例中使用 FIFO 语义。

但是请注意，对于流，这不是问题：在为客户端提供服务时，不会从流中删除流条目，因此只要XADD命令向流提供数据，就会为每个等待的客户端提供服务。

返回值

数组回复，具体如下：

该命令返回一个结果数组：返回数组的每个元素都是一个由两个元素组成的数组，其中包含键名称和为该键报告的条目。报告的条目是完整的流条目，具有 ID 以及所有字段和值的列表。字段和值的报告顺序与XADD添加的顺序相同。

使用BLOCK 时，超时时返回空回复。

XREADGROUP

该XREADGROUP命令是一个特殊版本XREAD命令与消费群体的支持。在阅读本页有意义之前，您可能必须了解 XREAD命令。

此外，如果您不熟悉流，我们建议您阅读我们Streams的介绍。一定要理解介绍中消费者组的概念，这样下面这个命令的工作方式会更简单。

30秒内消费群体

此命令与普通 XREAD之间的区别在于，该命令支持消费者组。

没有消费者组，只需使用XREAD，所有客户端都将获得所有到达流的条目。代替使用消费者组与XREADGROUP，可以创建客户端组，这些客户端消耗到达给定流的消息的不同部分。例如，如果流获得新条目 A、B 和 C，并且有两个消费者通过消费者组读取，则一个客户端将获得消息 A 和 C，另一个客户端将获得消息 B，并且等等。

在消费者组中，给定的消费者（即，只是消费来自流的消息的客户端）必须使用唯一的消费者名称进行标识。这只是一个字符串。

消费者组的保证之一是给定的消费者只能看到传递给它的消息的历史记录，因此一条消息只有一个所有者。但是，有一个称为消息声明的特殊功能，它允许其他使用者在某些使用者发生不可恢复的故障时声明消息。为了实现这样的语义，消费者组需要通过XACK命令明确确认消费者成功处理的消息。这是必需的，因为流将针对每个消费者组跟踪谁正在处理什么消息。

这是如何理解您是否要使用消费者组：

1. 如果您有一个流和多个客户端，并且您希望所有客户端都获取所有消息，则不需要消费者组。

2. 如果你有一个流和多个客户端，并且希望流进行分区或分片在你的客户，让每一个客户将获得一个子集流到达的消息，你需要一个消费群体。

XREAD 和 XREADGROUP 之间的差异

从语法的角度来看，命令几乎相同，但是XREADGROUP 需要一个特殊且强制的选项：

GROUP <group-name> <consumer-name>

组名只是与流关联的消费者组的名称。该组是使用XGROUP命令创建的。消费者名称是客户端用来在组内标识自己的字符串。第一次看到消费者时，消费者会在消费者组内自动创建。不同的客户端应该选择不同的消费者名称。

当您使用XREADGROUP阅读时，服务器将记住给定的消息已发送给您：该消息将存储在消费者组中，称为 Pending Entries List (PEL)，即已发送但未发送的消息 ID 列表还是承认了。

客户端必须使用XACK确认消息处理，以便从 PEL 中删除挂起的条目。可以使用XPENDING命令检查 PE* 。

所述NOACK子命令可用于避免增加该消息的情况下的PEL其中可靠性不是要求和偶尔的消息丢失是可以接受的。这相当于在消息被读取时确认消息。

使用XREADGROUP时在STREAMS选项中指定的 ID可以是以下两个之一：

特殊>ID，这意味着消费者只想接收从未交付给任何其他消费者的消息。这只是意味着，给我新的消息。
任何其他 ID，即 0 或任何其他有效 ID 或不完整 ID（仅毫秒时间部分），将具有返回等待消费者发送 ID 大于提供的 ID 的命令的条目的效果。所以基本上如果 ID 不是>，那么该命令只会让客户端访问其挂起的条目：传递给它但尚未确认的消息。请注意，在这种情况下，BLOCK和NOACK都被忽略。

与XREAD一样，XREADGROUP命令可以以阻塞方式使用。在这方面没有区别。

当消息传递给消费者时会发生什么？

两件事：

如果消息从未发送给任何人，也就是说，如果我们正在谈论一条新消息，则创建 PEL（待处理条目列表）。
相反，如果消息已经传递给这个消费者，并且它只是再次重新获取相同的消息，那么最后一次传递计数器会更新为当前时间，并且传递次数加一。您可以使用XPENDING命令访问这些消息属性。

使用示例

通常您使用这样的命令来获取新消息并处理它们。在伪代码中：

WHILE true

    entries = XREADGROUP GROUP $GroupName $ConsumerName BLOCK
2000 COUNT 10 STREAMS mystream >

    if entries == nil

        puts "Timeout... try again"

        CONTINUE

    end

    FOREACH entries AS stream_entries

        FOREACH stream_entries as message

            process_message(message.id,message.fields)

            # ACK the message as processed

            XACK mystream $GroupName message.id

        END

    END

END

通过这种方式，示例消费者代码将仅获取新消息、处理它们并通过XACK确认它们。然而，上面的示例代码并不完整，因为它不处理崩溃后的恢复。如果我们在处理消息的过程中崩溃会发生什么，我们的消息将保留在待处理条目列表中，因此我们可以通过给XREADGROUP最初的 ID 0 并执行相同的循环来访问我们的历史记录。一旦提供 0 的 ID 回复是一组空消息，我们知道我们处理并确认了所有待处理的消息：我们可以开始使用> 作为 ID，以便获取新消息并重新加入正在处理新事物的消费者。

要查看命令实际如何回复，请查看XREAD命令页面。

返回值

数组回复，具体如下：

使用BLOCK 时，超时时返回空回复。

XREVRANGE

这个命令与XRANGE完全一样，但有一个显着的区别，即以相反的顺序返回条目，并以相反的顺序取开始-结束范围：在XREVRANGE 中，您需要说明结束ID 和后面的开始ID，以及命令将生成两个 ID 之间（或完全相同）的所有元素，从末端开始。

因此，例如，要获取从较高 ID 到较低 ID 的所有元素，可以使用：

XREVRANGE somestream + -

类似地，只需将最后一个元素添加到流中即可发送：

XREVRANGE somestream + - COUNT 1

返回值

数组回复，具体如下：

该命令返回 ID 与指定范围匹配的条目，从较高的 ID 到较低的 ID 匹配。返回的条目是完整的，这意味着返回 ID 和它们组成的所有字段。此外，条目及其字段和值的返回顺序与XADD添加它们的顺序完全相同。

XTRIM

如果需要，XTRIM通过驱逐较旧的条目（具有较低 ID 的条目）来修剪（trim）流。

可以使用以下策略之一来修剪（trim）流：

MAXLEN：只要流的长度超过指定的threshold，就会驱逐条目，其中threshold是正整数。
MINID：驱逐 ID 低于的条目threshold，其中threshold是流 ID。

例如，这会将流修剪（trim）为恰好最新的 1000 个项目：

XTRIM mystream MAXLEN 1000

而在本例中，所有 ID 低于 649085820-0 的条目都将被驱逐：

XTRIM mystream MINID 649085820

默认情况下，或在提供可选=参数时，该命令执行精确修剪（trim）。

根据策略，精确修剪（trim）意味着：

MAXLEN：修剪（trim）后的流的长度将恰好是其原始长度和指定之间的最小值threshold。
MINID：流中最旧的 ID 将恰好是其原始最旧 ID 和指定的之间的最小值threshold。

几乎精确的修剪（trim）

由于精确修剪（trim）可能需要 Keybyte 服务器的额外工作，因此可以提供可选参数以使其更高效。

例如：

XTRIM mystream MAXLEN ~ 1000

所述~的参数之间MAXLEN策略和threshold用户正在请求修整流，以便它的长度是这样的装置至少在threshold，但可能略多。在这种情况下，Keybyte 将在可以获得性能时提前停止修剪（trim）（例如，当无法删除数据结构中的整个宏节点时）。这使得修剪（trim）效率更高，这通常是您想要的，尽管修剪（trim）后，流可能在threshold.

使用 , 时控制命令完成的工作量的另一种方法~是LIMIT子句。使用时，它指定count将被驱逐的最大条目。当LIMIT和count未指定时，默认值 100 * 宏节点中的条目数将隐式用作count. 将值 0 指定为count完全禁用限制机制。

返回值

整数回复：从流中删除的条目数。

Strings

APPEND

如果key已经存在并且是一个字符串，则此命令将value附加到字符串的末尾。如果key不存在，则创建并设置为空字符串，因此在这种特殊情况下APPEND 将类似于SET。

返回值

整数回复：追加操作后的字符串长度。

例子

redis> EXISTS mykey

(integer) 0

redis> APPEND mykey "Hello"

(integer) 5

redis> APPEND mykey " World"

(integer) 11

redis> GET mykey

"Hello World"



redis>

模式：时间序列

的APPEND命令可以用来创建固定大小的示例的列表的一个非常紧凑的表示中，通常被称为时间序列。每次新样本到达时，我们都可以使用命令存储它

APPEND timeseries "fixed-size sample"

访问时间序列中的单个元素并不难：

可以使用STRLEN来获取样本数量。
GETRANGE允许随机访问元素。如果我们的时间序列有相关的时间信息，我们可以很容易地实现二进制搜索来获取范围，结合GETRANGE和 Keybyte中可用的 Lua 脚本引擎。
SETRANGE可用于覆盖现有的时间序列。

这种模式的局限性在于我们被迫进入仅追加操作模式，无法轻松地将时间序列剪切到给定大小，因为 Keybyte 目前缺乏能够修剪（trim）字符串对象的命令。然而，以这种方式存储的时间序列的空间效率是显着的。

提示：可以根据当前的 Unix 时间切换到不同的键，这样每个键的样本量可能相对较少，避免处理非常大的键，并使这种模式更加友好地分布在许多 Keybyte 实例中。

使用固定大小的字符串（在实际实现中使用二进制格式更好）对传感器的温度进行采样的示例。

redis> APPEND ts "0043"

(integer) 4

redis> APPEND ts "0035"

(integer) 8

redis> GETRANGE ts 0 3

"0043"

redis> GETRANGE ts 4 7

"0035"



redis>

DECR

将存储的数字减key一。如果key不存在，则0在执行操作前设置为。如果键包含错误类型的值或包含不能表示为整数的字符串，则返回错误。此操作仅限于64 位有符号整数。

有关递增/递减操作的额外信息，请参阅INCR。

返回值

整数回复：key递减后的值

DECRBY

递减存储在数key通过decrement。如果key不存在，则在执行操作前设置为0。如果键包含错误类型的值或包含不能表示为整数的字符串，则返回错误。此操作仅限于 64 位有符号整数。

有关递增/递减操作的额外信息，请参阅INCR。

返回值

整数回复：key递减后的值

GET

获取的值key。如果键不存在，nil则返回特殊值。如果存储的值key不是字符串，则会返回错误，因为GET 仅处理字符串值。

返回值

批量字符串回复：key的值，当key不存在时为nil。

GETDEL

获取key键的值并删除键。此命令与GET类似，不同之处在于它还会在成功时删除键（当且仅当键的值类型是字符串时）。

返回值

批量字符串回复： key的值，当key不存在时为nil。或者如果键的值类型不是字符串则出错。

GETEX

获取的值key并可选择设置其到期时间。 GETEX类似于GET，但它是一个带有附加选项的写命令。

选项

该GETEX命令支持一组修改其行为的选项：

EX seconds -- 设置指定的过期时间，以秒为单位。
PX millisecond-- 设置指定的过期时间，以毫秒为单位。
EXAT timestamp-seconds -- 设置key到期的指定 Unix 时间，以秒为单位。
PXAT timestamp-milliseconds -- 设置指定的 Unix 时间，key将到期，以毫秒为单位。
PERSIST -- 删除与key关联的生存时间。

返回值

批量字符串回复：key的值，当key不存在时为nil。

GETRANGE

返回存储在key的字符串值的子字符串，由偏移量start和end（两者都包含）确定。可以使用负偏移量来提供从字符串末尾开始的偏移量。所以 -1 表示最后一个字符，-2 表示倒数第二个，依此类推。

该函数通过将结果范围限制为字符串的实际长度来处理超出范围的请求。

返回值

批量字符串回复

GETSET

以原子方式设置key到value返回存储在旧值key。当key存在但不包含字符串值时返回错误。成功的SET操作将丢弃与key关联的任何先前的生存时间。

设计模式

GETSET可与INCR一起使用以进行原子复位计数。例如：进程可能会在每次发生某些事件时针对键调用INCRmycounter，但有时我们需要获取计数器的值并将其自动重置为零。这可以使用GETSET mycounter "0"：

返回值

批量字符串回复：存储在key中的值或当key不存在时回复nil

INCR

将存储的数字key加一。如果key不存在，则在执行操作前设置为0。如果键包含错误类型的值或包含不能表示为整数的字符串，则返回错误。此操作仅限于 64 位有符号整数。

注意：这是一个字符串操作，因为 Keybyte 没有专用的整数类型。存储在键中的字符串被解释为以 10 为基数的64 位有符号整数来执行操作。

Keybyte 以整数表示形式存储整数，因此对于实际保存整数的字符串值，存储整数的字符串表示没有开销。

返回值

整数回复：key增量后的值

例子

redis> **SET mykey "10"**

"OK"

redis> **INCR mykey**

(integer) 11

redis> **GET mykey**

"11"



redis>

图案：计数器

计数器模式是你可以用 Keybyte 原子增量操作做的最明显的事情。这个想法只是在每次发生操作时向 Keybyte发送一个INCR命令。例如，在一个 Web 应用程序中，我们可能想知道该用户一年中每天的页面浏览量。

为此，Web 应用程序可以在每次用户执行页面查看时简单地增加一个键，创建键名，将用户 ID 和一个表示当前日期的字符串连接起来。

这个简单的模式可以通过多种方式扩展：

可以在每次页面查看时一起使用INCR和EXPIRE以让计数器仅计算间隔小于指定秒数的最新 N 个页面查看。
客户端可以使用 GETSET 来自动获取当前计数器值并将其重置为零。
使用其他原子递增/递减命令（如DECR或INCRBY），可以根据用户执行的操作处理可能变大或变小的值。例如，想象一下在线游戏中不同用户的得分。

模式：速率限制器

速率限制器模式是一个特殊的计数器，用于限制可以执行操作的速率。这种模式的经典实现涉及限制可以针对公共 API 执行的请求数量。

我们使用INCR提供了这种模式的两种实现，我们假设要解决的问题是将 API 调用的数量限制为每个 IP 地址每秒最多10 个请求。

模式：速率限制器 1

这种模式更简单直接的实现如下：

FUNCTION LIMIT_API_CALL(ip)

ts = CURRENT_UNIX_TIME()

keyname = ip+":"+ts

MULTI

    INCR(keyname)

    EXPIRE(keyname,10)

EXEC

current = RESPONSE_OF_INCR_WITHIN_MULTI

IF current > 10 THEN

    ERROR "too many requests per second"

ELSE

    PERFORM_API_CALL()

END

基本上，我们为每个 IP 都有一个计数器，每秒钟都有一个计数器。但是这个计数器总是递增，设置 10 秒的过期时间，这样当当前秒不同时，它们会被 Keybyte 自动删除。

请注意MULTI和EXEC的使用，以确保我们将在每次 API 调用时都增加并设置到期时间。

模式：速率限制器 2

另一种实现使用单个计数器，但要在没有竞争条件的情况下正确实现它有点复杂。我们将检查不同的变体。

FUNCTION LIMIT_API_CALL(ip):

current = GET(ip)

IF current != NULL AND current > 10 THEN

    ERROR "too many requests per second"

ELSE

    value = INCR(ip)

    IF value == 1 THEN

        EXPIRE(ip,1)

    END

    PERFORM_API_CALL()

END

计数器的创建方式是，从当前秒内执行的第一个请求开始，它只能存活一秒。如果同一秒内有超过 10 个请求，计数器将达到大于 10 的值，否则它将过期并重新从 0 开始。

在上面的代码中有一个竞争条件。如果由于某种原因客户端执行了INCR命令但没有执行EXPIRE，则key将被泄露，直到我们再次看到相同的 IP 地址。

这可以很容易地修复，将带有可选EXPIRE的INCR转换为使用EVAL命令发送的 Lua 脚本。

local current

current = redis.call("incr",KEYS[1])

if current == 1 then

    redis.call("expire",KEYS[1],1)

end

有一种不同的方法可以在不使用脚本的情况下解决此问题，而是使用 Keybyte 列表而不是计数器。实现更复杂并使用更高级的功能，但具有记住当前执行 API 调用的客户端的 IP 地址的优点，这可能有用或无用取决于应用程序。

FUNCTION LIMIT_API_CALL(ip)

current = LLEN(ip)

IF current > 10 THEN

    ERROR "too many requests per second"

ELSE

    IF EXISTS(ip) == FALSE

        MULTI

            RPUSH(ip,ip)

            EXPIRE(ip,1)

        EXEC

    ELSE

        RPUSHX(ip,ip)

    END

    PERFORM_API_CALL()

END

如果键已经存在，RPUSHX命令只会推送元素。

请注意，我们在这里有一个竞争，但这不是问题：EXISTS可能返回 false，但在我们在MULTI / EXEC块内创建key之前，key可能由另一个客户端创建。然而，这种竞争在极少数情况下只会错过 API 调用，因此速率限制仍将正常工作。

INCRBY

使存储在号码key通过increment。如果key不存在，则在执行操作前设置为0。如果键包含错误类型的值或包含不能表示为整数的字符串，则返回错误。此操作仅限于 64 位有符号整数。

有关递增/递减操作的额外信息，请参阅INCR。

返回值

整数回复：key增量后的值

INCRBYFLOAT

递增表示key由指定存储在的浮点数的字符串increment。通过使用负值increment，结果是存储在键中的值递减（通过明显的加法属性）。如果key不存在，则0在执行操作前设置为。如果发生以下情况之一，则返回错误：

键包含错误类型的值（不是字符串）。
当前键内容或指定的增量不能解析为双精度浮点数。

如果命令成功，则新增加的值将存储为键的新值（替换旧值），并作为字符串返回给调用者。

字符串键中已经包含的值和增量参数都可以选择以指数表示法提供，但是增量后计算的值以相同的格式一致存储，即一个整数，后跟（如果需要）一个点，以及代表数字小数部分的可变位数。尾随零总是被删除。

无论计算的实际内部精度如何，输出的精度都固定在小数点后 17 位。

返回值

批量字符串回复：key增量后的值。

MGET

返回所有指定键的值。对于每个不包含字符串值或不存在的键，nil都会返回特殊值。因此，操作永远不会失败。

返回值

数组回复：指定键的值列表。

MSET

将给定的键设置为其各自的值。 MSET用新值替换现有值，就像常规SET 一样。如果您不想覆盖现有值，请参阅MSETNX。

MSET是原子的，所以所有给定的键都是一次设置的。客户端不可能看到某些key已更新而其他key未更改。

返回值

简单的字符串回复：总是OK因为MSET不会失败。

MSETNX

将给定的键设置为其各自的值。即使只有一个键已经存在，MSETNX也不会执行任何操作。

由于此语义，MSETNX可用于以确保设置所有字段或根本不设置字段的方式设置代表唯一逻辑对象的不同字段的不同键。

MSETNX是原子的，所以所有给定的键都是一次设置的。客户端不可能看到某些key已更新而其他key未更改。

返回值

整数回复，特别是：

如果设置了所有键，则返回1。
如果没有设置键（至少一个键已经存在），则返回0。

PSETEX

PSETEX 的工作方式与SETEX完全一样，唯一的区别是过期时间以毫秒而不是秒指定。

SET

设置key为保持字符串value。如果key已经拥有一个值，则无论其类型如何，它都会被覆盖。成功的SET操作将丢弃与key关联的任何先前的生存时间。

选项

在SET命令支持一组修改其行为的选项：

EX seconds -- 设置指定的过期时间，以秒为单位。
PX millisecond-- 设置指定的过期时间，以毫秒为单位。
EXAT timestamp-seconds -- 设置key到期的指定 Unix 时间，以秒为单位。
PXAT timestamp-milliseconds -- 设置指定的 Unix 时间，key将到期，以毫秒为单位。
NX -- 仅在不存在的情况下设置key。
XX -- 仅设置已存在的key。
KEEPTTL -- 保留与key关联的生存时间。
GET -- 返回存储在 key 中的旧字符串，如果 key 不存在，则返回 nil。如果 key 中存储的值不是字符串，则返回错误并中止SET。

注意：由于SET命令选项可以替换SETNX、SETEX、PSETEX、GETSET，因此在未来的 Keybyte 版本中，这些命令可能会被弃用并最终被删除。

返回值

简单的字符串回复：（OK）如果SET被正确执行。

空回复：(nil)如果由于用户指定了or选项而未执行SET操作但不满足条件。NXXX

如果使用GET选项发出命令，则上述内容不适用。它将改为如下回复，无论SET是否实际执行：

批量字符串回复：存储在键中的旧字符串值。

空回复：(nil)如果键不存在。

例子

redis> **SET mykey "Hello"**

"OK"

redis> **GET mykey**

"Hello"

redis> **SET anotherkey "will expire in a minute" EX 60**

"OK"



redis>

图案

注意：不鼓励使用以下模式，以支持Redlock 算法，该算法实现起来稍微复杂一点，但提供更好的保证并且具有容错性。

该命令SET resource-name anystring NX EX max-lock-time是一种使用 Keybyte 实现锁定系统的简单方法。

如果上述命令返回，客户端可以获取锁OK（如果命令返回 Nil，则在一段时间后重试），并仅使用DEL删除锁。

达到到期时间后，锁将自动释放。

修改解锁模式可以使这个系统更加健壮，如下所示：

不是设置固定字符串，而是设置一个不可猜测的大随机字符串，称为令牌。
不要使用DEL释放锁，而是发送一个脚本，该脚本仅在值匹配时删除key。

这避免了客户端会在过期时间后尝试释放锁，删除稍后获取锁的另一个客户端创建的key。

解锁脚本的示例类似于以下内容：

if redis.call("get",KEYS[1]) == ARGV[1]

then

    return redis.call("del",KEYS[1])

else

    return 0

end

脚本应该被调用 EVAL …script… 1 resource-name token-value

SETEX

设置key为保持字符串value并key在给定秒数后设置为超时。该命令相当于执行以下命令：

SET mykey value

EXPIRE mykey seconds

SETEX是原子的，可以通过使用MULTI / EXEC块中的前两个命令来重现。它是作为给定操作序列的更快替代方案提供的，因为当 Keybyte 用作缓存时，此操作非常常见。

seconds无效时返回错误。

返回值

简单的字符串回复

SETNX

如果不存在，则设置key为保持字符串。在这种情况下，它等于SET。当已经持有一个值时，不执行任何操作。 SETNX是”SET if Not eXists”的简写。

返回值

整数回复，特别是：

如果设置了key，则返回1
如果未设置key，则返回0

SETRANGE

覆盖存储在key 的部分字符串，从指定的偏移量开始，覆盖value的整个长度。如果偏移量大于key 处字符串的当前长度，则用零字节填充该字符串以使偏移量适合。不存在的键被视为空字符串，因此此命令将确保它包含一个足够大的字符串，以便能够在offset处设置值。

请注意，您可以设置的最大偏移量为 2 ²⁹ -1 (536870911)，因为 Keybyte 字符串限制为 512 兆字节。如果您需要增长超过此大小，您可以使用多个key。

警告：当设置最后一个可能的字节并且存储在 key 中的字符串值还没有保存字符串值，或者保存一个很小的字符串值时，Keybyte需要分配所有可能阻塞服务器一段时间的中间内存。在 2010 款 MacBook Pro 上，设置字节数 536870911（512MB 分配）需要约 300 毫秒，设置字节数 134217728（128MB 分配）需要约 80 毫秒，设置位号 33554432（32MB 分配）需要约 30 毫秒和设置位号 838860 分配需要~8ms。请注意，一旦第一次分配完成，对相同键的后续调用SETRANGE 不会有分配开销。

图案

多亏了SETRANGE和类似的GETRANGE命令，您可以将 Keybyte 字符串用作具有O(1)随机访问的线性数组。在许多现实世界的用例中，这是一种非常快速和高效的存储。

返回值

整数回复：被命令修改后的字符串长度。

STRALGO

STRALGO 实现了对字符串进行操作的复杂算法。现在唯一实现的算法是 LCS 算法（最长公共子串）。然而，未来可能会实施新的算法。此命令的目标是向 Keybyte 用户提供需要快速实现且大多数编程语言的标准库中通常不提供的算法。

命令的第一个参数选择要使用的算法，现在参数必须是“LCS”，因为这是唯一实现的。

LCS算法

STRALGO LCS STRINGS <string_a> <string_b> | KEYS <key_a> <key_b>
[LEN] [IDX] [MINMATCHLEN <len>] [WITHMATCHLEN]

LCS 子命令实现最长公共子序列算法。请注意，这与最长公共字符串算法不同，因为字符串中的匹配字符不需要是连续的。

例如“foo”和“fao”之间的LCS是“fo”，由于从左到右扫描两个字符串，最长的公共字符集由第一个“f”和“o”组成。

LCS 对于评估两个字符串的相似程度非常有用。字符串可以代表很多东西。例如，如果两个字符串是 DNA 序列，LCS 将提供两个 DNA 序列之间相似性的度量。如果字符串代表某个用户编辑的某些文本，则 LCS 可以代表新文本与旧文本相比的差异，等等。

请注意，该算法O(N*M)及时运行，其中 N 是第一个字符串的长度，M 是第二个字符串的长度。因此，要么旋转不同的 Keybyte 实例以运行此算法，要么确保针对非常小的字符串运行它。

基本用法如下：

> STRALGO LCS STRINGS ohmytext mynewtext

"mytext"

也可以计算两个键的内容之间的 LCS：

> MSET key1 ohmytext key2 mynewtext

OK

> STRALGO LCS KEYS key1 key2

"mytext"

有时我们只需要匹配的长度：

> STRALGO LCS STRINGS ohmytext mynewtext LEN

6

然而，通常非常有用的是知道每个字符串中的匹配位置：

> STRALGO LCS KEYS key1 key2 IDX

1) "matches"

2) 1) 1) 1) (integer) 4

         2) (integer) 7

      2) 1) (integer) 5

         2) (integer) 8

   2) 1) 1) (integer) 2

         2) (integer) 3

      2) 1) (integer) 0

         2) (integer) 1

3) "len"

4) (integer) 6

匹配是从最后一个到第一个产生的，因为这是算法的工作方式，并且以相同的顺序发出事物更有效。上面的数组意味着第一个匹配项（数组的第二个元素）在第一个字符串的位置 2-3 和第二个字符串的 0-1 之间。然后是 4-7 和 5-8 之间的另一场比赛。

要将匹配列表限制为给定最小长度的匹配列表：

> STRALGO LCS KEYS key1 key2 IDX MINMATCHLEN 4

1) "matches"

2) 1) 1) 1) (integer) 4

         2) (integer) 7

      2) 1) (integer) 5

         2) (integer) 8

3) "len"

4) (integer) 6

最后还有匹配len：

> STRALGO LCS KEYS key1 key2 IDX MINMATCHLEN 4
WITHMATCHLEN

1) "matches"

2) 1) 1) 1) (integer) 4

         2) (integer) 7

      2) 1) (integer) 5

         2) (integer) 8

      3) (integer) 4

3) "len"

4) (integer) 6

返回值

对于 LCS 算法：

如果没有修饰符，则返回表示最长公共子字符串的字符串。
当LEN给出命令时，返回最长公共子串的长度。
当IDX给出命令时，该命令返回一个数组，其中包含 LCS 长度和字符串中的所有范围，每个字符串的开始和结束偏移量，其中有匹配项。当WITHMATCHLEN给出每个表示匹配的数组时，也将具有匹配的长度（参见示例）。

STRLEN

返回存储在key的字符串值的长度。key持有非字符串值时返回错误。

返回值

整数回复：字符串的长度 at key，或者0whenkey不存在。

Transactions

DISCARD

刷新事务中所有先前排队的命令并将连接状态恢复为正常。

如果使用了WATCH，则DISCARD会取消监视连接监视的所有键。

返回值

简单的字符串回复：始终OK。

EXEC

执行事务中所有先前排队的命令并将连接状态恢复为正常。

使用WATCH 时，EXEC仅在监视的键未被修改时才会执行命令，从而允许检查和设置机制。

返回值

数组回复：每个元素都是对原子事务中每个命令的回复。

使用WATCH 时，如果执行被中止，EXEC可以返回Null 回复。

MULTI

标记事务块的开始。后续命令将使用EXEC排队等待原子执行。

返回值

简单的字符串回复：始终OK。

UNWATCH

刷新事务的所有先前监视的键。

如果您调用EXEC或DISCARD，则无需手动调用UNWATCH。

返回值

简单的字符串回复：始终OK。

WATCH

标记要监视的给定键，以便有条件地执行事务。

返回值

简单的字符串回复：始终OK。

OPSLLM

咨询热线