3.1 基本换算#

1
1 byte = 8 bit

Redis 的 offset 从 0 开始：

• 第 1 个字节保存 offset 0～7；
• 第 2 个字节保存 offset 8～15；
• 第 n 个 bit 所在字节是 floor(offset / 8)。

一个字节内按“从最高有效位到最低有效位”编号：

1
字节内容： 1 0 1 0 0 0 0 1
2
offset：   0 1 2 3 4 5 6 7

因此：

1
SETBIT demo 0 1

会把第一个字节的最高位设置为 1，而不是最低位。

3.2 最大容量#

String 的最大长度是 512 MiB，因此单个 Bitmap 最多可以寻址：

1
512 MiB × 8 = 2^32 bit

offset 的有效范围是：

1
0 ～ 2^32 - 1

也就是最多约 42.95 亿个位。

3.3 内存估算#

如果最大 offset 为 m，数据部分至少需要：

1
floor(m / 8) + 1 字节

常见规模：

这些数字不包含 Redis 对象、key、内存分配器等额外开销。

Bitmap 并不是稀疏压缩结构。即使只执行：

1
SETBIT users 1000000000 1

Redis 也必须分配能够覆盖 offset 10 亿的连续 String，约占 119 MiB。对很短的 key 突然设置极远 offset，扩容和补零还可能阻塞 Redis 主线程。

4.1 适合#

• 对象可以映射为较连续、较紧凑的非负整数；
• 每个对象只需表示 0/1；
• 经常需要计数、交集、并集或差集；
• 不要求直接从 Bitmap 中列出完整业务对象。

4.2 不适合#

• ID 极度稀疏，例如只有少量用户但 ID 接近十亿；
• 需要保存名称、时间、次数等附加信息；
• 经常需要遍历并返回所有成员；
• 单个对象不只是布尔状态；
• 需要给每个 bit 单独设置 TTL。

Bitmap 的 TTL 是 key 级别的，不能给单独一个 bit 设置过期时间。

6.1 SETBIT：设置 bit#

1
SETBIT key offset value

• offset 从 0 开始；
• value 只能是 0 或 1；
• key 不存在时自动创建；
• 超出当前长度时自动扩容，中间部分补 0；
• 返回 修改前的 bit 值，不是修改后的值。

示例：

1
SETBIT active:2026-07-27 1001 1

第一次返回：

1
(integer) 0

重复执行返回：

1
(integer) 1

因此返回值可以用来判断“这是不是用户当天第一次活跃”，但业务端仍需考虑事件、网络重试和整体流程的幂等性。

清除状态：

1
SETBIT active:2026-07-27 1001 0

6.2 GETBIT：读取 bit#

1
GETBIT key offset

示例：

1
GETBIT active:2026-07-27 1001

返回 0 或 1。key 不存在或 offset 超过当前 String 长度时返回 0。

6.3 BITCOUNT：统计 1 的数量#

1
BITCOUNT key [start end [BYTE | BIT]]

统计整个 Bitmap：

1
BITCOUNT active:2026-07-27

如果“一名用户对应一个 offset”，结果就是当天去重活跃用户数。

范围查询默认按 byte，而且 start、end 都包含在内：

1
BITCOUNT key 0 0

表示统计第 1 个字节（offset 0～7），不是只统计 bit 0。

Redis 7.0+ 可以显式按 bit 范围统计：

1
BITCOUNT key 0 0 BIT

这才表示只统计 bit 0。BYTE 是默认模式。范围索引可以为负数，-1 表示最后一个 byte 或 bit，取决于指定的模式。

6.4 BITOP：位运算#

当前语法：

1
BITOP operation destination source [source ...]

经典操作：

Redis 8.2 新增：

示例——连续两天都活跃：

1
BITOP AND active:{app}:both \
2
  active:{app}:2026-07-26 \
3
  active:{app}:2026-07-27
4

5
BITCOUNT active:{app}:both

示例——两天内至少活跃一次：

1
BITOP OR active:{app}:union \
2
  active:{app}:2026-07-26 \
3
  active:{app}:2026-07-27
4

5
BITCOUNT active:{app}:union

Redis 8.2+ 查询“昨天活跃、今天未活跃”：

1
BITOP DIFF active:{app}:lost \
2
  active:{app}:2026-07-26 \
3
  active:{app}:2026-07-27
4

5
BITCOUNT active:{app}:lost

需要注意：

• 运算结果总会写入 destination；
• 返回值是目标 String 的字节长度，不是 1 的数量；
• 要统计结果，继续使用 BITCOUNT destination；
• 较短或不存在的源 key 会按 0 补齐到最长源 key 的长度；
• BITOP 是 O(N)，大 Bitmap 运算可能阻塞；
• Redis 8.2 以前只有 AND、OR、XOR、NOT。

在 Redis Cluster 中，源 key 和目标 key 应位于同一个 slot。上例通过共同的 hash tag {app} 达到这一点。

6.5 BITPOS：寻找第一个 0 或 1#

1
BITPOS key bit [start [end [BYTE | BIT]]]

示例：

1
BITPOS active:2026-07-27 1

返回第一个值为 1 的绝对 bit offset。

默认情况下，start 和 end 是 byte 范围；Redis 7.0+ 可使用 BIT：

1
BITPOS key 0 100 199 BIT

在 bit 100～199 中寻找第一个 0，但返回值仍是从整个 Bitmap offset 0 开始计算的绝对位置。

特殊返回语义：

• 查找 1，但 key 为空或全为 0：返回 -1；
• 不限定完整范围地查找 0 时，Redis 会把 String 右侧视作有无限个 0，因此全为 1 的三字节 String 会返回 24；
• 如果同时明确给出 start 和 end，而该范围内没有目标 bit，则返回 -1。

6.6 BITFIELD：把位数组当小整数数组#

1
BITFIELD key
2
  [GET encoding offset |
3
   [OVERFLOW WRAP|SAT|FAIL]
4
   <SET encoding offset value |
5
    INCRBY encoding offset increment> ...]

BITFIELD 不只是操作单个 0/1，它可以将一段连续 bit 解释为整数。

编码格式：

• uN：N 位无符号整数，支持到 u63；
• iN：N 位有符号整数，支持到 i64；
• 例如 u8 的范围是 0～255，i8 的范围是 -128～127。

三种主要操作：

• GET：读取整数；
• SET：写入整数，返回旧值；
• INCRBY：原子增减，返回新值。

普通 offset 表示 bit offset：

1
BITFIELD stats SET u8 0 100 SET u8 8 20

带 # 的 offset 表示“第几个同宽整数”，Redis 会自动乘以字段宽度：

1
BITFIELD stats SET u8 #0 100 SET u8 #1 20
2
BITFIELD stats GET u8 #0 GET u8 #1

这两组写法等价。

溢出策略：

示例：

1
BITFIELD counters \
2
  SET u8 #0 254 \
3
  OVERFLOW SAT INCRBY u8 #0 10 \
4
  GET u8 #0

对应返回值依次是：

1
0
2
255
3
255

一条 BITFIELD 可以包含多个子操作，它们会按顺序原子执行，返回数组与子操作一一对应。

6.7 BITFIELD_RO：只读查询#

1
BITFIELD_RO key GET encoding offset [GET encoding offset ...]

它只允许 GET，不能使用 SET、INCRBY 或 OVERFLOW，适合明确的只读访问和只读副本。

示例：

1
BITFIELD_RO stats GET u8 #0 GET u8 #1