RFC: Integrate RedisVL as underlying query engine

Summary

This issue tracks the plan to integrate RedisVL as the underlying query engine for Redis OM's search and vector operations. The goal is to leverage RedisVL's mature query engine while keeping Redis OM focused on ORM semantics.

Motivation

Currently, Redis OM and RedisVL have overlapping implementations for:

• RediSearch index schema generation
• FT.CREATE / FT.SEARCH / FT.AGGREGATE operations
• Vector query building
• Connection and cluster handling

RedisVL has more advanced capabilities:

• Hybrid vector policies (BATCHES, ADHOC_BF)
• EF_RUNTIME tuning, epsilon, range queries
• Cluster-aware error handling and hash-tag validation
• Comprehensive schema system covering all Redis field types

Rather than maintaining parallel implementations, Redis OM should delegate search/index work to RedisVL.

Architecture

Redis OM stays focused on:

• Domain modeling (Pydantic-based HashModel/JsonModel)
• CRUD operations (.save(), .get(), .delete())
• Query DSL (Model.find(...) with field expressions)
• Migration CLI & tooling
• Web framework integration

RedisVL becomes the canonical layer for:

• Index schema representation and lifecycle
• FT.* command execution
• Vector query building and tuning
• Cluster-specific semantics

Implementation Phases

Phase 1: Internal Adapter (No Public API Changes)

1. Introduce a SearchBackend protocol in Redis OM:

class SearchBackend(Protocol):
    async def ensure_index(self, model_cls: type[RedisModel]) -> None: ...
    async def drop_index(self, model_cls: type[RedisModel]) -> None: ...
    async def query(
        self,
        model_cls: type[RedisModel],
        query_expr: str | None,
        knn: KNNExpression | None,
        sort: list[str] | None,
        offset: int,
        limit: int,
    ) -> list[dict[str, Any]]: ...

2. Two implementations:

   • LegacySearchBackend (current behavior)
   • RedisVLBackend (new, behind feature flag)

3. Feature flag: REDIS_OM_SEARCH_BACKEND=redisvl or Meta.search_backend = "redisvl"

Phase 2: RedisVL Default for Vector Search

• If a model has vector fields and RedisVL is installed, use RedisVL backend
• Keep non-vector search on legacy backend initially
• Reduces duplication for the most complex part first

Phase 3: Migrate All Search to RedisVL

• Make RedisVL backend default for all indexed models
• Deprecate legacy search implementation
• Expose more RedisVL knobs through OM's API (epsilon, hybrid policy, range queries)

Phase 4: Optional Shared Core Package

• Extract redis-query-core if beneficial
• Both Redis OM and RedisVL depend on it
• RedisVL keeps AI extras (rerankers, caches, SVS)

Initial Step (1.0.x or 1.1)

As a first step, we'll:

1. Add redisvl as an optional dependency
2. Add Model.to_redisvl_schema() method to generate RedisVL IndexSchema from OM models
3. Document the escape hatch for advanced vector queries

This gives users immediate access to RedisVL's advanced features without changing OM internals.

Related

• RedisVL: https://github.com/redis/redis-vl-python
• RedisVL docs: https://redis.io/docs/latest/integrate/redisvl/

The issue names no repository files or tests. Start by reviewing the existing model schema path and RedisVL's IndexSchema API, then scope the initial step around the optional dependency, Model.to_redisvl_schema(), and documentation for the advanced-query escape hatch; done means those three deliverables are defined without changing the public search behavior.