HappyBase 是 Python 访问 HBase 的流行客户端，基于 Thrift 协议实现。在对 HBase 表进行读取操作时，扫描（scan）是使用最频繁的接口之一。它允许开发者按行键范围遍历数据，而不必事先知道每一行的精确行键。与 get 方法不同，scan 可以一次性返回多行，并且支持服务端过滤，大幅减少传输到客户端的数据量。
一、HappyBase扫描表的基本用法
HappyBase 通过 Connection 对象连接到 HBase 的 Thrift 服务，然后获取 Table 对象来执行扫描操作。最基础的扫描调用是 table.scan()，它返回一个生成器，可以逐行迭代结果。默认情况下 scan 会从表的第一行开始，一直扫描到最后一行的下一行，相当于全表扫描。为了避免一次加载过多数据，scan 方法提供了多个可选参数，常用的包括 row_start、row_stop、limit、batch_size、columns 和 filter。
下面是一个最简单的扫描示例，连接到本地的 HBase Thrift 服务并打印前 100 行数据：
import happybase
connection = happybase.Connection('localhost', port=9090)
table = connection.table('user_events')
# 扫描前100行，每批取10行
rows = table.scan(limit=100, batch_size=10)
for row_key, row_data in rows:
print(row_key, row_data)
这段代码中，limit 参数负责限制返回的总行数，batch_size 则控制每次从服务端读取的行数。batch_size 设置过小会增加网络往返次数，设置过大又会占用更多客户端内存，需要根据单行数据大小来权衡。如果只关心某些列族或列限定符，可以通过 columns 参数指定，例如 columns=[b'cf1', b'cf1:name']，这样可以减少不必要的数据传输。
需要注意的是，row_start 的行键是包含在结果中的，而 row_stop 的行键是排除在外的，扫描区间为左闭右开。默认情况下，row_start 和 row_stop 都需要传入字节串，即 b'rowkey'。如果不指定 row_stop，扫描会一直持续到表尾。对于大表来说，忘记设置 row_stop 或 limit 会导致客户端内存持续增长，甚至触发 Thrift 超时。
二、使用过滤器精确控制扫描范围
表数据量大时，仅靠行键范围并不能满足业务查询需求。例如，用户只想读取某个列族中状态为 active 的行，或者只想获取最近更新的版本。HappyBase 支持向 scan 方法传递 filter 参数，该参数是一个字符串，语法与 HBase 的过滤器表达式一致。服务端会先执行过滤，再把符合条件的行返回给客户端，能显著降低网络 I/O。
以下示例使用 SingleColumnValueFilter 过滤列 family cf1 中的 status 列，只返回值为 active 的行：
import happybase
connection = happybase.Connection('localhost', port=9090)
table = connection.table('user_events')
filter_str = "SingleColumnValueFilter('cf1', 'status', =, 'binary:active')"
rows = table.scan(
row_start=b'2024-01-01',
row_stop=b'2024-12-31',
columns=[b'cf1:name', b'cf1:status'],
filter=filter_str
)
for key, data in rows:
print(key, data.get(b'cf1:name'), data.get(b'cf1:status'))
代码中的 filter_str 使用单引号包裹过滤器内部参数，比较操作符为 =，值类型 binary 表示字节比较。除了 SingleColumnValueFilter，HBase 还提供了 RowFilter、PrefixFilter、QualifierFilter、FamilyFilter 等过滤器，它们可以组合使用。HappyBase 不会对过滤器字符串做语法校验，错误的过滤器会在服务端执行时报错，因此在生产环境中建议先在 HBase shell 中验证过滤器语法。
如果希望只获取最近 N 个版本的数据，可以结合 TimeRange 参数，或者在 filter 中使用 TimestampsFilter。另外，scan 方法还支持 reverse 参数，将其设置为 True 后可以按行键降序扫描，这在读取最新记录时非常有用，因为 HBase 本身按行键升序存储，反向扫描可以避免全表扫描后再排序。
三、批量扫描与性能优化
HappyBase 的 scan 返回的是生成器，并不会一次性把所有行加载到内存，但底层 Thrift 协议仍然会按照 batch_size 分批获取。如果客户端消费速度跟不上服务端产生速度，生成器会阻塞在等待下一批数据上。对于千万级行记录，即使每条记录只有几十字节，累积起来也可能把内存占满，因此合理设置 batch_size 并配合 limit 或行键范围是必要的。
一种常见的优化思路是使用行键前缀扫描。假设行键设计为 用户ID_时间戳，那么可以利用 PrefixFilter 或者 row_start 和 row_stop 来限定某个用户的数据范围。以下代码演示了利用 row_start 和 row_stop 扫描特定前缀的行，避免全表扫描：
import happybase
connection = happybase.Connection('localhost', port=9090)
table = connection.table('user_events')
prefix = b'10001_'
row_stop = prefix[:-1] + bytes([prefix[-1] + 1]) # 前缀加一作为结束键
rows = table.scan(
row_start=prefix,
row_stop=row_stop,
batch_size=100,
limit=500
)
for key, data in rows:
print(key, data)
上述代码中，row_stop 的计算方式是取前缀的最后一个字节加一，这样扫描范围刚好覆盖所有以 10001_ 开头的行键。如果前缀包含不可打印字符或需要更精确的控制，可以采用 HBase 的 PrefixFilter，写法为 filter="PrefixFilter('10001_')"。需要注意，PrefixFilter 会在服务端逐行检查，性能不如直接使用行键范围来的高，所以优先使用 row_start 和 row_stop。
另一个性能优化点是按需选取列。HBase 是列式存储，扫描时如果不指定 columns，默认返回所有列族的所有列。对于宽表来说，这会造成大量的无用 I/O。通过 columns 参数指定需要的列，比如 [b'cf1:name', b'cf1:age']，服务端只会返回这两列的数据。如果只需要最新的一个版本，还可以在表结构设计时设置 VERSIONS 为 1，减少存储和扫描压力。
四、避开扫描过程中的常见陷阱
使用 HappyBase 扫描表时，最常遇到的问题之一就是 row_start 和 row_stop 的边界理解错误。有些开发者以为 row_stop 会被包含在结果中，但实际上扫描区间是左闭右开，row_stop 对应的行不会返回。若要包含某个行键，可以将 row_stop 设置为该行键后面追加一个零字节，例如 b'rowkey\x00'，或者使用 row_stop=b'rowkey' + b'\x00'。同样，row_start 必须小于 row_stop，否则不会返回任何行。
另一个容易忽略的点是 Thrift 的连接超时。默认情况下，HappyBase 的 Connection 不会自动重连，如果在扫描过程中 Thrift 服务重启或网络抖动，迭代器会抛出 TTransportException。此时需要捕获异常并重新建立连接，从上次扫描的位置继续。可以使用 row_start 记录已处理的最后一行，实现断点续扫。以下是一个简单的异常处理示例：
import happybase
from thriftpy2.transport import TTransportException
connection = happybase.Connection('localhost', port=9090)
table = connection.table('user_events')
last_key = b''
try:
rows = table.scan(row_start=last_key, batch_size=50)
for key, data in rows:
last_key = key
print(key, data)
except TTransportException as e:
print('扫描中断，最后的行键:', last_key)
# 可在此重新连接并从 last_key 继续扫描
最后需要注意，过滤器字符串中的参数使用单引号，如果值本身包含单引号，需要进行转义。HappyBase 直接将该字符串传给服务端，不会做任何转义处理，错误的转义会导致过滤器解析失败。建议在调试时先用 HBase shell 的 scan 命令验证过滤器的正确性，再复制到 Python 代码中。此外，不要在生产环境中使用全表扫描而不设置任何限制，否则会严重拖慢 RegionServer 的响应，影响其他业务请求。