redis-query-engine

Redis Query Engine

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.

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.

1. Use DIALECT 2 (the modern default)

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.

When connecting to Redis, use an encrypted connection, read credentials from the environment or a secrets store, use a database user limited to the commands and key prefixes the task needs, and keep passwords out of commands and output.

See references/dialect.md.

2. Pick the right field type

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

The classic mistake is using TEXT for a category or status field because "it's a string." TAG is typically much faster and more accurate for exact match filters.

See references/field-types.md.

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

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.
• Before creating or altering an index on a large production keyspace, check memory headroom, estimate index size, run the change during a low traffic window with user approval, and watch FT.INFO while indexing runs.

See references/index-creation.md.

4. Zero-downtime index updates — use aliases

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 ...
# Wait until FT.INFO idx:products_v2 shows indexing is complete, compare document counts
# and sample results against the old index, and keep the old index for rollback.
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.

FT.DROPINDEX with its delete documents option removes every indexed key, not just the index. Get explicit user confirmation of the exact index or alias name before dropping an index or deleting an alias in production, and drop an old index only after the new one is verified, keeping its documents in place.

See references/index-management.md.

5. SKIPINITIALSCAN — only when historical data is irrelevant

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.
• You're indexing event streams where only future events matter.

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

The initial scan runs in the background, and progress is visible in FT.INFO. With SKIPINITIALSCAN, existing keys stay unsearchable until they are rewritten, so confirm with the user that historical documents need not be searchable before using it.

See references/skip-initial-scan.md.

6. Write specific queries, not *

Narrow the result set with filters before paging or aggregating.

# 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

Other levers:

• SORTBY requires SORTABLE on the sort field. Without it, sort is slow.
• LIMIT bounds the returned results and response size, while filters narrow the work done; large offsets add cost, so use small page sizes.
• 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.
• When reporting FT.INFO, FT._LIST or FT.PROFILE output, summarize only the relevant fields and leave out full schemas, prefixes or query text that may hold sensitive values.

Treat user supplied values as untrusted: pass them as query parameters with DIALECT 2 rather than joining them into the query string, escape special characters (punctuation, spaces, braces, pipes, dashes, at signs) in TAG and TEXT values that cannot be passed as parameters, and enforce tenant and authorization filters in server code rather than in user controlled query text.

See references/query-optimization.md.

References

• Redis: Query Engine — Indexing
• Redis: Query syntax
• Redis: Query dialects
• Redis: Administration (aliases, dropindex)
• FT.CREATE