feat(cache): add warnings when using sync methods with async-only Redis client (#391)

Co-authored-by: owais <[email protected]>

Author: bsbodden

redisvl/extensions/cache/embeddings/embeddings.py

@@ -14,6 +14,8 @@
 class EmbeddingsCache(BaseCache):
     """Embeddings Cache for storing embedding vectors with exact key matching."""
 
+    _warning_shown: bool = False  # Class-level flag to prevent warning spam
+
     def __init__(
         self,
         name: str = "embedcache",
@@ -124,6 +126,14 @@ def _process_cache_data(
         cache_hit = CacheEntry(**convert_bytes(data))
         return cache_hit.model_dump(exclude_none=True)
 
+    def _should_warn_for_async_only(self) -> bool:
+        """Check if only async client is available (no sync client).
+
+        Returns:
+            bool: True if only async client is available (no sync client).
+        """
+        return self._owns_redis_client is False and self._redis_client is None
+
     def get(
         self,
         text: str,
@@ -167,6 +177,14 @@ def get_by_key(self, key: str) -> Optional[Dict[str, Any]]:
 
             embedding_data = cache.get_by_key("embedcache:1234567890abcdef")
         """
+        if self._should_warn_for_async_only():
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (aget_by_key) instead of sync methods (get_by_key)."
+                )
+                EmbeddingsCache._warning_shown = True
+
         client = self._get_redis_client()
 
         # Get all fields
@@ -202,6 +220,14 @@ def mget_by_keys(self, keys: List[str]) -> List[Optional[Dict[str, Any]]]:
         if not keys:
             return []
 
+        if self._should_warn_for_async_only():
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (amget_by_keys) instead of sync methods (mget_by_keys)."
+                )
+                EmbeddingsCache._warning_shown = True
+
         client = self._get_redis_client()
 
         with client.pipeline(transaction=False) as pipeline:
@@ -283,6 +309,14 @@ def set(
             text, model_name, embedding, metadata
         )
 
+        if self._should_warn_for_async_only():
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (aset) instead of sync methods (set)."
+                )
+                EmbeddingsCache._warning_shown = True
+
         # Store in Redis
         client = self._get_redis_client()
         client.hset(name=key, mapping=cache_entry)  # type: ignore
@@ -333,6 +367,14 @@ def mset(
         if not items:
             return []
 
+        if self._should_warn_for_async_only():
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (amset) instead of sync methods (mset)."
+                )
+                EmbeddingsCache._warning_shown = True
+
         client = self._get_redis_client()
         keys = []
 

redisvl/index/index.py

@@ -245,8 +245,10 @@ def name(self) -> str:
     @property
     def prefix(self) -> str:
         """The optional key prefix that comes before a unique key value in
-        forming a Redis key."""
-        return self.schema.index.prefix
+        forming a Redis key. If multiple prefixes are configured, returns the
+        first one."""
+        prefix = self.schema.index.prefix
+        return prefix[0] if isinstance(prefix, list) else prefix
 
     @property
     def key_separator(self) -> str:
@@ -329,7 +331,7 @@ def key(self, id: str) -> str:
         """
         return self._storage._key(
             id=id,
-            prefix=self.schema.index.prefix,
+            prefix=self.prefix,
             key_separator=self.schema.index.key_separator,
         )
 

redisvl/index/storage.py

@@ -114,9 +114,13 @@ def _create_key(self, obj: Dict[str, Any], id_field: Optional[str] = None) -> st
             except KeyError:
                 raise ValueError(f"Key field {id_field} not found in record {obj}")
 
+        # Normalize prefix: use first prefix if multiple are configured
+        prefix = self.index_schema.index.prefix
+        normalized_prefix = prefix[0] if isinstance(prefix, list) else prefix
+
         return self._key(
             key_value,
-            prefix=self.index_schema.index.prefix,
+            prefix=normalized_prefix,
             key_separator=self.index_schema.index.key_separator,
         )
 

redisvl/redis/connection.py

@@ -133,31 +133,73 @@ def convert_index_info_to_schema(index_info: Dict[str, Any]) -> Dict[str, Any]:
         Dict[str, Any]: Schema dictionary.
     """
     index_name = index_info["index_name"]
-    prefixes = index_info["index_definition"][3][0]
+    prefixes = index_info["index_definition"][3]
+    # Normalize single-element prefix lists to string for backward compatibility
+    if isinstance(prefixes, list) and len(prefixes) == 1:
+        prefixes = prefixes[0]
     storage_type = index_info["index_definition"][1].lower()
 
     index_fields = index_info["attributes"]
 
     def parse_vector_attrs(attrs):
         # Parse vector attributes from Redis FT.INFO output
-        # Attributes start at position 6 as key-value pairs
+        # Format varies significantly between Redis versions:
+        # - Redis 6.2.6-v9: [... "VECTOR"] - no params returned by FT.INFO
+        # - Redis 6.2.x: [... "VECTOR", "FLAT", "6", "TYPE", "FLOAT32", "DIM", "3", ...]
+        #   Position 6: algorithm value (e.g., "FLAT" or "HNSW")
+        #   Position 7: param count
+        #   Position 8+: key-value pairs
+        # - Redis 7.x+: [... "VECTOR", "ALGORITHM", "FLAT", "TYPE", "FLOAT32", "DIM", "3", ...]
+        #   Position 6+: all key-value pairs
+
+        # Check if we have any attributes beyond the type declaration
+        if len(attrs) <= 6:
+            # Redis 6.2.6-v9 or similar: no vector params in FT.INFO
+            # Return None to signal we can't parse this field properly
+            return None
+
         vector_attrs = {}
+        start_pos = 6
+
+        # Detect format: if position 6 looks like an algorithm value (not a key),
+        # we're dealing with the older format
+        if len(attrs) > 6:
+            pos6_str = str(attrs[6]).upper()
+            # Check if position 6 is an algorithm value (FLAT, HNSW) vs a key (ALGORITHM, TYPE, DIM)
+            if pos6_str in ("FLAT", "HNSW"):
+                # Old format (Redis 6.2.x): position 6 is algorithm value, position 7 is param count
+                # Store the algorithm
+                vector_attrs["algorithm"] = pos6_str
+                # Skip to position 8 where key-value pairs start
+                start_pos = 8
+
         try:
-            for i in range(6, len(attrs), 2):
+            for i in range(start_pos, len(attrs), 2):
                 if i + 1 < len(attrs):
                     key = str(attrs[i]).lower()
                     vector_attrs[key] = attrs[i + 1]
         except (IndexError, TypeError, ValueError):
+            # Silently continue - we'll validate required fields below
             pass
 
         # Normalize to expected field names
         normalized = {}
 
-        # Handle dims/dim field
+        # Handle dims/dim field - REQUIRED for vector fields
         if "dim" in vector_attrs:
             normalized["dims"] = int(vector_attrs.pop("dim"))
         elif "dims" in vector_attrs:
             normalized["dims"] = int(vector_attrs["dims"])
+        else:
+            # If dims is missing from normal parsing, try scanning the raw attrs
+            # This handles edge cases where the format is unexpected
+            for i in range(6, len(attrs) - 1):
+                if str(attrs[i]).upper() in ("DIM", "DIMS"):
+                    try:
+                        normalized["dims"] = int(attrs[i + 1])
+                        break
+                    except (ValueError, IndexError):
+                        pass
 
         # Handle distance_metric field
         if "distance_metric" in vector_attrs:
@@ -178,10 +220,18 @@ def parse_vector_attrs(attrs):
             normalized["datatype"] = vector_attrs["data_type"].lower()
         elif "datatype" in vector_attrs:
             normalized["datatype"] = vector_attrs["datatype"].lower()
+        elif "type" in vector_attrs:
+            # Sometimes it's just "type" instead of "data_type"
+            normalized["datatype"] = vector_attrs["type"].lower()
         else:
             # Default to float32 if missing
             normalized["datatype"] = "float32"
 
+        # Validate that we have required dims
+        if "dims" not in normalized:
+            # Could not parse dims - this field is not properly supported
+            return None
+
         return normalized
 
     def parse_attrs(attrs, field_type=None):
@@ -234,7 +284,12 @@ def parse_attrs(attrs, field_type=None):
             field["path"] = field_attrs[1]
         # parse field attrs
         if field_attrs[5] == "VECTOR":
-            field["attrs"] = parse_vector_attrs(field_attrs)
+            attrs = parse_vector_attrs(field_attrs)
+            if attrs is None:
+                # Vector field attributes cannot be parsed on this Redis version
+                # Skip this field - it cannot be properly reconstructed
+                continue
+            field["attrs"] = attrs
         else:
             field["attrs"] = parse_attrs(field_attrs, field_type=field_attrs[5])
         # append field

redisvl/schema/schema.py

@@ -58,8 +58,8 @@ class IndexInfo(BaseModel):
 
     name: str
     """The unique name of the index."""
-    prefix: str = "rvl"
-    """The prefix used for Redis keys associated with this index."""
+    prefix: Union[str, List[str]] = "rvl"
+    """The prefix(es) used for Redis keys associated with this index. Can be a single string or a list of strings."""
     key_separator: str = ":"
     """The separator character used in designing Redis keys."""
     storage_type: StorageType = StorageType.HASH

tests/integration/test_embedcache_warnings.py

@@ -0,0 +1,88 @@
+"""Test warning behavior when using sync methods with async-only client."""
+
+import logging
+from unittest.mock import patch
+
+import pytest
+from redis import Redis
+
+from redisvl.extensions.cache.embeddings import EmbeddingsCache
+
+
+@pytest.fixture(autouse=True)
+def reset_warning_flag():
+    """Reset the warning flag before each test to ensure test isolation."""
+    EmbeddingsCache._warning_shown = False
+    yield
+    # Optionally reset after test as well for cleanup
+    EmbeddingsCache._warning_shown = False
+
+
+@pytest.mark.asyncio
+async def test_sync_methods_warn_with_async_only_client(async_client, caplog):
+    """Test that sync methods warn when only async client is provided."""
+    # Initialize EmbeddingsCache with only async_redis_client
+    cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client)
+
+    # Mock _get_redis_client to prevent actual connection attempt
+    with patch.object(cache, "_get_redis_client") as mock_get_client:
+        # Mock the Redis client methods that would be called
+        mock_client = mock_get_client.return_value
+        mock_client.hgetall.return_value = {}  # Empty result for get_by_key
+        mock_client.hset.return_value = 1  # Success for set
+
+        # Capture log warnings
+        with caplog.at_level(logging.WARNING):
+            # First sync method call should warn
+            _ = cache.get_by_key("test_key")
+
+            # Check warning was logged
+            assert len(caplog.records) == 1
+            assert (
+                "initialized with async_redis_client only" in caplog.records[0].message
+            )
+            assert "Use async methods" in caplog.records[0].message
+
+            # Clear captured logs
+            caplog.clear()
+
+            # Second sync method call should NOT warn (flag prevents spam)
+            _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2])
+
+            # Should not have logged another warning
+            assert len(caplog.records) == 0
+
+
+def test_no_warning_with_sync_client(redis_url):
+    """Test that no warning is shown when sync client is provided."""
+    # Create sync redis client from redis_url
+    sync_client = Redis.from_url(redis_url)
+
+    try:
+        # Initialize EmbeddingsCache with sync_redis_client
+        cache = EmbeddingsCache(name="test_cache", redis_client=sync_client)
+
+        with patch("redisvl.utils.log.get_logger") as mock_logger:
+            # Sync methods should not warn
+            _ = cache.get_by_key("test_key")
+            _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2])
+
+            # No warnings should have been logged
+            mock_logger.return_value.warning.assert_not_called()
+    finally:
+        sync_client.close()
+
+
+@pytest.mark.asyncio
+async def test_async_methods_no_warning(async_client):
+    """Test that async methods don't trigger warnings."""
+    # Initialize EmbeddingsCache with only async_redis_client
+    cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client)
+
+    with patch("redisvl.utils.log.get_logger") as mock_logger:
+        # Async methods should not warn
+        _ = await cache.aget_by_key("test_key")
+        _ = await cache.aset(text="test", model_name="model", embedding=[0.1, 0.2])
+
+        # No warnings should have been logged
+        mock_logger.return_value.warning.assert_not_called()