Package com.redis.vl.query

Class MultiVectorQuery

java.lang.Object
com.redis.vl.query.AggregationQuery
com.redis.vl.query.MultiVectorQuery
public final class MultiVectorQuery extends AggregationQuery
MultiVectorQuery allows for search over multiple vector fields in a document simultaneously.

The final score will be a weighted combination of the individual vector similarity scores following the formula:

score = (w_1 * score_1 + w_2 * score_2 + w_3 * score_3 + ... )

Vectors may be of different size and datatype, but must be indexed using the 'cosine' distance_metric.

Note on Runtime Parameters: MultiVectorQuery uses Redis FT.AGGREGATE for aggregation-based multi-vector 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 with single-vector queries, use VectorQuery or VectorRangeQuery instead. See Python PR #439 for details.

Ported from Python: redisvl/query/aggregate.py:257-400 (MultiVectorQuery class)

Python equivalent: 

 from redisvl.query import MultiVectorQuery, Vector

 vector_1 = Vector(vector=[0.1, 0.2, 0.3], field_name="text_vector", dtype="float32", weight=0.7)
 vector_2 = Vector(vector=[0.5, 0.5], field_name="image_vector", dtype="bfloat16", weight=0.2)

 query = MultiVectorQuery(
     vectors=[vector_1, vector_2],
     filter_expression=None,
     num_results=10,
     return_fields=["field1", "field2"],
     dialect=2
 )
Java equivalent: 
 Vector vector1 = Vector.builder()
     .vector(new float[]{0.1f, 0.2f, 0.3f})
     .fieldName("text_vector")
     .dtype("float32")
     .weight(0.7)
     .build();

 Vector vector2 = Vector.builder()
     .vector(new float[]{0.5f, 0.5f})
     .fieldName("image_vector")
     .dtype("bfloat16")
     .weight(0.2)
     .build();

 MultiVectorQuery query = MultiVectorQuery.builder()
     .vectors(Arrays.asList(vector1, vector2))
     .numResults(10)
     .returnFields(Arrays.asList("field1", "field2"))
     .build();

  • Method Details

    • builder

      public static MultiVectorQuery.Builder builder()
      Create a new Builder for MultiVectorQuery.
      Returns:
      A new Builder instance

    • toQueryString

      public String toQueryString()
      Build the Redis query string for multi-vector search.

      Format: @field1:[VECTOR_RANGE 2.0 $vector_0]=>{$YIELD_DISTANCE_AS: distance_0} | @field2:[VECTOR_RANGE 2.0 $vector_1]=>{$YIELD_DISTANCE_AS: distance_1}

      Returns:
      Query string

    • buildQueryString

      public String buildQueryString()
      Build the Redis query string for multi-vector search.

      Format: @field1:[VECTOR_RANGE 2.0 $vector_0]=>{$YIELD_DISTANCE_AS: distance_0} | @field2:[VECTOR_RANGE 2.0 $vector_1]=>{$YIELD_DISTANCE_AS: distance_1}

      Specified by:
      buildQueryString in class AggregationQuery
      Returns:
      Query string

    • toParams

      public Map<String,Object> toParams()
      Convert to parameter map for query execution.

      Returns map with vector_0, vector_1, etc. as byte arrays

      Returns:
      Parameters map

    • getParams

      public Map<String,Object> getParams()
      Convert to parameter map for query execution.

      Returns map with vector_0, vector_1, etc. as byte arrays

      Specified by:
      getParams in class AggregationQuery
      Returns:
      Parameters map

    • buildRedisAggregation

      public AggregationBuilder buildRedisAggregation()
      Build the Redis AggregationBuilder for multi-vector search.

      Creates an aggregation pipeline with:

      • LOAD all return fields
      • APPLY score calculations for each vector: score_i = (2 - distance_i) / 2
      • APPLY final combined score: w_1 * score_1 + w_2 * score_2 + ...
      • SORTBY combined_score DESC
      • LIMIT numResults
      Specified by:
      buildRedisAggregation in class AggregationQuery
      Returns:
      Configured AggregationBuilder

    • getScoringFormula

      public String getScoringFormula()
      Get the scoring formula for combining vector similarities.

      Formula: w_1 * score_1 + w_2 * score_2 + ...

      Where score_i = (2 - distance_i) / 2

      Returns:
      Scoring formula string

    • getScoreCalculations

      public Map<String,String> getScoreCalculations()
      Get individual score calculations.

      Returns map of score_0=(2-distance_0)/2, score_1=(2-distance_1)/2, etc.

      Returns:
      Map of score names to calculation formulas

    • toString

      public String toString()
      Overrides:
      toString in class Object