Redis Query Engine JSON 路径索引的字段设计

给 Redis JSON 文档设计 Query Engine 索引时，最容易犯的错误是把 JSON 结构当成一张可以整体索引的对象。更稳妥的做法是先把查询任务拆开：标题需要全文检索就建成 TEXT，分类或状态需要精确匹配就建成 TAG，价格、库存和时间需要范围过滤就建成 NUMERIC。

官方地址：https://redis.io/docs/latest/develop/ai/search-and-query/indexing/

JSON 索引的字段设计可以记成一句话：JSONPath 找到值，AS 给它稳定名字，字段类型决定查询语义；对象本身不能直接作为索引字段，排序字段还要单独考虑 SORTABLE。

先把 JSON 文档拆成可索引叶子字段

假设商品文档包含名称、分类、价格、库存和嵌套的供应商信息。文章只关心字段如何进入 schema，不把整份对象当成一个字段：

{
  "name": "静音机械键盘",
  "category": "keyboard",
  "price": 299.0,
  "stock": 18,
  "supplier": {
    "region": "华东",
    "active": true
  }
}

Redis 官方文档将 JSONPath 表达式的结果映射为 schema attribute。像 $.supplier 这样的路径返回的是 JSON 对象，不能直接建立索引；应继续下钻到 $.supplier.region 和 $.supplier.active 这样的叶子值。

因此，建索引前先列一张字段表比直接拼命令更可靠：

按查询任务选择 TEXT、TAG 和 NUMERIC

字段类型不是数据类型的简单翻译，而是你希望 Query Engine 如何解释值。TEXT 适合全文检索，TAG 适合类别、状态、编码等精确匹配，NUMERIC 适合数值范围。一个字符串字段如果既要全文检索又要精确过滤，可以用两个 schema 条目分别映射同一个 JSONPath，并用不同别名表达两种用途。

# 为 JSON 文档创建索引；每一项都指向可查询的叶子值
redis-cli FT.CREATE product-idx ON JSON PREFIX 1 product: \
  SCHEMA \
  $.name AS name TEXT \
  $.category AS category TAG \
  $.price AS price NUMERIC SORTABLE \
  $.stock AS stock NUMERIC \
  $.supplier.region AS supplier_region TAG \
  $.supplier.active AS supplier_active TAG

# 用 TAG 做精确筛选，用 NUMERIC 做范围筛选
redis-cli FT.SEARCH product-idx '@category:{keyboard} @price:[100 400]'

# 用 TEXT 做词查询；这里查询的是 AS 后的 attribute 名称
redis-cli FT.SEARCH product-idx '@name:(机械键盘)'

真正的性能基线应记录“查询条件、返回数量、执行延迟和索引内存”，而不是只写“加索引后更快”。同一份样本数据可以分别比较未声明 SORTABLE 与声明后的排序查询，但不要把示例数字当成线上结果。

SORTABLE 是查询排序的设计选择，会带来额外内存开销。只有确实需要按价格、时间或其他字段排序时才加；不需要排序的正文或描述字段不要为了“以后可能用到”全部设为可排序。

用 AS 给 JSONPath 稳定的查询字段

JSONPath 适合描述文档位置，但不一定适合写在每一条查询里。使用 AS 可以把 $.supplier.region 这样的路径映射成 supplier_region，之后查询就围绕稳定的 attribute 名称展开。这个别名也应该按业务语义命名，避免同一个字段在不同索引里出现含义不一致。

# 同一 JSONPath 可以用两个别名表达两种查询语义
redis-cli FT.CREATE product-idx-v2 ON JSON PREFIX 1 product: \
  SCHEMA \
  $.category AS category_exact TAG \
  $.category AS category_text TEXT \
  $.price AS price NUMERIC SORTABLE

# 查询时使用 attribute 别名，而不是重复书写 JSONPath
redis-cli FT.SEARCH product-idx-v2 '@category_exact:{keyboard}' RETURN 3 name price category_exact

字段命名最好保持“值的业务含义 + 查询语义”一致。例如 category_exact 直接提示它是精确过滤字段，name_text 则提示它服务于全文查询。别名不是装饰，它决定了后续查询、返回字段和文档维护者看到的接口名称。

用 FT.INFO 和查询组合确认设计边界

这一步不是重新设计字段，而是把已经确定的 schema 与查询写法对齐。先查看索引定义，再检查查询是否使用正确的 attribute：

# 查看索引定义、字段类型和索引统计信息
redis-cli FT.INFO product-idx

# 只返回业务需要的字段，减少结果载荷；返回数量必须与字段列表对应
redis-cli FT.SEARCH product-idx '@category:{keyboard}' \
  RETURN 3 name price stock

# 只有 schema 中声明为 SORTABLE 的字段才适合走低延迟排序路径
redis-cli FT.SEARCH product-idx '*' SORTBY 2 price ASC RETURN 2 name price

如果结果为空，先区分三类原因：路径没有命中文档字段、字段类型和查询语法不匹配，或者已有 JSON 文档还在异步建立初始索引。修改后的 JSON 文档会触发索引更新，但实际排查仍应先看 FT.INFO 中的定义和失败计数，再缩小到一条最小查询。

数组也要单独看待：字符串数组可以按 TAG 或 TEXT 设计，数字数组可以按 NUMERIC 或特定向量能力设计；多值路径下，排序和返回值有额外限制，不能把它当成单值字段使用。

字段设计清单与常见问题

1. 先写出每个查询需要的 JSONPath，而不是从 JSON 外观反推索引。
2. 对象路径继续下钻到叶子值，不直接索引 JSON object。
3. 全文用 TEXT，精确值用 TAG，范围值用 NUMERIC。
4. 需要排序的字段再声明 SORTABLE，并把内存代价纳入基线记录。
5. 用 AS 固定查询 attribute 名称，避免把长 JSONPath 散落到业务代码。
6. 用 FT.INFO、最小 FT.SEARCH 和返回字段检查设计是否一致。

Q：JSONPath 指向一个对象时能直接建索引吗？
不能。应分别索引对象里的字符串、数字或布尔叶子字段。

Q：分类字段为什么通常用 TAG 而不是 TEXT？
分类通常需要精确匹配，不需要分词或全文相关性；TAG 的查询语义更接近枚举值。

Q：所有字段都加 SORTABLE 可以吗？
不建议。它会增加内存开销，应该只给确实参与排序的字段声明。

总结一下：Redis Query Engine JSON 索引的核心是把文档结构翻译成查询契约。JSONPath 负责定位，AS 负责稳定命名，TEXT、TAG、NUMERIC 负责表达查询意图，SORTABLE 负责明确排序成本。按这个顺序设计，字段表、建索引命令和业务查询会保持在同一条线上。