在HBase的客户端扫描链路中，有一个参数经常被忽略，却直接决定全表扫描、范围查询以及数据导出任务的效率，它就是hbase.client.scanner.caching。这个参数控制客户端每次通过RPC向RegionServer请求多少行数据。默认值通常不大，如果扫描几千万行，客户端会发起大量远程调用，RegionServer也要反复维护Scanner状态，整体吞吐可能低得让人意外。下面从它背后的RPC交互机制入手，拆解如何结合行宽、并发度和内存限制来进行设置。
一、扫描缓存如何影响RPC交互
HBase客户端扫描并不是一次性把所有数据拉到本地，而是通过Scanner实例反复调用next()或next(int nbRows)逐批获取。每次客户端本地缓存耗尽时，都会向RegionServer发送一次RPC请求，RegionServer端会从StoreScanner中读取一批行并序列化返回。这个批量行数就是由hbase.client.scanner.caching或Scan.setCaching(int caching)决定的。
如果缓存值设置得很小，比如默认配置下只有100行，那么扫描一亿行数据理论上至少需要一百万次RPC。每一次RPC不仅有网络传输开销，还有服务端的Scanner上下文查找、序列化、Protobuf编码以及客户端反序列化和内存分配。这些固定成本累加起来非常可观。相反，如果把缓存值提升到1000或2000，RPC次数会按比例下降，扫描吞吐往往能成倍提升。
但同时要注意，较大的缓存值意味着RegionServer需要把更多行暂存在内存中，客户端也要预留更大的接收缓冲区。对宽行或大单元格数据来说，即使行数不多，字节数也可能很大。此时还需要考虑Scan.setMaxResultSize(long maxResultSize)对单次RPC结果大小的限制，避免一次性返回过多数据导致客户端GC压力或网络超时。
二、参数设置方式与默认行为
全局配置可以在hbase-site.xml中添加或修改：
<property> <name>hbase.client.scanner.caching</name> <value>500</value> <description>客户端扫描缓存行数</description> </property>
如果不想影响整个集群的所有客户端，推荐在具体扫描任务中通过代码单独设置。Java API示例如下：
import org.apache.hadoop.hbase.TableName;
import org.apache.hadoop.hbase.client.Connection;
import org.apache.hadoop.hbase.client.Result;
import org.apache.hadoop.hbase.client.ResultScanner;
import org.apache.hadoop.hbase.client.Scan;
import org.apache.hadoop.hbase.client.Table;
public class ScanCachingExample {
public static void scanWithCaching(Connection connection, String tableName) throws Exception {
Table table = connection.getTable(TableName.valueOf(tableName));
Scan scan = new Scan();
// 每次RPC拉取500行数据
scan.setCaching(500);
// 如果行特别宽，可以限制每行返回的列数
// scan.setBatch(100);
ResultScanner scanner = table.getScanner(scan);
try {
for (Result result : scanner) {
// 业务处理，注意不要在处理逻辑中做重量级操作
byte[] row = result.getRow();
}
} finally {
scanner.close();
table.close();
}
}
}
在HBase的默认配置中，hbase.client.scanner.caching通常为100。这个值对单行随机点查影响不大，因为点查走Get接口，不走Scan的缓存机制。但对范围扫描和全表扫描来说，100行一次RPC明显偏小。很多生产集群会在客户端统一上调到500至2000，尤其是离线分析任务。需要留意，Scan.setCaching(int caching)的优先级高于配置文件，代码中未显式设置时才使用全局值。
另外，HBase还提供了Scan.setBatch(int batch)，它的含义和caching不同。batch限制的是每行返回的列数量，主要解决单行数据过宽导致单次响应过大的问题。举例来说，如果一行有10万个列，caching设置200也不代表一次返回200行完整数据，实际返回的数据量可能被batch参数切成更小的列块。理解这两个参数的区别，是避免参数配置混乱的关键。
三、不同扫描场景的调优建议
全表扫描或大规模数据导出是缓存参数最能发挥作用的场景。比如使用MapReduce或Spark通过TableInputFormat读取HBase表时，每个Task会创建自己的Scanner，如果每个Scanner缓存过小，Task启动后大部分时间都消耗在RPC等待上。建议把caching调到1000至5000，同时设置合理的hbase.client.scanner.max.result.size，通常不要超过256MB。这样可以在网络往返次数和单次响应体积之间取得平衡。
在线业务中的小范围扫描则不宜盲目调大。假设一个页面需要按时间范围查询最近50条记录，caching设置成2000不会带来明显收益，反而会一次性拉取大量后续行，而这些行可能根本不会被用户翻页看到。此时保持默认100或者设置200至500已经足够。真正需要关注的是过滤条件下推和行键设计，避免扫描范围过大。
宽行扫描是另一个需要特别处理的场景。如果单行包含数千个列且每个单元格体积不小，建议把setBatch和setCaching组合使用。可以设置caching为1000，batch为200，这样一次RPC最多返回约200列，而不是整行的全部列。客户端循环遍历时会持续从RegionServer获取同一行的剩余列，直到该行读完或达到停止条件。这样既能减少RPC次数，又能避免单次响应过大导致超时。
四、常见误区与参数之间的关系
第一个常见误区是认为缓存行数越大扫描越快。实际上当caching超过某个阈值后，单次RPC响应可能接近或超过RegionServer的hbase.ipc.server.response.size.max，服务端会直接拒绝或截断响应。即使服务端允许返回，客户端内存也会被大量待处理Result对象占用。对于几十字节的小行，caching设为5000也许没问题；对于几百KB的大行，可能1000行已经让堆内存告急。
第二个误区是忽视Scanner租约和超时。RegionServer为每个Scanner维护一个租约，只有客户端持续发起next请求才会续租。如果客户端在两次next之间处理业务逻辑耗时较长，比如把每一行同步写入外部系统，那么caching过大时服务端在等待期间可能以为Scanner已经失效。此时建议要么在处理逻辑前把数据批量取出，要么适当降低缓存值并增加扫描超时时间。
第三个误区是把caching当成BlockCache的替代品。BlockCache用于缓存StoreFile中读出的数据块，减少磁盘IO；Scanner缓存则用于减少客户端与服务端之间的RPC次数。两者作用层级不同，无法相互替代。即使数据完全命中BlockCache，如果caching过小，RPC开销仍然很高。反之，caching再大也不能减少底层磁盘读取。排查扫描性能问题时，应同时观察RPC数量、网络流量和磁盘IO指标。
总结来说，hbase.client.scanner.caching是一个典型的用空间换时间的参数。调优时不要只盯着行数，而要结合单行大小、扫描范围、并发度以及客户端和服务端的内存状况。合理的缓存值通常需要通过压测确定，可以先从默认100开始，按500、1000、2000逐步提升，观察吞吐曲线和GC暂停时间，找到收益拐点后再固化到配置或代码中。
HBase扫描缓存hbase.client.scanner.cachingScanner缓存修改时间：2026-09-17 19:43:59