# Vector and hybrid search

```json metadata
{
  "title": "Vector and hybrid search",
  "description": "Search by meaning with vector embeddings, run KNN queries with FT.SEARCH, and combine keywords with semantic similarity using FT.HYBRID.",
  "categories": ["docs","develop","stack","oss","rs","rc","oss","kubernetes","clients"],
  "tableOfContents": {"sections":[{"id":"how-vector-search-works","title":"How vector search works"},{"id":"generate-and-store-embeddings","title":"Generate and store embeddings"},{"id":"add-a-vector-field-to-the-index","title":"Add a vector field to the index"},{"children":[{"id":"pre-filter-the-candidates","title":"Pre-filter the candidates"}],"id":"k-nearest-neighbors-knn","title":"K-nearest neighbors (KNN)"},{"id":"hybrid-search","title":"Hybrid search"},{"id":"what-you-have-learned","title":"What you have learned"},{"id":"where-to-go-next","title":"Where to go next"}]}

,
  "codeExamples": [{"codetabsId":"search_tutorial-stepcreate_vector_index","commands":[{"acl_categories":["@write","@slow","@dangerous","@search"],"complexity":"O(1)","name":"FT.DROPINDEX"},{"acl_categories":["@search"],"complexity":"O(K)","name":"FT.CREATE"}],"description":"Foundational: Recreate the index with a VECTOR field so embeddings can be searched","difficulty":"intermediate","id":"create_vector_index","languages":[{"id":"redis-cli","panelId":"panel_redis-cli_search_tutorial-stepcreate_vector_index"},{"clientId":"redis-py","clientName":"redis-py","id":"Python","langId":"python","panelId":"panel_Python_search_tutorial-stepcreate_vector_index"}]},{"codetabsId":"search_tutorial-stepvector_knn","description":"Vector KNN: Find the k nearest documents to a query vector using the =\u0026amp;gt;[KNN ...] syntax","difficulty":"intermediate","id":"vector_knn","languages":[{"id":"redis-cli","panelId":"panel_redis-cli_search_tutorial-stepvector_knn"},{"clientId":"redis-py","clientName":"redis-py","id":"Python","langId":"python","panelId":"panel_Python_search_tutorial-stepvector_knn"}]},{"codetabsId":"search_tutorial-stepvector_prefilter","commands":[{"acl_categories":["@read","@search"],"complexity":"O(N)","name":"FT.SEARCH"}],"description":"Filtered vector search: Restrict KNN candidates with a pre-filter before the vector search runs","difficulty":"advanced","id":"vector_prefilter","languages":[{"id":"redis-cli","panelId":"panel_redis-cli_search_tutorial-stepvector_prefilter"},{"clientId":"redis-py","clientName":"redis-py","id":"Python","langId":"python","panelId":"panel_Python_search_tutorial-stepvector_prefilter"}]},{"codetabsId":"search_tutorial-stephybrid_search","commands":[{"acl_categories":["@read","@search"],"complexity":"O(N+M)","name":"FT.HYBRID"}],"description":"Hybrid search: Combine a full-text SEARCH clause with a vector VSIM clause using FT.HYBRID","difficulty":"advanced","id":"hybrid_search","languages":[{"id":"redis-cli","panelId":"panel_redis-cli_search_tutorial-stephybrid_search"},{"clientId":"redis-py","clientName":"redis-py","id":"Python","langId":"python","panelId":"panel_Python_search_tutorial-stephybrid_search"}]}]
}
```## Code Examples Legend

The code examples below show how to perform the same operations in different programming languages and client libraries:

- **Redis CLI**: Command-line interface for Redis
- **C# (Synchronous)**: StackExchange.Redis synchronous client
- **C# (Asynchronous)**: StackExchange.Redis asynchronous client
- **Go**: go-redis client
- **Java (Synchronous - Jedis)**: Jedis synchronous client
- **Java (Asynchronous - Lettuce)**: Lettuce asynchronous client
- **Java (Reactive - Lettuce)**: Lettuce reactive/streaming client
- **JavaScript (Node.js)**: node-redis client
- **PHP**: Predis client
- **Python**: redis-py client
- **Rust (Synchronous)**: redis-rs synchronous client
- **Rust (Asynchronous)**: redis-rs asynchronous client

Each code example demonstrates the same basic operation across different languages. The specific syntax and patterns vary based on the language and client library, but the underlying Redis commands and behavior remain consistent.

---


This is the final step of the [Redis Search tutorial](https://redis.io/docs/latest/develop/get-started/search-tutorial). It builds on everything so far: the [catalog](https://redis.io/docs/latest/develop/get-started/search-tutorial/data-modeling), the [index](https://redis.io/docs/latest/develop/get-started/search-tutorial/indexing), and the [search](https://redis.io/docs/latest/develop/get-started/search-tutorial/search) syntax.


The hybrid search section uses [FT.HYBRID](https://redis.io/docs/latest/commands/ft.hybrid), which requires Redis 8.8 or later. Vector search with `FT.SEARCH` works on earlier versions with Redis Search.


So far you have matched products by the words they contain and the exact values of their fields. But a shopper searching for "*something to listen to music on a run*" will not use the word *headphones* or *earbuds*, and a keyword search would miss them. **Vector search** solves this by matching on *meaning* rather than exact words.


This tutorial performs vector search with `redis-cli` and the core Redis commands, and shows `redis-py` for Python. If you want a higher-level Python experience, [RedisVL](https://redis.io/docs/latest/develop/clients/redis-vl) is a client library purpose-built for vector workflows. You can also find vector search examples for the other client libraries:

- [`redis-py` (Python)](https://redis.io/docs/latest/develop/clients/redis-py/vecsearch)
- [`NRedisStack` (C#/.NET)](https://redis.io/docs/latest/develop/clients/dotnet/nredisstack/vecsearch)
- [`node-redis` (JavaScript/Node.js)](https://redis.io/docs/latest/develop/clients/nodejs/vecsearch)
- [`jedis` (Java)](https://redis.io/docs/latest/develop/clients/jedis/vecsearch)
- [`go-redis` (Go)](https://redis.io/docs/latest/develop/clients/go/vecsearch)


## How vector search works

A machine learning **embedding model** turns a piece of text into a list of numbers, called a **vector**, that captures its meaning. Texts with similar meanings produce vectors that are close together in space. To search by meaning, you:

1. Generate an embedding for each product (here, from its description) and store it on the document.
2. Add a `VECTOR` field to the index so Redis can search those embeddings.
3. At query time, embed the search phrase and ask Redis for the products whose vectors are nearest to it.

"Nearest" is measured by a **distance metric**. This tutorial uses cosine distance, where a smaller distance means more similar.

## Generate and store embeddings

Embeddings come from a model, so this step uses a client library rather than `redis-cli`. The example below uses the Python [SentenceTransformers](https://www.sbert.net/) framework to embed each product description and store the result on the document under `$.embedding`. The model used here produces 768-dimensional vectors.

```python
from redis import Redis
from sentence_transformers import SentenceTransformer

r = Redis(host="localhost", port=6379, decode_responses=True)
embedder = SentenceTransformer("msmarco-distilbert-base-v4")  # 768-dimensional vectors

# Embed each product's description and store it on the document.
for key in r.scan_iter(match="product:*"):
    description = r.json().get(key, "$.description")[0]
    embedding = embedder.encode(description).astype("float32").tolist()
    r.json().set(key, "$.embedding", embedding)
```

Redis can store vectors in either hashes or JSON documents. Because this tutorial uses JSON, each embedding is stored as a JSON array of numbers, so every product now has an `embedding` field alongside its other attributes.

## Add a vector field to the index

The index you created earlier does not know about the new `embedding` field. Recreate it to include a `VECTOR` field. Dropping the index does not delete your documents, and the embeddings you just stored are indexed as soon as the new index is created:

Foundational: Recreate the index with a VECTOR field so embeddings can be searched

**Difficulty:** Intermediate

**Commands:** FT.DROPINDEX, FT.CREATE

**Complexity:**
- FT.DROPINDEX: O(1)
- FT.CREATE: O(K)

**Available in:** Redis CLI, Python

##### Redis CLI

```
> FT.DROPINDEX idx:catalog
OK
> FT.CREATE idx:catalog ON JSON PREFIX 1 product: SCHEMA $.name AS name TEXT $.brand AS brand TAG SORTABLE $.category AS category TAG $.description AS description TEXT $.price AS price NUMERIC SORTABLE $.rating AS rating NUMERIC SORTABLE $.features[*] AS features TAG $.embedding AS embedding VECTOR FLAT 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
OK
```

##### Python

```python
r.ft("idx:catalog").dropindex()
schema = (
    TextField("$.name", as_name="name"),
    TagField("$.brand", as_name="brand", sortable=True),
    TagField("$.category", as_name="category"),
    TextField("$.description", as_name="description"),
    NumericField("$.price", as_name="price", sortable=True),
    NumericField("$.rating", as_name="rating", sortable=True),
    TagField("$.features[*]", as_name="features"),
    VectorField(
        "$.embedding",
        "FLAT",
        {"TYPE": "FLOAT32", "DIM": 768, "DISTANCE_METRIC": "COSINE"},
        as_name="embedding",
    ),
)
index = r.ft("idx:catalog")
index.create_index(
    schema,
    definition=IndexDefinition(prefix=["product:"], index_type=IndexType.JSON),
)
```



The vector field definition reads: index `$.embedding` as a `VECTOR` field using the `FLAT` algorithm, with `6` attributes following — `TYPE FLOAT32`, `DIM 768` (the model's dimension), and `DISTANCE_METRIC COSINE`. `FLAT` does an exact search and is a good default for small datasets; for large datasets you would choose `HNSW`. For all the options, see the [vector search concepts](https://redis.io/docs/latest/develop/ai/search-and-query/vectors) page.

## K-nearest neighbors (KNN)

A KNN query asks for the `k` products whose embeddings are closest to a query vector. You embed the search phrase with the *same* model, then pass the resulting vector to `FT.SEARCH`:

**Available in:** Redis CLI, Python

##### Redis CLI

```
[KNN ...] syntax" difficulty="intermediate" >}}
> FT.SEARCH idx:catalog "(*)=>[KNN 3 @embedding $query_vector AS score]" PARAMS 2 query_vector "\x9a\x99\x19\x3f..." SORTBY score ASC RETURN 2 score name DIALECT 2
```

##### Python

```python
query_vector = (
    embedder.encode("portable music for the outdoors").astype("float32").tobytes()
)
res = index.search(
    Query("(*)=>[KNN 3 @embedding $query_vector AS score]")
    .sort_by("score", asc=True)
    .return_fields("score", "name")
    .dialect(2),
    query_params={"query_vector": query_vector},
)
print([d.name for d in res.docs])
# >>> ['Sonus Boom Portable Speaker', 'Aurora BudsMini Earbuds', 'Aurora AcousticPro Headphones']
```



Here is what each part does:

- **`(*)`** is a pre-filter that runs *before* the vector search. `(*)` means "consider all products". You can put any query here to restrict the candidates (shown next).
- **`=>[KNN 3 @embedding $query_vector AS score]`** asks for the 3 nearest neighbors in the `embedding` field, naming each result's distance `score`.
- **`PARAMS 2 query_vector "..."`** supplies the query vector's binary value. The `2` means two arguments follow: the parameter name and its value.
- **`SORTBY score ASC`** orders results closest-first, and **`DIALECT 2`** selects the query dialect that vector search requires.


The query vector's binary value is long, so it is shortened in the example above. In a real application your client library builds it for you from the model's output, as in the [embedding step](#generate-and-store-embeddings) above.


For a phrase like "*portable music for the outdoors*", this returns the products whose descriptions are closest in meaning — the portable speaker and the earbuds rank highly — even though they share no specific keyword with the query.

### Pre-filter the candidates

The pre-filter is where vector search meets the filtering you already know. Replace `(*)` with any `FT.SEARCH` query to search for similar products *within a subset*. This finds the 3 nearest products **among Audio products only**:

Filtered vector search: Restrict KNN candidates with a pre-filter before the vector search runs

**Difficulty:** Advanced

**Commands:** FT.SEARCH

**Complexity:**
- FT.SEARCH: O(N)

**Available in:** Redis CLI, Python

##### Redis CLI

```
> FT.SEARCH idx:catalog "(@category:{Audio})=>[KNN 3 @embedding $query_vector AS score]" PARAMS 2 query_vector "\x9a\x99\x19\x3f..." SORTBY score ASC RETURN 2 score name DIALECT 2
```

##### Python

```python
res = index.search(
    Query("(@category:{Audio})=>[KNN 3 @embedding $query_vector AS score]")
    .sort_by("score", asc=True)
    .return_field("name")
    .dialect(2),
    query_params={"query_vector": query_vector},
)
print([d.name for d in res.docs])
# >>> ['Sonus Boom Portable Speaker', 'Aurora BudsMini Earbuds', 'Aurora AcousticPro Headphones']
```



## Hybrid search

Keyword search and vector search each have strengths. Keyword search is precise when the user knows the exact term; vector search is forgiving when they describe what they want in their own words. **Hybrid search** runs both at once and fuses the results, giving you the best of each.

The [FT.HYBRID](https://redis.io/docs/latest/commands/ft.hybrid) command takes a `SEARCH` clause (a full-text query, exactly like `FT.SEARCH`) and a `VSIM` clause (a vector similarity query), and combines their rankings. This searches for the keyword *wireless* and, at the same time, for products semantically similar to the query vector (here, an embedding of "*wireless headphones for listening to music*"):

Hybrid search: Combine a full-text SEARCH clause with a vector VSIM clause using FT.HYBRID

**Difficulty:** Advanced

**Commands:** FT.HYBRID

**Complexity:**
- FT.HYBRID: O(N+M)

**Available in:** Redis CLI, Python

##### Redis CLI

```
> FT.HYBRID idx:catalog SEARCH "wireless" VSIM @embedding $query_vector KNN 2 K 5 LOAD 1 @name PARAMS 2 query_vector "\x9a\x99\x19\x3f..."
```

##### Python

```python
hybrid_vector = (
    embedder.encode("wireless headphones for listening to music")
    .astype("float32")
    .tobytes()
)
res = r.execute_command(
    "FT.HYBRID",
    "idx:catalog",
    "SEARCH",
    "wireless",
    "VSIM",
    "@embedding",
    "$query_vector",
    "KNN",
    "2",
    "K",
    "5",
    "LOAD",
    "1",
    "@name",
    "PARAMS",
    "2",
    "query_vector",
    hybrid_vector,
)
print(res)
# >>> {'total_results': 7, 'results': [{'name': 'Aurora AcousticPro Headphones'}, ...]}
```



As with the KNN examples, the query vector's binary value is shortened above; your client library builds it from the model's output.

The result blends two rankings: products that literally mention *wireless* and products whose meaning is closest to the query vector. For this query, the wireless headphones and earbuds come out on top — they satisfy both the keyword and the meaning — followed by other wireless items and the nearest semantic matches such as the portable speaker.

By default, `FT.HYBRID` fuses the two rankings with a method called Reciprocal Rank Fusion. You can tune the balance with a `COMBINE` clause, and add `FILTER`, `LOAD`, `APPLY`, and `SORTBY` steps just as you would in an aggregation. See the [FT.HYBRID](https://redis.io/docs/latest/commands/ft.hybrid) reference for the full syntax.


The [Redis Insight Search workspace](https://redis.io/docs/latest/develop/tools/insight/search-workspace) is built for exactly this kind of work. Its welcome screen introduces full-text, vector, and hybrid search, it can load a ready-made vector dataset, and its editor handles the vector parameters for you — a much friendlier way to experiment with vector and hybrid queries than pasting binary blobs into `redis-cli`.


## What you have learned

Congratulations — you have gone from an empty database to running hybrid semantic search. Along the way you:

1. Modeled records as JSON documents and learned when hashes fit better.
2. Created an index and chose `TEXT`, `TAG`, and `NUMERIC` field types.
3. Searched, filtered, and projected with `FT.SEARCH`.
4. Grouped and summarized data with `FT.AGGREGATE`.
5. Searched by meaning with vector KNN and combined it with keywords using `FT.HYBRID`.

## Where to go next

- **Go deeper on querying** — the [query documentation](https://redis.io/docs/latest/develop/ai/search-and-query/query) covers fuzzy matching, geospatial queries, scoring, and more.
- **Tune your vectors** — [vector search concepts](https://redis.io/docs/latest/develop/ai/search-and-query/vectors) explains the `FLAT` and `HNSW` index types, vector range queries, and how to choose between them.
- **Use a vector-native Python library** — [RedisVL](https://redis.io/docs/latest/develop/clients/redis-vl) provides a higher-level API for building vector search and AI applications on Redis.
- **Build an AI application** — see how Redis powers retrieval-augmented generation in the [RAG quick start](https://redis.io/docs/latest/develop/get-started/rag) and [Redis for AI](https://redis.io/docs/latest/develop/ai).
- **See also** — if you need standalone similarity search without a full search index, Redis also offers the [vector sets](https://redis.io/docs/latest/develop/data-types/vector-sets) data type.