{ "schema_version": 2, "id": "commands/ft.hybrid", "title": "FT.HYBRID", "url": "https://redis.io/docs/latest/commands/ft.hybrid/", "summary": "Performs hybrid search combining text search and vector similarity search", "since": "8.4.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T09:47:58+01:00", "page_type": "content", "content_hash": "61bc4eed1c754d2e388059d657c0496c50b549b03cd531aff02528a58bce5c4e", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Performs hybrid search combining text search and vector similarity with configurable fusion methods.\n\n`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.\n\n> [!NOTE]\n> This command will only return document IDs (`keyid`) and scores to which the user has read access.\n> To retrieve entire documents, use projections with `LOAD *` or `LOAD field...`.\n\n[Examples](#examples)" }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
\nindex\n\nis the name of the index. You must first create the index using [`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create).\n
\n\n
\nSEARCH \"search-expression\"\n\ndefines the text search component of the hybrid query. The search expression uses the same syntax as [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) queries, supporting all text search capabilities including field-specific searches, boolean operations, and phrase matching.\n
\n\n
\nVSIM @vector_field \"vector-data\"\n\ndefines 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 `).\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
\nSCORER algorithm params...\n\nspecifies 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.\n\nExample: `SCORER 4 BM25 1.2 0.75` uses BM25 algorithm with parameters 1.2 and 0.75.\n
\n\n
\nYIELD_SCORE_AS alias-search-score\n\nassigns an alias to the search score for use in post-processing operations like `APPLY` or `SORTBY`.\n
\n\n
\nKNN count K top-k [EF_RUNTIME ef-value] [SHARD_K_RATIO shard-k-ratio] [YIELD_SCORE_AS name]\n\nconfigures 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. `SHARD_K_RATIO` controls the number of results each shard retrieves relative to the requested `top_k` in cluster setups. `YIELD_SCORE_AS` assigns an alias to the score value. See the [vector search](https://redis.io/docs/latest/develop/ai/search-and-query/vectors#cluster-optimization-examples) documentation for more information about `SHARD_K_RATIO`.\n
\n\n
\nRANGE count RADIUS radius-value [EPSILON epsilon-value] [YIELD_SCORE_AS name]\n\nconfigures 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.\n
\n\n
\nFILTER \"filter-expression\"\n\napplies 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`](https://redis.io/docs/latest/commands/ft.search), supporting all text search capabilities including field-specific searches, boolean operations, and phrase matching\n
\n\n
\nPOLICY [ADHOC_BF|BATCHES] [BATCH_SIZE batch-size-value]\n\ncontrols 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](https://redis.io/docs/latest/develop/ai/search-and-query/vectors#filters) for more information.\n
\n\n
\nCOMBINE method params...\n\nspecifies how to fuse the text search and vector similarity results. Supports multiple fusion methods:\n\n- **RRF (Reciprocal Rank Fusion)**: Default method. Parameters include `WINDOW` (default 20) and `CONSTANT` (default 60).\n- **LINEAR**: Linear combination with `ALPHA` and `BETA` weights.\n- **FUNCTION**: Custom fusion function (future support).\n\nExample: `COMBINE RRF 4 WINDOW 40 CONSTANT 1.5`\n
\n\n
\nYIELD_SCORE_AS alias-combined-score\n\nassigns an alias to the combined fusion score for use in post-processing operations.\n
\n\n
\nLOAD count field...\n\nspecifies which fields to return in the results. The `count` parameter indicates the number of fields that follow.\n\nExample: `LOAD 3 @category @brand @price`\n
\n\n
\nGROUPBY count field... REDUCE function...\n\ngroups results by specified fields and applies reduction functions. Follows the parameter count convention. The `count` parameter indicates the number of fields that follow.\n\nExample: `GROUPBY 4 category brand REDUCE 2 COUNT 0`\n
\n\n
\nAPPLY expression AS field\n\napplies transformations to create new fields. Can reference aliased scores and distances.\n\nExample: `APPLY \"@vector_distance+@score\" AS final_score`\n
\n\n
\nSORTBY count field [ASC|DESC]\n\nsorts the final results by the specified field in ascending or descending order. The `count` parameter indicates the number of fields that follow.\n
\n\n\n\n
\nLIMIT offset num\n\nlimits the final results. Default limit is 10 when not specified. The `offset` parameter is zero-indexed.\n
\n\n
\nPARAMS count key value...\n\ndefines parameter substitution for the query. Parameters can be referenced in search expressions using `$parameter_name`.\n\nExample: `PARAMS 4 min_price 50 max_price 200`\n
\n\n\n\n
\nTIMEOUT timeout\n\nsets a runtime timeout for the query execution in milliseconds.\n
" }, { "id": "default-values-and-behaviors", "title": "Default values and behaviors", "role": "content", "text": "FT.HYBRID provides sensible defaults to ease onboarding:\n\n- **Query count**: 2 (one SEARCH and one VSIM component required)\n- **Default LIMIT**: 10 results\n- **Default SCORER**: BM25STD for text search\n- **Default KNN K**: 10 neighbors\n- **Default RRF WINDOW**: 20\n- **Default RRF CONSTANT**: 60\n- **Default EF_RUNTIME**: 10 (as vector KNN [default](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/#hnsw-index))\n- **Default EPSILON**: 0.01 (as the vector RANGE [default](https://redis.io/docs/latest/develop/ai/search-and-query/vectors#hnsw-index))" }, { "id": "parameter-count-convention", "title": "Parameter count convention", "role": "parameters", "text": "All multi-parameter options use a count prefix that contains ALL tokens that follow:\n\n- `KNN 4 K 10 EF_RUNTIME 100` - 2 key-value pairs\n- `PARAMS 4 min_price 50 max_price 200` - 2 key-value pairs\n- `COMBINE RRF 4 WINDOW 40 CONSTANT 1.5` - RRF method with 2 key-value pairs\n\nThe only exception is alias usage with `AS`, which is not counted:\n- `APPLY \"@vector_distance+@score\" AS final_score`\n- `LOAD 3 @category AS cat @brand AS brd @price AS prc`" }, { "id": "reserved-fields", "title": "Reserved fields", "role": "content", "text": "The following fields are reserved for internal use:\n\n- `@__key` - reserved for loading key IDs when required\n- `@__score` - reserved for the combined score (can be aliased)\n- `@vector_distance` - yields the vector distance (can be aliased)\n- `@__combined_score` - fused score from the COMBINE step" }, { "id": "examples", "title": "Examples", "role": "example", "text": "
\nBasic hybrid search\n\nPerform a simple hybrid search combining text search for \"laptop\" with vector similarity:\n\n\n127.0.0.1:6379> FT.HYBRID products-idx\n SEARCH \"laptop\"\n VSIM @description_vector $query_vec\n KNN 2 K 10\n PARAMS 2 query_vec \n\n
\n\n
\nHybrid search with custom scoring and fusion\n\nSearch for electronics with custom BM25 parameters and RRF fusion:\n\n\n127.0.0.1:6379> FT.HYBRID products-idx\n SEARCH \"@category:electronics\"\n SCORER 4 BM25 1.5 0.8\n YIELD_SCORE_AS text_score\n VSIM @features_vector $query_vec\n KNN 4 K 20 EF_RUNTIME 200\n YIELD_SCORE_AS vector_score\n COMBINE RRF 4 WINDOW 50 CONSTANT 80\n YIELD_SCORE_AS hybrid_score\n SORTBY 2 hybrid_score DESC\n LIMIT 0 20\n PARAMS 2 query_vec \n\n
\n\n
\nHybrid search with pre-filtering\n\nSearch with vector pre-filtering and post-processing:\n\n\n127.0.0.1:6379> FT.HYBRID products-idx\n SEARCH \"smartphone\"\n VSIM @image_vector $query_vec\n KNN 2 K 15\n FILTER \"@price:[100 500]\"\n COMBINE LINEAR 4 ALPHA 0.7 BETA 0.3\n LOAD 4 @title @price @category @rating\n APPLY \"@price * 0.9\" AS discounted_price\n SORTBY 2 rating DESC\n PARAMS 2 query_vec \n\n
\n\n
\nHybrid search with parameters\n\nUse parameter substitution for dynamic queries:\n\n\n127.0.0.1:6379> FT.HYBRID products-idx\n SEARCH \"@brand:$brand_name\"\n VSIM @content_vector $query_vector\n RANGE 4 RADIUS 0.8 EPSILON 0.1\n FILTER \"@availability:$stock_status\"\n PARAMS 6 brand_name \"Apple\" query_vector stock_status \"in_stock\"\n\n
" }, { "id": "complexity", "title": "Complexity", "role": "performance", "text": "FT.HYBRID complexity depends on both the text search and vector similarity components:\n- 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.\n- Vector search: O(log n) for KNN with HNSW index, O(n) for range queries\n- Fusion: O(k) where k is the number of results to combine\n- Overall complexity is typically dominated by the more expensive component" }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nOne of the following:\n* [Array](https://redis.io/docs/latest/develop/reference/protocol-spec#arrays) with the first element being the total number of results, followed by document IDs and their field-value pairs as [arrays](https://redis.io/docs/latest/develop/reference/protocol-spec#arrays).\n* [Simple error reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-errors) in these cases: no such index, syntax error in query.\n\n**RESP3:**\n\nOne of the following:\n* [Map](https://redis.io/docs/latest/develop/reference/protocol-spec#maps) with the following fields:\n - `total_results`: [Integer](https://redis.io/docs/latest/develop/reference/protocol-spec#integers) - total number of results\n - `execution_time`: [double](https://redis.io/docs/latest/develop/reference/protocol-spec#doubles) containing hybrid query execution time\n - `warnings`: [Array](https://redis.io/docs/latest/develop/reference/protocol-spec#arrays) of warning messages indicating partial results due to index errors or `MAXPREFIXEXPANSIONS`, out-of-memory conditions, and `TIMEOUT` reached\n - `results`: [Array](https://redis.io/docs/latest/develop/reference/protocol-spec#arrays) of [maps](https://redis.io/docs/latest/develop/reference/protocol-spec#maps) containing document information\n* [Simple error reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-errors) in these cases: no such index, syntax error in query." }, { "id": "see-also", "title": "See also", "role": "related", "text": "[`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create) | [`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search) | [`FT.AGGREGATE`](https://redis.io/docs/latest/commands/ft.aggregate)" }, { "id": "related-topics", "title": "Related topics", "role": "related", "text": "- [Vector search concepts](https://redis.io/docs/latest/develop/ai/search-and-query/vectors)\n- [Combined search](https://redis.io/docs/latest/develop/ai/search-and-query/query/combined)\n- [Search commands in MULTI/EXEC transactions and Lua scripts](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/transactions)" } ], "examples": [] }