RediSearch FT.CREATE 的 FILTER 怎么只索引满足条件的文档

RediSearch 的 FT.CREATE 中，FILTER 决定哪些文档有资格进入这个索引：表达式在索引创建和文档新增、变更时判断，满足条件的文档才会被索引。它不是 FT.SEARCH 的查询条件，也不替代 PREFIX 对 key 前缀的筛选。

官方地址：https://redis.io/docs/latest/commands/ft.create/

先把 FILTER、PREFIX 和查询过滤分开

一个索引通常同时面对三种范围。PREFIX 面向 Redis key，例如只考虑 product: 开头的 Hash；FILTER 面向文档表达式，例如只收录已发布且库存大于零的商品；FT.SEARCH 里的查询过滤则发生在读请求阶段。三者写在不同位置，混用后最容易出现“查询条件明明写了，索引里却根本没有文档”的误判。

用字段表达式限制哪些文档进入索引

下面的例子只给 status 为 published 且 stock 大于零的商品建立可搜索字段。FILTER 后的整体字符串是一个表达式，字段用 @字段名 引用；字段是否可被索引，仍由后面的 SCHEMA 决定。

# 只让已发布且有库存的商品进入索引，SCHEMA 决定可搜索字段
redis-cli FT.CREATE product-idx ON HASH \
  PREFIX 1 product: \
  FILTER '@status == "published" && @stock > 0' \
  SCHEMA title TEXT SORTABLE \
         category TAG \
         stock NUMERIC SORTABLE

这里的条件只影响“是否进入 product-idx”。它不会删除不符合条件的 Hash，也不会改变 status 或 stock 的值。文档后来被更新为符合条件时，索引器才有机会把它纳入；如果更新后不再符合条件，它也不应继续作为这个索引的有效文档。

需要按 key 判断时使用 @__key

官方文档说明，FILTER 可以用 @__key 访问刚新增或变更的文档 key。因此，字段条件和 key 条件可以组合，但它们解决的是不同问题：字段条件判断文档内容，@__key 判断 Redis key 本身。

# 只处理 product: 前缀下、状态正常且属于公开租户的文档
redis-cli FT.CREATE public-product-idx ON HASH \
  PREFIX 1 product: \
  FILTER 'startswith(@__key, "product:") && @visibility == "public"' \
  SCHEMA title TEXT category TAG tenant_id TAG

如果已经用 PREFIX 1 product: 限定了 key，再重复写相同的 key 前缀通常没有额外收益；示例保留它是为了说明 @__key 的写法。实际规则应优先保持单一来源：稳定的命名空间交给 PREFIX，内容或动态属性交给 FILTER。

创建索引时别忽略存量扫描和查询阶段边界

FT.CREATE 默认会根据定义处理已有 key；如果指定 SKIPINITIALSCAN，则会跳过初始扫描。这个选项不会改变 FILTER 的含义，只会改变创建索引时是否处理当前已经存在的文档。需要覆盖存量数据时，不要把“索引创建成功”误认为“历史文档已经全部进入索引”。

同时，FILTER 不等于查询语句中的过滤器。可以把职责记成下面这张表：

常见问题

FILTER 能不能代替 PREFIX？

不能简单等价。两者都可能缩小范围，但 PREFIX 专门描述 key 前缀，FILTER 是表达式语言，适合字段和值的组合条件。

FILTER 写错会不会删除原始文档？

不会。它控制的是索引收录范围，不是 Redis 数据删除动作；但错误条件会让搜索结果缺少文档。

为什么文档已经满足条件却搜不到？

先确认它属于 PREFIX 范围，再确认创建时是否跳过了初始扫描，最后检查字段名、字段类型和表达式是否一致。