Floyd Small Object Compact Encoding：小型 Hash/Set/ZSet/List 紧凑存储预研

[AlexStocks]

背景

Floyd 当前对 Hash、Set、ZSet、List 采用 MetaCF + DataCF 的展开存储：一个 Redis Key 除了 metadata 外，每个 field/member/list element 还会形成独立 RocksDB entry；ZSet 同时维护 member→score 和 (score, member)→empty 两套索引。

这种格式适合大对象和局部更新，但对于只有少量元素的小对象，会重复存储 Redis Key、version、reserve、ctime，并增加 MemTable/SST entry、WAL、Bloom Filter、Block Index、Block Cache 和 Compaction 开销。

RocksDB 从 8.0 开始提供 Wide Columns：一个 key 可以对应多个 named columns。需要评估能否借此将小 Hash/Set/ZSet/List 聚合存储，类似 Redis 的 listpack/intset/quicklist 思路。

相关资料：

• RocksDB Wide Columns：https://github.com/facebook/rocksdb/wiki/Wide-Columns
• Floyd 存储生产化总讨论：Kiwi Floyd Storage 生产化改进：Redis Hashtag、多实例原子性、Compaction、Block Cache 与安全重分片 #344
• 存储格式版本化：feat(storage): 建立存储格式版本与迁移门禁 #342
• Reserve 与 Block Cache：[ENHANCE] Incomplete block cache sharing implementation #143

当前结论

“小对象聚合为一个 RocksDB KV”方向有价值，但当前不建议直接以 RocksDB WideColumnEntity 作为 Floyd 的生产存储格式。

更合适的候选方案是：

1. Kiwi/Floyd 自己定义 versioned packed value；
2. 小对象作为普通 RocksDB Value 存放在 MetaCF；
3. 超过阈值后，在一个 WriteBatch 内原子转换为现有 MetaCF + DataCF Expanded 格式；
4. 自动转换只做 Packed → Expanded，不在请求路径自动降级回 Packed；
5. 最终阈值由 benchmark 决定，Redis 默认值只作为初始参考。

本 Discussion 记录设计方向和后续验证项，当前优先级为 Low / Backlog，暂不进入实现。

为什么不直接采用 RocksDB Wide Columns

1. Wide Columns 当前仍是整体 Entity

RocksDB 会把 columns 序列化为一个 entity value，格式大致为：

version + column count + column name/value-size index + all column values

PutEntity 会覆盖完整 entity。当前公开 API 没有通用的单 column 更新、删除和只读取部分 columns 的能力。因此修改一个 Hash field，仍然需要读取、修改、重新序列化并写回整个 entity。

截至 RocksDB 11.1.2，公开 DB API 仍以 PutEntity、GetEntity、MultiGetEntity 为主，没有稳定的 UpdateColumn/DeleteColumn/Projection API。

2. 只有 Hash/Set 映射较自然

可能的映射：

Hash: column name = field,  column value = value
Set:  column name = member, column value = empty
ZSet: column name = member, column value = score
List: column name = index,  column value = element

问题是：

• RocksDB columns 按 column name 排序，ZSet 需要按 (score, member) 排序；
• List 的插入、删除和位置调整仍可能重写完整 entity；
• RocksDB 的空 column name 是 anonymous default column，而 Redis 允许空 field/member，需要额外转义或前缀；
• ZSet 若同时维护 member 顺序和 score 顺序，实际上仍需要 Floyd 自定义双索引编码。

3. 当前 rust-rocksdb binding 没有 Entity API

Kiwi 使用定制的 arana-db/rust-rocksdb，当前固定版本内部携带 RocksDB 10.9.1。C++ 层存在 Wide Columns，但 Rust 层没有完整暴露：

put_entity
get_entity
multi_get_entity
WideColumn / PinnableWideColumns
FilterV3

RocksDB 原生 C API 也没有直接提供完整 Wide Columns bridge，因此需要扩展 librocksdb-sys 的 C/C++ FFI、对象生命周期和错误处理。

4. Engine、Batch 与 Raft Binlog 不支持 Entity 类型

Floyd 当前 Engine/Batch 抽象只有普通 Put/Delete。Raft Binlog 的操作类型也只有：

NoOp
Put
Delete

Follower apply 会将 value 作为普通 KV 写入。WideColumnEntity 是 RocksDB internal value type；若只复制序列化后的 bytes 并使用普通 Put，Follower 得到的是普通 value，而不是 WideColumnEntity。

直接采用 Wide Columns，需要同步扩展 Engine、Batch、Binlog、Follower apply、snapshot/restore、混合版本兼容和存储格式门禁。

5. 当前 TTL Compaction Filter 无法处理 WideColumnEntity

Floyd 的 MetaCF TTL 清理依赖普通 CompactionFilter 解析 value 中的 type/etime。RocksDB 对 WideColumnEntity 需要使用 FilterV3；如果没有覆盖 FilterV3，默认行为是保留 WideColumnEntity。

当前 rust-rocksdb binding 没有暴露 FilterV3。如果直接把对象写成 entity，过期对象可能逻辑不可见，但无法由现有 TTL Compaction Filter 物理清理。

候选方案：Floyd Compact Encoding

建议为复合类型增加两种持久化编码：

Packed   # 小对象，全部内容位于 MetaCF 的一个普通 Value
Expanded # 当前 MetaCF + DataCF 展开格式

读取流程：

Get MetaCF
  → 检查 encoding
    → Packed: 解码单 Value 并执行命令
    → Expanded: 走现有 MetaCF + DataCF 路径

写入后若超过阈值：

持有 Redis Key 锁
  → 解码 Packed
  → 生成现有 DataCF entries
  → 将 Meta 标记为 Expanded
  → 同一个 RocksDB WriteBatch 原子提交

自动状态转换只做：

Packed → Expanded

Expanded 对象即使删除成员后重新变小，也不在在线请求路径自动转回 Packed，避免阈值附近反复转换、扫描 DataCF、制造 tombstone 和增加 Compaction 压力。未来如有需要，可由离线工具或低优先级后台任务完成 repack。

各数据类型的候选 Packed 编码

Hash

header + sorted(field, value) pairs

• field 按 bytewise 排序；
• HGET/HEXISTS 可二分查找；
• HGETALL/HKEYS/HVALS 顺序读取；
• HSET/HDEL 修改后整体重编码。

Set

建议支持两个子编码：

PackedIntSet
PackedStringSet

• 所有 member 都是规范化的十进制 i64 时使用有序整数数组；
• 其他情况使用 bytewise sorted、length-prefixed members；
• 必须保持 Redis binary-safe 和字符串相等语义，不能把 01 与 1 错误合并。

ZSet

header + sorted(score, member) pairs

• 按 (score, member) 排序，直接支持范围和 rank 类命令；
• 小对象下 ZSCORE/ZREM 可以线性扫描；
• 是否增加 member offset index 由 benchmark 决定，不在第一版预设双索引；
• 明确 NaN、±Inf、-0/+0 和同 score member 排序语义。

List

header + ordered length-prefixed elements

• 小 List 的 push/pop/index/range 只访问一个 RocksDB KV；
• 超阈值后先转换为现有逐元素 Expanded 格式；
• 长期可以另行评估 quicklist-like 分段 Value，避免大 List 一元素一 KV，但不属于本预研第一阶段。

阈值策略

可以借鉴 Redis 的维度，但不能只照搬 entry 数量：

hash-max-listpack-entries 512
hash-max-listpack-value 64
set-max-intset-entries 512
set-max-listpack-entries 128
set-max-listpack-value 64
zset-max-listpack-entries 128
zset-max-listpack-value 64
list-max-listpack-size -2  # 约 8 KiB/quicklist node

Floyd 还必须增加总编码大小上限：

max_entries
max_element_bytes
max_packed_bytes

只有三个条件都满足时保持 Packed。

第一轮 benchmark 候选范围：

类型	entry 候选	单元素候选	总 Packed 大小候选
Hash	64 / 128 / 256 / 512	64 B	4 / 8 / 16 KiB
String Set	64 / 128 / 256	64 B	4 / 8 / 16 KiB
Int Set	128 / 256 / 512	i64	4 / 8 KiB
ZSet	32 / 64 / 128	member 64 B	4 / 8 / 16 KiB
List	数量只作为保护项	单独限制大元素	4 / 8 / 16 KiB

Redis 的 list 8 KiB 是每个 quicklist node 的限制，不是整个 List 的限制。Floyd 第一版若把完整小 List 放入一个 Value，应把该限制理解为整个 Packed List 的大小上限。

存储格式与兼容性

该设计必须依赖 #342 的 StorageManifest 和 Value Format 版本门禁，例如：

value_format_version = 2
compound_encoding_version = 1

新版本可以识别旧 Expanded 和新 Packed/Expanded；旧二进制必须拒绝打开包含新格式的数据目录。

不能只在 reserve 中写一个 encoding bit 后继续允许旧二进制打开，否则旧代码可能把 Packed Meta 当成普通 metadata，再去 DataCF 查成员，最终把实际存在的数据错误表现为空。

后续 Benchmark 指标

在重新启动该方向前，至少需要比较 Packed 与 Expanded 的：

• WAL bytes；
• MemTable/SST entry 数；
• 数据库空间；
• RocksDB bytes written；
• Compaction bytes read/written；
• Bloom/index/filter size；
• Block Cache 占用和 hit rate；
• 命令吞吐及 p50/p95/p99；
• CPU、临时分配和完整 Value 重写成本；
• Packed → Expanded 转换延迟；
• 重启、快照、备份和 Raft apply 一致性。

测试数据应覆盖不同 entry 数、element 大小、总 payload 大小，以及 Hash/Set/ZSet/List 的 point/range/update/delete 命令。

优先级与启动条件

当前优先级：Low / Backlog。

在以下前置条件满足前不进入实现：

1. feat(storage): 建立存储格式版本与迁移门禁 #342 存储格式版本化与升级门禁具备可用设计或实现；
2. [ENHANCE] Incomplete block cache sharing implementation #143 Block Cache/空间放大指标能够测量；
3. Redis结构体compaction线程管理优化 #88 Compaction 闭环具备基本可观测性；
4. 有真实或合成 workload 证明小型复合对象占比足够高；
5. 建立 Packed/Expanded 对比 benchmark；
6. 明确 Raft、快照、备份与恢复兼容要求。

若将来 RocksDB 提供稳定的 column-level update/projection，且 rust-rocksdb 完整暴露 PutEntity/GetEntity/FilterV3，可以重新评估 Wide Columns。届时建议先从映射最自然的小 Hash 做实验，不一次覆盖四种数据类型。

非目标

• 当前不实现代码；
• 当前不确定最终阈值默认值；
• 当前不修改已有存储格式；
• 当前不承诺 Expanded → Packed 在线自动转换；
• 当前不直接引入 RocksDB WideColumnEntity；
• 当前不把 Large List 分段存储纳入同一阶段。