Redis HSCAN 怎样分批导出大型哈希中的字段

使用HSCAN导出大型哈希时，从游标0开始，每次把服务器返回的游标原样用于下一次调用，处理本批字段和值后，直到返回游标再次为0才结束。COUNT只是扫描工作量提示，不是固定页大小；空批次不代表结束，完整扫描也可能重复返回字段。

官方地址：https://redis.io/

先明确导出的完整性要求

如果只是把在线缓存里的字段交给离线分析，我会采用增量写文件，并让下游按字段合并重复记录。如果要求某一时刻所有字段和值严格一致，则应选择有明确快照边界的备份或冻结数据方案，不能把HSCAN包装成快照导出。

HSCAN只遍历指定哈希内部的字段，不会遍历全库键，也不提供排序分页。先确保键名和数据库选择正确，避免把空结果误认为导出程序故障。

按返回游标推进而不是按页码

游标是扫描状态，不是第几页，也不是字段数量。不要自行加500，也不要根据游标数值计算完成百分比。每次返回的数据和下一个游标必须一起处理；最后一次游标为0时，返回内容仍可能非空。

MATCH过滤可能让某一批没有符合条件的字段，但仍返回非零游标。修改COUNT可以调整后续调用的工作量；MATCH条件与键应在同一任务中保持稳定。

每批写入磁盘并接受重复字段

下面示例使用redis-py，按JSONL逐批写入字段和值。运行前在自己的环境安装客户端并提供REDIS_URL；示例不包含真实凭据，也不连接任何服务器：

import base64
import json
import os
from pathlib import Path

import redis


def export_hash(client, key, output):
    cursor = 0
    records = 0
    # 独占创建，失败保留部分文件；不能把部分文件当成完成导出。
    with Path(output).open("x", encoding="utf-8") as stream:
        while True:
            cursor, fields = client.hscan(key, cursor=cursor, count=500)
            for field, value in fields.items():
                # 保留二进制字段和值，避免UTF-8解码失败或换行破坏记录。
                row = {
                    "field_b64": base64.b64encode(field).decode("ascii"),
                    "value_b64": base64.b64encode(value).decode("ascii"),
                }
                stream.write(json.dumps(row, separators=(",", ":")) + "\n")
                records += 1
            stream.flush()  # 便于逐批消费；flush不等于断电持久化。
            if cursor == 0:
                break  # 必须先处理本批，再判断扫描完成。
    return records


if __name__ == "__main__":
    # 连接信息由环境提供，不在脚本中保存密码，也不输出连接URL。
    client = redis.Redis.from_url(
        os.environ["REDIS_URL"], decode_responses=False,
        socket_connect_timeout=5, socket_timeout=10,
    )
    try:
        total = export_hash(client, "catalog:items", "catalog-items.jsonl.part")
        print("扫描完成，输出记录数:", total)
    finally:
        client.close()  # 即使网络或文件写入失败也释放客户端资源。

文件扩展名.part明确表示任务产物需要由任务管理方在成功返回后发布为最终文件。异常会直接抛出，部分文件保留用于定位，不会打印完成提示。输出计数是记录数，不是唯一字段数；代码没有用内存set收集所有字段，因此不会为了去重重新占用与哈希规模相当的内存。

下游可把field_b64作为主键写入数据库或磁盘键值存储，让相同字段覆盖或按业务规则合并。即便保留最后一次扫描得到的值，它也只是扫描期间观察到的值，不能据此声称得到某一时间点的最终状态。若业务只要字段名，也应结合服务器和客户端支持情况选择仅字段接口；本文保留字段和值以避免额外版本要求。

按负载调整批次与输出设计

从适中的COUNT起步，结合单次响应字节数、命令耗时和服务延迟逐步调整。字段值很大时，500个字段也可能形成大响应；紧凑编码的小集合又可能一次返回全部内容，所以不能把COUNT当作严格内存上限。

单个游标链的下一次请求依赖上次结果，不宜随意把游标区间切成多个任务。若要并行，应按独立哈希键或业务分片规划，并给下游写入设置背压。把整个扫描包在大Lua脚本或长事务中，也会失去分批释放服务执行机会的目的。

把一致性和恢复责任写进任务契约

扫描期间持续存在的字段与扫描中途新增、删除的字段，保证不同；字段值也可能在两次调用之间改变。若键过期、被删除重建或迁移到另一份数据，原任务的业务边界就可能改变，应明确是重新开始还是终止报错。

保存游标不能天然得到精确一次恢复。先保存游标后写文件可能丢记录，先写文件后保存游标可能重复；任务需要可重放的输出和幂等落盘。故障后从0重扫并按字段合并，往往比把游标解释成永久检查点更容易说明。示例没有实现断点续传，也没有声称文件flush提供持久化提交。

为什么导出条数大于HLEN？

可能存在重复返回，且两次观察时数据正在变化。计数不能单独证明错误或完整性。

COUNT设置很小能保证每次只返回几条吗？

不能。它是工作量提示，响应数量和字节大小仍需由调用方观察并安排容量。

能用这个文件替代Redis备份吗？

只有当字段导出的业务语义满足需求时才适用。它不包含完整实例元数据，也不自动保留过期策略或提供一致恢复点。

官方资料：HSCAN、SCAN迭代保证、redis-py接口。