在Cassandra的存储引擎中，数据写入磁盘后会形成不可变的SSTable文件，每个SSTable都配有对应的index文件用于记录分区键在data文件中的偏移量。随着集群运行时间变长，单表SSTable数量和体积都会持续增长，如果每次读取都要加载并扫描完整的index文件，磁盘IO和延迟将难以控制。为此Cassandra设计了index summary这一轻量级内存结构，作为完整index文件的稀疏缩影，让读取路径在大多数情况下只需访问内存即可完成分区定位。
index summary的构建原理与内存布局
SSTable在刷盘或compaction完成时，会顺序遍历原index文件中的每一条分区索引项。Cassandra按照固定的抽样间隔（由index_interval参数控制，默认值为128）选取其中一部分条目，将其分区键和对应的index文件偏移量写入summary文件，同时把这些抽样条目以有序数组的形式保留在内存中。由于只保存了约原索引的1/128，summary占用堆外内存极少，却覆盖了所有分区的查找范围。
内存中的summary本质上是一个排序后的分区键列表，配合一个并行数组记录每个键在index文件中的位置。当收到读取请求时，系统先对summary数组做二分查找，找到小于等于目标分区键的最大抽样键，从而得到粗略的偏移区间。随后只需读取原index文件中该区间内的少量条目，就能精确定位data文件里的行数据。这种两阶段查找把原本可能触及大量磁盘块的操作压缩为一次内存二分加一次小范围顺序读。
值得注意的是，summary并非永远与index文件完全同步。在节点启动或SSTable被 compaction 替换后，Cassandra会重新生成summary；如果summary文件丢失，系统也能从index文件重建，只是会带来短暂的启动延迟。合理设置index_interval可以在内存成本和查找步长之间取得平衡，例如读多写少且内存宽裕的节点可调小该值以获得更快的定位。
读取路径中summary的实际作用与代码示例
在Cassandra源码的SSTableReader类中，getPosition方法会优先使用summary来缩小查找范围。下面这段简化示例展示了summary如何参与分区定位：
// 根据分区键在summary中查找近似偏移
public long getApproximatePosition(DecoratedKey key) {
// summary中保存了抽样分区键与index偏移的对应关系
int idx = Collections.binarySearch(summaryKeys, key);
if (idx >= 0) {
// 精确命中抽样键
return summaryOffsets.get(idx);
} else {
// 未命中则取前一个抽样点
int insertPoint = -idx - 1;
if (insertPoint == 0) {
return 0;
}
return summaryOffsets.get(insertPoint - 1);
}
}
上述逻辑说明，summary把全量index查找转换为内存中的二分操作。实际生产中，一个128GB的SSTable其index文件可能达到几百MB，而summary往往只有几MB，却足以把99%以上的读取请求挡在磁盘索引扫描之外。当并发读取上升时，这种内存结构的优势会进一步放大，因为二分查找几乎不带来IO争用。
若summary抽样过疏，比如将index_interval调到2048，则单次查找可能要在index文件中线性扫描上千个条目，反而削弱优势。因此在调参时应结合平均分区大小和单个SSTable包含的分区数来估算，而不是盲目采用默认值。同时，在大规模删除了数据并触发compaction之后，旧的summary随SSTable废弃，新summary重建，这一过程由系统自动完成，不需要人工干预。
运维视角下的summary调优与常见误区
很多人在观测到读取延迟突增时，会首先怀疑缓存命中率，却忽略了summary在compaction后的重建开销。实际上，当节点执行大规模compaction，大量SSTable被合并，旧summary失效，新文件生成时若磁盘繁忙，summary加载可能滞后，此时部分读取会临时退化为直接读index文件，表现为延迟毛刺。通过监控SSTableReader的summary加载指标，可以提前安排低峰期执行compaction。
另一个常见误区是认为增大堆内存就能解决所有索引问题。summary默认使用堆外内存（off-heap），不受JVM堆大小限制，但若将index_interval设得极小，堆外内存仍可能膨胀数倍，甚至引发直接内存溢出。正确的做法是根据数据规模计算所需summary体量，并结合cassandra.yaml中的file_cache_size等参数综合规划。下表列出了不同间隔下的内存与性能特征：
| index_interval | 内存占用倍数 | 平均查找扫描条目 | 适用场景 |
|---|---|---|---|
| 32 | 4x | 16 | 极低延迟交易类 |
| 128 | 1x | 64 | 通用混合负载 |
| 512 | 0.25x | 256 | 写密集日志类 |
从架构角度看，summary是Cassandra在“用少量内存换大量磁盘IO”思想下的典型实现。它与Bloom filter配合，前者缩小分区级范围，后者快速排除不含目标分区的SSTable，两者共同构成了高效的读路径前置过滤层。理解它们的分工，有助于在容量规划和故障排查时做出准确判断，而不是把性能问题简单归咎于硬件或网络。
CassandraSSTableindex_summary修改时间：2026-08-16 00:18:32