Redis FT.DICTDUMP 怎样读取自定义词典的全部词条

我在整理 RediSearch 自定义词典时，最容易混淆的是：词典不是普通 Redis Set，不能用 SMEMBERS 去读。要一次拿到指定词典的全部词条，直接执行 FT.DICTDUMP 。它返回一个字符串数组，数组中的每一项就是该词典里的一个词条。

官方文档：https://redis.io/docs/latest/commands/ft.dictdump/

先把字典和读取命令对上

FT.DICTDUMP 只认识字典名，所以第一步不是执行命令，而是确认写入词条时使用的名字。下面用 product_terms 做一个最小例子，词条故意包含普通单词和带空格的短语，便于观察返回结果。

# 往同一个 RediSearch 自定义词典写入两个词条
redis-cli FT.DICTADD product_terms "vector database" "hybrid search"

# 一次性读取 product_terms 中的全部词条
redis-cli --raw FT.DICTDUMP product_terms

这里的 --raw 只是让 redis-cli 以更适合复制的方式展示字符串；它不会改变 Redis 服务端的返回内容。返回结果通常会按多行显示，例如：

vector database
hybrid search

不要把显示顺序当成业务排序规则。若导出文件需要稳定顺序，应在客户端收到完整数组后自行排序；如果词条本身可能重复，也应在应用层决定是否去重。

FT.DICTDUMP 返回什么，和搜索结果有什么区别

命令的语义是“倾倒指定词典中的所有 term”。它不会执行 FT.SEARCH，不会根据文档字段筛选，也不会返回词条的权重、命中次数或来源信息。参数 dict 只表示要读取哪一个自定义词典。

因此，想检查“自定义词典到底写进去了哪些词”，用 FT.DICTDUMP；想检查“哪些文档匹配查询”，才使用搜索命令。两者得到的结果对象完全不同。

大字典读取时先算清成本

官方文档给出的时间复杂度是 O(N)，N 是词典大小。这个命令没有 LIMIT、游标或分页参数，调用一次就会把全部词条组成一份响应交给客户端。小字典可以直接在管理脚本中使用；几十万条以上的词典，则要把响应大小、客户端内存和 Redis 主线程上的处理时间一起纳入窗口。

我的处理习惯是把它放在低峰期的维护任务里，并在客户端完成排序、去重或写文件。不要把它放进每次用户搜索请求的热路径，也不要把它误当作可以逐页拉取的扫描接口。若确实需要增量同步，应在写入词典的业务侧维护变更记录，而不是反复全量 dump。

空结果、未知命令和权限怎么排查

先区分三种情况：字典存在但没有词条时，结果为空；字典名写错时，得到的是针对不存在对象的错误；服务端没有加载对应搜索能力，通常会表现为未知命令。另一个容易漏掉的点是 ACL：官方把该命令归在 @search 类别，账号需要具备相应命令权限。

# 先确认当前连接可执行基础命令
redis-cli PING

# 用实际字典名读取，不要把 Redis key 名当成字典名
redis-cli FT.DICTDUMP product_terms

# 词条规模较大时只在维护窗口执行，并把输出重定向到文件
redis-cli --raw FT.DICTDUMP product_terms > product_terms.txt

如果基础 PING 正常而 FT.DICTDUMP 报未知命令，优先检查 Redis 部署是否包含 RediSearch 能力，而不是修改字典名。若是权限错误，则检查调用账号的 ACL；不要为了排查直接放开生产账号的全部权限。

相关问题

FT.DICTDUMP 能只读取前 100 个词条吗？

命令本身没有分页参数。需要前缀、数量或排序时，应在客户端接收完整结果后处理，或者在业务侧维护适合查询的独立数据结构。

FT.DICTDUMP 返回的是文档还是词条？

返回的是指定自定义词典中的词条字符串，不包含文档 ID、字段内容或搜索命中分数。

为什么用 SMEMBERS 读不到这个词典？

RediSearch 自定义词典不是 Redis 原生 Set key。它由搜索模块管理，所以应使用 FT.DICTDUMP，而不是 Set 数据结构命令。

记住一条边界即可：小规模管理检查直接用 FT.DICTDUMP dict，大规模同步要按 O(N) 设计独立流程；它解决的是“读取全部词条”，不是“分页搜索词典”。