RediSearch `FT.CREATE` 完全参数指南 & HASH/JSON 双写实战

1、索引与 Schema 速概

• 索引 (index) —— 倒排、前缀、向量、Geo … 元数据集合
• Schema —— 索引蓝图：定义字段、类型、权重、排序及存储策略
• FT.CREATE —— 创建索引命令，分「索引级参数」和「字段级参数」两层

2 、FT.CREATE 语法模板

FT.CREATE <index>
    ON HASH|JSON
    PREFIX <n> <pfx1> [pfx2 …]
    [FILTER '<expr>']
    [其他索引级选项 …]
SCHEMA
    <field> [AS <alias>] <type> [字段级选项 …]
    ...

官方命令文档详见 Redis Docs ([redis.io][1])

3、索引级参数总览

4、字段类型

5、字段级选项

6、版本演进关键点

7、典型 Schema 范例

7.1 带权重、排序与标签

FT.CREATE blog-idx ON HASH PREFIX 1 blog:post:
SCHEMA
  title        TEXT    WEIGHT 5.0
  content      TEXT
  author       TAG
  created_date NUMERIC SORTABLE
  views        NUMERIC

7.2 自定义分隔符 TAG

FT.CREATE books-idx ON HASH PREFIX 1 book:details
SCHEMA
  title       TEXT
  categories  TAG SEPARATOR ";"

7.3 一字段两种索引

FT.CREATE multi-idx ON HASH PREFIX 1 inventory:
SCHEMA
  sku AS sku_text TEXT
  sku AS sku_tag  TAG SORTABLE

7.4 JSON + JSONPath

FT.CREATE prodjs-idx ON JSON
SCHEMA
  $.title       AS title       TEXT
  $.categories  AS categories  TAG
  $.emb_vector  AS vector      VECTOR FLAT 6 TYPE FLOAT32 DIM 384 DISTANCE_METRIC COSINE

8、Schema 设计最佳实践

1. 按需建索引：无查询需求字段可 NOINDEX / 不纳入 Schema
2. 权重分级：标题、关键词拉高 WEIGHT，正文保持默认 1
3. SORTABLE 谨慎：仅业务排序字段添加，否则内存倍增
4. TAG 代替 TEXT 精确过滤：城市/状态/ID 等离散值
5. FILTER 精准控制：索引前裁剪垃圾数据，减少写放大
6. 统一前缀：PREFIX 限定业务 Key，避免误索引其他模块

9、Hash + JSON 双写部署方案

场景：电商商品——Hash 做高速计数/库存；JSON 做复杂检索/推荐。

9.1 索引策略

9.2 代码示例（Go-redis）

pipe := rdb.TxPipeline()
// Hash: 秒级计数
pipe.HSet(ctx, "prod:1001", "price", 199, "stock", 8)
// JSON: 搜索主体
pipe.Do(ctx, "JSON.SET", "prodjs:1001", "$",
        `{"title":"Alpha Phone","desc":"6.7\" AMOLED",`+
        `"attrs":{"ram":8,"rom":256},"vector":`+string(vecBlob)+`}`)

_, err := pipe.Exec(ctx)

搜索 Top-10 最近邻 + 价格过滤：

FT.SEARCH idx_json \
  "@price:[100 300]=>[KNN 10 @vector $qvec]" \
  PARAMS 2 qvec $queryVector DIALECT 3

9.3 一致性 & 性能要点

1. 事务 or 幂等重试：TxPipeline + 重试
2. 内存评估：Hash + JSON 两份数据；NOFIELDS/NOOFFSETS 减负
3. 可观测性：FT.INFO 监控 sortable_values_size_mb 等指标 ([redis.io][3])
4. 索引热切换：新建索引 → FT.ALIASADD new → FT.ALIASUPDATE prod_read 零停机
5. Active-Active：JSON 已实现 CRDT；Hash 需应用幂等逻辑防冲突

10 | 常见坑与调优

11、总结

• Schema 决定索引成败：理解每个字段类型与参数含义至关重要
• 双写不是洪水猛兽：得当的事务、事件流 + RediSearch 实时索引即可平滑运行
• 主动监控 & 热切换：用 FT.INFO、FT.ALIAS* 工具化运维，才能保证线上稳定