feat: add skip_decode parameter to return_fields method (#252)

Implements skip_decode parameter for return_fields() method to improve
field deserialization UX. This allows users to skip decoding of binary
fields like embeddings while still returning them in query results.

- Added optional skip_decode parameter to BaseQuery.return_fields()
- Parameter accepts string or list of field names to skip decoding
- Maintains backward compatibility when skip_decode is not provided
- Comprehensive unit test coverage for all query types
- Enhanced skip_decode to use parent's return_field with decode_field=False
- Added comprehensive integration tests with real Redis
- Maintained full backward compatibility with return_field(decode_field=False)
- Tests confirm proper binary field handling (embeddings, image data)

Author: bsbodden

redisvl/query/query.py

@@ -30,6 +30,7 @@ class BaseQuery(RedisQuery):
     _params: Dict[str, Any] = {}
     _filter_expression: Union[str, FilterExpression] = FilterExpression("*")
     _built_query_string: Optional[str] = None
+    _skip_decode_fields: Set[str] = set()
 
     def __init__(self, query_string: str = "*"):
         """
@@ -47,6 +48,9 @@ def __init__(self, query_string: str = "*"):
         # has not been built yet.
         self._built_query_string = None
 
+        # Initialize skip_decode_fields set
+        self._skip_decode_fields = set()
+
     def __str__(self) -> str:
         """Return the string representation of the query."""
         return " ".join([str(x) for x in self.get_args()])
@@ -107,6 +111,60 @@ def _query_string(self, value: Optional[str]):
         """Setter for _query_string to maintain compatibility with parent class."""
         self._built_query_string = value
 
+    def return_fields(
+        self, *fields, skip_decode: Optional[Union[str, List[str]]] = None
+    ):
+        """
+        Set the fields to return with search results.
+
+        Args:
+            *fields: Variable number of field names to return.
+            skip_decode: Optional field name or list of field names that should not be
+                decoded. Useful for binary data like embeddings.
+
+        Returns:
+            self: Returns the query object for method chaining.
+
+        Raises:
+            TypeError: If skip_decode is not a string, list, or None.
+        """
+        # Only clear fields when skip_decode is provided (indicating user is explicitly setting fields)
+        # This preserves backward compatibility when return_fields is called multiple times
+        if skip_decode is not None:
+            # Clear existing fields to provide replacement behavior
+            self._return_fields = []
+            self._return_fields_decode_as = {}
+
+            # Process skip_decode parameter to prepare decode settings
+            if isinstance(skip_decode, str):
+                skip_decode_set = {skip_decode}
+                self._skip_decode_fields = {skip_decode}
+            elif isinstance(skip_decode, list):
+                skip_decode_set = set(skip_decode)
+                self._skip_decode_fields = set(skip_decode)
+            else:
+                raise TypeError(
+                    "skip_decode must be a string, list of strings, or None"
+                )
+
+            # Add fields using parent's return_field method with proper decode settings
+            for field in fields:
+                if field in skip_decode_set:
+                    # Use return_field with decode_field=False for skip_decode fields
+                    super().return_field(field, decode_field=False)
+                else:
+                    # Use normal return_field for other fields
+                    super().return_field(field)
+        else:
+            # Standard additive behavior (backward compatible)
+            super().return_fields(*fields)
+
+            # Initialize skip_decode_fields if not already set
+            if not hasattr(self, "_skip_decode_fields"):
+                self._skip_decode_fields = set()
+
+        return self
+
 
 class FilterQuery(BaseQuery):
     def __init__(