Package com.redis.vl.query

Class HybridQuery

java.lang.Object
com.redis.vl.query.AggregationQuery
com.redis.vl.query.HybridQuery
public final class HybridQuery extends AggregationQuery
HybridQuery combines text and vector search in Redis using aggregation.

Ported from Python: redisvl/query/aggregate.py:57-329 (AggregateHybridQuery class)

It allows you to perform a hybrid search using both text and vector similarity. It scores documents based on a weighted combination of text and vector similarity using the formula: 

 hybrid_score = (1 - alpha) * text_score + alpha * vector_similarity

Where text_score is the BM25 score from the text search and vector_similarity is the normalized cosine similarity from the vector search.

Redis Version Requirements: This query uses the ADDSCORES option in FT.AGGREGATE to expose the internal text search score (@__score). This feature requires Redis 7.4.0 or later. On older Redis versions, the query will fail.

Note on Runtime Parameters: HybridQuery uses Redis FT.AGGREGATE for aggregation-based hybrid search. As of Redis Stack 7.2+, runtime parameters (efRuntime, epsilon, etc.) are NOT supported in FT.AGGREGATE queries. If you need runtime parameter support, use VectorQuery or VectorRangeQuery instead. See Python PR #439 for details.

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",
     filter_expression=None,
     alpha=0.7,
     dtype="float32",
     num_results=10,
     return_fields=["field1", "field2"],
     stopwords="english",
     dialect=2,
 )
 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")
     .filterExpression(null)
     .alpha(0.7f)
     .dtype("float32")
     .numResults(10)
     .returnFields(List.of("field1", "field2"))
     .stopwords(loadDefaultStopwords("english"))
     .dialect(2)
     .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.1.0

  • Method Details

    • builder

      public static HybridQuery.HybridQueryBuilder builder()
      Create a new builder for HybridQuery.
      Returns:
      A new HybridQueryBuilder instance

    • getText

      public String getText()
      Get the text query string.
      Returns:
      The text to search for

    • getTextFieldName

      public String getTextFieldName()
      Get the text field name.
      Returns:
      The field name containing text data

    • getVector

      public float[] getVector()
      Get a copy of the query vector.
      Returns:
      A defensive copy of the vector array

    • getVectorFieldName

      public String getVectorFieldName()
      Get the vector field name.
      Returns:
      The field name containing vector data

    • getTextScorer

      public String getTextScorer()
      Get the text scoring algorithm.
      Returns:
      The text scorer (e.g., "BM25", "TFIDF")

    • getFilterExpression

      public Object getFilterExpression()
      Get the filter expression.

      Can be either a Filter object or a String containing a raw Redis filter expression.

      Returns:
      The filter to apply (Filter or String), or null if no filter

    • getAlpha

      public float getAlpha()
      Get the alpha weighting factor.
      Returns:
      Weight between 0.0 (vector only) and 1.0 (text only)

    • getDtype

      public String getDtype()
      Get the data type for vector storage.
      Returns:
      The data type (e.g., "float32", "float64")

    • getNumResults

      public int getNumResults()
      Get the maximum number of results.
      Returns:
      The result limit

    • getReturnFields

      public List<String> getReturnFields()
      Get an unmodifiable view of the return fields.
      Returns:
      Unmodifiable list of return fields

    • getStopwords

      public Set<String> getStopwords()
      Get an unmodifiable view of the stopwords.
      Returns:
      Unmodifiable set of stopwords

    • getDialect

      public int getDialect()
      Get the query dialect version.
      Returns:
      The dialect version (default 2)

    • loadDefaultStopwords

      public static Set<String> loadDefaultStopwords(String language)
      Load default stopwords for a given language.

      Python uses nltk, we'll use a simple file-based approach.

      Parameters:
      language - the language (e.g., "english", "german")
      Returns:
      set of stopwords

    • tokenizeAndEscapeQuery

      public String tokenizeAndEscapeQuery(String userQuery)
      Tokenize and escape the user query.

      Ported from Python: _tokenize_and_escape_query (line 185-209)

      Parameters:
      userQuery - the user query to tokenize
      Returns:
      tokenized and escaped query string joined by OR

    • buildQueryString

      public String buildQueryString()
      Build the full query string for text search with optional filtering.

      Ported from Python: _build_query_string (line 211-225)

      Specified by:
      buildQueryString in class AggregationQuery
      Returns:
      the query string

    • buildRedisAggregation

      public AggregationBuilder buildRedisAggregation()
      Build the Redis AggregationBuilder for this hybrid query.

      Ported from Python __init__ method (line 103-129)

      Specified by:
      buildRedisAggregation in class AggregationQuery
      Returns:
      the AggregationBuilder

    • getParams

      public Map<String,Object> getParams()
      Get the parameters for the aggregation query.

      Ported from Python: params property (line 132-145)

      Specified by:
      getParams in class AggregationQuery
      Returns:
      parameter map with vector