redis-query-engine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Redis Query Engine

Redis 查询引擎

Guidance for using the Redis Query Engine (RQE) to index and search Hash or JSON documents. Covers schema design with

FT.CREATE

, field-type choices, query syntax, index lifecycle management, and the most common performance pitfalls.

本指南介绍如何使用Redis 查询引擎（RQE）对Hash或JSON文档进行索引和搜索，涵盖FT.CREATE的schema设计、字段类型选择、查询语法、索引生命周期管理，以及最常见的性能陷阱。

When to apply

适用场景

Creating, modifying, or reviewing an RQE index (
```
FT.CREATE
```
,
```
FT.ALTER
```
).
Writing or optimizing
```
FT.SEARCH
```
/
```
FT.AGGREGATE
```
queries.
Deciding between
```
TEXT
```
,
```
TAG
```
,
```
NUMERIC
```
,
```
GEO
```
,
```
GEOSHAPE
```
, or
```
VECTOR
```
for a field.
Rolling out a new index schema without downtime.
Spinning up an index that should only cover newly written keys.

创建、修改或审核RQE索引（
```
FT.CREATE
```
、
```
FT.ALTER
```
）。
编写或优化
```
FT.SEARCH
```
/
```
FT.AGGREGATE
```
查询。
为字段选择
```
TEXT
```
、
```
TAG
```
、
```
NUMERIC
```
、
```
GEO
```
、
```
GEOSHAPE
```
或
```
VECTOR
```
类型。
零停机推出新的索引schema。
创建仅覆盖新写入键的索引。

1. Use DIALECT 2 (the modern default)

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

DIALECT 2

is the baseline. Other dialects (1, 3, 4) are deprecated as of Redis 8. Most modern client libraries already default to it — but specify it explicitly in raw commands for portability.

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

DIALECT 2

is required for vector search queries. It also handles special characters and NULLs predictably.

See references/dialect.md.

DIALECT 2

是基准版本。从Redis 8开始，其他方言（1、3、4）已被弃用。大多数现代客户端库已默认使用它，但为了可移植性，在原始命令中需显式指定。

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

DIALECT 2

是向量搜索查询的必需版本，它还能可预测地处理特殊字符和NULL值。

参见references/dialect.md。

2. Pick the right field type

2. 选择正确的字段类型

The field type decides both what you can query and how fast that query is. Use the narrowest type that supports your access pattern.

Field type	Use when	Notes
`TEXT`	Full-text search needed	Tokenized + stemmed; not for exact match
`TAG`	Exact match / filtering	Add `SORTABLE UNF` for fastest tag queries
`NUMERIC`	Range queries, sorting	Prices, counts, timestamps
`GEO`	Lat/long point queries	Single points (stores, users)
`GEOSHAPE`	Polygon / area queries	Delivery zones, regions
`VECTOR`	Similarity search	HNSW or FLAT; see redis-vector-search

The classic mistake is using

TEXT

for a category or status field because "it's a string."

TAG

is 10× faster for those.

See references/field-types.md.

字段类型决定了可执行的查询类型以及查询速度。选择能支持你的访问模式的最窄类型。

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

常见错误是因为“它是字符串”就对类别或状态字段使用

TEXT

，实际上

TAG

在这些场景下的速度是

TEXT

的10倍。

参见references/field-types.md。

3. Index only what you query — and always set a prefix

3. 仅索引需要查询的内容——始终设置前缀

FT.CREATE

without a

PREFIX

indexes every matching key in the database; with a wide schema it can blow up index size and write latency.

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

Rules of thumb:

Start with the minimum schema. Add fields as new query patterns emerge.
Always set
```
PREFIX
```
(or filter via
```
FILTER
```
expression).
Use
```
FT.INFO idx:<name>
```
to monitor index size after adding fields.
Use
```
SORTABLE
```
only on fields you actually sort by; it has a memory cost.

See references/index-creation.md.

不带

PREFIX

的

FT.CREATE

会索引数据库中所有匹配的键；如果schema范围较广，会导致索引大小膨胀和写入延迟增加。

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

经验法则：

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

参见references/index-creation.md。

4. Zero-downtime index updates — use aliases

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

For schema changes in production, keep application queries pointed at an alias and swap the underlying index.

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

在生产环境中进行schema变更时，保持应用查询指向别名，然后交换底层索引。

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}"


Useful management commands: `FT.INFO`, `FT.DROPINDEX`, `FT._LIST`, `FT.ALIASADD/UPDATE/DEL`.

See [references/index-management.md](references/index-management.md).

FT.SEARCH products "@category:{electronics}"


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

参见[references/index-management.md](references/index-management.md)。

5. SKIPINITIALSCAN — only when historical data is irrelevant

5. SKIPINITIALSCAN——仅在历史数据无关时使用

By default

FT.CREATE

walks all existing keys that match the prefix and indexes them. Use

SKIPINITIALSCAN

only when:

You're standing up the index for a new feature and existing data shouldn't be queryable.
Existing data is too large to scan synchronously.
You're indexing event streams where only future events matter.

For most schema migrations, the default (scan everything) is what you want.

See references/skip-initial-scan.md.

默认情况下，

FT.CREATE

会遍历所有匹配前缀的现有键并为其建立索引。仅在以下场景使用

SKIPINITIALSCAN

：

为新功能创建索引，且现有数据不应被查询到。
现有数据量过大，无法同步扫描。
为事件流建立索引，且仅未来事件重要。

对于大多数schema迁移，默认行为（扫描所有数据）是符合需求的。

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

6. Write specific queries, not

6. 编写特定查询，而非

Narrow the result set with filters before paging or aggregating.

undefined

在分页或聚合前使用过滤器缩小结果集。

undefined

Good — specific filter, limited fields returned

Bad — full scan plus unbounded LIMIT

不推荐——全扫描加上无限制的LIMIT

FT.SEARCH idx:products "*" LIMIT 0 10000


Other levers:

- `SORTBY` requires `SORTABLE` on the sort field. Without it, sort is slow.
- `LIMIT` early; the engine still processes everything above the limit if you don't.
- `RETURN` specific fields — don't fetch the whole document if you only need a few.
- Profile with `FT.PROFILE idx:<name> SEARCH QUERY "<query>"` when a query is slow.

See [references/query-optimization.md](references/query-optimization.md).

FT.SEARCH idx:products "*" LIMIT 0 10000


其他优化手段：

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

参见[references/query-optimization.md](references/query-optimization.md)。

redis-query-engine

Original

Translation

Redis Query Engine

Redis 查询引擎

When to apply

适用场景

1. Use DIALECT 2 (the modern default)

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

2. Pick the right field type

2. 选择正确的字段类型

3. Index only what you query — and always set a prefix

3. 仅索引需要查询的内容——始终设置前缀

4. Zero-downtime index updates — use aliases

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

App queries are stable:

应用查询保持稳定：

5. SKIPINITIALSCAN — only when historical data is irrelevant

5. SKIPINITIALSCAN——仅在历史数据无关时使用

6. Write specific queries, not
`*`

6. 编写特定查询，而非
`*`

Good — specific filter, limited fields returned

推荐——特定过滤器，返回有限字段

Bad — full scan plus unbounded LIMIT

不推荐——全扫描加上无限制的LIMIT

References

参考资料

redis-query-engine

Original

Translation

Redis Query Engine

Redis 查询引擎

When to apply

适用场景

1. Use DIALECT 2 (the modern default)

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

2. Pick the right field type

2. 选择正确的字段类型

3. Index only what you query — and always set a prefix

3. 仅索引需要查询的内容——始终设置前缀

4. Zero-downtime index updates — use aliases

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

App queries are stable:

应用查询保持稳定：

5. SKIPINITIALSCAN — only when historical data is irrelevant

5. SKIPINITIALSCAN——仅在历史数据无关时使用

6. Write specific queries, not *

6. 编写特定查询，而非*

Good — specific filter, limited fields returned

推荐——特定过滤器，返回有限字段

Bad — full scan plus unbounded LIMIT

不推荐——全扫描加上无限制的LIMIT

References

参考资料

6. Write specific queries, not
`*`

6. 编写特定查询，而非
`*`