1. 连接 Redis

ctx := context.Background()rdb := redis.NewClient(&redis.Options{Addr:     "localhost:6379",Password: "",DB:       0,Protocol: 2,           // 推荐 RESP2// UnstableResp3: true, // 若要体验 RESP3 + Raw*
})

2. 准备示例数据

user1 := map[string]interface{}{"name":  "Paul John","email": "paul.john@example.com","age":   42,"city":  "London",
}
user2 := map[string]interface{}{"name":  "Eden Zamir","email": "eden.zamir@example.com","age":   29,"city":  "Tel Aviv",
}
user3 := map[string]interface{}{"name":  "Paul Zamir","email": "paul.zamir@example.com","age":   35,"city":  "Tel Aviv",
}

3. 为 JSON 数据建索引

_, err := rdb.FTCreate(ctx, "idx:users",&redis.FTCreateOptions{OnJSON: true,                   // 针对 JSONPrefix: []interface{}{"user:"},// 仅索引 user:* 键},// schema&redis.FieldSchema{              // 全文本字段FieldName: "$.name",As:        "name",FieldType: redis.SearchFieldTypeText,},&redis.FieldSchema{              // TAG 用于精确匹配/聚合FieldName: "$.city",As:        "city",FieldType: redis.SearchFieldTypeTag,},&redis.FieldSchema{              // 数值范围查询FieldName: "$.age",As:        "age",FieldType: redis.SearchFieldTypeNumeric,},
).Result()
if err != nil { panic(err) }

写入 JSON 文档

_, _ = rdb.JSONSet(ctx, "user:1", "$", user1)
_, _ = rdb.JSONSet(ctx, "user:2", "$", user2)
_, _ = rdb.JSONSet(ctx, "user:3", "$", user3)

RediSearch 监听 user: 前缀，写入即自动索引。

4. 查询示例

4.1 复合搜索

res, _ := rdb.FTSearch(ctx,"idx:users","Paul @age:[30 40]",
).Result()fmt.Printf("匹配总数：%d\n", res.Total)

4.2 指定返回字段（`RETURN`）

cities, _ := rdb.FTSearchWithArgs(ctx, "idx:users", "Paul",&redis.FTSearchOptions{Return: []redis.FTSearchReturn{{FieldName: "$.city", As: "city"},},},
).Result()for _, d := range cities.Docs {fmt.Println(d.Fields["city"])
}
// London / Tel Aviv

4.3 仅计数不取文档

cnt, _ := rdb.FTSearchWithArgs(ctx, "idx:users", "Paul",&redis.FTSearchOptions{CountOnly: true},
).Result()
fmt.Println(cnt.Total) // 输出 2

4.4 聚合：统计每个城市的用户数

agg, _ := rdb.FTAggregateWithArgs(ctx, "idx:users", "*",&redis.FTAggregateOptions{GroupBy: []redis.FTAggregateGroupBy{{Fields: []interface{}{"@city"},Reduce: []redis.FTAggregateReducer{{Reducer: redis.SearchCount, As: "count"},},},},},
).Result()for _, row := range agg.Rows {fmt.Printf("%s - %v\n", row.Fields["city"], row.Fields["count"])
}
// London - 1
// Tel Aviv - 2

5. 切换到 Hash 模式的差异

建索引

_, err := rdb.FTCreate(ctx, "hash-idx:users",&redis.FTCreateOptions{OnHash: true,Prefix: []interface{}{"huser:"},},&redis.FieldSchema{FieldName: "name", FieldType: redis.SearchFieldTypeText},&redis.FieldSchema{FieldName: "city", FieldType: redis.SearchFieldTypeTag},&redis.FieldSchema{FieldName: "age",  FieldType: redis.SearchFieldTypeNumeric},
).Result()

OnHash:true 且 不需要 As 别名——字段名即 Hash 的 key。

写入数据

rdb.HSet(ctx, "huser:1", user1)
rdb.HSet(ctx, "huser:2", user2)
rdb.HSet(ctx, "huser:3", user3)

查询语法相同，但结果字段直接展开：

docs, _ := rdb.FTSearch(ctx,"hash-idx:users","Paul @age:[30 40]",
).Result()
fmt.Println(docs.Docs[0].Fields["city"]) // 直接获取 city

6. 常见坑位

问题	解决方案
返回 `"dialect version not supported"`	显式升级 RediSearch ≥ 2.4，或在服务器 `FT.CONFIG SET DEFAULT_DIALECT 2`
`Cannot create index while write traffic is on`	在生产写高峰创建索引时加 `FT.CREATE ... ON JSON ... STOPWORDS 0` 或使用 `FT.ALTER` 增量添加字段
RESP3 报 `unsupported`	使用 `Protocol:2`，或启用 `UnstableResp3` 并用 `RawResult()` 解析
查询结果字段在 `$` 键下	这是 JSON 模式的设计：所有字段存入 `Fields["$"]` 字符串里，需要二次解析或用 `RETURN $.field`