Initial Hybrid Search (FT.HYBRID) bindings #454

mgravell · 2025-11-12T14:33:16Z

tasks:

primary API is new HybridSearchResult ISearchCommands.HybridSearch((string indexName, HybridSearchQuery query, IReadOnlyDictionary<string, object>? parameters) API (and Async twin).

Note that because FT.HYBRID supports parameterization in both the queries and the filters, I have deviated from the pattern for FT.SEARCH, in that the parameters are specified separately to the query. This means that a single query instance can be created and stored, then reused repeatedly with different values. To avoid concurrency concerns, "popsicle immutability" is used in the query object, becoming automatically frozen when issued. For convenience, a secondary type-based API is presented to allow parameters from, for example, anonymous types.

HybridSearchQuery acts as a builder, so:

var query = new HybridSearchQuery().Search("text part").VectorSearch("@vectorField", vectorData);
var result = ft.HybridSearch("myIndex", query);

However, a full API for the supported server features is available, for example:

var query = new HybridSearchQuery()
            .Search(new("foo", Scorer.BM25StdTanh(5), "text_score_alias"))
            .VectorSearch(new HybridSearchQuery.VectorSearchConfig("bar", new float[] { 1, 2, 3 },
                    VectorSearchMethod.NearestNeighbour(10, 100, "vector_distance_alias"))
                .WithFilter("@foo:bar").WithScoreAlias("vector_score_alias"))
            .Combine(HybridSearchQuery.Combiner.ReciprocalRankFusion(10, 0.5), "my_combined_alias")
            .ReturnFields("field1", "field2")
            .GroupBy("field1").Reduce(Reducers.Quantile("@field3", 0.5).As("reducer_alias"))
            .Apply(new("@field1 + @field2", "apply_alias"))
            .SortBy(SortedField.Asc("field1"), SortedField.Desc("field2"))
            .Filter("@field1:bar")
            .Limit(12, 54)
            .ExplainScore()
            .Timeout()

var args = Parameters.From(new { x = 12, y = "abc" });
var results = ft.HybridSearch(query, args);

To complement this, we introduce some additional additional types; the types specific to hybrid-search are mostly inside NRedisStack.Search.HybridSearchQuery; the types that are also conceptually wider to all of search are in NRedisStack.Search.

NRedisStack.Search.ApplyExpression - immutable readonly struct tuple of string expression and string? alias - NRedisStack.Search.Scorer - immutable class, private subtypes for TFIDF, BM25STD, etc from https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/scoring/
NRedisStack.Search.VectorData - abstracts over ways of representing vector data; readonly struct
NRedisStack.Search.HybridSearchQuery - the new builder API
NRedisStack.Search.HybridSearchQuery - the new result API
NRedisStack.Search.HybridSearchQuery.Combiner - immutable class, private subtypes for RRD and linear combiners
NRedisStack.Search.HybridSearchQuery.SearchConfig - immutable readonly struct describing a text search with scorer and alias
NRedisStack.Search.HybridSearchQuery.VectorSearchConfig - immutable readonly struct describing a vector search with method, filter, alias
NRedisStack.Search.VectorSearchMethod - immutable class, private subtypes for "nearest neighbour", "range", etc
NRedisStack.Search.Parameters - allows objects to be used as parameter sources

At the moment VectorData only supports ROM<float> (float[]), in line with SE.Redis VSIM support, but we can extend this as necessary.

To make working with vector data more convenient, a new VectorData API is added, with use-cases:

var vec = VectorData.Raw(blob); - raw handling, owner handles lifetime
var vec = VectorData.Parameter(name); - vector deferred to the parameters collection
using var vec = VectorData.Lease<Half>(20); - lease a vector backed by raw bytes, interpreted as Half, with .Span a convenience accessor
using var vec = VectorData.LeaseWithValues(...) - like Lease, but inferring type and dimension from the supplied payload, which becomes the initial payload

There is no quantization etc; the caller is required to understand their vector type and send the values appropriately, but this is hopefully a little easier than making the consumer responsible for the byte shunt.

Note that in all cases, the vector is passed in PARAMS to prevent $ ambiguity, and to pre-empt future server API changes here.

The new APIs are marked [Experimental], pointing people to (when merged) a portal with the contents from https://github.com/redis/NRedisStack/blob/9548d539ff72ac370c7c0706e8e9c53b8492f1b3/docs/exp/NRS001.md

API note: the significance of With* in the VectorSearchConfig and SearchConfig is that these are "withers", i.e. while it is a fluent API, the underlying type is immutable, so this returns a different instance (in this case, of a value-type). This contrasts with the HybridSearchQuery which pairs with SearchQuery in exposing a mutable fluent API, where each method ends return this.

Note that this also includes a fix for #453

atakavci

other than a couple of questions and small details, looks pretty good to me.

atakavci · 2025-11-24T11:43:27Z

docs/exp/NRS001.md

@@ -0,0 +1,22 @@
+Redis 8.4 is currently in preview and may be subject to change.
+
+*Hybrid Search* is a new feature in Redis 8.4 that allows you to search across multiple indexes and data types.


multiple indexes

needs small change with wording.

atakavci · 2025-11-25T07:47:29Z

src/NRedisStack/Search/HybridSearchQuery.Combiner.cs

+            }
+        }
+
+        private sealed class LinearCombiner : Combiner


WINDOW is missing with LinearCombiner.
https://redis.io/docs/latest/commands/ft.hybrid/

atakavci · 2025-11-25T07:49:24Z

src/NRedisStack/Search/HybridSearchQuery.Combiner.cs

+
+public sealed partial class HybridSearchQuery
+{
+    public abstract class Combiner


why YIELD_SCORE_AS is left out?

the server doesn't implement this yet

atakavci · 2025-11-25T08:03:58Z

src/NRedisStack/Search/HybridSearchQuery.cs

+    /// <summary>
+    /// Configure the score fusion method (optional). If not provided, Reciprocal Rank Fusion (RRF) is used with server-side default parameters.
+    /// </summary>
+    internal HybridSearchQuery Combine(Combiner combiner, string scoreAlias) // YIELD_SCORE_AS not yet implemented


a bit confused, the comment on YIELD_SCORE_AS is a left over?

the server doesn't implement this yet

atakavci · 2025-11-25T08:38:11Z

src/NRedisStack/Search/HybridSearchQuery.cs

+    /// <summary>
+    /// Add the list of fields to return in the results. Well-known fields are available via <see cref="Fields"/>.
+    /// </summary>
+    public HybridSearchQuery ReturnFields(string field) // naming for consistency with SearchQuery


is this just to avoid array allocation for single item?

Yes, basically

atakavci · 2025-11-25T08:52:46Z

src/NRedisStack/OverloadResolutionPriorityAttribute.cs

+
+#if !NET9_0_OR_GREATER
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+internal sealed class OverloadResolutionPriorityAttribute(int priority) : Attribute


no use of this.

will remove; there was at some point

atakavci · 2025-11-25T09:05:05Z

src/NRedisStack/Search/HybridSearchQuery.Command.cs

+                    }
+                    break;
+            }
+            static int CountReducer(Reducer reducer) => 3 + reducer.ArgCount() + (reducer.Alias is null ? 0 : 2);


is there a way to make these calculations easier to maintain (or self explaning)?
feels like these expressions could get confusing quickly in between command syntax changes in time.

atakavci · 2025-11-25T09:33:33Z

src/NRedisStack/Search/HybridSearchQuery.cs

+/// common queries, by passing the search operands as named parameters.
+/// </summary>
+[Experimental(Experiments.Server_8_4, UrlFormat = Experiments.UrlFormat)]
+public sealed partial class HybridSearchQuery


lets put it explicitly that class is not thread-safe and not ready to use by multiple threads with as is condition.

mgravell added 7 commits November 10, 2025 17:06

in-progress hybrid search

d4f803e

preliminary API and final unit tests (no integration tests yet)

4e66b5a

push docs

6b531df

start integration tests

9128f9f

tweaking API

6141c16

refactor API and deal with missing server features

c736263

mask cursor API, unclear

4f32325

mgravell marked this pull request as draft November 12, 2025 14:33

mgravell added 22 commits November 12, 2025 14:49

normalize API

9548d53

rev local docker and mark docs as non-packable

8cc5ff2

dotnet format

752c65f

better support for vector data

98fab2b

dotnet format

5d795b6

naming is hard

83a2547

implement NOSORT

f262659

move parameters back to to method, not the builder

7c7d7fd

push all the changes

c992d83

more working-esque integration tests

7ebee4f

parse search results correctly

6bc9d55

integration tests

ef57889

pre-vs-post-filter

876adfb

attr

b89e990

update client docker

f775add

fix HC unit tests

d48818b

updating 8.4 state

cfe9ed6

format and fixups

0c19979

VectorData; make API usable

62a5ee7

ensure integration tests use the VectorData API

c310c6a

force VSIM payloads as vectors, unless named

55f958c

dotnet format

d1e7e35

atakavci reviewed Nov 25, 2025

View reviewed changes

		@@ -0,0 +1,22 @@
		Redis 8.4 is currently in preview and may be subject to change.

		Hybrid Search is a new feature in Redis 8.4 that allows you to search across multiple indexes and data types.

Initial Hybrid Search (FT.HYBRID) bindings #454

Are you sure you want to change the base?

Initial Hybrid Search (FT.HYBRID) bindings #454

Uh oh!

Conversation

mgravell commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

atakavci left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mgravell commented Nov 12, 2025 •

edited

Loading