mcpField
R
redis-query-engine

redis-query-engine

github.com/redis数据与数据库171435 次安装7 周前更新
代码仓库

关于 redis-query-engine

此技能为 Redis Query Engine 的 Hash 和 JSON 文档索引与查询提供指导，面向设计索引、编写查询和管理索引生命周期的开发者。内容涵盖字段类型选择、查询优化以及使用别名更新索引以减少停机。

主要功能

  1. 01指导 FT.CREATE 与 FT.ALTER
  2. 02涵盖 FT.SEARCH 和 FT.AGGREGATE
  3. 03解释字段类型与查询用途
  4. 04提供索引别名更新流程
  5. 05说明查询优化与性能注意事项

适用场景

  1. 01为 Hash 或 JSON 文档设计索引
  2. 02优化搜索和聚合查询
  3. 03规划生产环境索引模式更新
  4. 04控制索引范围与查询结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/redis/agent-skills --skill redis-query-engine

安装后在 Claude Code 中输入/redis-query-engine确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.cursor-plugin/
plugin.json
references/
dialect.md
field-types.md
index-creation.md
index-management.md
query-optimization.md
skip-initial-scan.md

详细介绍

Redis Query Engine

关于如何使用 Redis Query Engine（RQE）为哈希或 JSON 文档建立索引并进行搜索的指南。涵盖使用 FT.CREATE 设计架构、选择字段类型、查询语法、索引生命周期管理，以及最常见的性能陷阱。

适用场景

  • 创建、修改或审核 RQE 索引（FT.CREATE、FT.ALTER）。
  • 编写或优化 FT.SEARCH / FT.AGGREGATE 查询。
  • 为字段选择 TEXT、TAG、NUMERIC、GEO、GEOSHAPE 或 VECTOR。
  • 在不中断服务的情况下推出新的索引架构。
  • 创建仅涵盖新写入键的索引。

1. 使用 DIALECT 2（现代默认值）

DIALECT 2 是基准版本。其他方言（1、3、4）自 Redis 8 起已弃用。大多数现代客户端库已默认使用它，但为确保原始命令的可移植性，请明确指定。

FT.SEARCH idx:products "@name:laptop" DIALECT 2

向量搜索查询必须使用 DIALECT 2。它也能以可预测的方式处理特殊字符和 NULL。

参见 references/dialect.md。

2. 选择正确的字段类型

字段类型决定了可执行的查询类型以及查询速度。选择能满足访问模式的最精简类型。

字段类型适用场景说明
TEXT需要全文搜索会进行分词和词干提取；不适用于精确匹配
TAG精确匹配 / 筛选添加 SORTABLE UNF 可实现最快的标签查询
NUMERIC范围查询、排序价格、计数、时间戳
GEO经纬度点查询单个点（商店、用户）
GEOSHAPE多边形 / 区域查询配送区域、地区
VECTOR相似度搜索HNSW 或 FLAT；参见 redis-vector-search

一个常见错误是因为类别或状态字段“是字符串”，就将其设为 TEXT。这类字段使用 TAG 的速度快 10 倍。

参见 references/field-types.md。

3. 只索引要查询的内容，并始终设置前缀

不带 PREFIX 的 FT.CREATE 会索引数据库中所有匹配的键；如果架构范围很广，索引大小和写入延迟都可能大幅增加。

FT.CREATE idx:products ON HASH PREFIX 1 product:
    SCHEMA
        name TEXT WEIGHT 2.0
        category TAG SORTABLE
        price NUMERIC SORTABLE
        location GEO

经验法则：

  • 从最精简的架构开始。随着出现新的查询模式，再添加字段。
  • 始终设置 PREFIX（或通过 FILTER 表达式筛选）。
  • 添加字段后，使用 FT.INFO idx:<name> 监控索引大小。
  • 仅对实际用于排序的字段使用 SORTABLE；它会占用内存。

参见 references/index-creation.md。

4. 实现零停机索引更新——使用别名

在生产环境中更改架构时，应让应用查询指向一个别名，并切换该别名所指向的索引。

FT.CREATE idx:products_v2 ON HASH PREFIX 1 product: SCHEMA ...
FT.ALIASUPDATE products idx:products_v2

# App queries are stable:
FT.SEARCH products "@category:{electronics}"

实用管理命令：FT.INFO、FT.DROPINDEX、FT._LIST、FT.ALIASADD/UPDATE/DEL。

参见 references/index-management.md。

5. SKIPINITIALSCAN——仅当历史数据无关紧要时使用

默认情况下，FT.CREATE 会遍历所有与前缀匹配的现有键并为其建立索引。仅在以下情况使用 SKIPINITIALSCAN：

  • 正在为一项新功能创建索引，且不应查询现有数据。
  • 现有数据过于庞大，无法同步扫描。
  • 为事件流建立索引，且只关心未来的事件。

对于大多数架构迁移，默认行为（扫描所有内容）才是你需要的。

参见 references/skip-initial-scan.md。

6. 编写具体查询，而不是使用 *

在分页或聚合之前，先通过筛选条件缩小结果集。

# Good — specific filter, limited fields returned
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
    LIMIT 0 20
    RETURN 3 name price category

# Bad — full scan plus unbounded LIMIT
FT.SEARCH idx:products "*" LIMIT 0 10000

其他优化手段：

  • SORTBY 要求排序字段设置 SORTABLE。否则排序会很慢。
  • 尽早使用 LIMIT；如果不这样做，引擎仍会处理超过限制的所有内容。
  • 使用 RETURN 指定字段——如果只需要几个字段，就不要获取整个文档。
  • 查询速度较慢时，使用 FT.PROFILE idx:<name> SEARCH QUERY "<query>" 进行性能分析。

参见 references/query-optimization.md。

References

评论

支持 Markdown