fix: WITHSCORES+RETURN0 parsing, OR operand escaping, slop validation

- Fix stride mismatch in executor when WITHSCORES + RETURN 0 (NOCONTENT)
  produces [count, id, score, ...] without field arrays
- Add _ScoreParseMixin with _has_return_0() helper for both sync/async executors
- Escape individual OR operands in fulltext() to prevent accidental
  negation (anti-virus) and field injection (@field)
- Validate slop >= 0 in parser, raise ValueError for negative values
- Add tests for all three fixes

Author: nkanu17

sql_redis/executor.py

@@ -103,7 +103,20 @@ class QueryResult:
     count: int
 
 
-class Executor:
+class _ScoreParseMixin:
+    """Shared helper for detecting RETURN 0 (NOCONTENT) in translated args."""
+
+    @staticmethod
+    def _has_return_0(args: list[str]) -> bool:
+        """Return True when the args contain 'RETURN 0' (no document fields)."""
+        try:
+            idx = args.index("RETURN")
+            return args[idx + 1] == "0"
+        except (ValueError, IndexError):
+            return False
+
+
+class Executor(_ScoreParseMixin):
     """Executes SQL queries against Redis."""
 
     def __init__(self, client: redis.Redis, schema_registry: SchemaRegistry) -> None:
@@ -169,8 +182,19 @@ def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
             # Check if WITHSCORES was requested — changes response format
             with_scores = "WITHSCORES" in translated.args
             score_alias = translated.score_alias
-
-            if with_scores:
+            # RETURN 0 suppresses document fields (like NOCONTENT);
+            # with WITHSCORES the reply is [count, id, score, id, score, ...]
+            no_content = self._has_return_0(translated.args)
+
+            if with_scores and no_content:
+                # WITHSCORES + RETURN 0: [count, id1, score1, id2, score2, ...]
+                # Stride of 2: key, score (no field array)
+                for i in range(1, len(raw_result) - 1, 2):
+                    score = raw_result[i + 1]
+                    alias = score_alias or "__score"
+                    row = {alias: score}
+                    rows.append(row)
+            elif with_scores:
                 # WITHSCORES format: [count, key1, score1, [fields1], key2, score2, [fields2], ...]
                 # Stride of 3: key, score, field_list
                 for i in range(1, len(raw_result) - 2, 3):
@@ -198,7 +222,7 @@ def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
         return QueryResult(rows=rows, count=count)
 
 
-class AsyncExecutor:
+class AsyncExecutor(_ScoreParseMixin):
     """Async version of Executor for use with redis.asyncio clients."""
 
     def __init__(
@@ -271,8 +295,16 @@ async def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
         if translated.command == "FT.SEARCH":
             with_scores = "WITHSCORES" in translated.args
             score_alias = translated.score_alias
+            no_content = self._has_return_0(translated.args)
 
-            if with_scores:
+            if with_scores and no_content:
+                # WITHSCORES + RETURN 0: [count, id1, score1, id2, score2, ...]
+                for i in range(1, len(raw_result) - 1, 2):
+                    score = raw_result[i + 1]
+                    alias = score_alias or "__score"
+                    row = {alias: score}
+                    rows.append(row)
+            elif with_scores:
                 # WITHSCORES format: [count, key1, score1, [fields1], ...]
                 for i in range(1, len(raw_result) - 2, 3):
                     score = raw_result[i + 1]

sql_redis/parser.py

@@ -975,12 +975,16 @@ def _add_function_condition(
             field_name = args[0].name if isinstance(args[0], exp.Column) else None
             value = self._extract_literal_value(args[1])
 
-            # Optional 3rd arg: slop (int)
+            # Optional 3rd arg: slop (non-negative int)
             slop = None
             if len(args) >= 3:
                 slop_val = self._extract_literal_value(args[2])
                 if slop_val is not None:
                     slop = int(slop_val)
+                    if slop < 0:
+                        raise ValueError(
+                            f"FULLTEXT slop argument must be a non-negative integer (got {slop})"
+                        )
 
             # Optional 4th arg: inorder (boolean-like: 1/0 or true/false)
             inorder = False

sql_redis/query_builder.py

@@ -173,8 +173,10 @@ def build_text_condition(
             terms = " ".join(filtered_words) if filtered_words else value
             search_value = f"({terms})"
         elif " OR " in value:
-            # OR union within text field: split on ' OR ' and join with |
-            or_terms = [t.strip() for t in value.split(" OR ")]
+            # OR union within text field: split on ' OR ', escape each term, join with |
+            or_terms = [
+                self._escape_fulltext_term(t.strip()) for t in value.split(" OR ")
+            ]
             search_value = f"({'|'.join(or_terms)})"
         else:
             # Single-word FULLTEXT — escape to prevent accidental operator injection

tests/test_query_builder.py

@@ -567,3 +567,18 @@ def test_multi_field_non_exact_escapes(self):
             ["title", "description"], "FULLTEXT", "hello|world"
         )
         assert result == "(@title|description:hello\\|world)"
+
+    def test_or_terms_escape_special_chars(self):
+        """OR operands are escaped before joining with |."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition(
+            "title", "FULLTEXT", "laptop OR anti-virus"
+        )
+        # '-' is a RediSearch operator and should be escaped in OR terms
+        assert result == "@title:(laptop|anti\\-virus)"
+
+    def test_or_terms_escape_at_sign(self):
+        """OR operands escape @ to prevent field injection."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("title", "FULLTEXT", "hello OR @world")
+        assert result == "@title:(hello|\\@world)"

tests/test_sql_parser.py

@@ -855,3 +855,13 @@ def test_exists_in_where_raises_error(self):
         parser = SQLParser()
         with pytest.raises(ValueError, match="exists.*aggregate"):
             parser.parse("SELECT * FROM idx WHERE exists(email)")
+
+
+class TestSQLParserFulltextValidation:
+    """Tests for fulltext() argument validation."""
+
+    def test_fulltext_negative_slop_raises(self):
+        """Negative slop in fulltext() raises ValueError."""
+        parser = SQLParser()
+        with pytest.raises(ValueError, match="non-negative integer"):
+            parser.parse("SELECT * FROM idx WHERE fulltext(title, 'hello world', -1)")