feat: implement skip_decode parameter for binary fields (port of Python PR #389)

Add skipDecodeFields parameter to query builders to control binary field decoding:
- FilterQuery, VectorQuery, VectorRangeQuery, TextQuery
- Accepts List<String> or varargs of field names
- Returns immutable copy via getSkipDecodeFields()

Implementation details:
- Field names that should not be decoded from binary format
- Useful for binary data like embeddings and image data
- Validates field names cannot be null
- Maintains backward compatibility (defaults to empty list)

Test coverage:
- 10 unit tests in SkipDecodeFieldsTest
- Tests for all query types
- Validation tests for null handling
- Varargs convenience method tests

Python reference:
- skip_decode parameter in return_fields() method
- Prevents automatic decoding of specified binary fields
- Allows retrieval of raw bytes for embeddings/images

Refs: redis/redis-vl-python#389
Fixes: #252

Author: bsbodden

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

@@ -44,6 +44,8 @@ private FilterQuery(FilterQueryBuilder builder) {
     this.sortAscending = builder.sortAscending;
     this.inOrder = builder.inOrder;
     this.params = builder.params != null ? Map.copyOf(builder.params) : Map.of();
+    this.skipDecodeFields =
+        builder.skipDecodeFields != null ? List.copyOf(builder.skipDecodeFields) : List.of();
   }
 
   /**
@@ -92,6 +94,11 @@ public static FilterQueryBuilder builder() {
   /** Additional parameters for the query. Python: params (Optional[Dict[str, Any]]) */
   private final Map<String, Object> params;
 
+  /**
+   * Fields that should not be decoded from binary format. Python: skip_decode parameter (PR #389)
+   */
+  private final List<String> skipDecodeFields;
+
   /**
    * Build Redis Query object from FilterQuery.
    *
@@ -194,6 +201,17 @@ public Map<String, Object> getParams() {
     return params;
   }
 
+  /**
+   * Get the list of fields that should not be decoded from binary format.
+   *
+   * <p>Python equivalent: _skip_decode_fields attribute (PR #389)
+   *
+   * @return List of field names to skip decoding
+   */
+  public List<String> getSkipDecodeFields() {
+    return skipDecodeFields;
+  }
+
   /** Builder for FilterQuery with defensive copying. */
   public static class FilterQueryBuilder {
     private Filter filterExpression;
@@ -204,6 +222,7 @@ public static class FilterQueryBuilder {
     private boolean sortAscending = true; // Default to ascending
     private boolean inOrder = false;
     private Map<String, Object> params = Map.of();
+    private List<String> skipDecodeFields = List.of();
 
     FilterQueryBuilder() {}
 
@@ -359,6 +378,52 @@ public FilterQueryBuilder params(Map<String, Object> params) {
       return this;
     }
 
+    /**
+     * Set fields that should not be decoded from binary format.
+     *
+     * <p>Python equivalent: skip_decode parameter in return_fields() (PR #389)
+     *
+     * @param skipDecodeFields List of field names
+     * @return this builder
+     * @throws IllegalArgumentException if list contains null values
+     */
+    public FilterQueryBuilder skipDecodeFields(List<String> skipDecodeFields) {
+      if (skipDecodeFields == null) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      // Validate no null values
+      for (String field : skipDecodeFields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.copyOf(skipDecodeFields);
+      return this;
+    }
+
+    /**
+     * Set fields that should not be decoded from binary format (varargs).
+     *
+     * @param fields Field names
+     * @return this builder
+     * @throws IllegalArgumentException if any field is null
+     */
+    public FilterQueryBuilder skipDecodeFields(String... fields) {
+      if (fields == null || fields.length == 0) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      // Validate no null values
+      for (String field : fields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.of(fields);
+      return this;
+    }
+
     /**
      * Build the FilterQuery instance.
      *

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

@@ -52,6 +52,9 @@ public class TextQuery {
   /** Whether to sort in descending order */
   private final boolean sortDescending;
 
+  /** Fields that should not be decoded from binary format */
+  private final List<String> skipDecodeFields;
+
   private TextQuery(Builder builder) {
     this.text = builder.text;
     this.scorer = builder.scorer;
@@ -60,6 +63,8 @@ private TextQuery(Builder builder) {
     this.fieldWeights = new HashMap<>(builder.fieldWeights);
     this.sortBy = builder.sortBy;
     this.sortDescending = builder.sortDescending;
+    this.skipDecodeFields =
+        builder.skipDecodeFields != null ? List.copyOf(builder.skipDecodeFields) : List.of();
   }
 
   /**
@@ -81,6 +86,15 @@ public Map<String, Double> getFieldWeights() {
     return new HashMap<>(fieldWeights);
   }
 
+  /**
+   * Get the list of fields that should not be decoded from binary format.
+   *
+   * @return List of field names to skip decoding
+   */
+  public List<String> getSkipDecodeFields() {
+    return skipDecodeFields;
+  }
+
   /**
    * Build the Redis query string for text search with weighted fields.
    *
@@ -174,6 +188,7 @@ public static class Builder {
     private Map<String, Double> fieldWeights = new HashMap<>();
     private String sortBy;
     private boolean sortDescending = false;
+    private List<String> skipDecodeFields = List.of();
 
     /**
      * Set the text to search for.
@@ -327,6 +342,49 @@ public Builder sortDescending(boolean descending) {
       return this;
     }
 
+    /**
+     * Set fields that should not be decoded from binary format.
+     *
+     * @param skipDecodeFields List of field names
+     * @return This builder
+     * @throws IllegalArgumentException if list contains null values
+     */
+    public Builder skipDecodeFields(List<String> skipDecodeFields) {
+      if (skipDecodeFields == null) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      // Validate no null values
+      for (String field : skipDecodeFields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.copyOf(skipDecodeFields);
+      return this;
+    }
+
+    /**
+     * Set fields that should not be decoded from binary format (varargs).
+     *
+     * @param fields Field names
+     * @return This builder
+     * @throws IllegalArgumentException if any field is null
+     */
+    public Builder skipDecodeFields(String... fields) {
+      if (fields == null || fields.length == 0) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      for (String field : fields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.of(fields);
+      return this;
+    }
+
     /**
      * Build the TextQuery instance.
      *

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

@@ -61,6 +61,9 @@ public class VectorQuery {
   /** Whether to require terms in field to have same order as in query */
   private boolean inOrder;
 
+  /** Fields that should not be decoded from binary format */
+  private List<String> skipDecodeFields;
+
   /** Private constructor */
   private VectorQuery(
       String field,
@@ -77,7 +80,8 @@ private VectorQuery(
       boolean normalizeVectorDistance,
       String sortBy,
       boolean sortDescending,
-      boolean inOrder) {
+      boolean inOrder,
+      List<String> skipDecodeFields) {
     this.field = field;
     this.vector = vector != null ? vector.clone() : null; // Defensive copy
     this.numResults = numResults;
@@ -93,6 +97,8 @@ private VectorQuery(
     this.sortBy = sortBy;
     this.sortDescending = sortDescending;
     this.inOrder = inOrder;
+    this.skipDecodeFields =
+        skipDecodeFields != null ? new ArrayList<>(skipDecodeFields) : new ArrayList<>();
   }
 
   /**
@@ -505,6 +511,15 @@ public boolean isInOrder() {
     return inOrder;
   }
 
+  /**
+   * Get the list of fields that should not be decoded from binary format.
+   *
+   * @return List of field names to skip decoding
+   */
+  public List<String> getSkipDecodeFields() {
+    return skipDecodeFields != null ? new ArrayList<>(skipDecodeFields) : new ArrayList<>();
+  }
+
   @Override
   public String toString() {
     StringBuilder sb = new StringBuilder();
@@ -550,6 +565,7 @@ public Builder() {
     private String sortBy;
     private boolean sortDescending = false;
     private boolean inOrder = false;
+    private List<String> skipDecodeFields = new ArrayList<>();
 
     private static float[] toFloatArray(double[] doubles) {
       if (doubles == null) return null;
@@ -904,6 +920,49 @@ public Builder inOrder(boolean inOrder) {
       return this;
     }
 
+    /**
+     * Set fields that should not be decoded from binary format.
+     *
+     * @param skipDecodeFields List of field names
+     * @return This builder
+     * @throws IllegalArgumentException if list contains null values
+     */
+    public Builder skipDecodeFields(List<String> skipDecodeFields) {
+      if (skipDecodeFields == null) {
+        this.skipDecodeFields = new ArrayList<>();
+        return this;
+      }
+      // Validate no null values
+      for (String field : skipDecodeFields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = new ArrayList<>(skipDecodeFields);
+      return this;
+    }
+
+    /**
+     * Set fields that should not be decoded from binary format (varargs).
+     *
+     * @param fields Field names
+     * @return This builder
+     * @throws IllegalArgumentException if any field is null
+     */
+    public Builder skipDecodeFields(String... fields) {
+      if (fields == null || fields.length == 0) {
+        this.skipDecodeFields = new ArrayList<>();
+        return this;
+      }
+      for (String field : fields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = new ArrayList<>(Arrays.asList(fields));
+      return this;
+    }
+
     /**
      * Build the VectorQuery
      *
@@ -940,7 +999,8 @@ public VectorQuery build() {
           normalizeVectorDistance,
           sortBy,
           sortDescending,
-          inOrder);
+          inOrder,
+          skipDecodeFields);
     }
   }
 }

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

@@ -22,6 +22,7 @@ public final class VectorRangeQuery {
   private final String sortBy;
   private final boolean sortDescending;
   private final boolean inOrder;
+  private final List<String> skipDecodeFields;
 
   private VectorRangeQuery(Builder builder) {
     // Validate before modifying state to avoid partial initialization
@@ -44,6 +45,8 @@ private VectorRangeQuery(Builder builder) {
     this.sortBy = builder.sortBy;
     this.sortDescending = builder.sortDescending;
     this.inOrder = builder.inOrder;
+    this.skipDecodeFields =
+        builder.skipDecodeFields != null ? List.copyOf(builder.skipDecodeFields) : List.of();
   }
 
   /**
@@ -188,6 +191,15 @@ public boolean isInOrder() {
     return inOrder;
   }
 
+  /**
+   * Get the list of fields that should not be decoded from binary format.
+   *
+   * @return List of field names to skip decoding
+   */
+  public List<String> getSkipDecodeFields() {
+    return skipDecodeFields;
+  }
+
   /**
    * Build the query string for Redis range query
    *
@@ -242,6 +254,7 @@ public static class Builder {
     private String sortBy;
     private boolean sortDescending = false;
     private boolean inOrder = false;
+    private List<String> skipDecodeFields = List.of();
 
     /** Package-private constructor used by builder() method. */
     Builder() {}
@@ -454,6 +467,49 @@ public Builder inOrder(boolean inOrder) {
       return this;
     }
 
+    /**
+     * Set fields that should not be decoded from binary format.
+     *
+     * @param skipDecodeFields List of field names
+     * @return This builder
+     * @throws IllegalArgumentException if list contains null values
+     */
+    public Builder skipDecodeFields(List<String> skipDecodeFields) {
+      if (skipDecodeFields == null) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      // Validate no null values
+      for (String field : skipDecodeFields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.copyOf(skipDecodeFields);
+      return this;
+    }
+
+    /**
+     * Set fields that should not be decoded from binary format (varargs).
+     *
+     * @param fields Field names
+     * @return This builder
+     * @throws IllegalArgumentException if any field is null
+     */
+    public Builder skipDecodeFields(String... fields) {
+      if (fields == null || fields.length == 0) {
+        this.skipDecodeFields = List.of();
+        return this;
+      }
+      for (String field : fields) {
+        if (field == null) {
+          throw new IllegalArgumentException("skipDecodeFields cannot contain null values");
+        }
+      }
+      this.skipDecodeFields = List.of(fields);
+      return this;
+    }
+
     /**
      * Build the VectorRangeQuery instance.
      *