Redis FT.SYNUPDATE 的 SKIPINITIALSCAN 怎样影响旧文档

我第一次给 RediSearch 加同义词时，最容易误判的是命令返回的 OK。它只能说明同义词组更新成功，不代表所有旧文档已经按这组新词重新建立索引。真正决定旧文档是否受影响的，是有没有写 SKIPINITIALSCAN。

一句话结论：不带 SKIPINITIALSCAN 时，FT.SYNUPDATE 会扫描已有文档，让这次同义词更新覆盖存量数据；带上它后会跳过初始扫描，旧文档不因为这次更新立即受益，只有更新后写入的文档会受影响。Redis 官方地址：https://redis.io/docs/latest/commands/ft.synupdate/

下面用一个很小的搜索索引把这条边界讲清楚。本文只讨论同义词组更新与旧文档的关系，不展开 RediSearch 的完整建模和查询语法。

先把 FT.SYNUPDATE 的影响范围分成两层

FT.SYNUPDATE index synonym_group_id term [term ...] 做两件事：更新同义词组，并决定是否为这次更新触发初始扫描。官方文档明确说明，默认行为会扫描全部文档；SKIPINITIALSCAN 则不扫描、不为已有文档建立这次同义词对应的索引。

因此要把文档分成“命令执行前已经在索引里的旧文档”和“命令执行后才写入的新文档”。默认写法会同时照顾这两类文档；跳过初始扫描时，旧文档保持原来的索引状态，而后续写入的文档可以按更新后的同义词关系进入索引。

先建一个最小搜索索引

为了避免把“命令成功”与“旧文档已经生效”混为一谈，可以先准备一个只包含标题字段的索引，再写入一条旧文档。这里的命令是演示用骨架，重点在文档进入索引的时间点。

# 创建一个只索引 title 字段的搜索索引，方便观察词语是否进入索引
redis-cli FT.CREATE idx_products ON HASH PREFIX 1 product: SCHEMA title TEXT

# 写入同义词更新前已经存在的旧文档
redis-cli HSET product:1 title "Redis search guide"

# 先创建一个包含两个词的同义词组，命令成功只返回 OK
redis-cli FT.SYNUPDATE idx_products product-search redisearch "redis search"

这里的 product:1 就是后面要观察的存量文档。实际项目通常会先批量导入文档，再根据用户搜索词维护同义词组，所以“同义词组是在什么时候更新的”会直接决定旧数据是否要付出一次扫描成本。

不带 SKIPINITIALSCAN：旧文档会被纳入这次更新

默认写法是：

# 不写 SKIPINITIALSCAN，让 Redis Search 扫描已有文档
redis-cli FT.SYNUPDATE idx_products product-search "elastic search" "es search"

# 再写入一条新文档；它天然处在同义词组更新之后
redis-cli HSET product:2 title "Elastic search guide"

这条命令成功后，Redis 会对已有文档执行初始扫描；因此 product:1 和之后写入的 product:2 都在这次同义词维护的覆盖范围内。这里的“覆盖”指索引层面的同义词处理，不是改写 Hash 里的原始 title 文本。

默认行为适合两种情况：同义词是搜索规则的正式上线内容，旧文档必须立刻能用；或者你无法接受新旧文档在一段时间内表现不一致。代价也很明确：文档量大时，初始扫描会带来额外资源消耗和上线时延。

带 SKIPINITIALSCAN：旧文档不会自动补齐

如果把命令改成下面这样，语义就变了：

# 跳过已有文档的初始扫描，只让后续写入使用更新后的同义词组
redis-cli FT.SYNUPDATE idx_products product-search SKIPINITIALSCAN "search engine" "全文搜索"

# 这条文档是在更新之后写入，属于后续文档
redis-cli HSET product:3 title "全文搜索入门"

OK 仍然表示同义词组更新成功，但它不表示 product:1、product:2 这类旧文档已经被重新扫描。它们是否能按新同义词命中，要看后续是否安排了回填、重建索引或其他存量数据处理。

这正是 SKIPINITIALSCAN 的价值：在同义词词表快速迭代、文档量很大或希望把索引压力放到低峰期时，可以先让新写入的数据采用新规则，再单独安排存量兼容。它不是“更快但结果完全相同”的开关，而是明确改变了旧文档的生效范围。

我会怎样选择上线策略

我的判断顺序通常只有三步。第一，确认同义词是“立刻改变线上搜索语义”，还是“先让新数据试运行”。前者省略 SKIPINITIALSCAN，后者才考虑跳过扫描。第二，估算存量文档的规模和扫描窗口，不能因为命令是 O(1) 的控制操作，就推断后续扫描没有成本。第三，给旧文档安排明确的回填或重建路径，并把“旧文档暂时不命中”当成上线期间的已知状态。

一个实用的验收表可以这样写：

常见问题

FT.SYNUPDATE 返回 OK，为什么旧文档仍然搜不到新同义词？如果命令带了 SKIPINITIALSCAN，这是预期行为：它跳过已有文档扫描，旧文档需要单独处理。

SKIPINITIALSCAN 会修改旧文档原文吗？不会。同义词组影响的是搜索索引与查询语义，不会把 Hash 中原来的字段文本改成同义词。

什么时候不应该使用 SKIPINITIALSCAN？当业务要求同义词更新后存量数据立刻统一可检索，而且能够安排扫描资源时，直接使用默认行为更容易保持结果一致。