feat(command): Add hybrid search command

search_commands.go

@@ -29,6 +29,8 @@ type SearchCmdable interface {
 	FTDropIndexWithArgs(ctx context.Context, index string, options *FTDropIndexOptions) *StatusCmd
 	FTExplain(ctx context.Context, index string, query string) *StringCmd
 	FTExplainWithArgs(ctx context.Context, index string, query string, options *FTExplainOptions) *StringCmd
+	FTHybrid(ctx context.Context, index string, searchExpr string, vectorField string, vectorData Vector) *FTHybridCmd
+	FTHybridWithArgs(ctx context.Context, index string, options *FTHybridOptions) *FTHybridCmd
 	FTInfo(ctx context.Context, index string) *FTInfoCmd
 	FTSpellCheck(ctx context.Context, index string, query string) *FTSpellCheckCmd
 	FTSpellCheckWithArgs(ctx context.Context, index string, query string, options *FTSpellCheckOptions) *FTSpellCheckCmd
@@ -344,6 +346,85 @@ type FTSearchOptions struct {
 	DialectVersion int
 }
 
+// FTHybridCombineMethod represents the fusion method for combining search and vector results
+type FTHybridCombineMethod string
+
+const (
+	FTHybridCombineRRF      FTHybridCombineMethod = "RRF"
+	FTHybridCombineLinear   FTHybridCombineMethod = "LINEAR"
+	FTHybridCombineFunction FTHybridCombineMethod = "FUNCTION"
+)
+
+// FTHybridSearchExpression represents a search expression in hybrid search
+type FTHybridSearchExpression struct {
+	Query        string
+	Scorer       string
+	ScorerParams []interface{}
+	YieldScoreAs string
+}
+
+// FTHybridVectorExpression represents a vector expression in hybrid search
+type FTHybridVectorExpression struct {
+	VectorField  string
+	VectorData   Vector
+	Method       string // KNN or RANGE
+	MethodParams []interface{}
+	Filter       string
+	YieldScoreAs string
+}
+
+// FTHybridCombineOptions represents options for result fusion
+type FTHybridCombineOptions struct {
+	Method       FTHybridCombineMethod
+	Count        int
+	Window       int     // For RRF
+	Constant     float64 // For RRF
+	Alpha        float64 // For LINEAR
+	Beta         float64 // For LINEAR
+	YieldScoreAs string
+}
+
+// FTHybridGroupBy represents GROUP BY functionality
+type FTHybridGroupBy struct {
+	Count        int
+	Fields       []string
+	ReduceFunc   string
+	ReduceCount  int
+	ReduceParams []interface{}
+}
+
+// FTHybridApply represents APPLY functionality
+type FTHybridApply struct {
+	Expression string
+	AsField    string
+}
+
+// FTHybridWithCursor represents cursor configuration for hybrid search
+type FTHybridWithCursor struct {
+	Count   int // Number of results to return per cursor read
+	MaxIdle int // Maximum idle time in milliseconds before cursor is automatically deleted
+}
+
+// FTHybridOptions hold options that can be passed to the FT.HYBRID command
+type FTHybridOptions struct {
+	CountExpressions  int                        // Number of search/vector expressions
+	SearchExpressions []FTHybridSearchExpression // Multiple search expressions
+	VectorExpressions []FTHybridVectorExpression // Multiple vector expressions
+	Combine           *FTHybridCombineOptions    // Fusion step options
+	Load              []string                   // Projected fields
+	GroupBy           *FTHybridGroupBy           // Aggregation grouping
+	Apply             []FTHybridApply            // Field transformations
+	SortBy            []FTSearchSortBy           // Reuse from FTSearch
+	Filter            string                     // Post-filter expression
+	LimitOffset       int                        // Result limiting
+	Limit             int
+	Params            map[string]interface{} // Parameter substitution
+	ExplainScore      bool                   // Include score explanations
+	Timeout           int                    // Runtime timeout
+	WithCursor        bool                   // Enable cursor support for large result sets
+	WithCursorOptions *FTHybridWithCursor    // Cursor configuration options
+}
+
 type FTSynDumpResult struct {
 	Term     string
 	Synonyms []string
@@ -1819,6 +1900,66 @@ func (cmd *FTSearchCmd) readReply(rd *proto.Reader) (err error) {
 	return nil
 }
 
+// FTHybridResult represents the result of a hybrid search operation
+type FTHybridResult = FTSearchResult
+
+type FTHybridCmd struct {
+	baseCmd
+	val     FTHybridResult
+	options *FTHybridOptions
+}
+
+func newFTHybridCmd(ctx context.Context, options *FTHybridOptions, args ...interface{}) *FTHybridCmd {
+	return &FTHybridCmd{
+		baseCmd: baseCmd{
+			ctx:  ctx,
+			args: args,
+		},
+		options: options,
+	}
+}
+
+func (cmd *FTHybridCmd) String() string {
+	return cmdString(cmd, cmd.val)
+}
+
+func (cmd *FTHybridCmd) SetVal(val FTHybridResult) {
+	cmd.val = val
+}
+
+func (cmd *FTHybridCmd) Result() (FTHybridResult, error) {
+	return cmd.val, cmd.err
+}
+
+func (cmd *FTHybridCmd) Val() FTHybridResult {
+	return cmd.val
+}
+
+func (cmd *FTHybridCmd) RawVal() interface{} {
+	return cmd.rawVal
+}
+
+func (cmd *FTHybridCmd) RawResult() (interface{}, error) {
+	return cmd.rawVal, cmd.err
+}
+
+func (cmd *FTHybridCmd) readReply(rd *proto.Reader) (err error) {
+	data, err := rd.ReadSlice()
+	if err != nil {
+		return err
+	}
+	// Parse hybrid search results similarly to FT.SEARCH
+	// We can reuse the FTSearch parser since the result format should be similar
+	searchResult, err := parseFTSearch(data, false, true, false, false)
+	if err != nil {
+		return err
+	}
+
+	// FTSearchResult and FTHybridResult are aliases
+	cmd.val = searchResult
+	return nil
+}
+
 // FTSearch - Executes a search query on an index.
 // The 'index' parameter specifies the index to search, and the 'query' parameter specifies the search query.
 // For more information, please refer to the Redis documentation about [FT.SEARCH].
@@ -2191,3 +2332,190 @@ func (c cmdable) FTTagVals(ctx context.Context, index string, field string) *Str
 	_ = c(ctx, cmd)
 	return cmd
 }
+
+// FTHybrid - Executes a hybrid search combining full-text search and vector similarity
+// The 'index' parameter specifies the index to search, 'searchExpr' is the search query,
+// 'vectorField' is the name of the vector field, and 'vectorData' is the vector to search with.
+func (c cmdable) FTHybrid(ctx context.Context, index string, searchExpr string, vectorField string, vectorData Vector) *FTHybridCmd {
+	options := &FTHybridOptions{
+		CountExpressions: 2,
+		SearchExpressions: []FTHybridSearchExpression{
+			{Query: searchExpr},
+		},
+		VectorExpressions: []FTHybridVectorExpression{
+			{VectorField: vectorField, VectorData: vectorData},
+		},
+	}
+	return c.FTHybridWithArgs(ctx, index, options)
+}
+
+// FTHybridWithArgs - Executes a hybrid search with advanced options
+func (c cmdable) FTHybridWithArgs(ctx context.Context, index string, options *FTHybridOptions) *FTHybridCmd {
+	args := []interface{}{"FT.HYBRID", index}
+
+	if options != nil {
+		// Add count expressions if specified
+		if options.CountExpressions > 0 {
+			args = append(args, options.CountExpressions)
+		} else {
+			// Default to 2 expressions (1 search + 1 vector)
+			args = append(args, 2)
+		}
+
+		// Add search expressions
+		for _, searchExpr := range options.SearchExpressions {
+			args = append(args, "SEARCH", searchExpr.Query)
+
+			if searchExpr.Scorer != "" {
+				args = append(args, "SCORER", searchExpr.Scorer)
+				if len(searchExpr.ScorerParams) > 0 {
+					args = append(args, searchExpr.ScorerParams...)
+				}
+			}
+
+			if searchExpr.YieldScoreAs != "" {
+				args = append(args, "YIELD_SCORE_AS", searchExpr.YieldScoreAs)
+			}
+		}
+
+		// Add vector expressions
+		for _, vectorExpr := range options.VectorExpressions {
+			args = append(args, "VSIM", "@"+vectorExpr.VectorField)
+			args = append(args, vectorExpr.VectorData.Value()...)
+
+			if vectorExpr.Method != "" {
+				args = append(args, vectorExpr.Method)
+				if len(vectorExpr.MethodParams) > 0 {
+					args = append(args, vectorExpr.MethodParams...)
+				}
+			}
+
+			if vectorExpr.Filter != "" {
+				args = append(args, "FILTER", vectorExpr.Filter)
+			}
+
+			if vectorExpr.YieldScoreAs != "" {
+				args = append(args, "YIELD_SCORE_AS", vectorExpr.YieldScoreAs)
+			}
+		}
+
+		// Add combine/fusion options
+		if options.Combine != nil {
+			args = append(args, "COMBINE", string(options.Combine.Method))
+
+			if options.Combine.Count > 0 {
+				args = append(args, options.Combine.Count)
+			}
+
+			switch options.Combine.Method {
+			case FTHybridCombineRRF:
+				if options.Combine.Window > 0 {
+					args = append(args, "WINDOW", options.Combine.Window)
+				}
+				if options.Combine.Constant > 0 {
+					args = append(args, "CONSTANT", options.Combine.Constant)
+				}
+			case FTHybridCombineLinear:
+				if options.Combine.Alpha > 0 {
+					args = append(args, "ALPHA", options.Combine.Alpha)
+				}
+				if options.Combine.Beta > 0 {
+					args = append(args, "BETA", options.Combine.Beta)
+				}
+			}
+
+			if options.Combine.YieldScoreAs != "" {
+				args = append(args, "YIELD_SCORE_AS", options.Combine.YieldScoreAs)
+			}
+		}
+
+		// Add LOAD (projected fields)
+		if len(options.Load) > 0 {
+			args = append(args, "LOAD", len(options.Load))
+			for _, field := range options.Load {
+				args = append(args, field)
+			}
+		}
+
+		// Add GROUPBY
+		if options.GroupBy != nil {
+			args = append(args, "GROUPBY", options.GroupBy.Count)
+			for _, field := range options.GroupBy.Fields {
+				args = append(args, field)
+			}
+			if options.GroupBy.ReduceFunc != "" {
+				args = append(args, "REDUCE", options.GroupBy.ReduceFunc, options.GroupBy.ReduceCount)
+				args = append(args, options.GroupBy.ReduceParams...)
+			}
+		}
+
+		// Add APPLY transformations
+		for _, apply := range options.Apply {
+			args = append(args, "APPLY", apply.Expression, "AS", apply.AsField)
+		}
+
+		// Add SORTBY
+		if len(options.SortBy) > 0 {
+			args = append(args, "SORTBY", len(options.SortBy))
+			for _, sortBy := range options.SortBy {
+				args = append(args, sortBy.FieldName)
+				if sortBy.Asc && sortBy.Desc {
+					cmd := newFTHybridCmd(ctx, options, args...)
+					cmd.SetErr(fmt.Errorf("FT.HYBRID: ASC and DESC are mutually exclusive"))
+					return cmd
+				}
+				if sortBy.Asc {
+					args = append(args, "ASC")
+				}
+				if sortBy.Desc {
+					args = append(args, "DESC")
+				}
+			}
+		}
+
+		// Add FILTER (post-filter)
+		if options.Filter != "" {
+			args = append(args, "FILTER", options.Filter)
+		}
+
+		// Add LIMIT
+		if options.LimitOffset >= 0 && options.Limit > 0 || options.LimitOffset > 0 && options.Limit == 0 {
+			args = append(args, "LIMIT", options.LimitOffset, options.Limit)
+		}
+
+		// Add PARAMS
+		if len(options.Params) > 0 {
+			args = append(args, "PARAMS", len(options.Params)*2)
+			for key, value := range options.Params {
+				args = append(args, key, value)
+			}
+		}
+
+		// Add EXPLAINSCORE
+		if options.ExplainScore {
+			args = append(args, "EXPLAINSCORE")
+		}
+
+		// Add TIMEOUT
+		if options.Timeout > 0 {
+			args = append(args, "TIMEOUT", options.Timeout)
+		}
+
+		// Add WITHCURSOR support
+		if options.WithCursor {
+			args = append(args, "WITHCURSOR")
+			if options.WithCursorOptions != nil {
+				if options.WithCursorOptions.Count > 0 {
+					args = append(args, "COUNT", options.WithCursorOptions.Count)
+				}
+				if options.WithCursorOptions.MaxIdle > 0 {
+					args = append(args, "MAXIDLE", options.WithCursorOptions.MaxIdle)
+				}
+			}
+		}
+	}
+
+	cmd := newFTHybridCmd(ctx, options, args...)
+	_ = c(ctx, cmd)
+	return cmd
+}