redis scan命令详解

翻译自：https://redis.io/commands/scan

使用SCAN命令和与之密切相关的命令SSCAN，HSCAN和ZSCAN以便逐步迭代元素集合。

• SCAN迭代当前选择的Redis数据库中的密钥集。
• SSCAN迭代Sets类型的元素。
• HSCAN迭代Hash类型的字段及其关联的值。
• ZSCAN迭代“排序集”类型的元素及其关联的分数。

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

但是，尽管像SMEMBERS这样的阻塞命令能够在给定的时间内提供Set中所有元素，但是SCAN系列命令仅对返回的元素提供有限的保证，因为我们递增迭代的集合可以在迭代过程中更改。

请注意，SCAN，SSCAN，HSCAN和ZSCAN的工作方式都非常相似，因此本文档涵盖了所有四个命令。但是，明显的区别是，对于SSCAN，HSCAN和ZSCAN，第一个参数是保存Set，Hash或Sorted Set值的键的名称。该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选项来调整每次调用返回的元素数量的数量级。

COUNT选项

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

• COUNT的默认值为10。
• 当迭代键空间或足够大以可由哈希表表示的Set，Hash或Sorted Set时，假设未使用MATCH选项，则服务器通常将返回计数或每次调用返回的计数元素多于计数元素。请检查为什么SCAN可能一次返回本文档后面的所有元素。
• 当迭代编码为整数集的Set（仅由整数组成的小集合）或编码为ziplist的哈希和有序集（哈希和由较小的单个值组成的集合）时，通常无论第COUNT个计数如何，所有元素均在第一个SCAN调用中返回值。

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

MATCH选项

可以仅迭代与给定的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>

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

TYPE选项

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

该type参数与TYPE命令返回的字符串名称相同。请注意一个怪癖，其中某些Redis类型（例如GeoHashes，HyperLogLogs，Bitmap和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选项值如何。发生这种情况的原因是，仅当我们要扫描的聚合数据类型表示为哈希表时，才可以实现基于游标的迭代器，并且它很有用。但是，Redis使用内存优化，其中使用紧凑的单分配打包编码来表示小的聚合数据类型，直到它们达到给定数量的项或给定的单个元素的最大大小为止。在这种情况下，请扫描 没有有意义的游标要返回，并且必须立即迭代整个数据结构，因此它唯一明智的行为是在调用中返回所有内容。

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

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

返回值

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

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