Skip to main content
Support Requests Chat with us

Redis Software: Search Command Deprecations and Query Parsing Changes in Redis 8

Natalie Patterson

0 comments

Redis Software 8.0 introduces the Redis Search, replacing legacy Search command behavior and enforcing stricter parsing rules. This article outlines deprecated commands and options, parsing and validation changes, and the steps operators must take before upgrading cluster databases to Redis 8.0 or later.

At a glance

  • Availability: Redis Software 8.0 and later

  • Applies to: Cluster databases using Search / Query features (RediSearch → RQE)

  • Impact: Deprecated Search commands and options are removed; strict parsing may break legacy queries or scripts.

  • Behavior: Enforced automatically with no rollback toggle once databases run Redis 8.0

Prerequisites

  • Cluster nodes upgraded to Redis Software 8.0 or later

  • Databases using Redis Search 

  • Admin access via rladmin, REST API, or Admin UI

  • Valid backup before upgrade

  • Maintenance window to validate and test query behavior post-upgrade

Pre-upgrade checklist

Problem Fast check Action
FT.ADD or FT.DEL failing Command rejected during upgrade test Replace with native writes (HSET / JSON.SET) and deletes (DEL / UNLINK).
FT.SEARCH using FILTER or GEOFILTER Query returns “Invalid argument” Convert filters to query syntax (@price:[10 20], @loc:[-73.98 40.75 5 km]).
Queries using NOSTOPWORDS Option ignored or rejected Define STOPWORDS behavior when creating index.
Older dialect specified (1, 3, 4) Query fails or returns 0 results Use DIALECT 2.
FT.CONFIG deprecated Command error on execution Replace with CONFIG GET/SET; verify allowed parameters.

Migration summary table

Problem Fast check Action
FT.ADD or FT.DEL failing Command rejected during upgrade test Replace with native writes (HSET / JSON.SET) and deletes (DEL / UNLINK).
FT.SEARCH using FILTER or GEOFILTER Query returns “Invalid argument” Convert filters to query syntax (@price:[10 20], @loc:[-73.98 40.75 5 km]).
Queries using NOSTOPWORDS Option ignored or rejected Define STOPWORDS behavior when creating index.
Older dialect specified (1, 3, 4) Query fails or returns 0 results Use DIALECT 2.
FT.CONFIG deprecated Command error on execution Replace with CONFIG GET/SET; verify allowed parameters.

Deprecations

Deprecated command or option Replacement Example Notes
FT.ADD, FT.SAFEADD Use HSET or JSON.SET HSET user:1 name "Alice" Index updates automatically through RQE.
FT.DEL Use DEL or UNLINK DEL user:1 Removes document from index automatically.
FT.GET, FT.MGET Use native reads JSON.GET user:1 Direct key reads.
FT.CONFIG Use CONFIG GET/SET CONFIG GET search_* Server-level parameters only.
FILTER / GEOFILTER Use query syntax @price:[10 20], @loc:[-73.98 40.75 5 km] No longer supported as options.
NOSTOPWORDS Use STOPWORDS 0 in schema FT.CREATE idx STOPWORDS 0 ... Query-time flag removed.
DIALECT 1, 3, 4 Use DIALECT 2 FT.SEARCH idx ... DIALECT 2 Deprecated dialects removed.

Parsing and validation changes

Redis Software 8.0 enforces full command argument validation.

Key updates

  • LIMIT must have valid combinations (offset=0 when limit=0).

  • FT.CURSOR READ and FT.ALIASADD enforce strict argument ordering.

  • APPLY expressions require parentheses around exponents (for example, (@price ^ 2)).

  • Invalid input now returns errors, not empty result sets.

  • Default scoring algorithm switched from TF-IDF → BM25.

Migration steps

  1. Audit command usage.
    Search scripts, Lua code, or apps for deprecated FT.* commands and options.

  2. Replace writes and deletes.
    Use HSET / JSON.SET for writes and DEL / UNLINK for deletes, indexes auto-update.

  3. Rewrite queries.
    Convert numeric and geo filters to inline query syntax.

  4. Enforce dialect.
    Specify DIALECT 2 explicitly in all queries.

  5. Review configurations.
    Validate CONFIG parameters for RQE; remove unsupported ones from automation scripts.

  6. Validate ACLs.
    Ensure roles allow RQE commands under @read or @write.

  7. Test and monitor.
    Run verification queries and observe metrics for query errors or ranking changes.

Testing and verification

Test Command Expected result
Numeric range query FT.SEARCH idx "@price:[10 20]" LIMIT 0 10 Returns matching documents
Geo query FT.SEARCH idx "@loc:[-73.98 40.75 5 km]" Returns nearby documents
Deprecated syntax FT.SEARCH idx * FILTER price 10 20 Fails with “Invalid argument”
LIMIT rule FT.SEARCH idx "*" LIMIT 10 0 Fails (invalid offset/limit)
ACL validation Restricted user runs FT.SEARCH Allowed if +@read; JSON.SET denied if -@write

Troubleshooting

Symptom Likely cause Resolution
“Invalid argument” errors post-upgrade Deprecated syntax (FILTER, GEOFILTER) Convert to query-string syntax.
Empty search results Dialect mismatch Add DIALECT 2.
Ranking changes Scoring method changed Validate results and retune scoring thresholds.
Command failures in automation Deprecated FT.CONFIG calls Replace with supported CONFIG operations.
ACL permission errors ACL category updates Re-evaluate roles for RQE coverage.

References

For assistance upgrading or remediating deprecated command usage, contact Redis Support and include your database ID, Redis version, and command examples.

 

Related to

Was this article helpful?

0 out of 0 found this helpful

Related articles

0 comments

Please sign in to leave a comment.