Skip to content

Commit f0048fb

Browse files
committed
Merge remote-tracking branch 'origin/main' into HEAD
2 parents c24a71d + 085f739 commit f0048fb

20 files changed

Lines changed: 669 additions & 207 deletions

‎docs/api/exceptions.rst‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -186,14 +186,23 @@ Telling "the index is missing" apart from other failures
186186
Redis Search reports an absent index as an ordinary error reply rather than a distinct
187187
type, and the wording has changed between versions -- older releases say ``Unknown index
188188
name``, Redis 8.6 and earlier say ``<name>: no such index``, and Redis 8.8 introduced
189-
``SEARCH_INDEX_NOT_FOUND Index not found: <name>``. There is no error code to branch on,
190-
so code that needs to distinguish "missing" from "something went wrong" has to match the
191-
message.
192-
193-
:meth:`~redisvl.index.SearchIndex.exists` already does this for you, which is the reason
194-
to prefer it over catching errors from :meth:`~redisvl.index.SearchIndex.info`: it
195-
returns ``False`` only for a recognized missing-index reply and re-raises everything
196-
else, so a permission or connection failure is never reported as an absent index.
189+
``SEARCH_INDEX_NOT_FOUND Index not found: <name>``. Matching the message couples your code
190+
to one of those wordings.
191+
192+
:meth:`~redisvl.index.SearchIndex.exists` makes the distinction without reading the
193+
message, which is the reason to prefer it over catching errors from
194+
:meth:`~redisvl.index.SearchIndex.info`. redis-py raises a plain ``ResponseError`` for an
195+
ordinary error reply, and a more specific exception for the replies that mean the check
196+
itself failed, such as ``NoPermissionError``, ``BusyLoadingError`` or ``ClusterDownError``;
197+
connection failures are not ``ResponseError`` at all. The exceptions are ``BUSY``, sent
198+
while a script or function is running, and ``ERRCLUSTER``, which Redis Search sends on a
199+
cluster whose topology is not yet initialized; redis-py leaves both as a plain
200+
``ResponseError`` with the code leading the message. A server with Redis Search not loaded
201+
at all answers with ``unknown command`` instead, which is checked for separately since
202+
that phrase isn't a leading code. ``exists()`` returns ``False`` only for a plain
203+
``ResponseError`` that is none of these, and re-raises everything else, so a permission,
204+
connection, busy-server, cluster-startup, or missing-module failure is never reported as an
205+
absent index.
197206

198207
.. code-block:: python
199208
@@ -209,10 +218,10 @@ else, so a permission or connection failure is never reported as an absent index
209218
if "no such index" in str(e): # breaks on Redis 8.8
210219
index.create()
211220
212-
When you do need the distinction elsewhere, read ``e.__cause__`` rather than the
213-
:class:`RedisSearchError` message: the wrapper interpolates the index name, so an index
214-
whose name happens to contain one of the wordings above would make an unrelated failure
215-
look like an absence.
221+
When you do need the distinction elsewhere, apply the same rule to ``e.__cause__``, the
222+
original redis-py exception: a plain ``ResponseError`` that starts with neither ``BUSY`` nor
223+
``ERRCLUSTER``, and doesn't contain ``unknown command``, means the index is absent, and
224+
anything else means the check failed.
216225

217226
Catching everything
218227
-------------------

‎docs/concepts/queries.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,15 @@ Use when neither pure keyword search nor pure semantic search gives good enough
136136
HybridQuery requires Redis >= 8.4.0 and redis-py >= 7.1.0.
137137
```
138138

139+
For explicit `vector_search_method="KNN"` or `"RANGE"`, the optional tuning
140+
parameters default to `None`. RedisVL omits these parameters, so Redis uses the
141+
index's configured values. Set `knn_ef_runtime` only for HNSW,
142+
and `range_epsilon` only for HNSW or SVS-VAMANA. FLAT supports neither option.
143+
Explicit values, including zero, are sent to Redis for validation.
144+
145+
`"RANGE"` requires `range_radius`. A radius of `0` is valid. Omitting the radius
146+
raises `ValueError`.
147+
139148
### AggregateHybridQuery
140149

141150
Similar to HybridQuery but uses Redis aggregation pipelines. Provides more control over score combination and result processing.

‎redisvl/exceptions.py‎

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
This module defines all custom exceptions used throughout the RedisVL library.
55
"""
66

7+
from redis.exceptions import ResponseError
8+
79

810
class RedisVLError(Exception):
911
"""Base exception for all RedisVL errors."""
@@ -78,35 +80,42 @@ def for_svs_vamana(cls, min_redis_version: str):
7880
return cls(message)
7981

8082

81-
# Redis Search reports an absent index as an ordinary error reply whose wording
82-
# depends on the server version, so matching the message is the only option.
83-
# Every known wording lives here rather than at each call site. See the "Telling
84-
# 'the index is missing' apart from other failures" section of docs/api/exceptions.rst.
85-
_MISSING_INDEX_ERROR_FRAGMENTS = (
86-
"unknown index name",
87-
"no such index",
88-
"search_index_not_found",
89-
"index not found",
90-
)
83+
# redis-py raises a ResponseError subclass for most error codes that mean the
84+
# check itself failed, but leaves these unmapped, so they arrive as a bare
85+
# ResponseError with the code still leading the message: BUSY while a script or
86+
# function runs, and ERRCLUSTER, which Redis Search's FT.INFO sends on a cluster
87+
# whose topology is not yet initialized.
88+
_UNMAPPED_TRANSIENT_ERROR_CODES = frozenset({"BUSY", "ERRCLUSTER"})
89+
90+
# "unknown command" means Redis Search isn't loaded at all -- there's no index
91+
# to be missing. Unlike BUSY/ERRCLUSTER this isn't a leading error code: a real
92+
# server sends it as "ERR unknown command 'FT.INFO', with args beginning with:
93+
# ...", so it's matched as a substring rather than the first token.
94+
_MODULE_NOT_LOADED_PHRASE = "unknown command"
9195

9296

9397
def _is_missing_index_error(exc: RedisSearchError) -> bool:
94-
"""Check whether a Redis Search error means the index does not exist.
98+
"""Check whether a failed ``FT.INFO`` means the index does not exist.
9599
96-
Different Redis Search versions phrase the error differently, so every
97-
known wording is matched. The check reads the underlying Redis error rather
98-
than the :class:`RedisSearchError` wrapping it, because the wrapper's
99-
message interpolates the index name and would otherwise match for an index
100-
named after one of the wordings.
100+
An absent index is a bare :class:`~redis.exceptions.ResponseError` whose
101+
wording changes between Redis versions, so the reply is classified by type
102+
and leading error code, never by the wording after the code. Error codes
103+
redis-py maps to a subclass (``NOPERM``, ``LOADING``, ``CLUSTERDOWN`` and
104+
others), connection failures, the unmapped ``BUSY`` and ``ERRCLUSTER``
105+
replies, and "unknown command" (Redis Search not loaded) all mean the
106+
check failed.
101107
102108
Args:
103109
exc: A :class:`RedisSearchError` wrapping the ``redis-py`` exception
104-
that Redis raised. Wrappers raised without a cause are matched on
105-
their own message.
110+
that Redis raised.
106111
107112
Returns:
108113
bool: True if the error indicates a missing index, False otherwise.
109114
"""
110-
cause = exc.__cause__ if exc.__cause__ is not None else exc
111-
message = str(cause).lower()
112-
return any(fragment in message for fragment in _MISSING_INDEX_ERROR_FRAGMENTS)
115+
cause = exc.__cause__
116+
if type(cause) is not ResponseError:
117+
return False
118+
message = str(cause)
119+
if _MODULE_NOT_LOADED_PHRASE in message.lower():
120+
return False
121+
return message.split(" ", 1)[0] not in _UNMAPPED_TRANSIENT_ERROR_CODES

‎redisvl/migration/wizard.py‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
)
1313
from redisvl.migration.planner import MigrationPlanner
1414
from redisvl.migration.utils import list_indexes, write_yaml
15+
from redisvl.schema.fields import CompressionType
1516
from redisvl.schema.schema import IndexSchema
1617

1718
SUPPORTED_FIELD_TYPES = ["text", "tag", "numeric", "geo"]
@@ -824,19 +825,14 @@ def _prompt_vector_attrs(self, field: Dict[str, Any]) -> Dict[str, Any]:
824825
print(
825826
" Note: LVQ/LeanVec optimizations require Intel hardware with AVX-512"
826827
)
827-
compression_input = (
828-
input("COMPRESSION [leave blank for none]: ").strip().upper()
829-
)
830-
# Map input to correct enum case (CompressionType expects exact case)
831-
compression_map = {
832-
"LVQ4": "LVQ4",
833-
"LVQ8": "LVQ8",
834-
"LVQ4X4": "LVQ4x4",
835-
"LVQ4X8": "LVQ4x8",
836-
"LEANVEC4X8": "LeanVec4x8",
837-
"LEANVEC8X8": "LeanVec8x8",
838-
}
839-
compression = compression_map.get(compression_input)
828+
compression_input = input("COMPRESSION [leave blank for none]: ").strip()
829+
compression: Optional[str] = None
830+
if compression_input:
831+
try:
832+
# CompressionType is case-insensitive; .value is the canonical form
833+
compression = CompressionType(compression_input).value
834+
except ValueError:
835+
print(f" Unknown compression '{compression_input}', ignoring.")
840836
if compression:
841837
attrs["compression"] = compression
842838

‎redisvl/query/hybrid.py‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,9 @@ def __init__(
5353
text_scorer: str = "BM25STD",
5454
yield_text_score_as: str | None = None,
5555
vector_search_method: Literal["KNN", "RANGE"] | None = None,
56-
knn_ef_runtime: int = 10,
56+
knn_ef_runtime: int | None = None,
5757
range_radius: float | None = None,
58-
range_epsilon: float = 0.01,
58+
range_epsilon: float | None = None,
5959
yield_vsim_score_as: str | None = None,
6060
filter_expression: str | FilterExpression | None = None,
6161
combination_method: Literal["RRF", "LINEAR"] | None = None,
@@ -84,10 +84,11 @@ def __init__(
8484
see https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/scoring/
8585
yield_text_score_as: The name of the field to yield the text score as.
8686
vector_search_method: The vector search method to use. Options are {KNN, RANGE}. Defaults to None.
87-
knn_ef_runtime: The exploration factor parameter for HNSW, optional if `vector_search_method` is "KNN".
88-
range_radius: The search radius to use, required if `vector_search_method` is "RANGE".
89-
range_epsilon: The epsilon value to use, optional if `vector_search_method` is "RANGE"; defines the
90-
accuracy of the search.
87+
knn_ef_runtime: The exploration factor for HNSW when `vector_search_method` is "KNN".
88+
Defaults to None, which omits EF_RUNTIME and uses the index's configured value.
89+
range_radius: The search radius, required if `vector_search_method` is "RANGE". Zero is valid.
90+
range_epsilon: The search accuracy parameter for HNSW and SVS-VAMANA when
91+
`vector_search_method` is "RANGE". Defaults to None, which omits EPSILON and uses the index's configured value.
9192
yield_vsim_score_as: The name of the field to yield the vector similarity score as.
9293
filter_expression: The filter expression to use for both the text and vector searches. Defaults to None.
9394
combination_method: The combination method to use. Options are {RRF, LINEAR}. If not specified, the server
@@ -214,10 +215,11 @@ def build_base_query(
214215
yield_text_score_as: The name of the field to yield the text score as.
215216
vector_search_method: The vector search method to use. Options are {KNN, RANGE}. Defaults to None.
216217
num_results: The number of nearest neighbors to return, required if `vector_search_method` is "KNN".
217-
knn_ef_runtime: The exploration factor parameter for HNSW, optional if `vector_search_method` is "KNN".
218-
range_radius: The search radius to use, required if `vector_search_method` is "RANGE".
219-
range_epsilon: The epsilon value to use, optional if `vector_search_method` is "RANGE"; defines the
220-
accuracy of the search.
218+
knn_ef_runtime: The exploration factor for HNSW when `vector_search_method` is "KNN".
219+
Defaults to None, which omits EF_RUNTIME and uses the index's configured value.
220+
range_radius: The search radius, required if `vector_search_method` is "RANGE". Zero is valid.
221+
range_epsilon: The search accuracy parameter for HNSW and SVS-VAMANA when
222+
`vector_search_method` is "RANGE". Defaults to None, which omits EPSILON and uses the index's configured value.
221223
yield_vsim_score_as: The name of the field to yield the vector similarity score as.
222224
filter_expression: The filter expression to use for the vector similarity search. Defaults to None.
223225
@@ -262,16 +264,16 @@ def build_base_query(
262264
)
263265

264266
vsim_search_method_params["K"] = num_results
265-
if knn_ef_runtime:
267+
if knn_ef_runtime is not None:
266268
vsim_search_method_params["EF_RUNTIME"] = knn_ef_runtime
267269

268270
elif vector_search_method == "RANGE":
269271
vsim_search_method = VectorSearchMethods.RANGE
270-
if not range_radius:
272+
if range_radius is None:
271273
raise ValueError("Must provide RADIUS if vector_search_method is RANGE")
272274

273275
vsim_search_method_params["RADIUS"] = range_radius
274-
if range_epsilon:
276+
if range_epsilon is not None:
275277
vsim_search_method_params["EPSILON"] = range_epsilon
276278

277279
elif vector_search_method is not None:

‎redisvl/redis/connection.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,7 @@ def parse_vector_attrs(attrs):
526526
# params in "flags" as key/value pairs, possibly followed by
527527
# valueless modifiers: ["algorithm", "FLAT", "dim", 4, "INDEXMISSING"]
528528
flags = attrs.get("flags") or []
529+
index_missing = "INDEXMISSING" in flags
529530
i = 0
530531
while i < len(flags):
531532
key = str(flags[i]).lower()
@@ -535,6 +536,10 @@ def parse_vector_attrs(attrs):
535536
vector_attrs.setdefault(key, flags[i + 1])
536537
i += 2
537538
else:
539+
# INDEXMISSING is a valueless modifier after the key/value pairs
540+
index_missing = "INDEXMISSING" in attrs[6:]
541+
attrs = attrs[:6] + [a for a in attrs[6:] if a != "INDEXMISSING"]
542+
538543
# Check if we have any attributes beyond the type declaration
539544
if len(attrs) <= 6:
540545
# Redis 6.2.6-v9 or similar: no vector params in FT.INFO
@@ -683,6 +688,9 @@ def parse_vector_attrs(attrs):
683688
except (ValueError, TypeError):
684689
pass
685690

691+
if index_missing:
692+
normalized["index_missing"] = True
693+
686694
# Validate that we have required dims
687695
if "dims" not in normalized:
688696
# Could not parse dims - this field is not properly supported

‎redisvl/schema/fields.py‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,15 @@ class CompressionType(str, Enum):
9696
LeanVec4x8 = "LeanVec4x8"
9797
LeanVec8x8 = "LeanVec8x8"
9898

99+
@classmethod
100+
def _missing_(cls, value):
101+
if isinstance(value, str):
102+
lowered = value.lower()
103+
for member in cls:
104+
if member.value.lower() == lowered:
105+
return member
106+
return None # falls through to the normal ValueError
107+
99108

100109
### Helper Functions ###
101110

@@ -229,8 +238,6 @@ def field_data(self) -> dict[str, Any]:
229238
}
230239
if self.initial_cap is not None: # Only include it if it's set
231240
field_data["INITIAL_CAP"] = self.initial_cap
232-
if self.index_missing: # Only include it if it's set
233-
field_data["INDEXMISSING"] = True
234241
return field_data
235242

236243

@@ -557,7 +564,13 @@ def as_redis_field(self) -> RedisField:
557564
field_data = self.attrs.field_data
558565
if self.attrs.block_size is not None:
559566
field_data["BLOCK_SIZE"] = self.attrs.block_size
560-
return RedisVectorField(name, self.attrs.algorithm, field_data, as_name=as_name)
567+
return RedisVectorField(
568+
name,
569+
self.attrs.algorithm,
570+
field_data,
571+
as_name=as_name,
572+
index_missing=self.attrs.index_missing,
573+
)
561574

562575

563576
class HNSWVectorField(BaseField):
@@ -578,7 +591,13 @@ def as_redis_field(self) -> RedisField:
578591
"EPSILON": self.attrs.epsilon,
579592
}
580593
)
581-
return RedisVectorField(name, self.attrs.algorithm, field_data, as_name=as_name)
594+
return RedisVectorField(
595+
name,
596+
self.attrs.algorithm,
597+
field_data,
598+
as_name=as_name,
599+
index_missing=self.attrs.index_missing,
600+
)
582601

583602

584603
class SVSVectorField(BaseField):
@@ -605,7 +624,13 @@ def as_redis_field(self) -> RedisField:
605624
field_data["REDUCE"] = self.attrs.reduce
606625
if self.attrs.training_threshold is not None:
607626
field_data["TRAINING_THRESHOLD"] = self.attrs.training_threshold
608-
return RedisVectorField(name, self.attrs.algorithm, field_data, as_name=as_name)
627+
return RedisVectorField(
628+
name,
629+
self.attrs.algorithm,
630+
field_data,
631+
as_name=as_name,
632+
index_missing=self.attrs.index_missing,
633+
)
609634

610635

611636
FIELD_TYPE_MAP = {

0 commit comments

Comments
 (0)