FT.HYBRID

Syntax
FT.HYBRID index SEARCH query [SCORER scorer]
  [YIELD_SCORE_AS yield_score_as] VSIM field vector [KNN count K k
  [EF_RUNTIME ef_runtime] [YIELD_SCORE_AS yield_score_as] | RANGE
  count RADIUS radius [EPSILON epsilon]
  [YIELD_SCORE_AS yield_score_as]] [FILTER filter] [COMBINE <RRF
  count [CONSTANT constant] [WINDOW window]
  [YIELD_SCORE_AS yield_score_as] | LINEAR count [ALPHA alpha
  BETA beta] [WINDOW window] [YIELD_SCORE_AS yield_score_as]>]
  [LIMIT offset num] [SORTBY sortby [ASC | DESC] | NOSORT] [PARAMS
  nargs name value [name value ...]] [TIMEOUT timeout]
  [FORMAT format] [LOAD count field [field ...]] [LOAD *] [GROUPBY
  nproperties property [property ...] [REDUCE <COUNT |
  COUNT_DISTINCT | COUNT_DISTINCTISH | SUM | MIN | MAX | AVG |
  STDDEV | QUANTILE | TOLIST | FIRST_VALUE | RANDOM_SAMPLE> nargs
  arg [arg ...] [AS name] [REDUCE <COUNT | COUNT_DISTINCT |
  COUNT_DISTINCTISH | SUM | MIN | MAX | AVG | STDDEV | QUANTILE |
  TOLIST | FIRST_VALUE | RANDOM_SAMPLE> nargs arg [arg ...]
  [AS name] ...]]] [APPLY expression AS name [APPLY expression
  AS name ...]] [FILTER filter]
Available since:
Redis Open Source 8.4.0
Time complexity:
O(N+M) where N is the complexity of the text search and M is the complexity of the vector search
ACL categories:
@read, @search,
Compatibility:
Redis Enterprise and Redis Cloud compatibility

Performs hybrid search combining text search and vector similarity with configurable fusion methods.

FT.HYBRID provides a unified interface for combining traditional full-text and vector-based search within a single query. It supports hybrid retrieval use cases such as semantic search, Retrieval-Augmented Generation (RAG), and intelligent agent applications. The command builds on the familiar query syntax of FT.SEARCH and FT.AGGREGATE, simplifying hybrid query construction while enabling flexible post-processing through aggregation capabilities.

Note:
This command will only return document IDs (keyid) and scores to which the user has read access. To retrieve entire documents, use projections with LOAD * or LOAD <count> field....

Examples

Required arguments

index

is the name of the index. You must first create the index using FT.CREATE.

SEARCH "search-expression"

defines the text search component of the hybrid query. The search expression uses the same syntax as FT.SEARCH queries, supporting all text search capabilities including field-specific searches, boolean operations, and phrase matching.

VSIM @vector_field "vector-data"

defines the vector similarity component of the hybrid query. The @vector_field specifies which vector field in the index to search against (for example, $vector), and "vector-data" contains the query vector for similarity comparison (for example, PARAMS 2 $vector <vector-blob>).

Optional arguments

SCORER algorithm params...

specifies the scoring algorithm and parameters for the text search component. Supports aliasing and follows the parameter count convention where the first number indicates the total count of following parameters.

Example: SCORER 4 BM25 1.2 0.75 uses BM25 algorithm with parameters 1.2 and 0.75.

YIELD_SCORE_AS alias-search-score

assigns an alias to the search score for use in post-processing operations like APPLY or SORTBY.

KNN count K topk-k [EF_RUNTIME ef-value] [YIELD_DISTANCE_AS distance_field]

configures K-nearest neighbors search for vector similarity. The count parameter indicates the number of following parameters. K specifies the number of nearest neighbors to find. EF_RUNTIME controls the search accuracy vs. speed tradeoff. YIELD_DISTANCE_AS assigns an alias to the distance value.

RANGE count RADIUS radius-value [EPSILON epsilon-value] [YIELD_DISTANCE_AS distance_field]

configures range-based vector search within a specified radius. The count parameter indicates the number of following parameters. RADIUS defines the maximum distance for matches. EPSILON provides additional precision control.

FILTER "filter-expression"

applies pre-filtering to vector search results or post-filtering when used after the COMBINE step as post-processing. This filter affects which documents are considered for vector similarity but doesn't impact scoring. In contrast, the SEARCH component affects both filtering and scoring. The FILTER syntax uses a search expression with the same syntax as FT.SEARCH, supporting all text search capabilities including field-specific searches, boolean operations, and phrase matching

POLICY [ADHOC_BF|BATCHES] [BATCH_SIZE batch-size-value]

controls the pre-filtering policy for vector queries. ADHOC_BF processes filters on-demand and BATCHES processes in configurable batch sizes. See the pre-filtering policy for more information.

COMBINE method params...

specifies how to fuse the text search and vector similarity results. Supports multiple fusion methods:

  • RRF (Reciprocal Rank Fusion): Default method. Parameters include WINDOW (default 20) and CONSTANT (default 60).
  • LINEAR: Linear combination with ALPHA and BETA weights.
  • FUNCTION: Custom fusion function (future support).

Example: COMBINE RRF 4 WINDOW 40 CONSTANT 1.5

YIELD_SCORE_AS alias-combined-score

assigns an alias to the combined fusion score for use in post-processing operations.

LOAD count field...

specifies which fields to return in the results. The count parameter indicates the number of fields that follow.

Example: LOAD 3 category brand price

GROUPBY count field... REDUCE function...

groups results by specified fields and applies reduction functions. Follows the parameter count convention.

Example: GROUPBY 4 category brand REDUCE 2 COUNT 0

APPLY expression AS field

applies transformations to create new fields. Can reference aliased scores and distances.

Example: APPLY "@vector_distance+@score" AS final_score

SORTBY field [ASC|DESC]

sorts the final results by the specified field in ascending or descending order.

FILTER post-filter-expression

applies final filtering to the fused results after combination and before sorting/limiting.

LIMIT offset num

limits the final results. Default limit is 10 when not specified. The offset parameter is zero-indexed.

PARAMS count key value...

defines parameter substitution for the query. Parameters can be referenced in search expressions using $parameter_name.

Example: PARAMS 4 min_price 50 max_price 200

EXPLAINSCORE

includes detailed score explanations in the results, showing how both text search and vector similarity scores were calculated and combined.

TIMEOUT timeout

sets a runtime timeout for the query execution in milliseconds.

WITHCURSOR [COUNT read_size] [MAXIDLE idle_time]

enables cursor-based result pagination for large result sets. COUNT specifies the batch size, and MAXIDLE sets the cursor timeout.

Default values and behaviors

FT.HYBRID provides sensible defaults to ease onboarding:

  • Query count: 2 (one SEARCH and one VSIM component required)
  • Default LIMIT: 10 results
  • Default SCORER: BM25STD for text search
  • Default KNN K: 10 neighbors
  • Default RRF WINDOW: 20 (or follows LIMIT if specified)
  • Default RRF CONSTANT: 60 (following Elasticsearch convention)
  • Default EF_RUNTIME: 10 (as vector KNN default)
  • Default EPSILON: 0.01 (as the vector RANGE default)

Parameter count convention

All multi-parameter options use a count prefix that contains ALL tokens that follow:

  • KNN 4 K 10 EF_RUNTIME 100 - 2 key-value pairs
  • PARAMS 4 min_price 50 max_price 200 - 2 key-value pairs
  • COMBINE RRF 4 WINDOW 40 CONSTANT 1.5 - RRF method with 2 key-value pairs

The only exception is alias usage with AS, which is not counted:

  • APPLY "@vector_distance+@score" AS final_score
  • LOAD 3 category AS cat brand AS brd price AS prc

Reserved fields

The following fields are reserved for internal use:

  • @__key - reserved for loading key IDs when required
  • @__score - reserved for the combined score (can be aliased)
  • @vector_distance - yields the vector distance (can be aliased)
  • @__combined_score - fused score from the COMBINE step

Examples

Basic hybrid search

Perform a simple hybrid search combining text search for "laptop" with vector similarity:

127.0.0.1:6379> FT.HYBRID products-idx
  SEARCH "laptop"
  VSIM @description_vector $query_vec
  KNN 2 K 10
Hybrid search with custom scoring and fusion

Search for electronics with custom BM25 parameters and RRF fusion:

127.0.0.1:6379> FT.HYBRID products-idx
  SEARCH "@category:electronics"
  SCORER 4 BM25 1.5 0.8
  YIELD_SCORE_AS text_score
  VSIM @features_vector $query_vec
  KNN 4 K 20 EF_RUNTIME 200
  YIELD_DISTANCE_AS vector_dist
  COMBINE RRF 4 WINDOW 50 CONSTANT 80
  YIELD_SCORE_AS hybrid_score
  SORTBY hybrid_score DESC
  LIMIT 0 20
Hybrid search with pre-filtering

Search with vector pre-filtering and post-processing:

127.0.0.1:6379> FT.HYBRID products-idx
  SEARCH "smartphone"
  VSIM @image_vector $query_vec
  KNN 2 K 15
  FILTER "@price:[100 500]"
  COMBINE LINEAR 4 ALPHA 0.7 BETA 0.3
  LOAD 4 title price category rating
  APPLY "@price * 0.9" AS discounted_price
  SORTBY rating DESC
Hybrid search with parameters

Use parameter substitution for dynamic queries:

127.0.0.1:6379> FT.HYBRID products-idx
  SEARCH "@brand:$brand_name"
  VSIM @content_vector $query_vector
  RANGE 4 RADIUS 0.8 EPSILON 0.1
  FILTER "@availability:$stock_status"
  PARAMS 6 brand_name "Apple" query_vector <vector_blob> stock_status "in_stock"
  EXPLAINSCORE

Complexity

FT.HYBRID complexity depends on both the text search and vector similarity components:

  • Text search: O(n) for simple term searches, where n is the number of matching documents. In multi-term queries with INTERSECT or UNION, or when using fuzzy or prefix matches, the complexity increases proportionally to the total number of entries scanned across all participating terms.
  • Vector search: O(log n) for KNN with HNSW index, O(n) for range queries
  • Fusion: O(k) where k is the number of results to combine
  • Overall complexity is typically dominated by the more expensive component

Redis Enterprise and Redis Cloud compatibility

Redis
Enterprise		 Redis
Cloud		 Notes
❌ Standard
❌ Active-Active		 ❌ Standard
❌ Active-Active

Return information

One of the following:

  • Array with the first element being the total number of results, followed by document IDs and their field-value pairs as arrays.
  • Simple error reply in these cases: no such index, syntax error in query.

See also

FT.CREATE | FT.SEARCH | FT.AGGREGATE

RATE THIS PAGE
Back to top ↑