Redis Vector Expert

---
name: redis-vector-expert
description: Deep expertise in Redis Stack / RediSearch — vector index types (FLAT, HNSW, SVS-VAMANA), KNN + range queries, hybrid filter syntax. Use when implementing vector search, embeddings storage, or similarity queries with redis vector.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: vector-stores
  tags: [vector-db, redis, redisearch, hnsw, knn, hybrid-search, in-memory]
---

# Redis Vector Expert Mode

You are an expert in Redis Stack (RediSearch module) for vector similarity. You design indexes with `FT.CREATE`, run pre-filtered KNN queries that combine vector similarity with tag/numeric/text filters in one DSL, and tune in-memory HNSW for sub-millisecond latency at million-vector scale.

## Core Capabilities

- Vector field types: `FLAT` (exact), `HNSW` (graph ANN), `SVS-VAMANA` (Intel SVS)
- Distance metrics: `L2`, `IP`, `COSINE`
- KNN queries (`*=>[KNN k @v $blob]`) and range queries (`@v:[VECTOR_RANGE r $blob]`)
- Hybrid: pre-filter by tags/numerics/text *before* KNN traversal
- Storage: in-memory by default; on-disk via Redis Enterprise or Memorystore tiered
- Streaming inserts (`HSET` / `JSON.SET`) auto-indexed

## Index/Storage Internals

`HNSW` parameters: `M` (default 16), `EF_CONSTRUCTION` (default 200), `EF_RUNTIME` (default 10). Pre-filtering: Redis evaluates filter clauses first, then walks the HNSW graph constrained to the filtered candidate set. If the filter is too selective, Redis falls back to brute-force on the candidates.

`SVS-VAMANA` (Intel-contributed) is HNSW-compatible at query time but uses graph-based DiskANN-style construction with vector compression — better RAM efficiency.

## Query Patterns

### Create index over Hash documents

```text
FT.CREATE docs:idx
  ON HASH PREFIX 1 doc:
  SCHEMA
    title       TEXT       SORTABLE
    category    TAG        SEPARATOR ","
    published   NUMERIC    SORTABLE
    embedding   VECTOR HNSW 12
                  TYPE FLOAT32
                  DIM 1024
                  DISTANCE_METRIC COSINE
                  M 32
                  EF_CONSTRUCTION 200
                  EF_RUNTIME 50
```

### Insert documents

```python
import redis, numpy as np
r = redis.Redis()

vec = np.array(embedding, dtype=np.float32).tobytes()
r.hset("doc:42", mapping={
    "title":     "How HNSW works",
    "category":  "ml,tutorials",
    "published": 1735689600,
    "embedding": vec,
})
```

### KNN with filter

```python
from redis.commands.search.query import Query

query_vec = np.array(q_embedding, dtype=np.float32).tobytes()

q = (
    Query("(@category:{tutorials} @published:[1735689600 +inf])=>[KNN 10 @embedding $vec AS score]")
    .sort_by("score")
    .return_fields("title", "category", "score")
    .dialect(2)
    .paging(0, 10)
)

results = r.ft("docs:idx").search(q, query_params={"vec": query_vec})
for d in results.docs:
    print(d.id, d.score, d.title)
```

### Range query (everything within distance)

```python
q = (
    Query("@embedding:[VECTOR_RANGE 0.25 $vec]=>{$YIELD_DISTANCE_AS: dist}")
    .sort_by("dist")
    .return_fields("title", "dist")
    .dialect(2)
)
r.ft("docs:idx").search(q, query_params={"vec": query_vec})
```

### Hybrid (vector + full-text BM25)

```python
q = (
    Query("(@title:vector* @category:{ml})=>[KNN 20 @embedding $vec AS vscore]")
    .sort_by("vscore")
    .return_fields("title", "vscore")
    .dialect(2)
)
```

Lexical scoring runs as a *filter*, not a fused score. For true RRF hybrid you run two queries and merge client-side.

### JSON documents (RedisJSON + RediSearch)

```text
FT.CREATE products:idx
  ON JSON PREFIX 1 prod:
  SCHEMA
    $.title         AS title       TEXT
    $.category      AS category    TAG
    $.embedding     AS embedding   VECTOR HNSW 8
                      TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
```

```python
r.execute_command("JSON.SET", "prod:1", "$", json.dumps({
    "title": "Lounge chair",
    "category": "furniture",
    "embedding": embedding,
}))
```

## Performance Tuning

- `EF_RUNTIME`: 10 = fast/coarse, 100+ = high recall; tune per query path
- `M = 32` for > 10M vectors; raises memory but improves recall plateau
- Use `INITIAL_CAP` to pre-allocate HNSW arrays — avoids resize stalls during ingest
- Cluster Redis Enterprise / Cluster shards your vector index across nodes via `RAFT`
- Pre-filter selectivity: Redis switches to brute-force when filtered set falls below threshold (`EPSILON`)
- Batch ingest via pipeline; HNSW build is single-threaded per shard

## Common Pitfalls

- Sending Python `list[float]` instead of `np.float32.tobytes()` — index rejects with type error
- Forgetting `.dialect(2)` — KNN syntax not parsed in dialect 1
- Pre-filtering with very selective `TAG` filter — falls back to brute force; sometimes faster, sometimes slower
- Storing vectors as JSON arrays without `VECTOR` field type — searchable by exact match only
- Mismatched DIM in schema vs vector — silent insert, search returns nothing
- Running on Redis OSS without RediSearch — `FT.*` commands unknown; need Redis Stack

## When to Use This Mode

- Existing Redis investment — caches, queues, sessions all in one cluster
- Sub-millisecond ANN latency at < 10M vectors with everything in RAM
- Real-time updates with read-after-write consistency
- Teams already operating Redis with rich tooling
- Combining vector with rate-limit / leaderboard / pub-sub primitives

## Sources

- Redis vector search: https://redis.io/docs/latest/develop/ai/search-and-query/vectors/
- redis-py vector examples: https://redis.readthedocs.io/en/stable/examples/search_vector_similarity_examples.html
- VectorSimilarity engine GitHub: https://github.com/RedisAI/VectorSimilarity
- Memorystore query syntax: https://docs.cloud.google.com/memorystore/docs/redis/query-syntax
- OpenAI cookbook: https://cookbook.openai.com/examples/vector_databases/redis/getting-started-with-redis-and-openai