Redis Vector / RedisVL

0.14.1 · active · verified Sat Feb 28

The official AI-native Python client for vector search on Redis. Wraps redis-py with a high-level interface for defining vector schemas, building HNSW/FLAT indexes, running hybrid search, semantic routing, LLM caching, and session memory. Requires Redis 7.2+ with Search & Query module, or Redis Stack (self-hosted), or Redis Cloud. The underlying redis-py client is a separate package ('redis') — redisvl depends on it. Import root is 'redisvl'. Maintained by Redis Inc.

Warnings

breaking Plain redis (Redis OSS) does not support vector search. You must use Redis Stack, Redis Cloud, or Redis Enterprise — all of which include the Search & Query module. pip install redisvl succeeds but all index operations fail against plain Redis.
Fix: Use: docker run -d redis/redis-stack:latest for local dev, or Redis Cloud free tier. Cannot use standard redis:latest Docker image.
breaking HybridQuery (native hybrid text+vector search) requires Redis 8.4.0+. Using it against Redis 7.x or 8.x < 8.4.0 raises a command error. AggregateHybridQuery is the backward-compatible alternative.
Fix: Check Redis version before using HybridQuery. Use AggregateHybridQuery for Redis < 8.4.0.
breaking redis-py 6.0.0 introduced a client-side default dialect override (DIALECT 2) for FT.SEARCH and FT.AGGREGATE. This can change query results compared to older versions. Affects raw redis-py users who rely on default dialect behavior.
Fix: Pin dialect explicitly in queries if you need dialect 1 behavior, or audit query results after upgrading redis-py to 6.x.
gotcha COSINE distance in Redis uses the range [0, 2], not [0, 1]. 0 = identical, 2 = opposite. Documentation has historically stated [0, 1] in some places — this was incorrect. Fixed in redisvl release notes.
Fix: Use thresholds in [0, 2] range for cosine distance in Redis. A threshold of 0.2 in pinecone/other libraries is ~0.2 here too but verify against your data.
gotcha Vectors must be stored as bytes (np.array(..., dtype='float32').tobytes()) for HASH storage type. Passing a Python list or numpy array directly to index.load() silently stores wrong data.
Fix: Always call .astype('float32').tobytes() when using HASH storage. JSON storage type handles serialization differently — check redisvl docs for your storage_type.
gotcha redisvl previously had an unintentional dependency on botocore (AWS SDK). Any environment without boto would get an ImportError on redisvl.utils.vectorize. Fixed in a patch release.
Fix: Keep redisvl up to date. If hitting ImportError on botocore, upgrade redisvl.

Install

pip install redisvl Core install (no vectorizer deps)
pip install redisvl[openai] With OpenAI vectorizer
pip install redisvl[all] All vectorizer dependencies
pip install redisvl[hiredis] With hiredis (high-performance parser)
docker run -d --name redis -p 6379:6379 -p 8001:8001 redis/redis-stack:latest Local Redis Stack (required for vector search)

Imports

SearchIndex
```
from redisvl.index import SearchIndex
```
redisvl does not have a useful top-level import. All classes are in submodules.
VectorQuery
```
from redisvl.query import VectorQuery
```
Also HybridQuery (Redis 8.4.0+ only), RangeQuery, FilterQuery.
IndexSchema
```
from redisvl.schema import IndexSchema
```
Schema can be loaded from a dict or YAML file.

Quickstart

Requires Redis Stack or Redis Cloud running locally. Vectors stored as bytes (float32.tobytes()) in HASH storage. HNSW index supports incremental inserts. Use AsyncSearchIndex for async workflows.

import numpy as np
from redis import Redis
from redisvl.index import SearchIndex
from redisvl.schema import IndexSchema
from redisvl.query import VectorQuery

# Define schema
schema = IndexSchema.from_dict({
    "index": {"name": "docs", "prefix": "doc", "storage_type": "hash"},
    "fields": [
        {"name": "text", "type": "text"},
        {
            "name": "embedding",
            "type": "vector",
            "attrs": {
                "algorithm": "hnsw",
                "datatype": "float32",
                "dims": 4,
                "distance_metric": "cosine"
            }
        }
    ]
})

# Connect and create index
index = SearchIndex(schema, redis_url="redis://localhost:6379")
index.create(overwrite=True)

# Load data
index.load([
    {"id": "1", "text": "hello world", "embedding": np.array([0.1, 0.2, 0.3, 0.4], dtype='float32').tobytes()},
])

# Search
query = VectorQuery(
    vector=[0.1, 0.2, 0.3, 0.4],
    vector_field_name="embedding",
    num_results=5
)
results = index.query(query)
print(results)

view raw JSON →