Package com.redis.vl.query

Class AggregateHybridQuery

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

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: AggregateHybridQuery 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.

For native FT.HYBRID support with built-in score fusion (RRF, LINEAR), use HybridQuery instead. This requires Redis 8.4+.

Python equivalent: 

 query = AggregateHybridQuery(
     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: 

 AggregateHybridQuery query = AggregateHybridQuery.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(FullTextQueryHelper.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 AggregateHybridQuery.AggregateHybridQueryBuilder builder()
      Create a new builder for AggregateHybridQuery.
      Returns:
      A new AggregateHybridQueryBuilder instance

    • loadDefaultStopwords

      public static Set<String> loadDefaultStopwords(String language)
      Load default stopwords for a given language.
      Parameters:
      language - the language (e.g., "english", "german")
      Returns:
      set of stopwords

    • getText

      public String getText()

    • getTextFieldName

      public String getTextFieldName()

    • getVector

      public float[] getVector()

    • getVectorFieldName

      public String getVectorFieldName()

    • getTextScorer

      public String getTextScorer()

    • getFilterExpression

      public Object getFilterExpression()

    • getAlpha

      public float getAlpha()

    • getDtype

      public String getDtype()

    • getNumResults

      public int getNumResults()

    • getReturnFields

      public List<String> getReturnFields()

    • getStopwords

      public Set<String> getStopwords()

    • getDialect

      public int getDialect()

    • buildQueryString

      public String buildQueryString()
      Description copied from class: AggregationQuery
      Build the base query string for the aggregation.
      Specified by:
      buildQueryString in class AggregationQuery
      Returns:
      the query string

    • buildRedisAggregation

      public AggregationBuilder buildRedisAggregation()
      Description copied from class: AggregationQuery
      Build the Redis AggregationBuilder for this query.
      Specified by:
      buildRedisAggregation in class AggregationQuery
      Returns:
      the Jedis AggregationBuilder configured for this query

    • getParams

      public Map<String,Object> getParams()
      Description copied from class: AggregationQuery
      Get the parameters for the aggregation query.

      Used for parameterized queries (e.g., vector parameter in HybridQuery).

      Specified by:
      getParams in class AggregationQuery
      Returns:
      a map of parameter names to values