Redis Search 查询超时怎样设置上限

Redis Search 查询超时，最直接的做法是在 FT.SEARCH 后追加 TIMEOUT 毫秒数，例如 TIMEOUT 80。但这个值只是当前查询的有效时间预算，不等于客户端 TCP 超时，也不自动保证命令在 80 毫秒内完成全部结果装载。工程上还要配合 search-timeout 默认值、search-on-timeout 返回策略，以及必要时的前台超时上限。

官方文档：https://redis.io/docs/latest/develop/ai/search-and-query/administration/configuration/

先分清三种“超时上限”

Redis Search 的查询时间预算由三层组成：查询命令自己的 TIMEOUT，模块级的 search-timeout 默认值，以及较新版本提供的 search-_max-foreground-timeout-limit 前台硬上限。命令带了 TIMEOUT 时，使用查询值；没有传入时才继承 search-timeout。因此，把默认值改成 500，并不能阻止某个查询显式要求更长时间。

先读配置，再改默认值

在生产环境先用帮助和读取命令确认当前配置，尤其要确认超时后到底返回部分结果还是报错。不同 Redis Query Engine 版本的配置名称和可用策略可能不同，先读取比直接复制旧博客里的参数更稳妥。

# 查看 Redis Search 当前配置和参数说明
FT.CONFIG GET TIMEOUT
FT.CONFIG GET ON_TIMEOUT
FT.CONFIG HELP TIMEOUT
FT.CONFIG HELP ON_TIMEOUT

# 只在明确要改变全局默认时执行，单位是毫秒
FT.CONFIG SET TIMEOUT 500
FT.CONFIG SET ON_TIMEOUT FAIL

search-timeout 的默认值用于没有单独 TIMEOUT 的查询；它是默认值，不是天然的 ceiling。超时策略常见为 RETURN 和 FAIL：前者返回查询已经累积的结果，后者返回错误。若业务必须知道“结果是否完整”，通常选择 FAIL 更容易在应用层做降级。

给单次 FT.SEARCH 设置独立上限

先把慢查询缩小成可观察的实验：限制返回字段、设置有限的 LIMIT，再加上查询级 TIMEOUT。下面的命令不会改变全局默认值，适合先验证一条高风险检索。

# 只返回标题字段，给本次查询 80 毫秒预算
FT.SEARCH books-idx "@title:(redis search)" \
  RETURN 1 title \
  LIMIT 0 20 \
  TIMEOUT 80

# 用 NOCONTENT 检查匹配规模，避免把文档加载时间混进判断
FT.SEARCH books-idx "@title:(redis search)" \
  NOCONTENT LIMIT 0 0 TIMEOUT 80

这里的 80 不是接口端到端 SLA。查询解析、最终的文档字段加载或聚合 reducer 可能还会继续消耗时间；如果调用方还配置了更短的 socket 或 HTTP deadline，客户端可能先于 Redis 收到超时。接口层应把 Redis 错误、部分结果和客户端取消分别记录。

用结果语义决定 RETURN 还是 FAIL

如果使用 RETURN，响应里的数量和业务语义要谨慎解释：结果可能是截至超时已积累的部分集合，不应直接写入“完整搜索结果”。集群环境还要关注各分片的等待关系；新版本支持的 RETURN_STRICT 才适合讨论严格截止时间，不能把它当成所有旧版本都存在的选项。

用 FT.PROFILE 找到真正的慢点

如果查询频繁触发 80 毫秒预算，先用 FT.PROFILE 看解析、迭代器和结果处理阶段，再决定调整索引或查询写法。单纯提高 TIMEOUT 只能延后症状，还可能让 Redis 主线程和搜索资源承受更长占用。

# LIMITED 减少 profile 输出，先看整体和迭代器耗时
FT.PROFILE books-idx SEARCH LIMITED QUERY "@title:(redis search)" \
  LIMIT 0 20 TIMEOUT 80

排查时重点看前缀或通配符扩展、多个条件的交集规模、排序字段是否可用，以及 LIMIT 是否过大。分页还要使用稳定排序，否则只设置 LIMIT 并不能保证多次请求之间不重复或不漏项。

常见问题

把 FT.CONFIG SET TIMEOUT 设为 0 就是无限安全吗？

不是。它会关闭默认查询超时，但查询仍可能受前台硬上限、客户端 deadline、资源竞争和版本策略影响；生产环境应为高风险查询显式设置 TIMEOUT。

超时返回了几条结果，能当作完整结果吗？

不能。使用 RETURN 时应把它当作已累积结果，并在业务响应中保留 partial 或降级标记。

调大 TIMEOUT 后仍然慢，下一步看什么？

先用 FT.PROFILE 看迭代器、排序、字段加载和查询规模，再缩小返回字段或优化索引；不要只反复提高毫秒数。