feat(query): add HybridQuery for FT.HYBRID server-side fusion

[banker]

Adds HybridQuery and SearchIndex.hybridSearch() that delegate text+vector score fusion entirely to Redis via the FT.HYBRID command (introduced in Redis OSS 8.4.0). Unlike Python redisvl's HybridQuery — which issues two queries client-side and fuses ranks itself — this implementation runs as a single round-trip with server-side RRF or LINEAR fusion.

The new method is separate from index.search() because FT.HYBRID has its own command, options shape, and reply format. HybridSearchResult extends SearchResult with executionTime and warnings fields.

Notable behaviours:

• text + textFieldName triggers tokenize + escape + OR-join. Omitting textFieldName passes the body through verbatim so power users can use full Redis Search syntax.
• vsimFilter is a raw string in the FT.SEARCH filter dialect (e.g. '@brand:{nike}'). postFilter is a raw string in the FT.AGGREGATE expression dialect (e.g. '@price < 200'). The two clauses use different syntaxes server-side.
• LOAD always includes @__key so doc.id round-trips. Score aliases set via YIELD_SCORE_AS are not added to LOAD — Redis already injects them, and re-loading triggers "score alias already exists" errors.
• LOAD/SORTBY field references are auto-prefixed with @ when the user passes bare names; explicit @ or $.path prefixes are preserved.
• Testcontainer image bumped from redis:8.0 to redis:8.4 for FT.HYBRID support.

Marked @experimental in JSDoc since the underlying client.ft.hybrid() is itself flagged experimental in @redis/search.

Tests: 38 unit tests asserting toCommand() output for representative configs (KNN/RANGE methods, RRF/LINEAR fusion, score aliases, LOAD prefixing, SORTBY, NOSORT, postFilter, TIMEOUT) plus 7 integration tests against a real Redis 8.4 Testcontainer covering each fusion method, each vector method, vsimFilter, postFilter, verbatim text body, and LIMIT.

[banker]

Note: latest commit will close #20

[nkanu17]

Addressed the hybrid review pass in b7b087e.
Changes:

• Always emits a default RRF COMBINE with YIELD_SCORE_AS so default HybridQuery results have a stable combined score alias.
• Keeps result mapping defensive by falling back to Redis default score keys if present.
• Adds runtime validation for numResults, offset, timeout, textFieldName, returnFields, sortBy, and noSort/sortBy conflicts.
• Restores the main CI matrix to Redis Stack latest + 7.4.0-v8, and adds a separate Redis 8.4 HybridQuery job for FT.HYBRID coverage.

Verification run locally:

• npm run type-check
• npm run test:unit
• npm test -- tests/integration/hybrid-search.test.ts
• REDISVL_SKIP_HYBRID=true npm test -- tests/integration/hybrid-search.test.ts
• npm run build

[ymendez-redis]

Shall I add the search stopwords or is this not in scope yet?

[Copilot]

Pull request overview

Adds first-class hybrid (text + vector) search support to the library by introducing a HybridQuery builder and SearchIndex.hybridSearch() that execute Redis’ FT.HYBRID for server-side fusion (RRF/LINEAR) in a single round trip, along with docs and CI/test updates for Redis 8.4 compatibility.

Changes:

• Introduce HybridQuery (FT.HYBRID command builder) and SearchIndex.hybridSearch() result mapping (HybridSearchResult).
• Add unit + integration test coverage for command generation and Redis 8.4 execution.
• Add user-guide documentation + sidebar entry; update CI and local Testcontainers Redis image to support FT.HYBRID.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/sidebars.ts	Adds the Hybrid Search page to the user guide sidebar.
website/docs/user-guide/hybrid-search.md	New Hybrid Search documentation and examples for HybridQuery / hybridSearch().
tests/unit/query/hybrid.test.ts	Unit tests validating HybridQuery config validation and toCommand() output.
tests/integration/hybrid-search.test.ts	Integration tests against Redis 8.4+ for FT.HYBRID behavior.
tests/global-setup.ts	Bumps default Testcontainers Redis image to 8.4 (env-overridable).
src/query/index.ts	Re-exports the new hybrid query module.
src/query/hybrid.ts	Implements HybridQuery, validation, and FT.HYBRID option construction.
src/query/base.ts	Adds HybridSearchResult<T> interface.
src/indexes/search-index.ts	Adds hybridSearch() and FT.HYBRID row mapping to SearchDocument.
src/index.ts	Public exports for HybridQuery types and HybridSearchResult.
.github/workflows/test.yml	Skips hybrid integration tests in Redis Stack matrix and adds dedicated Redis 8.4 job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

website/docs/user-guide/hybrid-search.md:272

• This snippet imports from 'redisvl', but the package name used throughout the docs/repo is 'redis-vl'. Update the import so the example can be copied/pasted successfully.

```typescript
import { HybridQuery, HuggingFaceVectorizer } from 'redisvl';