FT.HYBRID

Performs hybrid search combining text search and vector similarity search

Browse all commands · Upstream source documentation

Reference field	Value
Canonical name	`FT.HYBRID`
Catalog group	Search commands
Upstream since	8.4.0 — upstream Redis/module version, not an ffkv release
Pinned catalog	Redis 8.10.0

Syntax

FT.HYBRID index
  SEARCH query
    [SCORER scorer]
    [YIELD SCORE AS name]
  VSIM vector field $vector param
    [KNN count K k [EF RUNTIME ef runtime]] [SHARD K RATIO shard k ratio]]
    [RANGE count RADIUS radius [EPSILON epsilon]]
    [YIELD SCORE AS name]
    [FILTER] count filter-expression [POLICY [ADHOC/BATCHES] BATCH SIZE batch-size-value]
  [COMBINE RRF count [CONSTANT constant] [WINDOW window] [YIELD SCORE AS name]]
  [COMBINE LINEAR count [[ALPHA alpha] [BETA beta]] [WINDOW window] [YIELD SCORE AS name]]
  [LIMIT offset num]
  [SORTBY count sortby [ASC | DESC]]
  [NOSORT]
  [LOAD count field [field ...]]
  [LOAD *]
  [GROUPBY nargs property [property ...]
  [GROUPBY nargs property [property ...]
    [REDUCE function nargs arg [arg ...] [AS name]
    [REDUCE function nargs arg [arg ...] [AS name] ...]] ...]]
  [APPLY expression AS name [APPLY expression AS name ...]]
  [FILTER filter]
  PARAMS nargs vector param vector blob [name value ...]
  [TIMEOUT timeout]

ffkv behavior and limits

Search worker configuration controls a real Rayon pool; GC schedules generation-fenced Rust compaction, not a POSIX fork. Search indexes and documents are bounded and RAM-resident; upstream syntax is not a promise of every option combination or Redis module ABI parity.

Source: README.md:375–377, 636–642; src/engine/search/; tests/bdd/features/search.feature.

All requests share the 8 MiB framing/1,024-argument ingress limit; normal RESP replies have 64 MiB wire/logical budgets with bounded nesting/value counts. Management and Lua origins impose smaller budgets. These are not a process RSS cap. Catalog inclusion is not exhaustive option or wire-format parity. See limits and compatibility.

Metadata availability

This command is in the canonical catalog but has no matching entry in the pinned src/command_metadata.json. Argument flags, complexity and key specifications are not invented. Use the syntax, upstream source documentation and actual scenario evidence below.

BDD coverage and source examples

These are source observations, not a test run performed by this documentation build. A tag identifies scenario intent; an extracted vector identifies a command invocation, which may intentionally produce an error. Scenarios may require setup, multiple connections, persistence, cluster nodes or native-module fixtures.

Reciprocal-rank fusion combines the union of text and vector branches — tests/bdd/features/search.feature:726; command tag and invocation observed.
Invalid query schema and pipeline options fail without document mutation (Scenario Outline) — tests/bdd/features/search.feature:1027; command tag and invocation observed.

Extracted command vectors

The following JSON arrays are the test harness’s argument vectors, not shell commands. Numeric arguments are converted by the harness; objects of the form {"base64":"…"} represent decoded binary bytes, not a literal JSON command argument. Preserve scenario setup and connection ordering. See the CLI guide for shell quoting and binary stdin. No reply is invented or inferred.

Reciprocal-rank fusion combines the union of text and vector branches — tests/bdd/features/search.feature:732 (I execute:)

Binary payload: decode the base64 object to bytes using a client API or binary stdin; do not send the base64 text as the value.

[
  "FT.HYBRID",
  "idx",
  "SEARCH",
  "rare",
  "SCORER",
  "DOCSCORE",
  "VSIM",
  "@v",
  "$q",
  "KNN",
  "2",
  "K",
  "2",
  "COMBINE",
  "RRF",
  "2",
  "CONSTANT",
  "60",
  "PARAMS",
  "2",
  "q",
  {
    "base64": "AAAAAAAAAAA="
  },
  "LIMIT",
  "0",
  "10"
]

Next source assertion: the reply contains:

["total_results",3,[["__key","doc:both","__score",{"$approx":{"value":0.03278688524590164,"abs":1e-12}}],["__key","doc:text"],["__key","doc:vector"]]]

Invalid query schema and pipeline options fail without document mutation — tests/bdd/features/search.feature:1033 (I execute:)

Expanded from an actual Examples row: command=["FT.HYBRID","idx","SEARCH","safe","VSIM","v","$q","PARAMS",2,"q","bad"].

[
  "FT.HYBRID",
  "idx",
  "SEARCH",
  "safe",
  "VSIM",
  "v",
  "$q",
  "PARAMS",
  2,
  "q",
  "bad"
]

Next source assertion: the reply is an error with code “ERR”

Reciprocal-rank fusion combines the union of text and vector branches — tests/bdd/features/search.feature:740 (I execute:)

Binary payload: decode the base64 object to bytes using a client API or binary stdin; do not send the base64 text as the value.

[
  "FT.HYBRID",
  "idx",
  "SEARCH",
  "rare",
  "SCORER",
  "DOCSCORE",
  "VSIM",
  "@v",
  "$q",
  "KNN",
  "2",
  "K",
  "2",
  "COMBINE",
  "RRF",
  "2",
  "CONSTANT",
  "60",
  "PARAMS",
  "2",
  "q",
  {
    "base64": "AAAAAAAAAAA="
  },
  "GROUPBY",
  "0",
  "REDUCE",
  "COUNT",
  "0",
  "AS",
  "count"
]

Next source assertion: the reply contains:

["total_results",1,[["count",{"$approx":3}]]]