feat(query): add sortBy and inOrder parameters to vector queries

Add query enhancements for better result control and term ordering:

**sortBy parameter:**
- Add sortBy/sortDescending to VectorQuery and VectorRangeQuery
- Support ascending and descending sort order
- Integrate with FTSearchParams for Redis sorting
- Port Python test_sort_vector_query and test_sort_range_query

**inOrder parameter:**
- Add inOrder to VectorQuery and VectorRangeQuery
- FilterQuery already had inOrder support
- Requires terms in field to match query order
- Uses FTSearchParams.inOrder() for Redis enforcement

**Implementation details:**
- Update SearchIndex to handle sorting via searchWithSort()
- Support both sortBy and inOrder simultaneously
- Fix VectorRangeQuery distance field name (vector_distance vs distance)
- Add 4 comprehensive integration tests

All 312+ tests passing with no regressions.

Author: bsbodden

core/src/main/java/com/redis/vl/index/SearchIndex.java

@@ -1104,6 +1104,13 @@ public SearchResult search(VectorQuery query) {
     // Convert VectorQuery to search string
     String queryString = query.toQueryString();
     Map<String, Object> params = query.toParams();
+
+    // Handle sorting or inOrder if specified
+    if ((query.getSortBy() != null && !query.getSortBy().isEmpty()) || query.isInOrder()) {
+      return searchWithSort(
+          queryString, params, query.getSortBy(), query.isSortDescending(), query.isInOrder());
+    }
+
     return search(queryString, params);
   }
 
@@ -1138,6 +1145,57 @@ public SearchResult search(String query, Map<String, Object> params) {
     }
   }
 
+  /**
+   * Search with sorting and/or inOrder support.
+   *
+   * @param query The query string
+   * @param params Query parameters
+   * @param sortBy Field to sort by (can be null)
+   * @param descending Whether to sort in descending order
+   * @param inOrder Whether to require terms in field to have same order as in query
+   * @return Search results
+   */
+  private SearchResult searchWithSort(
+      String query, Map<String, Object> params, String sortBy, boolean descending, boolean inOrder) {
+    if (!exists()) {
+      throw new RedisVLException("Index " + getName() + " does not exist");
+    }
+
+    UnifiedJedis jedis = getUnifiedJedis();
+    try {
+      // Convert params to FTSearchParams
+      redis.clients.jedis.search.FTSearchParams searchParams =
+          new redis.clients.jedis.search.FTSearchParams();
+
+      // Set dialect to 2 for KNN queries
+      searchParams.dialect(2);
+
+      // Add vector parameters if present
+      if (params != null && !params.isEmpty()) {
+        addParamsToSearchParams(searchParams, params);
+      }
+
+      // Add sorting if specified
+      if (sortBy != null && !sortBy.isEmpty()) {
+        redis.clients.jedis.args.SortingOrder order =
+            descending
+                ? redis.clients.jedis.args.SortingOrder.DESC
+                : redis.clients.jedis.args.SortingOrder.ASC;
+        searchParams.sortBy(sortBy, order);
+      }
+
+      // Add inOrder if specified
+      if (inOrder) {
+        searchParams.inOrder();
+      }
+
+      return jedis.ftSearch(schema.getName(), query, searchParams);
+    } catch (Exception e) {
+      throw new RuntimeException(
+          "Failed to search index with sorting/inOrder: " + e.getMessage(), e);
+    }
+  }
+
   /**
    * List all search indexes in Redis
    *
@@ -1227,6 +1285,9 @@ public List<Map<String, Object>> query(Object query) {
                 .hybridQuery(vq.getHybridQuery())
                 .efRuntime(vq.getEfRuntime())
                 .returnFields(vq.getReturnFields())
+                .sortBy(vq.getSortBy())
+                .sortDescending(vq.isSortDescending())
+                .inOrder(vq.isInOrder())
                 .build();
       }
 
@@ -1241,14 +1302,19 @@ public List<Map<String, Object>> query(Object query) {
               .field(vrq.getField())
               .numResults(vrq.getNumResults())
               .returnDistance(true)
+              .sortBy(vrq.getSortBy())
+              .sortDescending(vrq.isSortDescending())
+              .inOrder(vrq.isInOrder())
               .build();
       SearchResult result = search(vq);
       // Filter results by distance threshold
       List<Map<String, Object>> allResults = processSearchResult(result);
       List<Map<String, Object>> filtered = new ArrayList<>();
       for (Map<String, Object> doc : allResults) {
-        if (doc.containsKey("distance")) {
-          double distance = Double.parseDouble(doc.get("distance").toString());
+        // Check both "distance" and "vector_distance" for compatibility
+        Object distanceObj = doc.getOrDefault("distance", doc.get("vector_distance"));
+        if (distanceObj != null) {
+          double distance = Double.parseDouble(distanceObj.toString());
           if (distance <= vrq.getDistanceThreshold()) {
             filtered.add(doc);
           }

core/src/main/java/com/redis/vl/query/VectorQuery.java

@@ -52,6 +52,15 @@ public class VectorQuery {
   /** Batch size for hybrid search */
   private Integer batchSize;
 
+  /** Field to sort results by */
+  private String sortBy;
+
+  /** Whether to sort in descending order (default: ascending) */
+  private boolean sortDescending;
+
+  /** Whether to require terms in field to have same order as in query */
+  private boolean inOrder;
+
   /** Private constructor */
   private VectorQuery(
       String field,
@@ -65,7 +74,10 @@ private VectorQuery(
       String hybridQuery,
       Integer efRuntime,
       List<String> returnFields,
-      boolean normalizeVectorDistance) {
+      boolean normalizeVectorDistance,
+      String sortBy,
+      boolean sortDescending,
+      boolean inOrder) {
     this.field = field;
     this.vector = vector != null ? vector.clone() : null; // Defensive copy
     this.numResults = numResults;
@@ -78,6 +90,9 @@ private VectorQuery(
     this.efRuntime = efRuntime;
     this.returnFields = returnFields;
     this.normalizeVectorDistance = normalizeVectorDistance;
+    this.sortBy = sortBy;
+    this.sortDescending = sortDescending;
+    this.inOrder = inOrder;
   }
 
   /** Create a builder */
@@ -330,6 +345,18 @@ public boolean isNormalizeVectorDistance() {
     return normalizeVectorDistance;
   }
 
+  public String getSortBy() {
+    return sortBy;
+  }
+
+  public boolean isSortDescending() {
+    return sortDescending;
+  }
+
+  public boolean isInOrder() {
+    return inOrder;
+  }
+
   @Override
   public String toString() {
     StringBuilder sb = new StringBuilder();
@@ -366,6 +393,9 @@ public static class Builder {
     private Integer efRuntime;
     private List<String> returnFields;
     private boolean normalizeVectorDistance = false;
+    private String sortBy;
+    private boolean sortDescending = false;
+    private boolean inOrder = false;
 
     private static float[] toFloatArray(double[] doubles) {
       if (doubles == null) return null;
@@ -495,6 +525,21 @@ public Builder normalizeVectorDistance(boolean normalize) {
       return this;
     }
 
+    public Builder sortBy(String sortBy) {
+      this.sortBy = sortBy;
+      return this;
+    }
+
+    public Builder sortDescending(boolean descending) {
+      this.sortDescending = descending;
+      return this;
+    }
+
+    public Builder inOrder(boolean inOrder) {
+      this.inOrder = inOrder;
+      return this;
+    }
+
     public VectorQuery build() {
       // Validate required fields
       if (field == null || field.trim().isEmpty()) {
@@ -523,7 +568,10 @@ public VectorQuery build() {
           hybridQuery,
           efRuntime,
           returnFields,
-          normalizeVectorDistance);
+          normalizeVectorDistance,
+          sortBy,
+          sortDescending,
+          inOrder);
     }
   }
 }

core/src/main/java/com/redis/vl/query/VectorRangeQuery.java

@@ -14,6 +14,9 @@ public class VectorRangeQuery {
   private final boolean normalizeVectorDistance;
   private double distanceThreshold;
   private Double epsilon;
+  private final String sortBy;
+  private final boolean sortDescending;
+  private final boolean inOrder;
 
   private VectorRangeQuery(Builder builder) {
     // Validate before modifying state to avoid partial initialization
@@ -33,6 +36,9 @@ private VectorRangeQuery(Builder builder) {
     this.returnScore = builder.returnScore;
     this.normalizeVectorDistance = builder.normalizeVectorDistance;
     this.epsilon = builder.epsilon;
+    this.sortBy = builder.sortBy;
+    this.sortDescending = builder.sortDescending;
+    this.inOrder = builder.inOrder;
   }
 
   public static Builder builder() {
@@ -91,6 +97,18 @@ public void setEpsilon(double epsilon) {
     this.epsilon = epsilon;
   }
 
+  public String getSortBy() {
+    return sortBy;
+  }
+
+  public boolean isSortDescending() {
+    return sortDescending;
+  }
+
+  public boolean isInOrder() {
+    return inOrder;
+  }
+
   /**
    * Build the query string for Redis range query
    *
@@ -140,6 +158,9 @@ public static class Builder {
     private boolean returnScore = false;
     private boolean normalizeVectorDistance = false;
     private Double epsilon;
+    private String sortBy;
+    private boolean sortDescending = false;
+    private boolean inOrder = false;
 
     public Builder vector(float[] vector) {
       this.vector = vector != null ? vector.clone() : null;
@@ -195,6 +216,21 @@ public Builder epsilon(double epsilon) {
       return this;
     }
 
+    public Builder sortBy(String sortBy) {
+      this.sortBy = sortBy;
+      return this;
+    }
+
+    public Builder sortDescending(boolean descending) {
+      this.sortDescending = descending;
+      return this;
+    }
+
+    public Builder inOrder(boolean inOrder) {
+      this.inOrder = inOrder;
+      return this;
+    }
+
     public VectorRangeQuery build() {
       return new VectorRangeQuery(this);
     }