Vector and hybrid search

Search by meaning with vector embeddings, run KNN queries with FT.SEARCH, and combine keywords with semantic similarity using FT.HYBRID.

This is the final step of the Redis Search tutorial. It builds on everything so far: the catalog, the index, and the search syntax.

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.

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 framework to embed each product description and store the result on the document under $.embedding. The model used here produces 768-dimensional vectors.

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:

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 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:

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.

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:

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 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_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 reference for the full syntax.

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 covers fuzzy matching, geospatial queries, scoring, and more.
• Tune your vectors — vector search concepts explains the FLAT and HNSW index types, vector range queries, and how to choose between them.
• Use a vector-native Python library — RedisVL 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 and Redis for AI.
• See also — if you need standalone similarity search without a full search index, Redis also offers the vector sets data type.