Filter stopwords in OR operands before building text query

Strip Redis default stopwords from each OR operand, matching the
existing multi-word FULLTEXT path behavior.  If an operand becomes
empty after filtering (all tokens are stopwords), fall back to the
original words so the query is not silently truncated.  A UserWarning
is emitted listing the removed stopwords.

Author: nkanu17

sql_redis/query_builder.py

@@ -187,16 +187,37 @@ def build_text_condition(
             # or "OR tablet") so that the empty-operand check below catches
             # these malformed inputs instead of silently dropping "OR".
             or_parts: list[str] = []
+            all_removed: list[str] = []
             for part in re.split(r"(?:^|\s+)OR(?:\s+|$)", value):
                 words = part.strip().split()
                 if not words:
                     raise ValueError(
                         "Empty operand in OR expression — each side of OR "
                         "must contain at least one search term."
                     )
-                if len(words) > 1:
+
+                # Filter stopwords from this operand (same logic as
+                # the multi-word FULLTEXT branch).
+                removed = [w for w in words if w.lower() in REDIS_DEFAULT_STOPWORDS]
+                filtered = [
+                    w for w in words if w.lower() not in REDIS_DEFAULT_STOPWORDS
+                ]
+                if removed:
+                    all_removed.extend(removed)
+                # Use filtered list if any non-stopword tokens remain;
+                # otherwise fall back to original words so we don't
+                # silently produce an empty operand.
+                effective = filtered if filtered else words
+
+                if not effective:
+                    raise ValueError(
+                        "Empty operand in OR expression — each side of OR "
+                        "must contain at least one search term."
+                    )
+
+                if len(effective) > 1:
                     escaped_tokens = []
-                    for w in words:
+                    for w in effective:
                         if w.startswith("~"):
                             escaped_tokens.append(
                                 "~" + self._escape_fulltext_term(w[1:])
@@ -205,11 +226,21 @@ def build_text_condition(
                             escaped_tokens.append(self._escape_fulltext_term(w))
                     or_parts.append(f"({' '.join(escaped_tokens)})")
                 else:
-                    token = words[0]
+                    token = effective[0]
                     if token.startswith("~"):
                         or_parts.append("~" + self._escape_fulltext_term(token[1:]))
                     else:
                         or_parts.append(self._escape_fulltext_term(token))
+
+            if all_removed:
+                warnings.warn(
+                    f"Stopwords {all_removed} were removed from OR "
+                    f"expression '{value}'. By default, Redis does not "
+                    "index stopwords. To include stopwords in your "
+                    "index, create it with STOPWORDS 0.",
+                    UserWarning,
+                    stacklevel=2,
+                )
             search_value = f"({'|'.join(or_parts)})"
         elif " " in value:
             # FULLTEXT with multi-word: tokenized search with stopword filtering.

tests/test_query_builder.py

@@ -697,6 +697,36 @@ def test_or_only_raises(self):
         with pytest.raises(ValueError, match="Empty operand"):
             builder.build_text_condition("title", "FULLTEXT", "OR")
 
+    def test_or_operand_stopword_filtered(self):
+        """Stopwords inside OR operands are stripped with a warning."""
+        builder = QueryBuilder()
+        with pytest.warns(UserWarning, match="Stopwords.*removed from OR"):
+            result = builder.build_text_condition("title", "FULLTEXT", "laptop OR the")
+        # "the" is a stopword — after filtering only "laptop" remains on
+        # the right side, but since the right operand was *only* a stopword
+        # and falls back to original words, we keep it.
+        # Actually "the" is the only word so filtered=[] → fallback to ["the"].
+        # Let's just verify the left side is clean.
+        assert "laptop" in result
+
+    def test_or_multi_word_operand_stopword_filtered(self):
+        """Stopwords in multi-word OR operands are stripped."""
+        builder = QueryBuilder()
+        with pytest.warns(UserWarning, match="Stopwords.*removed from OR"):
+            result = builder.build_text_condition(
+                "title", "FULLTEXT", "gaming laptop OR the tablet"
+            )
+        # "the" stripped from second operand → "tablet"
+        assert result == "@title:((gaming laptop)|tablet)"
+
+    def test_or_all_stopwords_operand_warns(self):
+        """OR operand that is entirely stopwords falls back but warns."""
+        builder = QueryBuilder()
+        with pytest.warns(UserWarning, match="Stopwords.*removed from OR"):
+            result = builder.build_text_condition("title", "FULLTEXT", "laptop OR the")
+        # "the" is sole token and a stopword → filtered=[] → fallback to ["the"]
+        assert result == "@title:(laptop|the)"
+
     def test_escape_asterisk_in_fulltext(self):
         """Literal * in FULLTEXT is escaped to prevent wildcard."""
         builder = QueryBuilder()