SCARD 是 Redis 中专门用于读取 Set 集合元素数量的命令，全称可以理解为 set cardinality，也就是集合基数。很多人在第一次使用时担心一个包含上百万元素的集合调用 SCARD 会不会拖慢 Redis，实际上这个命令的执行成本极低。先创建集合并写入成员，然后调用 SCARD：
一、SCARD 命令的基本语法与返回值
SCARD 的语法只有一个参数，即 key。通过 redis-cli 可以这样操作：
# 向集合中加入三个元素 SADD user:online 1001 1002 1003 # 获取集合当前元素数量 SCARD user:online
这条命令会返回整数 3。需要注意的是，当指定的 key 不存在时，SCARD 返回 0，而不是 nil。这一点与 GET 命令不同，开发时不要用 SCARD 判断键是否存在，因为它对不存在的键和空集合无法区分。若 key 存在但类型不是 Set，例如字符串、列表或哈希，Redis 会返回 WRONGTYPE 错误，提示操作的对象类型不正确。
除了命令行，在 Java、Python、Go 等客户端库中，SCARD 通常被封装为返回整数类型的方法。例如在 Python 的 redis-py 中，client.scard("user:online") 返回 int。接收返回值时不必担心时间消耗，因为命令本身不传输成员数据。
二、SCARD 为什么能做到 O(1)
SCARD 的高性能来自 Redis 对 Set 底层结构的精心设计。Redis 的 Set 类型有两种内部编码：intset 和 hashtable。当集合元素全部为整数并且数量不超过 set-max-intset-entries 参数时，Redis 使用 intset；否则转换为 hashtable。两种结构都维护了元素数量信息，SCARD 直接读取这个长度字段，所以不需要遍历集合。
以 intset 为例，其头部包含一个 length 属性，SADD 和 SREM 操作会同步更新 length。hashtable 编码中，底层 dict 结构同样记录了键值对总数。因此即使集合拥有数十万甚至上百万个成员，SCARD 的执行时间也不会随数据量增长而明显增加。这个设计和很多编程语言里集合的 size() 方法类似。
不过要区分单节点和集群环境。官方文档中的 O(1) 指的是单个 key 在单个 Redis 实例上的表现。如果你使用 Redis Cluster，并且业务数据分散在不同槽位，想统计总数量就必须对每个相关 key 执行 SCARD 再加总，或者在客户端维护计数。SCARD 本身不具备跨 key 聚合能力。
三、SCARD 与 SMEMBERS、SSCAN 的选择
SCARD、SMEMBERS、SSCAN 是操作 Set 的常见命令，但用途截然不同。SMEMBERS 返回集合中所有成员，时间复杂度 O(N)，当集合很大时会一次性把成员全部拉回客户端，可能造成网络阻塞和内存峰值。SSCAN 采用游标方式分批遍历集合，适合需要展示或处理全量成员的场景，但它返回的是成员信息，不是数量。SCARD 只返回一个整数，不涉及成员数据传输。
如果页面只需要显示某个标签集合一共有多少个不同值，应该用 SCARD，而不是 SMEMBERS。很多性能问题正是因为在查看大集合数量时误用了 SMEMBERS，导致 Redis 输出缓冲区被打满。如果需要分页展示集合成员，可以先执行 SCARD 获取总数，再使用 SSCAN 按页拉取。例如列表页顶部显示共有 128 个设备在线，下方表格用 SSCAN 每次返回 20 条记录。
一个简单判断标准是：只要业务不关心具体成员，只关心数量，就选 SCARD。需要成员明细时才考虑 SSCAN，避免使用 SMEMBERS 读取大集合。
四、实战场景：标签去重与在线统计
内容管理系统中，一篇文章可能被多个编辑打标签，重复标签不应重复计数。用 Redis Set 存储标签，SADD 天然去重，SCARD 直接给出标签数量。
# 添加文章标签 SADD article:10086:tags redis 缓存 后端 # 重复添加同一个标签 SADD article:10086:tags redis # 查看标签总数 SCARD article:10086:tags
执行到 SCARD 时返回 3，说明重复的 redis 标签没有被重复统计。这个场景下，如果标签集合增长到几万甚至几十万，SCARD 依然可以快速响应，因为读取操作不会遍历整个 Set。需要注意的是，Set 不保留插入顺序，如果标签还需要按添加时间展示，可以同时使用 ZSet 维护顺序，但 SCARD 仅对 Set 生效。
另一个典型应用是活跃设备统计。每次设备启动时执行 SADD device:active:20250401 设备ID，管理后台通过 SCARD device:active:20250401 获取当日活跃设备总数。这里不能只用 SCARD 做历史趋势，因为每天需要独立 key。若需要跨天去重统计，可以结合 Bitmap 或 HyperLogLog，但那是另外的话题。
五、常见疑问与排错方法
不少开发者问到，SCARD 读到的数量会不会包含已经过期但尚未删除的元素？Redis 的过期机制采用惰性删除和定期删除结合，一旦键被认为过期，任何访问该键的命令都会先触发删除，SCARD 也会返回 0。因此在逻辑上层不需要额外判断过期，与不存在键的表现一致。
另一个高频疑问是，为什么 Redis Cluster 中执行 SCARD 有时只统计到部分数据？这是因为 Cluster 按槽位分布数据，同一个业务对象可能使用不同的 key 存储在不同的节点上。例如统计文章标签时，如果 key 设计为 article:10086:tags，这个键只会在一个槽位，不存在部分数据问题。但如果你的数据被拆分到多个 key，比如 article:10086:tag:0、article:10086:tag:1，就必须分别 SCARD 再求和。
遇到 SCARD 报错 WRONGTYPE 时，应先执行 TYPE key 检查键类型。最常见的原因是 key 之前被其他命令如 SET 或 LPUSH 占用。此时如果确认旧数据可以删除，执行 DEL 后重新用 SADD 写入 Set 即可。排错过程中不要盲目重启 Redis，因为键类型错误与实例稳定性无关。
Redis SCARD集合基数SCARD 命令修改时间：2026-09-22 20:00:13