Redis 8.10 HIMPORT 导入哈希字段的批量组织

Redis 8.10 新增的 HIMPORT，适合“很多 Hash 拥有同一组字段”的批量导入任务。它不是把任意 CSV 自动变成 Hash，而是先在一条物理连接上用 PREPARE 注册有序字段集，再反复用 SET 只发送 key 和对应值。字段名稳定、记录量大时，这种组织方式能减少重复字段名的传输与命令处理，并为紧凑 Hash 模板提供明确提示。

官方命令地址：https://redis.io/docs/latest/commands/himport/

为什么批量导入的瓶颈常在字段重复

传统 HSET 很灵活，每条记录都能携带不同字段。但当十万条用户画像都包含 name、email、country、last_login 时，每条命令仍要重复发送这些字段名。数据越同构，重复成本越明显。

HIMPORT 把字段名从“每条记录携带”改成“连接内准备一次”。例如将四个字段注册为 user_profile_v1，之后导入记录时只按既定顺序传四个值。这里真正需要维护的是一份有版本的字段契约，而不是一条更短的命令。

先把业务字段冻结成有序 fieldset

字段顺序就是协议。若字段集按 name, email, country, last_login 准备，那么每次 SET 的第一个值都会写入 name，第二个值写入 email。值数量不一致会报错，顺序写错却可能形成语义错误，因此导入程序不能临时按 Map 遍历结果拼接值。

生产环境建议在名称中加入模式版本，例如 user_profile_v1。新增字段时建立 user_profile_v2，让旧批次按旧契约结束，再切换新批次，避免导入过程中字段位置悄悄改变。

# 所有行交给同一个 redis-cli 进程，fieldset 才能在后续命令中继续可见
printf '%s\n' \
  'HIMPORT PREPARE user_profile_v1 name email country last_login' \
  'HIMPORT SET user:1001 user_profile_v1 Alice alice@example.com CN 2026-10-10T09:00:00Z' \
  'HIMPORT SET user:1002 user_profile_v1 Bob bob@example.com SG 2026-10-10T09:05:00Z' \
  'HIMPORT DISCARD user_profile_v1' |
redis-cli --quoted-input

HIMPORT SET 的复杂度是 O(N)，N 为字段数。它写入的是普通 Redis Hash，后续仍可用 HGET、HMGET、HGETALL 等常规命令读取。DISCARD 只清理当前连接上的 fieldset 定义，不会删除已经写入的数据。

连接池是最容易踩错的边界

fieldset 不是数据库级对象，也不会自动同步给其他客户端。连接 A 执行 PREPARE 后，连接 B 直接执行同名 SET 会得到 fieldset 不存在的错误。连接池如果把两条命令借给不同连接，即使日志里的命令顺序正确，导入仍会失败。

可靠做法有两种：一是为整个小批次租用并固定一条连接，在这条连接上完成 PREPARE、多次 SET 和 DISCARD；二是让客户端为每条物理连接维护“已准备字段集”状态，在首次使用或重连后自动重放 PREPARE。不要只用进程级布尔值记录“已经准备”，因为进程内可能同时存在多条连接。

规模化导入要先分组，再切小批次

原始数据进入导入器后，先按字段集合分组。字段完全一致的记录使用同一个 fieldset；缺少大量字段的稀疏记录、字段频繁变化的事件属性，则继续使用 HSET 更清晰。不要为了统一接口给每条记录补一长串无意义空值。

每个字段组再切成可重试的小批次。批次开始时在固定连接上 PREPARE，逐条或流水线发送 SET，完成后抽样读取并记录批次游标。若连接中断，重新取得连接后再次 PREPARE，从已确认游标之后继续。由于 SET 会覆盖目标 Hash，重放同一完整记录通常容易做到幂等；但业务侧仍要防止旧快照覆盖新数据。

HIMPORT SET 本身没有过期时间参数。若导入的 key 需要 TTL，应在同一批次中另外安排 EXPIRE，并把“Hash 已写入但 TTL 尚未设置”纳入失败恢复设计。

上线前要验收什么

第一层是数据验收：随机抽取 key，用 HMGET 按字段契约检查值的位置，再确认旧字段是否按预期被覆盖。第二层是连接验收：主动断开连接，确认客户端能在新连接上重放 PREPARE 后继续写入，而不是持续报 fieldset 不存在。

第三层是模板指标。Redis 8.10 可从 INFO STATS 观察 hash_templates 与 hash_template_keys，从 INFO MEMORY 观察 used_memory_hash_templates，并用 MEMORY STATS 查看 hash.templates。MEMORY USAGE key 会包含 key 自身成本以及其模板份额。指标没有增长时，先检查字段集是否稳定、记录是否确实同构，而不是盲目扩大批次。

常见问题

HIMPORT 能代替所有 HSET 吗？

不能。它面向字段稳定、重复写入量大的同构 Hash。字段动态、单条更新或稀疏数据继续使用 HSET 更直接。

执行 DISCARD 后，已经导入的 Hash 会消失吗？

不会。DISCARD 只移除当前连接中的指定 fieldset；已写入的 key 仍是普通 Hash。

Redis 重连后为什么突然找不到 fieldset？

因为 fieldset 的生命周期绑定物理连接。新连接必须重新执行 HIMPORT PREPARE，连接池也要按每条连接分别维护准备状态。

什么时候应该新建 fieldset 版本？

字段增加、删除或顺序变化时都应使用新版本名称。这样旧批次和新批次可以并存，回滚时也不会混淆值的位置。