Package com.redis.vl.query

Class HybridQuery

java.lang.Object
com.redis.vl.query.HybridQuery
public final class HybridQuery extends Object
HybridQuery combines text and vector search using the native Redis FT.HYBRID command.

Ported from Python: redisvl/query/hybrid.py (HybridQuery class)

This query uses the native FT.HYBRID command available in Redis 8.4+ which provides built-in score fusion via RRF (Reciprocal Rank Fusion) or LINEAR combination methods. This is the recommended approach for hybrid search on Redis 8.4+.

For older Redis versions (7.4+) that use FT.AGGREGATE with manual score fusion, see AggregateHybridQuery.

Alpha Semantics: In this class, linearAlpha represents the text weight in the LINEAR combiner (matching the Python convention). This differs from AggregateHybridQuery where alpha represents the vector weight. The different parameter names prevent confusion.

Python equivalent: 

 query = HybridQuery(
     text="example text",
     text_field_name="text_field",
     vector=[0.1, 0.2, 0.3],
     vector_field_name="vector_field",
     text_scorer="BM25STD",
     combination_method="RRF",
     num_results=10,
 )
 results = index.query(query)

Java equivalent: 

 HybridQuery query = HybridQuery.builder()
     .text("example text")
     .textFieldName("text_field")
     .vector(new float[]{0.1f, 0.2f, 0.3f})
     .vectorFieldName("vector_field")
     .textScorer("BM25STD")
     .combinationMethod(CombinationMethod.RRF)
     .numResults(10)
     .build();
 List<Map<String, Object>> results = index.query(query);

This class is final to prevent finalizer attacks, as it throws exceptions in constructors for input validation (SEI CERT OBJ11-J).

Since:
0.2.0

  • Method Details

    • builder

      public static HybridQuery.HybridQueryBuilder builder()

    • loadDefaultStopwords

      public static Set<String> loadDefaultStopwords(String language)

    • getText

      public String getText()

    • getTextFieldName

      public String getTextFieldName()

    • getVector

      public float[] getVector()

    • getVectorFieldName

      public String getVectorFieldName()

    • getVectorParamName

      public String getVectorParamName()

    • getTextScorer

      public String getTextScorer()

    • getYieldTextScoreAs

      public String getYieldTextScoreAs()

    • getVectorSearchMethod

      public HybridQuery.VectorSearchMethod getVectorSearchMethod()

    • getKnnEfRuntime

      public int getKnnEfRuntime()

    • getRangeRadius

      public Float getRangeRadius()

    • getRangeEpsilon

      public float getRangeEpsilon()

    • getYieldVsimScoreAs

      public String getYieldVsimScoreAs()

    • getFilterExpression

      public Object getFilterExpression()

    • getCombinationMethod

      public HybridQuery.CombinationMethod getCombinationMethod()

    • getRrfWindow

      public int getRrfWindow()

    • getRrfConstant

      public int getRrfConstant()

    • getLinearAlpha

      public float getLinearAlpha()

    • getYieldCombinedScoreAs

      public String getYieldCombinedScoreAs()

    • getDtype

      public String getDtype()

    • getNumResults

      public int getNumResults()

    • getReturnFields

      public List<String> getReturnFields()

    • getStopwords

      public Set<String> getStopwords()

    • buildQueryString

      public String buildQueryString()
      Build the query string for the SEARCH clause.

      Tokenizes the text, removes stopwords, escapes special characters, and adds optional filter expression.

      Returns:
      the query string for FT.HYBRID SEARCH clause

    • buildFTHybridParams

      public redis.clients.jedis.search.hybrid.FTHybridParams buildFTHybridParams()
      Build the FTHybridParams for the native FT.HYBRID command.
      Returns:
      the configured FTHybridParams

    • toAggregateHybridQuery

      public AggregateHybridQuery toAggregateHybridQuery()
      Convert this HybridQuery to an AggregateHybridQuery for fallback when FT.HYBRID is not available.

      Maps the LINEAR alpha semantics: HybridQuery's linearAlpha (text weight) maps to AggregateHybridQuery's alpha as (1 - linearAlpha) since AggregateHybridQuery's alpha is the vector weight.

      Returns:
      an AggregateHybridQuery with equivalent parameters

    • getParams

      public Map<String,Object> getParams()
      Get the parameters map for the query (vector parameter).
      Returns:
      parameter map with vector bytes